如何配置 ONLYOFFICE JWT 金鑰身份驗證

ONLYOFFICE JWT 驗證僅在文件伺服器和整合應用程式使用相同的金鑰時才有效。在目前的 Docker 部署中，JWT 驗證預設為啟用。為了實現穩定的集成，請設定您自己的持久性金鑰，JWT_SECRET而不是依賴容器自動產生的金鑰，然後在 Nextcloud、您的自訂文件管理器或任何與 ONLYOFFICE Docs 通訊的連接器中配置相同的金鑰。

本實用參考手冊重點介紹您最可能需要的配置：Docker 和 Docker Compose、用於簽署編輯器配置的自訂整合、頭部/主體行為、驗證、輪換以及常見錯誤。它基於 2026 年 10 月更新的 ONLYOFFICE 最新文件。

快速參考

從 ONLYOFFICE Docs 7.2 版本開始，Docker 部署預設啟用 JWT，並在您未提供金鑰時產生隨機金鑰。 Docker 官方文件警告，自動產生的金鑰在重新啟動或容器重建後可能會發生變化，導致整合失敗。對於任何實際部署，請務必設定顯式金鑰。請參閱ONLYOFFICE Docs 的 JWT 配置指南和Docker 官方安裝指南。

1. 確定 ONLYOFFICE 容器和部署方法

對於 Docker 主機，請從以下操作開始：

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker images | grep onlyoffice

確定實例是透過docker runDocker Compose、控制台還是其他編排層啟動的。您需要修改建立容器的來源配置。編輯容器內產生的檔案並非長久之計。

針對 Docker，ONLYOFFICE 建議管理員使用環境變量，而不是手動編輯設定檔/etc/onlyoffice/documentserver/local.json。如果直接在該檔案中編輯 JWT 值，Docker 啟動程序可能會在容器重新啟動時復原或重新產生這些值。

2. 產生強密鑰並安全存儲

一個方便的 shell 指令是：

openssl rand -hex 32

這將產生 32 個隨機字節，以 64 個十六進位字元表示。 ONLYOFFICE 並不要求使用這種精確的格式；重要的要求是雙方共享同一個密鑰，並且該密鑰難以猜測。

JWT_SECRET像對待密碼或 API 憑證一樣對待：

• 不要將其提交到公共 Git 倉庫。
• 不要將其放入發送到瀏覽器的前端 JavaScript 程式碼中。
• 限制對 Compose 環境檔案或包含該檔案的密鑰儲存的存取。
• 生產環境和測試環境等不同環境使用不同的金鑰。

ONLYOFFICE 的簽章文件明確警告，令牌簽章必須在伺服器端進行，因為任何包含金鑰的瀏覽器端程式碼都會將其暴露給使用者。官方範例使用 HMAC-SHA256 演算法HS256。請參閱ONLYOFFICE JWT 簽名文件。

3. 在 Docker Compose 中配置 JWT

一個最基本的 Compose 服務可以包含：

services:
  documentserver:
    image: onlyoffice/documentserver:latest
    restart: unless-stopped
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: "${ONLYOFFICE_JWT_SECRET}"
      JWT_HEADER: "Authorization"
      JWT_IN_BODY: "false"
    ports:
      - "8080:80"

盡可能將真正的金鑰放在 Compose 檔案之外。例如，將其放在一個權限受限的.env檔案中：

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

然後確保將該文件從版本控制中排除，並且只有需要該文件的管理員或服務帳戶才能讀取該文件。

ONLYOFFICE官方Docker-DocumentServer 倉庫文件包括 、JWT_ENABLED和。目前的 Docker 啟動程式碼預設啟用 JWT 驗證，使用作為預設標頭，並在未提供明確金鑰時產生隨機金鑰。JWT_SECRETJWT_HEADERJWT_IN_BODYAuthorization

4. 重新建立容器，以便套用新環境。

為 Compose：

docker compose up -d --force-recreate
docker compose ps

對於最初使用 JWT 建立的容器docker run，官方 JWT 指南指示管理員停止並刪除舊容器，然後使用 JWT 環境變數建立新容器。在此過程中，請勿刪除持久性磁碟區或綁定掛載的資料。

您還可以檢查正在運行的容器的環境，而無需列印金鑰本身：

docker inspect onlyoffice-documentserver \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep '^JWT_' \
  | sed 's/^JWT_SECRET=.*/JWT_SECRET=[REDACTED]/'

如果容器名稱不同，onlyoffice-documentserver請相應地進行替換。

5. 在整合中配置相同的密鑰

這是最容易被忽略的部分。在 ONLYOFFICE Docs 上啟用 JWT 而未設定文件管理端會導致編輯器請求被拒絕。連接器或自訂應用程式必須使用完全相同的金鑰對請求進行簽署。

Nextcloud 範例

在 ONLYOFFICE 的 Nextcloud 設定中，輸入與文件伺服器相同的金鑰。標頭名稱也必須符合。 ONLYOFFICE 目前的 Nextcloud 整合文件列出了 `<connector settings>`jwt_secret和jwt_header`<connector settings>`，其中 `<connector settings Authorization>` 是預設標頭。請參閱Nextcloud 官方連接器文件。

如果您的連接器有一個名為「密鑰」、「JWT 密鑰」或類似名稱的字段，請勿在此處產生第二個獨立的密鑰。請複製相同的密鑰值。

6. 對於自訂集成，請在伺服器上對完整的編輯器配置進行簽署。

對於自訂應用程序，首先建立編輯器配置，在後端對該配置進行簽名，然後將生成的 JWT 分配給頂級token屬性。

Node.js範例：

import jwt from "jsonwebtoken";

const config = {
  documentType: "word",
  document: {
    fileType: "docx",
    key: "document-2026-001",
    title: "Project Plan.docx",
    url: "https://files.example.com/project-plan.docx"
  },
  editorConfig: {
    callbackUrl: "https://app.example.com/onlyoffice/callback"
  }
};

config.token = jwt.sign(config, process.env.ONLYOFFICE_JWT_SECRET, {
  algorithm: "HS256"
});

ONLYOFFICE 的瀏覽器簽章文件指出，用於開啟檔案的令牌有效負載必須與編輯器配置具有相同的結構。自 7.1 版本起，此操作的驗證參數集受到嚴格控制，因此對過時或不完整的結構進行簽署是失敗的常見原因。請參閱“瀏覽器令牌簽名”。

傳遞給函數的最終配置DocsAPI.DocEditor包含令牌：

new DocsAPI.DocEditor("placeholder", config);

官方 API 參考文件將其定義config.token為 ONLYOFFICE Docs 用於驗證編輯器配置的加密簽章。

7. 瞭解頭部標記與主體標記的差異

ONLYOFFICE 中的 JWT 不僅僅用於瀏覽器編輯器配置。它也用於服務之間的請求，例如命令、轉換和回調流量。

ONLYOFFICE 支援在請求體和請求頭中使用請求令牌。其安全性常見問題指出，請求頭可能會受到伺服器長度限制，因此建議對適用的傳入請求使用請求體令牌。從文件 7.1 開始，如果傳入請求中存在請求體令牌，則優先使用請求體令牌；否則，使用請求頭令牌。傳出方可以同時發送請求體和請求頭令牌。請參閱ONLYOFFICE 請求令牌文件。

Docker 變數JWT_IN_BODY預設值為false，因此不要因為它存在就啟用它。只有當您的整合旨在持續發送和驗證正文令牌時，才應更改它。

8. 使用真實的編輯請求進行測試

一個有效的驗證步驟如下：

1. 透過您的實際整合開啟文件。
2. 驗證編輯器是否載入正常，無令牌錯誤。
3. 稍作修改。
4. 關閉編輯器或執行正常儲存操作。
5. 驗證儲存應用程式是否接收並接受回調。

文件伺服器歡迎頁面成功顯示並不能證明兩個應用程式之間的 JWT 配置正確。 JWT 錯誤通常僅在整合發送編輯器設定、命令、轉換請求或回呼時才會出現。

官方安全概述解釋了預期行為：ONLYOFFICE 會驗證令牌並使用已簽署的有效負載值；如果在需要驗證時令牌缺失或無效，則會拒絕請求。請參閱ONLYOFFICE 文件中的安全概述。

9. 身份驗證失敗時，檢查 JWT 狀態和日誌

目前的 Docker 啟動程式碼會將管理員引導至 JWT 狀態助理。使用正確的容器名稱，運行：

docker exec onlyoffice-documentserver \
  sudo documentserver-jwt-status.sh

您也可以查看日誌：

docker logs --tail 200 onlyoffice-documentserver
docker exec onlyoffice-documentserver \
  find /var/log/onlyoffice/documentserver -type f -maxdepth 3 -print

如果變更密鑰後整合立即失敗，請依序檢查以下各項：

• 是否JWT_ENABLED已在重新建立的容器中啟用？
• 整合是否使用了完全相同的密鑰，包括大小寫和標點符號？
• 連接器是否使用相同的 JWT 標頭名稱？
• 對於自訂編輯器，您是否對傳送至瀏覽器的相同設定物件進行簽署？
• 回調函數和命令請求是否也按要求進行簽名和驗證？
• 儲存在 shell 或 Compose 檔案中的金鑰是否被環境變數擴充截斷、解釋或取代？

常見故障模式

“無效令牌”或“無效簽名”

最可能的原因是金鑰不匹配，或令牌簽章所使用的有效負載與待驗證的請求不同。請在進行任何相關的配置變更後重新產生令牌。請勿重複使用文件中的範例令牌；這些範例令牌使用示範金鑰簽名，對您的伺服器無效。

在 Docker 重啟之前一切正常。

這通常意味著部署依賴自動產生的 JWT 金鑰。 ONLYOFFICE 明確警告，重新啟動或容器重建後，隨機產生的金鑰可能會重新產生。請JWT_SECRET自行設置，並在整合中輸入相同的值。

Nextcloud 顯示連線或令牌錯誤

首先檢查雙方的密鑰和標頭。 ONLYOFFICE 的 Nextcloud 文件要求連接器的標頭jwt_header與文件伺服器中配置的標頭相符。目前的預設值為Authorization.

大型簽名請求回傳 HTTP 錯誤

檢查 JWT 是否包含在超過代理程式或 Web 伺服器標頭大小限制的請求頭中。 ONLYOFFICE 的安全性常見問題解答解釋說，這也是為什麼對於適用的 POST 請求，最好使用請求體令牌的原因之一。

安全地輪換 JWT 密鑰

必須協調 JWT 密鑰輪換。如果連接器仍然使用舊密鑰進行簽名，而僅更改文件伺服器沒有任何好處。

對於簡單的單一執行個體部署：

1. 產生新的密鑰並安全儲存。
2. 如果活躍的編輯人員可能會受到影響，請安排一個較短的維護窗口。
3. 將整合式金鑰和文件伺服器金鑰JWT_SECRET作為一個協調的變更進行更新。
4. 重新建立文檔伺服器容器。
5. 開啟、編輯並儲存測試文檔。
6. 在將服務恢復正常使用前，請確認回呼功能正常。

對於負載平衡器後面的多個文件伺服器實例，所有服務於相同整合的實例在變更期間都需要相容的 JWT 配置。應制定周密的部署計劃，而不是臨時輪換單一節點。

生產檢查清單

• 持久密鑰：明確設定JWT_SECRET；不要依賴隨機產生的值。
• 到處都是一樣的秘訣：文檔伺服器和整合必須具有相同的價值。
• 後端簽章：永遠不要在前端/瀏覽器程式碼中暴露金鑰。
• HS256：使用 ONLYOFFICE 官方程式碼範例中所示的 HMAC-SHA256 方法。
• 標頭協定：如果連接器透過命名標頭傳送 JWT，則該名稱必須與文件伺服器相符。
• 容器重建： Docker 環境變更需要重建容器。
• 真正的整合測試：開啟、編輯、儲存並驗證回調行為。
• 秘密儲存：將秘密資訊排除在公共儲存庫和日誌之外。
• 受控輪換：兩側同時更新，並在維護結束前進行驗證。

結論

對於基於 Docker 的 ONLYOFFICE 安裝，持久化配置非常簡單：產生一個強密鑰，透過容器環境變數設定JWT_ENABLED=true該JWT_SECRET密鑰，重新建立容器，然後在連接器或後端配置完全相同的密鑰。自訂整合應該在伺服器上使用 HS256 對編輯器配置和服務請求進行簽名，切勿在瀏覽器程式碼中進行簽名。

如果 JWT 在重啟後突然失效，請檢查密鑰是否曾經設定為持久化狀態。如果配置變更後立即失效，請先比較金鑰、頭部和簽章有效負載，然後再尋找其他問題。這三項檢查可以解決大多數 JWT 設定錯誤，並且不會降低身份驗證的安全性。