逐一升級 Apigee Edge Private Cloud 的作業系統

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本文說明如何使用替代方法，升級 Apigee Edge Private Cloud 叢集中伺服器的作業系統 (OS)。這種逐一節點升級的方法可讓您就地升級 OS，一次升級一部機器/節點，不必設定全新的平行資料中心。

相容性

在逐一啟動節點的 OS 升級作業前，請先確認目前的 Apigee Edge for Private Cloud 版本支援目標 OS 版本。如要確認，請參閱作業系統相容性矩陣。

必要條件

開始逐一升級節點前，請確認已完成下列工作：

備份所有節點

建議您先完整備份所有節點 (例如 VM 層級備份和/或元件層級備份)，再按照程序操作，確保安全無虞。 以防後續步驟無法正常運作。如要進一步瞭解元件層級備份，請參閱「備份及還原」。

確認 Edge 正在執行

使用下列指令，確保 Edge 在更新程序期間正常運作：

/opt/apigee/apigee-service/bin/apigee-all status

節點更換順序

建議您按照元件類型，依下列順序升級節點：

• Cassandra
• Zookeeper
• Postgres
• LDAP
• Qpid
• Message-Processor
• 路由器
• 管理伺服器
• UI/UE
• 單一登入 (SSO)

其他情況

逐一升級節點的 OS 時，如果現有設定包含下列任一設定，請考慮採取這些額外步驟：

• apigee-mtls - 如果啟用 apigee-mtls，這個設定就不支援節點對節點的 OS 升級 (輪流)。如要升級，請按照「升級 apigee-mtls 指南」操作。

Cassandra

更換 Cassandra 時，請先更換非種子節點，再更換種子節點。

以下是 Cassandra 的特殊案例：

• Cassandra Native-mTLS - 如果啟用並強制執行 Native-mTLS，請設定 conf_cassandra_client_encryption_optional=true，移除已啟用 mTLS 節點的強制執行作業。詳情請參閱原生 mTLS 說明文件。
• 已啟用 Cassandra 節點間加密 - 請參閱「啟用 Cassandra 節點間加密」，確保新取代節點的信任儲存區包含現有 Cassandra 節點的憑證，反之亦然。

更換 Cassandra 節點的步驟如下：

1. 拍攝虛擬機器快照 (如有可能) 來備份節點，並在所有節點上使用下列指令，為 Cassandra 進行 Apigee 備份：

   apigee-service apigee-cassandra backup

2. 取得搭載升級版 OS 的新節點。
3. 套用特定作業系統的必要條件。
4. 下載並執行 Edge 檔案，安裝 apigee-service 公用程式。使用中的 Apigee 版本啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
5. 列出種子節點：

   apigee-service apigee-cassandra configure -search conf_cassandra_seeds

6. 更新設定檔，方法是變更現有 Cassandra 節點的 IP，並換成新節點的 IP 位址。

   現有 CASS_HOSTS

   CASS_HOSTS="$IP1 $IP2 $IP3"

   新版 CASS_HOSTS

   CASS_HOSTS="$IP1 $IP4 $IP3"

7. 使用更新後的 Cassandra 節點 IP 重新設定叢集中的現有節點 (要替換的節點除外)。請參閱設定檔參考資料。

   /opt/apigee/apigee-setup/bin/setup.sh -p c -f updatedConfigFile

8. 停止並取消註冊舊節點上的 Cassandra：
   1. 在要更換的節點上停止 Cassandra：

      apigee-service apigee-cassandra stop

   2. 列出要停用的 Cassandra 節點 UUID (如果是多個資料中心，請相應考量)：

      apigee-adminapi.sh servers list -r dc-1 -p central -t application-datastore --admin AdminEmailID --pwd 'AdminPassword' --host localhost

   3. 取消註冊與現有 Cassandra UUID 相關聯的資料儲存區類型：

      curl -u AdminEmailID:'AdminPassword' -X POST http://MS_IP:8080/v1/servers -d "type=cache-datastore&type=user-settings-datastore&type=scheduler-datastore&type=audit-datastore&type=apimodel-datastore&type=application-datastore&type=edgenotification-datastore&type=identityzone-datastore&type=auth-datastore&region=dc-1&pod=central&uuid=old_cassandra_uuid&action=remove"

   4. 刪除伺服器。

      curl -u AdminEmailID:AdminPassword -X DELETE http://MS_IP:8080/v1/servers/old_cassandra_uuid

9. 準備 apigee-cassandra 主機的新節點。在新的 Cassandra 節點上，於 /opt/apigee/customer/application/cassandra.properties 下方的 cassandra.properties 檔案中新增下列這行 (如果沒有這個檔案，請建立)：

   conf_jvm_options_custom_settings=-Dcassandra.replace_address=IPOfOldCassandraNode -Dcassandra.allow_unsafe_replace=true

10. 確認 cassandra.properties 檔案中的擁有者和群組已設為 apigee:apigee。視需要使用下列指令更新擁有者和群組：

    chown apigee:apigee /opt/apigee/customer/application/cassandra.properties

11. 在新增節點上安裝 Cassandra 並執行設定：

    apigee-service apigee-cassandra install

    apigee-service apigee-cassandra setup -f updatedConfigFile

12. 設定新節點後，請移除新增至 /opt/apigee/customer/application/cassandra.properties 的額外設定，然後重新啟動 apigee-cassandra：

    conf_jvm_options_custom_settings=-Dcassandra.replace_address=IPOfOldCassandraNode -Dcassandra.allow_unsafe_replace=true

    apigee-service apigee-cassandra restart

13. 檢查新更換節點的狀態：

    apigee-service apigee-cassandra status

    /opt/apigee/apigee-cassandra/bin/nodetool status

14. 重新建構新增至叢集的節點：

    /opt/apigee/apigee-cassandra/bin/nodetool rebuild -dc dc-1

15. 在設定檔中更新新的 Cassandra 節點 IP，重新設定 Router、Message-Processor、Qpid、Postgres 和 Management 伺服器的現有節點：

    /opt/apigee/apigee-setup/bin/setup.sh -p r|mp|qs|ps|ms|mo -f updatedConfigFile

16. 從舊節點移除/解除安裝 Cassandra：

    apigee-service apigee-cassandra uninstall

17. 對叢集中的其他 Cassandra 節點重複執行上述步驟。

Zookeeper

請參閱下列步驟，更換 Zookeeper 節點。建議先更換追隨者節點，再更換領導者節點，確保集合維持法定人數。

1. 備份節點，方法是建立虛擬機器快照 (如有可能)，並在所有節點上備份 Zookeeper 的 Apigee。
2. 停止並解除安裝現有節點上的 Zookeeper：

   apigee-service apigee-zookeeper stop

   apigee-service apigee-zookeeper uninstall

3. 取得搭載升級版 OS 的新節點。
4. 套用特定作業系統的必要條件。
5. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
6. 更新設定檔，移除過時/已刪除的節點 IP 位址，並替換為 Zookeeper 的新節點 IP。詳情請參閱設定檔參考資料：

   現有 ZK 設定

   ZK_HOSTS="$IP1 $IP2 $IP3"
   ZK_CLIENT_HOSTS="$IP1 $IP2 $IP3"
       

   已更新 ZK 設定

   ZK_HOSTS="$IP1 $IP4 $IP3"
   ZK_CLIENT_HOSTS="$IP1 $IP4 $IP3"
       

7. 使用更新後的設定檔，在新節點上安裝、設定及啟動 Zookeeper：

   /opt/apigee/apigee-setup/bin/setup.sh -p zk -f updatedConfigFile

8. 使用 updatedConfigFile 變更現有的 Zookeeper 節點：

   /opt/apigee/apigee-setup/bin/setup.sh -p zk -f updatedConfigFile

9. 更新設定檔中的新 Zookeeper 節點 IP，重新設定現有的 Router、Message-Processor、Qpid、Postgres 和 Management 伺服器節點：

   /opt/apigee/apigee-setup/bin/setup.sh -p r|mp|qs|ps|ms|mo -f updatedConfigFile

10. 針對所有 Zookeeper 節點重複上述步驟。

Postgres

本節將說明如何以零停機時間的方式升級 Postgres 節點，並完成所述步驟。後續小節會提供完成每個步驟的詳細說明。

• 將任何現有的待命節點換成目標作業系統。
• 將新的待命節點升級為主要節點。
• 停用舊主機。
• 繼續更換其他待機節點。

建議先停止 edge-qpid-server，再開始更換作業，盡量避免遺失任何可能的 Analytics 訊息。

apigee-service edge-qpid-server stop

待命中

1. 取得 edge-postgres-server 節點的 UUID：

   curl http://pg_standby_ip:8084/v1/servers/self

2. 停止 Postgres：

   apigee-service edge-postgres-server stop

   apigee-service apigee-postgresql stop

3. 按照這些步驟，從 Analytics 群組中移除現有的 Postgres 待命伺服器。
4. 解除安裝 apigee-postgres 和 postgres-server：

   apigee-service edge-postgres-server uninstall

   apigee-service apigee-postgresql uninstall

5. 取得搭載升級版 OS 的新節點。
6. 套用特定作業系統的必要條件。
7. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
8. 在現有主要執行個體上設定主要/待命複寫，方法是使用 EXISTING_PG_MASTER_IP 和 NEW_PG_STANDBY_IP 更新設定檔。詳情請參閱設定檔參考資料：

   PG_MASTER=EXISTING_PG_MASTER_IP

   PG_STANDBY=NEW_PG_STANDBY_IP

   apigee-service apigee-postgresql setup-replication-on-master -f updatedConfigFile

9. 在新待命節點上，使用主要/待命設定安裝、設定及啟動 Postgres：

   PG_MASTER=EXISTING_PG_MASTER_IP

   PG_STANDBY=NEW_PG_STANDBY_IP

   /opt/apigee/apigee-setup/bin/setup.sh -p ps -f updatedConfigFile

10. 驗證待命設定：

    apigee-service apigee-postgresql postgres-check-standby

主要執行個體

1. 取得現有 Postgres 主節點的 UUID：

   curl http://pg_ip:8084/v1/servers/self

2. 將升級後的新作業系統待命節點升級為主要節點。
3. 停止現有主要執行個體上的 Postgres：

   apigee-service apigee-postgresql stop

   apigee-service edge-postgres-server stop

4. 將新的待機節點升級為主要節點：

   apigee-service apigee-postgresql promote-standby-to-master EXISTING_PG_MASTER_IP

5. 從 Analytics 和消費者群組中移除舊的主節點。
6. 將新主節點新增至 Analytics 和消費者群組。
7. 如果使用營利功能，請更新新的 Postgres 主要節點，並按照下列步驟操作。
8. 主要節點更換完畢後，即可使用更新後的主要節點設定啟動 edge-qpid-server：

   apigee-service edge-qpid-server start

9. 如果您使用營利功能，也請重新啟動管理伺服器和訊息處理器：

   apigee-service edge-management-server restart

10. 在舊版主機上停止並解除安裝 apigee-postgres 和 postgres-server：

    apigee-service edge-postgres-server uninstall

    apigee-service apigee-postgresql uninstall

新增備用裝置

1. 取得搭載升級版 OS 的新節點。
2. 套用特定作業系統的必要條件。
3. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
4. 使用新主要執行個體 IP 和新待命節點 IP，在新主要執行個體和新待命節點設定檔中設定主要執行個體/待命節點複製作業。詳情請參閱設定檔參考資料：

   apigee-service apigee-postgresql setup-replication-on-master -f updatedConfigFile

5. 在新待命節點上安裝及設定：

   /opt/apigee/apigee-setup/bin/setup.sh -p ps -f updatedConfigFile

6. 按照設定主要待命裝置的步驟，將新的待命裝置新增至分析群組。

LDAP

更換 LDAP 節點時，管理伺服器必須停止運作，且在更換節點期間，任何管理 API 都會視為無法使用。

1. 在所有節點上停止管理伺服器：

   apigee-service edge-management-server stop

2. 停用現有 LDAP 節點：
   1. 為 LDAP 節點建立 VM 層級的備份/快照。
   2. 停止 LDAP 前，請務必擷取 LDAP 資料的計數，以便稍後驗證，例如：

      ldapsearch -o ldif-wrap=no -b "dc=apigee,dc=com" -D "cn=manager,dc=apigee,dc=com" -H ldap://:10389 -LLL -x -w Secret123 | wc -l

   3. 如要設定主動/被動轉送：
      1. 在被動節點上新增 mark_writable.ldif 檔案，並加入以下內容，將目前的被動節點設為作用中：

         dn: olcDatabase={2}bdb,cn=config
         changetype: modify
         replace: olcReadOnly
         olcReadOnly: FALSE

      2. 在被動節點上執行下列指令，將其設為作用中：

         ldapmodify -a -x -w "$APIGEE_LDAPPW" -D "$CONFIG_BIND_DN" -H "ldap://:10389" -f mark_writable.ldif

      3. 如果採用主動-主動架構，請繼續執行步驟 d)，停用節點。
   4. 在 Active-Active LDAP 設定中，中斷兩個 LDAP 節點之間的複製作業，然後更新設定。按照 LDAP 停用文件中列出的步驟操作。
   5. 停止並備份 LDAP 資料，然後解除安裝現有 LDAP 節點 (如果已完成主動-主動設定，請略過此步驟)：

      apigee-service apigee-openldap stop

      apigee-service apigee-openldap backup

      apigee-service apigee-openldap uninstall

3. 取得搭載升級版 OS 的新節點。
4. 套用特定作業系統的必要條件。
5. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
6. 設定新的 LDAP 節點：
   1. 根據設定更新新節點的 configFile，您可以參閱「Edge 設定檔參考資料」，根據僅限主動或主動/主動設定：
      • LDAP_TYPE
      • LDAP_PEER
      • LDAP_SID
      • USE_LDAP_REMOTE_HOST=y/n
   2. 使用 updatedConfigFile 在新節點上設定並啟動 LDAP：

      /opt/apigee/apigee-setup/bin/setup.sh -p ld -f updatedConfigFile

   3. 從舊節點備份 LDAP 資料 (如果可以略過主動-主動設定)：
      1. 在新節點上進行備份範例，這樣系統就會產生預設備份資料夾/路徑：

         apigee-service apigee-openldap backup

      2. 將備份資料從舊節點移至產生的備份資料夾。
      3. 還原資料前，請先停止 apigee-openldap：

         apigee-service apigee-openldap stop

      4. 還原從舊節點建立的備份：

         apigee-service apigee-openldap restore backup_file

         例如：

         apigee-service apigee-openldap restore 2026.02.09,10.28.20

7. 針對其他 LDAP 節點重複執行上述步驟 (如果為作用中-作用中)。
8. 使用更新的 LDAP 主機設定重新設定並啟動管理伺服器：

   /opt/apigee/apigee-setup/bin/setup.sh -p mt -f updatedConfigFile

9. 重新設定並啟動單一登入 (SSO) (如適用)：

   apigee-service apigee-sso setup -f updatedConfigFile

   apigee-service apigee-sso restart

10. (選用) 按照說明文件中的步驟，將第二個 Active Directory 設定為唯讀。

Qpid

如要以升級的 OS 節點取代現有 Qpid 節點，請務必執行下列步驟：

1. 停止接收訊息處理器傳送至現有節點佇列的任何訊息。
2. 排除佇列中的現有訊息。
3. 停止並停用現有節點。

停用現有節點。為確保郵件不會遺失，請採取下列額外措施：

1. 停止 Qpid 代理程式：

   apigee-service apigee-qpidd stop

2. 封鎖所有訊息處理器從通訊埠 5672 傳入的流量：

   iptables -A INPUT -p tcp --dport 5672 -s MP_IP -j DROP

3. 再次啟動 Qpid 代理，排空現有訊息：

   apigee-service apigee-qpidd start

4. 開始停用前，請務必將佇列中的所有訊息排空至消費者。
5. 取得 edge-qpid-server 節點的 UUID：

   curl http://qpid_node_ip:8083/v1/servers/self

6. 完成 Qpid 的停用或移除步驟，從 Analytics 移除 apigee-qpidd 和 edge-qpid-server。
7. 停止並解除安裝 apigee-qpidd 和 edge-qpid-server：

   apigee-service apigee-qpidd stop

   apigee-service edge-qpid-server stop

   apigee-service apigee-qpidd uninstall

   apigee-service edge-qpid-server uninstall

新增節點：

1. 取得搭載升級版 OS 的新節點。
2. 套用特定作業系統的必要條件。
3. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
4. 在新節點上設定及執行 Qpid 服務，然後按照這些步驟將服務加入消費者群組。如要新增其他群組 (例如營利)，請按照相同步驟操作。
5. 如果已啟用營利服務，請重新啟動管理伺服器和訊息處理器：

   apigee-service edge-management-server restart

   apigee-service edge-message-processor restart

6. 在所有 Qpid 節點上重複上述步驟。

Message-processor

1. 取得 edge-message-processor 節點的 UUID：

   curl http://mp_ip:8082/v1/servers/self

2. 停用並解除安裝訊息處理器節點。
3. 如果已啟用營利服務，請解除安裝 edge-mint-message-processor。
4. 解除安裝訊息處理工具：

   apigee-service edge-message-processor uninstall

5. 取得搭載升級版 OS 的新節點。
6. 套用特定作業系統的必要條件。
7. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
8. 按照這些步驟，將訊息處理器新增至叢集、完成設定並啟動。
9. 如果啟用營利功能，請一併設定營利服務和訊息處理器。詳情請參閱以下說明文件。

路由器

1. 取得 edge-router 節點的 UUID：

   curl http://router_ip:8081/v1/servers/self

2. 停用可連線性並驗證是否可連線：

   iptables -A INPUT -i eth0 -p tcp --dport 15999 -j REJECT

   curl -vvv -X GET http://router_ip:15999/v1/servers/self/reachable

3. 停用並解除安裝路由器節點。
4. 解除安裝路由器：

   apigee-service edge-router uninstall

5. 取得搭載升級版 OS 的新節點。
6. 套用特定作業系統的必要條件。
7. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
8. 將路由器新增、設定及啟動至叢集。

管理伺服器

僅限單一管理伺服器

1. 取得搭載升級版 OS 的新節點。
2. 套用特定作業系統的必要條件。
3. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
4. 使用更新後的 IP 和設定檔新增管理伺服器 (請參閱這裡)，然後執行設定指令：

   /opt/apigee/apigee-setup/bin/setup.sh -p mt -f updatedConfigFile

5. 使用新的管理 IP 設定重新設定並重新啟動 UI。

   /opt/apigee/apigee-setup/bin/setup.sh -p ui -f updatedConfigFile

6. 使用新的管理 IP 設定重新設定 SSO (如適用)：

   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile

7. 使用新的管理 IP 設定重新設定新版 UI (UE) (如適用)：

   /opt/apigee/apigee-setup/bin/setup.sh -p ue -f updatedConfigFile

8. 如果已啟用營利功能：
   1. 重新設定營利 MS，並採用新的管理 IP 設定 (如適用)，請參閱營利設定說明文件。

      /opt/apigee/apigee-setup/bin/setup.sh -p mo -f updatedConfigFile

   2. 重新啟動管理伺服器：

      apigee-service edge-management-server restart

9. 按照這些步驟，在現有/舊節點上停用管理伺服器。
10. 如果已啟用營利功能，請從 Analytics 群組中移除管理伺服器 UUID。範例：

    curl -v -u AdminEmail:AdminPassword -X DELETE "http://localhost:8080/v1/analytics/groups/ax/mint_axgroup/servers?uuid=MS_UUID&type=consumer-server"

11. 解除安裝營利管理伺服器：

    apigee-service edge-mint-management-server uninstall

多個管理伺服器

1. 使用現有節點上的另一個管理伺服器，按照這些步驟停用其中一個管理伺服器。
2. 停止並解除安裝管理伺服器：

   apigee-service edge-management-server stop

   apigee-service edge-management-server uninstall

3. 取得搭載升級版 OS 的新節點。
4. 套用特定作業系統的必要條件。
5. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
6. 使用更新後的 IP 和設定檔新增管理伺服器 (請參閱這裡)，然後執行設定指令：

   /opt/apigee/apigee-setup/bin/setup.sh -p mt -f updatedConfigFile

7. 使用更新的管理 IP 設定重新設定並重新啟動 UI：

   /opt/apigee/apigee-setup/bin/setup.sh -p ui -f updatedConfigFile

8. (僅在啟用 SSO 時) 使用更新的管理 IP 設定重新設定並重新啟動 SSO：

   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile

9. (僅適用於啟用新版 UI 的情況) 使用更新後的管理 IP 設定重新設定並重新啟動新版 UI：

   /opt/apigee/apigee-setup/bin/setup.sh -p ue -f updatedConfigFile

10. 對其他管理伺服器重複上述步驟。

UI/UE

1. 備份 UI 節點/建立 UI 節點的 VM 快照。
2. 停止並解除安裝 UI：

   apigee-service edge-ui stop

   apigee-service edge-ui uninstall

3. (僅限使用新版 UI) 停止並解除安裝新版 UI：

   apigee-service edge-management-ui stop

   apigee-service edge-management-ui uninstall

4. 取得搭載升級版 OS 的新節點。
5. 套用特定作業系統的必要條件。
6. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
7. 在新節點上設定及執行 edge-ui，並更新 IP 設定：

   /opt/apigee/apigee-setup/bin/setup.sh -p ui -f updatedConfigFile

8. (僅在啟用 SSO 時) 視需要使用 UI 新節點 IP 設定，重新設定並執行 SSO：

   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile

9. (僅在啟用新版 UI 時) 在新節點上設定及執行新版 UI，並更新 IP 設定：

   /opt/apigee/apigee-setup/bin/setup.sh -p ue -f updatedConfigFile

   apigee-service edge-management-ui configure-sso -f updatedConfigFile

   apigee-service edge-ui configure-sso -f updatedConfigFile

SSO

1. 備份 UI 節點/建立 UI 節點的 VM 快照。
2. 停止並解除安裝單一登入 (SSO)：

   apigee-service apigee-sso stop

   apigee-service apigee-sso uninstall

3. 取得搭載升級版 OS 的新節點。
4. 套用特定作業系統的必要條件。
5. 下載所用 Apigee 版本的啟動程序，執行啟動程序以取得 apigee-service，並安裝 apigee-setup。
6. 按照指南新增 SSO 的設定和金鑰，並考量新節點 IP。
7. 設定及啟動單一登入：

   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile

8. 使用新的 SSO 節點 IP 更新設定，並重新設定 UI 的 SSO：

   apigee-service edge-ui configure-sso -f updatedConfigFile

9. (如果使用新版 UI) 在新版 UI 節點上執行 configure-sso，請參閱說明文件：

   apigee-service edge-management-ui configure-sso -f updatedConfigFile

   apigee-service edge-ui configure-sso -f updatedConfigFile