如何為 Collabora Online CODE Docker 新增自訂字體

要在 Docker 中執行的 Collabora Online CODE（Collabora Online 開發版）中使用自訂字體，字體檔案必須可供 Collabora 容器本身存取。僅將字型檔案安裝在 Docker 主機或單獨的 Nextcloud 容器中，並不能使其可供辦公室伺服器使用。對於單一 Compose 部署，只讀綁定掛載通常是最簡單的選擇；自訂鏡像更容易在託管叢集中復現，而遠端字體配置如果能夠安全操作，則可以集中交付。

具體的字體目錄可能因鏡像和版本而異。 Collabora 目前的上游 Helm 部署會將自訂字體掛載到 `/etc/fonts`/usr/share/fonts/custom和/opt/cool/systemplate/usr/share/fonts/custom`/etc/fonts` 目錄。這可以作為這兩個位置的參考，但並不能保證每個獨立的 Docker 標籤都是如此。在部署以下範例之前，請檢查您實際執行的鏡像中的路徑。

哪種字型安裝方法最適合您的部署？

根據您維護的 CODE 執行個體數量、更新部署方式以及您是否能夠執行安全的字型主機來選擇。

如果您使用 Helm Chart 安裝 Collabora，請先檢查 Chart 的deployment.customFonts設定：上游 Chart 已提供自訂字型掛載選項。對於獨立的 Docker Compose 設置，如果您的映像路徑匹配，請繼續使用綁定掛載。

查看上游 Helm 部署範本及其兩個字型掛載位置，並檢查 chart 的自訂字型值。

更換 Docker 容器之前，應該檢查哪些內容？

• 字體格式：請使用您的 Collabora 設定支援的字體檔案。 Collabora 官方字型伺服器專案文件中提供了 TrueType ( .ttf) 和 OpenType ( .otf) 檔案。
• 許可：請確認字體許可允許您在伺服器端使用字體並將其分發給使用者。除非許可允許，否則請勿從桌面作業系統複製字體。
• 字體族名稱：字體選單中顯示的名稱來自字體的內部元數據，可能與字體的檔案名稱不同。請使用字體族名稱進行測試，而不僅僅是檔案名稱。
• 所有實例：如果代理程式將使用者路由到多個 Collabora 容器，請在每個實例上安裝相同的字型檔案。否則，當同一文件在不同的伺服器上開啟時，渲染效果可能會有所不同。
• 鏡像路徑必須準確：請檢查運行中鏡像的目錄和啟動配置。不要盲目復用舊路徑，例如/opt/lool來自不相關軟體包的路徑。

在您的 Compose 檔案旁邊建立一個宿主目錄./fonts，並將允許的檔案放入.ttf其中.otf。目錄僅包含您打算透過 Collabora 公開的字體。

如何使用 Docker Compose 新增字體？

將兩個唯讀卷條目新增至現有的 Collabora 服務volumes清單。保留服務的目前鏡像、連接埠、環境變數和其他設定；這是一個新增功能，而不是替換 Compose 檔案。

services:
  collabora:
    volumes:
      - ./fonts:/usr/share/fonts/custom:ro
      - ./fonts:/opt/cool/systemplate/usr/share/fonts/custom:ro

左側的來源目錄位於 Docker 主機上。右側的路徑位於容器內部。:ro後綴使文件對容器為唯讀。這些目標路徑遵循 Collabora 目前的上游 Helm 範本；對於獨立的 CODE Docker 映像，請先檢查您的特定標籤。如果任一位置缺失或您的版本使用不同的目錄，請使用該鏡像支援的路徑，而不是強制使用此範例。

請在空閒時段套用 Compose 更改，因為重新建立 Collabora 服務可能會中斷正在進行的編輯會話。如果您的服務名為 `composite` collabora，請執行：

docker compose up -d collabora

如果實際的 Compose 服務名稱與此處不同，請使用實際的服務名稱。除非其他服務也需要配置更改，否則請避免完全重啟整個服務堆疊。

如何確認容器能夠看到這些文件？

首先檢查掛載的目錄中是否包含字型檔。將 `<container name>` 替換collabora為您設定中使用的容器名稱：

docker exec collabora ls /usr/share/fonts/custom
docker exec collabora ls /opt/cool/systemplate/usr/share/fonts/custom

查看檔案可以確認 Docker 掛載成功，但這並不能證明編輯器已載入字體。如果映像包含 Fontconfig 工具，您可以使用下列命令檢查已發現的字型族名稱fc-list，例如：

docker exec collabora fc-list : family file

使用容器中提供的工具，篩選出您期望的字體系列。如果fc-list未安裝該工具，請勿將軟體包新增至正在執行的容器中作為永久解決方案；請驗證鏡像的字型配置或使用可複現的自訂鏡像。如果檔案可見但未被發現，請檢查權限、檔案格式、內部字型系列元資料以及兩個掛載路徑。然後查閱日誌，找到您部署的確切鏡像和版本。

如何在 Collabora Online 中測試字體？

1. 透過啟動 Collabora 編輯器的正常整合方式開啟或建立測試文件。
2. 開啟字體系列選單，尋找字體的內部系列名稱。
3. 選中它，輸入一個簡短的範例，儲存，關閉，然後重新開啟文件。
4. 如果您的部署包含多個 Collabora 實例，請使用其他使用者或瀏覽器檢查相同文件。

以下範例展示了預期的檢查類型：編輯器選單中出現字體系列。此範例並非來自實際的 CODE 部署環境，您的工具列可能會因版本或整合方式而異。

如果字體系列顯示正常，但文字卻以替代字體顯示，請確保所選字形和字重（例如，常規和粗體）存在，並確認該字體存在於系統模板路徑和通用字體目錄中。僅憑選單項目並不能證明每個樣式或每個伺服器都擁有該字體。

什麼時候客製化圖片或遠端字體服務才值得使用？

建立自訂鏡像以實現可重複性

使用 Dockerfile 將已核准的字型檔案複製到所選 CODE 映像使用的路徑中，可簡化部署的複現：映像摘要會同時識別伺服器建置及其字型集。但代價是，每次更新字型或基礎鏡像時，都需要重新建置、掃描和部署。基礎鏡像升級後，請重新檢查目標目錄，並避免將字型複製指令視為所有 CODE 版本通用的指令。

使用共享目錄的遠端字體配置

Collabora 的字體伺服器專案描述了遠端字體配置和一個 JSON 目錄。其維護者將該程式碼庫標記為用於開發和測試，因此請勿將範例伺服器視為可用於生產環境的服務。對於生產環境，請使用維護良好的 HTTPS 端點，限制並驗證其提供的字體，並考慮網路可用性和快取刷新機制。這種選擇可以減少每個主機的文件管理工作，但同時也增加了一項服務，其故障或配置偏差可能會影響字體的可用性。

在選擇此方法之前，請參閱官方的 Collabora 字體伺服器專案和Collabora 配置文檔，以了解遠端字體可用性。

你該選擇哪個方案？

對於使用 Docker Compose 管理的單一 CODE 容器，建議先使用唯讀綁定掛載：這樣易於回滾，且無需自訂建置。對於透過 CI/CD 維護的集群，如果希望每次部署都包含明確的、可審核的字體集，則最好使用自訂鏡像。只有在集中分發字體具有顯著的維運優勢，且能夠提供安全可靠的 HTTPS 服務時，才考慮遠端字體配置。無論採用哪種方式，部署後都應驗證路徑並在實際文件中測試字體；僅憑主機的字體清單無法確認 Collabora 是否已載入該字體。