# AGENTS.md — Sub2API 部署与发版

## 项目概述

Sub2API — AI API 网关平台，Go + Vue 3 前后端一体，Ent ORM，支持多账户管理、API 密钥分发、Token 级计费、智能调度、支付集成。

- 上游: `https://github.com/Wei-Shaw/sub2api`
- 本地: `/Users/qingse/Sync/local-git/sub2api`
- 当前稳定版: `v0.1.133`
- 许可证: LGPL v3

## 部署留痕规则

所有远程部署、迁移、域名切换、证书、反代、Compose、数据库、Redis、Mihomo 或代理配置变化，都必须在当前仓库留痕。

- 根级 `AGENTS.md` 只记录规则、索引和通用流程。
- 每台服务器必须在 `ops/remote/` 下单独一个子目录。
- 服务器目录必须记录域名、IP、服务器名、Tabby profile、部署方式、部署架构、运行检查和操作记录。
- 当前实际生效配置副本必须放在对应服务器目录的 `current/` 下，例如 `docker-compose.yml`、`nginx-sub2api.conf` 或 `Caddyfile`。
- 计划但尚未部署的配置放在 `planned/` 下，不能写成当前事实。
- `.env`、数据库密码、JWT/TOTP 密钥、Mihomo 订阅和真实代理配置只允许放在被 `.gitignore` 排除的 `secrets/` 或 `backups/` 中，禁止提交。
- 通过 Tabby 操作远程后，必须同步更新对应服务器目录，避免远程真实状态和项目记录漂移。

当前远程部署索引见 `ops/remote/README.md`。每个服务器目录至少包含：

```text
ops/remote/<server>-sub2api/
├── README.md              # 服务器级部署记录
├── current/               # 当前远程生效配置副本
├── planned/               # 计划配置，未部署时使用
├── secrets/README.md      # 敏感配置保存说明，真实文件不提交
├── backups/.gitkeep       # 远程备份说明或占位，真实备份不提交
└── .gitignore             # 排除密钥、订阅和备份
```

## 远程部署索引

| 目录 | Tabby 连接 | 公网入口 | 状态 |
|------|------------|----------|------|
| `ops/remote/jppro-sub2api/` | `个人-JPpro-akile-0504-1c1g` | `https://proxy.api.lilifamily.com` / `https://jp.proxy.api.lilifamily.com` | proxy-ng 公开入口节点，回源到 3c4g origin |
| `ops/remote/us-racknerd-0425-sub2api/` | `个人-US-racknerd-0425-1c1g` | `https://pai.cyan2000.uk` | 旧机，迁移来源和回滚来源 |
| `ops/remote/us-racknerd-0526-sub2api/` | `个人-US-racknerd-0526-3c4g` | `https://origin.proxy.api.lilifamily.com` / `https://catproxy.lilifamily.com` | Sub2API 受限 origin 和公开直连主站入口 |

## JPpro 当前 proxy-ng 记录

| 项目 | 详情 |
|------|------|
| 服务器 | JP Pro VPS `151.242.164.72`，Debian Trixie 1C1G20G |
| 域名 | `proxy.api.lilifamily.com`、`jp.proxy.api.lilifamily.com` |
| Tabby 连接 | `个人-JPpro-akile-0504-1c1g` |
| 部署方式 | apt 安装 nginx + Certbot，作为 proxy-ng 入口中转 |
| 回源目标 | `https://origin.proxy.api.lilifamily.com` |
| 访问 | `https://proxy.api.lilifamily.com/`、`https://jp.proxy.api.lilifamily.com/` |
| 详细记录 | `ops/remote/jppro-sub2api/` |

当前 JPpro 不运行 Sub2API、PostgreSQL、Redis、Caddy 或账号出口代理；只运行 nginx 反向代理。当前已启用独立 origin 回源、3c4g 来源 IP 白名单和 `X-Proxy-Ng-Token` 校验。

## JPpro 历史部署记录

| 项目 | 详情 |
|------|------|
| 服务器 | JP Pro VPS `151.242.164.72`，Debian Trixie 1C1G20G |
| 域名 | `proxy.api.cyan2000.uk` |
| Tabby 连接 | `个人-JPpro-akile-0504-1c1g` |
| 部署目录 | `/opt/sub2api/`，已于 2026-05-26 清理 |
| 访问 | `https://proxy.api.cyan2000.uk/`，当前未在 JPpro 上提供服务 |
| 详细记录 | `ops/remote/jppro-sub2api/` |

### 远程目录结构

```
/opt/sub2api/
├── docker-compose.yml    # 官方 docker-compose.yml + Caddy
├── .env                  # 密钥配置 (chmod 600)
└── Caddyfile             # Caddy 反向代理配置
```

数据存储在 Docker 命名卷：`sub2api_data`、`postgres_data`、`redis_data`、`caddy_data`、`caddy_config`。

### 历史 Docker 服务架构

```
Browser :443 (HTTPS) → Caddy → sub2api :8080 (内部) → postgres :5432 (内部)
                       :80 → 301 redirect              → redis :6379 (内部)
```

| 容器 | 镜像 | 角色 |
|------|------|------|
| `sub2api-caddy` | `caddy:2-alpine` | HTTPS 自动证书 + 反向代理 |
| `sub2api` | `weishaw/sub2api:latest` | Go 后端 + 内嵌 Vue 前端 |
| `sub2api-postgres` | `postgres:18-alpine` | 主数据库 |
| `sub2api-redis` | `redis:8-alpine` | 缓存 |

### Caddy 配置

```
proxy.api.cyan2000.uk {
    reverse_proxy sub2api:8080
    encode gzip
}
```

Caddy 自动从 Let's Encrypt 获取和管理 TLS 证书，HTTP(:80) 自动 301 跳转到 HTTPS(:443)。

## 发版流程

远程服务器可直接拉取 Docker Hub，常规升级只需 pull + restart。

### 常规升级（官方镜像）

```bash
cd /opt/sub2api
docker compose pull sub2api
docker compose up -d
```

### 本地编译部署（二开修改时使用）

当 GitHub 不可达需要国内 GOPROXY，或需要本地修改代码后部署时：

```bash
# 1. 拉取代码
cd /Users/qingse/Sync/local-git/sub2api
git fetch ea-ali
git checkout <tag>

# 2. 构建前端
cd frontend && pnpm install --frozen-lockfile && pnpm run build

# 3. 交叉编译 Go
cd ../backend
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  GOPROXY=https://goproxy.cn,direct \
  go build -tags embed -ldflags="-s -w -X main.Version=<版本>" -trimpath \
  -o /tmp/sub2api ./cmd/server

# 4. 构建最小 Docker 镜像
mkdir -p /tmp/sub2api-build/{deploy,backend/resources}
cp /tmp/sub2api /tmp/sub2api-build/
cp -r ../backend/resources/* /tmp/sub2api-build/backend/resources/
cp ../deploy/docker-entrypoint.sh /tmp/sub2api-build/deploy/

cat > /tmp/sub2api-build/Dockerfile << 'EOF'
FROM alpine:latest
RUN apk add --no-cache ca-certificates tzdata su-exec libpq wget
RUN addgroup -g 1000 sub2api && adduser -u 1000 -G sub2api -s /bin/sh -D sub2api
COPY sub2api /app/sub2api
COPY backend/resources /app/resources
COPY deploy/docker-entrypoint.sh /app/docker-entrypoint.sh
RUN chmod +x /app/docker-entrypoint.sh && mkdir -p /app/data && chown sub2api:sub2api /app/data
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD wget -q -T 5 -O /dev/null http://localhost:8080/health || exit 1
WORKDIR /app
ENTRYPOINT ["/app/docker-entrypoint.sh"]
CMD ["/app/sub2api"]
EOF

docker build --platform linux/amd64 -t sub2api:<版本> /tmp/sub2api-build

# 5. 导出上传
docker save sub2api:<版本> | gzip > /tmp/sub2api-<版本>.tar.gz
# Tabby SFTP: open_profile(个人-JPpro-akile-0504-1c1g) → sftp_upload → /tmp/

# 6. 远程部署
docker load < /tmp/sub2api-<版本>.tar.gz
cd /opt/sub2api
sed -i 's|image:.*|image: sub2api:<版本>|' docker-compose.yml
docker compose up -d

# 7. 清理
rm -rf /tmp/sub2api-build /tmp/sub2api /tmp/sub2api-*.tar.gz
```

## 运维命令

```bash
# 查看服务状态
cd /opt/sub2api && docker compose ps

# 查看日志
docker logs sub2api --tail 50 -f

# 查询数据库
docker exec sub2api-postgres psql -U sub2api -d sub2api -c "SELECT ..."

# 重启服务
cd /opt/sub2api && docker compose up -d

# 停止服务
cd /opt/sub2api && docker compose down

# 数据备份
cd /opt/sub2api && tar czf /tmp/sub2api-backup-$(date +%Y%m%d).tar.gz data/ postgres_data/ redis_data/
```

## Git 远程

| 远程 | URL | 角色 |
|------|-----|------|
| `origin` | `https://github.com/Wei-Shaw/sub2api.git` | 上游 |
| `ea-ali` | `ssh://git@101.200.34.71:2222/zizi-al/sub2api.git` | 可写开发远程 |

## 注意事项

- Go 编译必须加 `-tags embed`，否则前端不会嵌入二进制
- 前端 build 输出到 `backend/internal/web/dist`，Go 编译时通过 `//go:embed` 嵌入
- GitHub 和 Docker Hub 在国内网络不可达时，Go proxy 用 `goproxy.cn`，Docker base image 用本地缓存
- 远程服务器可访问 Docker Hub，postgres:18-alpine 和 redis:8-alpine 自动拉取
- `.env` 文件权限必须是 600，包含数据库密码和 JWT 密钥
- 首次启动会自动创建管理员账号（`AUTO_SETUP=true`）