Atoms 密钥和机密信息
将你应用的私密凭证存储在 Atoms 云 → 密钥 中，以避免其值出现在聊天和源代码中，并管理独立的测试和生产值。
在使用 密钥 之前，请先将项目连接到 Atoms 云。如果尚未连接，请让智能体连接 Atoms 云，或参阅 Atoms 云。
在 Atoms 云 中使用密钥
开始之前
在添加密钥之前，请确认：
如果 密钥 或 新建密钥 不可用，请确认你打开的是目标项目，并且该项目已连接到 Atoms 云。如果 新建密钥 仍不可用，请确认你是工作区所有者。如果 Atoms 显示套餐或使用可用性消息，请按照屏幕上的可用性或升级路径操作，然后重试。
添加测试密钥
- 在桌面设备上打开项目。
- 在与 App 预览 所在相同的工作区工具栏中，选择 Atoms 云。
- 在 Atoms 云侧边栏中选择 密钥。
- 打开 测试密钥，然后选择 在此项目中。
- 选择 新建密钥。
- 填写必填字段：
- 名称： 输入清晰的引用名称，例如 RESEND_API_KEY。使用字母、数字和下划线，并以字母或下划线开头。
- 值： 按提供方给出的内容原样输入凭证。
- 描述： 说明该密钥的用途，例如 用于发送账户邮件。不要包含凭证值。
- 如果你想在其他项目中复用该密钥，请选择 保存到库。
- 选择 添加。密钥保存后，Atoms 会显示 密钥添加成功。
添加测试密钥
只有工作区所有者才能添加新密钥。如果你需要添加密钥，请联系工作区所有者。
在聊天中使用已保存的密钥
引用已保存的密钥，而不是在消息中输入其值。
- 在桌面版 Atoms 中打开项目 聊天 并输入
#。 - 选择 密钥。
- 搜索已保存的密钥，然后选择其名称。
- 告诉智能体该密钥的用途，以及你希望集成执行什么操作。
# 菜单会添加对已保存密钥的引用，而不会将其值插入到你的消息中。
在聊天中引用已保存的密钥
测试已保存的密钥
- 在 App 预览 中，执行一个会使用该密钥的简单操作。
- 确认它产生了预期结果，例如发送测试邮件或返回测试数据。
- 检查任何可见错误或日志，并确保它们不会暴露密钥的值。
如果服务为你提供了独立的测试密钥和正式密钥，请在构建应用时使用测试密钥。仅在应用发布后使用正式密钥。如果测试失败，请检查提供方的控制台，确认该密钥处于激活状态并且有权限执行所请求的操作。排查问题时，切勿将密钥的值粘贴到聊天中。
了解密钥的工作方式
在添加密钥之前，了解 Atoms 存储的内容以及如何保护你的凭证会很有帮助。
Atoms 存储什么
Atoms 云 → 密钥 用于存储你的应用连接外部服务时使用的凭证，例如 API 密钥和访问 Token。
每个已保存的密钥都有名称、描述和私密值。名称和描述可帮助智能体理解何时使用该密钥，而私密值会对 聊天 保持隐藏。
在哪里获取密钥
Atoms 不会为外部服务创建或提供凭证。你必须从相关服务提供方处获取。选择权限、测试密钥以及检查其是否会过期时，请遵循提供方的说明。
保持私密凭证的机密性
切勿将私密凭证粘贴到 聊天、源代码、在浏览器中运行的代码、截图、日志或支持消息中。请将其保存在 密钥 中，然后按名称引用已保存的条目。
如果私密值已经暴露，请将其视为已泄露，并通过提供方将其撤销或轮换。
私密凭证与浏览器安全凭证
密钥 不会将已保存的值标记为 公开 或 私密。将某个值保存在 密钥 中，并不会自动使其适合在面向浏览器的代码中安全使用。如果你的应用在浏览器中使用该值，访问者可能能够查看它。
在决定将凭证用于何处之前，请查阅提供方文档：
- 仅当提供方明确说明可安全暴露时，才可在面向浏览器的代码中使用该值。
- 将私密凭证保留在服务器端或后端逻辑中，以免向应用访问者暴露。
选择密钥的环境和存储位置
添加密钥时，你需要分别做出两个决定：
- 哪个环境将使用该密钥。
- 该密钥是仅保留在此项目中，还是可供其他项目使用。
选择环境
| 选项 | 使用时机 |
|---|---|
| 测试密钥 | 在 App 预览 中开发和测试应用时使用。如果你没有单独添加生产值，则已发布的应用也会使用测试值。 |
| 生产密钥 | 当已发布的应用需要单独的正式凭证时使用。生产值会在发布过程中添加，并与测试值分开管理。 |
选择将密钥保存到哪里
| 选项 | 何时使用 |
|---|---|
| 在此项目中 | 当某个密钥应仅供当前项目使用时，选择此项。 |
| 密钥库 | 当你明确希望在多个项目之间复用某个密钥时，选择此项。添加或更新测试密钥时，选择 保存到库 以使其在库中可用。 |
环境和存储位置彼此独立。将测试密钥保存到 密钥库 会使其可复用，但不会将其变成生产值。
默认使用 在此项目中。只有在你确定该密钥应在多个项目之间共享时，才将其保存到库中。
使用单独的生产值
当你发布使用了已保存密钥的项目时，发布流程可能会要求你配置 生产密钥。默认情况下，已发布的应用会使用测试值。若要使用不同的凭证，请选择 生产 并为该密钥保存一个单独的值。
在以下情况下，请使用单独的生产值：
- 提供方提供不同的测试凭证和正式凭证。
- 你不希望开发期间使用的凭证被已发布的应用使用。
生产值通过发布流程创建。你不能通过在 生产密钥 标签页中选择 新建密钥 来创建。为已发布应用配置生产值后，你可以在 Atoms 云 → 密钥 → 生产密钥 下查看它。
发布或更新应用后，请在已发布的网站上重复相关用户路径，以确认生产密钥工作正常。完整部署流程请参阅 发布和部署。
更新或轮换凭证
更新已保存的测试值
- 打开 Atoms 云 → 密钥 → 测试密钥。
- 根据条目的保存位置，打开 在此项目中 或 密钥库。
- 选择该密钥的 值 或 描述，输入更新后的信息，然后选择 更新。
- 等待出现 保存成功，然后再次测试受影响的流程。
计划内密钥轮换
当现有凭证仍然安全，而你希望在不中断应用的情况下替换它时，请按以下步骤操作：
- 通过服务提供方创建替代凭证。
- 在 Atoms 中替换测试值，然后在 App 预览 中测试受影响的功能。
- 如果已发布的应用使用单独的生产值，请替换它并发布更新。
- 在已发布的网站上测试相同功能。
- 确认替代凭证工作正常后，通过提供方撤销旧凭证。
如果凭证可能已经暴露
请将该凭证视为已泄露，并立即采取行动：
- 通过服务提供方将其撤销或禁用。
- 创建替代凭证。
- 在 Atoms 中更新相关的测试值和生产值。
- 在 App 预览 和已发布应用中再次测试受影响的功能。
- 尽可能从源代码、聊天、截图和日志中移除任何已暴露的副本。
从 Atoms 中删除密钥或移除其值，并不会撤销原始凭证。你必须通过服务提供方将其撤销。
移除凭证
在删除已保存的密钥之前，请确保你的应用已不再依赖它：
- 移除使用该密钥的功能，或将其引用替换为另一个已保存的密钥。
- 通过服务提供方撤销原始凭证，使其无法再被使用。
- 打开 Atoms 云 → 密钥，找到不再活动的条目，选择 删除，然后确认。
删除密钥后无法撤销。它还可能导致仍引用该密钥的预览或旧检查点失效。如果 删除 不可用，则说明该密钥仍被标记为活动。请先移除或替换对它的所有引用，然后再重试。
常见问题
为什么我的测试密钥在 App 预览 中可用，但发布后不可用？
如果你的测试密钥在 App 预览 中可用，但已发布的应用因密钥缺失或为空而失败：
- 检查相关测试值或生产值是在上次发布之前还是之后保存的。如果是在之后保存的，请重新发布以使更改生效。
- 验证已保存的密钥是否具有正确的测试值或生产值。除非配置了单独的生产值，否则已发布的应用会使用测试值。
- 查看下游服务错误以获取线索。“Unauthorized” 通常表示该环境中的密钥为空或不正确。
如果问题仍然存在，请联系支持团队，并附上：
- 项目链接或线上 URL
- 受影响的密钥名称，以及问题出在测试值还是生产值
- 下游服务返回的完整错误信息
- 配置页面的脱敏截图
- 密钥配置是在发布之前还是之后保存的
重要提示：仅提供密钥名称。不要发送机密值、密码或 Token。