这个教程解决什么问题

读完这篇你能做到：选对部署路线，完成 SubBoost 的安装，创建管理员账号，通过健康检查确认服务就绪。SubBoost 有两条官方部署路径——一键镜像和 Compose 源码构建，本文都覆盖。

路线怎么选

路线适合特点
一键部署（GHCR 镜像）大多数人拉镜像即跑，最快上手
高级部署（Compose 源码构建）熟悉 Docker Compose、要深度定制从源码构建，配置全部可控

先说一句通用前提：SubBoost 依赖 PostgreSQL 存储订阅和节点数据，一键镜像已经内置处理，Compose 路线则由 Compose 文件提供或复用你已有的数据库。

路线一：一键部署（推荐）

官方镜像发布在 GHCR（ghcr.io），一键部署的具体命令以官方文档「一键部署」章节为准——镜像 tag 会随版本更新，直接复制文档里的 docker run 命令执行即可。

核心要点是三个：

  1. 端口映射：容器内服务端口映射到宿主机（可用 SUBBOOST_PORT 环境变量自定义）
  2. 数据持久化：把数据目录挂载为 volume，升级镜像不丢订阅配置
  3. 首次初始化：部署完成后浏览器打开服务页面，首次访问会引导你创建管理员账号——这一步完成后才能进入管理界面

部署形态和本站写过的 n8n Docker 部署是同一套范式，如果你的服务器上已经跑着其他自托管服务，流程完全熟悉。

路线二：Docker Compose 源码构建

适合想完全掌控配置的用户。按官方文档的步骤：

第一步，准备环境。 需要 Docker 和 Docker Compose，以及一份公开源码。PostgreSQL 由 Compose 文件提供，或者指向你已有的数据库实例。

第二步，配置环境变量。 进入源码的 local 目录，复制环境变量模板：

cd local
cp local.env.example .env

然后编辑 .env，关键变量清单：

变量作用注意事项
POSTGRES_PASSWORD数据库密码用长随机串，别用默认值
DATABASE_URL数据库连接串密码与上一项保持一致
ENCRYPTION_KEY订阅数据加密密钥生成后妥善保管，丢失则加密数据无法解密
JWT_SECRET登录会话签名密钥换成随机值
CRON_SECRET定时任务触发凭证自动刷新功能使用
APP_URL应用的对外访问地址影响生成的订阅链接域名
SUBBOOST_PORT服务监听端口按需自定义

其中 ENCRYPTION_KEY 最值得强调：SubBoost 用它加密存储你的订阅敏感信息。这个密钥一旦丢失，数据库里的订阅数据就解不开了——部署时生成好，和数据库备份一起纳入你的备份策略。

第三步，启动。 Compose 文件会同时拉起应用和数据库：

docker compose up -d

部署后验证

两条官方提供的健康检查端点：

# 存活检查
curl http://127.0.0.1:端口/api/health/live

# 就绪检查（数据库连通）
curl http://127.0.0.1:端口/api/health/ready

live 返回正常说明进程活着，ready 返回正常说明数据库连接就绪。两个都通过后，浏览器打开服务地址，走首次访问的管理员创建流程，登录进控制台就算部署完成。

反向代理与 HTTPS

给 SubBoost 套一层反代是标准操作：订阅链接走 HTTPS 更安全，也避免部分客户端对 HTTP 订阅的限制。Caddy 两行配置搞定，本站的雷池配合 Caddy 方案里 Caddy 的配置模式可以直接套用；Vercel/Nginx 用户按常规反代配置即可。

注意 APP_URL 要和反代后的对外地址一致，否则生成的订阅链接域名不对。

部署常见问题 FAQ

Q：服务器需要什么配置？

SubBoost 是轻量 Web 服务，依赖 PostgreSQL 存数据，一台最低配的 VPS 就能跑。它的职责是拉取订阅、管理节点池、输出聚合订阅，不承载代理流量，对带宽和 CPU 没有特殊要求。

Q：可以复用已有的 PostgreSQL 吗？

可以。Compose 路线允许把 DATABASE_URL 指向已有的数据库实例，不必单独起库。注意容器网络里主机名用服务名而不是 localhost，并给 SubBoost 单独建库建账号，别和其他服务混用同一份数据。

Q：怎么升级版本？

Compose 路线两条命令：docker compose pull 拉新镜像，docker compose up -d 重建容器。数据都在 volume 里不会丢。升级前确认 volume 配置在，顺手做一次数据库备份，再走健康检查验证。

Q：忘记管理员密码怎么办？

管理界面首次访问创建的管理员账号控制着你全部订阅数据，凭证务必存进密码管理器。万一丢失，重置方式以官方文档为准——这也是数据库备份不能偷懒的另一个理由。

Q：端口被占用或不想暴露端口怎么办？

改 SUBBOOST_PORT 换一个监听端口即可。更好的做法是让应用只监听本机回环地址，对外由反向代理提供 HTTPS 服务——安全性和整洁度都更好。

Q：可以部署在 NAS 或家里的小主机上吗？

可以，Docker 能跑的地方就能部署。两个前提要满足：机器常开稳定——聚合订阅是全家客户端的依赖入口，服务器宕机等于所有客户端断更；外网访问路径要处理好，家庭宽带环境要么内网穿透，要么只在局域网内使用。

Q：健康检查端点要暴露到公网吗？

不必。live 和 ready 两个端点在本机 curl 验证即可，反向代理上可以不转发它们——暴露面越小越好。

日常运维操作卡

部署完成只是开始，日常高频操作记这一张表：

操作命令 / 位置说明
查看日志docker compose logs -f排障第一步，报错信息在这里
重启服务docker compose restart改过环境变量要用 up -d 重建
升级版本docker compose pull && docker compose up -d数据在 volume，配置不丢
备份数据库pg_dump 定时任务备份三件套见自托管隐私实践
健康检查curl /api/health/ready升级或改动后先跑一遍

三个常见坑

坑一：数据库连接失败。 Compose 路线先确认数据库容器起来了再看应用日志；复用已有 PostgreSQL 时检查 DATABASE_URL 的主机名——容器网络里要用服务名而不是 localhost。

坑二：订阅链接打不开。 十有八九是 APP_URL 配置与实际访问地址不一致，或者反代没有正确转发。

坑三：升级后数据丢失。 没挂数据卷。PostgreSQL 数据和应用数据都在 volume 里，docker compose pull && docker compose up -d 升级前确认 volume 配置在。

部署完成后，下一步就是把你的订阅导入进来——见订阅聚合实战。