在伺服器和連接器中設定 ONLYOFFICE JWT 密鑰

始終使用同一個強 JWT 金鑰：在 ONLYOFFICE Docs 中配置該金鑰，並將相同的值複製到已連接平台的 ONLYOFFICE 設定中，並保持 JWT 驗證啟用狀態。 Docs 7.2 及更高版本預設啟用 JWT 並自動產生密鑰；更改密鑰意味著必須更新所有整合以與之匹配。具體的伺服器端方法取決於 Docs 是以 Linux 軟體包還是 Docker 容器的形式運作。

哪些條件必須符合？

JWT（JSON Web Token）使 ONLYOFFICE Docs 能夠驗證簽名請求。文件平台和 Docs 必須使用相同的金鑰和相容的標頭設定。伺服器為瀏覽器配置以及傳入和傳出的服務請求使用不同的令牌設定；共享的密鑰值保護這些交換。請勿將金鑰放在公用網頁、客戶端 JavaScript 套件、支援工單或公開可讀的原始碼庫中。

編輯前，請先確定部署類型並記錄連接器所使用的文件 URL。使用密碼管理器或加密安全的密碼產生器產生一個長且難以預測的金鑰。將其視為憑證，並儲存在受限的配置儲存庫中。

ONLYOFFICE local.json 摘錄，其中瀏覽器、收件匣和寄件匣令牌驗證設定為 true — 應啟用 local.json 中的令牌啟用設置，以進行瀏覽器、收件匣和寄件匣驗證。

配置 Linux 安裝

對於基於軟體包的 Linux 安裝，請編輯該檔案/etc/onlyoffice/documentserver/local.json。保留所有現有設定：將以下按鍵合併到現有的 JSON 中，而不是取代整個檔案。範例展示了令牌驗證結構以及官方配置指南中描述的三個匹配的密鑰位置：

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "request": {
            "inbox": true,
            "outbox": true
          },
          "browser": true
        }
      },
      "secret": {
        "inbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "outbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "session": { "string": "REPLACE_WITH_YOUR_SECRET" }
      }
    }
  }
}

請將所有佔位符替換為完全相同的密鑰值。請勿貼上範例佔位符本身。 `--request-validation`、`--request-validation`browser和inbox` outbox--request-validation` 開關是獨立的；僅啟用其中一個開關並不會啟用所有請求驗證。 Docs 7.2 及更高版本預設啟用 JWT，但明確檢查這些設定有助於審核現有配置或跨節點統一行為。對於 7.2 之前的版本，官方指南建議啟用所有三個開關。

ONLYOFFICE local.json 摘錄，其中包含相同的收件匣、寄件匣和會話佔位符金鑰 — 保持收件匣、寄件匣和會話金鑰字串相同，以便伺服器的 JWT 檢查使用相同的金鑰。

重新啟動前請先驗證 JSON 語法。稍後重啟文件伺服器服務，以便載入變更：

sudo systemctl restart ds-converter ds-docservice ds-metrics

請使用具有系統服務管理權限的帳戶執行該命令。在 Windows 系統中，設定檔位於%ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json；請使用官方指南中的 Windows 重新啟動說明，而不是 Linux 命令。

無需編輯產生的配置即可配置 Docker

對於官方文件伺服器 Docker 映像，請透過容器環境變數設定 JWT。官方指南警告，手動更改產生的 JWT 值local.json可能會在容器重新啟動後被撤銷。請在容器建立指令或 Compose 服務中設定JWT_ENABLED=trueJWT JWT_SECRET，然後重新建立容器以使環境變數生效。將 JWT 金鑰保存在受保護的環境變數檔案或金鑰管理員中，並限制該檔案的權限；避免將其提交到版本控制系統中。

services:
  onlyoffice:
    image: onlyoffice/documentserver:YOUR_PINNED_TAG
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: ${ONLYOFFICE_JWT_SECRET}

ONLYOFFICE_JWT_SECRET在部署環境或受保護的文件中定義.env。使用經過測試的鏡像標籤，而不是依賴其他方式latest，並查閱文件以確認您正在執行的確切標籤。變更環境值後，使用正常的部署流程重新建立容器。簡單的重啟可能會導致舊環境仍然存在。

Docker Compose 服務摘錄，將 JWT_ENABLED 設為 true，並將 JWT_SECRET 從受保護的環境變數中取得。 — 對於 Docker，在建立容器時傳遞 JWT 設置，並將金鑰保存在 Compose 檔案之外。

更新連接器並保護金鑰

開啟與 ONLYOFFICE Docs 連接的平台（例如 Nextcloud 或其他支援的連接器）中的整合設定。在密鑰欄位中輸入相同的 JWT 密鑰並儲存。同時確認已設定的文件伺服器 URL，以及（如果連接器公開）授權標頭。 ONLYOFFICE Docs 中的預設標頭為 `<default_header>` Authorization；僅當雙方都配置為使用相同的替代方案時才更改它。

密鑰不匹配通常表現為開啟或儲存文件時出現無效令牌或授權錯誤。當負載平衡器後面的 Docs 節點僅更新時，也可能出現金鑰不符。如果您執行多個節點，請在向所有節點發送流量之前，請同步所有節點的金鑰和令牌設定。分階段逐步推出變更：同時更新 Docs 和連接器，並預期在過渡期間，使用舊值簽署的現有編輯器會話或請求將會失敗。

任何能夠讀取密鑰的人都可以創建伺服器可能接受的令牌。限制對設定檔和部署變數的訪問，對連接器到文件的連接使用加密傳輸，如果金鑰可能已洩露，則應輪換金鑰。輪換金鑰需要將所有文件節點和連接器更新為新值；不要在已簽入的文件或日誌中保留舊憑證。

連接器設定表單，啟用 JWT 驗證並設定遮罩金鑰，位於終端狀態檢查上方 — 在連接器中啟用 JWT 驗證，並輸入與文件伺服器上配置的相同的金鑰。

驗證配置

配置變更後，請確認 Docs 服務或容器是否正在執行。
對於 Docker 部署，執行命令sudo docker exec <container_name> sudo documentserver-jwt-status.sh以檢查 JWT 狀態。請使用實際的容器名稱。此輔助工具的文件僅針對 Docker 編寫；請勿假定它在每個軟體包安裝中都可用。
透過已連接的平台開啟文檔，進行少量無害的修改，然後儲存。確認編輯器已開啟且平台已接收至已儲存的變更。
如果驗證失敗，請逐個字元比較伺服器和連接器金鑰，檢查所有相關的令牌開關是否已啟用，並驗證請求頭配置。

官方配置指南是受支援設定和版本行為的權威指南。請參考ONLYOFFICE 的 JWT 配置文件和官方 Docker 安裝參數，以了解您部署的特定版本。