文档中心知识库安全API Explorer
文档中心›KB›ZCenter 启用 HTTPS 后页面或 API 无法访问，如何排查？KB
文档目录

问题说明

本文用于排查启用HTTPS或上传SSL证书后，ZCenter页面无法打开、API返回502/503、浏览器证书报错或实际证书未更新的问题。ZCenter保存sslSetting后通过RabbitMQ异步通知Base更新Caddy，配置保存成功不代表Caddy已经加载成功。

现象

  • 启用HTTPS后浏览器无法连接、TLS握手失败或返回错误证书。
  • 上传证书接口成功，但访问时仍展示旧证书或内置证书。
  • HTTP入口正常，HTTPS入口异常；或配置显示已启用但Caddy仍监听HTTP模式。
  • Base或Caddy日志出现证书加载、Caddy管理API、MQ消息消费或端口监听错误。

适用环境

  • 产品：ZCenter
  • 版本：5.1.0
  • 组件：Portal全局设置、Base、RabbitMQ、Caddy和SSL证书

可能原因

  • sslSetting已写入数据库，但RabbitMQ刷新事件未成功发送或消费。
  • Base无法访问Caddy管理接口127.0.0.1:2019。
  • 证书与私钥不匹配、PEM格式错误、私钥加密、证书链不完整或文件权限不足。
  • Caddy动态监听端口8300/8301与外部负载均衡或端口映射不一致。
  • 证书SAN与实际访问域名不匹配，或内置证书使用了非预期的主机IP。
  • Caddy配置只部分更新，数据库状态和实际运行配置不一致。

排查步骤

1. 保留HTTP恢复通道并确认基础入口

curl -v --max-time 10 http://127.0.0.1:8100/
curl -v --max-time 10 http://127.0.0.1:8100/api/portal/v4/pub/login
  • 预期结果：8100基础入口仍可访问。
  • 异常处理：8100也不可达时先排查Caddy/Gateway基础服务和端口，不要继续修改证书。

2. 检查监听端口和Caddy管理接口

ss -lntp | grep -E ':(8100|8200|8300|8301|2019)\b'
curl -sS http://127.0.0.1:2019/config/apps/http/servers/srv3
curl -sS http://127.0.0.1:2019/config/apps/tls
  • 预期结果：HTTPS启用时动态服务监听8301；HTTP模式监听8300；Caddy管理接口仅本机可访问。
  • 异常处理：2019不可达时检查Caddy进程和管理接口；动态状态与数据库不一致时检查Base刷新事件。

3. 检查全局设置和刷新事件

  • 查询GLOBAL_SETTINGS/sslSetting的当前值，并搜索Base日志中的REFRESH_SSL_CONFIG、[***error***]和Caddy更新失败。
  • 同时检查RabbitMQ的inner_base队列和消费者。
  • 判断：保存接口成功但没有刷新事件消费记录，优先处理RabbitMQ或Base监听器。

4. 校验证书、私钥和证书链

openssl x509 -in /var/lib/caddy/tls/tls.crt -noout -subject -issuer -serial -dates -fingerprint -sha256
openssl pkey -in /var/lib/caddy/tls/tls.key -noout -check
openssl x509 -in /var/lib/caddy/tls/tls.crt -pubkey -noout | openssl pkey -pubin -outform DER | openssl sha256
openssl pkey -in /var/lib/caddy/tls/tls.key -pubout -outform DER | openssl sha256
  • 预期结果：证书有效，私钥可读取，两次公钥摘要一致，证书链和SAN满足访问域名要求。
  • 异常处理：重新准备正确PEM证书和未加密私钥，修正文件权限；不要仅凭上传接口成功判断证书有效。

5. 检查实际对外证书

openssl s_client -connect <host>:<public-port> -servername <certificate-dns-name> -showcerts </dev/null
  • 预期结果：返回目标证书和完整链，域名与SAN匹配。
  • 异常处理：检查负载均衡、VIP、SNI和端口映射，确认请求确实到达目标Caddy实例。

处理方式

  1. 证书问题时，修正证书、私钥、链和文件权限后重新上传并触发SSL配置刷新。
  2. RabbitMQ或Base未消费刷新事件时，先恢复消息链路，再重新保存sslSetting触发更新。
  3. Caddy管理接口不可用时，按部署规范恢复Caddy；不要直接只修改数据库配置。
  4. 需要快速恢复时，通过仍可用的HTTP入口将sslSetting恢复为{"enable":false}，并验证Caddy切回HTTP模板。
  5. 修正外部负载均衡/VIP到8300或8301的实际映射，具体公网端口以现场部署为准。

验证方法

  • 配置验证：数据库中的sslSetting与预期一致。
  • Caddy验证：管理API中的动态服务和TLS对象已更新，监听端口符合模式。
  • 证书验证：openssl s_client返回预期证书、链和SNI结果。
  • 业务验证：页面、静态资源和至少一个API请求均可通过目标HTTPS地址访问。
  • 日志验证：Base和Caddy不再出现证书加载、管理API或TLS握手错误。

风险与回滚

  • SSL开关为全局配置，变更可能影响所有用户和API客户端。
  • 直接修改数据库不会触发Caddy刷新，可能造成配置长期不一致。
  • 删除证书文件可能形成单文件残留状态，不应作为首选回滚方式。
  • 操作前保存原sslSetting、证书指纹和Caddy状态；失败时从HTTP通道恢复原设置和证书。

补充信息

上一篇Gateway返回503且提示无可用服务实例，如何排查？下一篇ZCenter 监控报表无数据或页面空白，如何排查？
ZCenter 启用 HTTPS 后页面或 API 无法访问，如何排查？ | 故障排查 · KB | ZStack 资源中心