Community程式設計與開發github.com

Laravel → Coolify Docker 部署

將 Laravel 應用容器化並部署到 Coolify:在開發者機器上構建映像(包括 Apple Silicon → amd64 交叉編譯),推送至 GitHub Container Registry (ghcr.io),並以 Docker Compose 堆疊(Web + 佇列工作者 + 排程器 + 資料庫)執行。

Laravel → Coolify Docker 部署 是什麼?

此技能自動化將 Laravel(或 Filament)專案容器化並部署到 Coolify(或 Dokploy、EasyPanel、CapRover 或一般 VPS)的完整工作流程。它會生成一個基於 serversideup/php 的 Dockerfile、生產用 docker-compose.prod.yml、一個建置與推送腳本、信任代理修復、本地測試設定以及部署文件。該技能首先使用 Python 腳本檢查專案,收集關於 PHP 版本、擴充套件、佇列、排程器、資料庫驅動程式和前端相依性的資訊。它會修復常見問題,例如遺失 Linux 原生二進位檔案的 npm lockfile,以及需要信任代理以避免在反向代理後方產生 http:// URL。產生的 Docker 組合堆疊包含一個 Web 服務(nginx + PHP-FPM,連接埠 8080)、一個佇列工作者和一個可選的排程器,共用以確保持久性的儲存磁碟區。此技能強調本地驗證,包括健康檢查、代理測試和儲存體測試,然後再推送至 GHCR 並提供詳細的部署文件。它支援 Apple Silicon 交叉編譯 amd64、多架構建置,並處理常見的陷阱,例如在沒有完整組合堆疊的情況下執行容器時,Laravel 會回退到 SQLite。

相容平台~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>
                                                          │ pull
伺服器 (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 Push 而一起出現;同時安裝兩者沒問題。
  • extensions.system_binaries — 需要作業系統二進位檔案的套件(Chromium、wkhtmltopdf、ffmpeg)。在使映像膨脹之前,檢查程式碼是否實際使用它們(grep 類別);如果有使用,請參閱 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 變更基礎映像(參閱變體)。
  • 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;參閱變體。
  • 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)、對自己的 URL 執行 file_get_contents(asset(...)) 的程式碼、硬編碼的 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 Push 失敗)。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)。
  • 將特定應用程式的環境變數鍵(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,以及 AUTORUN_ENABLED,它會執行 storage:link、等待資料庫、migrate --force 和 php artisan optimize(這包括 filament:optimize 和其他套件的最佳化掛鉤)。只有 app 服務設定 AUTORUN_ENABLED=true,因此遷移只執行一次;worker/scheduler 等待 app 變為健康。
  • 在 $BUILDPLATFORM 上的 Assets 階段 — 在 Mac 上原生執行,而 PHP 階段為 amd64 模擬;輸出與架構無關。
  • 在複製原始碼之前安裝 Composer — 依賴層保持快取;僅程式碼重建在模擬下也很快。
  • 一個共用的 storage/app 磁碟區,用於 app + worker (+ scheduler) — 工作寫入的檔案必須對 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, key, passwords
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(如果應用程式有使用者期望在首次安裝時使用的 seeders)。
  5. 佇列:將一個真實的佇列類別(來自應用程式的通知/工作)分派到每個已命名的佇列,並確認工作者記錄 DONE 並且副作用已發生。從 tinker --execute 分派的閉包在工作器中失敗(eval 過的程式碼無法反序列化)— 那是測試產物,不是錯誤。在選擇測試收件者時,也要尊重應用程式自身的 shouldSend/授權。
  6. 儲存體:從工作者將檔案寫入 public 磁碟,透過 localhost:8080/storage/... 從應用程式擷取它,然後 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. 撰寫部署文件

根據 references/docs-template.md 建立 docs/DOCKER_DEPLOYMENT.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 <image> 或 Docker Desktop 的 ▶ 按鈕單獨對映像操作。這只會啟動 Web 容器:沒有 DB 服務存在,自動執行已關閉,Laravel 會回退到 sqlite(Database file at path [...] does not exist)或無法解析 mysql。答案始終是 compose 堆疊。在文件的本地測試部分說明這一點。

相關技能