Coolify 4.2 升級要改什麼？先處理 Member 唯讀與 API GET→POST

4.2 會影響哪些既有流程#

先把變更分成「角色權限」和「HTTP 方法」兩層：

這兩件事不要混成「token 失效」。Member 是團隊角色，token 則有自己的 team scope 和 permission。升級後出現 405，先修 HTTP method；出現 401 或 403，再檢查 token、角色與權限。

升級前先找出所有 API 呼叫#

不要只搜尋 coolify 這個字串，還要找出 HTTP client 的 method 和會改變資源狀態的路徑。可以在部署與自動化 repository 先做一輪盤點：

1
rg -n \
2
  --glob '*.sh' --glob '*.yml' --glob '*.yaml' --glob '*.json' \
3
  'curl|fetch|axios|/api/v1/(enable|disable|deploy|start|restart|stop|validate)' .

把結果分成三類：

1. 只讀取列表或查詢狀態的呼叫，通常維持 GET。
2. 觸發部署、啟停、重啟或啟用／停用 API 的呼叫，改成 POST。
3. 包含自訂 URL 或 wrapper 的呼叫，沿著函式追到真正送出的 method，不要只改呼叫端名稱。

如果你原本透過 Coolify 與 Zeabur 自架部署比較 建立了自動化，這次應以實際 script 和部署版本為準重新驗證，不要把比較文章裡的概念當成目前 API 契約。

把狀態變更從 GET 改成 POST#

以 application restart 為例，升級後應明確送出 POST 和 Bearer token：

1
curl --fail-with-body -X POST \
2
  "$COOLIFY_URL/api/v1/applications/$APP_UUID/restart" \
3
  -H "Authorization: Bearer $COOLIFY_TOKEN"

其他 state-changing 路徑也用同一個原則處理，包括：

• /enable、/disable
• /deploy
• /servers/{uuid}/validate
• /applications/{uuid}/start、/restart、/stop
• /databases/{uuid}/start、/restart、/stop
• /services/{uuid}/start、/restart、/stop
• /services/{uuid}/applications/{app_uuid}/start、/restart、/stop

不要把所有 API 都機械式改成 POST。列出部署資源、查詢 logs 或取得團隊資料的讀取端點，仍應以 Coolify API reference 的 method 為準。

在 CI 裡可以先把 URL、method 和 response status 記錄下來，但不要把 token 印到 log：

1
response_file="$(mktemp)"
2
status="$(curl -sS -o "$response_file" -w '%{http_code}' \
3
  -X POST "$COOLIFY_URL/api/v1/applications/$APP_UUID/deploy" \
4
  -H "Authorization: Bearer $COOLIFY_TOKEN")"
5

6
case "$status" in
7
  2*) cat "$response_file" ;;
8
  405) echo "Coolify API method is still wrong" >&2; exit 1 ;;
9
  401|403) echo "Coolify API token is not authorized" >&2; exit 1 ;;
10
  *) cat "$response_file" >&2; exit 1 ;;
11
esac

正式腳本還要處理暫存檔清理、逾時和重試；上例的重點是把 405、401、403 分開，讓排錯訊息能直接指出下一步。

重新分配 token 權限，不要先給 root#

Coolify API token 的權限不是只有「能不能登入」。官方文件列出以下主要層級：

例如，單純部署的 pipeline 不應因為遇到 403 就直接改用 root。先確認它是否只需要 read 加 deploy，並確認 token 是在正確的 team 建立；Coolify 會把 token 綁定在建立時的 team。

如果 script 需要啟用或停用整個 API，官方文件說這兩個端點要求 root。這是特例，不應反過來把一般部署 token 都提升成 root。

針對 Member 唯讀行為安排回歸#

升級前把實際角色分成三組測試：

1. Member 查看：確認可以看到被授權 team 的專案、應用程式、資料庫與服務。
2. Member 寫入：確認不會再把建立、更新、刪除或啟停操作交給 Member 角色執行。
3. 自動化 token：確認 pipeline 使用的是明確的 token permission，不依賴某位使用者能在 dashboard 上看到按鈕。

這個改動的目的不是讓 Member 完全看不到資源，而是讓「可查看」和「可改變 production 狀態」分離。若你的值班流程由 Member 帳號負責按下 deploy，升級後要改成由受控的 CI token 或具備適當權限的角色執行，並保留審計紀錄。

用狀態碼判斷升級後的問題#

可以用這個順序處理常見錯誤：

不要用「重新建立 token」掩蓋 405；也不要用「把權限加滿」掩蓋 403。先保存 request method、endpoint（遮蔽 token）、status code 和 response body，再做最小修改。

安全的升級順序#

如果 Coolify 管理的是 production，可以依這個順序降低風險：

1. 匯出目前版本、token 用途、team 和自動化呼叫的清單。
2. 在 staging 或備援環境先升級 4.2，跑讀取、部署、重啟與回滾測試。
3. 先合併 script 的 POST 修改，再安排 Coolify instance 升級。
4. 用最小權限建立或更新 pipeline token，並設定合理的到期與 IP allowlist。
5. 上線後觀察 405、403、部署完成和 webhook 回呼，不要只看服務 container 是 running。

如果設定 Allowed IPs，也要先把 CI runner 的出口 IP 加入，否則 token 權限正確仍可能無法連線。token 只顯示一次，應放在 secret manager；不要寫入 repository、Docker image 或 CI 的明文輸出。

結論：先修 method，再重做最小權限#

Coolify 4.2 的相容性工作可以拆成兩個可驗證的變更：所有狀態變更 API 依官方路徑改用 POST，然後重新確認 Member 唯讀、token permission 和 team scope。遇到 405、401、403 時分層排錯，能避免把 HTTP method 問題誤判成權限問題，也能避免用 root 快速繞過升級後的安全邊界。

常見問題#