Linux 二进制部署

二进制安装适合已经维护 PostgreSQL、Redis 和 systemd 的服务器。发布包包含嵌入式前端，因此不需要单独部署 Web 静态站点。

前置条件

• Linux amd64 或 arm64。
• Bash 4+。
• PostgreSQL 15+ 已启动并允许服务器连接。
• Redis 7+ 已启动并允许服务器连接。
• root 或 sudo 权限。

一键安装

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

安装脚本会检测系统架构、下载最新 Release、校验文件、创建 sub2api 系统用户，并安装 systemd 服务。

主要路径：

内容	路径
程序目录	/opt/sub2api
配置目录	/etc/sub2api
systemd 服务	sub2api.service

首次启动

sudo systemctl enable --now sub2api
sudo systemctl status sub2api
sudo journalctl -u sub2api -f

浏览器打开：

http://服务器IP:8080

首次运行会进入设置向导，依次填写 PostgreSQL、Redis 和管理员信息。

修改监听地址

使用 systemd override，避免直接修改发行版自带的 service 文件：

sudo systemctl edit sub2api

加入：

[Service]
Environment=SERVER_HOST=127.0.0.1
Environment=SERVER_PORT=8080

应用修改：

sudo systemctl daemon-reload
sudo systemctl restart sub2api

当同机运行 Caddy 或 Nginx 时，推荐监听 127.0.0.1:8080，只让反向代理访问应用。

固定安全密钥

生产环境必须使用固定密钥，避免重启后登录状态或 TOTP 失效：

sudo systemctl edit sub2api

[Service]
Environment=JWT_SECRET=替换为openssl生成的随机值
Environment=TOTP_ENCRYPTION_KEY=替换为64位十六进制随机值
Environment=TZ=Asia/Shanghai

生成方式：

openssl rand -hex 32

密钥一旦投入使用，不要在没有迁移方案的情况下随意更换。

安装指定版本或回退

# 查看可用版本
sudo /opt/sub2api/install.sh list-versions

# 安装指定版本
sudo /opt/sub2api/install.sh rollback v0.1.149

具体脚本路径可能随安装版本变化，也可以重新下载官方安装脚本并传入相同命令。回退程序版本不能自动回退数据库迁移，操作前必须备份 PostgreSQL。

常用运维命令

sudo systemctl status sub2api
sudo systemctl restart sub2api
sudo systemctl stop sub2api
sudo journalctl -u sub2api -f

卸载

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

卸载前先备份数据库、配置目录和运行数据。不要假设卸载脚本会替你保留所有数据。