diff --git a/操作说明.md b/操作说明.md new file mode 100644 index 0000000..6be3fd2 --- /dev/null +++ b/操作说明.md @@ -0,0 +1,212 @@ +# AirGate 操作说明 + +--- + +## 一、首次部署 + +### 1. 启动服务 + +```bash +# 后端 +cd C:\Airlabs_Project\AirGate\backend +venv\Scripts\activate +python manage.py runserver 8101 + +# 前端(另一个终端) +cd C:\Airlabs_Project\AirGate\frontend +npm run dev +``` + +打开 `http://localhost:5174`,使用 `admin` / `admin123` 登录。 + +### 2. 配置火山主账号 + +1. 左侧菜单 → **系统设置** +2. 页面下方「火山引擎主账号」→ 点 **添加主账号** +3. 填入主账号的 AccessKey 和 SecretKey(加密存储,不可回显) +4. 点 **测试** 验证密钥有效 + +> AK/SK 获取方式:登录 `console.volcengine.com` → 右上角头像 → 密钥管理 → 新建密钥 + +### 3. 配置全局默认参数 + +在**系统设置**页面上方「全局默认配置」中设置: + +| 配置项 | 说明 | 建议值 | +|--------|------|--------| +| 默认告警阶梯(%) | 消费达到额度的百分比时告警 | 50,80,90 | +| 项目默认授权策略 | 添加项目时自动授权的策略 | ArkFullAccess,TOSFullAccess | +| 监控间隔(秒) | 定时查询消费的间隔 | 3600(1小时) | +| 飞书 Webhook URL | 告警通知地址 | 从飞书群机器人获取 | + +--- + +## 二、日常操作 + +### 给新部门开通子账号 + +**步骤 1:创建子账号** + +1. 左侧菜单 → **子账号管理** → 点 **创建子账号** +2. 填写: + - **用户名**:英文,如 `dept_video` + - **显示名**:如 `视频部门` + - **火山控制台密码**:填上(对方需要登录火山后台创建方舟 API Key) + - 其他选填 +3. 点 **创建** +4. 弹窗显示 API 密钥 → **立即复制保存**(SecretKey 仅显示一次) + +**步骤 2:在火山控制台创建项目** + +1. 登录 `console.volcengine.com`(你的主账号) +2. 左上角项目管理 → 新建项目(如 `team-video-1`) + +**步骤 3:在 AirGate 关联项目并授权** + +1. 回到 AirGate → 子账号管理 → 找到刚创建的子账号 +2. 点 **更多 → 项目管理** +3. 从下拉框选择刚创建的项目 → 点 **添加** +4. 系统自动在项目范围内授权 ArkFullAccess + TOSFullAccess + +**步骤 4:划拨额度** + +1. 点子账号的 **划拨** 按钮 +2. 选择「追加额度」,输入金额(如 100000) +3. 填备注(如 `首次划拨`)→ 确认 + +**步骤 5:告知对方** + +发给对方以下信息: +- 火山控制台登录地址:`https://console.volcengine.com` +- 用户名:`dept_video` +- 密码:你设置的密码 +- 登录后选择项目 `team-video-1`,进入方舟平台创建 Seedance 2.0 的 API Key + +--- + +### 给子账号追加/扣减额度 + +1. 子账号管理 → 找到目标用户 → 点 **划拨** +2. 选择「追加额度」或「扣减额度」 +3. 输入金额和备注 → 确认 + +> 扣减有保护:总额度不能低于已消费金额 + +--- + +### 给子账号增加新项目 + +1. 先在火山控制台创建新项目 +2. 回到 AirGate → 子账号管理 → 更多 → **项目管理** +3. 从下拉框选择新项目 → 添加(自动授权) + +--- + +### 关闭某个项目的监测 + +1. 子账号管理 → 更多 → **项目管理** +2. 找到目标项目 → 关闭「监测」开关 +3. 该项目的消费不再计入子账号的累计消费(不影响告警和停用判断) + +--- + +### 手动停用/恢复子账号 + +**停用:** +1. 子账号管理 → 更多 → **停用账号** +2. 确认后,子账号的控制台登录和所有 API Key 立即失效 + +**恢复:** +1. 子账号管理 → 更多 → **恢复账号** +2. 确认后,控制台登录和 API Key 立即恢复 + +--- + +### 查看消费明细 + +1. 左侧菜单 → **消费监控** +2. 表格展示每个子账号的累计消费、额度、使用率 +3. 点行首的 **展开箭头**,查看该子账号各项目的独立消费 +4. 点 **刷新消费数据** 手动触发一次消费查询 +5. 点 **查看主账号余额** 查看主账号的可用余额 + +> 消费数据来自火山 Billing API,有 1-2 天延迟 + +--- + +### 查看告警记录 + +1. 左侧菜单 → **告警记录** +2. 可按类型筛选:告警 / 自动停用 / 手动操作 / 错误 + +--- + +### 修改子账号的告警阶梯 + +1. 子账号管理 → 更多 → **监控配置** +2. 修改告警阶梯百分比(如添加 95%) +3. 开关消费监控 / 额度用尽自动停用 +4. 保存 + +--- + +### 查看/管理子账号的权限策略 + +1. 子账号管理 → 更多 → **权限策略** +2. 上方可从下拉框选择策略手动附加 +3. 已有策略列表中可点 **移除** + +> 常规情况不需要手动管理权限,添加项目时会自动授权 + +--- + +## 三、告警与自动停用机制 + +``` +定时任务每小时运行一次 + │ + ▼ +遍历每个子账号下所有开启监测的项目 + │ + ▼ +分别查询每个项目的消费 → 累加得出总消费 + │ + ▼ +总消费 / 已划拨额度 = 使用率 + │ + ├── 使用率 ≥ 50% → 飞书告警(仅一次) + ├── 使用率 ≥ 80% → 飞书告警(仅一次) + ├── 使用率 ≥ 90% → 飞书告警(仅一次) + └── 使用率 ≥ 100% → 自动停用子账号 + 飞书告警 +``` + +- 每个阶梯只通知一次,不会重复 +- 追加或扣减额度后,告警状态自动重置 +- 「额度用尽自动停用」可在监控配置中关闭(只告警不停用) + +--- + +## 四、外部系统对接(AirDrama) + +AirGate 支持通过 API Key 认证供外部系统调用: + +```bash +# 在 .env 中设置 +AIRGATE_API_KEY=你的密钥 + +# 调用示例 +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 章。 + +--- + +## 五、注意事项 + +1. **消费数据有 1-2 天延迟**:火山 Billing API 的限制,划拨额度时建议预留余量 +2. **SecretKey 只显示一次**:创建子账号时弹窗里的 SecretAccessKey 关掉就没了,务必保存 +3. **项目由你创建**:子账号没有创建项目的权限,需要新项目时在火山控制台创建后在 AirGate 关联 +4. **seaislee 账号不要动**:这是你自己的子账号,监控和自动停用已关闭 +5. **加密密钥不要丢**:`.env` 中的 `AIRGATE_ENCRYPTION_KEY` 丢失后,已存储的火山主账号 AK/SK 无法解密,需要重新配置