sub2api/VPS_DEPLOYMENT_NOTES.md

# Sub2API VPS 部署 + CI/CD 记录

> 2026-04-19 @ `ai.puro.im` · 217.216.32.230 · Ubuntu 22.04 x86_64

本文档对应 `LOCAL_SETUP_NOTES.md`（Mac 本地开发环境）的线上版本，覆盖：从零到站点可访问、接入 Codex CLI、建立 Drone CI 自动部署的完整流程。

---

## 概览

```
           外网
            │ HTTPS (Let's Encrypt, Caddy auto-TLS)
            ▼
     ai.puro.im :443
            │
     ┌──────┴──────┐
     │   Caddy     │  host, /etc/caddy/conf.d/sub2api.conf
     │ reverse_    │  → 127.0.0.1:8081
     │ proxy       │
     └──────┬──────┘
            │
     docker port map 127.0.0.1:8081 → 容器 8080
            │
   ┌────────▼──────────────┐
   │ sub2api-net (compose) │
   │   sub2api (Go)        │  /opt/sub2api/ (持久化)
   │   sub2api-pg (PG15)   │  ├─ app-data/ (config, .installed, pricing, logs)
   │   sub2api-redis       │  ├─ pg-data/
   │   (redis:7-alpine)    │  └─ redis-data/
   └───────────────────────┘
            │  VPS 出口
            ▼
  api.anthropic.com / chatgpt.com / api.openai.com
```

### CI 流程

```
Mac (本地仓库) ─ git push gitea main ─▶ Gitea (git.puro.im) ──webhook──▶ Drone (devops.puro.im)
                                                                              │
                                                                  ┌───────────┴────────────┐
                                                                  │  build-frontend (pnpm) │
                                                                  │  build-backend (go)    │
                                                                  │  deploy                │
                                                                  │   - cp bin + Dockerfile│
                                                                  │   - docker compose up  │
                                                                  │     --build sub2api    │
                                                                  └────────────────────────┘
```

---

## 一、VPS 环境

| 项 | 值 | 备注 |
|---|---|---|
| 主机 | 217.216.32.230（新加坡） | `ssh vps` |
| OS | Ubuntu 22.04 LTS x86_64 | |
| Caddy | host 安装，`/etc/caddy/conf.d/*.conf` auto-include | 已跑着 puro.im / git.puro.im / devops.puro.im / erp.puro.im / ... |
| Docker | host 装 + `devops-net` 网络 | 各应用容器都在 devops-net 里 |
| Gitea | `git.puro.im:2222` (SSH), 3000 (HTTP) | purovps/sub2api 仓库 |
| Drone | `devops.puro.im`（OAuth via Gitea） | drone-server + drone-runner-docker |
| Sub2API 专用 docker-compose | `sub2api-net` 独立 bridge 网络（**不加 devops-net**） | 隔离 PG/Redis 生命周期 |
| DNS | Cloudflare **DNS only**（非代理模式） | `ai.puro.im` A 记录 → VPS IP |
| 端口冲突 | 宿主 `:8080` 被 drone-server 占 | Sub2API 映射到宿主 `127.0.0.1:8081` |

---

## 二、初次部署流程（手工路径，首次跑通）

> CI 跑通后这段主要作为"首次引导 / 灾难恢复参考"。日常改代码走 CI（下一节）。

### 1. 本机交叉编译 linux/amd64 二进制

```bash
cd /Users/mini/Work/dev/sub2api/backend
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -tags embed -ldflags='-s -w' -o sub2api-linux ./cmd/server
# 产物 ~75MB, static ELF x86-64
```

注意：本机 macOS arm64，VPS 是 x86_64，**必须交叉编译**。`-tags embed` 把前端 dist 打进二进制（配合先跑 `pnpm run build`）。

### 2. VPS 建目录 + scp 文件

```bash
ssh vps "mkdir -p /opt/sub2api/{app-data,pg-data,redis-data}"

# 准备 deploy 文件（本地 staging 目录）
cp backend/sub2api-linux /Users/mini/Work/dev/sub2api-deploy/
# Dockerfile + docker-compose.yml 见下节内容

scp /Users/mini/Work/dev/sub2api-deploy/{sub2api-linux,Dockerfile,docker-compose.yml} \
    vps:/opt/sub2api/

# distroless:nonroot 需要 UID 65532 可写
ssh vps "chown -R 65532:65532 /opt/sub2api/app-data"
```

### 3. Dockerfile（`.ci/Dockerfile` 也是同一份）

```dockerfile
FROM gcr.io/distroless/static-debian12:nonroot
WORKDIR /app
COPY sub2api-linux /app/sub2api
EXPOSE 8080
ENTRYPOINT ["/app/sub2api"]
```

### 4. docker-compose.yml

关键点：
- `sub2api` 监听 `127.0.0.1:8081:8080`（避开宿主 8080 被 drone 占）
- `/app/data` 整个挂到 `./app-data`（含 config.yaml / install.lock / pricing / logs）
- PG 密码通过 `POSTGRES_PASSWORD` env（不进仓库）
- 独立 `sub2api-net` bridge，不混 devops-net

生产文件位置：`/opt/sub2api/docker-compose.yml`（**不签入 git**，含 PG 密码）。模板结构：

```yaml
services:
  postgres:
    image: postgres:15
    container_name: sub2api-pg
    environment:
      POSTGRES_DB: sub2api
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: "<32-hex 强口令>"
    volumes: [./pg-data:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d sub2api"]
    restart: unless-stopped
    networks: [sub2api-net]

  redis:
    image: redis:7-alpine
    container_name: sub2api-redis
    command: ["redis-server", "--appendonly", "yes"]
    volumes: [./redis-data:/data]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
    restart: unless-stopped
    networks: [sub2api-net]

  sub2api:
    build: .
    image: sub2api:local
    container_name: sub2api
    depends_on:
      postgres: { condition: service_healthy }
      redis:    { condition: service_healthy }
    volumes:
      - ./app-data:/app/data
    ports: ["127.0.0.1:8081:8080"]
    restart: unless-stopped
    networks: [sub2api-net]

networks:
  sub2api-net:
    driver: bridge
```

### 5. 起 stack

```bash
ssh vps "cd /opt/sub2api && docker compose up -d --build"
# 等 PG/Redis healthy 后 sub2api 才会起（depends_on + healthcheck 保证）
```

### 6. Caddy 反代

`/etc/caddy/conf.d/sub2api.conf`：

```caddy
ai.puro.im {
    reverse_proxy 127.0.0.1:8081 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
    encode gzip zstd
    log {
        output file /var/log/caddy/ai.puro.im.log
        format json
    }
}
```

```bash
ssh vps "systemctl reload caddy"
```

### 7. 首次访问 → Setup Wizard

**不预先写 `/opt/sub2api/app-data/config.yaml`**——让 sub2api 以 wizard 模式启动，自己生成 config。走：

1. 浏览器开 `https://ai.puro.im` → 自动进 Setup Wizard
2. Step 1 数据库：host=`postgres` / port=`5432` / user=`postgres` / password=<compose 里那个> / dbname=`sub2api` / sslmode=`disable`
3. Step 2 Redis：host=`redis` / port=`6379` / password 空 / db=`0`
4. Step 3 Admin：邮箱 + ≥8 位密码（自己选好记下来）
5. Step 4 提交 → wizard 写 `app-data/config.yaml` + `app-data/.installed` + DB 创建 admin → 进程自杀、compose 重启后以正常模式跑

### 8. 加 OpenAI OAuth 账号（账号池）

从本机 `~/.codex/auth.json` 抽 `tokens.refresh_token`，粘到：
- 后台 → 账号管理 → 添加账号 → Platform: OpenAI / Type: OAuth → "粘贴 Refresh Token" → 验证
- 弹出 ChatGPT 邮箱+Plan 即成功

### 9. 三件必调（否则 503 "no available OpenAI accounts"）

见 [§四 · 坑 3](#坑-3-新建-oauth-账号一上来无法调度)，后台 UI 里：
- **开启调度开关**
- **去掉 auto_pause_on_expired**
- **清掉 expires_at**（或设远期）

---

## 三、CI/CD 流水线（Drone）

### 仓库

| 位置 | 用途 |
|---|---|
| GitHub: `Wei-Shaw/sub2api` | 上游，origin remote |
| Gitea: `git.puro.im/purovps/sub2api` | 我们的 fork，**Drone trigger source**，remote 名 `gitea` |

本地开发流程：

```bash
# 日常
git checkout main
# 改代码...
git commit
git push gitea main    # 触发 CI
# 可选同步上游
git fetch origin
git merge origin/main  # 手动决定是否合上游
```

### Drone 激活

首次激活：https://devops.puro.im → Sync → 点亮 `purovps/sub2api` → Settings → 开 **Trusted**（pipeline 要挂 host socket 和 `/opt/sub2api`）。

激活后 Gitea 会自动配 webhook（`POST https://devops.puro.im/hook`，事件 `push, pull_request, ...`）。

### `.drone.yml` 三段 pipeline

```yaml
kind: pipeline
type: docker
name: default
trigger: { branch: [main], event: [push] }

steps:
  - name: build-frontend       # node:18-alpine + pnpm 10.33
    # pnpm install --frozen-lockfile && pnpm run build
    # 产物 → backend/internal/web/dist/

  - name: build-backend        # golang:1.23-alpine + GOTOOLCHAIN=auto
    # 自动拉 Go 1.26.2 toolchain
    # CGO_ENABLED=0 GOOS=linux GOARCH=amd64 → sub2api-linux

  - name: deploy               # docker:cli
    # cp backend/sub2api-linux /opt/sub2api/sub2api-linux
    # cp .ci/Dockerfile       /opt/sub2api/Dockerfile
    # cd /opt/sub2api && docker compose up -d --build sub2api
    # 验证 sub2api 容器 running
```

host 挂载 3 类卷：
- `/var/run/docker.sock` — 用宿主 docker daemon 做构建+重启
- `/opt/sub2api` — 更新 binary/Dockerfile
- `/opt/drone/cache/{pnpm-store,go-build,go-mod}` — 加速后续构建

### 首次构建时长

| Step | 首次 | 缓存命中后 |
|---|---|---|
| build-frontend | ~90s | ~30s |
| build-backend | ~60s（+首次下 Go 1.26.2 toolchain） | ~40s |
| deploy | ~20s | ~20s |
| **合计** | **~3 min** | **~90s** |

### CI 不碰的内容（secrets / 数据）

| 文件/目录 | 位置 | 为什么 |
|---|---|---|
| `docker-compose.yml` | `/opt/sub2api/` | 含 PG 密码 |
| `app-data/config.yaml` | `/opt/sub2api/app-data/` | JWT secret / 运行态 |
| `pg-data/` | `/opt/sub2api/` | PG 数据 |
| `redis-data/` | `/opt/sub2api/` | Redis 数据 |

CI 只：
- 覆写 `/opt/sub2api/sub2api-linux`（二进制）
- 覆写 `/opt/sub2api/Dockerfile`
- `docker compose up -d --build sub2api` — 只重建 `sub2api` service（PG/Redis 不动）

### Skip CI

文档/无代码变动想跳过构建：commit 消息加 `[CI SKIP]`（Drone 官方约定）。

---

## 四、踩坑与解法

### 坑 1：Setup Wizard 默认写 `server.port: 443`

**现象**：Wizard 跑完 → 容器重启 → `127.0.0.1:8081` 无响应（app 启动了但监听在 container 内的 :443）。

**根因**：Wizard 默认把 `server.port` 写成 443（面向"容器直接暴露 HTTPS"的用法，不适合我们"容器内 8080 + Caddy 外 443"的模式）。

**解法**：
```bash
ssh vps "sed -i 's/port: 443/port: 8080/' /opt/sub2api/app-data/config.yaml && docker restart sub2api"
```

后续 CI 不重写 config.yaml，这个修复是一次性的。

---

### 坑 2：distroless:nonroot 日志目录权限

**现象**：容器启动日志刷 `write error: can't open new logfile: open /app/data/logs/sub2api.log: permission denied`。

**根因**：`gcr.io/distroless/static-debian12:nonroot` 进程 UID=65532，但 `/opt/sub2api/app-data/logs` 宿主目录 owner=root。

**解法**：
```bash
ssh vps "chown -R 65532:65532 /opt/sub2api/app-data"
```

一次性。CI 不碰 app-data，所以不复发。

---

### 坑 3：新建 OAuth 账号一上来"无法调度"

**现象**：refresh_token 粘好、验证通过、UI 显示"正常"，curl `/responses` 报 `503 "Service temporarily unavailable"`，日志 `openai.account_select_failed: no available OpenAI accounts`。

**根因（三个叠加）**：
1. UI 默认 `schedulable=false`
2. Wizard/后端给 `expires_at` 写了 **access_token 的短期过期**（~7 分钟后），而 `auto_pause_on_expired=true` 默认开
3. 每次 sub2api 重启 → `[AccountExpiry] Auto paused 1 expired accounts` → schedulable 被打回 false

**解法**（SQL 或 UI 都可）：
```sql
UPDATE accounts
SET schedulable=true, expires_at=NULL, auto_pause_on_expired=false
WHERE id=<n>;
```

**已存 memory**：`feedback_sub2api_account_pitfalls.md`。长期方案：修 fork 里的账号创建逻辑，OAuth 账号的 `expires_at` 应指 refresh_token 过期或订阅到期，不是 access_token。

---

### 坑 4：`run_mode: simple` 隐藏 SaaS 菜单

**现象**：为跳过 `INSUFFICIENT_BALANCE` 临时切到 `run_mode: simple`，重登后台发现**用户管理 / 分组管理 / 渠道管理 / 订阅管理 / 兑换码 / 优惠码**全消失。

**根因**：**设计行为**，不是 bug。`simple` 模式是给 "单用户/团队内部工具" 用，刻意隐藏 SaaS 管理面板；前端 `stores/auth.ts` 里 `isSimpleMode = computed(() => runMode === 'simple')` 控制路由可见性。

**解法**：
- 如果需要管理 group/订阅/计费/兑换码 → 保持 `run_mode: standard`
- `INSUFFICIENT_BALANCE` 的替代方案：给 admin 塞大额 balance 即可（见坑 5）

---

### 坑 5：`standard` 模式 + admin balance=0 → 403

**现象**：切回 `standard` 后 curl `/responses` 报 `INSUFFICIENT_BALANCE`。

**根因**：中间件 `api_key_auth.go:198` 检查 `apiKey.User.Balance <= 0` → 403。admin 默认余额为 0。

**解法**：
```sql
UPDATE users SET balance = 1000000000 WHERE id=1;
```

10 亿够跑很久。接 iShare 后改用 iShare 订阅模式（sub2api 标记为 "subscription mode"，走订阅限额而不查 balance）。

---

### 坑 6：Redis L2 cache stale

**现象**：跑 [坑 5] 的 SQL 之后、docker restart sub2api 之后，curl 仍报 `INSUFFICIENT_BALANCE`。

**根因**：Sub2API 的 API key 鉴权有两级缓存：
- L1 进程内 LRU（TTL 15s）
- L2 Redis（key `sub2api:apikey:*`，**TTL 300s**）

docker restart 只清 L1，L2 是独立 Redis 容器，保留着旧的 `balance=0` 缓存条目。

**解法**：
```bash
ssh vps "docker exec sub2api-redis redis-cli FLUSHDB && docker restart sub2api"
```

**一般经验**：改 DB 里的 user / api_key / account 后需重启 sub2api **+** 清 Redis。只重启 sub2api 不够。

---

### 坑 7：`/setup/*` 路由按需注册

**现象**：首次手工写了 config.yaml 让容器跑起来，后来想走 Wizard 重新配置；前端进了 `/setup` 页，填完点"测试连接" → `Request failed with status code 404`。

**根因**：`cmd/server/main.go` 里只有 `NeedsSetup() == true` 分支（走 `runSetupServer()`）才 `setup.RegisterRoutes(r)`。config.yaml 已存在时走 `runMainServer()`，setup 路由不注册 → 前端 `/setup/test-db` → 404。

**解法**：让 `NeedsSetup()` 返回 true，即 `/app/data/config.yaml` **和** `/app/data/.installed` 都不存在。具体做法：
```bash
ssh vps "cd /opt/sub2api && mv app-data/config.yaml app-data/config.yaml.bak; \
  mv app-data/.installed app-data/.installed.bak 2>/dev/null; \
  docker restart sub2api"
```

---

## 五、当前状态 snapshot（2026-04-19）

```
Domain    https://ai.puro.im  (HTTP/2, Let's Encrypt via Caddy)
VPS       217.216.32.230 (Singapore, Ubuntu 22.04)
Image     sub2api:local (Drone CI-built, distroless + static Go binary)

Containers on VPS:
  sub2api          ← Drone 每次 push 重建
  sub2api-pg       postgres:15   (devops-net 无关，独立 sub2api-net)
  sub2api-redis    redis:7-alpine

Accounts:
  admin@puro.im (id=1, role=admin, balance=1e9)
  test_myopenai (OpenAI OAuth, group=test_codex, schedulable=true)

API keys:
  sk-d2132de2f0b4c1ab64ef7241a16d254cab483f1f8afd47ad4a89e39cf6e2345a
  (user=admin, group=test_codex)

Config:
  run_mode: standard
  server.port: 8080 (容器内)
  database.host: postgres (compose DNS)
  redis.host: redis (compose DNS)

CI:
  Drone job trigger = git push gitea main
  Gitea webhook → Drone webhook (active)
  最近一次 build: commit 9c34e961 ✓ (前端 ~90s + 后端 ~60s + deploy ~20s)
```

---

## 六、常用运维命令

### 日常
```bash
# 状态
ssh vps "cd /opt/sub2api && docker compose ps"

# 日志
ssh vps "docker logs sub2api --tail 100 -f"
ssh vps "tail -f /var/log/caddy/ai.puro.im.log"

# 强制重启 sub2api（不动 PG/Redis）
ssh vps "docker restart sub2api"

# 重载 Caddy
ssh vps "systemctl reload caddy"

# 清 Redis 缓存（改 DB 后要做）
ssh vps "docker exec sub2api-redis redis-cli FLUSHDB"
```

### 触发 CI 重建
```bash
git commit --allow-empty -m "ci: rebuild" && git push gitea main
# 跟 build 进度（可选）
ssh vps "docker ps --filter 'name=^drone-'"
```

### 数据备份
```bash
# PG dump
ssh vps "docker exec sub2api-pg pg_dump -U postgres sub2api" \
  > ~/backups/sub2api-$(date +%Y%m%d).sql

# 整个 /opt/sub2api/
ssh vps "tar -czf /tmp/sub2api-full-$(date +%Y%m%d).tgz -C /opt sub2api"
scp vps:/tmp/sub2api-full-*.tgz ~/backups/
```

### 查关键 DB 信息
```sql
-- 账号池
SELECT id, name, platform, type, status, schedulable, expires_at FROM accounts;

-- API keys
SELECT id, user_id, name, status, group_id, quota, quota_used FROM api_keys;

-- 用户 + 余额
SELECT id, email, role, balance FROM users;

-- 今日用量
SELECT model_name, SUM(total_tokens), SUM(total_cost)
  FROM usage_logs
 WHERE created_at > NOW() - INTERVAL '24 hours'
 GROUP BY model_name
 ORDER BY 2 DESC;
```

---

## 七、清理/从头重来

```bash
# 停 + 删所有容器
ssh vps "cd /opt/sub2api && docker compose down"

# 清数据（会彻底删 wizard 数据、用户、账号池！）
ssh vps "rm -rf /opt/sub2api/{app-data,pg-data,redis-data}"
ssh vps "mkdir -p /opt/sub2api/{app-data,pg-data,redis-data}"
ssh vps "chown -R 65532:65532 /opt/sub2api/app-data"

# 重新起（走 Wizard）
ssh vps "cd /opt/sub2api && docker compose up -d"

# Caddy 保留，不用动
```

**不清数据的"纯重建"**（CI 跑一遍等价）：
```bash
git commit --allow-empty -m "ci: rebuild" && git push gitea main
```

---

## 参考

- 本地开发：`LOCAL_SETUP_NOTES.md`
- CI 配置：`.drone.yml`、`.ci/Dockerfile`、`.ci/README.md`
- 上游：https://github.com/Wei-Shaw/sub2api
- Fork：https://git.puro.im/purovps/sub2api