# 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. 拉源码
```bash
git clone https://github.com/Wei-Shaw/sub2api.git /Users/mini/Work/dev/sub2api
```

### 2. 起依赖容器（非默认端口）
```bash
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（首次）
```bash
npm install -g pnpm
```

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

### 5. 构建后端（⚠️ 必带 `-tags embed`）
```bash
cd /Users/mini/Work/dev/sub2api/backend
go build -tags embed -o sub2api ./cmd/server
# 产物：105MB Mach-O 64-bit arm64
```

### 6. 生成 config.yaml
```bash
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. 启动 + 验证
```bash
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`：
```yaml
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)
```

---

## 五、下次重启命令

```bash
# 启动依赖（容器如果 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
```

## 六、清理重来

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