修正 Kopano WebApp「無法連線到 Kopano Core」錯誤

解決 Kopano WebApp「無法連接到 Kopano Core」錯誤的最快方法是確定究竟是以下三個層中的哪一個出了問題：Kopano Core 本身、WebApp 到 Core 的接口，還是WebApp 用於與 Core 通信的PHP-MAPI 層。重新啟動所有服務有時看似能解決問題，但這會掩蓋根本原因，並使重複出現的故障更難診斷。

Kopano 的官方 WebApp 文件指出，WebApp 依賴Kopano Core php-mapi，其DEFAULT_SERVER設定控制 WebApp 連接到 Kopano Core 的方式。文件中列出的選項包括本機 Unix 套接字、連接埠 236 上的 HTTP 以及連接埠 237 上的 HTTPS。請參閱Kopano WebApp 設定文件和Kopano Core 管理員手冊。

重要版本說明：截至撰寫本文時，Kopano 提供的公開管理員手冊版本較舊，與許多目前的 Linux 發行版版本不符。因此，您安裝的軟體包名稱、PHP 版本、服務封裝器和日誌位置可能有所不同。下文所述的連接模型和配置選項是基於 Kopano 官方發布的文檔，但在更改生產伺服器之前，您應該確認本地路徑和軟體包版本。

應該先嘗試哪一種解決方法？

先從最符合您自身狀況的症狀入手，而不是一次套用所有變更。

1. Kopano Core 真的在運作嗎？

在編輯 Web 應用程式設定之前，請檢查伺服器進程。在基於 systemd 的發行版上，請使用：

sudo systemctl status kopano-server

如果設備發生故障或處於非活動狀態，請在重新啟動之前檢查其最近的日誌：

sudo journalctl -u kopano-server -n 100 --no-pager

尋找資料庫連線錯誤、設定解析失敗、權限問題、檔案缺失或啟動錯誤。 Kopano 核心文件指出，設定變更通常需要重新啟動受影響的元件，例如使用 `kopano update` 指令systemctl restart kopano-<component>。文件中也指出，`kopano update`/etc/kopano/server.cfg是 `kopano update` 的常用設定檔kopano-server。請參閱“配置 KC 組件”。

在以下情況下選擇此路徑：服務明顯宕機、啟動後崩潰，或其他 Kopano 工具也無法與 Core 通訊。先修復 WebApp 只能解決下游問題。

權衡：重啟是最快的復原方法，但如果進程立即再次失敗，則需要日誌輸出。在生產系統中，請在重新啟動前捕捉故障詳情，以免遺失最清晰的證據。

2. WebApp 是否指向正確的 Kopano Core 端點？

在 WebApp 中，關鍵設定位於DEFAULT_SERVER. config.phpKopano 的官方 WebApp 手冊中記錄了以下範例：

define("DEFAULT_SERVER", "default:");
define("DEFAULT_SERVER", "file:///var/run/kopano/server.sock");
define("DEFAULT_SERVER", "http://localhost:236/kopano");
define("DEFAULT_SERVER", "https://localhost:237/kopano");

文件中預設的映射指向本地套接字file:///var/run/kopano/server.sock。當 WebApp 和 Core 運行在同一台機器上時，這通常是最簡單的選擇。如果它們運行在不同的機器上，本機 Unix 套接字將無法運作；您需要一個可存取的 HTTP 或 HTTPS 端點。 Kopano 的效能調優文件描述了 WebApp 主機如何透過連接埠 236（或 SSL 模式下的連接埠 237）連接到單獨的 Kopano 伺服器。請參閱Kopano 效能調優和分離伺服器配置。

本機 Unix 套接字：通常是單一主機上開銷最低的選擇，避免了僅為了本機 Web 應用程式存取而暴露 TCP 服務。缺點是套接字必須存在，並且 Web 伺服器程序必須能夠使用它。

使用 236 連接埠的 HTTP 協定：更易於跨主機進行測試，並且適用於安全架構允許的可信任內部網路。缺點是流量在 Kopano 傳輸層未加密。

連接埠 237 上的 HTTPS：適用於需要在 WebApp 和 Core 之間進行加密傳輸的情況。它引入了證書設定和驗證要求。 Kopano 的特殊設定文件展示了 WebApp 如何使用 HTTPS DEFAULT_SERVER，以及在某些情況下如何使用用戶端憑證。請參閱Kopano 的特殊 Core 配置。

3. 如果使用 Unix 套接字，該套接字是否存在，Web 伺服器能否存取到它？

對於同一主機上的部署，請驗證套接字本身：

ls -l /var/run/kopano/server.sock
file /var/run/kopano/server.sock
ss -xl | grep kopano

如果該檔案缺失，請勿建立同名常規檔案。套接字由正在運行的 Kopano 伺服器創建。因此，套接字缺失通常指向 Core 啟動問題、套接字路徑變更或配置不符。

如果套接字存在，請檢查其擁有權和權限模式。 Web 伺服器使用者必須能夠透過其目錄路徑存取套接字。根據您的發行版，Web 伺服器帳戶可能是 `<username>` www-data、apache`<username>` 或其他特定於服務的使用者。避免使用諸如 `<username>` 之類的寬泛權限模式來解決權限錯誤chmod 777；這會增加風險，並且下次服務重新建立套接字時可能會被覆寫。

更好的方法是將 WebApp 與 Kopano 產生的套接字位置對齊，然後使用發行版預設的群組或服務權限。如果您的伺服器已進行自訂，請在變更所有權之前將核心配置與 WebApp 端點進行比較。

4. 如果 Core 運作正常，但 WebApp 仍然顯示無法連接，該怎麼辦？

接下來檢查 PHP-MAPI。 Kopano 明確指出 WebApp 依賴 PHP-MAPI。 WebAppphp-mapi設定檢查還可以測試 PHP 和 PHP-MAPI 的可用性。請參閱WebApp Config.php 文件。

快速命令列檢查如下：

php -m | grep -i mapi

然而，此測試存在一個重要的限制：PHP 命令列介面可能使用與 Apache PHP、PHP-FPM 或其他 Web 伺服器整合不同的配置。命令列介面測試結果為陽性僅證明命令列環境能夠識別此模組。

有用的後續檢查包括：

php --ini
php -i | grep -i mapi

然後將其與您的 Web 伺服器或 FPM 池使用的 PHP 配置進行比較。如果缺少軟體包或版本不相容，請從與您的發行版和 Kopano 版本對應的儲存庫中安裝相符的Kopano Core/PHP-MAPI 軟體包集。不要只是為了讓擴充功能出現在清單中而混合使用不相關的 PHP-MAPI 版本php -m。

當出現以下情況時，請選擇此路由： kopano-server系統運作正常，端點正確且可達，但 WebApp 在其 PHP 端連線或設定檢查期間失敗。

權衡：當二進位檔案不匹配時，重新安裝或升級軟體包可能是正確的修復方法，但這比修復單一端點對系統的影響更大。請先確認軟體包版本，並合理安排生產環境的升級。

是否需要重新啟動 Apache、PHP-FPM 或 Kopano 伺服器？

重新啟動配置或模組發生變更的組件。

• 如果進行了更改/etc/kopano/server.cfg，請重新啟動kopano-server。
• 如果您安裝或啟用了 PHP 擴展，請重新啟動 WebApp 使用的 PHP 服務層，例如 Apache 或相關的 PHP-FPM 服務。
• 如果您只更改了 WebApp 的 PHP 配置文件，通常不需要完全重新啟動 Kopano Core，除非 Core 端點本身也發生了更改。

具體的 Web 服務指令會因發行版和 PHP 套件的差異而有所差異。例如systemctl restart apache2，可能是systemctl restart httpd`<service_name>`、`<service_name>` 或帶有版本號的 PHP-FPM 單元。請使用主機上存在的服務名稱，而不是盲目複製命令。

遠端核心伺服器和防火牆呢？

如果 WebApp 和 Kopano Core 是分開的，請先檢查路由和設定的監聽器，然後再懷疑是 WebApp 的問題。 Kopano 文件描述了透過 236 連接埠進行 HTTP 訪問，透過 237 連接埠進行 SSL 存取。因此，遠端部署會增加一些本機 Unix 套接字部署所沒有的故障模式：防火牆規則、監聽器綁定、DNS、TLS 憑證、反向代理程式和中間網路策略。

對於 HTTP 端點，至少可以檢查 Web 應用程式主機是否可以存取 TCP 監聽器：

nc -vz core.example.net 236

對於 HTTPS，請使用符合您憑證原則的工具單獨驗證 TLS 端點。成功的 TCP 連線並不能證明 Web 應用程式驗證或 MAPI 操作會成功，但連線失敗則證明 PHP-MAPI 無法透過該位址和連接埠存取已設定的服務。

如果您使用反向代理，請記住 Kopano 文件要求代理路徑和後端對應必須與 Web 應用程式使用的 URL 保持一致。官方 Core 手冊也提到了代理 Kopano 流量時需要注意的 HTTP/1.1 問題。請參閱Kopano Core 元件配置。

一個實用的診斷流程，可最大限度減少不必要的變更

1. 檢查kopano-server狀態。如果失敗，請先修復核心元件。
2. 請讀取核心日誌。必須先解決資料庫或設定故障，Web應用程式才能連線。
3. 驗證DEFAULT_SERVER。確認它與本機套接字或正確的遠端 HTTP/HTTPS 端點相符。
4. 測試實際的套接字或網路監聽器。這可以區分傳輸故障和 PHP 問題。
5. 請在 Web 執行階段環境中驗證 PHP-MAPI。不要只依賴 CLI PHP 環境。
6. 僅重啟受影響的服務。然後重新測試 Web 應用程序，如果錯誤仍然存在，請檢查日誌。

這種順序比從重新安裝軟體包開始更安全，因為它保留了測試結果，使每次測試都有意義。它還能避免相反的錯誤：在 Kopano Core 本身無法啟動的情況下，重複重新啟動 WebApp 或 Apache。

什麼時候改變 DEFAULT_SERVER 反而會成為錯誤的解決方法？

不要DEFAULT_SERVER因為登入頁面顯示連線錯誤就進行更改。如果當前值正確指向預期的核心實例，更改它可能會掩蓋原始問題或將使用者重定向到錯誤的後端。

例如，替換default:本身http://localhost:236/kopano並不等於升級。它會將傳輸方式從文件中指定的本機預設套接字變更為 TCP。這對於調試或需要 TCP 的網路拓撲可能很有用，但同時也改變了安全性和操作層面。對於同一主機上的設置，修復缺少或無法存取的套接字通常比打開另一個監聽器更簡潔。

如果錯誤仍然存在，該怎麼辦？

此時，應從關係雙方收集證據：

• DEFAULT_SERVER去除憑證或密鑰後，得到確切的值；
• systemctl status kopano-server以及最近的 Kopano 伺服器日誌條目；
• 套接字所有權或遠端監聽器資訊；
• Web 服務執行階段中 PHP 版本和已載入的 MAPI 擴充功能；
• WebApp/PHP 錯誤日誌記錄了登入失敗時的相關資訊。

Kopano 的 WebApp 文件指出，PHP 錯誤日誌記錄是透過 PHP 設定啟用的config.php，並警告不要直接顯示錯誤訊息，因為這樣做可能會損壞 JSON 回應。因此，伺服器端日誌是更好的診斷來源。在增加日誌詳細程度之前，請參考官方的 WebApp 日誌記錄設定。

一旦確定故障是出在核心啟動、傳輸、權限、PHP-MAPI 或遠端網路層面，就套用針對該層面的最小修復方案。這比將「無法連接到 Kopano Core」視為單一錯誤並使用通用解決方案要可靠得多。