docs: add operations guide (操作说明.md)

Step-by-step guide covering: initial setup, creating sub-accounts,
project authorization flow, quota management, alert mechanism,
external API integration, and important notes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

操作说明.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 无法解密，需要重新配置