解決 Nextcloud 中 ONLYOFFICE 的「令牌無效」錯誤

如果 Nextcloud 連接到 ONLYOFFICE Docs 時報告“令牌無效”，請確保連接器的 JWT 金鑰與文件伺服器實際使用的金鑰一致。在 ONLYOFFICE Docs 7.2 及更高版本中，JWT 驗證預設為啟用，並且會自動產生金鑰；僅更改 Nextcloud 設定或編輯 Docker 容器產生的設定檔可能會導致雙方金鑰不同步。

保持 JWT 啟用狀態。首先確定活動金鑰和部署類型，更新正確的配置，然後執行連接器的連接檢查。檢查結果應顯示連線成功；僅瀏覽器編輯器開啟並不能證明文件下載和回呼功能正常運作。

錯誤訊息提示了什麼？

JWT（JSON Web Token）是一種簽章令牌，用於驗證 Nextcloud 和 ONLYOFFICE Docs 之間的請求是否可信。連接器使用其配置的金鑰對請求進行簽名，而文件伺服器則使用其配置的金鑰驗證請求。如果簽名金鑰不同，則無法驗證令牌簽名，請求將被拒絕。

最常見的原因包括：從舊版複製的金鑰、從未在 Nextcloud 中輸入的自動產生的金鑰、已更改但未透過重新建立容器套用的 Docker 環境變量，或文件伺服器設定中金鑰值不一致。如果連接器和文件伺服器使用的 JWT 標頭名稱不同，自訂 JWT 標頭也可能導致不符。

本文解決的是 JWT 不符問題。如果錯誤訊息顯示伺服器無法存取、憑證無效或文件無法下載，請分別檢查伺服器位址、TLS 憑證以及 Nextcloud 到文件伺服器的網路路徑。 JWT 更正無法解決這些問題。

1. 找到活動的文檔伺服器金鑰

請使用目前執行的文檔伺服器的配置。不要假設從先前的容器或伺服器中保存的金鑰仍然有效。

Linux：檢查/etc/onlyoffice/documentserver/local.json。
Windows：檢查%ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json。
Docker：從正在執行的容器中讀取金鑰。官方鏡像也支援使用以下命令讀取會話密鑰：

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

請替換<containerID>為實際的容器名稱或 ID。請將回傳值視為憑證：請勿將其貼到支援論壇、螢幕截圖或公共日誌中。

在配置中，比較 `<path> `、`<path>` 和`<path>`local.json中的值。對於此標準設置，它們應該完全相同。此外，請確認已為瀏覽器、請求收件匣和請求寄件匣啟用令牌驗證。 7.2 之前的文件版本需要明確啟用令牌驗證；更高版本預設為啟用。services.CoAuthoring.secret.inbox.stringservices.CoAuthoring.secret.outbox.stringservices.CoAuthoring.secret.session.string

2. 更新 Nextcloud 的 ONLYOFFICE 連接器

以 Nextcloud 管理員身分登入並開啟設定 > 管理 > ONLYOFFICE。
在伺服器設定中，將在執行中的文件伺服器上找到的完整金鑰輸入到「金鑰」欄位中。避免在密鑰前或密鑰尾部添加空格，並且除非密鑰本身包含引號，否則不要添加引號。
如果您的部署使用了自訂標頭，請檢查 JWT 標頭設定。連接器的jwt_header設定和文件伺服器配置的令牌標頭必須一致。如果您並非有意自訂標頭，請勿在此次修復過程中對其進行更改。
儲存設定。兩端都保持 JWT 啟用狀態。

occ也可以使用Nextcloud 安裝目錄中的Nextcloud 指令來變更文件中記錄的連接器設定：

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

請替換YOUR_SECRET為實際值。 Shell 轉義有助於保留標點符號，但包含單引號的金鑰需要比直接插入命令列更安全的方法。命令列參數也可能對具有特權的程序檢查或 shell 歷史記錄可見。盡可能使用管理員介面，然後在不暴露金鑰的情況下驗證儲存的值。

3. 根據您的安裝情況，以正確的方式套用變更。

Docker 或 Docker Compose

對於 Docker 部署，請透過容器環境配置 JWT，而不是手動編輯自動產生的 JWT local.json。在文件伺服器服務定義中設定相同的金鑰：

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

修改 Compose 檔案後，需要重新建立文件伺服器容器，以使環境生效。例如，在包含 Compose 檔案的目錄中：

docker compose up -d --force-recreate <documentserver-service>

請將服務名稱替換為您 Compose 檔案中的名稱。簡單的重啟不會將更改後的環境變數值套用到現有容器。如果您使用 `--remove` 命令，請使用更新後的環境變數值docker run重新建立容器，並保留其現有的連接埠、磁碟區和其他必要選項。在確認這些設定和持久性資料掛載之前，請勿刪除生產環境容器。JWT_ENABLEDJWT_SECRET

容器啟動後，使用上述命令重新讀取其活動金鑰，並確保該值仍與 Nextcloud 相符。避免將生產環境密鑰放在公開共享的 Compose 檔案或原始碼倉庫中。

Linux 軟體套件或 Windows 安裝

如果您有意設定了自訂金鑰local.json，請確保三個金鑰欄位匹配，並啟用所需的令牌驗證值。重新啟動相關的文件伺服器服務以套用變更。目前的 ONLYOFFICE 說明列出了Linux 系統上的 `<command>` ds-converter、ds-docservice`<command>` 和 `<command> ds-metrics`；由其他服務管理器管理的安裝可能需要針對此設定採取對應的重新啟動方法。在 Windows 系統上，儲存設定後重新啟動 ONLYOFFICE 服務。

如果重啟後配置仍然不匹配，通常表示產生的配置或部署環境覆蓋了已編輯的檔案。對於 Docker，請將修正後的配置移至環境變數並重新建立容器。對於打包部署，在變更更多設定之前，請先檢查目前配置和服務的啟動配置。

確認維修狀況

在 Nextcloud 安裝目錄中，執行官方連接器檢查：

sudo -u www-data php occ onlyoffice:documentserver --check

如果不是www-data，請使用與您的安裝環境相符的 Web 伺服器帳戶。該命令應報告連接成功。如果仍然報告無效令牌，請再次確認正在執行的文件伺服器的活動金鑰與 Nextcloud 的金鑰完全匹配，並且任何自訂 JWT 標頭也匹配。

使用 ONLYOFFICE 從 Nextcloud 開啟一個小型測試文件。確認編輯器載入完畢，進行少量修改，儲存，關閉編輯器，然後重新開啟檔案以確認變更已儲存。
如果檢查結果顯示網路或憑證錯誤，請停止變更 JWT 值。驗證 Nextcloud 是否可以存取文件伺服器位址，以及文件伺服器是否可以存取 Nextcloud 回呼位址。盡可能使用受信任的 TLS 憑證；停用憑證驗證是一種不安全的權宜之計，並且無法解決令牌驗證問題。

這些檢查旨在確認配置的連接和基本保存路徑有效。但它們並不能證明每個反向代理路由、外部儲存配置或多伺服器拓撲結構都正確；如果您的部署使用了這些路徑，請單獨進行測試。