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
监控间隔(秒)	定时查询消费的间隔	3600（1小时）
飞书 Webhook URL	告警通知地址	从飞书群机器人获取

---

二、管理员操作

给新部门开通子账号

步骤 1：创建子账号

1. 左侧菜单 → 子账号管理 → 点 创建子账号
2. 填写：
   • 用户名：英文，如 dept_video
   • 显示名：如 视频部门
   • 火山控制台密码：不填（子账号不需要登录火山控制台）
   • 其他选填
3. 点 创建
4. 弹窗显示 IAM API 密钥 → 立即复制保存（SecretKey 仅显示一次）

步骤 2：在火山控制台创建项目并开通模型

1. 登录 console.volcengine.com（你的主账号）
2. 项目管理 → 新建项目（如 team-video-1）
3. 进入方舟平台 → 切到该项目 → 开通 Seedance 2.0 端点
4. 在该项目下创建方舟 API Key → 复制完整 Key

步骤 3：在 AirGate 关联项目并授权

1. 回到 AirGate → 子账号管理 → 找到刚创建的子账号
2. 点 更多 → 项目管理
3. 从下拉框选择刚创建的项目 → 点 添加
4. 点项目行上的 授权 按钮 → 勾选需要的策略（如 ArkFullAccess + TOSFullAccess）→ 保存

步骤 4：录入 API Key

1. 左侧菜单 → API Key 管理 → 点 录入 API Key
2. 选择子账号、所属项目
3. 填写名称/用途、粘贴完整的 API Key
4. 点 录入 → Key 加密存储

步骤 5：划拨额度

1. 子账号管理 → 点子账号的 划拨 按钮
2. 输入金额（如 100000）和备注 → 确认

步骤 6：设置子账号的 AirGate 登录密码

1. 子账号管理 → 更多 → 登录密码
2. 输入密码 → 开启「允许登录」→ 保存

步骤 7：告知对方

发给对方以下信息：

• AirGate 登录地址：http://你的部署地址
• 登录方式：选择「子账号登录」
• 用户名：dept_video
• 密码：你设置的密码
• 登录后在「我的 API Key」中查看和复制 Key

---

给子账号追加/扣减额度

1. 子账号管理 → 找到目标用户 → 点 划拨
2. 输入正数追加、负数扣减
3. 填备注 → 确认

扣减有保护：总额度不能低于已消费金额

---

给子账号增加新项目

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. 操作日志：查看所有系统操作记录

---

三、子账号操作

子账号使用独立的登录入口，不需要登录火山控制台。

登录

1. 打开 AirGate 登录页面
2. 切换到 「子账号登录」
3. 输入用户名和密码（由管理员提供）

查看我的 API Key

1. 登录后默认进入 「我的 API Key」 页面
2. 显示管理员分配给你的所有 API Key
3. 点 查看 显示完整 Key 明文 → 点 复制 复制到剪贴板
4. Key 状态：启用（可用）/ 停用（不可用，联系管理员）

修改密码

1. 左侧菜单 → 修改密码
2. 输入原密码 + 新密码 → 确认
3. 修改成功后自动跳转到登录页，需要用新密码重新登录

使用 API Key 调用服务

拿到 API Key 后，直接调用火山方舟的 API：

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 可以直接使用。

---

四、告警与自动停用机制

定时任务每小时运行一次
    │
    ▼
遍历每个子账号下所有开启监测的项目
    │
    ▼
分别查询每个项目的消费 → 累加得出总消费
    │
    ▼
总消费 / 已划拨额度 = 使用率
    │
    ├── 使用率 ≥ 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 列表见研究报告第 11 章。

---

六、注意事项

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 丢失后，已存储的密钥无法解密