安全

这页总结保护 API Key 和接入安全的最关键规则。每一条都来自实际事故中常见的泄露方式，建议在生产环境接入前逐条确认。

不要把 API Key 放进前端代码

浏览器前端会把代码发给用户，API Key 会泄露。

正确做法：

• 前端只发起你自己的后端请求。
• 后端再带着 API Key 调 Arqel。

不要把完整 API Key 提交到 Git

提交前检查：

• .env
• 配置文件
• 终端历史
• 截图

如果已经提交过，尽快删除、重置或停用该 Key。

不要把完整 API Key 发给别人

排查问题时可以提供：

• Key 名称。
• Key 前后几位。
• 请求时间。
• 模型名。
• 状态码和错误信息。

不要提供：

• 完整 Key。
• 私有提示词。
• 客户数据。

Agent 不要随便碰 secrets 文件

不要让 Agent 在没有明确授权时编辑这些文件：

• .env
• 密钥配置文件
• 生产环境 secret 配置

日志要脱敏

如果你的服务会记录请求日志，务必隐藏：

• API Key。
• Access token。
• Cookie。
• 用户隐私内容。
• 私有提示词和系统提示词。
• 模型完整响应。
• 工具调用参数。
• 客户文件路径、文件名和片段内容。

排查问题时，优先记录请求时间、状态码、模型名、Key 名称、请求 ID / trace ID 和脱敏后的错误信息。不要为了方便排查就把完整请求体和响应体长期写进日志。

生产环境用 Secret Manager

生产环境建议把 Key 放到 Secret Manager、云平台 Secrets 或服务器安全环境变量里，不要硬编码。

分开本地、测试和生产 Key

建议至少分三类：

• 本地开发。
• 测试环境。
• 生产环境。

这样更容易管理权限和追踪问题。

定期轮换 Key

如果 Key 长期不变，风险会积累。建议定期检查并轮换不再使用的 Key。

Key 命名和生命周期

建议给 Key 起能看懂来源的名字：

用途	示例名称
本地 API 测试	local-api-test
Cursor	cursor-personal
Claude Code	claude-code-dev
Codex	codex-local
生产后端	server-production

不用的 Key 应及时停用或删除。临时测试 Key 用完后不要长期保留。

如果怀疑 Key 泄露

1. 立即停用或删除该 Key。
2. 创建新 Key。
3. 更新所有使用旧 Key 的配置。
4. 检查日志、仓库和截图是否也泄露过。
5. 如有必要，通知相关团队。

如果你写后端代理

前端不应该直接调用 Arqel 并暴露 API Key。更安全的做法是：浏览器请求你自己的后端，后端再调用 Arqel。

这个后端代理至少要做到：

• 校验你自己的用户身份，不要做成公开转发器。
• 只允许可信前端来源访问，配置清晰的 CORS / Origin 策略。
• 按用户、IP 或项目做限流。
• 限制请求体大小和最大输出长度。
• 设置上游请求超时、客户端断开处理和自动重试上限。
• 401 / 403 这类鉴权错误不要自动重试。
• 不要把 Arqel API Key 返回给浏览器。
• 日志里脱敏 Authorization、Cookie、access token、API Key、提示词、响应内容、工具参数、客户文件路径和用户隐私内容。
• 不允许普通用户传入任意 Base URL，避免把你的服务变成开放代理。
• 生产环境使用 Secret Manager、云平台 Secrets 或服务器环境变量保存 Key。
• 准备暂停开关，必要时能快速停用某个 Key、用户、项目或代理入口。
• 设置预算、额度或用量提醒，便于发现异常消耗。

如果代理出现异常高频请求，先停用对应 Key 或暂停代理，再排查日志。

联系支持时提供什么

可以提供：

• 请求时间和时区。
• Key 名称或前后几位，不要提供完整 Key。
• Base URL。
• 模型名。
• HTTP 状态码。
• 错误信息。
• 使用的工具或 SDK 版本。
• 请求 ID / trace ID（如果响应或控制台提供）。

不要提供完整 API Key、客户数据、私有提示词、未打码截图或生产 secret。

如果需要提供复现材料，请先最小化请求内容。只保留能够复现问题的字段，删除客户数据、内部文件路径、工具调用参数和无关上下文。