litellm-gateway/TODO.md

# TODO — LiteLLM Gateway

> 建立时间：2026-04-10
> 负责人：西莉雅 (Sileya)

---

## 背景

### 问题
- MiniMax M2.7 频繁返回 529（服务过载），导致 session 被 terminate
- Agent 的 API Key 存在泄漏风险（直接写在配置里）
- 没有额度管控，agent 滥用无法控制
- 缺少统一日志，无法追踪用量

### 目标
在 OMV（Nas/Proxmox）节点上部署 LiteLLM Gateway，实现：
1. MiniMax API 安全代理（key 集中管理）
2. 模型自动回落（M2.7 → M2.5 → M2.5-Lightning）
3. per-key 额度管控
4. 完整 API 管理接口（用量查询、key 生成/封禁）
5. Sileya Skill 化（通过 API 动态管理）

---

## 部署规划

### 部署节点
- **OMV (Open Media Vault)** — 运行在 NAS 上的 Proxmox 容器
- 或者直接跑在 Nas 本身（推荐，更简单）

### 模型路由策略
```
优先: MiniMax-M2.7
  ↓ 529 / 超时 / 500
备用: MiniMax-M2.5
  ↓ 529 / 超时 / 500
兜底: MiniMax-M2.5-Lightning
```

### 双 Key 隔离
- `sk-sileya-fixed` — 西莉雅的专属 key，指向固定 model group，**不动 config.yaml 就永远不受影响**
- `sk-admin-*` — 管理员 key，可动态管理其他 key

### 热更新策略
| 操作 | 是否需要重启 |
|------|------------|
| `/key/generate` 生成新 key | ❌ 不需要 |
| `/key/block` 封禁 key | ❌ 不需要 |
| `/model/new` 动态加模型 | ❌ 不需要 |
| 改 fallback 策略 / 模型顺序 | ⚠️ 需要（但不频繁，重启 < 5s）|

---

## 待办事项

### P0 — 必须完成（网关可用）
- [ ] **DEPLOY-01**: 在 OMV/Nas 上安装 Python 环境 + pip install litellm
- [ ] **DEPLOY-02**: 配置 `config.yaml`（MiniMax provider + fallback 路由 + virtual key）
- [ ] **DEPLOY-03**: 配置 `.env`（MINIMAX_API_KEY + LITELLM_MASTER_KEY）
- [ ] **DEPLOY-04**: 启动验证 — curl 测试 `/health`
- [ ] **DEPLOY-05**: OpenClaw 接入 — 修改 `openclaw.json` 的 model provider 指向 LiteLLM

### P1 — 管控能力
- [ ] **MGMT-01**: 生成各 agent 的专属 key（`sk-sileya-fixed`、`sk-ligoudan`、`sk-nico`）
- [ ] **MGMT-02**: 配置 per-key RPM 限制（各 agent 独立额度）
- [ ] **MGMT-03**: Sileya Skill — `lite-llm-admin`（用量查询、key 管理接口）
- [ ] **MGMT-04**: 验证 hot reload — 测试 `/key/generate` 不影响 Sileya session

### P2 — 安全加固
- [ ] **SEC-01**: 网络隔离 — LiteLLM 仅内网可访问，Tailscale/ZeroTier 组网
- [ ] **SEC-02**: 确认 Sileya 的 key 配置在 `config.yaml` 固定区域，不参与动态更新
- [ ] **SEC-03**: 审计日志 — 确认所有请求记录到数据库

### P3 — 可选优化
- [ ] **OPT-01**: LiteLLM Dashboard（`:4000/ui`）启用，Web UI 管理
- [ ] **OPT-02**: Prometheus metrics 接入（Grafana 监控）
- [ ] **OPT-03**: 多 provider 预留 — 对接其他 LLM（Claude/GPT）时网关层无需修改

---

## 关键配置

### config.yaml 核心结构
```yaml
model_list:
  - model_name: MiniMax-M2.7
    litellm_params:
      model: minimax/MiniMax-M2.7
      api_key: os.environ/MINIMAX_API_KEY
      api_base: https://api.minimax.io/v1
      rpm: 60

  - model_name: MiniMax-M2.5
    litellm_params:
      model: minimax/MiniMax-M2.5
      api_key: os.environ/MINIMAX_API_KEY
      api_base: https://api.minimax.io/v1
      rpm: 60

  - model_name: MiniMax-M2.5-Lightning
    litellm_params:
      model: minimax/MiniMax-M2.5-Lightning
      api_key: os.environ/MINIMAX_API_KEY
      api_base: https://api.minimax.io/v1
      rpm: 120

router_settings:
  fallback_params: [{"model": ["MiniMax-M2.7", "MiniMax-M2.5", "MiniMax-M2.5-Lightning"]}]
  num_retries: 3
  retry_after: 5
  timeout: 30

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
```

### Sileya Key 专属配置（不参与动态更新）
```yaml
# config.yaml 中的 sileya 专属区
# 此区域修改需要重启，但这种情况极低频
```

---

## API 接口

### 管理 API（admin key）
```
POST /key/generate         — 生成新 key
GET  /key/info?key=sk-xxx  — 查询 key 用量
GET  /spend                — 查询总用量
POST /key/block            — 封禁 key
POST /key/unblock          — 解封 key
POST /model/new            — 动态添加模型（热生效）
```

### 对外 API（agent 使用）
```
POST /v1/chat/completions  — 标准 OpenAI 兼容接口
GET  /health               — 健康检查
```

---

## 目录结构
```
litellm-gateway/
├── README.md
├── TODO.md
├── config.yaml             # 主配置
├── .env.example            # 环境变量模板
├── requirements.txt        # Python 依赖
├── run.sh                  # 启动脚本
└── docs/
    ├── CONFIG_GUIDE.md
    ├── DEPLOYMENT.md
    └── SKILL_INTEGRATION.md
```

---

## 里程碑

- [ ] **M1**: LiteLLM 在 OMV 上跑通，health check 通过
- [ ] **M2**: Sileya 通过 LiteLLM 代理访问 MiniMax，fallback 验证通过
- [ ] **M3**: 所有 agent 迁移到独立 key 体系
- [ ] **M4**: Sileya Skill `lite-llm-admin` 可用，日常管理无需手动操作