如何配置 Kopano Z-Push 以進行 ActiveSync 移動同步

Z-Push 允許相容的行動裝置透過 Microsoft Exchange ActiveSync 與 Kopano Core 同步。可靠的配置取決於 Z-Push 後端與 Kopano 伺服器的匹配、透過 HTTPS 發布 ActiveSync 端點以及在升級過程中保留 Z-Push 狀態。正確的配置還取決於您是需要最簡單的單一伺服器部署，還是需要獨立的服務和多主機容量。

選擇適合您環境的配置

Z-Push 是一個開源的 ActiveSync 同步伺服器。它充當相容設備和群組後端之間的協定層；裝置通常會新增一個 Exchange 或 ActiveSync 帳戶，而不是直接連接到 Kopano。當所選後端和行動用戶端支援這些資料類型時，Z-Push 可以同步電子郵件、聯絡人、日曆項目和任務。 Kopano 在其Kopano Core 管理員文件中描述了這種關係。

對於現有的 Kopano Core 伺服器，Kopano 後端是理想的起點。只有當 IMAP 和 CalDAV/CardDAV 系統實際儲存相關數據，或您有意使用不同的資料來源時，才選擇 IMAP 和 CalDAV/CardDAV。後端替換並非功能中立：同步行為、通訊錄、任務、公用資料夾和相容性都可能有所不同。

安裝或變更配置之前

• 請記錄您的 Kopano Core、Z-Push、PHP、Web 伺服器和作業系統版本。檢查您計劃使用的軟體包支援的組合；僅憑 Z-Push 支援的 PHP 版本並不能保證 Kopano MAPI 擴充功能適用於該版本。
• 選擇用戶端將使用的公共主機名，例如sync.example.com，並為該名稱準備受信任的 TLS 憑證。
• 確定 Z-Push 是運行在 Kopano 主機上還是單獨的 Web 伺服器上。單獨的主機可以隔離面向 Web 的服務，但這需要 Kopano 能夠正常存取網絡，並且 MAPI 伺服器位址配置正確。
• 升級前請備份 Z-Push 設定和狀態目錄。 Z-Push 狀態會追蹤裝置同步情況；Kopano 的升級指南文件指出，需要保留現有行動裝置設定檔的狀態。
• 在註冊個人或公司手機之前，請選擇每個使用者應同步的資料類型並查看設備策略要求。

設定伺服器端

1. 安裝相符的 Z-Push 軟體包

請使用專為您的發行版和 Kopano 版本構建的軟體包（如有）。典型的基於軟體包的設定會將 Z-Push 核心、Kopano 後端和 Web 伺服器整合分開。 Kopano 管理員手冊中描述了諸如z-push-backend-kopanoWeb 伺服器設定軟體包之類的軟體包，但具體的軟體包名稱和儲存庫可用性取決於發行版，並且該手冊涵蓋的是較早版本的 Kopano 核心文件。在使用其歷史命令之前，請確認目前軟體包是否受支援。

原始碼安裝和容器化部署提供了對版本和檔案系統佈局的更多控制權。但它們也把責任轉移到了維運人員身上：您必須確保 PHP 擴充功能在 Web 伺服器使用的相同 PHP 執行時間環境中可用，持久化狀態和日誌，並在重新部署後保持 ActiveSync 路由的可存取性。

2. 選擇 Kopano 後端和伺服器位址

在 Z-Push 的主配置中，使用已安裝版本文件中記錄的設定和類別名，將後端提供者設定為 Kopano 後端。打包部署中常見的設定是BackendKopano：請勿在未查看軟體包提供的範例之前，將設定貼上到結構不同的設定檔中。在 Kopano 後端配置中，如果 Kopano 服務不在同一主機上或無法透過預設本機連線訪問，請設定 MAPI 伺服器位址。

// Example only: confirm the setting and file path in your installed package.
define('BACKEND_PROVIDER', 'BackendKopano');

不同打包版本之間的檔案名稱和常數可能有所不同。請勿在公開的配置範例中洩露敏感信息，限製配置文件權限，並驗證 Apache 或 PHP-FPM 使用的 PHP 運行時是否能夠加載所需的 Kopano MAPI 擴展。命令列 PHP 環境運作正常並不能證明 Web PHP 運行時也啟用了相同的擴充。

3. 透過 HTTPS 發布 ActiveSync 端點

用戶端需要一個穩定的 HTTPS URL 來存取 ActiveSync 處理程序，通常是主機名稱後面跟著 ` /Microsoft-Server-ActiveSync.`。設定 Apache、Nginx 或您選擇的反向代理，將該路徑路由到 Z-Push 的入口點。保持規範端點與主機名稱一致，避免重定向更改請求方法或將行動用戶端傳送到其他路徑。 Kopano 指南特別警告不要重新命名 Z-Push 目錄來建立端點，因為重定向可能會破壞裝置同步。

請使用名稱與端點主機名稱相符的有效憑證。 HTTPS 可保護傳輸中的憑證和同步數據，許多目前的行動用戶端會拒絕不受信任或不匹配的憑證。請勿透過在生產帳戶上停用 TLS 來規避憑證警告。如果 TLS 在反向代理處終止，請確認代理程式依預期轉送要求和驗證相關的標頭，並確保代理程式到 Z-Push 的連線符合您的內部安全性原則。

4. 設定可寫入狀態和日誌位置

Z-Push 必須能夠寫入其狀態和日誌位置。授予特定 Web 伺服器帳戶存取權限，例如www-data在許多 Debian 和 Ubuntu 系統中；服務帳戶因發行版而異。避免將這些目錄設定為全域可寫入。在多主機部署中，選擇專為共享存取而設計的狀態機制，而不是假設一個節點上的檔案對另一個節點可見。 Kopano 管理員指南解釋了狀態目錄權限，並指出在升級 Z-Push 時應保留狀態。

設定手機帳戶

在手機上，新增工作帳戶或 Exchange 帳戶，然後選擇 Exchange ActiveSync、Microsoft Exchange 或該用戶端提供的等效選項。具體標籤和螢幕會因作業系統和郵件應用程式而異。輸入使用者的電子郵件地址和憑證。如果自動發現功能無法找到伺服器，請輸入 Z-Push 主機名，如果需要，還需輸入 ActiveSync 端點。請使用 Kopano 驗證設定中要求的使用者名稱格式；不要假設完整的電子郵件地址和 Kopano 登入名稱始終相同。

啟用 SSL/TLS，並在仔細查看裝置原則的允許內容（例如設定密碼或應用組織管理的裝置控制）後再接受它們。選擇要同步的類別：郵件、聯絡人、行事曆和任務（如有）。舊版Kopano 行動裝置指南描述了 Exchange 帳戶的一般工作流程，但其中的螢幕截圖和作業系統標籤已過時。請按照目前手機的提示操作，而不是直接複製舊的選單路徑。

如果郵件應用程式提供同步規劃功能，推播或頻繁更新可以加快郵件送達速度，但可能會消耗更多電量和網路流量。延長輪詢間隔可以減少背景檢查，但會延遲新郵件的送達。對於工作郵箱，如果郵件的及時送達至關重要，建議先使用客戶端的推送設定（如果支援），然後根據電池使用情況和組織策略進行調整。

在註冊更多設備之前，請先驗證每一層。

1. 終端機：在瀏覽器中開啟公用主機名，並確認 TLS 憑證有效。在新增帳戶前，應先修復瀏覽器錯誤或憑證警告。
2. Web路由：確認ActiveSync路徑能夠到達Z-Push處理程序，且沒有重定向循環或傳回通用的Web伺服器404頁面。該端點是協議處理程序，而非普通網站。
3. 後端驗證：使用測試帳戶並確認 Z-Push 日誌顯示後端連線成功，且不洩漏密碼或令牌。
4. 初始同步：新增一部測試手機，並檢查選定的郵件資料夾、聯絡人、行事曆和任務。成功登入並不代表所有資料類型都已正確同步。
5. 雙向更改：在手機上建立測試日曆事件，並確認它出現在 Kopano 中；然後在 Kopano 中進行測試更改，並確認更改已傳達至手機。
6. 重新啟動與恢復：在已排程的測試視窗期間重新啟動 Web 服務，驗證同步是否已恢復，並確認狀態目錄是否完好無損。

根據症狀進行故障排除

請同時使用 Z-Push 本身的日誌和 Web 伺服器/PHP 日誌，並確保時間戳記一致。如果您需要測試新的裝置設定文件，請先確認伺服器端狀態重設是否適用於您的版本，並了解此操作是否會觸發完整的重新同步。請勿將刪除整個狀態目錄作為首要的故障排除步驟。

您應該選擇哪種配置？

對於小型現有 Kopano Core 安裝，通常只需使用發行版支援的 Z-Push 軟體包集、Kopano 後端、一個 HTTPS 端點以及精心管理的本機狀態權限，即可最大限度地減少元件數量。當隔離或操作邊界需要額外的網路和 PHP-MAPI 相容性運作時，才應使用單獨的主機。只有在選擇並測試了共享狀態方案後，才應考慮使用多主機設計。如果郵件、日曆或聯絡人位於 Kopano 之外，請在部署前比較相關的 Z-Push 後端，並在使用者實際使用的行動用戶端上測試每種資料類型。

Z-Push 和 Kopano 的打包方式、PHP 支援以及裝置行為在不同版本之間可能會有所變化。請以已安裝軟體套件的範例設定及其對應的版本文件為準；舊版 Kopano 手冊僅供參考，不建議直接複製到新系統中。 Z -Push 專案倉庫是目前專案代碼和版本資訊的來源。