From f76ab6bd97c651dca4272eb1e9f5fdcc54a319fc Mon Sep 17 00:00:00 2001
From: seaislee1209 <seaislee129@gmail.com>
Date: Thu, 19 Mar 2026 16:59:04 +0800
Subject: [PATCH] docs: add README with system overview and usage guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ebb2389
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# AirGate
+
+火山引擎 IAM 子账号管控平台。独立部署，带管理界面，可通过 API 对接其他系统。
+
+## 解决什么问题
+
+火山引擎的 IAM 子账号没有消费限额功能，子账号可以不受限地花光主账号余额。AirGate 通过额度划拨 + 阶梯告警 + 自动停用，实现对子账号的消费管控。
+
+## 核心功能
+
+| 功能 | 说明 |
+|------|------|
+| **子账号管理** | 创建 / 同步 / 停用 / 恢复 IAM 子账号 |
+| **权限策略** | 查看 / 附加 / 移除 IAM 策略（Ark、TOS 等） |
+| **额度划拨** | 主账号给子账号划拨额度，支持追加和扣减 |
+| **阶梯告警** | 消费达到额度的 50% / 80% / 90% 时飞书通知 |
+| **自动停用** | 消费达到额度 100% 时自动停用子账号 |
+| **消费监控** | 定时查询 Billing API，按项目维度追踪消费 |
+| **密钥安全** | 主账号 AK/SK 加密存储（AES-256），界面脱敏显示 |
+
+## 使用前提
+
+- 子账号的资源需要放在**独立的火山项目**下，消费才能按项目准确追踪
+- 火山账单数据有 **1-2 天延迟**，划拨额度时建议预留余量
+
+## 本地运行
+
+```bash
+# 1. 复制环境变量
+cp .env.example .env
+# 编辑 .env，填入 AIRGATE_ENCRYPTION_KEY（生成方式见文件内注释）
+
+# 2. 启动后端
+cd backend
+python -m venv venv
+venv\Scripts\activate        # Windows
+pip install -r requirements.txt
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py runserver 8101
+
+# 3. 启动前端（另一个终端）
+cd frontend
+npm install
+npm run dev
+```
+
+打开 `http://localhost:5174`，登录后：
+
+1. **系统设置** → 添加火山主账号（填 AK/SK，加密存储）
+2. **子账号管理** → 同步已有用户 或 创建新子账号
+3. 给子账号点 **划拨** → 设置额度
+4. 点 **更多 → 监控配置** → 选关联项目 + 设告警阶梯
+
+## Docker 部署
+
+```bash
+docker-compose up -d
+```
+
+- 前端：`http://localhost:5174`
+- 后端：`http://localhost:8101`
+
+## 外部系统对接
+
+AirDrama 等外部系统可通过 API Key 调用 AirGate 接口：
+
+```bash
+curl -H "X-API-Key: 你的key" http://airgate:8101/api/v1/iam-users/
+```
+
+在 `.env` 中设置 `AIRGATE_API_KEY` 启用。
+
+## 技术栈
+
+- 后端：Django 4.2 + DRF + APScheduler
+- 前端：Vue 3 + Element Plus
+- 加密：cryptography (Fernet)
+- 部署：Docker + Nginx