diff --git a/操作说明.md b/操作说明.md index 972a362..17fb6b4 100644 --- a/操作说明.md +++ b/操作说明.md @@ -42,146 +42,120 @@ npm run dev ## 二、管理员操作 -### 给新部门开通子账号 - -**步骤 1:创建子账号** +### 1. 创建子账号 1. 左侧菜单 → **子账号管理** → 点 **创建子账号** 2. 填写: - **用户名**:英文,如 `dept_video` - **显示名**:如 `视频部门` - - **火山控制台密码**:不填(子账号不需要登录火山控制台) - - 其他选填 + - **手机号**:可选 + - **火山控制台密码**:需包含大小写字母、数字和特殊字符,8位以上(火山密码策略要求) 3. 点 **创建** -4. 弹窗显示 IAM API 密钥 → **立即复制保存**(SecretKey 仅显示一次) +4. 系统自动在火山创建 IAM 用户,并自动生成 `AirGate_Deny_{username}` 策略用于项目隔离 -**步骤 2:在火山控制台创建项目并开通模型** +### 2. 权限管理 -1. 登录 `console.volcengine.com`(你的主账号) -2. 项目管理 → 新建项目(如 `team-video-1`) -3. 进入方舟平台 → 切到该项目 → 开通 Seedance 2.0 端点 -4. 在该项目下创建方舟 API Key → **复制完整 Key** +统一权限管理页面,一页展示所有权限信息: -**步骤 3:在 AirGate 关联项目并授权** +1. 子账号管理 → 找到目标用户 → 点 **权限管理** +2. 页面分区: + - **全局策略**:当前用户挂载的全局策略列表(实时从火山查询) + - **项目级策略**:当前用户在各项目下挂载的策略(实时从火山查询) + - **关联项目**:管理用户关联的火山项目(添加/移除) + - **添加/移除策略**:为用户附加或移除 IAM 策略 +3. 添加关联项目时自动更新 Deny 策略(将新项目加入白名单) +4. 移除关联项目时自动更新 Deny 策略(将项目从白名单移除) -1. 回到 AirGate → 子账号管理 → 找到刚创建的子账号 -2. 点 **更多 → 项目管理** -3. 从下拉框选择刚创建的项目 → 点 **添加** -4. 点项目行上的 **授权** 按钮 → 勾选需要的策略(如 `ArkFullAccess` + `TOSFullAccess`)→ 保存 +### 3. 额度划拨 -**步骤 4:录入 API Key** +1. 子账号管理 → 找到目标用户 → 点 **划拨** +2. 输入正数追加、负数扣减 +3. **必须填写备注** → 确认 + +> 扣减有保护:总额度不能低于已消费金额 + +### 4. 监控配置 + +1. 子账号管理 → 找到目标用户 → 点 **监控配置** +2. 可配置项: + - **阶梯告警**:自定义告警百分比阶梯(如 50,80,90),未设置则使用全局默认值 + - **消费监控开关**:开启/关闭该用户的消费监控 + - **自动停用开关**:额度用尽时是否自动停用(关闭则只告警不停用) + - **Deny策略免除开关**:管理员自用账号可开启,免除 Deny 策略限制 + +### 5. 停用/恢复账号 + +**停用:** +1. 子账号管理 → 更多 → **停用账号** +2. 系统自动执行: + - 关闭火山控制台登录 + - 停用所有 API Key + - 移除所有权限策略 + - 保存策略快照(区分全局策略/项目级策略 + 登录状态),用于恢复 + +**恢复:** +1. 子账号管理 → 更多 → **恢复账号** +2. 系统自动执行: + - 从快照还原所有权限策略(全局+项目级) + - 重建 `AirGate_Deny_{username}` 策略 + - 按停用前状态恢复火山控制台登录(停用前已关闭的不会自动打开) + +### 6. 火山登录开关 + +1. 子账号管理 → 更多 → **火山登录开关** +2. 独立于停用/恢复操作,可随时开启或关闭子账号的火山控制台登录权限 +3. 同步调用火山 `UpdateLoginProfile` API + +### 7. 编辑子账号信息 + +1. 子账号管理 → 找到目标用户 → 点 **编辑** +2. 可修改:显示名、手机号、邮箱 +3. 修改后自动同步到火山引擎(调用 `UpdateUser` API) + +### 8. API Key 管理 1. 左侧菜单 → **API Key 管理** → 点 **录入 API Key** 2. 选择子账号、所属项目 3. 填写名称/用途、粘贴完整的 API Key 4. 点 **录入** → Key 加密存储 -**步骤 5:划拨额度** +> API Key 采用手动录入方式。管理员在火山控制台创建 Key 后,将明文录入 AirGate。 +> 原因:火山 `CreateApiKey` API 不返回 Key 明文,`ListApiKeys` 只返回脱敏值。 -1. 子账号管理 → 点子账号的 **划拨** 按钮 -2. 输入金额(如 100000)和备注 → 确认 +操作:查看明文 / 启用 / 停用 / 删除,可按子账号、项目筛选。 -**步骤 6:设置子账号的 AirGate 登录密码** +### 9. 系统管理 -1. 子账号管理 → 更多 → **登录密码** -2. 输入密码 → 开启「允许登录」→ 保存 - -**步骤 7:告知对方** - -发给对方以下信息: -- AirGate 登录地址:`http://你的部署地址` -- 登录方式:选择「子账号登录」 -- 用户名:`dept_video` -- 密码:你设置的密码 -- 登录后在「我的 API Key」中查看和复制 Key +1. **修改密码**:左侧菜单 → 系统管理 → 修改密码 +2. **管理员管理**(仅超级管理员):创建新管理员 / 启停 / 重置密码 +3. **操作日志**:查看所有系统操作记录(含类型筛选) --- -### 给子账号追加/扣减额度 +## 三、Deny策略说明 -1. 子账号管理 → 找到目标用户 → 点 **划拨** -2. 输入正数追加、负数扣减 -3. 填备注 → 确认 +### 原理 -> 扣减有保护:总额度不能低于已消费金额 +AirGate 通过 Deny 策略实现项目隔离。原理:列出火山账号下所有项目,排除用户的白名单项目(已关联项目),对其余项目全部 Deny。 + +### 自动管理 + +- **创建子账号时**:自动生成 `AirGate_Deny_{username}` 策略 +- **添加关联项目时**:自动更新所有子账号的 Deny 策略,将新项目加入白名单 +- **移除关联项目时**:自动更新 Deny 策略,将项目从白名单移除 +- **项目变动时**:刷新所有用户的 Deny 策略(确保新增的火山项目也被 Deny) + +### Deny策略免除 + +管理员自用账号可在监控配置中开启「Deny策略免除」开关,免除 Deny 策略限制,允许访问所有项目。 + +### 为什么用 Deny 策略 + +火山 Open API 的 `AttachUserPolicy` 不支持 `Scope=Project` 参数(2026-03-28 实测)。即使传了 `ProjectName` + `Scope=Project`,策略仍以 Global 方式挂载。项目级策略只能在火山控制台网页上手动操作。因此 AirGate 的项目隔离完全依赖 Deny 策略实现。 --- -### 给子账号增加新项目 - -1. 先在火山控制台创建新项目 + 开通模型端点 + 创建 API Key -2. 回到 AirGate → 子账号管理 → 更多 → **项目管理** → 添加项目 -3. 点 **授权** 选择策略 -4. 去 **API Key 管理** 录入新的 Key - ---- - -### 管理子账号的项目级权限 - -1. 子账号管理 → 更多 → **项目管理** -2. 找到目标项目 → 点 **授权** -3. 勾选/取消策略 → 保存(增量更新:只添加新的、移除取消的) - ---- - -### 关闭某个项目的监测 - -1. 子账号管理 → 更多 → **项目管理** -2. 找到目标项目 → 关闭「监测」开关 -3. 该项目的消费不再计入子账号的累计消费 - ---- - -### 手动停用/恢复子账号 - -**停用:** -1. 子账号管理 → 更多 → **停用账号** -2. 系统自动执行三步:停用控制台登录 + 停用所有 API Key + 移除所有权限策略 -3. 子账号刷新页面后立即无法操作 - -**恢复:** -1. 子账号管理 → 更多 → **恢复账号** -2. 自动恢复控制台登录 + API Key + 权限策略(从停用时的快照恢复) - ---- - -### 查看/管理 API Key - -1. 左侧菜单 → **API Key 管理** -2. 可按子账号、项目筛选 -3. 操作:查看明文 / 启用 / 停用 / 删除 - ---- - -### 查看消费明细 - -1. 左侧菜单 → **消费监控** -2. 表格展示每个子账号的累计消费、额度、使用率 -3. 点行首展开查看各项目的独立消费 -4. 点 **刷新消费数据** 手动触发查询 -5. 点 **查看主账号余额** 查看可用余额 - -> 消费数据来自火山 Billing API,有 1-2 天延迟 - ---- - -### 查看告警/操作日志 - -1. 左侧菜单 → **告警记录** — 查看告警和自动停用记录 -2. 左侧菜单 → **系统管理** → **操作日志** — 查看所有操作记录(含类型筛选) - ---- - -### 管理员账号管理 - -1. 左侧菜单 → **系统管理** -2. **修改密码**:修改当前管理员的密码 -3. **管理员管理**(仅超级管理员):创建新管理员 / 启停 / 重置密码 -4. **操作日志**:查看所有系统操作记录 - ---- - -## 三、子账号操作 +## 四、子账号操作 > 子账号使用独立的登录入口,不需要登录火山控制台。 @@ -227,7 +201,7 @@ response = requests.post(url, headers=headers, json={...}) --- -## 四、告警与自动停用机制 +## 五、告警与自动停用机制 ``` 定时任务每小时运行一次 @@ -254,7 +228,7 @@ response = requests.post(url, headers=headers, json={...}) --- -## 五、外部系统对接(AirDrama) +## 六、外部系统对接(AirDrama) AirGate 支持通过 API Key 认证供外部系统调用: @@ -271,12 +245,14 @@ curl -H "X-API-Key: 你的密钥" http://localhost:8101/api/v1/billing/overview/ --- -## 六、注意事项 +## 七、火山API限制 -1. **消费数据有 1-2 天延迟**:火山 Billing API 的限制,划拨额度时建议预留余量 -2. **IAM SecretKey 只显示一次**:创建子账号时弹窗里的 SecretAccessKey 关掉就没了 -3. **方舟 API Key 由管理员录入**:火山 API 不返回 Key 明文,需要在火山控制台创建后手动录入 AirGate -4. **子账号不登录火山控制台**:所有操作通过 AirGate 完成,避免权限泄露 -5. **项目由管理员创建**:子账号没有创建项目的权限,需要新项目时联系管理员 -6. **seaislee 账号不要动**:这是你自己的子账号,监控和自动停用已关闭 -7. **加密密钥不要丢**:`.env` 中的 `AIRGATE_ENCRYPTION_KEY` 丢失后,已存储的密钥无法解密 +1. **项目级策略(Scope=Project)通过API无法设置**:需在火山控制台手动操作,AirGate 的项目隔离完全依赖 Deny 策略 +2. **火山控制台密码要求**:需包含大小写字母、数字和特殊字符,8位以上 +3. **消费数据有 1-2 天延迟**:火山 Billing API 的限制,划拨额度时建议预留余量 +4. **IAM SecretKey 只显示一次**:创建子账号时弹窗里的 SecretAccessKey 关掉就没了 +5. **方舟 API Key 由管理员录入**:火山 API 不返回 Key 明文,需要在火山控制台创建后手动录入 AirGate +6. **子账号不登录火山控制台**:所有操作通过 AirGate 完成,避免权限泄露 +7. **项目由管理员创建**:子账号没有创建项目的权限,需要新项目时联系管理员 +8. **seaislee 账号不要动**:这是你自己的子账号,监控和自动停用已关闭 +9. **加密密钥不要丢**:`.env` 中的 `AIRGATE_ENCRYPTION_KEY` 丢失后,已存储的密钥无法解密 diff --git a/火山引擎IAM子账号管控工具_深度研究报告.md b/火山引擎IAM子账号管控工具_深度研究报告.md index f99a9ed..4e0c58c 100644 --- a/火山引擎IAM子账号管控工具_深度研究报告.md +++ b/火山引擎IAM子账号管控工具_深度研究报告.md @@ -1232,6 +1232,15 @@ PUT /api/v1/iam-users/{id}/projects/{pid}/policies/ # 更新项目级授权 **结论**:火山控制台无法实现项目级的视图隔离。要实现"子账号只看到自己项目",必须在应用层(AirGate)控制。 +### 13.1.2 火山Open API不支持Scope=Project(2026-03-28 实测) + +| 测试场景 | 结果 | +|----------|------| +| `AttachUserPolicy` 传 `Scope=Project` + `ProjectName=xxx` | 策略仍以 **Global** 方式挂载,`ListAttachedUserPolicies` 查询显示 Scope=Global | +| 火山控制台网页上手动「限制到项目资源」 | 策略正确以 Project 方式挂载 | + +**结论**:火山 Open API 的 `AttachUserPolicy` 即使传了 `Scope=Project` + `ProjectName` 参数,策略仍然以 Global 方式挂载。项目级策略(Scope=Project)只能在火山控制台网页上手动操作(点击「限制到项目资源」按钮)。因此 AirGate 无法通过 API 实现项目级授权,项目隔离完全依赖 Deny 策略实现。 + ### 13.1.1 跨项目 API 访问问题(2026-03-28 实测) | 测试场景 | 结果 | @@ -1268,11 +1277,15 @@ PUT /api/v1/iam-users/{id}/projects/{pid}/policies/ # 更新项目级授权 | `ListApiKeys` 指定 `int_dev_Airlabs` | 返回 1 个 Key | **被拒绝** ✅ | | `ListAssetGroups` 指定 `HAGOOT_DEV` | 正常返回 | 正常返回 ✅ | -### 13.2 最终权限方案 +### 13.2 最终权限方案:全局授权 + Deny策略隔离 ``` 子账号在火山引擎上的权限(由 AirGate 自动管理): +核心思路:全局授权 + Deny策略隔离 + 由于火山 Open API 不支持 Scope=Project(见 13.1.2), + 所有策略以全局方式挂载,再通过 Deny 策略限定可访问的项目范围。 + 全局权限: ├── AccessKeySelfManageAccess ← 管理自己的 AK/SK(可选) └── AirGate_Deny_{username} ← 自定义 Deny 策略,禁止访问非授权项目 @@ -1291,10 +1304,13 @@ PUT /api/v1/iam-users/{id}/projects/{pid}/policies/ # 更新项目级授权 火山控制台登录:默认关闭(AirGate 提供开关可随时切换) Deny 策略自动管理(项目隔离的唯一可靠手段): + - 创建子账号时 → 自动创建 AirGate_Deny_{username} 策略 - 添加关联项目时 → 自动更新 Deny 策略,将新项目加入白名单 - 移除关联项目时 → 自动更新 Deny 策略,将项目从白名单移除 + - 火山项目变动时 → 刷新所有用户的 Deny 策略 - Deny 策略列出所有非白名单项目并明确拒绝 - 策略命名:AirGate_Deny_{username} + - 管理员自用账号可免除 Deny 策略(监控配置中开启) ``` 子账号**不能也不需要**登录火山控制台。所有操作通过 AirGate 完成: diff --git a/版本管理.md b/版本管理.md index 9cff794..c22e74e 100644 --- a/版本管理.md +++ b/版本管理.md @@ -2,6 +2,26 @@ --- +## v0.5.0 (2026-03-28 ~ 2026-03-29) + +### 权限管理重构 +- feat: 统一权限管理页面(全局策略 + 项目级策略 + 关联项目 + 添加/移除策略,一页展示) +- feat: Deny策略自动化(项目隔离)—— 创建子账号时自动生成 `AirGate_Deny_{username}`,添加/移除项目时自动更新 +- feat: Deny策略免除开关(管理员自用账号可在监控配置中开启) +- fix: 火山API不支持Scope=Project(2026-03-28实测),改用全局授权 + Deny策略实现项目隔离 +- fix: 项目变动刷新所有用户Deny策略 +- fix: 前后端权限显示一致(实时从火山查询,不再依赖本地缓存) + +### 账号管理增强 +- feat: 火山控制台登录开关(独立于停用/恢复,随时切换) +- feat: 编辑子账号信息(显示名、手机号、邮箱,修改后同步火山 `UpdateUser` API) +- feat: 创建子账号密码校验(火山密码策略:大小写字母 + 数字 + 特殊字符,8位以上) +- fix: 停用/恢复保存策略快照(区分全局策略/项目级策略 + 登录状态,恢复时精确还原) +- fix: 同步不再把火山登录关闭当成账号停用 +- fix: 检测幽灵LoginProfile(CreateDate=1970,火山API已知问题) + +--- + ## v0.4.0 (2026-03-20) ### UI 优化