Sub2API 部署时配置已有 PostgreSQL 与 Redis 的方案及后期迁移指南一、概述Sub2API 支持两种部署方式Docker Compose 容器化部署和二进制直接部署。无论采用哪种方式都可以配置使用已有的外部 PostgreSQL 和 Redis 服务而非使用项目自带的数据库容器。这种方案的优势在于统一数据管理多个服务共享同一数据库实例便于统一备份和维护简化迁移流程数据库独立于应用容器迁移时只需处理数据层资源利用率高避免为每个应用重复部署数据库容器节省系统资源二、配置使用已有数据库部署阶段2.1 Docker Compose 部署方案如果使用 Docker Compose 部署 Sub2API需要修改docker-compose.yml移除自带的 db 和 redis 服务改用外部连接。步骤 1修改 docker-compose.ymlversion:3.8services:sub2api:image:weishaw/sub2api:latestcontainer_name:sub2apirestart:unless-stoppedports:-8080:8080volumes:-./data:/app/data-./logs:/app/logsenv_file:-.env# 移除 depends_on 中 db 和 redis 的依赖mem_limit:800m# 不再需要 db 和 redis 服务定义步骤 2配置 .env 文件Sub2API 通过环境变量连接数据库和缓存。在.env中配置如下# PostgreSQL 外部连接DATABASE_DSNpostgres://用户名:密码数据库主机:5432/数据库名?sslmodedisable# Redis 外部连接REDIS_ADDRRedis主机:6379REDIS_PASSWORD你的Redis密码REDIS_DB0# JWT / Session 密钥自行生成随机串JWT_SECRETyour_random_32char_stringSESSION_SECRETyour_another_random_string# 时区TZAsia/Shanghai字段说明变量名说明示例DATABASE_DSNPostgreSQL 完整连接串postgres://sub2api:Pass123192.168.1.100:5432/sub2api?sslmodedisableREDIS_ADDRRedis 服务地址和端口redis:6379或192.168.1.100:6379REDIS_PASSWORDRedis 密码无密码则留空MyRedisPass123REDIS_DBRedis 数据库编号0注意DATABASE_DSN也可以替换为DATABASE_URL变量两者等价。sslmodedisable适用于内网环境公网访问建议启用 SSL。2.2 二进制部署方案如果使用官方install.sh脚本将 Sub2API 直接安装在宿主机上可通过 Web 设置向导配置外部数据库。步骤 1安装 Sub2APIcurl-sSLhttps://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh|sudobashsudosystemctlenablesub2api--now步骤 2通过 Web 向导配置访问http://你的服务器IP:8080进入设置向导页面填写以下信息配置项填写值PostgreSQL 主机数据库服务器 IP本地填127.0.0.1PostgreSQL 端口5432数据库名已创建的数据库名如sub2api用户名数据库用户密码数据库密码Redis 主机Redis 服务器 IP本地填127.0.0.1Redis 端口6379Redis 密码Redis 密码Redis DB建议使用1如与其他应用共用 Redis错开编号2.3 外部数据库准备注意事项PostgreSQL 配置要点允许远程连接修改postgresql.conf中的listen_addresses *配置访问权限在pg_hba.conf中添加允许应用服务器 IP 的访问规则高版本权限问题PostgreSQL 15 中新用户默认无法在publicschema 建表需手动授予权限-- 以 postgres 管理员身份执行GRANTALLONSCHEMApublicTOyour_sub2api_user;Redis 配置要点允许外部访问修改redis.conf中bind 127.0.0.1为bind 0.0.0.0或指定应用服务器 IP设置密码配置requirepass参数增强安全性三、后期迁移方案当需要将 Sub2API 迁移到新服务器时可以采用以下两种方案。3.1 方案一完整数据导出与导入适用于大多数场景步骤 1备份数据库在旧服务器上导出 PostgreSQL 数据# 使用 pg_dump 导出完整数据库pg_dump-Usub2api-hlocalhost-dsub2api-Fc-f/backups/sub2api_backup.dump# 或导出为 SQL 格式便于跨版本恢复pg_dump-Usub2api-hlocalhost-dsub2api/backups/sub2api_backup.sql步骤 2备份 Redis 数据# 触发 RDB 持久化redis-cli-a你的密码 BGSAVE# 复制 dump.rdb 文件默认在 /var/lib/redis/ 目录cp/var/lib/redis/dump.rdb /backups/步骤 3备份应用数据目录# 备份 Sub2API 数据目录含配置文件、上传文件等tar-czf/backups/sub2api_data.tar.gz /opt/sub2api/data/步骤 4在新服务器上恢复恢复 PostgreSQL# 新服务器创建空数据库createdb-Upostgres sub2api# 恢复数据根据备份格式选择pg_restore-Usub2api-dsub2api /backups/sub2api_backup.dump# 或psql-Usub2api-dsub2api/backups/sub2api_backup.sql恢复 Redis# 停止 Redis替换 dump.rdb重启systemctl stop rediscp/backups/dump.rdb /var/lib/redis/ systemctl start redis恢复应用数据tar-xzf/backups/sub2api_data.tar.gz-C/opt/sub2api/3.2 方案二低停机迁移使用 PostgreSQL 主从同步适用于对停机时间要求严格的场景利用 PostgreSQL 原生流复制实现近零停机迁移。整体思路在新服务器上部署 PostgreSQL 作为从库与旧库建立同步等待数据完全同步后将从库提升为主库切换应用连接至新数据库具体操作步骤步骤 1建立 SSH 隧道连接旧库# 将旧服务器数据库端口映射到新服务器本地 5433 端口exportOLD_IP旧服务器IPssh-fN-L127.0.0.1:5433:172.19.0.3:5432 root$OLD_IP步骤 2在新服务器上准备数据卷# 停止并清空 PostgreSQL 数据目录dockercompose downdockervolumermindex_postgres_datadockervolume create index_postgres_data步骤 3使用 pg_basebackup 初始化从库dockerrun--rm--networkhost-vindex_postgres_data:/var/lib/postgresql/data\postgres:15-alpinesh-lc\rm -rf /var/lib/postgresql/data/* \ pg_basebackup -h 127.0.0.1 -p 5433 -U sub2api -D /var/lib/postgresql/data \ -Fp -Xs -P -R --checkpointfast \ chown -R postgres:postgres /var/lib/postgresql/data步骤 4启动从库并配置同步dockercompose up-dpostgres# 更新 primary_conninfodockercomposeexecpostgres psql-Usub2api-dsub2api\-calter system set primary_conninfo host旧服务器IP port5432 usersub2api sslmodedisabledockercompose restart postgres步骤 5确认同步完成并提升为主库# 查询 WAL 接收状态确认 latest_end_time 已接近当前时间dockercomposeexecpostgres psql-Usub2api-dsub2api\-cselect status, latest_end_time from pg_stat_wal_receiver;# 提升为主库dockercomposeexecpostgres pg_ctl promote-D/var/lib/postgresql/data# 确认已成为主库返回 f 表示已提升dockercomposeexecpostgres psql-Usub2api-dsub2api\-cselect pg_is_in_recovery();步骤 6启动完整服务dockercompose up-d3.3 迁移后验证完成迁移后建议执行以下验证验证项命令数据库连接测试docker compose exec postgres pg_isreadyRedis 连接测试docker compose exec redis redis-cli ping应用健康检查curl -I http://localhost:8080/health数据一致性对比对比迁移前后SELECT COUNT(*) FROM users结果查看应用日志docker compose logs --tail100 sub2api四、总结与建议环节关键要点部署配置修改.env或 Web 向导将DATABASE_DSN和REDIS_ADDR指向已有服务地址PostgreSQL 准备开启远程访问、配置pg_hba.conf、PostgreSQL 15 需手动授予publicschema 权限Redis 准备修改bind和requirepass建议使用0以外的 DB 编号数据备份定期使用pg_dump和 RedisBGSAVE同时备份应用数据目录迁移策略小规模迁移使用pg_dump/psql大规模/低停机场景使用 PostgreSQL 流复制推荐部署使用docker-compose.local.yml本地目录挂载版迁移时可直接tar打包整个数据目录安全提醒无论采用哪种方式部署务必确保 PostgreSQL5432和 Redis6379端口不直接暴露到公网仅允许应用服务器 IP 访问避免安全风险。
Sub2API 部署时配置已有 PostgreSQL 与 Redis 的方案及后期迁移指南一、概述Sub2API 支持两种部署方式Docker Compose 容器化部署和二进制直接部署。无论采用哪种方式都可以配置使用已有的外部 PostgreSQL 和 Redis 服务而非使用项目自带的数据库容器。这种方案的优势在于统一数据管理多个服务共享同一数据库实例便于统一备份和维护简化迁移流程数据库独立于应用容器迁移时只需处理数据层资源利用率高避免为每个应用重复部署数据库容器节省系统资源二、配置使用已有数据库部署阶段2.1 Docker Compose 部署方案如果使用 Docker Compose 部署 Sub2API需要修改docker-compose.yml移除自带的 db 和 redis 服务改用外部连接。步骤 1修改 docker-compose.ymlversion:3.8services:sub2api:image:weishaw/sub2api:latestcontainer_name:sub2apirestart:unless-stoppedports:-8080:8080volumes:-./data:/app/data-./logs:/app/logsenv_file:-.env# 移除 depends_on 中 db 和 redis 的依赖mem_limit:800m# 不再需要 db 和 redis 服务定义步骤 2配置 .env 文件Sub2API 通过环境变量连接数据库和缓存。在.env中配置如下# PostgreSQL 外部连接DATABASE_DSNpostgres://用户名:密码数据库主机:5432/数据库名?sslmodedisable# Redis 外部连接REDIS_ADDRRedis主机:6379REDIS_PASSWORD你的Redis密码REDIS_DB0# JWT / Session 密钥自行生成随机串JWT_SECRETyour_random_32char_stringSESSION_SECRETyour_another_random_string# 时区TZAsia/Shanghai字段说明变量名说明示例DATABASE_DSNPostgreSQL 完整连接串postgres://sub2api:Pass123192.168.1.100:5432/sub2api?sslmodedisableREDIS_ADDRRedis 服务地址和端口redis:6379或192.168.1.100:6379REDIS_PASSWORDRedis 密码无密码则留空MyRedisPass123REDIS_DBRedis 数据库编号0注意DATABASE_DSN也可以替换为DATABASE_URL变量两者等价。sslmodedisable适用于内网环境公网访问建议启用 SSL。2.2 二进制部署方案如果使用官方install.sh脚本将 Sub2API 直接安装在宿主机上可通过 Web 设置向导配置外部数据库。步骤 1安装 Sub2APIcurl-sSLhttps://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh|sudobashsudosystemctlenablesub2api--now步骤 2通过 Web 向导配置访问http://你的服务器IP:8080进入设置向导页面填写以下信息配置项填写值PostgreSQL 主机数据库服务器 IP本地填127.0.0.1PostgreSQL 端口5432数据库名已创建的数据库名如sub2api用户名数据库用户密码数据库密码Redis 主机Redis 服务器 IP本地填127.0.0.1Redis 端口6379Redis 密码Redis 密码Redis DB建议使用1如与其他应用共用 Redis错开编号2.3 外部数据库准备注意事项PostgreSQL 配置要点允许远程连接修改postgresql.conf中的listen_addresses *配置访问权限在pg_hba.conf中添加允许应用服务器 IP 的访问规则高版本权限问题PostgreSQL 15 中新用户默认无法在publicschema 建表需手动授予权限-- 以 postgres 管理员身份执行GRANTALLONSCHEMApublicTOyour_sub2api_user;Redis 配置要点允许外部访问修改redis.conf中bind 127.0.0.1为bind 0.0.0.0或指定应用服务器 IP设置密码配置requirepass参数增强安全性三、后期迁移方案当需要将 Sub2API 迁移到新服务器时可以采用以下两种方案。3.1 方案一完整数据导出与导入适用于大多数场景步骤 1备份数据库在旧服务器上导出 PostgreSQL 数据# 使用 pg_dump 导出完整数据库pg_dump-Usub2api-hlocalhost-dsub2api-Fc-f/backups/sub2api_backup.dump# 或导出为 SQL 格式便于跨版本恢复pg_dump-Usub2api-hlocalhost-dsub2api/backups/sub2api_backup.sql步骤 2备份 Redis 数据# 触发 RDB 持久化redis-cli-a你的密码 BGSAVE# 复制 dump.rdb 文件默认在 /var/lib/redis/ 目录cp/var/lib/redis/dump.rdb /backups/步骤 3备份应用数据目录# 备份 Sub2API 数据目录含配置文件、上传文件等tar-czf/backups/sub2api_data.tar.gz /opt/sub2api/data/步骤 4在新服务器上恢复恢复 PostgreSQL# 新服务器创建空数据库createdb-Upostgres sub2api# 恢复数据根据备份格式选择pg_restore-Usub2api-dsub2api /backups/sub2api_backup.dump# 或psql-Usub2api-dsub2api/backups/sub2api_backup.sql恢复 Redis# 停止 Redis替换 dump.rdb重启systemctl stop rediscp/backups/dump.rdb /var/lib/redis/ systemctl start redis恢复应用数据tar-xzf/backups/sub2api_data.tar.gz-C/opt/sub2api/3.2 方案二低停机迁移使用 PostgreSQL 主从同步适用于对停机时间要求严格的场景利用 PostgreSQL 原生流复制实现近零停机迁移。整体思路在新服务器上部署 PostgreSQL 作为从库与旧库建立同步等待数据完全同步后将从库提升为主库切换应用连接至新数据库具体操作步骤步骤 1建立 SSH 隧道连接旧库# 将旧服务器数据库端口映射到新服务器本地 5433 端口exportOLD_IP旧服务器IPssh-fN-L127.0.0.1:5433:172.19.0.3:5432 root$OLD_IP步骤 2在新服务器上准备数据卷# 停止并清空 PostgreSQL 数据目录dockercompose downdockervolumermindex_postgres_datadockervolume create index_postgres_data步骤 3使用 pg_basebackup 初始化从库dockerrun--rm--networkhost-vindex_postgres_data:/var/lib/postgresql/data\postgres:15-alpinesh-lc\rm -rf /var/lib/postgresql/data/* \ pg_basebackup -h 127.0.0.1 -p 5433 -U sub2api -D /var/lib/postgresql/data \ -Fp -Xs -P -R --checkpointfast \ chown -R postgres:postgres /var/lib/postgresql/data步骤 4启动从库并配置同步dockercompose up-dpostgres# 更新 primary_conninfodockercomposeexecpostgres psql-Usub2api-dsub2api\-calter system set primary_conninfo host旧服务器IP port5432 usersub2api sslmodedisabledockercompose restart postgres步骤 5确认同步完成并提升为主库# 查询 WAL 接收状态确认 latest_end_time 已接近当前时间dockercomposeexecpostgres psql-Usub2api-dsub2api\-cselect status, latest_end_time from pg_stat_wal_receiver;# 提升为主库dockercomposeexecpostgres pg_ctl promote-D/var/lib/postgresql/data# 确认已成为主库返回 f 表示已提升dockercomposeexecpostgres psql-Usub2api-dsub2api\-cselect pg_is_in_recovery();步骤 6启动完整服务dockercompose up-d3.3 迁移后验证完成迁移后建议执行以下验证验证项命令数据库连接测试docker compose exec postgres pg_isreadyRedis 连接测试docker compose exec redis redis-cli ping应用健康检查curl -I http://localhost:8080/health数据一致性对比对比迁移前后SELECT COUNT(*) FROM users结果查看应用日志docker compose logs --tail100 sub2api四、总结与建议环节关键要点部署配置修改.env或 Web 向导将DATABASE_DSN和REDIS_ADDR指向已有服务地址PostgreSQL 准备开启远程访问、配置pg_hba.conf、PostgreSQL 15 需手动授予publicschema 权限Redis 准备修改bind和requirepass建议使用0以外的 DB 编号数据备份定期使用pg_dump和 RedisBGSAVE同时备份应用数据目录迁移策略小规模迁移使用pg_dump/psql大规模/低停机场景使用 PostgreSQL 流复制推荐部署使用docker-compose.local.yml本地目录挂载版迁移时可直接tar打包整个数据目录安全提醒无论采用哪种方式部署务必确保 PostgreSQL5432和 Redis6379端口不直接暴露到公网仅允许应用服务器 IP 访问避免安全风险。
