623a7518b2
- docs.sections.getKey.note 键从 zh/en 删除 - DocsView 对应 <p class="note"> 段删掉 - 全仓再次 grep 确认无其他 ishare/iShare 引用
169 lines
5.1 KiB
Markdown
169 lines
5.1 KiB
Markdown
# 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
|
||
```
|