Community编程与开发github.com

Laravel Coolify Docker 部署

将 Laravel 应用容器化并部署到 Coolify——在本地构建镜像(包括 Apple Silicon → amd64 交叉编译),推送到 GitHub Container Registry (ghcr.io),并通过 Docker Compose 堆栈(Web + 队列工作者 + 调度器 + 数据库)运行。

Laravel Coolify Docker 部署 是什么?

该技能提供了一个完整的自动化工作流,用于将 Laravel 应用容器化并部署到 Coolify 及其他基于 Docker 的平台。核心流程包括:在您的机器上使用 `docker buildx` 构建针对 `linux/amd64` 的镜像(支持 Apple Silicon 交叉编译),将镜像推送到 `ghcr.io`,然后在服务器上通过 `docker-compose.prod.yml` 堆栈运行,无需在服务器上构建。它生成一个基于 `serversideup/php` 的多阶段 `Dockerfile`、包含应用、队列工作者、调度器和 MySQL 的 compose 文件、用于构建和推送的自动化脚本、本地测试配置以及全面的部署文档。该技能会扫描项目以确定 PHP 版本、扩展、队列名称、数据库需求,并修复常见问题,例如添加受信任的代理配置以解决 Coolify 的 TLS 终止问题、修复缺失 Linux 原生二进制文件的 npm lockfile,以及确保工作容器可见的文件存储卷。文档包含针对 Coolify、Dokploy、EasyPanel、CapRover 等平台的变体指南,以及详细的故障排除表,涵盖 Laravel 回退到 SQLite、无法连接 MySQL、排队任务不处理、由于代理导致http:// 资源损坏等典型问题。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/uluumbch/laravel-coolify-docker/tree/HEAD/skills/laravel-coolify-docker

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Laravel → Docker → GHCR → Coolify

目标设置:镜像在开发者的机器上构建,推送到 ghcr.io,服务器(Coolify)仅拉取并运行它,通过 compose 文件。不在服务器上构建,镜像中无密钥,所有配置来自环境变量。

工作站 ── docker buildx (linux/amd64) ──push──▶ ghcr.io/<所有者>/<仓库>:latest,:<sha>
                                                          │ 拉取
服务器 (Coolify) ── docker-compose.prod.yml ──▶ app (nginx+php-fpm :8080) · worker · [scheduler] · db

捆绑文件(复制并调整;占位符如 __IMAGE__):

路径用途
scripts/inspect_laravel.py <目录>只读项目扫描 → JSON 事实。首先运行此脚本。
scripts/repair_npm_lock.py <目录>修复缺少 Linux 原生二进制的 package-lock.json(需要 Docker)。
assets/Dockerfile基于 serversideup/php:<版本>-fpm-nginx 的多阶段镜像。
assets/dockerignore另存为 .dockerignore。
assets/docker-compose.prod.ymlapp + worker + (scheduler) + mysql,Coolify 指向的文件。
assets/docker-compose.prod.local.yml工作站覆盖:发布 :8080,无安全 cookie。
assets/env.docker.example另存为 .env.docker.example;本地和 Coolify 环境的模板。
assets/docker-build-push.sh另存为 scripts/docker-build-push.sh;构建 amd64 并推送 latest 和 git SHA 标签。
references/variants.mdPostgres/MariaDB、Redis、Horizon、Reverb、Octane、SSR、Wayfinder、pnpm/yarn/bun、Chromium、仅 SQLite。
references/coolify.md服务器上的 GHCR 认证、创建资源、域名 :8080、部署/更新/回滚。
references/other-platforms.mdDokploy、EasyPanel、CapRover、纯 Docker + Caddy、Kubernetes 笔记。
references/troubleshooting.md症状 → 原因 → 修复表格。出问题时阅读。
references/docs-template.md为您为项目编写的 docs/DOCKER_DEPLOYMENT.md 提供的提纲。

如果用户只有问题或故障(而非完整设置),直接转到 references/troubleshooting.md 或相关参考,而不是运行整个工作流。

工作流

1. 检查项目

python3 <技能目录>/scripts/inspect_laravel.py <项目目录>

它报告决定镜像和堆栈的事实。仔细阅读——每个字段映射到一个决策:

  • php.allowed — 每个锁定的包接受的 PHP 次要版本。为基础镜像标签选择最高允许的版本。如果为空,则锁定在任何单一版本上都无法满足;告诉用户哪些包阻止了(php.blocked_by)。不要仅仅因为 composer.json 说 ^8.2 就选择一个版本:传递性包(例如 openspout ~8.2||~8.3||~8.4,Symfony 8 >=8.4.1)会缩小范围,如果猜错,构建会在后期失败。
  • extensions.install_on_serversideup — 正好放入 install-php-extensions 的内容。gmp/bcmath 因 Web 推送一起出现;安装两者没问题。
  • extensions.system_binaries — 需要系统二进制文件的包(Chromium、wkhtmltopdf、ffmpeg)。检查代码是否实际使用它们,以免增加镜像体积(搜索类的引用);如果使用,请参见 references/variants.md。
  • queues — needs_worker 和 worker_queue_arg。工作器的 --queue= 必须列出每个命名队列(来自 onQueue、$queue、viaQueues()),否则那些作业将永远保留在表中,而默认队列工作器看起来健康。
  • scheduler.has_scheduled_tasks → 添加 scheduler 服务。
  • packages.key_packages → Horizon 替换工作器;Reverb 添加 WebSocket 服务;Octane 更改基础镜像(参见 variants)。
  • database — compose DB 服务的驱动程序。注意 config_default 通常是 sqlite:如果容器中未设置 DB_CONNECTION,Laravel 将静默使用 SQLite。因此 compose 文件显式设置了它。
  • frontend.npm_lock_missing_linux_binaries — 不空表示 npm ci 将在 Linux 中失败。运行 repair_npm_lock.py(步骤 3)。
  • frontend.vite_needs_php_at_build — Wayfinder 等需要在 Vite 构建期间使用 PHP;参见 variants。
  • proxy.bootstrap_trustProxies / legacy_TrustProxies_middleware — 步骤 3 的代理修复是否需要。
  • git.ghcr_image — 镜像名称(GHCR 要求小写)。
  • existing_files — 不要覆盖现有的 docker-compose.yml(通常是用于开发的 Sail);生产文件是 docker-compose.prod.yml。

还要浏览代码,查找扫描无法判断的内容:启动时访问数据库的提供者(会破坏构建期间的 composer dump-autoload / optimize)、使用 file_get_contents(asset(...)) 自身 URL 的代码、硬编码的 storage_path 假设。

2. 确认只有用户知道的几件事

简要询问(一轮),如果他们不关心则合理默认:

  • 服务器 CPU 架构 — 通常是 linux/amd64(大多数 VPS)。ARM 服务器(Hetzner CAX、Oracle Ampere、Graviton)→ linux/arm64。未知 → 多架构 linux/amd64,linux/arm64(构建较慢)。这一点很重要,因为在 Mac 上构建的 arm64 镜像无法在 amd64 服务器上启动(exec format error)。
  • 数据库:在 compose 堆栈中运行(最简单,推荐)或使用现有的/托管数据库(删除 mysql 服务,传递 DB_HOST)。
  • 任何应保留不变的内容(旧的部署工作流、Sail compose 文件)。

3. 让代码为容器做好准备

  • 信任代理。 Coolify 的 Traefik 终止 TLS 并转发 HTTP。如果不信任 X-Forwarded-*,Laravel 会生成 http:// URL(混合内容、Livewire/Filament 资源损坏、不安全 cookie、Web 推送失败)。Laravel 11+:在 bootstrap/app.php 中
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->trustProxies(at: '*');
    })
    
    Laravel ≤10:在 app/Http/Middleware/TrustProxies.php 中设置 protected $proxies = '*';。'*' 是安全的,仅因为端口 8080 从未发布到互联网——在文档中说明这一点。
  • 修复 npm lockfile(如果扫描标记了它):
    python3 <技能目录>/scripts/repair_npm_lock.py <项目目录>
    
    它仅重新解析原生二进制包(rollup、esbuild、lightningcss、Tailwind oxide、swc、sass-embedded);向用户报告它打印的版本升级。
  • .env.example:添加应用读取但示例中缺少的键(比较 config/ 中的 env( 调用与文件),以便部署文档完整。
  • .gitignore:添加 .env.docker。

4. 生成 Docker 文件

从 assets/ 复制到项目中并填充占位符:__IMAGE__、__REPO_URL__(https GitHub URL,将 GHCR 包链接到仓库)、__APP_NAME__、__PHP_VERSION__、__PHP_EXTENSIONS__、__QUEUES__。然后调整:

  • 如果没有任何作业排队,则删除 worker 服务;如果有计划任务,则取消注释 scheduler。
  • 根据 references/variants.md 将 DB 服务/环境变量替换为 Postgres、MariaDB 或 Redis。
  • 将特定于应用的 env 键(API 密钥、VAPID、S3)添加到 x-app-env 锚点,格式为 ${VAR:-};将真正必需的标记为 ${VAR:?msg},这样缺少值时会响亮地失败,而不是半配置启动。
  • 将 APP_TIMEZONE 默认值设置为应用的 config/app.php 中的默认值。
  • 包管理器不是 npm、没有 package.json、SSR、Chromium → references/variants.md。

模板中内置的设计决策(除非有理由,否则保留它们):

  • serversideup/php 以非 root www-data 身份在 :8080 上提供 NGINX+FPM,提供 /up 健康检查、healthcheck-queue/healthcheck-schedule,以及运行 storage:link、等待数据库、migrate --force 和 php artisan optimize(包括 filament:optimize 和其他包的优化钩子)的 AUTORUN_ENABLED。只有 app 服务设置 AUTORUN_ENABLED=true,因此迁移只运行一次;工作者/调度器等待 app 健康。
  • 在 $BUILDPLATFORM 上的 Assets 阶段——在 Mac 上本地运行,PHP 阶段则为 amd64 模拟;输出与架构无关。
  • 复制源代码前安装 Composer——依赖层保持缓存;仅代码重建即使在模拟下也很快。
  • app + worker (+ scheduler) 共用一个 storage/app 卷——工作者写入的文件必须对 Web 容器可见。
  • 日志输出到 stderr,以便平台的日志查看器能够显示它们。

5. 在推送任何内容前在本地验证

必须实际执行——不要止步于“Dockerfile 看起来正确”。使用 compose 项目名称,以免与开发容器冲突。

docker buildx build --load -t <名称>:test .                       # 原生架构,快速
docker run --rm --entrypoint php <名称>:test -m                  # 扩展存在吗?
docker run --rm --entrypoint php <名称>:test artisan key:generate --show
cp .env.docker.example .env.docker   # APP_IMAGE=<名称>, IMAGE_TAG=test, PULL_POLICY=never, 密钥, 密码
docker compose -p <名称>test --env-file .env.docker -f docker-compose.prod.yml -f docker-compose.prod.local.yml up -d --wait

(--entrypoint php 跳过 serversideup 的横幅/自动化,因此一次性命令输出纯净。)

检查,并报告每个结果:

  1. 所有服务 healthy;app 日志显示 storage:link、迁移、optimize,无 ❌。
  2. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up → 200;登录/首页 → 200,且其 CSS/JS URL 返回 200。
  3. 代理:curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<页面> → 资源 URL 以 https://x.example.com 开头。
  4. php artisan db:seed --force(如果应用具有用户期望在首次安装时运行的种子数据)。
  5. 队列:将真实的排队类(来自应用的通知/作业)分发到每个命名队列,并确认工作者日志输出 DONE 并且副作用已发生。从 tinker --execute 分发的闭包会在工作者中失败(评估的代码无法反序列化)——这是测试工件,不是错误。在选择测试收件人时也要注意应用自己的 shouldSend/授权。
  6. 存储:从工作者向 public 磁盘写入文件,通过 localhost:8080/storage/... 从 app 获取,然后 down + up 并确认文件和数据库行持久存在。
  7. 为服务器进行交叉编译:docker buildx build --platform linux/amd64 -t <名称>:amd64 --load . 然后 docker image inspect <名称>:amd64 --format '{{.Architecture}}'。在后台运行它——QEMU 构建需要几分钟。

完成后使用 docker compose -p <名称>test down -v 拆除。

6. 编写部署文档

创建 docs/DOCKER_DEPLOYMENT.md,遵循 references/docs-template.md,使用项目现有文档的语言,并从 README.md 链接。文档必须解释每个文件的变更内容和原因(用户创建此技能时要求了这一点,未来的维护者也需要)、架构、一次性设置、构建/推送、本地测试、Coolify 步骤、更新/回滚、运维、从旧主机迁移数据以及您在步骤 1 中发现的特定于项目的注意事项。

7. 交接——在面向外部的任何操作前确认

推送到 GHCR 会发布镜像,部署会改变生产环境,因此停下来让用户决定。给他们:

  1. echo <具有 write:packages 权限的 PAT> | docker login ghcr.io -u <用户> --password-stdin
  2. 提交,然后 scripts/docker-build-push.sh(拒绝脏的工作树;--load 用于仅本地构建)。
  3. 来自 references/coolify.md 的 Coolify 步骤——特别是服务器需要为私有包提供只读 GHCR 登录,使用 sudo docker login 完成(Coolify 以 root 身份拉取;非 root 登录对其不可见),以及域名输入为 https://domain:8080(:8080 = 容器端口)。
  4. 提醒:迁移时重复使用旧的 APP_KEY(以及 VAPID 或其他长期密钥);在新部署上线后禁用任何旧的 SSH/FTP 部署工作流。

一旦他们登录,提供为他们运行推送的服务。

常见的用户混淆及预防

用户经常尝试 docker run <镜像> 或 Docker Desktop 的 ▶ 按钮仅针对镜像。这仅启动 Web 容器:没有数据库服务存在,自动运行关闭,Laravel 回退到 sqlite(Database file at path [...] does not exist)或无法解析 mysql。答案始终是 compose 堆栈。在文档的本地测试部分说明这一点。

相关技能