秘密信息与集成元数据：不存储 API 密钥的设计

一句话定义

秘密信息是一项原则：将集成状态和标识元数据保存在服务数据库中，并将真正的秘密信息存放在专用的 secret store 中。

核心结论：如果将 API 密钥存储在常规运营记录或日志中，便会通过查询权限和备份扩大暴露范围。界面上进行了遮蔽，也不能成为存储原文的正当理由。

为什么需要这项技术？

如果将 API 密钥存储在常规运营记录或日志中，便会通过查询权限和备份扩大暴露范围。界面上进行了遮蔽，也不能成为存储原文的正当理由。

工作原理

服务中只保存 provider、连接状态、key fingerprint 和更新时间。秘密信息通过各环境的 secret manager 注入，并设置轮换与撤销流程。

设计时不能只考虑准确性。还必须一并定义延迟、成本、数据边界、更新周期以及失败时的行为，才能在运营中获得可复现的结果。对于自动化无法确定的值，不要将其改为 0 或成功，而应安全地保留为未测量或需要审核的状态。

与 SAG 技术的关联

SAG 的 credential 记录是用于准备连接的 metadata 契约，不会存储实际的 API key，也不会将外部连接标记为已完成。

实务检查清单

• 不在数据库和日志中保留原始 key
• 仅显示 fingerprint 和更新时间
• 验证轮换后旧 key 已撤销
• 将失败、空结果和权限错误的状态与成功区分开
• 在相同条件下重新验证变更前后的结果

研究与官方文档

• Google AI 搜索功能官方指南

参考文档为原理和建议提供依据。它们不保证搜索曝光、AI 提及、排名或营收；实际应用效果应通过服务数据以及在相同条件下进行的观测来验证。

主题技术参考

• OWASP 秘密信息管理

如何继续阅读相关技术

了解租户权限、任务重试、缓存和审批记录。

• 设计稳定的客户空间
• 功能说明 FAQ