Coolify 是一个开源、可自托管的平台即服务(PaaS),用于通过 Docker 在自己的服务器上部署应用、数据库和服务。文档地址为 https://coolify.io/docs/llms.txt。
主要能力与用法:面向自托管部署,应用、数据库与服务以 Docker 方式运行;提供界面配置域名、卷等部署要素。
必要注意事项(来自资料):
- 零停机部署需要健康检查。Traefik 在端口开放时就转发流量,而非应用就绪时。缺少显式健康检查(Dockerfile HEALTHCHECK 或界面配置)时,请求会在容器启动中或迁移完成前到达。依赖滚动更新前务必配置健康检查端点。
- Destinations 是隔离的 Docker 网络,不同 Destination 上的服务无法通过容器名互相访问。例如位于 destination-a 的数据库与位于 destination-b 的应用需要显式配置 DNS 或 IP。不能假设所有服务在同一网络(如 Heroku/Railway 的默认行为)。
- 持久卷路径必须与容器写入路径完全一致。若应用写入 /app/data,在界面挂载 /data 无效。绑定挂载需要容器内路径精确匹配,符号链接与相对路径无法在容器重启后保留。配置卷前请核实容器真实写入路径。
- Nixpacks 在私有仓库或 .npmrc 场景下会静默失败。自动检测适用于标准公开项目,但会跳过 .npmrc、私有包仓库和非标准 monorepo 布局且无明确报错。若本地构建成功而 Coolify 中 Nixpacks 失败,改用 Dockerfile 并以构建时环境变量传入仓库凭据。
- 在尝试 Let's Encrypt 挑战前 DNS 必须能解析。配置域名后 Coolify 会立即尝试 ACME 挑战;若 DNS 未传播,挑战会失败并重试数小时且无显著告警。添加域名前请从外部验证 DNS 解析,通配符证书需通过 Cloudflare 或 Hetzner 的 DNS-01。
- 入口 shell 脚本必须显式转发 SIGTERM。滚动更新会向旧容器发送 SIGTERM 以优雅关闭;shell 入口脚本默认不转发信号,会导致容器在超时后被杀死。应在脚本最后使用 exec(如 exec "$@")或显式处理信号。