修復 Collabora CODE 容器在 ARM64 架構上無法啟動的問題

如果 Collabora 線上開發版 (CODE) 容器在 ARM64 機器上立即退出，請先檢查架構相容性，然後再變更網路、憑證或 WOPI 設定。截至 2026 年 10 月 7 日，官方collabora/code倉庫列出了linux/arm64當前版本（包括當前latest標籤和版本 26.04.4.2.1）的原生變體。這意味著現代 ARM64 主機通常無需 x86 模擬即可運行 CODE。對於初學者來說，最實用的工作流程是：確認主機架構，檢查鏡像標籤，移除任何強制的 AMD64 設置，拉取一個支援 ARM64 的鏡像，然後再排查應用程式層級的配置問題。

本指南著重於啟動失敗本身，並未假定所有 ARM64 問題都由相同原因造成。如果容器啟動成功，但 Nextcloud、ownCloud 或其他 WOPI 主機無法連接到它，則屬於另一層故障排除範疇。

在進行任何更改之前，您需要了解以下資訊。

ARM64是一種 64 位元 ARM CPU 架構。 Linux 通常將其標記為`< aarch64linux/ linux/arm64...

多平台鏡像是指一個鏡像標籤，其註冊表清單指向針對不同架構（例如 AMD64 和 ARM64）的獨立鏡像建構版本。 Docker 文件指出，當拉取多平台映像時，它會自動選擇與主機相符的變體。有關底層行為，請參閱 Docker 的多平台映像檔。

對於 Collabora CODE，請務必查看Docker Hub 上的官方collabora/code 標籤列表，而不是依賴舊教程。本文於 2026 年 10 月 7 日審核時，latest其中26.04.4.2.1包含linux/arm64一個專門的latest-arm64標籤。較早的已鎖定版本可能有所不同，因此您實際部署的標籤比「Collabora 支援 ARM」這樣的籠統說法更為重要。

準備一次安全的故障排除會議

• docker-compose.yml保留一份目前命令或部署命令的副本。
• 請記錄您使用的確切 Collabora 圖片標籤。
• 不要僅僅為了診斷架構不匹配而刪除應用程式資料或反向代理配置。
• 如果這是生產環境部署，請先在維護視窗或測試主機上測試替換標籤。

目標結果很簡單：Docker 應該拉取 ARM64 映像，容器應該保持運作而不是立即退出，其日誌應該正常記錄 Collabora 啟動過程，而不是出現架構錯誤。

步驟 1：確認主機和 Docker 架構

在實際執行 Collabora 容器的機器上執行以下檢查：

uname -m
docker info --format '{{.Architecture}}'
docker version

在原生 64 位元 ARM Linux 主機上，uname -m通常會返回aarch64，而 Docker 應該報告arm64。在此上下文中，這些名稱指的是相同架構系列。

如果 Docker 報告的架構是 AMD64，而實體機器是 ARM64，請確定您使用的是遠端 Docker 環境、虛擬機器或後端不同的 Docker Desktop。在繼續操作之前，請解決此問題。否則，您可能會在一個系統上進行測試，卻部署到另一個系統。

哪些錯誤表示架構不符？

典型的訊號包括exec format error註冊表訊息（表示存在no matching manifest for linux/arm64某個服務）或明確配置了 Compose 服務platform: linux/amd64。這些訊息比通用的「容器已退出」輸出更能證明平台不符。

步驟 2：在拉取圖片之前，檢查 Collabora 圖片標籤的準確性

不要想當然地認為每個歷史標籤都與現在的標籤具有相同的平台支援latest。請檢查部署中標籤的註冊表元資料：

docker buildx imagetools inspect collabora/code:latest

Docker 的buildx imagetools inspect 文件解釋了該指令如何顯示鏡像倉庫中包含的平台。您也可以使用docker manifest inspect；Docker 在其清單檢查參考文件中記錄了該命令。

如果linux/arm64出現，您可以使用多平台標籤，讓 Docker 選擇正確的映像。官方倉庫也列出了用於明確故障排除的鏡像latest-arm64。對於長期運行的生產環境部署，使用您測試過的確切版本標籤通常比使用其他標籤更容易復現latest，因為latest隨著新版本的發布，標籤也會隨之移動。

如果您的置頂標籤不包含 ARM64，您有三種選擇：

步驟 3：移除意外新增的 AMD64 覆蓋設定並乾淨俐落地拔出

常見的故障並非 Collabora 鏡像本身的問題，而是部署檔案強制使用了錯誤的平台。 Docker Compose 將platform目標作業系統和架構定義為選擇映像變體的依據。 Docker 的Compose 服務參考文件中列出了諸如 `<path>` 之類的值linux/arm64/v8。

在 ARM64 主機上，這種設定很可疑：

services:
  collabora:
    image: collabora/code:latest
    platform: linux/amd64

如果不需要模擬，請刪除該行，讓 Docker 選擇主機原生版本。或者，platform: linux/arm64如果您希望明確指定架構，也可以進行指定。

然後僅移除失敗的容器並重新拉取鏡像。除非有其他原因，否則不要刪除持久化資料：

docker compose down
docker image rm collabora/code:latest 2>/dev/null || true
docker pull --platform linux/arm64 collabora/code:latest
docker compose up -d

如果您使用專用架構標籤進行診斷運行，請進行替換collabora/code:latest-arm64。確認部署成功後，請考慮鎖定確切的版本，例如經過測試的 26.04.x 標籤，而不是讓生產系統使用不斷變化的標籤。

步驟 4：在追蹤整合問題之前，請確認 CODE 是否已啟動。

容器重建完成後，檢查狀態和日誌：

docker compose ps
docker compose logs --tail=100 collabora

對於單容器部署，等效命令為docker ps -a和docker logs --tail=100 <container-name>。

首要的成功標準是容器保持運作狀態，不再出現清單或可執行檔案格式錯誤。只有在滿足此條件後，您才能繼續檢查連接埠 9980 的可及性、反向代理設定、TLS、允許的 WOPI 主機或應用程式整合。 Collabora 的官方 CODE Docker 文件是驗證目前部署參數的最佳參考。

避免初學者常犯的錯誤

在檢查官方鏡像之前安裝 QEMU

當軟體僅支援其他 CPU 架構時，模擬可能很有用，但目前的 Collabora CODE 鏡像包含 ARM64 版本。先添加模擬可能會掩蓋真正的問題，並且會增加額外的複雜性。如果所需的 CODE 版本支援原生 ARM64，則應優先使用原生 ARM64。

假設「最新」標籤和舊的置頂標籤是等效的

平台可用性與特定的鏡像標籤和清單檔案相關聯。目前版本的標籤可能支援 ARM64，而舊版本則可能不支援。請檢查 Compose 檔案中的具體引用。

強制平台：linux/amd64，因為舊指南使用了該平台。

這會導致 ARM64 主機即使存在原生 ARM64 鏡像，也會拉取 x86-64 版本。除非您有經過測試的明確理由需要進行模擬，否則請移除此覆蓋設定。

在進程執行之前更改 WOPI、SSL 或代理設定

exec format error在 Collabora 能夠有效處理大多數應用層配置之前，會發生一些問題。請先解決架構選擇問題。網路和 WOPI 故障排除稍後再進行。

診斷過程中刪除卷

架構不匹配通常不需要銷毀持久化資料。應盡量縮小修復範圍，以便輕鬆回滾。

如果 ARM64 鏡像仍然存在呢？

如果清單檔案中明確包含了linux/arm64該變體，而 Docker 也拉取了該變體，那麼架構就不再是主要原因了。此時，需要捕獲以下資訊：

• docker compose ps或者docker ps -a
• 最後 100-200 行日誌
• 確切的 CODE 標籤
• 您的 Docker Engine 和 Compose 版本
• Compose 服務定義的非機密部分

然後根據實際日誌訊息，檢查權限、掛載路徑、安全設定檔、記憶體壓力、連接埠衝突、證書或 WOPI 配置。確認運行鏡像為 ARM64 架構後，請避免重複切換架構。

一條切實可行的決策路徑

1. 如果主機不是 ARM64，請停止使用 ARM64 特有的修復方法，並診斷真正的平台。
2. 如果主機是 ARM64，但所選的 CODE 標籤沒有 ARM64 清單，則移至受支援的本機標籤或刻意選擇不同的託管策略。
3. 如果標籤支援 ARM64 但 Compose 強制使用 AMD64，請刪除或修正該platform設定。
4. 如果正確的 ARM64 鏡像仍然存在，請將其視為正常的 Collabora 啟動問題，並查看日誌，而不是繼續指責 CPU 架構。

結論

在現代 ARM64 系統上，首選的解決方案通常不是使用類比。經 2026 年 10 月 7 日驗證，目前官方 Collabora CODE 標籤包含原生 ARM64 鏡像。請aarch64在arm64主機上確認，檢查鏡像清單，刪除過時或強制使用的 AMD64 引用，重新拉取 ARM64 相容鏡像，並驗證容器是否保持運作。此步驟可使故障排除對初學者友好，並防止無關的 SSL、代理或 WOPI 更改掩蓋基本的平台不匹配問題。