docs: update operation guide, changelog, and research report
- Rewrite 操作说明.md with full admin/sub-account operation flow - Add v0.5.0 to 版本管理.md (permission refactor + account enhancements) - Add Scope=Project API limitation finding to research report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
seaislee1209
parent
9f00e6996b
commit
294a0885ff
220
操作说明.md
220
操作说明.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` 丢失后，已存储的密钥无法解密
|
||||
|
||||
@ -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 完成：
|
||||
|
||||
20
版本管理.md
20
版本管理.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 优化
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user