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