my-free-code安全指南:本地代理鉴权、loopback-only与API密钥保护最佳实践

原创2026-11-14 18:22:411,938 阅读

my-free-code安全指南:本地代理鉴权、loopback-only与API密钥保护最佳实践

my-free-code 是一个面向 Claude Code 等编程智能体的开源多供应商 AI 网关(AI gateway),负责模型路由、流式响应、工具调用、推理透传与故障回退。正因为它站在客户端与各家上游 API 之间,手里握着你的 API 密钥,安全配置必须做好。本指南给出 5 个即学即用的安全实践,帮你把本地代理的风险降到最低。

1️⃣ 为什么本地 AI 网关是安全敏感点?

my-free-code 作为本地代理(local proxy),默认监听 http://127.0.0.1:8082,所有经过它的请求都带着你配置的上游凭证。如果配置不当,可能出现两类风险:

  • 端口暴露:网关被局域网或公网访问,他人免费消耗你的 token 配额;
  • 密钥泄漏:.env 文件或配置文件被提交到仓库,API 密钥随代码泄露。

好消息是,my-free-code 在设计上就内置了多层防护,你只需按下面的步骤配置即可。

2️⃣ 保持 loopback-only:只监听 127.0.0.1

最快配置方法:确认环境变量中 HOST 保持默认值 127.0.0.1,不要把网关绑定到 0.0.0.0 或内网网卡地址。

HOST=127.0.0.1
PORT=8082

这些默认值定义在 my_free_code/config.py。

更妙的是,管理接口还有一层"loopback-only"校验。在 my_free_code/api/routes.py 中,loopback_only 会检查请求的 Host 头,只有来自 127.0.0.1、::1、localhost 的请求才能打开 /admin 页面,否则直接返回 403 admin is local-only。即使你误把端口映射出去,Admin 控制台也不会对非本机来源开放。

3️⃣ 设置强代理鉴权令牌 PROXY_AUTH_TOKEN

网关的所有数据接口(/v1/messages、/v1/models、/api/admin/* 等)都要求请求头携带 Bearer 令牌。核心逻辑在 my_free_code/api/routes.py:

def require_auth(authorization: str | None):
    if not settings.auth_token:
        return
    expected = "Bearer " + settings.auth_token
    if not authorization or not secrets.compare_digest(authorization, expected):
        raise HTTPException(status_code=401, detail="invalid proxy authorization")

两个值得注意的细节:

  • 使用 secrets.compare_digest 做恒定时间比较,防止时序攻击(timing attack)逐字节猜解令牌;
  • 令牌来自 PROXY_AUTH_TOKEN 环境变量,默认值是弱口令 local——正式使用前一定要改成随机强口令。

推荐生成方式:

python -c "import secrets; print(secrets.token_urlsafe(32))"

然后把结果写入 .env:

PROXY_AUTH_TOKEN=在这里粘贴一长串随机值

对应的鉴权测试用例见 tests/test_auth.py,你可以用 pytest -q 验证未带令牌的请求会被正确拦截。

4️⃣ 用 .env 保管上游 API 密钥,并绝不提交

my-free-code 需要调用各家上游(OpenRouter、DeepSeek、Groq 等),这些密钥统一放在 .env 文件中,模板见 .env.example。三条铁律:

  1. 不要把真实密钥写进代码或提交到仓库。项目的 .gitignore 已将 .env 列入忽略清单,只需 cp .env.example .env 后填入真实密钥即可;
  2. 只填你在用的供应商,不用的 *_API_KEY 留空即可,减少暴露面;
  3. 密钥隔离:上游凭证只存在于本地环境配置中,网关转发请求时只会把凭证附加给对应的目标供应商,绝不会把 A 家的 key 发给 B 家(见 my_free_code/providers/adapters.py 中按供应商附加 Authorization 头的实现)。

本地模型(Ollama、LM Studio、llama.cpp)则直接走本机地址,如:

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1

5️⃣ 让 CLI 启动器自动注入令牌,避免手动暴露

很多用户在多个客户端之间手动复制令牌,反而容易把令牌留在 shell 历史里。my-free-code 的启动器会自动把 PROXY_AUTH_TOKEN 注入客户端的环境变量中:

python -m my_free_code.cli.mfc claude

在 my_free_code/cli/launchers.py 中可以看到,启动器会设置 ANTHROPIC_AUTH_TOKEN / OPENAI_API_KEY 为本地令牌、把 Base URL 指向 http://127.0.0.1:8082,并自动追加 NO_PROXY,保证流量不出本机。也就是说:客户端只需要认识本地网关这一个弱令牌,真正的上游密钥始终留在服务端环境里,客户端永远看不到。

6️⃣ 管理端点边界:/admin 与 /api/admin/*

端点 访问限制
/admin(管理页面) 仅本机(loopback-only 校验)
/api/admin/status、/api/admin/models、/api/admin/providers Bearer 鉴权
/v1/models、/v1/messages 等 Bearer 鉴权
/health 公开(不含敏感信息)

Admin 路由的鉴权实现见 my_free_code/api/admin_routes.py。只要坚持第 2、3 步的配置,管理接口就是双重受保护的。

7️⃣ 安全清单:上线前逐项核对

  • [ ] HOST=127.0.0.1,未绑定公网/内网地址
  • [ ] PROXY_AUTH_TOKEN 已替换为 32 位以上随机强口令
  • [ ] 真实密钥只写在本地 .env,且该文件已被 .gitignore 排除
  • [ ] 未使用的 *_API_KEY 保持留空
  • [ ] 用 python -m my_free_code.cli.mfc claude 等启动器代替手动配置环境变量
  • [ ] 不打算对外提供服务时,不转发 8082 端口

my-free-code 官方文档中的安全要点同样值得回顾:保持 loopback 监听、设置非弱令牌、绝不提交 .env、不将 Admin 端点暴露到互联网(见 README.md 的 Security 章节)。架构边界与请求生命周期详见 ARCHITECTURE.md。

按这套流程配置后,你的本地 AI 网关就具备了"只对本机开放 + 令牌鉴权 + 密钥隔离"的三重防护,可以放心地让 Claude Code、Codex、Cline 等客户端通过它路由到任意供应商。

登录后查看全文
my-free-code