docs: restructure README + add DESIGN.md (二开白盒手册)
README 重写为分层结构：架构速览 + 快速开始 + 按主题分组的配置表 + API 参考 + 常用场景 + 升级注意 + 故障排查 + 二开入口。相比旧版： 更好导航，破坏性改动显式标注升级路径，故障排查能覆盖生产常见坑。 DESIGN.md 是全新的工程手册，覆盖：项目目标/非目标、组件数据流、 模块职责表、6 个核心流程的 ASCII 图解（启动、非流式/流式 chat、 子进程 + LSP、bundle、自动登录、关闭）、11 条关键设计决策 （每条带问题/方案/权衡/未选其他方案原因）、扩展指引（常见需求 → 改哪些文件）、 已知问题 / TODO、完整迭代历程（M1~M4 + M3 性能 bug 根因）、 Lingma LSP 协议速查。 目标：新成员或几个月后的自己能在一天内理清全项目。 Made-with: Cursor
This commit is contained in:
GitHub Actions
525
README.md
525
README.md
@@ -1,282 +1,353 @@
|
||||
# Lingma OpenAI Gateway
|
||||
|
||||
把本地 Lingma 能力封装为 OpenAI 兼容接口，支持：
|
||||
把本地 Lingma 插件封装成 OpenAI 兼容接口。任何能调 OpenAI 的客户端（Cursor、Dify、LangChain、curl…）都能直接接入。
|
||||
|
||||
- `GET /v1/models`
|
||||
- `POST /v1/chat/completions`
|
||||
- `stream=true`（SSE）
|
||||
- Bearer API Key 鉴权
|
||||
**支持：** `GET /v1/models` / `POST /v1/chat/completions`（含 SSE 流式） / Bearer 鉴权 / Prometheus / 多账号实例池 / 会话复用 / 免浏览器登录态注入。
|
||||
|
||||
## 1. 准备目录
|
||||
> 想看架构、模块划分、设计决策、二开路线图 → 直接读 [`DESIGN.md`](./DESIGN.md)。
|
||||
|
||||
```bash
|
||||
mkdir -p data
|
||||
---
|
||||
|
||||
## 架构速览
|
||||
|
||||
```
|
||||
┌─────────────┐ OpenAI 协议 ┌─────────────────────────────────────────┐
|
||||
│ 任意客户端 │ ───────────▶ │ FastAPI (app/main.py) │
|
||||
│ (curl/ │ │ ├─ auth_guard / admin_guard │
|
||||
│ Cursor/ │ │ ├─ chat_guard (InFlightGuard 背压) │
|
||||
│ Dify…) │ │ ├─ SessionCache (LRU+TTL, KV 复用) │
|
||||
└─────────────┘ │ └─ StatsCollector + Prometheus │
|
||||
└────────────────┬────────────────────────┘
|
||||
│ 选实例 (least-in-flight + affinity)
|
||||
┌────────────────▼────────────────────────┐
|
||||
│ LingmaPool (app/lingma_pool.py) │
|
||||
│ ├─ inst-0 inst-1 inst-N … │
|
||||
│ └─ 启动前自动 restore session bundle │
|
||||
└────────────────┬────────────────────────┘
|
||||
│
|
||||
┌───────────────────────┼───────────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
|
||||
│ LingmaGatewayClient│ │ … │ │ … │
|
||||
│ (LSP over WS) │ │ │ │ │
|
||||
│ ├─ Popen (PID管理) │ │ │ │ │
|
||||
│ ├─ reconnect loop │ │ │ │ │
|
||||
│ └─ ws://:PORT │ │ │ │ │
|
||||
└──────────┬─────────┘ └────────────────────┘ └────────────────────┘
|
||||
│ spawn + ws
|
||||
┌──────────▼─────────┐
|
||||
│ Lingma 二进制 │
|
||||
│ --workDir /… │
|
||||
└────────────────────┘
|
||||
```
|
||||
|
||||
说明：
|
||||
---
|
||||
|
||||
- 启动时会自动获取最新插件并提取 `Lingma` 到 `data/bin`。
|
||||
- 默认通过 VSCode Marketplace 查询最新版本，再下载对应 VSIX。
|
||||
- 登录态与运行数据统一写入 `data/.lingma`。
|
||||
|
||||
## 2. 配置环境变量
|
||||
## 一、快速开始
|
||||
|
||||
```bash
|
||||
git clone <repo>
|
||||
cd lingma-openai-gateway
|
||||
cp .env.example .env
|
||||
# 至少填 API_KEYS + LINGMA_USERNAME + LINGMA_PASSWORD（或 session bundle）
|
||||
mkdir -p data secrets
|
||||
docker compose up -d --build
|
||||
docker compose logs -f # 看到 "Uvicorn running on..." 就 OK
|
||||
```
|
||||
|
||||
至少修改：
|
||||
冒烟测试：
|
||||
|
||||
- `API_KEYS`
|
||||
- `LINGMA_USERNAME`
|
||||
- `LINGMA_PASSWORD`
|
||||
```bash
|
||||
API_KEY=$(grep '^API_KEYS=' .env | cut -d= -f2 | cut -d, -f1)
|
||||
curl -s http://127.0.0.1:8317/healthz
|
||||
curl -s http://127.0.0.1:8317/v1/models -H "Authorization: Bearer $API_KEY"
|
||||
curl -s http://127.0.0.1:8317/v1/chat/completions \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"org_auto","messages":[{"role":"user","content":"hi"}]}'
|
||||
```
|
||||
|
||||
如果你的 Lingma 路径不同，修改：
|
||||
---
|
||||
|
||||
- `LINGMA_BIN`
|
||||
## 二、配置参考
|
||||
|
||||
可选（企业专属域）：
|
||||
`.env.example` 是权威说明，这里按主题分组。
|
||||
|
||||
- `DEDICATED_DOMAIN_URL`
|
||||
### 2.1 核心
|
||||
|
||||
### `.env` 字段说明（简版）
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `HOST` / `PORT` | `0.0.0.0` / `8317` | 网关监听地址与端口 |
|
||||
| `API_KEYS` | — | Bearer key，多个逗号分隔；**留空则 /v1/\* 无鉴权**，启动会 warn |
|
||||
| `LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR`，日志为结构化 JSON，含 `request_id` |
|
||||
| `DEFAULT_MODEL` | `org_auto` | 模型无法映射时兜底 |
|
||||
| `DEFAULT_ASK_MODE` | `chat` | `chat` 或 `agent`（传 `model: "agent"` 时自动切） |
|
||||
| `DEDICATED_DOMAIN_URL` | — | 企业专属域（可空） |
|
||||
|
||||
- `HOST`：网关监听地址（通常 `0.0.0.0`）
|
||||
- `PORT`：网关监听端口（外部调用端口）
|
||||
- `API_KEYS`：Bearer Key，多个用逗号分隔
|
||||
- `LINGMA_BIN`：容器内 Lingma 路径
|
||||
- `LINGMA_SOURCE_TYPE`：二进制来源（`marketplace`/`vsix`）
|
||||
- `LINGMA_MARKETPLACE_PUBLISHER`：Marketplace 发布者
|
||||
- `LINGMA_MARKETPLACE_EXTENSION`：Marketplace 扩展名
|
||||
- `LINGMA_VSIX_URL`：VSIX 下载地址（最新优先）
|
||||
- `LINGMA_BOOTSTRAP_ALWAYS`：启动时是否总尝试刷新 Lingma
|
||||
- `LINGMA_FORCE_REFRESH`：是否强制刷新（忽略本地缓存）
|
||||
- `LINGMA_WORK_DIR`：Lingma 工作目录（登录与会话数据）
|
||||
- `LINGMA_SOCKET_PORT`：Lingma 本地 WS 端口
|
||||
- `LINGMA_STARTUP_TIMEOUT`：Lingma 启动等待秒数
|
||||
- `LINGMA_RPC_TIMEOUT`：单次 RPC 超时秒数
|
||||
- `DEFAULT_MODEL`：默认模型（无法映射时兜底）
|
||||
- `DEFAULT_ASK_MODE`：默认模式（`chat`/`agent`）
|
||||
- `DEDICATED_DOMAIN_URL`：企业专属域（可留空）
|
||||
- `AUTO_LOGIN_ENABLED`：未登录时自动登录开关
|
||||
- `AUTO_LOGIN_HEADLESS`：自动登录是否无头浏览器
|
||||
- `AUTO_LOGIN_TIMEOUT`：自动登录超时秒数
|
||||
- `AUTO_LOGIN_MAX_RETRY`：自动登录重试次数
|
||||
- `LINGMA_USERNAME`：Lingma 登录用户名
|
||||
- `LINGMA_PASSWORD`：Lingma 登录密码
|
||||
- `METRICS_TOKEN`：`/metrics` 独立鉴权 token（留空则 `API_KEYS` 也可访问；两者皆空时 `/metrics` 默认 503，除非显式开 `METRICS_PUBLIC=true`）
|
||||
- `METRICS_PUBLIC`：显式把 `/metrics` 设为公开，仅在私网采集器场景使用（默认 `false`）
|
||||
- `ADMIN_TOKEN`：`/internal/*` 管理端点独立鉴权 token（留空则退化为 `API_KEYS`）。生产环境建议单独配置，这样轮换 `API_KEYS` 不需要重新颁发 session bundle 导出权限
|
||||
- `LOG_LEVEL`：日志级别（默认 `INFO`，输出结构化 JSON，包含 `request_id`）
|
||||
- `GATEWAY_MAX_IN_FLIGHT`：`/v1/chat/completions` 并发上限（默认 4，`<=0` 表示不限流）
|
||||
- `GATEWAY_QUEUE_TIMEOUT_SEC`：排队等待超时秒数（默认 30，超过后直接 429 + `Retry-After`）
|
||||
- `LINGMA_ACCOUNTS`：多账号实例池，格式 `u1:p1,u2:p2` 或 JSON 数组；配置后每个账号起一个独立 Lingma 子进程
|
||||
- `LINGMA_INSTANCE_COUNT`：实例数（默认等于账号数；显式指定且不足时账号会循环复用）
|
||||
- `SESSION_REUSE_ENABLED`：多轮对话复用上游 sessionId（默认 `true`）。命中时只把最新一条 user 消息发给 Lingma，命中上游 KV cache，显著降低第 2 轮及以后的首 token 延迟
|
||||
- `SESSION_CACHE_MAX_ENTRIES`：会话缓存容量（LRU，默认 256）
|
||||
- `SESSION_CACHE_TTL_SEC`：会话缓存 TTL 秒数（默认 1800；超时自动失效，避免复用到已被 Lingma 回收的 session）
|
||||
- `LINGMA_SESSION_BUNDLE` / `LINGMA_SESSION_BUNDLE_FILE`：已登录态注入，跳过 Playwright。具体见下方"跳过自动登录"章节
|
||||
### 2.2 权限分层（生产建议全配）
|
||||
|
||||
### `.env` 最小必填示例
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `ADMIN_TOKEN` | — | `/internal/*` 专属 token；未配置时 fallback 到 `API_KEYS`（兼容）；都为空 → 503 |
|
||||
| `METRICS_TOKEN` | — | `/metrics` 专属 token；未配置时 fallback 到 `API_KEYS` |
|
||||
| `METRICS_PUBLIC` | `false` | 显式公开 `/metrics`（仅用于私网采集器） |
|
||||
|
||||
> `ADMIN_TOKEN` / `METRICS_TOKEN` / `API_KEYS` 三者都为空时，`/metrics` 和 `/internal/*` 会返回 503（拒绝裸奔）。
|
||||
|
||||
### 2.3 并发与背压
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `GATEWAY_MAX_IN_FLIGHT` | `4` | 并发上限；`<=0` 表示不限 |
|
||||
| `GATEWAY_QUEUE_TIMEOUT_SEC` | `30` | 排队超时；超时直接返回 `429 + Retry-After` |
|
||||
|
||||
### 2.4 Lingma 进程
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `LINGMA_BIN` | `/app/data/bin/Lingma` | 容器内二进制路径 |
|
||||
| `LINGMA_SOURCE_TYPE` | `marketplace` | `marketplace` 或 `vsix` |
|
||||
| `LINGMA_MARKETPLACE_PUBLISHER` | `Alibaba-Cloud` | Marketplace 发布者 |
|
||||
| `LINGMA_MARKETPLACE_EXTENSION` | `tongyi-lingma` | Marketplace 扩展名 |
|
||||
| `LINGMA_VSIX_URL` | 官方地址 | 兜底 VSIX 下载地址 |
|
||||
| `LINGMA_BOOTSTRAP_ALWAYS` | `true` | 启动时总是尝试刷新二进制 |
|
||||
| `LINGMA_FORCE_REFRESH` | `false` | 强制忽略本地缓存重新下载 |
|
||||
| `LINGMA_WORK_DIR` | `/app/data/.lingma/vscode/sharedClientCache` | 登录态/缓存所在目录 |
|
||||
| `LINGMA_SOCKET_PORT` | `36510` | 单实例模式下的 Lingma WS 端口 |
|
||||
| `LINGMA_STARTUP_TIMEOUT` | `40` | 启动超时秒 |
|
||||
| `LINGMA_RPC_TIMEOUT` | `30` | 单次 RPC 超时秒 |
|
||||
|
||||
### 2.5 多账号 / 多实例池
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `LINGMA_ACCOUNTS` | — | `u1:p1,u2:p2` 或 JSON 数组；配置后每个账号 = 一个独立 Lingma 子进程 |
|
||||
| `LINGMA_INSTANCE_COUNT` | 账号数 | 显式指定实例数；不足账号循环复用并打 warn |
|
||||
| `LINGMA_USERNAME` / `LINGMA_PASSWORD` | — | 单实例兼容模式（仅 `LINGMA_ACCOUNTS` 为空时生效） |
|
||||
|
||||
### 2.6 会话复用（KV cache 优化）
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `SESSION_REUSE_ENABLED` | `true` | 多轮对话命中时只发增量 user 消息 + 复用上游 `sessionId` |
|
||||
| `SESSION_CACHE_MAX_ENTRIES` | `256` | LRU 容量 |
|
||||
| `SESSION_CACHE_TTL_SEC` | `1800` | TTL（秒），避免命中已回收的 session |
|
||||
|
||||
### 2.7 登录态注入（跳过 Playwright）
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `LINGMA_SESSION_BUNDLE` | — | base64 格式的 bundle（inline，适合短字符串） |
|
||||
| `LINGMA_SESSION_BUNDLE_FILE` | — | bundle 文件路径（推荐，避免 env 过长） |
|
||||
|
||||
### 2.8 自动登录
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `AUTO_LOGIN_ENABLED` | `true` | 未登录时自动启 Playwright |
|
||||
| `AUTO_LOGIN_HEADLESS` | `true` | 无头浏览器 |
|
||||
| `AUTO_LOGIN_TIMEOUT` | `180` | 登录超时秒 |
|
||||
| `AUTO_LOGIN_MAX_RETRY` | `2` | 登录失败重试次数 |
|
||||
|
||||
---
|
||||
|
||||
## 三、API 参考
|
||||
|
||||
### 3.1 公共（`API_KEYS`）
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/healthz` | 免鉴权；返回 `ok` / `pool_size` / `pool_ready` / 每实例状态 |
|
||||
| GET | `/v1/models` | OpenAI 兼容；`id` 是 Lingma 原 key，`name` 是可读名 |
|
||||
| POST | `/v1/chat/completions` | OpenAI 兼容；`stream=true` 走 SSE；`model: "agent"` 切 agent 模式 |
|
||||
|
||||
**chat 请求示例（非流式）**
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8317/v1/chat/completions \
|
||||
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
|
||||
-d '{"model":"dashscope_qmodel","messages":[{"role":"user","content":"你好"}]}'
|
||||
```
|
||||
|
||||
**chat 请求示例（流式 + usage）**
|
||||
|
||||
```bash
|
||||
curl -N http://127.0.0.1:8317/v1/chat/completions \
|
||||
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"dashscope_qmodel",
|
||||
"stream":true,
|
||||
"stream_options":{"include_usage":true},
|
||||
"messages":[{"role":"user","content":"介绍一下你自己"}]
|
||||
}'
|
||||
```
|
||||
|
||||
### 3.2 观测（`METRICS_TOKEN` 或 `API_KEYS`）
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/metrics` | Prometheus 文本；含池每实例 gauge、并发、session cache 命中率、token 计数 |
|
||||
|
||||
### 3.3 管理（`ADMIN_TOKEN` 或 fallback 到 `API_KEYS`）
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/internal/stats` | JSON：`stats` + `concurrency` + `pool` + `session_cache` |
|
||||
| GET | `/internal/auto-login/status` | 每实例登录态与 auto_login 状态 |
|
||||
| POST | `/internal/auto-login/start?instance=inst-0` | 主动触发某实例登录（可不传，由 pool.pick 选） |
|
||||
| POST | `/internal/session/export?instance=inst-0` | 把已登录实例的 cache 打包成 base64 bundle |
|
||||
| GET | `/internal/models/raw?instance=inst-0` | Lingma 原始 `config/queryModels` 响应（displayName / isReasoning / isVl 等） |
|
||||
|
||||
---
|
||||
|
||||
## 四、常用场景
|
||||
|
||||
### 4.1 多账号池
|
||||
|
||||
```env
|
||||
PORT=8317
|
||||
API_KEYS=sk-your-api-key
|
||||
LINGMA_USERNAME=your-username
|
||||
LINGMA_PASSWORD=your-password
|
||||
LINGMA_BIN=/app/data/bin/Lingma
|
||||
LINGMA_WORK_DIR=/app/data/.lingma/vscode/sharedClientCache
|
||||
LINGMA_SOURCE_TYPE=marketplace
|
||||
LINGMA_MARKETPLACE_PUBLISHER=Alibaba-Cloud
|
||||
LINGMA_MARKETPLACE_EXTENSION=tongyi-lingma
|
||||
LINGMA_VSIX_URL=https://tongyi-code.oss-cn-hangzhou.aliyuncs.com/vscode/tongyi-lingma-latest.vsix
|
||||
DEDICATED_DOMAIN_URL=
|
||||
LINGMA_ACCOUNTS=user1:pass1,user2:pass2,user3:pass3
|
||||
# LINGMA_INSTANCE_COUNT=3 # 不写默认=账号数
|
||||
```
|
||||
|
||||
### 数据目录说明
|
||||
- 每个账号一个独立 Lingma 子进程 + 独立 `workDir`（`data/.lingma/pool/inst-<i>/`）。
|
||||
- 路由：同 `user` 字段或同 system prompt 的请求**粘性**分到同一实例；其他按**最小在途**分配。
|
||||
- 一个实例挂掉不影响整体，`/healthz.pool_ready` 下降，自动重连。
|
||||
|
||||
- 本项目所有持久化数据都在 `./data`：
|
||||
- `data/bin/Lingma`：自动提取的 Lingma 二进制
|
||||
- `data/.lingma/...`：Lingma 登录态、缓存、日志（单实例模式）
|
||||
- `data/.lingma/pool/inst-<i>/...`：多实例模式下每个实例独立的登录态/缓存
|
||||
### 4.2 跳过 Playwright（session bundle）
|
||||
|
||||
### 多实例池（方案乙：多账号）
|
||||
|
||||
启用方式：在 `.env` 里配置 `LINGMA_ACCOUNTS=u1:p1,u2:p2`，重启容器即可。
|
||||
|
||||
- 每个账号对应一个独立 Lingma 子进程，各自独立登录、独立 workDir。
|
||||
- 路由策略：同一 `user` 字段或同一 system prompt 的请求粘性路由到同一实例；其余按 least-in-flight 分配。
|
||||
- 一个实例挂了/断连不影响整体，`/healthz` 汇报 `pool_ready` 计数。
|
||||
- `/internal/stats.pool` 按实例粒度暴露状态，`/metrics` 增加 `gateway_pool_instance_in_flight{name}` / `gateway_pool_instance_ready{name}`。
|
||||
- 未配置 `LINGMA_ACCOUNTS` 时自动退化为单实例模式（沿用 `LINGMA_USERNAME/LINGMA_PASSWORD`），向下兼容。
|
||||
|
||||
### 跳过自动登录（session bundle 注入）
|
||||
|
||||
Playwright 登录偶尔会因为反爬虫策略失败。如果你已经有一个登录好的 Lingma
|
||||
workDir（本项目任意历史部署、或 VSCode 插件的 shared cache），可以直接把那
|
||||
份登录态导出成 "bundle" 注入到新的部署，完全跳过浏览器。
|
||||
|
||||
**导出**（在一个已登录的 gateway 上执行）：
|
||||
**从已登录实例导出：**
|
||||
|
||||
```bash
|
||||
curl -sS -X POST \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN" \
|
||||
"http://host:port/internal/session/export" \
|
||||
| jq -r '.bundle_b64' > lingma-session.b64
|
||||
| jq -r '.bundle_b64' > secrets/lingma-session.b64
|
||||
chmod 600 secrets/lingma-session.b64
|
||||
```
|
||||
|
||||
可选 `?instance=inst-0` 指定从哪个实例导出（多实例场景）。
|
||||
|
||||
**注入**（新部署的 `.env` 三选一）：
|
||||
**在新部署注入（选一种）：**
|
||||
|
||||
```env
|
||||
# 方式 1：直接塞 base64
|
||||
LINGMA_SESSION_BUNDLE=H4sIAAAA...
|
||||
|
||||
# 方式 2：从文件读（推荐，避免 env 过长）
|
||||
# 文件注入（推荐）—— 需要在 docker-compose.yml 挂载 secrets 目录
|
||||
LINGMA_SESSION_BUNDLE_FILE=/secrets/lingma-session.b64
|
||||
|
||||
# 方式 3：多账号模式，每个账号独立 bundle（JSON 模式）
|
||||
# 或 inline（适合小 bundle）
|
||||
LINGMA_SESSION_BUNDLE=H4sIAAAA...
|
||||
|
||||
# 多账号 JSON 模式，每账号独立 bundle
|
||||
LINGMA_ACCOUNTS=[
|
||||
{"username":"u1","password":"p1","session_bundle_file":"/secrets/u1.b64"},
|
||||
{"username":"u2","password":"p2","session_bundle":"H4sIAAAA..."}
|
||||
]
|
||||
```
|
||||
|
||||
**行为**：
|
||||
**行为保证：**
|
||||
|
||||
- bundle 只在目标 workDir **没有** 已有登录态（即 `cache/user` 为空或不存在）时才注入，不会覆盖活跃的登录。
|
||||
- 注入成功后 Lingma 启动时直接 ready，`auth_status()` 命中已登录，跳过
|
||||
Playwright。
|
||||
- 注入失败（bundle 损坏、权限不足等）自动 fallback 到原有 Playwright 流程。
|
||||
- bundle 只打包 `cache/{id,user,quota,config.json}` 四个文件，不包含
|
||||
db/logs/index，体积通常 < 10 KB。
|
||||
- bundle 含敏感 token，**按密钥保管**，不要写入公共仓库。
|
||||
- 只在目标 `workDir` 空（`cache/user` 不存在或 empty）时才注入；不会覆盖活跃登录态。
|
||||
- 注入失败（损坏/权限）自动 fallback 到 Playwright。
|
||||
- bundle 只含 `cache/{id,user,quota,config.json}` 4 个文件；大小上限 4 MiB，实际通常 < 10 KB。
|
||||
- **bundle 等同于密钥**，落盘需 `chmod 600`，不要进 git。
|
||||
|
||||
## 3. Docker 运行
|
||||
### 4.3 Prometheus 接入
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```yaml
|
||||
# prometheus scrape_configs 片段
|
||||
- job_name: lingma-gateway
|
||||
bearer_token: <METRICS_TOKEN>
|
||||
static_configs: [{targets: ['host:8317']}]
|
||||
metrics_path: /metrics
|
||||
```
|
||||
|
||||
说明：
|
||||
关键指标：
|
||||
|
||||
- 构建阶段已默认使用腾讯云 PyPI 镜像（`mirrors.cloud.tencent.com`）。
|
||||
- 如需自定义镜像源，可在 `docker-compose.yml` 的 `build.args` 中修改。
|
||||
| 指标 | 类型 | 意义 |
|
||||
|---|---|---|
|
||||
| `gateway_in_flight` / `gateway_queued` | gauge | 并发 / 排队 |
|
||||
| `gateway_rejected_total` | counter | 背压拒绝（429）累计 |
|
||||
| `gateway_pool_instance_ready{name}` | gauge | 每实例是否就绪（0/1） |
|
||||
| `gateway_pool_instance_in_flight{name}` | gauge | 每实例在途 |
|
||||
| `gateway_session_cache_hit_total` / `_miss_total` | counter | 会话复用命中率原料 |
|
||||
| `gateway_chat_requests_success` / `_error` | counter | chat 成功率 |
|
||||
|
||||
查看日志：
|
||||
---
|
||||
|
||||
```bash
|
||||
docker compose logs -f
|
||||
## 五、升级注意事项
|
||||
|
||||
从旧版本升级时注意**破坏性变更**（每一项都有 fallback，默认不会炸，但建议显式配置）：
|
||||
|
||||
| 版本 | 变更 | 应对 |
|
||||
|---|---|---|
|
||||
| v0.3 | `/metrics` 裸奔时（无 token / 无 key）由公开改为 503 | 显式配 `METRICS_PUBLIC=true` 或 `METRICS_TOKEN` |
|
||||
| v0.3 | `/internal/*` 引入 `ADMIN_TOKEN` | 未配置自动 fallback 到 `API_KEYS`，生产建议单独配 |
|
||||
| v0.2 | 默认会话复用（多轮对话只发增量） | 如果你的客户端裁剪了历史导致语义不连续，设 `SESSION_REUSE_ENABLED=false` |
|
||||
| v0.2 | Chat 请求走 JSON-RPC `notify` 而非 `request`（修复 30s TTFB bug） | 无需行动 |
|
||||
| v0.2 | 多实例池（`LINGMA_ACCOUNTS` 存在时启用） | 不配则保持单实例行为 |
|
||||
|
||||
---
|
||||
|
||||
## 六、故障排查（FAQ）
|
||||
|
||||
| 症状 | 排查方向 |
|
||||
|---|---|
|
||||
| `/healthz` 返回 `ok=false` / `pool_ready=0` | 查 `docker logs`，关键字 `lingma spawned` / `state ... -> ready`；若卡在 `starting` → Lingma 二进制或 workDir 权限问题 |
|
||||
| 返回 `401` 且带 `Invalid admin token` | 你用了 `API_KEYS` 去打 `/internal/*`，但服务端已设了 `ADMIN_TOKEN`；用 `ADMIN_TOKEN` 或清空 `ADMIN_TOKEN` |
|
||||
| 返回 `503 metrics scraping disabled` | 三个 env 全空，按 "权限分层" 章节配任一 |
|
||||
| 返回 `429 Too many in-flight` | 并发超过 `GATEWAY_MAX_IN_FLIGHT`；增大或客户端加重试 |
|
||||
| 首 token 延迟 2-3 秒 | Lingma 侧常态；多轮对话第二轮起，会话复用命中后 TTFB 明显降低（看 `gateway_session_cache_hit_total`） |
|
||||
| Playwright 登录失败 | 导出一个已登录 bundle 注入（见 4.2），彻底跳过浏览器 |
|
||||
| 容器重启后 Lingma 要重新登录 | `data/` 没挂在卷上或被清过；确认 `./data:/app/data` 挂载 + bundle fallback |
|
||||
| 升级后 `/metrics` 返回 503 | v0.3 默认严格；按表格 5.1 配置 |
|
||||
|
||||
开 `LOG_LEVEL=DEBUG` 可以看到 Lingma 子进程的 stderr 输出，便于定位 native 崩溃。
|
||||
|
||||
---
|
||||
|
||||
## 七、开发与二开
|
||||
|
||||
项目本身是单仓 FastAPI，3400 行 Python。推荐阅读路径：
|
||||
|
||||
1. **先读 [`DESIGN.md`](./DESIGN.md)** —— 架构、模块职责、关键设计决策、二开指引。
|
||||
2. 再按需读对应模块：
|
||||
- 想改请求入口 / 路由 → `app/main.py`
|
||||
- 想加实例调度策略 → `app/lingma_pool.py::pick()`
|
||||
- 想改 Lingma 通信协议 → `app/lingma_client.py`
|
||||
- 想扩展会话复用 → `app/session_cache.py` + `main.py` 的 reuse 块
|
||||
- 想做认证改造 → `app/auth.py` + `main.py::*_guard`
|
||||
3. 本地跑：`pip install -r requirements.txt && uvicorn app.main:app --reload`。
|
||||
|
||||
---
|
||||
|
||||
## 八、目录结构
|
||||
|
||||
```
|
||||
lingma-openai-gateway/
|
||||
├── app/ # 主代码（见 DESIGN.md 模块一览）
|
||||
│ ├── main.py # FastAPI 入口 + 路由
|
||||
│ ├── lingma_pool.py # N 实例池
|
||||
│ ├── lingma_client.py # LSP over WS + 子进程管理
|
||||
│ ├── session_cache.py # 多轮对话 sessionId 复用
|
||||
│ ├── session_bundle.py # 登录态 export/import
|
||||
│ ├── concurrency.py # InFlightGuard 背压
|
||||
│ ├── auto_login.py # Playwright 登录
|
||||
│ ├── auth.py # Bearer / admin / metrics 三档鉴权
|
||||
│ ├── config.py # 环境变量 → dataclass
|
||||
│ ├── model_map.py # 模型 key ↔ displayName
|
||||
│ ├── openai_schema.py # OpenAI 请求/响应 Pydantic
|
||||
│ ├── stats.py # StatsCollector + Prometheus
|
||||
│ ├── logging_config.py # 结构化 JSON log + request_id 上下文
|
||||
│ └── bootstrap_lingma.py # 启动时下载/提取 Lingma 二进制
|
||||
├── data/ # 持久化（Lingma 二进制 + workDir），不进 git
|
||||
├── secrets/ # 注入的 bundle 等敏感文件，不进 git
|
||||
├── Dockerfile # Playwright base + HEALTHCHECK
|
||||
├── docker-compose.yml
|
||||
├── .env.example # 配置权威文档
|
||||
├── requirements.txt
|
||||
├── README.md # 本文件
|
||||
└── DESIGN.md # 架构与二开手册
|
||||
```
|
||||
|
||||
## 4. 调用示例
|
||||
---
|
||||
|
||||
### 模型列表
|
||||
## License
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8317/v1/models \
|
||||
-H "Authorization: Bearer sk-your-api-key"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `id` 保持 Lingma 原始模型 key（兼容 OpenAI 客户端）
|
||||
- `name` 提供可读名称（如 `qwen3.6-plus`）
|
||||
- 调用 `/v1/chat/completions` 时，`model` 既可传 `id`，也可直接传 `name`
|
||||
|
||||
### 非流式聊天
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8317/v1/chat/completions \
|
||||
-H "Authorization: Bearer sk-your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "dashscope_qmodel",
|
||||
"messages": [
|
||||
{"role": "user", "content": "写一个 python hello world"}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### 流式聊天
|
||||
|
||||
```bash
|
||||
curl -N http://127.0.0.1:8317/v1/chat/completions \
|
||||
-H "Authorization: Bearer sk-your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "dashscope_qmodel",
|
||||
"stream": true,
|
||||
"messages": [
|
||||
{"role": "user", "content": "介绍一下你自己"}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## 5. 统计与监控
|
||||
|
||||
支持调用次数与 token（估算值）统计：
|
||||
|
||||
- `GET /internal/stats`（需 Bearer）
|
||||
- `GET /metrics`（Prometheus 文本格式）
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8317/internal/stats \
|
||||
-H "Authorization: Bearer sk-xxx"
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8317/metrics \
|
||||
-H "Authorization: Bearer ${METRICS_TOKEN:-sk-your-api-key}"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `usage.prompt_tokens/completion_tokens` 为估算值（按字节近似换算）。
|
||||
- 非流式响应里会附带 `usage` 字段。
|
||||
- 流式响应可传 `stream_options: {"include_usage": true}` 让最后一帧返回 `usage`。
|
||||
- `/metrics` 默认需要 Bearer 鉴权：优先匹配 `METRICS_TOKEN`，否则接受 `API_KEYS` 里任意一个；两者皆未配置时返回 503，显式 `METRICS_PUBLIC=true` 才公开。
|
||||
- `/internal/*` 管理端点（auto-login, session export, models/raw, stats）默认走 `ADMIN_TOKEN`，未配置时退化为 `API_KEYS`；两者都未配置则 503。
|
||||
|
||||
## 6. 容器内自动登录
|
||||
|
||||
已内置自动登录能力（Playwright + Chromium）。
|
||||
|
||||
你可以主动触发：
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8317/internal/auto-login/start \
|
||||
-H "Authorization: Bearer sk-your-api-key"
|
||||
```
|
||||
|
||||
查看状态：
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8317/internal/auto-login/status \
|
||||
-H "Authorization: Bearer sk-your-api-key"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 若未登录，`/v1/models` 与 `/v1/chat/completions` 也会尝试自动登录。
|
||||
- 账号密码来自 `.env`（`LINGMA_USERNAME` / `LINGMA_PASSWORD`）。
|
||||
- 建议仅在受控环境使用，并妥善保护 `.env`。
|
||||
|
||||
## 7. agent 模式
|
||||
|
||||
在 v1 中，若 `model` 传 `agent` 或 `lingma-agent`，会走 agent 模式。
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8317/v1/chat/completions \
|
||||
-H "Authorization: Bearer sk-xxx" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "agent",
|
||||
"messages": [
|
||||
{"role": "user", "content": "分析这个项目目录结构"}
|
||||
]
|
||||
}'
|
||||
```
|
||||
内部使用，按需调整。
|
||||
|
||||
Reference in New Issue
Block a user