如何為 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 執行個體數量、更新部署方式以及您是否能夠執行安全的字型主機來選擇。

方法	最佳匹配	權衡
只讀綁定掛載	一個 Compose 主機或小型安裝	無需重新建置即可輕鬆更新，但每個主機都需要相同的檔案和相容的容器路徑。
自訂 Docker 映像	CI/CD、可重複部署或多個託管主機	字體與鏡像一起進行版本控制，但更改字體意味著需要重新建置並重新部署鏡像。
遠端字體配置	需要集中管理目錄的幾個實例	集中式交付增加了對服務和網路的依賴；生產環境使用需要HTTPS和運維加固。

如果您使用 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 公開的字體。

/srv/collabora 目錄下的檔案管理器顯示了一個字型資料夾、兩個範例字型檔案和 docker-compose.yml 檔案。 — 在將目錄新增至 Collabora 服務之前，請先開啟主機端的字體資料夾和 Compose 檔案。

如何使用 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 編輯器顯示了兩個唯讀字體綁定掛載點，一個位於 /usr/share/fonts/custom 目錄下，另一個位於 systemplate 字體目錄下。 — 範例磁碟區映射將同一個主機字型目錄傳送到兩個上游 Collabora 字型位置。

請在空閒時段套用 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 exec 命令，該命令列出了 Collabora 容器內的兩個 custom-font 目錄。 — 範例驗證命令：列出正在運行的 Collabora 容器中的兩個已掛載路徑。

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

docker exec collabora fc-list : family file

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

如何在 Collabora Online 中測試字體？

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

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

一個範例文件編輯器字型選單，其中從多個字型系列中選擇了 Sample Sans 字型。 — 驗證步驟範例：確認目標字型系列出現在編輯器的字型選單中。

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

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

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

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

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

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

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

你該選擇哪個方案？

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