AirGate/操作说明.md

# 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 |
| 监控间隔(秒) | 定时查询消费的间隔 | 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：

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

---

## 五、告警与自动停用机制

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