內容

目標

需求

介紹

前置作業與注意事項

設定

透過網頁介面將現有控制器設定為分散式叢集模式

透過指令為新安裝的控制器設定分散式叢集模式

分散式叢集模式的高可用性

常見問題 (FAQ)

如何調整叢集節點的 IP

如何新增或刪除節點

如何在叢集模式下升級控制器

如何對分散式叢集模式無法運作進行故障排除？

如何對節點狀態顯示「已斷線」進行故障排除

如何對升級前因系統資源使用率過高導致的節點停止失敗進行故障排除？

如何對因啟動指令執行不同步而導致的節點啟動失敗進行故障排除？

目標

本文介紹了控制器分散式節點的概念，並詳述了兩種部署方式：一是透過網頁介面使用現有控制器部署分散式節點；二是新安裝控制器時，透過終端機指令進行部署。

系統需求 (Requirements)

• Omada 軟體控制器 (Omada Software Controller)
• Omada 設備，請參閱Omada 叢集部署產品清單
• Ubuntu 22.04
• JAVA17
• Mongodb v7.0

簡介 (Introduction)

Omada 軟體控制器的分散式叢集模式，能滿足客戶對網路高可用性 (High Availability) 的要求。在此模式下，多個節點協同合作管理 Omada 設備。這種合作方式不僅顯著提高了控制器可管理的設備數量上限，同時透過多節點的協調運作，確保了整個網路的高可用性。如果發生節點故障，系統將觸發自動負載平衡，故障節點的服務會由其他節點接管。在故障轉移期間，原故障節點管理站點下的設備會短暫離線，隨後自動重新連線至其他節點。一旦設備恢復「已連線」狀態，所有服務將正常運作。

如下圖所示，這是一個典型的分散式叢集部署拓撲，其中多個節點（三個或更多節點）可以共同管理 Omada 設備。

前置作業與 注意事項 (Prerequisites and Precautions)

在正式配置和部署分散式節點之前，請務必注意以下建議和事項。

• 分散式叢集模式至少需要三個節點。在設定前，請準備至少三個控制器進行部署。
• 安裝分散式叢集模式需要 Java 17。請使用 *sudo apt install openjdk-17-jre-headless* 指令來安裝 Java 17。
• 修改系統的檔案句柄 (handle) 數是使用控制器分散式叢集模式的先決條件。編輯 “/etc/security/limits.conf”，加入以下參數，儲存檔案，然後登出並重新登入以使變更生效。

* soft nofile 65535

* hard nofile 65535

請注意，修改檔案句柄數的方法可能因 Linux 版本而異。請根據您的 Linux 版本進行修改。

• 請確保每個節點的系統時間一致，時間差異應小於 20 秒。
• 請確保所有節點的 JDK 和 MongoDB 版本一致。
• 節點 IP 僅支援固定 IP (Static IP)。如果需要修改 IP/連接埠，將需要重新初始化。請參考「如何調整叢集節點的 IP」。
• 一個已加入叢集的節點，必須先與原連線斷開並從原叢集中移除，才能加入新的叢集。
• 建議將所有節點部署在同一網段內。

組態設定 (Configuration)

透過網頁介面將現有控制器配置為分散式叢集模式

步驟 1. 在「全域檢視」中，前往**全域檢視 > 設定 > 叢集**，並啟用**叢集**功能。然後選擇模式為**分散式叢集**。

步驟 2. 點擊**新增節點 (Add Node)** 以新增至少三個節點。輸入這些節點的 **名稱 (NAME)** 和 **節點管理主機名稱/IP (NODE MANAGEMENT HOSTNAME/IP)**。在此處，IPs 和主機名稱應對應不同的伺服器。在即將推出的版本中，我們將支援節點使用相同的 IP 或主機名稱共同管理設備。請在**設備管理主機名稱/IP (DEVICE MANAGEMENT HOSTNAME/IP)**中指定管理設備的 IP 位址。此 IP 位址將用於建立與設備的連線和通訊。如果未指定，將預設使用**節點管理主機名稱/IP**。然後點擊**套用 (Apply)**。

之後，控制器將彈出一個提示視窗和**初始化屬性檔案 (init properties file)**。請下載初始化屬性檔案。您需要重新啟動控制器以使設定生效。請盡快重新啟動以防止設備斷線或其他問題。離線新增的節點將被視為關閉狀態節點，這將影響災難恢復能力。請盡快初始化它們。

步驟 3. 分別替換每個節點上的 **properties** 檔案（從步驟 2 下載）。 properties 檔案的路徑是： * /opt/tplink/EAPController/data/cluster/omada_distributed_internal_mongo_cluster.properties*

步驟 4. 分別在每個節點上執行初始化指令。初始化節點時，請為所有節點設定帳號和密碼。初始化節點時，**務必首先初始化主要節點**（導出初始化屬性的那個節點）。否則，初始化可能會失敗。

sudo omadacluster -config

/opt/tplink/EAPController/data/cluster/omada_distributed_internal_mongo_cluster.properties -nodeName init

• 主要節點初始化期間終端機輸出的範例。

• 非主要節點初始化期間終端機輸出的範例

步驟 5. 部署成功後，前往「叢集」頁面確認。當分散式叢集模式正常運行時，您可以透過任一節點存取控制器。

透過指令為新安裝的控制器配置分散式叢集模式

步驟 1. 選擇叢集模式安裝（安裝後不會自動啟動）。

• 使用 deb 進行安裝

echo "omadac omadac/init-cluster-mode boolean true" | sudo debconf-set-selections

sudo dpkg -i /path/to/controller_installation_package

• 使用 tar.gz 進行安裝

解壓縮後，透過 shell 安裝腳本部署叢集模式。輸入 ./install.sh *init - cluster – mode*，系統在安裝後不會自動啟動，並會列印設定叢集的相關提示資訊。

步驟 2. 開始安裝控制器，並依提示編輯 properties 檔案。

修改每個節點的 properties 檔案 * /opt/tplink/EAPController/data/cluster/omada_distributed_internal_mongo_cluster.properties *

步驟 3 分別在每個節點上執行初始化指令。

sudo omadacluster -config /opt/tplink/EAPController/data/cluster/omada_distributed_internal_mongo_cluster.properties -node <nodeName> init

• 主要節點初始化期間終端機輸出的範例

非主要節點初始化期間終端機輸出的範例

步驟 4 部署成功後，登入控制器並設定使用者名稱和密碼，其他節點將同步使用者名稱和密碼。

然後前往「叢集」頁面確認。當分散式叢集模式正常運行時，您可以透過任一節點存取控制器。

分散式叢集模式的高可用性 (High Availability)

分散式叢集模式的高可用性特點如下所述。當混合節點總數為 3~4 個時，允許 1 個混合成員斷線；當混合節點總數為 5~6 個時，允許 2 個混合成員斷線；當混合節點總數為 7 個時，允許 3 個混合成員斷線。也就是說，允許故障的混合節點數量少於混合節點最大數量的一半。

如果斷線節點的數量超過允許的限制，整個叢集將會故障。若要還原叢集，您需要讓斷線節點恢復連線，使允許故障的節點數量少於混合節點最大數量的一半。

如果需要重新啟動叢集，請確保在所有節點都停止之後，同時啟動超過總節點數一半的數量。

常見問題 (FAQ)

如何調整叢集節點的 IP

當控制器分散式叢集模式正在運行時，如果您想修改節點的 IP，需要遵循以下步驟：

(1) 如果要修改的節點狀態為「已連線」：

a. 修改指定節點的網路卡 IP，使其同時綁定**舊** IP 和**新** IP。

b. 在任一節點的「叢集」介面中，將指定節點的 IP 更改為新 IP。

c. 在指定節點上，執行指令 *sudo tpeap stop* 關閉節點，然後修改網路卡以僅綁定新 IP。

d. 執行 *sudo tpeap start* 啟動節點。

(2) 如果要修改的節點狀態為「已斷線」：

a. 修改指定節點的網路卡 IP，使其同時綁定舊 IP 和新 IP。

b. 在任一線上的節點的「叢集」介面中，將指定節點的 IP 更改為新 IP，並導出新的 properties 檔案。

c. 將 properties 檔案傳輸到要修改的節點。

d. 在指定節點上，使用此 properties 檔案執行初始化指令 *sudo omadacluster -config <propertiesPath> -node <nodeName> init* 進行初始化。

如何新增或刪除節點

(1) 新增節點

步驟 1. 在新節點上調整檔案句柄數，並安裝相同版本的控制器。

步驟 2. 在現有節點上設定新節點。前往**全域檢視 > 設定 > 叢集**介面，點擊**新增節點**。輸入新節點的**名稱**和 **IP/主機名稱**，然後點擊**套用**。

點擊**確認**。

步驟 3. 點擊**導出初始化屬性 (Export init properties)**，然後下載檔案並將其複製到新加入節點上控制器的 * /opt/tplink/EAPController/data/cluster* 路徑。

步驟 4. 在新節點上開啟終端機並執行初始化指令。

sudo omadacluster -config

/opt/tplink/EAPController/data/cluster/omada_distributed_internal_mongo_cluster.properties -nodeName init

步驟 5 . 成功新增節點後，前往「叢集」頁面確認。當分散式叢集模式正常運行時，您可以透過任一節點存取控制器。

(2) 刪除節點

步驟 1. 前往要刪除的節點並停止其控制器。

步驟 2. 從任一節點檢查節點狀態。

步驟 3. 當節點上出現刪除圖示時，點擊刪除按鈕，然後點擊**套用**。

步驟 4. 您可以從任一節點看到正在被刪除的節點。

如何在叢集模式下升級控制器

目前 Omada 叢集支援離線升級。在升級 Omada 叢集之前，您應該停止所有節點上控制器的運行。

為將對網路的影響降到最低，請盡量在非忙碌時段升級叢集。

請確保所有設備韌體都支援叢集部署，以防止升級後設備斷線。

具體的升級步驟如下：

1. 在所有節點上執行 **sudo tpeap stop** 指令，停止叢集運行。
2. 在所有節點上安裝較新版本的控制器。參考您先前版本的安裝方式，選擇使用 deb 或 tar.gz 進行安裝。
3. 請確保所有節點都已正確升級到較新版本後。然後**同時**運行所有節點的控制器，執行指令 **sudo tpeap start**。
4. 等待所有控制器顯示「Started successfully (成功啟動)」。然後您就可以正常存取叢集了。

以一個節點的升級過程為例：

如何對分散式叢集模式無法運作進行故障排除？

• 檢查檔案句柄數 (handle number) 的修改是否成功。您可以使用 "ulimit -a" 來驗證檔案句柄數是否修改成功。
• 檢查每個節點的參數是否一致，包括控制器版本、Mongodb 版本和 Java 版本。
• 如果節點長時間無法成功連線，請確保透過網頁介面將現有控制器配置為分散式叢集模式時，從**主要節點**開始初始化。

如何對節點狀態顯示「已斷線」進行故障排除

請檢查每個節點的**全域檢視 > 設定 > 系統設定 > 目前節點系統時間 (Current Node System Time)** 的時間差是否在 20 秒以內。

如何對升級前因系統資源使用率過高導致的節點停止失敗進行故障排除？

1. 在異常節點上執行 **ps -ef | grep ‘java’** 指令，查詢系統中活躍的 Java 程序。
2. 執行 **sudo kill -9 <PID>** 指令，強制停止異常節點上的 Java 程序（將 <PID> 替換為實際的程序 ID）。
3. 按照正常步驟安裝較新版本的控制器，然後完成升級。

如何對因啟動指令執行不同步而導致的節點啟動失敗進行故障排除？

請在異常節點上再次執行 **sudo tpeap start** 指令。

如需了解各項功能與配置的更多詳細資訊，請前往 下載中心 下載您產品的使用手冊。