# openteam · 大模型中转站

自托管的 LLM API 中转网关，功能对标 OpenRouter / one-api：统一 OpenAI 与 Anthropic 协议入口，背后对接多个上游渠道，内置用户体系、API Key 管理与用量计费。

> 规划文档见 [PLANNING.md](./PLANNING.md)。当前进度：**M0-M2 + M4-M5 + M3 收尾已完成**（基建 + 用户/密钥/核心代理 + 前端 MVP + 管理后台基础 + 三协议互转 + 渠道体系 + 限流/配额 + 前端骨架屏）。

## 功能（当前）

- **代理端点**（Bearer API Key）
  - `POST /v1/chat/completions` — OpenAI Chat（非流式 + 流式 SSE）
  - `POST /v1/responses` — OpenAI Responses API（非流式 + 流式事件）
  - `POST /v1/messages` — Anthropic Messages API（非流式 + 流式事件）
  - `GET /v1/models` — 可用模型列表
  - **三协议互转**：客户端协议 × 渠道协议不匹配时自动转换（如 Chat 调用 Claude、Messages 调用 OpenAI、Responses 调用 Claude），流式逐事件转换；协议匹配时直通
  - 错误按客户端协议返回（OpenAI 格式 / Anthropic 格式）
- **渠道体系**：按模型绑定选渠道 + 加权负载均衡；每渠道并发信号量（满载溢出）；后台健康检查（连续失败进 cooldown、恢复放回）；可安全重试的失败自动故障转移（网络错误/429/5xx/超时且未写出响应头）
- **限流/配额**（内存计数）：密钥级每日请求数 / Token 数配额、用户级每秒速率（`OT_RATELIMIT_USER_RPS`）；超限返回 429
- **前端**：Dashboard / 管理总览骨架屏加载态
- **用户体系**：注册（开放/邀请码可切换，管理后台可改）、登录（JWT access + HttpOnly refresh cookie）、argon2id 密码
- **API Key**：`sk-ot-` 48 位 base62，仅存 SHA-256 哈希，明文一次性展示；支持限额/过期/白名单字段
- **用量计费**：请求级 `usage_logs` 异步批量落库，按模型价格扣减余额，日粒度预聚合（`usage_daily`）
- **管理 API**：渠道 CRUD + 连通测试 + 模型导入、模型管理 + 定价 + 渠道绑定、用户管理、全局用量/统计、系统配置
- **前端**（Vue3 + Tailwind，taste-skill 设计，深色优先）
  - Landing / 登录 / 注册
  - 控制台：Dashboard（余额/用量/趋势图）、API Keys、用量明细
  - 管理后台：运营总览、渠道管理、模型与定价、用户管理、系统配置
- **后端**：Go + Gin + GORM，SQLite（开发）/ PostgreSQL（生产）

> 剩余：M6 充值（待定）与 M3 收尾（限流、骨架屏）。

## 快速开始（开发）

前置：Go 1.23+。

```bash
# 1. 配置（复制并修改，至少设置上游 key）
cp .env.example .env

# 2. 启动后端（SQLite 起步，无需数据库）
cd server && go run ./cmd/server
# 默认管理员 admin / admin123（生产务必修改）

# 3. 用 mock 上游联调（无需真实 key，另开终端）
make mock-upstream   # :9000 起一个模拟 OpenAI 服务
```

`.env` 中 `OT_PROXY_UPSTREAM_KEY` / `OT_PROXY_UPSTREAM_BASE_URL` 指向 mock 上游时，服务首次启动会自动创建默认渠道与示例模型。

### 冒烟测试（curl）

```bash
# 注册 → 登录 → 建 key
curl -s -X POST localhost:8080/api/v1/auth/register -H 'Content-Type: application/json' \
  -d '{"username":"alice","email":"a@b.com","password":"password123"}'
TOKEN=$(curl -s -X POST localhost:8080/api/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"password123"}' | jq -r .data.access_token)
KEY=$(curl -s -X POST localhost:8080/api/v1/keys -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"dev"}' | jq -r .data.key)

# 对话（非流式 + 流式）
curl -s localhost:8080/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"stream":false}'
curl -N localhost:8080/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"stream":true}'

# 用量
curl -s localhost:8080/api/v1/usage/summary -H "Authorization: Bearer $TOKEN"
curl -s "localhost:8080/api/v1/usage/logs?page_size=5" -H "Authorization: Bearer $TOKEN"
```

### 前端（开发）

```bash
cd web && pnpm i && pnpm dev   # http://localhost:5173（/api、/v1 代理到 8080）
```

### 测试

```bash
cd server && go test ./...
cd web && pnpm build           # vue-tsc 类型检查 + 构建
```

## 仓库结构

```
server/                     # Go 后端
  cmd/server/               # 入口
  internal/
    config/                 # viper + env（OT_ 前缀）
    store/                  # GORM models + 连接
    pkg/                    # apikey / crypto / jwt / resp
    api/                    # 管理 API（认证、用户、密钥、用量、渠道/模型/管理后台）
    proxy/                  # 代理网关（鉴权、直通、流式、记账）
    channel/                # 渠道选择与密钥解密
    usage/                  # 异步记账
web/                        # Vue3 前端（Tailwind，taste-skill 设计 tokens）
  src/
    views/                  # Landing / 登录注册 / console / admin
    components/             # ui（Button/Input/Modal/Badge/Toast/TrendChart）+ layout
    stores/ · api/ · router/ · lib/
scripts/mockupstream/       # mock 上游（联调）
deploy/                     # Docker 部署（后续里程碑）
```