AirGate/操作说明.md

AirGate 操作说明

---

一、首次部署

1. 启动服务

# 后端
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 认证供外部系统调用：

# 在 .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 或研究报告第 11 章。

---

五、注意事项

1. 消费数据有 1-2 天延迟：火山 Billing API 的限制，划拨额度时建议预留余量
2. SecretKey 只显示一次：创建子账号时弹窗里的 SecretAccessKey 关掉就没了，务必保存
3. 项目由你创建：子账号没有创建项目的权限，需要新项目时在火山控制台创建后在 AirGate 关联
4. seaislee 账号不要动：这是你自己的子账号，监控和自动停用已关闭
5. 加密密钥不要丢：.env 中的 AIRGATE_ENCRYPTION_KEY 丢失后，已存储的火山主账号 AK/SK 无法解密，需要重新配置