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.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 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中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)。 - 將特定應用程式的環境變數鍵(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 的橫幅/自動化,因此一次性命令輸出乾淨。)
檢查並報告每個結果:
- 所有服務
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(如果應用程式有使用者期望在首次安裝時使用的 seeders)。- 佇列:將一個真實的佇列類別(來自應用程式的通知/工作)分派到每個已命名的佇列,並確認工作者記錄
DONE並且副作用已發生。從tinker --execute分派的閉包在工作器中失敗(eval 過的程式碼無法反序列化)— 那是測試產物,不是錯誤。在選擇測試收件者時,也要尊重應用程式自身的shouldSend/授權。 - 儲存體:從工作者將檔案寫入
public磁碟,透過localhost:8080/storage/...從應用程式擷取它,然後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. 撰寫部署文件
根據 references/docs-template.md 建立 docs/DOCKER_DEPLOYMENT.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 <image> 或 Docker Desktop 的 ▶ 按鈕單獨對映像操作。這只會啟動 Web 容器:沒有 DB 服務存在,自動執行已關閉,Laravel 會回退到 sqlite(Database file at path [...] does not exist)或無法解析 mysql。答案始終是 compose 堆疊。在文件的本地測試部分說明這一點。