修正 ONLYOFFICE Nextcloud 整合中的「令牌無效」錯誤

ONLYOFFICE 的「Token 無效」訊息通常表示整合雙方驗證的 JSON Web Token (JWT) 不一致。在 Nextcloud 環境中，關鍵在於存在多個令牌路徑：發送到瀏覽器的編輯器配置、發送到 ONLYOFFICE Docs 的傳入請求以及發送到 Nextcloud 的傳出請求（例如回調）。任何一條路徑上的故障都可能在用戶端表現相似。

在您開始更改設定之前，請注意一個重要細節：自 ONLYOFFICE Docs 7.2 版本起，JWT 已預設為啟用，並且文件伺服器可以自動產生金鑰。因此，先前教程中「停用 JWT」的建議並不適用於現代安裝。 ONLYOFFICE 目前的指導原則是配置您自己的金鑰，並在連接器中使用相同的金鑰。請參閱ONLYOFFICE 的 JWT 配置指南。

快速參考：首先要檢查什麼

1. 確認共享金鑰確實相同

JWT 驗證依賴一個共享金鑰。 ONLYOFFICE Docs 使用此金鑰對令牌進行簽名，接收方則使用相同的金鑰驗證簽名。即使只有一個字元的差異、末尾的空格、過時的環境變量，或是重新產生的 Docker 金鑰，都足以導致看似有效的令牌驗證失敗。

Nextcloud 上的連接器支援此jwt_secret設定。官方連接器還提供了一個occ配置介面，因此您可以檢查 Nextcloud 實際使用的值，而無需依賴您認為有效的設定檔。連接器的目前設定記錄在ONLYOFFICE Nextcloud 連接器的官方 README 檔案中。

sudo -u www-data php occ config:app:get onlyoffice jwt_secret
sudo -u www-data php occ config:app:get onlyoffice jwt_header

請勿將金鑰貼到支援工單、螢幕截圖、與他人分享的 shell 歷史記錄或公開問題報告中。請在本地進行比較。

對於 ONLYOFFICE Docs 的原生 Linux 安裝，支援的設定檔為：

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE 會分別記錄瀏覽器、收件匣和寄件匣的令牌設定。用於驗證的金鑰值必須與您的連接器配置一致。請勿編輯default.json；ONLYOFFICE 明確警告，重新啟動或升級後預設值可能會被覆蓋。此方法適用local.json於軟體包安裝。

如果您在 Docker 中執行 ONLYOFFICE Docs，

local.json請使用 Docker 環境變量，而不是在容器內手動編輯。 ONLYOFFICE 指出，Docker 可以在啟動期間重新產生 JWT 配置；其官方映像支援 `<JWT_NAME>`、 ` <JWT_NAME>` JWT_ENABLED、 `<JWT_NAME> ` 和`<JWT_NAME> `。目前的 Docker 映像檔將 `<JWT_NAME>` 列為預設 JWT 標頭。請參閱官方 Docker DocumentServer 倉庫。JWT_SECRETJWT_HEADERJWT_IN_BODYAuthorization

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=replace-with-a-long-random-secret
  - JWT_HEADER=Authorization

更改 Docker 環境變數後，需要重新建立容器，以便執行中的服務能夠接收到這些變更。僅僅編輯 Compose 檔案而不重新建立容器，並不會更改容器現有的環境變數。

2. 確保 JWT 標頭完全匹配

人們常常誤以為郵件頭名稱只是裝飾性的，其實不然。 ONLYOFFICE Docs 的收件匣和寄件匣令牌郵件頭是可設定的，Nextcloud 連接器也有對應的jwt_header設定。它們必須描述相同的請求路徑。

目前 ONLYOFFICE API 文件將 ` Authorization<documentserver_default_name>` 列為傳入 JWT 請求的預設文件伺服器，而 Nextcloud 官方整合文件也同樣將其列為Authorization連接器的預設設定。較舊的範例和現有安裝可能使用 `<documentserver_default_name>`AuthorizationJWT或其他明確配置的值。因此，安全的規則並非“始終使用某個特定字串”，而是確保兩端的活動配置保持一致。

請求格式也很重要。 ONLYOFFICE 的 API 文件顯示，請求頭令牌使用 Bearer 方案發送。有關底層協定的詳細信息，請參閱ONLYOFFICE 請求頭令牌文件。

如果您特意使用了自訂標頭，請在兩個產品中配置相同的值。如果您沒有理由進行自訂，則使用目前的預設值Authorization可以減少操作步驟。

3. 檢查反向代理是否更改了令牌路徑

如果 Nextcloud 和 ONLYOFFICE 的設定相符但錯誤仍然存在，請檢查它們之間的路徑。反向代理、驗證閘道、WAF 或入口控制器都可能影響授權標頭。這取決於您的技術棧，因此在沒有證據的情況下不要斷定是代理的問題。

使用以下實際測試步驟：

• 確認 Nextcloud 主機可以存取公用文件伺服器 URL。
• 確認內部文件伺服器 URL（如果已設定）可以從 Nextcloud 伺服器或容器解析。
• 確認內部 Nextcloud/儲存 URL 可以從 ONLYOFFICE Docs 主機或容器解析。
• 執行連接器檢查時，檢查代理存取/錯誤日誌。
• 如果您的代理伺服器有明確的規則Authorization，請確認它是轉送而不是替換或刪除標頭。

不要為了消除錯誤而禁用 JWT。這樣做會移除驗證機制，而不是修復問題。此外，不要為了解決 JWT 問題而停用 TLS 驗證：憑證驗證和 JWT 簽章驗證是獨立的控制機制。如果遇到憑證問題，請單獨修復憑證鍊或信任配置。

4. 使用連接器本身的健康檢查

官方 ONLYOFFICE 連接器包含一個專用的診斷命令：

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

連接器文件指出，此檢查會報告連線是否成功或錯誤原因。它比僅測試文件伺服器登入頁面更有用，因為它從 Nextcloud 的角度測試了整合。

如果檢查結果顯示文件伺服器可存取但令牌驗證失敗，則傳回使用金鑰和標頭。如果完全無法存取伺服器，請先解決 DNS、路由、防火牆、TLS 或內部 URL 問題，然後再繼續處理 JWT。

5. 僅當證據指向該時間點時才進行核實。

JWT 可能包含與時間相關的聲明，而 Nextcloud 連接器會公開這些聲明jwt_leeway和jwt_expiration設定。但這並不意味著您應該先增加容差。如果時脈出現重大誤差，即使令牌本身是正確的，也可能導致其失效；增加容差可能會掩蓋基礎架構問題。

比較 Nextcloud 和 ONLYOFFICE 主機或容器上的 UTC 時間：

date -u
timedatectl status

請確保兩個系統時間同步可靠。只有在確認時鐘差異很小且合理後，才應考慮允許一定的誤差範圍。連接器支援的 JWT 設定列於官方連接器配置參考文件中。

此整合中 JWT 驗證的工作原理

ONLYOFFICE Docs 使用 JWT 來保護編輯器初始化和伺服器間請求。其 API 將瀏覽器令牌與傳入和傳出的 HTTP 請求令牌分開。對於傳入請求，令牌可以包含在請求頭中，或者對於支援的 POST 請求，令牌可以包含在請求體中。對於 GET 請求，ONLYOFFICE 文件中提供了基於請求頭的令牌處理方法。請參閱官方請求簽名文件。

這就解釋了為什麼一個操作可以成功而另一個操作會失敗。例如，如果只有一個方向的令牌設定正確，那麼開啟編輯器可能會成功，但後續的回呼或下載請求卻會失敗。

常見誤解

“如果 /healthcheck 傳回 true，則 JWT 一定是正確的。”

不。健康端點僅證明服務正在回應；它並不能證明 Nextcloud 連接器和文件伺服器共用相同的 JWT 金鑰和標頭。操作：運轉occ onlyoffice:documentserver --check並檢查有效的連接器設定。

“我可以在 Docker 容器內編輯 local.json 文件，然後就完成了。”

對於 Docker 部署來說，這種方法很脆弱。 ONLYOFFICE 建議透過 Docker 環境變數設定 JWT，因為啟動時可能會重新產生配置。操作方法：在容器配置中定義`<JWT_NAME>` JWT_ENABLED、JWT_SECRET`<JWT_NAME>` 和 `<JWT_NAME>`（如果需要），JWT_HEADER然後重新建立容器。

“AuthorizationJWT 始終是必需的標頭。”

否。目前官方文件伺服器設定中列出的Authorization是預設標頭，但現有部署和較早的範例可能使用其他明確配置的標頭。操作：讀取所有活動配置並使其保持一致。

“關閉 JWT 是最快的解決方法。”

它或許能消除眼前的驗證錯誤，但同時也移除了一項安全控制措施，並可能掩蓋根本原因導致的不匹配。操作：除非您有明確且有據可查的理由在不使用 JWT 的情況下運行，否則請修復共用金鑰/標頭。

最終驗證清單

• Nextcloud 和 ONLYOFFICE Docs 中配置了相同的 JWT 金鑰。
• 雙方的 JWT 標頭名稱符合。
• Docker部署使用持久化環境變量，而不是在容器內進行臨時編輯。
• 公用伺服器和內部伺服器 URL 在使用方向上均可存取。
• 沒有代理規則意外刪除或重寫 JWT 標頭。
• Nextcloud 和 ONLYOFFICE 系統已同步時脈。
• occ onlyoffice:documentserver --check成功了。
• 實際文件可以開啟、編輯、自動儲存、關閉，然後重新開啟並儲存變更。

當令牌錯誤仍然存在時

如果金鑰和標頭匹配、時脈同步且連接器檢查成功，但特定操作仍會報告無效令牌，請在變更更多設定之前擷取失敗請求的確切方向和相應的日誌。 ONLYOFFICE 會區分瀏覽器、收件匣和寄件匣的驗證，因此下一個問題是故障發生在編輯器初始化期間、傳送到文件伺服器的命令期間，還是發生在發送回 Nextcloud 的回呼/下載期間。

請將文件伺服器日誌、Nextcloud 日誌和代理程式日誌結合使用，確保時間戳記一致。避免公開完整的 JWT 或密鑰。如果需要比較令牌結構，請對簽名和敏感聲明進行編輯。簽名和驗證的參考行為請參閱ONLYOFFICE 的簽名文件。