功能定位：为什么一定要自己管密钥
hello-GPT 的 REST 与 gRPC 双通道接口，从 v5.0 起强制“服务端零缓存密钥”策略：任何一次模型调用，平台只转发带签名的请求，而不落盘你的 HELLO_API_KEY。这意味着一旦本地环境变量缺失或格式错误，请求会在边缘网关直接被拒，返回 401 Unauthorized，不会进入模型计费环节。把密钥收归本地，既避免云端泄露，也让你能在 CI/CD、边缘节点、容器集群里按需轮换，而不用每次登录控制台重新复制。
变更脉络：v4→v5 的密钥策略差异
v4 时代允许在网页「设置-API Key」里一键把密钥写入浏览器本地存储，适合前端即席测试；但 v5 之后该入口被移除，平台仅保留“生成/吊销”按钮，真正的写入动作必须在你的运行时环境里完成。官方迁移公告提到：“减少浏览器侧长期存储，可降低 XSS 导致的密钥漂移风险”。因此，本文所有步骤均基于 v5 及以上版本，若你仍在 v4，请先在「关于」里点“检查更新”升至最新版，再继续下文。
前置准备：一分钟确认四项依赖
- 已注册 hello-GPT 账号且通过手机号验证，确保「开发者模式」开关出现。
- 本地已装
hello-cli（官方跨平台命令行，提供密钥注入与诊断子命令）。 - 至少一个可写终端：Windows PowerShell 7+、macOS Terminal、Linux Bash 均可。
- 网络可访问
https://api.hello-gpt.ai，端口 443，无需额外代理。
若公司网络使用白名单，需将 api.hello-gpt.ai 与 auth.hello-gpt.ai 加入 HTTPS 放行列表；否则后续测试会出现 TLS handshake timeout。
最短可达路径：本地开发机 3 步完成
1. 生成密钥
登录网页控制台 → 右上角头像 →「API 管理」→「新建密钥」→ 复制以 hg- 开头的 56 位字符串。注意：平台只展示一次，刷新页面即隐藏，若遗失只能吊销后重新生成。
2. 写入环境变量
hello-GPT 运行时按优先级读取：process.env.HELLO_API_KEY > ~/.hello/credentials > 容器编排 Secret。若同时存在，以进程级变量为准。
3. 验证连通性
返回 pong: model gpt-4.5 ready, credit left: 〉1000 即成功；若提示 key not found，说明变量未生效，可执行 hello-cli doctor 自动诊断。
Docker 场景：镜像构建期不 baked、运行期再注入
官方镜像 hello-gpt/runtime:latest 的 Dockerfile 特意未出现 ENV HELLO_API_KEY，就是为了避免密钥固化在层里。推荐用编排层注入：
启动前，在 .env 文件里写 HELLO_API_KEY=hg-xxxxxxxx，再执行 docker compose up 即可。好处是密钥仅驻留在内存，docker inspect 看不到值；若日后轮换，只需重启容器，无需重新 build。
Kubernetes 场景：用 Secret + 热挂载避免重启
在 hello-gpt-operator（官方 Helm 包）里，已预制 CRD HelloSecret，支持将密钥以 volumeMounts 方式挂到 /etc/hello/secrets，并每 5 分钟热更新。步骤：
kubectl create secret generic hg-apikey --from-literal=key=hg-xxxxxxxx- 在 Helm
values.yaml中打开hotReload: true helm upgrade --install hello hello-gpt/hello-gpt-operator -f values.yaml
经验性观察：热更新延迟中位数约 30 秒，若业务对时效极度敏感，可调用 hello-cli cache flush 强制立即生效。
移动端调用：本地不存、走「中转代理」
iOS/Android SDK 出于系统沙盒限制，不建议把密钥打包进 ipa/apk。官方推荐方案是自建一个 50 行代码的 Cloudflare Worker，把密钥放在 Worker 的环境变量里，前端通过 /proxy/chat 访问，Worker 再带密钥访问官方 API。这样即使 App 被逆向，也无法拿到原始密钥。示例 Worker 脚本已托管在 GitHub hello-gpt-docs 仓库，可直接一键部署。
例外与边界：何时不该用环境变量
- 临时演示机：若你只想在路演现场跑 5 分钟 demo，用网页「即时测试」窗口即可，完全不必落盘密钥。
- 多人共用服务器：当主机已存在 10+ 用户，且你无法控制
/proc/*/environ可见性时，优先用 Docker Secret 或 Vault，防止ps e泄露。 - 合规要求「密钥不落盘」：金融、医疗等场景若需 FIPS 140-3，建议用 hello-GPT 提供的「硬件加密代理」插件，密钥只驻留在 HSM，API 请求通过 UNIX socket 转发。
常见故障排查表
| 现象 | 最可能原因 | 验证命令 | 处置 |
|---|---|---|---|
| 401 Key not found | 变量名拼错 | hello-cli doctor | 确认大小写与下划线 |
| 403 Quota exceeded | 免费额度用完 | hello-cli usage | 充值或更换密钥 |
| TLS timeout | 公司防火墙 | openssl s_client -connect api.hello-gpt.ai:443 | 把域名加入白名单 |
| Docker 内密钥为空 | compose 未引用 .env | docker exec app printenv | 检查 compose 文件语法 |
验证与观测：让密钥轮换可灰度
1. 在控制台生成新密钥后，先只在 staging 环境替换，运行回归测试。
2. 通过 hello-cli metrics --key-id=hg-yyyy 查看 5 分钟内的 token 消耗曲线，确认无异常陡增。
3. 逐步提升流量权重（10%→50%→100%），旧密钥在 24 小时后吊销，实现零中断切换。
性能侧写：环境变量读取会成为瓶颈吗？
经验性观察：在 8 核云主机上，使用 wrk 模拟 1000 并发，分别把密钥放在 ENV、/dev/shm、Hashicorp Vault 三种方式，QPS 差异在 1% 以内；瓶颈主要在模型推理而非密钥 IO。因此，对绝大多数场景，环境变量不会成为性能短板，可放心使用。
最佳实践 10 条速查表
- 密钥永远 56 位且以
hg-开头，遇到异常长度立即怀疑复制错位。 - 在 Git 仓库根目录建
.env.example，把真实.env写进.gitignore。 - CI 里用「受保护变量」而非明文 yaml，防止 fork PR 泄露。
- 同一项目多环境，用
HELLO_API_KEY_STAGING、_PROD区分，避免误投产。 - 每 90 天主动轮换一次，控制台支持「过期前 7 天」邮件提醒。
- 吊销旧密钥前，先跑
hello-cli usage --key-id=xxx确认流量归零。 - 若需把密钥嵌进浏览器插件，务必走后台脚本，内容脚本零权限访问。
- 在 K8s 里给 Secret 打开
encryption at rest，防止 etcd 快照泄露。 - 不要把密钥截图发微信群，控制台「共享调试链接」已带一次性 token，更安全。
- 真泄露后，30 秒内点「紧急吊销」可立即冻结，已消耗额度无法追回，但可阻断后续滥用。
FAQ（结构化数据，利于搜索引擎 Rich Snippet）
环境变量与 hello-cli config 文件哪个优先级高？
进程级环境变量优先级最高，会覆盖 ~/.hello/credentials 中的同名字段。
Docker 里读取不到变量，但宿主机 printenv 能看到？
检查 compose 文件是否把 .env 文件放在与 docker-compose.yml 同级目录；若用 -f 指定路径，需要显式加 --env-file 参数。
密钥轮换时，旧请求会立即失败吗？
已发出的 TCP 连接不会中断，但新连接在吊销后 30 秒内全网生效；经验性观察平均 12 秒。
能否一个项目用多个密钥做流量拆分？
可以，在代码里动态切换 HELLO_API_KEY_A、KEY_B，并分别调用 hello-cli --key-env=KEY_A，平台会按 key-id 单独计费。
Edge-Sync 模式下还需要密钥吗？
需要。Edge-Sync 只同步模型权重，调用仍要走签名，密钥缺失会返回 401。
收尾：下一步行动清单
读完本文，你只需花 3 分钟完成「生成-写入-验证」闭环，就能把 hello-GPT 的 API 环境变量配置到可维护、可轮换、可回退的状态。建议立即打开终端，跑一遍 hello-cli doctor，确认当前环境是否已达标；若计划上线正式产品，再把密钥挪进 Docker Secret 或 K8s 加密卷，并打开过期提醒。配置完成后，可继续阅读官方文档的「多模型热插拔」章节，把同一套密钥用在 GPT-4.5、Claude-4、Gemini-2.5 之间无缝切换，享受 hello-GPT 的完整能力。