在 Collabora CODE Docker 中提供自訂字體

若要在 Docker 中執行的 Collabora Online CODE 中渲染自訂字體，請將字體檔案儲存在主機上，並將同一目錄掛載到容器的系統字體目錄和文件系統板中。系統板為獨立的文件程序提供文件；僅將字體掛載到系統板/usr/share/fonts可能會導致字體系列出現在字體選單中，但不會在其文件中渲染。本指南使用 Docker Compose 和目前的 CODE 映像路徑/opt/cool/systemplate；如果您使用其他映像，請驗證路徑。

檔案管理器開啟了包含常規和粗體 TTF 檔案的 collabora-fonts 資料夾。 — 將已授權的字型檔案放在 Docker 可以讀取的主機目錄中。

選擇一個你可以維護的字體來源

對於單一 Docker 主機而言，只讀綁定掛載通常是最簡單的選擇。它能在 CODE 容器重建或升級時保留字型文件，您可以精確地查看容器可以讀取哪些文件。請使用您有權安裝並分發到伺服器的字型檔案。除非您已檢查過許可證並且確實需要這些文件，否則請勿複製整個桌面系統的字體目錄。

請使用環境支援的未壓縮字型檔案格式，通常為 TrueType.ttf或 OpenType .otf。包含文件所需的樣式，例如常規、粗體、斜體和粗斜體。保持字體族名稱和檔案名稱清晰明了，並確保容器使用者可以讀取每個目錄和檔案。如果字體僅包含一種樣式，則當文件要求粗體或斜體時，Collabora 可能會替換為其他字體。

首先建立一個專用的主機目錄，並將授權檔案複製到該目錄中：

sudo mkdir -p /srv/collabora/fonts
sudo cp BrandSans-Regular.ttf BrandSans-Bold.ttf /srv/collabora/fonts/
sudo chmod -R a+rX /srv/collabora/fonts

請將範例檔案名稱替換為您實際的字型檔案。讀取權限至關重要，因為在目前鏡像中，CODE 程序以非特權帳戶運行。請保持目錄路徑穩定；Compose 綁定掛載將引用該路徑。

將字體掛載到主機字體樹和系統板中

在您現有的collabora服務配置中docker-compose.yml新增這些磁碟區條目。請保留您現有的鏡像、連接埠、網域允許清單、SSL 設定、金鑰和重新啟動策略；以下程式碼片段僅顯示了字型掛載。

一段 Docker Compose YAML 程式碼片段，將一個主機字體資料夾以唯讀方式掛載到系統字體和 systemplate 字體目錄中。 — 在現有 CODE 服務的磁碟區部分下方新增兩個唯讀掛載點。

services:
  collabora:
    volumes:
      - /srv/collabora/fonts:/usr/share/fonts/truetype/more:ro
      - /srv/collabora/fonts:/opt/cool/systemplate/usr/share/fonts/truetype/more:ro

第一個目標使容器能夠透過常規字體發現機制取得字體。第二個目標將字體放置在用於準備隔離文件環境的範本中。 Collabora 的 SDK 手冊中記錄了這種 Docker 的雙位置磁碟區模式。請勿掛載整個目錄/usr/share/fonts或 systemplate 目錄：這可能會隱藏鏡像已提供的字型。

系統模板路徑與版本相關。目前 CODE 26.04 鏡像元資料將/opt/cool/systemplate其標識為系統範本路徑，Collabora 的目前文件也使用該位置。如果您執行的是舊版映像或特定廠商的建置版本，請在編輯目標路徑之前檢查該映像的文件或啟動配置。

重新建立容器並確認字體發現

儲存 Compose 檔案並將字體檔案放置在主機上後，重新建立 CODE 服務，以便 Docker 應用綁定掛載：

終端機顯示 Docker Compose 正在重新建立 Collabora 服務，並執行 fc-list 指令來檢查可用字體。 — 重新建立服務，然後使用 fc-list 查看 Fontconfig 是否偵測到字型系列。

docker compose up -d --force-recreate collabora
docker compose exec -T collabora fc-list

在輸出結果中尋找字型系列名稱或已掛載的檔案路徑。若要縮小清單範圍，請使用管道將結果grep與字體本身報告的系列名稱一起傳遞，例如：

docker compose exec -T collabora fc-list | grep -i "Brand Sans"

如果命令報告未找到匹配項，請檢查主機路徑、檔案權限、掛載縮排和容器日誌。您可以使用命令檢查docker inspect正在執行的容器中的有效掛載點，或使用命令docker compose config來擷取 YAML 縮排錯誤。docker compose down通常無需執行命令即可應用磁碟區變更；重新建立服務就足夠了。

請確認字體在實際文件中能夠正常顯示。

在 Collabora Online 中，工具列中選擇了自訂字體系列，文件頁面上可以看到範例文字。 — 重新開啟文件後，檢查字體選擇器和渲染後的文字。

透過 Nextcloud 或 WOPI 整合開啟測試文檔，選擇一小段文字樣本，然後從字體選擇器中選擇自訂字體系列。使用該字體輸入一行新文本，儲存、關閉並重新開啟檔案。檢查常規文本和粗體文本，並將換行符或頁面佈局與來源文件進行比較。選單中顯示的字體系列僅用於初步檢查；重新開啟後可見的文字才是有效的渲染檢查。

字體出現在選單中，但文字消失或回退：確認第二個掛載點指向 systemplate 字體目錄，並且包含相同的檔案。
選單中缺少字型：請確認檔案有效且可讀，然後檢查fc-list輸出和容器啟動日誌。
字體在鏡像更新前一直有效：請確認 Compose 中仍然存在兩個掛載點，並且您的主機目錄不在臨時容器路徑內。
僅部分字元可渲染：所選字體可能不包含這些字形。請新增包含所需字元集的字體，或使用適當的備用字體。

綁定掛載可使字體獨立於 CODE 鏡像，但並不能保證在每個用戶端或每個文件中佈局完全相同。字型替換、缺失字形、不同字型版本以及文件特定的格式仍會影響換行。如需更多設定詳情，請參閱 Collabora 的字型安裝文件、CODE Docker 映像指南以及Collabora Online SDK 手冊。當您變更 CODE 版本時，應重新檢查手冊中的 Docker 範例和目前映像檔。