my-free-code安全指南:本地代理鉴权、loopback-only与API密钥保护最佳实践
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。三条铁律:
- 不要把真实密钥写进代码或提交到仓库。项目的 .gitignore 已将
.env列入忽略清单,只需cp .env.example .env后填入真实密钥即可; - 只填你在用的供应商,不用的
*_API_KEY留空即可,减少暴露面; - 密钥隔离:上游凭证只存在于本地环境配置中,网关转发请求时只会把凭证附加给对应的目标供应商,绝不会把 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 等客户端通过它路由到任意供应商。