如何為 ONLYOFFICE 文件伺服器新增自訂字體

若要在 ONLYOFFICE Docs 中使用自訂字體，請將其字體檔案安裝到執行文件伺服器的電腦或容器中，重新產生伺服器的字體列表，然後在編輯器和匯出的文件中檢查結果。具體的檔案持久化步驟取決於您的伺服器是直接安裝在 Linux 系統上還是運行在 Docker 容器中。

成功更改字體意味著字體會以其字體族名稱顯示在編輯器的字體選擇器中，並且在測試文件中顯示正常。在選單中看到字體名稱是一個有用的初步檢查，但這並不能證明所有樣式、語言或匯出路徑都有效。在將字體用於生產文件之前，請檢查常規文字和粗體文字、所需的字元集以及 PDF 或列印預覽。

安裝字體後會發生哪些變化？

ONLYOFFICE Docs 使用文件伺服器主機提供的字體，並為其編輯器建立字體元資料。供應商的安裝指南列出了 TrueType 和 OpenType 字型系列，包括.ttf、.otf、.ttc及相關格式，以及 WOFF 格式。支援的文件類型並不能保證每個字體文件或字體功能都表現完全相同；請測試您計劃使用的特定字體和文件。

伺服器端字型安裝允許連接的編輯人員透過文件伺服器使用該字型。它不會將字型安裝到每個使用者的電腦上或其他文件處理伺服器上。如果下載的檔案或單獨開啟的檔案在缺少該字體的軟體中查看，該軟體可能會使用其他字體。 ONLYOFFICE 也指出，當伺服器上沒有文件中使用的字體時，文件可能會使用最接近的替代字體顯示，這可能會改變換行或頁面佈局。

請使用您已獲得授權部署到伺服器上的字型檔案。請將文件及其授權條款與您的部署記錄一起儲存，尤其是當字型對伺服器使用、重新散佈或嵌入文件有限制時。

選擇合適的安裝方法

• Linux 軟體包安裝：將字型檔案複製到文件伺服器的系統字型目錄，然後執行 NoneLYOFFICE 的字型產生腳本。此方法適用於您直接管理主機的情況。
• Docker 容器：將持久的主機目錄掛載到容器的字型目錄中，或將字型複製到正在執行的容器中進行短期測試。在容器內重新產生字體元資料。綁定掛載在容器重建後仍然有效；而一次複製到容器中的字體通常無效。
• 託管或整合部署：如果文件伺服器容器由其他平台或安裝工具管理，則應透過該部署的配置應用持久掛載。單獨編輯正在執行的容器可能會導致更新或替換過程中資料遺失。

ONLYOFFICE 目前發布的字體指南在 Linux 和 Docker 上的社群版中展示了相同的主要流程，並單獨發布了企業版的 Linux 指南。路徑、權限和容器編排可能會因版本和安裝方法而異，因此請使用部署中現有的配置，而不是用其他環境的範例取代它。

在 Linux 系統上新增字體

1. 準備並安裝字型文件

取得所需的字體族文件，包括字體族提供的粗體和斜體變體。將常用的字體族檔案放在一個名稱清晰的目錄中。例如，管理員可以將字型族放在 `<path>` 目錄下/usr/share/fonts/，這是 ONLYOFFICE Linux 說明中使用的系統位置：

sudo mkdir -p /usr/share/fonts/custom/brand-sans
sudo cp BrandSans-*.ttf /usr/share/fonts/custom/brand-sans/

請將範例檔案名稱替換為您實際擁有的檔案。避免透過重新命名字體檔案來更改其字體系列名稱；編輯器會使用儲存在每個字體檔案中的元資料。請確保文檔伺服器進程可以讀取這些檔案。如果您透過軟體包或組態管理系統管理字體，請使用系統，以便在維護後文件仍然存在。

2. 重新產生 ONLYOFFICE 字型列表

安裝檔案後，執行供應商提供的字體產生腳本：

sudo /usr/bin/documentserver-generate-allfonts.sh

等待腳本運行完畢並檢查其輸出是否有錯誤。此步驟會更新文件伺服器所使用的字型資料；僅將字型檔案複製到主機可能不會使其顯示在已執行的編輯器中。請勿在此過程中刪除現有的伺服器字體。供應商警告稱，刪除系統字體可能會影響文件的佈局和顯示。

向 Docker 部署新增字體

1. 將字體目錄設定為持久化

對於使用 Docker Compose 管理的部署，請新增綁定掛載到現有文件伺服器服務。建立一個主機目錄來存放文件，然後將其對應到容器的自訂字體目錄。 ONLYOFFICE 的 Docker 映像將其宣告/usr/share/fonts/truetype/custom為磁碟區，其 Docker 字型指令也允許將字型複製到該目錄下/usr/share/fonts/。

services:
  onlyoffice-documentserver:
    image: onlyoffice/documentserver:<your-pinned-version>
    volumes:
      - /srv/onlyoffice/fonts:/usr/share/fonts/truetype/custom

這是一個需要合併到您現有 Compose 檔案中的程式碼片段，並非完整的配置替換。請保留您現有的鏡像版本、網路、環境變數、資料磁碟區、金鑰和服務名稱。請在主機上準備好字體文件，/srv/onlyoffice/fonts並確保容器可以讀取它們。

套用已變更的 Compose 檔案可能會重新建立文件伺服器容器，並中斷正在進行的編輯工作階段。請檢查您的部署流程，備份 Compose 配置，並合理安排更改時間。如果容器由裝置或整合管理，請使用其支援的設定方法，而不是編輯產生的 Compose 檔案。

2. 重新建立或重新啟動，然後產生字體元數據

使用標準的 Compose 工作流程部署掛載點。然後在實際的文檔伺服器容器內執行字體產生腳本。對於名為 `<container_name>` 的容器onlyoffice-documentserver，指令如下：

docker exec onlyoffice-documentserver   /usr/bin/documentserver-generate-allfonts.sh

使用顯示的容器名稱或 ID docker ps。如果您只想在永久設定之前檢查字體，供應商文件中提供了使用 `--font-files` 命令將字體檔案複製到正在運行的容器中docker cp，然後在容器內執行相同腳本的方法。請將此操作視為測試：複製到容器中的檔案可能會在容器被替換時遺失。

在編輯器和輸出中驗證字型。

1. 在連接到此文檔伺服器的編輯器中開啟文檔，並開啟字體選擇器。搜尋元資料中記錄的字型系列名稱。
2. 建立一個包含普通文字、粗體文字以及所需語言字元的簡短測試文件。確認已選擇正確的字重，而不是合成樣式或替代樣式。
3. 儲存、重新開啟並匯出或列印預覽測試文件。將換行符號、頁數、間距和字形覆蓋率與預期結果進行比較。
4. 在使用者實際使用的文件編輯器或應用程式中重複檢查。伺服器上存在的字體並不能保證無關的本機應用程式或其他伺服器上也存在該字體。

對於較舊的版本，瀏覽器快取的字體元資料可能會延遲使用者看到的內容。 ONLYOFFICE 官方指南指出，對於 8.1.3 或更早版本，添加字體後需要清除瀏覽器快取並重新開啟頁面；對於更高版本，則無需執行此步驟。請先驗證伺服器端檔案和產生的元數據，然後僅在版本匹配的情況下才參考快取建議。

如果字體缺失或版面變化

• 字型選擇器中缺少該字型：請確認該文件位於文件伺服器主機上的字型目錄或正確的容器內，且可讀，並具有受支援的文件類型。再次運行字體生成腳本並查看其輸出。在 Docker 中，請從容器內部檢查掛載情況；僅憑主機路徑無法證明磁碟區已掛載到活動服務。
• 字體家族名稱看起來不一樣：請檢查字體嵌入的家族元資料。檔案名稱BrandSans-Bold.ttf可能安裝正確，但選單中顯示的卻是字型內部定義的家族名稱。
• 字體顯示正常，但文字內容錯誤：請檢查字體是否包含所需的字元和樣式檔案。字體可能出現在字體選擇器中，但缺少文件使用的字形或字重。
• 更改後文件會重新排版：請比較更改前後使用的字體系列和樣式。如果其他機器或匯出服務中缺少原始字體，則可以使用替代字體，但替代字體可能會變更佈局。請在所有渲染操作中安裝授權字體，或使用文件安全的替代字體並再次檢查頁面。
• 更新後字型消失：請檢查是否僅在臨時容器內進行了安裝。將檔案移至持久性主機目錄，並在重新建立服務之前透過部署配置將其附加到主機。

當需要在共用文件和受控匯出中使用相同字體系列時，添加自訂字體最為有用。但它也存在一些限制：伺服器安裝並未授予字體使用權限，無法在字體中添加缺少的字形，也無法保證在使用不同字體集的軟體中實現像素級一致的渲染效果。因此，建議將自訂字型目錄置於版本控製或組態管理之下，記錄文件伺服器版本，並在升級後重新執行驗證檢查。

官方參考資料

• ONLYOFFICE Docs 社群版：在 Linux 系統上新增字體
• ONLYOFFICE Docs 社群版：在 Docker 上新增字體
• ONLYOFFICE Docs 企業版：在 Linux 系統上新增字體
• ONLYOFFICE Docker-DocumentServer 倉庫