本文最后更新于 2026-05-13，文章内容可能已经过时。

sub2api 部署与更新手册

其他组件 go,redis,pgsql,的安装我就不详细说了,推荐 docker版本redis 和 docker版本的pgsql;

1. 基本信息

服务器地址：192.168.215.110
管理面板地址：http://192.168.215.110:8080/
项目根目录：/opt/sub2api-stack/sub2api
前端目录：/opt/sub2api-stack/sub2api/frontend
后端目录：/opt/sub2api-stack/sub2api/backend
数据库：PostgreSQL 15

export ADMIN_EMAIL='<管理员邮箱>'

export ADMIN_PASSWORD='<管理员密码>'

export POSTGRES_PASSWORD='<PostgreSQL密码>'

2. 代理配置

服务器当前通过你本地 Windows 代理出网，临时代理这样设置：

(自己的win上面的代理软件,自己设置,不做详细解释了1.内网能访问2.监听0.0.0.0);

export http_proxy=http://192.168.215.124:7897

export https_proxy=http://192.168.215.124:7897

export HTTP_PROXY=http://192.168.215.124:7897

export HTTPS_PROXY=http://192.168.215.124:7897

Git 永久代理：

git config --global http.proxy http://192.168.215.124:7897

git config --global https.proxy http://192.168.215.124:7897

取消 Git 代理：

git config --global --unset http.proxy

git config --global --unset https.proxy

3. 首次部署 / 重新编译

先修改配置: (/opt/sub2api-stack/sub2api/backend/config.yaml)

database配置正确：

database:
 host: "127.0.0.1"
 port: 5432
 user: "sub2api"
 password: "XXXXXXXXXXX"
 dbname: "sub2api"
 sslmode: "disable"

redis配置正确：

redis:
 host: "127.0.0.1"
 port: 6380
 password: ""
 db: 0
 enable_tls: false

必须改的就是这个：

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

这个不能直接用默认值(自己换成32位随机数)。

3.1 编译前端

cd /opt/sub2api-stack/sub2api/frontend

pnpm install

pnpm run build

3.2 编译后端

cd /opt/sub2api-stack/sub2api/backend

go build -tags embed -o sub2api ./cmd/server

说明：

-tags embed 用于把前端构建产物嵌入后端二进制
编译成功后会生成：
/opt/sub2api-stack/sub2api/backend/sub2api

4. 启动服务

cd /opt/sub2api-stack/sub2api/backend

nohup ./sub2api > /opt/sub2api-stack/sub2api/backend/sub2api.out 2>&1 &

echo $!

说明：

nohup：后台运行
sub2api.out：日志文件
echo $!：输出当前后台进程 PID

防火墙放行8080

systemctl is-active firewalld
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --reload
firewall-cmd --list-ports
ss -lntp | grep 8080

5. 日志查看

查看最近 100 行日志：

tail -n 100 /opt/sub2api-stack/sub2api/backend/sub2api.out

持续追踪日志：

tail -f /opt/sub2api-stack/sub2api/backend/sub2api.out

6. 停止服务

pkill -f '/opt/sub2api-stack/sub2api/backend/sub2api'

如果想先确认进程再停，可以先执行：

pgrep -af '/opt/sub2api-stack/sub2api/backend/sub2api'

7. 重启服务

pkill -f '/opt/sub2api-stack/sub2api/backend/sub2api'

cd /opt/sub2api-stack/sub2api/backend

nohup ./sub2api > /opt/sub2api-stack/sub2api/backend/sub2api.out 2>&1 &

echo $!

sleep 2

tail -n 50 /opt/sub2api-stack/sub2api/backend/sub2api.out

8. 检查端口

查看 8080 是否正常监听：

ss -lntp | grep 8080

如果服务正常启动，通常可以看到 8080 端口被 sub2api 占用。

9. 代码更新与重新部署

cd /opt/sub2api-stack/sub2api

git pull

cd /opt/sub2api-stack/sub2api/frontend

pnpm install

pnpm run build

cd /opt/sub2api-stack/sub2api/backend

go build -tags embed -o sub2api ./cmd/server

pkill -f '/opt/sub2api-stack/sub2api/backend/sub2api'

nohup ./sub2api > /opt/sub2api-stack/sub2api/backend/sub2api.out 2>&1 &

echo $!

sleep 2

tail -n 50 /opt/sub2api-stack/sub2api/backend/sub2api.out

10. 推荐的日常操作顺序

更新代码后标准流程

git pull
前端 pnpm install && pnpm run build
后端 go build -tags embed -o sub2api ./cmd/server
停掉旧进程
启动新进程
tail -n 50 sub2api.out 看日志
ss -lntp | grep 8080 看端口
浏览器访问管理面板确认页面正常

11. 常见问题

1) pnpm install 很慢或失败

先确认代理是否生效：

echo $http_proxy

echo $https_proxy

2) 编译成功但页面没更新

这是因为前端要先重新 build，然后后端再重新 go build -tags embed ...，只编译 Go 不够。

3) 服务启动后打不开管理面板

先看两件事：

tail -n 100 /opt/sub2api-stack/sub2api/backend/sub2api.out

ss -lntp | grep 8080

4) pkill 后马上重启失败

可能旧进程还没完全退出，可以加一点等待：

pkill -f '/opt/sub2api-stack/sub2api/backend/sub2api'

sleep 2

12. 更适合保存的简版命令清单

启动

cd /opt/sub2api-stack/sub2api/backend

nohup ./sub2api > /opt/sub2api-stack/sub2api/backend/sub2api.out 2>&1 &

echo $!

停止

pkill -f '/opt/sub2api-stack/sub2api/backend/sub2api'

重启

pkill -f '/opt/sub2api-stack/sub2api/backend/sub2api'

cd /opt/sub2api-stack/sub2api/backend

nohup ./sub2api > /opt/sub2api-stack/sub2api/backend/sub2api.out 2>&1 &

echo $!

sleep 2

tail -n 50 /opt/sub2api-stack/sub2api/backend/sub2api.out

更新

cd /opt/sub2api-stack/sub2api
git pull

cd /opt/sub2api-stack/sub2api/frontend
pnpm install
pnpm run build

cd /opt/sub2api-stack/sub2api/backend
go build -tags embed -o sub2api ./cmd/server

pkill -f '/opt/sub2api-stack/sub2api/backend/sub2api'
nohup ./sub2api > /opt/sub2api-stack/sub2api/backend/sub2api.out 2>&1 &
echo $!
sleep 2
tail -n 50 /opt/sub2api-stack/sub2api/backend/sub2api.out