Sub2API 完整迁移安装教程

后台登录

公开教程已移除真实登录信息。部署后请使用迁移包中的实际配置登录，并立即修改管理员密码。本地部署已关闭 Cloudflare Turnstile。

迁移包文件

安装到新的 Windows 电脑

1. 安装 WSL2 和 Ubuntu

以管理员身份打开 PowerShell：

wsl --install -d Ubuntu

重启 Windows，打开 Ubuntu，并完成 Linux 用户名和密码初始化。

2. 在 Ubuntu 内安装 Docker Engine

sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

退出并重新打开 Ubuntu，使 Docker 用户组设置生效。

3. 放置迁移包

将整个迁移包放到空间充足的磁盘，例如：

D:\Sub2API迁移包-20260901

4. 一键恢复

cd /mnt/d/Sub2API迁移包-20260901
chmod +x restore.sh backup-current.sh
sudo ./restore.sh

恢复完成后打开 http://127.0.0.1:8080。

安装到新的 Linux 服务器

1. 安装 Docker

sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo systemctl enable --now docker

2. 上传迁移包

在本地 PowerShell 运行，将 SERVER_IP 替换为服务器地址：

scp -r "D:\Sub2API迁移包-20260901" root@SERVER_IP:/opt/sub2api

3. 恢复并启动

cd /opt/sub2api
chmod +x restore.sh backup-current.sh
./restore.sh

服务默认只监听 127.0.0.1:8080，不会直接暴露到公网。

4. 配置 Nginx 域名代理

sudo apt install -y nginx

server {
    listen 80;
    server_name YOUR_DOMAIN;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

替换 YOUR_DOMAIN，启用站点并配置 HTTPS。随后在后台把前端地址改为新的 HTTPS 域名，并重新配置 Cloudflare Turnstile。

宝塔面板安装

适用于安装了宝塔 Linux 面板的 Ubuntu、Debian、CentOS 或 OpenCloudOS 服务器。

1. 安装 Docker 管理器

登录宝塔面板，在「软件商店」搜索并安装「Docker 管理器」，确认 Docker 服务处于运行状态。若没有对应插件，可在宝塔「终端」安装。

Ubuntu 或 Debian：

apt update
apt install -y docker.io docker-compose-v2
systemctl enable --now docker

CentOS、Rocky Linux 或 OpenCloudOS：

yum install -y docker docker-compose-plugin
systemctl enable --now docker

docker version
docker compose version

2. 上传并解压迁移包

在宝塔「文件」中进入 /opt，上传完整迁移备份，然后在宝塔终端执行：

cd /opt
tar -xzf Sub2API完整迁移备份-20260901.tar.gz
mv Sub2API迁移包-20260901 sub2api
cd /opt/sub2api
sha256sum -c SHA256SUMS.txt

校验项全部显示 OK 后继续。

3. 一键恢复应用和数据库

cd /opt/sub2api
chmod +x restore.sh backup-current.sh
./restore.sh
docker compose ps

sub2api、sub2api-postgres 和 sub2api-redis 都应显示为 healthy。

4. 在宝塔新建网站

1. 进入宝塔「网站」，新建站点并填写域名，例如 api.example.com。
2. PHP 版本选择「纯静态」。
3. 数据库选择「不创建」，本项目使用容器内 PostgreSQL。
4. 创建后打开站点设置。

5. 添加反向代理

在站点设置的「反向代理」中添加代理：

需要手动编辑 Nginx 时，使用以下配置：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
}

6. 申请 HTTPS 证书

在站点「SSL」设置中使用 Let's Encrypt 申请证书，并开启「强制 HTTPS」。申请前确认域名 A 记录指向服务器，安全组和宝塔防火墙已放行 80、443。

应用的 8080 端口只监听 127.0.0.1，无需对公网放行。

7. 修改域名相关设置

1. 登录后台，把前端地址改为新的 HTTPS 域名。
2. 按新域名重新配置 Cloudflare Turnstile。
3. 检查邮件、支付和 OAuth 等回调地址。
4. 修改迁移包提供的临时管理员密码。

8. 宝塔环境备份与日志

cd /opt/sub2api
./backup-current.sh
docker compose logs -f --tail=200 sub2api
systemctl enable docker

建议使用宝塔计划任务定期导出数据库，并将备份同步到另一台机器或对象存储。

日常管理

查看状态

docker compose ps

查看应用日志

docker compose logs -f --tail=200 sub2api

停止和重新启动

docker compose down
docker compose --env-file .env up -d

生成最新备份

sudo ./backup-current.sh

校验迁移文件

sha256sum -c SHA256SUMS.txt

数据与安全事项

PostgreSQL 与 Redis 使用 Docker 命名卷。迁移到另一台机器时，以 SQL 文件作为数据库恢复依据。

.env 包含数据库密码、JWT 密钥和 TOTP 加密密钥。请完整保管迁移包，不要公开上传。丢失 TOTP_ENCRYPTION_KEY 会影响已有 TOTP 数据解密。

重复执行 restore.sh 会按 SQL 中的清理语句重新导入数据库。生产环境执行前，应额外生成一份最新数据库备份。