b25641cfc6
- Admin section: full workflow from account creation to key entry - Sub-account section: login, view keys, change password, use API - Updated for manual key entry mode and no-console-login architecture - Added alert/auto-disable mechanism description Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
283 lines
8.4 KiB
Markdown
283 lines
8.4 KiB
Markdown
# 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`
|
||
- **显示名**：如 `视频部门`
|
||
- **火山控制台密码**：不填（子账号不需要登录火山控制台）
|
||
- 其他选填
|
||
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：
|
||
|
||
```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 章。
|
||
|
||
---
|
||
|
||
## 六、注意事项
|
||
|
||
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` 丢失后，已存储的密钥无法解密
|