【AI工具】wsl2 + ubuntu22.04安装部署sub2api详细教程

博主介绍：✌全网粉丝24W+，CSDN博客专家、Java领域优质创作者，掘金/华为云/阿里云/InfoQ等平台优质作者、专注于Java技术领域✌

技术范围：SpringBoot、SpringCloud、Vue、SSM、HTML、Nodejs、Python、MySQL、PostgreSQL、大数据、物联网、机器学习等设计与开发。

感兴趣的可以先关注收藏起来，在工作中、生活上等遇到相关问题都可以给我留言咨询，希望帮助更多的人。
技术扩展 ：最近发现了一个特别好用的人工智能学习网站，通俗易懂，风趣幽默，忍不住想分享一下给大家，进入传送门：https://www.captainbed.cn/no8g/。

wsl2 + ubuntu22.04安装部署sub2api详细教程

前言
- [0.1 技术栈](#0.1 技术栈)
- [0.2 Nginx 反向代理注意事项](#0.2 Nginx 反向代理注意事项)
[一、Docker Compose 安装方式（推荐）](#一、Docker Compose 安装方式（推荐）)
- [1.1 前置条件](#1.1 前置条件)
- [1.2 快速开始（一键部署）](#1.2 快速开始（一键部署）)
- [1.3 手动部署](#1.3 手动部署)
- [1.4 部署版本对比](#1.4 部署版本对比)
- [1.5 启用"数据管理"功能（datamanagementd）](#1.5 启用“数据管理”功能（datamanagementd）)
- [1.6 访问](#1.6 访问)
- [1.8 轻松迁移（本地目录版）](#1.8 轻松迁移（本地目录版）)
- [1.9 常用命令](#1.9 常用命令)
二、脚本安装方式
- [2.1 前置条件](#2.1 前置条件)
- [2.2 安装步骤](#2.2 安装步骤)
- [2.3 安装后配置](#2.3 安装后配置)
- [2.4 升级](#2.4 升级)
- [2.5 常用命令](#2.5 常用命令)
三、源码编译方式安装
- [3.1 前置条件](#3.1 前置条件)
- [3.2 编译步骤](#3.2 编译步骤)

Sub2API 是一款开源的 AI API 网关平台，可将 Claude、OpenAI、Gemini、Antigravity 等订阅统一接入，支持拼车共享、配额分发、并发控制及精确计费。它可通过生成 API Key 供下游工具调用，实现原生工具无缝使用。

本文推荐使用 Docker Compose 部署，因为这种方式会自动拉起 Sub2API、PostgreSQL 和 Redis，配置最省心，也方便后续备份和迁移。

前言

0.1 技术栈

组件	技术
后端	Go 1.25.7, Gin, Ent
前端	Vue 3.4+, Vite 5+, TailwindCSS
数据库	PostgreSQL 15+
缓存/队列	Redis 7+

0.2 Nginx 反向代理注意事项

通过 Nginx 反向代理 Sub2API（或 CRS 服务）并搭配 Codex CLI 使用时，需要在 Nginx 配置的 http 块中添加：

nginx 复制代码

underscores_in_headers on;

Nginx 默认会丢弃名称中含下划线的请求头（如 session_id），这会导致多账号环境下的粘性会话功能失效。

一、Docker Compose 安装方式（推荐）

使用 Docker Compose 部署，包含 PostgreSQL 和 Redis 容器。

1.1 前置条件

Docker 20.10+
Docker Compose v2+

1.2 快速开始（一键部署）

使用自动化部署脚本快速搭建：

bash 复制代码

# 创建部署目录
mkdir -p sub2api-deploy && cd sub2api-deploy

# 下载并运行部署准备脚本
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f sub2api

脚本功能

下载 docker-compose.local.yml（本地保存为 docker-compose.yml）和 .env.example
自动生成安全凭证（JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD）
创建 .env 文件并填充自动生成的密钥
创建数据目录（使用本地目录，便于备份和迁移）
显示生成的凭证供你记录

1.3 手动部署

如果你希望手动配置：

bash 复制代码

# 1. 克隆仓库
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# 2. 复制环境配置文件
cp .env.example .env

# 3. 编辑配置（生成安全密码）
nano .env

.env 必须配置项

bash 复制代码

# PostgreSQL 密码（必需）
POSTGRES_PASSWORD=your_secure_password_here

# JWT 密钥（推荐 - 重启后保持用户登录状态）
JWT_SECRET=your_jwt_secret_here

# TOTP 加密密钥（推荐 - 重启后保留双因素认证）
TOTP_ENCRYPTION_KEY=your_totp_key_here

# 可选：管理员账号
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_admin_password

# 可选：自定义端口
SERVER_PORT=8080

生成安全密钥

bash 复制代码

# 生成 JWT_SECRET
openssl rand -hex 32

# 生成 TOTP_ENCRYPTION_KEY
openssl rand -hex 32

# 生成 POSTGRES_PASSWORD
openssl rand -hex 32

bash 复制代码

# 4. 创建数据目录（本地版）
mkdir -p data postgres_data redis_data

# 5. 启动所有服务
# 选项 A：本地目录版（推荐 - 易于迁移）
docker compose -f docker-compose.local.yml up -d

# 选项 B：命名卷版（简单设置）
docker compose up -d

# 6. 查看状态
docker compose -f docker-compose.local.yml ps

# 7. 查看日志
docker compose -f docker-compose.local.yml logs -f sub2api

1.4 部署版本对比

版本	数据存储	迁移便利性	适用场景
docker-compose.local.yml	本地目录	✅ 简单（打包整个目录）	生产环境、频繁备份
docker-compose.yml	命名卷	⚠️ 需要 docker 命令	简单设置

推荐： 使用 docker-compose.local.yml（脚本部署）以便更轻松地管理数据。

1.5 启用"数据管理"功能（datamanagementd）

如需启用管理后台"数据管理"，需要额外部署宿主机数据管理进程 datamanagementd。

关键点：

主进程固定探测：/tmp/sub2api-datamanagement.sock
只有该 Socket 可连通时，数据管理功能才会开启
Docker 场景需将宿主机 Socket 挂载到容器同路径

详细部署步骤见：deploy/DATAMANAGEMENTD_CN.md

1.6 访问

在浏览器中打开 http://你的服务器IP:8080

如果管理员密码是自动生成的，在日志中查找：

bash 复制代码

docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"

##1.7 升级

bash 复制代码

# 拉取最新镜像并重建容器
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

1.8 轻松迁移（本地目录版）

使用 docker-compose.local.yml 时，可以轻松迁移到新服务器：

bash 复制代码

# 源服务器
docker compose -f docker-compose.local.yml down
cd ..
tar czf sub2api-complete.tar.gz sub2api-deploy/

# 传输到新服务器
scp sub2api-complete.tar.gz user@new-server:/path/

# 新服务器
tar xzf sub2api-complete.tar.gz
cd sub2api-deploy/
docker compose -f docker-compose.local.yml up -d

1.9 常用命令

bash 复制代码

# 停止所有服务
docker compose -f docker-compose.local.yml down

# 重启
docker compose -f docker-compose.local.yml restart

# 查看所有日志
docker compose -f docker-compose.local.yml logs -f

# 删除所有数据（谨慎！）
docker compose -f docker-compose.local.yml down
rm -rf data/ postgres_data/ redis_data/

二、脚本安装方式

一键安装脚本，自动从 GitHub Releases 下载预编译的二进制文件。

2.1 前置条件

Linux 服务器（amd64 或 arm64）
PostgreSQL 15+（已安装并运行）
Redis 7+（已安装并运行）
Root 权限

2.2 安装步骤

bash 复制代码

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

脚本会自动：

检测系统架构
下载最新版本
安装二进制文件到 /opt/sub2api
创建 systemd 服务
配置系统用户和权限

2.3 安装后配置

bash 复制代码

# 1. 启动服务
sudo systemctl start sub2api

# 2. 设置开机自启
sudo systemctl enable sub2api

# 3. 在浏览器中打开设置向导
# http://你的服务器IP:8080

设置向导将引导你完成：

数据库配置
Redis 配置
管理员账号创建

2.4 升级

可以直接在管理后台左上角点击检测更新按钮进行在线升级。

网页升级功能支持：

自动检测新版本
一键下载并应用更新
支持回滚

2.5 常用命令

bash 复制代码

# 查看状态
sudo systemctl status sub2api

# 查看日志
sudo journalctl -u sub2api -f

# 重启服务
sudo systemctl restart sub2api

# 卸载
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash -s -- uninstall -y

三、源码编译方式安装

从源码编译安装，适合开发或定制需求。

3.1 前置条件

Go 1.21+
Node.js 18+
PostgreSQL 15+
Redis 7+

3.2 编译步骤

bash 复制代码

# 1. 克隆仓库
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

# 2. 安装 pnpm（如果还没有安装）
npm install -g pnpm

# 3. 编译前端
cd frontend
pnpm install
pnpm run build
# 构建产物输出到 ../backend/internal/web/dist/

# 4. 编译后端（嵌入前端）
cd ../backend
go build -tags embed -o sub2api ./cmd/server

# 5. 创建配置文件
cp ../deploy/config.example.yaml ./config.yaml

# 6. 编辑配置
nano config.yaml

注意： -tags embed 参数会将前端嵌入到二进制文件中。不使用此参数编译的程序将不包含前端界面。

config.yaml 关键配置：

yaml 复制代码

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"

database:
  host: "localhost"
  port: 5432
  user: "postgres"
  password: "your_password"
  dbname: "sub2api"

redis:
  host: "localhost"
  port: 6379
  password: ""

jwt:
  secret: "change-this-to-a-secure-random-string"
  expire_hour: 24

default:
  user_concurrency: 5
  user_balance: 0
  api_key_prefix: "sk-"
  rate_multiplier: 1.0

好了，今天分享到这里。希望你喜欢这次的探索之旅！不要忘记 "点赞" 和 "关注" 哦，我们下次见！🎈

本文完结！

祝各位大佬和小伙伴身体健康，万事如意，发财暴富，扫下方二维码与我一起交流！！！