---
title: "秘密信息与集成元数据：不存储 API 密钥的设计"
slug: "secret-handling-integration-metadata"
language: "zh-cn"
tags: ["비밀정보","sag 기술","아키텍처","플랫폼 운영"]
created: "2026-08-27T00:00:00.000Z"
published: "2026-10-08T10:01:27.600Z"
updated: "2026-10-08T10:01:27.600Z"
sample: false
---

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

## 一句话定义

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

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

## 为什么需要这项技术？

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

## 工作原理

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

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

## 与 SAG 技术的关联

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

## 实务检查清单

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

## 研究与官方文档

- [Google AI 搜索功能官方指南](https://developers.google.com/search/docs/appearance/ai-features)

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

## 主题技术参考

- [OWASP 秘密信息管理](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)


## 如何继续阅读相关技术

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

- [设计稳定的客户空间](/ko/blog?tag=%ED%94%8C%EB%9E%AB%ED%8F%BC%20%EC%9A%B4%EC%98%81)
- [功能说明 FAQ](/zh-cn/faq)