把 AI 接进项目后，API Key、日志和权限怎么管

把 AI 接进项目后，API Key、日志和权限怎么管

把大模型接入项目，最先遇到的通常不是模型调用，而是三个工程问题：

1. API Key 放在哪里，怎样轮换？
2. 请求和响应能不能写入日志，哪些字段必须脱敏？
3. 不同用户、服务和环境，分别拥有哪些权限？

这三个问题彼此关联。密钥泄露可能导致未授权调用；日志泄露可能暴露用户数据和业务提示词；权限过宽则会放大任何一个组件被攻破后的影响。

本文给出一套与具体模型厂商无关的管理方法，适用于后端服务、脚本、数据处理任务和内部工具。

先确定威胁边界

在设计之前，先列出需要保护的对象：

• API Key、短期令牌和云平台服务账号凭据。
• 用户输入、模型输出、上传文件和系统提示词。
• 账单信息、调用量、组织结构和内部项目名称。
• 具备写数据库、发邮件、执行命令等能力的工具接口。

常见攻击路径包括：

• 密钥被提交到 Git 仓库、构建日志或聊天记录。
• 错误堆栈包含完整请求体，并被发送到集中式日志平台。
• 前端直接持有高权限 Key，用户可以在浏览器中读取或复用。
• 测试环境和生产环境共用同一凭据，导致排查和撤销困难。
• Agent 工具没有做参数校验，模型可以间接访问超出业务范围的数据。

安全目标不是“绝对不出错”，而是把泄露范围、持续时间和恢复成本控制在可接受范围内。

API Key 的生命周期

1. 创建时分环境、分服务

至少区分：

• 本地开发：个人凭据或本地代理，禁止提交到仓库。
• 测试环境：只访问测试数据和测试模型资源。
• 生产环境：由部署平台注入，应用代码不直接读取配置文件。

不同服务也应使用不同凭据，例如 chat-service、embedding-worker、batch-job 分开管理。这样某个服务需要撤销时，不会影响全部系统。

2. 通过环境变量或密钥管理器注入

本地开发可以使用未纳入版本控制的 .env 文件：

# .env.local
AI_API_KEY=replace-with-a-real-key
AI_BASE_URL=https://api.example.com

应用启动时读取环境变量，而不是把密钥写进源码：

import os
import sys

api_key = os.getenv("AI_API_KEY")
if not api_key:
    print("AI_API_KEY is missing", file=sys.stderr)
    raise SystemExit(1)

print("AI credential is configured")

生产环境应优先使用云厂商密钥管理服务、Kubernetes Secret 或 CI/CD 的受保护变量。密钥管理器需要配置访问审计、版本控制和最小读取权限。

3. 轮换和撤销

建议建立固定流程：

1. 创建新 Key，并写入密钥管理器的新版本。
2. 发布支持双 Key 的应用版本，短时间内同时接受旧、新凭据。
3. 切换流量并观察错误率、调用量和账单变化。
4. 撤销旧 Key。
5. 检查仓库、构建产物和日志系统中是否仍存在旧值。

如果怀疑泄露，不要等待确认结果。先撤销或冻结凭据，再调查来源。轮换周期应结合权限范围、暴露面和组织要求制定，不能只依赖“长期不变的主 Key”。

4. 在 CI 中阻止误提交

可以使用 secret scanning 工具检查提交、合并请求和制品。即使扫描没有发现问题，也不要把扫描结果当作凭据安全的证明；历史提交、构建缓存和第三方日志仍需单独检查。

日志：记录事实，不记录秘密

日志的价值在于回答“谁在什么时候调用了什么功能、结果如何”。它不等于保存完整对话。

推荐记录这些字段：

• request_id：请求追踪 ID。
• service、environment、model：服务和运行环境。
• actor_id_hash：经过不可逆处理的用户标识。
• input_chars、output_chars、duration_ms：规模和耗时。
• status、error_type、retry_count：结果和重试信息。
• 供应商返回的用量字段（如果接口提供）。

默认不记录：

• API Key、Authorization Header、Cookie。
• 完整用户输入、完整模型输出。
• 身份证号、邮箱、手机号、访问令牌和业务机密。
• 含有文件内容的调试对象。

脱敏要在日志入口完成

不要依赖开发人员“记得删字段”。可以在统一日志函数中做递归脱敏：

import re
from typing import Any

SECRET_KEYS = {
    "api_key", "authorization", "token", "password",
    "access_token", "refresh_token"
}

BEARER_RE = re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+")

def redact(value: Any, key: str = "") -> Any:
    normalized = key.lower()
    if normalized in SECRET_KEYS:
        return "[REDACTED]"

    if isinstance(value, dict):
        return {k: redact(v, k) for k, v in value.items()}

    if isinstance(value, list):
        return [redact(item, key) for item in value]

    if isinstance(value, str):
        return BEARER_RE.sub("Bearer [REDACTED]", value)

    return value

生产环境还应考虑：

• 日志传输加密和访问控制。
• 按数据类型设置保留期限。
• 对敏感字段使用哈希或分桶统计。
• 将调试日志与审计日志分离。
• 定期抽样检索，验证脱敏规则没有失效。

为了排查模型质量问题，可以保存经过用户授权、截断或匿名化的样本，并设置单独的访问审批流程。不要因为“日志只在内网”就默认可以保存所有内容。

权限：把模型当作不可信调用者

模型输出应被视为不可信数据。即使模型建议执行某个操作，也必须由后端代码完成身份校验、参数校验和业务授权。

按身份和用途拆分权限

一个实用的分层方式：

每个工具接口都应定义明确的输入和输出。例如“查询订单”只接受经过校验的订单号，不能接受任意 SQL；“发送邮件”需要收件人白名单和人工确认。

前后端边界

浏览器端不应持有生产 API Key。推荐流程是：

1. 前端向自己的后端发起请求。
2. 后端验证登录态、租户和配额。
3. 后端从密钥管理器读取凭据并调用模型。
4. 后端过滤响应后返回前端。
5. 审计日志记录调用者、用途和结果。

如果确实需要客户端直连，也应使用短期、范围受限的令牌，并通过后端签发和撤销，不能把长期高权限密钥打包进 JavaScript。

如何核对接入路径和计费信息

不同服务的接口、可用模型、上下文限制、地区可用性和计费规则都会变化。需要复现实验或评估工具时，应先阅读对应提供方的当前文档，并在实际项目中做一次小规模验证。

如果需要一个独立的第三方入口来查看当前支持的工具和计费说明，可以访问 moli。moli 与任何模型提供商或 CSDN 没有隶属关系，该链接仅作为核对当期支持范围和计费信息的可选方式。

无论使用哪种入口，都应确认：

• 请求是否经过你的后端控制。
• 凭据由谁保存、谁可以撤销。
• 用量和错误信息能否导出审计。
• 数据是否会被用于训练或其他处理，相关条款以当前文档为准。
• 账单单位、上下文限制和速率限制是否适合你的任务。

推荐的开发到生产工作流

本地开发

• 使用独立的开发凭据。
• 只使用脱敏样例数据。
• 在 .gitignore 中排除 .env*。
• 为调用封装统一客户端，集中处理超时、重试和日志。

测试环境

• 使用测试项目和测试数据。
• 模拟超时、限流、无效凭据和返回格式变化。
• 验证日志中不存在 Key 和原始敏感内容。
• 检查权限矩阵：普通用户不能访问管理接口。

生产发布

• 发布前执行密钥扫描和依赖扫描。
• 通过密钥管理器注入凭据。
• 为模型调用设置预算、超时和最大重试次数。
• 开启调用审计和异常告警。
• 准备撤销 Key、回滚版本和关闭高风险工具的操作手册。

常见失败模式

验证清单

可以在每次发布和每月审计时执行：

• 仓库、镜像和构建日志中没有真实 Key。
• 前端资源中没有长期凭据。
• 测试、预发布和生产凭据相互隔离。
• Key 有负责人、创建时间、用途和撤销步骤。
• 日志经过脱敏，且访问权限与保留期限明确。
• 普通用户无法读取其他租户数据。
• 工具参数经过类型、范围和资源归属校验。
• 超时、重试、限流和预算行为经过测试。
• 发生泄露时，值班人员能在几分钟内完成撤销和替换。
• 当前能力、可用性、上下文限制和计费规则已通过最新文档核对。

结语

把 AI 接入项目后，真正需要维护的是一条完整的控制链：凭据可撤销、日志可审计、权限可限制、异常可恢复。先从服务端代理、密钥分环境、日志默认脱敏和工具最小权限做起，再根据业务风险增加审批、预算和数据保留策略。

模型能力、服务可用性、上下文限制和计费方式都可能调整，发布前应重新核对当前文档，并用授权数据完成小规模验证。