密钥与权限

密钥生命周期

1. 创建：按环境、业务线或应用创建独立密钥，并填写清晰备注。
2. 分发：只分发给服务端运行环境或密钥管理系统。
3. 使用：通过环境变量、密钥管理服务或 CI/CD Secret 注入。
4. 追踪：按 API Key 维度查看用量、业务归属和异常调用。
5. 轮换：定期生成新密钥、灰度切换、确认无异常后禁用旧密钥。
6. 删除：下线应用或人员离岗后及时删除无用密钥。

创建密钥时建议在备注中写清用途、业务场景、环境、负责人或内部系统标识，便于后续审计、用量归因和泄露处置。

密钥管理要求

• 不要将 API Key 提交到代码仓库。
• 不要在客户端、日志、报错信息、截图或文档中暴露完整密钥。
• 为开发、测试、预发、生产使用不同密钥。
• 为不同租户、团队或业务线划分密钥，便于追踪用量。
• 对生产密钥配置访问控制和审批流程。

本地环境示例

本地开发可以使用环境变量或 .env.local 保存密钥，但必须确保文件不会提交到仓库。中国大陆业务可用 https://api.qnaigc.com/v1，海外部署或跨境访问可用 https://api.modelink.ai/v1。

export MODELINK_API_KEY="替换为你的 Modelink API Key"
export MODELINK_BASE_URL="https://api.qnaigc.com/v1"

.gitignore 中建议包含：

.env
.env.*
!.env.example

可以保留一个不含真实密钥的 .env.example，用于说明项目需要哪些变量：

MODELINK_API_KEY=
MODELINK_BASE_URL=https://api.qnaigc.com/v1
MODELINK_MODEL=

权限隔离

建议按照环境、项目、团队、业务线或租户划分权限。生产环境密钥不应复用于测试环境，具备写入、外发、生产操作能力的工具必须额外限制。

对编程工具、Agent 和 MCP 场景，建议默认采用最小权限策略：

• 默认拒绝读取 .env、密钥文件、生产配置和客户数据目录。
• 将文件读取、命令执行、网络访问和生产变更拆分授权。
• 对工具调用记录请求 ID、调用方、参数摘要、执行结果和错误信息。
• 高风险动作使用人工确认、沙箱环境或只读模式。

轮换流程

推荐采用“双密钥灰度”方式轮换：

1. 在控制台创建新密钥，并标注用途和负责人。
2. 将新密钥写入密钥管理系统或 CI/CD Secret。
3. 灰度发布应用，确认新密钥请求成功率、耗时和用量正常。
4. 全量切换到新密钥。
5. 观察一段时间后禁用旧密钥。
6. 检查是否还有旧密钥调用，确认无异常后删除旧密钥。

泄露处置

如果怀疑密钥泄露，应立即：

1. 在控制台禁用或删除泄露密钥。
2. 创建新密钥并更新应用配置。
3. 检查请求日志和用量记录，排查异常调用。
4. 评估是否存在数据、费用或业务风险。
5. 必要时联系支持团队协助追踪和处置。