跳转到主要内容
轮换前先确认你在更换哪类秘密:应用 API Token、上游账户凭据、OCI registry Secret,还是数据库加密主密钥。它们没有相同的更新路径。 应用 Token 见身份管理。本页讨论受保护连接引用的 Managed Secret;它的原始值只写入、不回显,不能通过读取 API 导出。

列出影响范围

用 secret(secret_id) 查询元数据及依赖连接 / Harness。为每个依赖记录当前验证与启用状态、活动 Session 和计划清理方式。先安排任务结束,再轮换;旧凭据是否还能在供应商侧使用由供应商决定,不能依赖 Hexagon 自动撤回上游权限。

更新值并重新验证

以下接续 owner 客户端,值由私有环境提供:
dependent* 来自事先读取的引用清单。更新值或 enabled 会在同一事务中禁用依赖连接、清空验证并递增版本。循环部分不是跨所有连接的原子操作;中途失败时保留已处理清单,不声称所有依赖已恢复。 轮换后创建新 Session 使用新版本策略。旧 Session 固定的授权不能被假定为自动迁移;已接受的上游请求可能继续完成,撤销不能倒转副作用。

两个依赖连接的轮换实例

假设同一 Managed Secret 被模型连接 A 和受保护 HTTP 连接 B 引用。更换值前保存两者 ID 与版本。更新会将替代值复制到各依赖连接的加密凭据,令连接进入 draft/disabled,清空验证并递增版本。仅修改 Secret 名称不会触发这项依赖连接失效。 如果 A 验证成功、B 失败,只在成功检查后启用 A,让 B 保持禁用。记录部分完成状态,不宣布轮换全部完成,也不重放中断的业务写入来测试 B。修正 B 上游权限后,再明确验证、启用。为已改变的模型/受保护 HTTP 版本创建新 Session,并确认实际授权访问及清理。 模型/受保护 HTTP grant 在后续每次请求中检查连接当前版本,因此即使重新启用连接,旧 grant 仍会在轮换后失败。旧 Session 固定先前版本,通过它签发新 grant 可能返回 session_connection_changed。已接受的请求另当别论,仍可能完成。Tool 授权恢复遵循专用流程,不能从模型/HTTP grant 规则推断。 元数据依赖列表只是清单辅助,不证明不存在其他活动工作:其 Session 视图有数量上限,并按固定连接定义选择。活动工作与资源清理须分别对账。此例是建议执行的轮换练习,本轮没有对真实上游运行它。 专用连接凭据替换练习将无效占位凭据替换为已获准的模型凭据,观察版本变化及 draft/disabled 状态,重新验证、启用,并完成新的 Vercel/Pi 任务。Session 已关闭,创建/删除操作完成,测试连接已删除,原共享连接版本未变。这证明 Hexagon 连接中的凭据替换,不是上游账户密钥签发/撤销或加密主密钥轮换。

禁用、删除与 registry

禁用 Secret 不删除上游账户。删除仍被未删除连接或 Harness 镜像注册引用的 Secret,会返回 secret_in_use。不要直接删除数据库引用来绕过保护。 registry Secret 用于获准的镜像拉取路径,轮换在后续 provisioning 读取;它不是注入 Agent 的环境值。新镜像拉取、私有 registry 支持和既有注册引用需要分别检查。

主密钥和恢复

以上 API 更新的是上游秘密,不是加密主密钥。当前没有可由这里调用的通用主密钥轮换流程。替换 master.key 或 hosted HEXAGON_MASTER_KEY 可能使既有加密数据无法正常解密;不要作为排障步骤尝试。 备份必须保留匹配数据库、密钥与部署身份,使用可信私有存储。Secret 删除是逻辑删除,历史加密信封可能保留,不是物理擦除保证。 验证应确认新 Session 可访问获准服务、旧授权后续请求被拒绝、所有依赖逐一验证、日志 / guest 环境没有原始密钥。依据:Managed Secrets、凭据边界。下一步:连接生命周期、备份恢复、安全边界。