一、操作场景
·首次开通 TencentDB Agent 后，确认默认全局只读角色已自动创建并生效。
·基于业务需求，为特定实例创建可写权限角色并关联生效。
·查看当前账号下所有 CAM 角色的状态、策略及关联实例情况。
二、背景信息
TencentDB Agent 通过腾讯云 访问管理（CAM） 统一管理 TencentDB Agent 调用云 API 的权限。用户角色是在客户 CAM 账号下创建的标准 CAM 角色，TencentDB Agent 管理端负责镜像展示这些角色，并维护角色与实例的关联关系。TencentDB Agent 以绑定的角色身份获取临时凭证调用腾讯云数据库管控面 API，实现权限与人的子账号完全解耦。
三、核心概念
| 概念 | 说明 |
| 用户角色 | 客户在 CAM 控制台创建或由 TencentDB Agent 代创建的 CAM 角色，TencentDB Agent 以该角色身份调用云 API，权限边界由角色关联的策略决定 |
| 默认全局只读角色 | 客户首次创建 TencentDB Agent 实例时自动代建的 TencentDBAgent_AI_GlobalReadOnly 角色，默认对账号下所有未单独绑定角色的实例生效。 |
| 角色模板 | TencentDB Agent 提供的预定义策略组合方案，包含只读角色模板和可写角色模板，简化角色创建流程。 |
| 关联实例 | 将 CAM 角色绑定到指定 TencentDB Agent 实例，在操作该实例时以绑定角色身份执行。 |
四、生效优先级
TencentDB Agent 调用云 API 时，按以下优先级确定使用的角色：
1. 指定实例关联的角色：若目标实例已被单独绑定某角色，优先使用该角色。
2. 全局生效角色：若实例未被单独绑定，使用账号下的全局生效角色（默认为 TencentDBAgent_AI_GlobalReadOnly）。
六、只读角色模板（14条预置策略）
| 类别 | 策略名称 | 适用产品 |
| 关系型数据库（5条） | QcloudCDBReadOnlyAccess | 云数据库 MySQL |
| | QcloudCynosDBReadOnlyAccess | TDSQL-C MySQL |
| | QcloudMariaDBReadOnlyAccess | TDSQL MariaDB |
| | QcloudPostgreSqlReadOnlyAccess | 云数据库 PostgreSQL |
| | QcloudSqlServerReadOnlyAccess | 云数据库 SQL Server |
| KV / 缓存（2条） | QcloudRedisReadOnlyAccess | Distributed Cache (兼容 Redis) |
| | QcloudKeeWiDBReadOnlyAccess | KeeWiDB |
| 文档型 / 时序型（2条） | QcloudMongoDBReadOnlyAccess | 云数据库 MongoDB |
| | QcloudCTSDBReadOnlyAccess | CTSDB |
| 数据传输与诊断（4条） | QcloudDTSReadOnlyAccess | 数据传输服务 DTS |
| | QcloudDMCReadOnlyAccess | 数据库管理中心 DMC |
| | QcloudDBbrainReadOnlyAccess | 数据库智能管家 DBbrain |
| | QcloudMonitorReadOnlyAccess | 云监控 |
| 数据库 AI 服务（1条） | QcloudDatabaseClawUserFullAccess | 数据库 AI 服务 |
七、可写角色模板（14条只读 + 13条 FullAccess + 1条 Deny 兜底）
在只读模板全部14条策略基础上，额外关联以下策略：
写权限策略（13条）
| 类别 | 策略名称 | 适用产品 |
| 关系型数据库（5条） | QcloudCDBFullAccess | 云数据库 MySQL |
| | QcloudCynosDBFullAccess | TDSQL-C MySQL |
| | QcloudMariaDBFullAccess | TDSQL MariaDB |
| | QcloudPostgreSqlFullAccess | 云数据库 PostgreSQL |
| | QcloudSqlServerFullAccess | 云数据库 SQL Server |
| KV / 缓存（2条） | QcloudRedisFullAccess | Distributed Cache (兼容 Redis) |
| | QcloudKeeWiDBFullAccess | KeeWiDB |
| 文档型 / 时序型（2条） | QcloudMongoDBFullAccess | 云数据库 MongoDB |
| | QcloudCTSDBFullAccess | CTSDB |
| 数据传输与诊断（3条） | QcloudDTSFullAccess | 数据传输服务 DTS |
| | QcloudDMCFullAccess | 数据库管理中心 DMC |
| | QcloudDBbrainFullAccess | 数据库智能管家 DBbrain |
| 数据库 AI 服务（1条） | QcloudTDAIFullAccess | 数据库 AI 服务 |
Deny 兜底策略（1条）
| 策略名称 | 拒绝范围 |
| TencentDBAgent_DenyDestructive_v2 | 永久拒绝销毁、扩缩容、库表删除、网络变更等高危动作 |
注意：警告：
注意：可写角色允许 TencentDB Agent 调用数据库写操作类 API（参数变更、账号管理、备份恢复等），通过强制叠加 Deny 策略 TencentDBAgent_DenyDestructive_v2 兜底拒绝高危动作。本角色建议绑定指定实例，不建议全局生效。
八、实现机制
TencentDB Agent 用户角色管理基于以下机制实现权限的安全隔离：
1. 角色始终归属客户账号：所有用户角色均创建在客户自己的 CAM 账号下，客户随时可在 CAM 控制台查看、修改或收回权限。TencentDB Agent 仅在客户授权范围内代为创建和维护角色。
2. TencentDB Agent 身份与人的子账号解耦：TencentDB Agent 调用云 API 时使用独立的用户角色身份，不继承当前操作人（子账号）的 CAM 权限。即使操作人拥有扩缩容、网络变更等高危权限，TencentDB Agent 的操作边界仍受角色策略约束。
3. 默认全局只读兜底：客户首次创建实例时，系统自动代建默认全局只读角色 TencentDBAgent_AI_GlobalReadOnly，确保所有实例开通即拥有只读安全基线，无需客户主动配置。
4. 角色绑定到实例级别：每个 TencentDB Agent 实例可独立绑定不同的用户角色。角色变更后实例需重启以加载新凭证（通常 30 秒内恢复）。
5. 可写权限强制叠加 Deny 兜底：可写角色在授予写操作权限的同时，强制关联 TencentDBAgent_DenyDestructive_v2 策略，从 CAM 策略层面永久拒绝销毁、扩缩容、库表删除、网络变更等高危动作，确保不可能执行不可逆操作。
6. 全链路审计可追溯：每次 TencentDB Agent 调用云 API 时，请求携带实例 ID 和操作主体信息，可在 CAM 审计日志中追溯到具体实例和操作链路。
九、使用限制
| 限制项 | 限制说明 |
| 访问权限 | 仅主账号或被授予 QcloudDatabaseClawAdminFullAccess 策略的子账号可访问用户角色页面。 |
| 角色载体 | 用户角色页面仅展示 TencentDB Agent 可使用的 CAM 角色，其他类型的角色不在此页面展示。 |
| 全局角色数量 | 账号下最多1个全局生效角色处于启用状态。 |
| 实例角色绑定 | 同一实例只能绑定1个指定角色，绑定新角色时自动替换原绑定。 |
| 角色命名规范 | 角色名称以 DatabaseClaw_ 开头，支持英文、数字、下划线，长度不超过60个字符。 |
| 代创建前提 | 使用 TencentDB Agent 代创建角色功能时，当前操作人需具备 cam:CreateRole 和 cam:AttachRolePolicy 权限。 |
十、注意事项
·角色变更后，受影响的实例需要重启才能使新角色生效。重启期间（通常30秒内）TencentDB Agent 对话暂时不可用。
·可写角色模板中强制叠加 Deny 策略 TencentDBAgent_DenyDestructive_v2，永久拒绝销毁实例、扩缩容、网络变更、库表删除等高危动作。
·角色的编辑、删除、标签管理、策略调整等维护操作需在 CAM 控制台完成，TencentDB Agent 管理端不提供这些操作。
十一、前提条件
·当前账号已被授予 QcloudDatabaseClawAdminFullAccess CAM 策略。
·首次创建 TencentDB Agent 实例时已完成 TencentDBAgent_AIRoleProvisioner 角色的服务授权。
十三、创建用户角色
TencentDB Agent 提供两种创建用户角色的方式：通过 TencentDB Agent 代创建或前往 CAM 控制台手动创建。
十四、方式一：TencentDB Agent 代创建（推荐）
1. 登录 数据库 AI 服务控制台。
2. 在左侧导航栏选择 TencentDB Agent > 后台管理。
3. 选择团队管理 > 用户角色页面。
4. 在用户角色页面，单击 TencentDB Agent 代创建。
5. 在弹出的选择角色模板对话框中，选择需要创建的角色模板类型：
·只读角色模板：仅具备数据库只读权限，适用于诊断分析场景。
·可写角色模板：在只读基础上具备写操作权限（参数变更、账号管理、备份恢复等），同时强制叠加 Deny 策略拒绝高危动作。
6. 单击下一步，进入角色信息确认页面。
7. 确认或修改以下角色信息。
| 参数 | 说明 |
| 推荐角色名称 | 系统自动生成的角色名称，格式为 TencentDBAgent_AI_ReadOnly_<时间戳>或 TencentDBAgent_AI_ReadWrite_<时间戳>。支持自定义修改，需遵循以下约束：必须以 DatabaseClaw_开头仅支持英文、数字、下划线长度不超过60个字符 |
| 推荐角色描述 | 系统自动生成的角色描述，支持自定义修改。 |
| 标签 | 可选配置。为角色绑定标签键值对，用于资源的分类管理与成本核算。 |
| 策略信息 | 展示该角色将关联的预置策略清单（如只读/读写权限）。该内容为系统预置，不支持修改。 |
8. 阅读页面底部的安全说明，勾选确认复选框：我已了解：TencentDB Agent 代创建会在当前操作人 CAM 权限范围内创建角色并关联策略；后续编辑/删除仍在 CAM 完成。
9. 单击 TencentDB Agent 代创建，完成角色创建。
注意：说明：
十五、方式二：前往 CAM 控制台创建
1. 登录 CAM 控制台。
2. 在左侧导航栏选择角色。
3. 在页面上方单击新建角色。
4. 在弹出的选择角色载体窗口，选择腾讯云产品服务作为角色载体，进入新建自定义角色页面。
5. 在输入角色载体信息步骤，通过搜索选择腾讯云数据库 AI 服务，可选择的使用案例选择腾讯云数据库 AI 服务，单击下一步。
6. 在配置角色策略步骤，勾选你想要给当前角色添加的策略为角色配置策略，单击下一步。
注意：说明：
注意：可根据实际角色需要选择策略。若无匹配的策略，你可以 通过策略生成器创建自定义策略 后再进行操作。
7. 在配置角色标签步骤（可选），输入角色的标签键和标签值，单击下一步。
8. 在审阅步骤，输入你的角色名称，审阅你即将创建角色的相关信息无误后，单击完成后即完成自定义角色创建。
注意：支持自定义，需遵循以下约束：
注意：• 必须以 TencentDBAgent_ 开头，若不满足该命名约束，用户角色页面将不展示该新建角色。
注意：• 仅支持英文、数字、下划线
注意：• 长度不超过60个字符
9. 创建完成后，返回 TencentDB Agent 用户角色页，单击刷新按钮查看新建角色。
十六、关联实例
为角色配置生效的 TencentDB Agent 实例范围，在操作对应实例时以该角色身份执行。
1. 登录 数据库 AI 服务控制台。
2. 在左侧导航栏选择 TencentDB Agent > 后台管理。
3. 选择团队管理 > 用户角色页面。
4. 在用户角色页面，找到目标角色行，单击关联实例。
5. 在关联实例弹窗中，查看角色基础信息。
| 参数 | 说明 |
| 角色名称 | 当前操作用户所关联的 CAM 角色名称。 |
| 角色 ID | 该角色在 CAM 系统中的唯一标识（RoleId）。 |
| 角色载体 | 角色的信任实体信息，用于定义哪些账号或服务可以扮演该角色。 |
| CAM 操作 | 单击打开 CAM 角色详情将跳转至 CAM 控制台，查看该角色的权限策略、关联用户及信任策略等完整信息。 |
6. 在关联实例区域，通过地域筛选和搜索框定位目标实例。
实例列表字段说明：
| 参数 | 说明 |
| 实例 ID / 名称 | TencentDB Agent 实例的唯一资源标识（InstanceId）及自定义名称。 |
| 状态 | 实例当前的运行状态，包括运行中、重启中、隔离中等枚举值。 |
| 当前 AI 角色 | 该实例当前绑定的 CAM 角色名称。若未单独绑定或处于默认状态，则显示为 -。 |
7. 勾选需要关联的实例，单击保存关联实例。
注意：说明：
注意：保存后，TencentDB Agent 会更新对应 Pod 的 ServiceAccount 注解，触发 Pod rolling restart。期间实例状态变为重启中，恢复后回到运行中。重启过程中正在进行的 AI 对话会暂时中断，恢复后可继续提问。
注意：
十七、查看用户角色列表
1. 登录 数据库 AI 服务控制台。
2. 在左侧导航栏选择 TencentDB Agent > 后台管理。
3. 选择团队管理 > 用户角色页面。
4. 查看当前账号下 TencentDB Agent 可使用的 CAM 角色列表。
列表字段说明如下：
| 参数 | 说明 |
| 角色名称 | CAM 角色名称，与 CAM 控制台中的角色名称完全一致。 |
| 角色 ID | CAM 角色的唯一标识符（RoleId）。 |
| 角色载体 | 角色的信任实体信息（Principal）。 |
| 角色描述 | CAM 角色的描述信息，用于说明角色的用途。 |
| 标签信息 | 该角色所绑定的标签键值对，用于资源分类与成本管理。 |
| 会话最大持续时间 | 通过此角色获取的临时密钥（STS）的最长有效时间，默认为 2 小时。 |
| 关联实例 | 当前已绑定该角色的 TencentDB Agent 实例数量。单击数值可查看具体关联的实例地域及实例 ID。 |
| 操作 | 支持对该角色执行的操作：• 关联实例：配置实例与角色的绑定关系。具体操作请参见 关联实例。• CAM 详情：跳转至 CAM 控制台查看完整角色信息。 |
5. 若需搜索特定角色，在页面右上方的搜索框中输入角色名称进行筛选。
十八、查看 CAM 角色详情
1. 登录 数据库 AI 服务控制台。
2. 在左侧导航栏选择 TencentDB Agent > 后台管理。
3. 选择团队管理 > 用户角色页面。
4. 在用户角色页面，找到目标角色行，单击操作列的 CAM 详情，跳转至 CAM 控制台查看该角色的完整信息，包括权限策略、角色载体、会话设置等。
十九、管理 CAM 角色
TencentDB Agent 用户角色支持在 CAM 控制台创建或由 TencentDB Agent 代创建。无论角色来源如何，其全生命周期管理（查看、修改、删除等）均需在 CAM 控制台统一操作。
| 操作场景 | 说明 |
| 修改角色 | 调整角色的信任策略（载体）或权限策略。 |
| 删除角色 | 在 CAM 控制台移除不再使用的角色。注意：若角色仍被实例关联，删除可能导致服务异常。 |
20、后续步骤
·角色创建并关联实例后，TencentDB Agent 在对应实例的对话中将以该角色身份调用云 API，无需额外配置。
·如需调整角色策略（增减权限），请前往 CAM 控制台 编辑对应角色的策略列表。
·如需管理团队成员的访问权限，请参见 管理用户。
21、对应的 API 接口
| API 名称 | 说明 |
| DescribeClawRoles | 查询用户角色列表，返回角色名称、ID、载体、关联实例数等信息 |
| CreateClawRole | 基于角色模板代创建 CAM 角色并关联预置策略 |
| AssignClawRoleToInstances | 将指定角色关联到目标 TencentDB Agent 实例（支持批量） |
23、Q1：默认全局只读角色是什么时候创建的？
默认全局只读角色 TencentDBAgent_AI_GlobalReadOnly 在客户首次创建 TencentDB Agent 实例时由系统自动代建。创建成功后，该角色自动对账号下所有未单独绑定角色的实例生效，TencentDB Agent 以只读权限调用云 API。
24、Q2：TencentDB Agent 代创建角色和在 CAM 手动创建有什么区别？
| 对比维度 | TencentDB Agent 代创建 | CAM 手动创建 |
| 操作位置 | TencentDB Agent 管理端 | CAM 控制台 |
| 策略关联 | 按模板自动关联全部预置策略 | 需手动逐条关联策略 |
| 前提条件 | 操作人需具备 cam:CreateRole 和 cam:AttachRolePolicy 权限 | 操作人需具备 CAM 角色创建权限 |
| 适用场景 | 快速创建标准化角色 | 需要自定义策略组合时 |
两种方式创建的角色在 CAM 中完全等价，后续编辑、删除、策略调整均在 CAM 控制台完成。
25、Q3：只读角色和可写角色如何选择？
| 场景 | 推荐角色类型 | 说明 |
| 生产环境实例 | 只读角色 | TencentDB Agent 仅可执行诊断分析操作，不可进行任何写变更。 |
| 测试/开发环境实例 | 可写角色 | TencentDB Agent 可执行参数变更、账号管理、备份恢复等写操作，高危动作仍被 Deny 策略拒绝。 |
| 全局默认 | 只读角色 | 未单独绑定角色的实例默认以只读权限运行。 |
26、Q4：关联实例后为什么需要重启？
TencentDB Agent 采用 TKE OIDC 机制将 CAM 角色绑定到实例 Pod。角色变更后需要更新 Pod 的 ServiceAccount 绑定，因此受影响的实例需要重启以加载新角色的临时凭证。重启过程通常在30秒内完成。
27、Q5：可写角色的 Deny 策略能否移除？
可写角色代创建时，Deny 策略 TencentDBAgent_DenyDestructive_v2 会强制绑定，不可在代创建流程中跳过。客户如确有需要，可在 CAM 控制台手动解绑该策略。