From b25641cfc662c9315b40254ccda685ccb85cc522 Mon Sep 17 00:00:00 2001 From: seaislee1209 Date: Sat, 21 Mar 2026 17:51:45 +0800 Subject: [PATCH] docs: rewrite operations guide with admin/sub-account sections - Admin section: full workflow from account creation to key entry - Sub-account section: login, view keys, change password, use API - Updated for manual key entry mode and no-console-login architecture - Added alert/auto-disable mechanism description Co-Authored-By: Claude Opus 4.6 (1M context) --- 操作说明.md | 164 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 117 insertions(+), 47 deletions(-) diff --git a/操作说明.md b/操作说明.md index 6be3fd2..972a362 100644 --- a/操作说明.md +++ b/操作说明.md @@ -17,7 +17,7 @@ cd C:\Airlabs_Project\AirGate\frontend npm run dev ``` -打开 `http://localhost:5174`，使用 `admin` / `admin123` 登录。 +打开 `http://localhost:5174`，使用 `admin` / `admin123` 登录（首次登录后请立即修改密码）。 ### 2. 配置火山主账号 @@ -35,13 +35,12 @@ npm run dev | 配置项 | 说明 | 建议值 | |--------|------|--------| | 默认告警阶梯(%) | 消费达到额度的百分比时告警 | 50,80,90 | -| 项目默认授权策略 | 添加项目时自动授权的策略 | ArkFullAccess,TOSFullAccess | | 监控间隔(秒) | 定时查询消费的间隔 | 3600（1小时） | | 飞书 Webhook URL | 告警通知地址 | 从飞书群机器人获取 | --- -## 二、日常操作 +## 二、管理员操作 ### 给新部门开通子账号 @@ -51,44 +50,58 @@ npm run dev 2. 填写： - **用户名**：英文，如 `dept_video` - **显示名**：如 `视频部门` - - **火山控制台密码**：填上（对方需要登录火山后台创建方舟 API Key） + - **火山控制台密码**：不填（子账号不需要登录火山控制台） - 其他选填 3. 点 **创建** -4. 弹窗显示 API 密钥 → **立即复制保存**（SecretKey 仅显示一次） +4. 弹窗显示 IAM API 密钥 → **立即复制保存**（SecretKey 仅显示一次） -**步骤 2：在火山控制台创建项目** +**步骤 2：在火山控制台创建项目并开通模型** 1. 登录 `console.volcengine.com`（你的主账号） -2. 左上角项目管理 → 新建项目（如 `team-video-1`） +2. 项目管理 → 新建项目（如 `team-video-1`） +3. 进入方舟平台 → 切到该项目 → 开通 Seedance 2.0 端点 +4. 在该项目下创建方舟 API Key → **复制完整 Key** **步骤 3：在 AirGate 关联项目并授权** 1. 回到 AirGate → 子账号管理 → 找到刚创建的子账号 2. 点 **更多 → 项目管理** 3. 从下拉框选择刚创建的项目 → 点 **添加** -4. 系统自动在项目范围内授权 ArkFullAccess + TOSFullAccess +4. 点项目行上的 **授权** 按钮 → 勾选需要的策略（如 `ArkFullAccess` + `TOSFullAccess`）→ 保存 -**步骤 4：划拨额度** +**步骤 4：录入 API Key** -1. 点子账号的 **划拨** 按钮 -2. 选择「追加额度」，输入金额（如 100000） -3. 填备注（如 `首次划拨`）→ 确认 +1. 左侧菜单 → **API Key 管理** → 点 **录入 API Key** +2. 选择子账号、所属项目 +3. 填写名称/用途、粘贴完整的 API Key +4. 点 **录入** → Key 加密存储 -**步骤 5：告知对方** +**步骤 5：划拨额度** + +1. 子账号管理 → 点子账号的 **划拨** 按钮 +2. 输入金额（如 100000）和备注 → 确认 + +**步骤 6：设置子账号的 AirGate 登录密码** + +1. 子账号管理 → 更多 → **登录密码** +2. 输入密码 → 开启「允许登录」→ 保存 + +**步骤 7：告知对方** 发给对方以下信息： -- 火山控制台登录地址：`https://console.volcengine.com` +- AirGate 登录地址：`http://你的部署地址` +- 登录方式：选择「子账号登录」 - 用户名：`dept_video` - 密码：你设置的密码 -- 登录后选择项目 `team-video-1`，进入方舟平台创建 Seedance 2.0 的 API Key +- 登录后在「我的 API Key」中查看和复制 Key --- ### 给子账号追加/扣减额度 1. 子账号管理 → 找到目标用户 → 点 **划拨** -2. 选择「追加额度」或「扣减额度」 -3. 输入金额和备注 → 确认 +2. 输入正数追加、负数扣减 +3. 填备注 → 确认 > 扣减有保护：总额度不能低于已消费金额 @@ -96,9 +109,18 @@ npm run dev ### 给子账号增加新项目 -1. 先在火山控制台创建新项目 -2. 回到 AirGate → 子账号管理 → 更多 → **项目管理** -3. 从下拉框选择新项目 → 添加（自动授权） +1. 先在火山控制台创建新项目 + 开通模型端点 + 创建 API Key +2. 回到 AirGate → 子账号管理 → 更多 → **项目管理** → 添加项目 +3. 点 **授权** 选择策略 +4. 去 **API Key 管理** 录入新的 Key + +--- + +### 管理子账号的项目级权限 + +1. 子账号管理 → 更多 → **项目管理** +2. 找到目标项目 → 点 **授权** +3. 勾选/取消策略 → 保存（增量更新：只添加新的、移除取消的） --- @@ -106,7 +128,7 @@ npm run dev 1. 子账号管理 → 更多 → **项目管理** 2. 找到目标项目 → 关闭「监测」开关 -3. 该项目的消费不再计入子账号的累计消费（不影响告警和停用判断） +3. 该项目的消费不再计入子账号的累计消费 --- @@ -114,11 +136,20 @@ npm run dev **停用：** 1. 子账号管理 → 更多 → **停用账号** -2. 确认后，子账号的控制台登录和所有 API Key 立即失效 +2. 系统自动执行三步：停用控制台登录 + 停用所有 API Key + 移除所有权限策略 +3. 子账号刷新页面后立即无法操作 **恢复：** 1. 子账号管理 → 更多 → **恢复账号** -2. 确认后，控制台登录和 API Key 立即恢复 +2. 自动恢复控制台登录 + API Key + 权限策略（从停用时的快照恢复） + +--- + +### 查看/管理 API Key + +1. 左侧菜单 → **API Key 管理** +2. 可按子账号、项目筛选 +3. 操作：查看明文 / 启用 / 停用 / 删除 --- @@ -126,41 +157,77 @@ npm run dev 1. 左侧菜单 → **消费监控** 2. 表格展示每个子账号的累计消费、额度、使用率 -3. 点行首的 **展开箭头**，查看该子账号各项目的独立消费 -4. 点 **刷新消费数据** 手动触发一次消费查询 -5. 点 **查看主账号余额** 查看主账号的可用余额 +3. 点行首展开查看各项目的独立消费 +4. 点 **刷新消费数据** 手动触发查询 +5. 点 **查看主账号余额** 查看可用余额 > 消费数据来自火山 Billing API，有 1-2 天延迟 --- -### 查看告警记录 +### 查看告警/操作日志 -1. 左侧菜单 → **告警记录** -2. 可按类型筛选：告警 / 自动停用 / 手动操作 / 错误 +1. 左侧菜单 → **告警记录** — 查看告警和自动停用记录 +2. 左侧菜单 → **系统管理** → **操作日志** — 查看所有操作记录（含类型筛选） --- -### 修改子账号的告警阶梯 +### 管理员账号管理 -1. 子账号管理 → 更多 → **监控配置** -2. 修改告警阶梯百分比（如添加 95%） -3. 开关消费监控 / 额度用尽自动停用 -4. 保存 +1. 左侧菜单 → **系统管理** +2. **修改密码**：修改当前管理员的密码 +3. **管理员管理**（仅超级管理员）：创建新管理员 / 启停 / 重置密码 +4. **操作日志**：查看所有系统操作记录 --- -### 查看/管理子账号的权限策略 +## 三、子账号操作 -1. 子账号管理 → 更多 → **权限策略** -2. 上方可从下拉框选择策略手动附加 -3. 已有策略列表中可点 **移除** +> 子账号使用独立的登录入口，不需要登录火山控制台。 -> 常规情况不需要手动管理权限，添加项目时会自动授权 +### 登录 + +1. 打开 AirGate 登录页面 +2. 切换到 **「子账号登录」** +3. 输入用户名和密码（由管理员提供） + +### 查看我的 API Key + +1. 登录后默认进入 **「我的 API Key」** 页面 +2. 显示管理员分配给你的所有 API Key +3. 点 **查看** 显示完整 Key 明文 → 点 **复制** 复制到剪贴板 +4. Key 状态：启用（可用）/ 停用（不可用，联系管理员） + +### 修改密码 + +1. 左侧菜单 → **修改密码** +2. 输入原密码 + 新密码 → 确认 +3. 修改成功后自动跳转到登录页，需要用新密码重新登录 + +### 使用 API Key 调用服务 + +拿到 API Key 后，直接调用火山方舟的 API： + +```python +import requests + +API_KEY = "你在 AirGate 看到的 Key" +url = "https://ark.cn-beijing.volces.com/api/v3/chat/completions" + +headers = { + "Authorization": f"Bearer {API_KEY}", + "Content-Type": "application/json", +} + +# 调用示例（以 Seedance 2.0 为例） +response = requests.post(url, headers=headers, json={...}) +``` + +> 不需要登录火山控制台，API Key 可以直接使用。 --- -## 三、告警与自动停用机制 +## 四、告警与自动停用机制 ``` 定时任务每小时运行一次 @@ -183,10 +250,11 @@ npm run dev - 每个阶梯只通知一次，不会重复 - 追加或扣减额度后，告警状态自动重置 - 「额度用尽自动停用」可在监控配置中关闭（只告警不停用） +- 停用会同时移除所有权限策略，确保即使有活跃会话也立即失效 --- -## 四、外部系统对接（AirDrama） +## 五、外部系统对接（AirDrama） AirGate 支持通过 API Key 认证供外部系统调用： @@ -199,14 +267,16 @@ curl -H "X-API-Key: 你的密钥" http://localhost:8101/api/v1/iam-users/ curl -H "X-API-Key: 你的密钥" http://localhost:8101/api/v1/billing/overview/ ``` -完整 API 列表见 [README.md](README.md) 或研究报告第 11 章。 +完整 API 列表见研究报告第 11 章。 --- -## 五、注意事项 +## 六、注意事项 1. **消费数据有 1-2 天延迟**：火山 Billing API 的限制，划拨额度时建议预留余量 -2. **SecretKey 只显示一次**：创建子账号时弹窗里的 SecretAccessKey 关掉就没了，务必保存 -3. **项目由你创建**：子账号没有创建项目的权限，需要新项目时在火山控制台创建后在 AirGate 关联 -4. **seaislee 账号不要动**：这是你自己的子账号，监控和自动停用已关闭 -5. **加密密钥不要丢**：`.env` 中的 `AIRGATE_ENCRYPTION_KEY` 丢失后，已存储的火山主账号 AK/SK 无法解密，需要重新配置 +2. **IAM SecretKey 只显示一次**：创建子账号时弹窗里的 SecretAccessKey 关掉就没了 +3. **方舟 API Key 由管理员录入**：火山 API 不返回 Key 明文，需要在火山控制台创建后手动录入 AirGate +4. **子账号不登录火山控制台**：所有操作通过 AirGate 完成，避免权限泄露 +5. **项目由管理员创建**：子账号没有创建项目的权限，需要新项目时联系管理员 +6. **seaislee 账号不要动**：这是你自己的子账号，监控和自动停用已关闭 +7. **加密密钥不要丢**：`.env` 中的 `AIRGATE_ENCRYPTION_KEY` 丢失后，已存储的密钥无法解密