如何用 Docker 自托管 Super Productivity 的 SuperSync 同步服务器并验证数据库迁移与服务健康【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivitySuper Productivity 自带的同步走的是 WebDAV而packages/super-sync-server提供的是一个独立的、基于操作日志Event Sourcing的自托管同步服务器供 Super Productivity 客户端的 Custom Sync 接入。本文的目标是在一台部署主机上用 Docker Compose 完成一次可复现的部署配置.env、运行deploy.sh它会先执行 Prisma 数据库迁移再替换应用容器并验证健康端点最后用文档给出的输出与/health端点判断迁移和服务是否成功。部署主机需要准备 Docker含 Compose 插件、curl、git、jq并且镜像修订检查要求 Compose 支持docker compose config --format json。部署前提域名、镜像标签与主机条件域名Caddy 反代会为DOMAIN自动申请 SSL 证书所以部署前需要先把一个可解析到该主机的域名指过来例如sync.your-domain.com。镜像没有 release tagghcr.io/super-productivity/supersync只发布latest和master-sha两种标签二者都构建自master默认部署跟踪的是上游master而不是某个发布版本。需要固定版本时把.env里的SUPERSYNC_IMAGE钉到某个master-sha标签。数据库版本下限受支持且 CI 与生产环境使用 PostgreSQL 16compose 里捆绑postgres:16-alpine14、15 仍可运行并会应用所有迁移但不在测试覆盖范围内。Linux 主机上的 PostgreSQL 14 是硬性下限——迁移管线会在连接上设置client_connection_check_interval更老或非 Linux 的服务器会以unrecognized configuration parameter的 FATAL 错误拒绝每条迁移连接。资源默认容器内存上限是应用 768m、Postgres 1536m、Caddy 256m。若用--build在部署机本地编译镜像还需要额外几分钟时间和约 1.5 GB 以上峰值内存外加每构建增长约 1.4 GB 且不会被自动清理的 BuildKit 缓存——小 VPS 上 README 建议直接拉取官方镜像。复制并配置 .env进入packages/super-sync-server目录后把env.example复制为.env并编辑cd packages/super-sync-server cp env.example .env必须设置的项env.example 中这几项刻意留空服务器会拒绝启动变量要求DOMAIN你的域名不带https://如sync.your-domain.comJWT_SECRET必填最少 32 字符。用openssl rand -base64 32生成POSTGRES_PASSWORD必填捆绑 Postgres 容器没有它无法初始化。用openssl rand -base64 24生成PUBLIC_URL带协议的公网地址如https://sync.your-domain.com。生产环境Docker 下NODE_ENV默认production必须以https://开头否则服务器拒绝启动与登录直接相关的可选项WEBAUTHN_RP_ID域名不带协议/端口与WEBAUTHN_ORIGIN带协议启用 passkey 登录时必填。passkey 绑定在WEBAUTHN_RP_ID上日后改值会使所有已注册凭据失效。SMTP 一组变量SMTP_HOST、SMTP_PORT、SMTP_SECURE、SMTP_USER、SMTP_PASS、SMTP_FROM生产环境的账号创建与登录走 passkey 或邮件 magic link没有密码式/api/register、/api/login。要让用户能收到验证/登录链接就必须配置 SMTP。CORS_ORIGINS默认https://app.super-productivity.com自托管前端时把前端 URL 加进去生产环境不要用*CORS 以credentials: true运行。数据库连接使用捆绑 Postgres 时保持DATABASE_URL不设置默认连接串指向postgres:5432旧的db:5432仍作为网络别名兼容。指向外部 PostgreSQL 时设置DATABASE_URL并把POSTGRES_SERVICE置为空值deploy.sh就会只启动应用与反代服务外部库记得追加?connection_limitNpool_timeout10来限定 Prisma 连接池。执行 deploy.sh 完成迁移与启动完整部署路径是运行仓库提供的脚本而不是直接docker compose up原因见后文限制一节# 1. 获取源码并进入服务器目录如需要 clone 地址https://gitcode.com/GitHub_Trending/su/super-productivity cd packages/super-sync-server # 2. 部署拉取镜像、执行迁移、启动并验证健康 ./scripts/deploy.shdeploy.sh 会依次做这些事用 compose 文件里的 Caddy 镜像执行caddy validate校验 Caddyfile先git pull --ff-only更新本地检出脚本自身的副作用会更新工作区文件再拉取supersync镜像本地构建用./scripts/deploy.sh --build且要求镜像输入文件无未提交/未跟踪变更核对镜像的org.opencontainers.image.revision标签与最新影响镜像输入的提交一致防止对旧镜像跑新迁移。自建镜像可传相同VCS_REF或在明确知情的情况下设置SUPERSYNC_SKIP_IMAGE_REVISION_CHECKtruedocker compose up -d --wait确保 Postgres 就绪默认等待 60s再用一次性容器执行SELECT 1验证数据库连通在替换应用容器之前运行迁移一次性 migrator 容器执行镜像内的 scripts/migrate-deploy.sh内部即prisma migrate deploy加受控恢复逻辑整体超时由MIGRATION_TIMEOUT默认 900 秒控制以RUN_MIGRATIONS_ON_STARTUPfalse启动全部容器并--wait所有健康检查默认等 900s可用DEPLOY_WAIT_TIMEOUT调整对$DOMAIN的/health做 HTTPS 检查最多 6 次、每次间隔 5 秒。如何判断数据库迁移成功迁移结果直接体现在脚本输出与退出码上成功路径依次看到 Applying database migrations before app restart (timeout: 900s)...、 Starting containers (wait timeout: 900s)...与All containers healthy。全新数据库不需要任何手工处理——迁移链以0_init基线开头migrate deploy会自动应用基线和后续全部迁移。退出码124表示迁移超时通常是CREATE INDEX CONCURRENTLY被长事务阻塞。处理方式是清除阻塞事务后重跑或对大表调高MIGRATION_TIMEOUTREADME 建议 3600 作为大 operations 表的起点。超时的 migrator 容器会被强制移除所以过低的时间值不会再把下一次部署卡死在P1002咨询锁上。P3009迁移被记录为失败与P3018CREATE/DROP INDEX CONCURRENTLY不能在事务块内执行由migrate-deploy.sh自动处理它解析失败记录、在 Prisma 之外应用 SQL、标记已应用并重试。凡是两种受控恢复形态都不匹配的其他失败脚本会停下并打印手工恢复步骤此时按打印的步骤操作不要自行猜测。被锁约束的 reloption 型迁移自己设置短lock_timeout的那类会快速失败而不是排队并在原生范围内有限次重试如果全部尝试都超时该迁移保持回滚状态需要清除阻塞事务后重跑部署。验证服务健康deploy.sh末尾会输出部署是否成功这就是最直接的验证方式 Deployment successful! Service is healthy at https://sync.your-domain.com/health失败时脚本会打印 Health check failed!并用docker compose logs --tail30给出最近日志。容器层面还有三层健康检查定义在 docker-compose.ymlsupersync每 30s 用wget --spider http://localhost:1900/health启动宽限 30spostgrespg_isready加psql -c SELECT 1间隔 10scaddy探测 admin APIhttp://127.0.0.1:2019/config/间隔 30s。你也可以手动复核DOMAIN已设置时走 HTTPS未设置时脚本回退到http://localhost:1900/healthcurl -sf https://sync.your-domain.com/health部署成功后把 Super Productivity 客户端的Custom Sync提供方指向该实例Base URL填你的部署地址如https://sync.your-domain.comAuth Token填登录得到的 JWT。已知限制与常见坑docker compose up不能替代部署。RUN_MIGRATIONS_ON_STARTUP默认false容器启动迁移被禁用所以docker compose pull docker compose up -d可能让应用跑在未应用迁移的库上。生产更新一律走./scripts/deploy.sh。镜像修订检查失败时报The supersync image revision does not match the expected source revision等 GHCR 镜像构建完成、构建并推送当前镜像或改用--build跳过检查只应用于有意识的手工覆盖。旧库基线问题早于0_init基线创建的数据库必须先告诉 Prisma 其 schema 已反映了哪些迁移有 Prisma 历史的库用npx prisma migrate resolve --applied 0_initprisma db push创建的库另有 README 给出的完整流程否则下次migrate deploy会因relation users already exists/P3005失败。法律页面镜像不带服务条款隐私政策要五个PRIVACY_*变量全设置才发布/privacy.html只设一部分是启动错误而不是静默回退。上线后的数据库备份建议见 Backup Disaster Recoveryscripts/backup.sh生成全量与仅账号两类 dump。【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考