文档中心知识库安全API Explorer
文档中心›KB›在双管理节点 HA 环境下替换 ZStack Cloud 平台的 HTTPS 证书KB
文档目录

适用场景

  • 产品：ZStack Cloud的双管理节点（MN）HA 部署
  • 版本：ZStack Cloud 版本
  • 组件：管理节点 UI、zsha2、Java keytool、openssl
  • 触发条件：需要将平台的 HTTPS 证书（更换平台 https 证书）替换为客户提供的证书

问题现象

  • 客户需要替换平台的 HTTPS 证书。
  • 默认的浏览器 / API 客户端仍提示原始的自签名证书告警。

判断方法

  1. 确认客户提供的证书为 .pfx / .p12 文件，且其对应的私钥可用。
  2. 确认环境健康，且无其他维护任务在运行。
  3. 确认新的 HTTPS 监听端口（ZStack 管理 UI 启用 SSL 时默认为 5443）从用户网络可达。

原因说明

ZStack 管理节点将其 HTTPS 证书嵌入到 PKCS12 密钥库中，并由 zstack.properties（consoleProxyCertFile）引用。要替换证书，需要先将客户提供的 PFX 重新编码为 ZStack 期望的密钥库格式，再通过 zstack-ctl config_ui 进行注册。必须同时更新两个管理节点，避免 VIP 故障切换到仍持有旧证书的节点。

解决方案

1. 执行前准备

  • 确认环境健康；关闭云主机全局高可用；在两个 MN 上分别备份 ZStack MySQL 数据库；停止管理节点服务。
  • 准备证书文件：9-15.p12（客户提供）及其对应的私钥（例如 xxxx.key）。
  • 确认 Java keytool 可用。例如：
  /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.222.b10-0.el7_6.x86_64/bin/keytool

在目标 MN 上请根据实际 JDK 安装路径调整。

2. 处理步骤

  1. 将证书导入浏览器（可选的健康检查步骤），并重新导出为 P12。
  • 将 .pfx 文件导入浏览器的证书存储，再导出为 .p12。
  1. 从客户的 P12 生成 PEM。
   openssl pkcs12 -in 9-15.p12 -out 9-15.pem -nodes
  1. 确认环境健康；关闭高可用；备份数据库；停止 MN 服务。
  • 在每个 MN 上：备份 MySQL，然后执行 zsha2 stop-node。
  1. 将客户证书和私钥重新打包为新的 PKCS12。
   openssl pkcs12 -export -in 9-15.pem -inkey xxxx.key -out test.p12

按提示设置密码，并记住该密码（后续步骤需要使用）。

  1. 将新的 PKCS12 再转换回 PEM（便于 keytool 处理）。
   openssl pkcs12 -in test.p12 -out test.pem -nodes
  1. 查询新 PKCS12 中的证书别名。
   /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.222.b10-0.el7_6.x86_64/bin/keytool \
     -list -v -keystore /root/Keystore_Tomcat/test.p12
  1. 向管理节点注册新证书。
   zstack-ctl config_ui \
     --enable-ssl True \
     --ssl-keyalias=1 \
     --ssl-keystore=/xxxx/xxx/test.p12 \
     --ssl-keystore-type=PKCS12 \
     --ssl-keystore-password=<第 4 步设置的密码> \
     --server-port=5443

请将 --ssl-keyalias、--ssl-keystore、--ssl-keystore-password 替换为实际值。

  1. 将新的 keystore 和 PEM 拷贝到默认的 ZStack UI 目录。
   cp test.p* /usr/local/zstack/zstack-ui/
  1. 将 consoleProxyCertFile 指向新 PEM 的绝对路径。
  • 编辑 /usr/local/zstack/apache-tomcat/webapps/zstack/WEB-INF/classes/zstack.properties：
     consoleProxyCertFile = /usr/local/zstack/zstack-ui/test.pem
  1. 在第二个管理节点上重复步骤 1–9。
  • 两台 MN 必须都持有新证书，以确保 VIP 故障切换时不会切换到旧证书。
  1. 启动管理节点服务。
    zsha2 start-node
  1. 在主域名和子域名上分别验证控制台访问。
  • 通过主域名登录；打开云主机控制台；再切换到子域名重复验证。

验证方法

  • 浏览器在主域名和子域名上都展示新的 HTTPS 证书（颁发者与客户提供的 CA 一致）。
  • 在两个域名上都可以成功打开云主机控制台。
  • zsha2 status 显示两台 MN 均健康，HA 状态正常。
  • 验证通过后，在 UI 中重新开启全局云主机高可用。

风险与回滚

  • 风险： 错误的 keystore 密码或别名会导致管理 UI 无法启动，直至证书被修复前平台都无法登录。
  • 风险： 若未在两台 MN 上都完成更新，VIP 持有者会持有新证书、备节点仍持有旧证书；在维护窗口内一旦发生 VIP 切换，就会对外暴露旧证书。
  • 回滚： 恢复原来的 .p12 / .pem，使用旧值重新运行 zstack-ctl config_ui；将 zstack.properties 中的 consoleProxyCertFile 恢复到原路径；重启 MN 服务。
上一篇ZStack Cloud 双管理节点 HA 部署断电后管理数据库重新同步下一篇在 ZStack Cloud 双管理节点 HA 部署上变更时间源（NTP）
在双管理节点 HA 环境下替换 ZStack Cloud 平台的 HTTPS 证书 | 技术方案 · KB | ZStack 资源中心