源码开发与构建

源码方式适合开发功能、调试协议兼容或构建自己的镜像。生产环境仍建议构建不可变 Docker 镜像，而不是在服务器上长期运行开发命令。

开发环境

当前仓库要求：

• Go 1.26.5。
• Node.js 20+；官方 Docker 构建使用 Node.js 24。
• pnpm 9。
• PostgreSQL 和 Redis。

获取代码

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

安装前端依赖

cd frontend
corepack enable
corepack prepare pnpm@9 --activate
pnpm install --frozen-lockfile

仓库只维护 pnpm-lock.yaml，不要混用 npm 或 yarn。

启动开发服务

先确保 PostgreSQL 和 Redis 可用。全新环境可以先运行命令行设置向导：

cd backend
go run ./cmd/server --setup

设置完成后再分别启动后端与前端。

终端一：

cd backend
go run ./cmd/server

终端二：

cd frontend
pnpm dev

前端默认运行在 http://localhost:3000，并把 /api、/v1 和 /setup 代理到 http://localhost:8080。可以通过环境变量修改：

VITE_DEV_PORT=3000
VITE_DEV_PROXY_TARGET=http://localhost:8080

运行检查

# 后端单元测试
cd backend
make test-unit

# 后端集成测试
make test-integration

# 前端 lint、类型检查和关键测试
cd ..
make test-frontend

# 全量前端测试
pnpm --dir frontend test:run

构建自定义镜像

根目录 Dockerfile 会构建 Vue 前端、把静态资源嵌入 Go 二进制，再生成非 root 运行镜像：

docker build -t sub2api:local .

如需让 Compose 使用本地镜像，把应用服务改为：

services:
  sub2api:
    image: sub2api:local

然后启动：

cd deploy
docker compose -f docker-compose.local.yml up -d

手动构建单二进制

正式二进制需要先构建前端，再使用 embed build tag：

pnpm --dir frontend install --frozen-lockfile
pnpm --dir frontend build

cd backend
CGO_ENABLED=0 go build \
  -tags embed \
  -trimpath \
  -o bin/sub2api \
  ./cmd/server

pnpm build 会把前端输出到 backend/internal/web/dist。没有 -tags embed 时，生成的后端二进制不包含 Web 管理后台。

修改数据库结构

修改 Ent Schema 后需要重新生成代码，同时提供向前迁移 SQL：

cd backend
go generate ./ent

不要只依赖 Ent 生成结果。正式环境的已有数据库仍然通过 backend/migrations 中的迁移文件升级。