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.yml | app + 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.md | Postgres/MariaDB、Redis、Horizon、Reverb、Octane、SSR、Wayfinder、pnpm/yarn/bun、Chromium、仅 SQLite。 |
references/coolify.md | 服务器上的 GHCR 认证、创建资源、域名 :8080、部署/更新/回滚。 |
references/other-platforms.md | Dokploy、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中Laravel ≤10:在->withMiddleware(function (Middleware $middleware): void { $middleware->trustProxies(at: '*'); })app/Http/Middleware/TrustProxies.php中设置protected $proxies = '*';。'*'是安全的,仅因为端口 8080 从未发布到互联网——在文档中说明这一点。 - 修复 npm lockfile(如果扫描标记了它):
它仅重新解析原生二进制包(rollup、esbuild、lightningcss、Tailwind oxide、swc、sass-embedded);向用户报告它打印的版本升级。python3 <技能目录>/scripts/repair_npm_lock.py <项目目录> .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 的横幅/自动化,因此一次性命令输出纯净。)
检查,并报告每个结果:
- 所有服务
healthy;app日志显示storage:link、迁移、optimize,无 ❌。 curl -s -o /dev/null -w '%{http_code}' localhost:8080/up→ 200;登录/首页 → 200,且其 CSS/JS URL 返回 200。- 代理:
curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<页面>→ 资源 URL 以https://x.example.com开头。 php artisan db:seed --force(如果应用具有用户期望在首次安装时运行的种子数据)。- 队列:将真实的排队类(来自应用的通知/作业)分发到每个命名队列,并确认工作者日志输出
DONE并且副作用已发生。从tinker --execute分发的闭包会在工作者中失败(评估的代码无法反序列化)——这是测试工件,不是错误。在选择测试收件人时也要注意应用自己的shouldSend/授权。 - 存储:从工作者向
public磁盘写入文件,通过localhost:8080/storage/...从 app 获取,然后down+up并确认文件和数据库行持久存在。 - 为服务器进行交叉编译:
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 会发布镜像,部署会改变生产环境,因此停下来让用户决定。给他们:
echo <具有 write:packages 权限的 PAT> | docker login ghcr.io -u <用户> --password-stdin- 提交,然后
scripts/docker-build-push.sh(拒绝脏的工作树;--load用于仅本地构建)。 - 来自
references/coolify.md的 Coolify 步骤——特别是服务器需要为私有包提供只读 GHCR 登录,使用sudo docker login完成(Coolify 以 root 身份拉取;非 root 登录对其不可见),以及域名输入为https://domain:8080(:8080= 容器端口)。 - 提醒:迁移时重复使用旧的
APP_KEY(以及 VAPID 或其他长期密钥);在新部署上线后禁用任何旧的 SSH/FTP 部署工作流。
一旦他们登录,提供为他们运行推送的服务。
常见的用户混淆及预防
用户经常尝试 docker run <镜像> 或 Docker Desktop 的 ▶ 按钮仅针对镜像。这仅启动 Web 容器:没有数据库服务存在,自动运行关闭,Laravel 回退到 sqlite(Database file at path [...] does not exist)或无法解析 mysql。答案始终是 compose 堆栈。在文档的本地测试部分说明这一点。