用 Docker Compose 部署

用 compose.yaml 在自己的服务器上运行项目:设置公网地址,启动并迁移,在前面加上 TLS,并创建线上管理员。

在 Docker 主机上,项目是一组 compose 服务:migrate 服务应用迁移后退出,web 服务由根目录的 Dockerfile 构建,数据库是挂在卷上的 SQLite 文件或自带的 Postgres。agent 服务可选,作为 compose 服务运行,且只支持 Postgres。整个过程不创建任何远程资源。在自己管理的服务器上首次部署时使用本指南。

准备工作

  • 一台装有 Docker 和 Docker Compose 的服务器(docker compose version 有输出),项目已检出到上面。
  • deploy.config.json 中是 "platform": "docker"。执行 pnpm kernlift deploy-target docker 来设置,按需加上 --dialect sqlite、--dialect postgres 或 --agent。见 deploy.config.json。
  • 项目根目录有 compose.yaml 和 .env.production,这条命令会写出它们。.env.production 不进仓库,需要你自己拷到服务器上。
  • 一个指向该服务器的域名,以及负责 TLS 的反向代理。

准备各项值

设置公网地址

在 .env.production 里把 SITE_URL 设为公网地址,例如 https://your-domain.com。不设置时 web 服务回退到 http://localhost:3000。应用首次启动时还会用它初始化认证的 基础 URL,OAuth 回调和邮件链接就会指向那里。

检查生成的密钥

同一个文件里必须有 BETTER_AUTH_SECRET 和 CONFIG_ENCRYPTION_KEY,数据库是 Postgres 时还要有 POSTGRES_PASSWORD。包含 agent 时还有 AGENT_INTERNAL_SIGNING_SECRET 和 AGENT_RESOURCE_GRANT_SECRET。缺少其中任何一个,Compose 都会启动失败。要补上缺失的键而不改动已有的值,再执行一次 pnpm kernlift deploy-target docker。

启动

构建、迁移并启动

pnpm run deploy

该脚本执行:

docker compose --env-file .env.production up -d --build

migrate 服务先执行 node scripts/db/migrate-runtime.mjs,成功后 web 才启动。使用 Postgres 时,migrate 会等 postgres 服务健康后再执行。

在前面加上 TLS

web 服务对外发布 3000 端口。把反向代理指向它,用你填在 SITE_URL 里的地址以 HTTPS 提供站点。

创建线上管理员

docker compose --env-file .env.production exec web node .output/scripts/bootstrap-super-admin.mjs

脚本在 web 容器内运行,针对它自己的数据库,并提示输入邮箱和密码。

数据放在哪里

数据库服务卷
sqlite无;web 直接打开 /data/app.dbdata
postgrespostgres,镜像 postgres:16-alpine,用户与库名均为 kernliftpgdata

请备份这些卷,删除卷会删除数据库。用户上传的文件不存放在服务器上,需要在 /admin/config/storage 配置 S3 兼容存储,见配置文件存储与上传。

"agent": true 时,还会有一个由 apps/agent-service/Dockerfile 构建的 agent 服务。web 服务在 compose 网络里通过 http://agent:3001 访问它,它不对外发布端口。只运行一个实例,因为它在内存里保存运行状态。

发布新版本

拉取新代码后再执行一次 pnpm run deploy。镜像会重新构建,migrate 应用新增的迁移,成功后 web 被替换。

验证

  • docker compose ps 显示 web 在运行,migrate 已成功退出。
  • 站点可以通过 HTTPS 在你的域名上打开。
  • 以管理员身份打开 /setup,第一行写明 Docker 和所用数据库,会话密钥为就绪。
  • /admin/config/auth 里的 基础 URL 是站点实际对外的地址。站点用的是另一个域名时,在那里改掉。
  • 定时任务在一两分钟内变为就绪。定时任务在 web 容器里运行。
  • 包含 agent 时,/app/agent 打开工作台。
  • 在仓库里,pnpm build:node 之后的 pnpm smoke:node 检查你要发布的构建,pnpm validate:deploy-targets 检查渲染出的 compose.yaml。

故障排查

Compose 报 set BETTER_AUTH_SECRET、set CONFIG_ENCRYPTION_KEY 或 set POSTGRES_PASSWORD 后停止

.env.production 里缺少该值,或者执行命令时没有带 --env-file .env.production。使用 pnpm run deploy。

OAuth 登录或邮件链接指向 localhost:3000

/admin/config/auth 里的 基础 URL 还是回退地址。在那里改正。同时在 .env.production 里设置 SITE_URL,再执行 pnpm run deploy,让元数据和绝对链接也使用公网地址。

web 一直不启动

migrate 失败了。用 docker compose logs migrate 查看它的输出。

/setup 上定时任务一直未就绪

用 docker compose ps 检查 web 容器是否在运行。如果设置了 JOBS_IN_PROCESS=false,就必须由外部 cron 执行 pnpm jobs:run。

下一步