> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理和轮换受保护凭据

轮换前先确认你在更换哪类秘密：应用 API Token、上游账户凭据、OCI registry Secret，还是数据库加密主密钥。它们没有相同的更新路径。

应用 Token 见[身份管理](https://docs.hexagon.autos/zh-CN/operate/access-control.md)。本页讨论受保护连接引用的 Managed Secret；它的原始值只写入、不回显，不能通过读取 API 导出。

## 列出影响范围

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

## 更新值并重新验证

以下接续 owner 客户端，值由私有环境提供：

```python theme={null}
import os
client.update_secret(secret_id, value=os.environ['REPLACEMENT_SECRET'])
for connection_id in dependent_connection_ids:
    result = client.validate_connection(connection_id)
    if result['status'] != 'ready':
        raise RuntimeError('Dependent connection remains disabled')
    client.update_connection(connection_id, enabled=True)
```

```typescript theme={null}
const replacement = process.env.REPLACEMENT_SECRET;
if (!replacement) throw new Error('Missing replacement secret');
await client.updateSecret(secretId, { value: replacement });
for (const id of dependentConnectionIds) {
  const result = await client.validateConnection(id);
  if (result.status !== 'ready') throw new Error('Dependent connection remains disabled');
  await client.updateConnection(id, { enabled: true });
}
```

`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 授权恢复遵循[专用流程](https://docs.hexagon.autos/zh-CN/build/tool-authorization.md)，不能从模型/HTTP grant 规则推断。

元数据依赖列表只是清单辅助，不证明不存在其他活动工作：其 Session 视图有数量上限，并按固定连接定义选择。活动工作与资源清理须分别对账。此例是建议执行的轮换练习，本轮没有对真实上游运行它。

[专用连接凭据替换练习](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-docs-credential-rotation-cloud.json)将无效占位凭据替换为已获准的模型凭据，观察版本变化及 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](https://github.com/NexusFox88/docs/blob/main/resources/modules/credentials/managed-secrets.ts)、[凭据边界](https://github.com/NexusFox88/docs/blob/main/resources/docs/secret-management.md)。下一步：[连接生命周期](https://docs.hexagon.autos/zh-CN/build/connection-lifecycle.md)、[备份恢复](https://docs.hexagon.autos/zh-CN/operate/backup-restore.md)、[安全边界](https://docs.hexagon.autos/zh-CN/concepts/security-boundaries.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.