Coolify 在 2026 年 11 月 2 日發布 v4.6.0。這個版本加入成員與 API token 的細緻資源範圍、更新 channel、token 暫停與輪替等能力，但也有明確的破壞性變更：經 API 或 MCP 刪除資源時，只有 write 的 token 不再足夠，必須具備新的 delete 能力或 root。另外，映像層改用 zstd 壓縮，release note 指出拉取需要 Docker Engine 23.0 以上，而 Coolify 要求 Docker 24.0。

這不是所有 Coolify 站台都要立刻搬家，也不是 v4.5 服務會在某日自動停止。影響集中在自行管理 Coolify instance、以 API 或 MCP 做自動化，以及主機 Docker 版本較舊的團隊。若只從 Dashboard 手動部署，可能不會遇到 token 相容性；但 host runtime、備份與回滾仍屬於自架方責任，不能只看到「Update available」就直接按下升級。

先盤點誰會刪除、誰只需要部署

把所有 Coolify token 的使用者、team、到期日、來源 IP、secret 儲存位置與呼叫 endpoint 列成清冊。特別搜尋刪除 application、service、environment variable、storage、backup、scheduled task、tag，以及 detach tag 的腳本。v4.6 後這些操作若只有舊 write 權限會收到拒絕；反之，為了讓舊腳本快速通過而全面改成 root，會把一次相容性問題變成長期權限風險。

依官方權限文件，監控與 inventory 用 read，部署、重啟、停止與取消用 deploy，設定變更才需要 write；只有真正要刪除的自動化才加入 delete。敏感資料讀取與一般讀取也應分開。每個 token 綁定建立時的 active team，切換使用者目前 team 不會改變既有 token，因此多 team 整合應各自建立 token，而不是共用一把高權限 root token。

除了權限，還要檢查 token owner 的角色。官方文件說明，執行特權操作時 owner 必須仍是 team administrator 或 owner；成員被移除或降級可能讓 token 失效。這類 403 不應被 deployment job 無限重試，因為問題是授權狀態，不是短暫網路異常。

主機與資料的升級前檢查

先在每個 Coolify server 執行唯讀盤點，確認 Docker Engine 版本、磁碟剩餘空間、CPU、記憶體、目前 Coolify version、update channel 與所有 workload 健康狀態。v4.6 release note 對拉取與執行列出不同門檻；實務上應以 Coolify 要求的 Docker 24.0 作為最低線，而不是只確認 Docker 23 能解 zstd。

如果 Docker 需要跨 major 升級，把它視為另一個維護步驟：先確認作業系統與 Docker 官方 repository 支援、Compose 與 storage driver 狀態，再安排重啟窗口。不要在同一個未驗證步驟裡同時升 Docker、Coolify、資料庫與所有應用映像，否則故障時無法判斷是哪一層造成。

備份至少涵蓋 Coolify 自身資料、/data/coolify/source/.env、資料庫與持久 volume；並確認備份能在隔離環境讀取。Coolify 安裝文件特別提醒保存 .env，其中 APP_KEY 牽涉資料庫值的解密。只有看到備份 job 顯示成功，不等於能重建 instance；應記錄 recovery 步驟、DNS 切換、憑證與外部 secret 的來源。

staging 驗收要包含允許與拒絕

先複製一個不承載正式流量的 instance 或 server，使用與 production 相同的 Docker major、反向代理與 token 呼叫方式升級。建立至少四種測試 token：read-only、deploy-only、write 但無 delete、以及只在測試環境具備 delete 的 token。驗證 read token 看不到敏感值，deploy token 可以部署但不能改設定，write token 可以更新卻不能刪除，delete token 只能處理授權範圍內的資源。

v4.6 新增按 project、environment 或 resource 限制存取，測試時不要只驗證一個正常 endpoint；要同時呼叫授權內與授權外資源，確認搜尋結果、清單與 direct ID endpoint 都沒有越界。若 MCP server 也使用同一套權限，將其視為另一個 client 驗證，因為自然語言工具呼叫不應取得比 CI 更寬的刪除權限。

部署測試要包含 Git 觸發、手動 redeploy、registry login、log、terminal、scheduled task 與 backup。升級後確認既有應用、資料庫、WebSocket、TLS 與 health check，而不是只看 Coolify Dashboard 能開啟。記錄升級前後相同指標；release note 的效能數字是專案方特定 benchmark，不能直接宣稱自己的主機也會快固定倍數。

Token 輪替與正式上線

最安全的做法不是修改原 token 後直接祈禱，而是建立替代 token，放進 secret manager，在 staging 或 canary job 測試，再切換 production。官方 token 文件建議替代 token 生效後才撤銷舊 token，並確認舊 token 回傳 401 Unauthenticated。token value 只在建立時顯示，應事先確定值會進入正確的 secret 儲存位置，而不是貼在工單或 repository。

正式升級前凍結非必要設定變更，記錄目前 image digest、Coolify version 與 Docker version。升級後先驗證平台本身，再逐一執行低風險部署和有明確 rollback 的 API 操作。若出現權限拒絕，先比對 token permission、resource scope、team 與 owner role；不要立刻補 root。

選擇上，沒有 API 自動化且 Docker 已符合要求的小型 instance，可在完整備份後依正常窗口升級。大量依賴 API、跨 team 或由 MCP 管理資源的環境，應先完成權限矩陣與雙 token 切換。若舊 OS 無法安全升到 Docker 24，應先建立新 host、演練資料與 workload 遷移，而不是為了追版本在不受支援的主機上硬升。

Coolify 的價值是讓自架部署更接近平台體驗，但 v4.6 也再次提醒：控制平面升級仍是基礎設施變更。完成條件應包含最小權限、可還原資料、明確 host runtime 與測過的拒絕路徑，而不只是版本號顯示 4.6.0。