sub2api/LOCAL_SETUP_NOTES.md

Sub2API 本地开发环境搭建记录

2026-04-19 @ macOS (darwin/arm64)

一、环境依赖

项	版本	说明
Go	1.24.3（本机）→ 1.26.2（auto via GOTOOLCHAIN）	go.mod 要求 1.26.2，靠 Go 1.21+ 的 GOTOOLCHAIN 机制自动下载
Node	v24.13.0	≥18 即可
pnpm	v10.33.0	现装：npm install -g pnpm
Docker	OrbStack	已跑 mysql8@3306，端口冲突规避见下
端口占用	8080 / 5433 / 6380 均空闲	5432/6379 留给可能的其他 PG/Redis

二、部署步骤（实际执行）

1. 拉源码

git clone https://github.com/Wei-Shaw/sub2api.git /Users/mini/Work/dev/sub2api

2. 起依赖容器（非默认端口）

docker run -d --name sub2api-pg \
  -e POSTGRES_PASSWORD=devpass -e POSTGRES_DB=sub2api \
  -p 5433:5432 postgres:15

docker run -d --name sub2api-redis \
  -p 6380:6379 redis:7

3. 安装 pnpm（首次）

npm install -g pnpm

4. 构建前端

cd /Users/mini/Work/dev/sub2api/frontend
pnpm install      # ~9 秒
pnpm run build    # ~8 秒，产物输出到 ../backend/internal/web/dist/

5. 构建后端（⚠️ 必带 -tags embed）

cd /Users/mini/Work/dev/sub2api/backend
go build -tags embed -o sub2api ./cmd/server
# 产物：105MB Mach-O 64-bit arm64

6. 生成 config.yaml

cp /Users/mini/Work/dev/sub2api/deploy/config.example.yaml \
   /Users/mini/Work/dev/sub2api/backend/config.yaml

修改四处（见下方问题点 Issue #1 说明 sslmode）：

字段	原值	改为
database.port	5432	5433
database.password	"your_secure_password_here"	"devpass"
database.sslmode	"prefer"	"disable"
redis.port	6379	6380
jwt.secret	"change-this-..."	openssl rand -hex 32 产出的 64 位 hex

7. 启动 + 验证

cd /Users/mini/Work/dev/sub2api/backend
nohup ./sub2api > /tmp/sub2api.log 2>&1 &
# 等 5-10 秒让服务完成 pricing 数据下载
curl -si http://localhost:8080 | head
# 期望：HTTP/1.1 200 OK，HTML 含 <title>Sub2API - AI API Gateway</title>

---

三、遇到的问题与解法

Issue #1 — sslmode: "prefer" 启动失败

现象：后端启动立即退出，日志：

Failed to initialize application: acquire migrations lock:
pq: unsupported sslmode "prefer"; only "require" (default),
"verify-full", "verify-ca", and "disable" supported

根因：config.example.yaml 默认的 sslmode: "prefer" 是 libpq（C 驱动）的模式，Go 的 lib/pq 不支持。

解法：本地 Docker Postgres 没配 SSL，改成 disable：

database:
  sslmode: "disable"

生产若走带 SSL 的 PG，用 require 或 verify-full。

---

Issue #2 — go.mod 要求 Go 1.26.2，本机只有 1.24.3

现象：首次 go build 触发：

go: downloading go1.26.2 (darwin/arm64)

根因：backend/go.mod 第一行 go 1.26.2 写死。

解法：无需手动升级 Go。Go 1.21+ 的 GOTOOLCHAIN 机制会自动下载指定版本并透明切换。首次 build 比较慢（下载 toolchain + 全部依赖），后续会缓存。

---

Issue #3 — frontend 构建产物路径是相对路径到 backend

现象：pnpm run build 的日志显示产物写到 ../backend/internal/web/dist/。

说明：这是预期行为。Vite 配置把输出指向 backend 的 embed 目录，配合 go build -tags embed 把 dist 打进 Go 二进制。所以：

• 每次改前端代码都要重新 pnpm run build 然后 go build -tags embed
• 如果 go build 时忘了 -tags embed，后端启动后访问 / 会 404

---

Issue #4 — 日志文件 /app/data/logs/sub2api.log 写入失败

现象：启动日志里有 WARN：

日志文件输出初始化失败，降级为仅标准输出
path=/app/data/logs/sub2api.log err=mkdir /app: read-only file system

根因：默认配置指向容器内路径 /app/data/logs/，本地裸跑在 macOS 上 /app 不可写。

影响：无功能影响，只是降级到 stdout。我们用 nohup ./sub2api > /tmp/sub2api.log 2>&1 & 已经把 stdout 重定向了，日志照样完整。

若要消除 WARN：修改 config 里 logging.file_path（或等同字段）指向本地可写路径，如 /tmp/sub2api/logs/sub2api.log，并 mkdir -p 目录。

---

四、当前状态

Backend PID:  26921
HTTP:         200 @ http://localhost:8080
页面:         Sub2API - AI API Gateway（Setup Wizard 入口）
Pricing:      已下载 177 个模型价格
Containers:   sub2api-pg (Up), sub2api-redis (Up)

---

五、下次重启命令

# 启动依赖（容器如果 stopped）
docker start sub2api-pg sub2api-redis

# 启动后端
cd /Users/mini/Work/dev/sub2api/backend
nohup ./sub2api > /tmp/sub2api.log 2>&1 &

# 停止
pkill -f "/Users/mini/Work/dev/sub2api/backend/sub2api"
docker stop sub2api-pg sub2api-redis

六、清理重来

pkill -f "/Users/mini/Work/dev/sub2api/backend/sub2api"
docker rm -f sub2api-pg sub2api-redis
rm -rf /Users/mini/Work/dev/sub2api