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
   • 显示名：如 视频部门
   • 手机号：可选
   • 火山控制台密码：需包含大小写字母、数字和特殊字符，8位以上（火山密码策略要求）
3. 点 创建
4. 系统自动在火山创建 IAM 用户，并自动生成 AirGate_Deny_{username} 策略用于项目隔离

2. 权限管理

统一权限管理页面，一页展示所有权限信息：

1. 子账号管理 → 找到目标用户 → 点 权限管理
2. 页面分区：
   • 全局策略：当前用户挂载的全局策略列表（实时从火山查询）
   • 项目级策略：当前用户在各项目下挂载的策略（实时从火山查询）
   • 关联项目：管理用户关联的火山项目（添加/移除）
   • 添加/移除策略：为用户附加或移除 IAM 策略
3. 添加关联项目时自动更新 Deny 策略（将新项目加入白名单）
4. 移除关联项目时自动更新 Deny 策略（将项目从白名单移除）

3. 额度划拨

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 加密存储

API Key 采用手动录入方式。管理员在火山控制台创建 Key 后，将明文录入 AirGate。 原因：火山 CreateApiKey API 不返回 Key 明文，ListApiKeys 只返回脱敏值。

操作：查看明文 / 启用 / 停用 / 删除，可按子账号、项目筛选。

9. 系统管理

1. 修改密码：左侧菜单 → 系统管理 → 修改密码
2. 管理员管理（仅超级管理员）：创建新管理员 / 启停 / 重置密码
3. 操作日志：查看所有系统操作记录（含类型筛选）

---

三、Deny策略说明

原理

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. 打开 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 章。

---

七、火山API限制

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