问题说明

本文用于排查 ZSphere 环境中添加 AD/LDAP 服务器时，因 StartTLS、LDAPS、端口、证书域名或管理节点域名解析配置不匹配导致测试连接失败的问题。排查时需要先区分当前使用的是 StartTLS 方式还是 LDAPS 方式，再检查服务器地址、端口、TLS 开关、证书名称和解析结果是否一致。

现象

• 在 ZSphere 管理页面添加 AD/LDAP 服务器并点击测试连接时，页面提示连接失败。
• 页面可能显示以下错误：

  Cannot connect to LDAP/AD server
  LDAP connection has been closed unexpected

• 打开 TLS 后，服务器地址或端口被调整，未再次确认配置，导致测试连接失败。
• 使用 ldaps://IP:636 访问 AD/LDAP 服务器时，如果证书中未包含该 IP 地址，可能因证书主机名不匹配导致连接失败。

适用环境

• 产品：ZSphere
• 版本：4.x、5.x
• 组件：AD/LDAP 认证、用户同步
• 服务器类型：WindowsAD
• 部署形态：ZSphere 环境对接外部 AD/LDAP 服务器
• 连接方式：StartTLS 或 LDAPS

可能原因

该现象可能由以下一种或多种原因导致：

• StartTLS 场景使用了错误的地址和端口组合，例如 ldap://<AD 地址>:636 并开启 TLS。
• LDAPS 场景使用 IP 地址访问 ldaps://<AD 地址>:636，但 AD/LDAP 服务器证书中未包含该 IP 地址作为 SAN。
• AD/LDAP 服务器证书绑定的是域名，但 ZSphere 管理节点无法解析该域名。
• 打开 TLS 后，页面自动调整端口，未根据实际连接方式再次确认服务器地址。
• 基本 DN、用户 DN、登录属性、过滤条件或绑定账号密码填写不正确。

排查步骤

按顺序执行以下检查。每一步都应确认当前状态是否符合预期，或指出下一步处理动作。

1. 确认当前使用的连接方式

• 检查项：确认现场计划使用 StartTLS 还是 LDAPS。
• 命令/UI 路径：在 ZSphere 管理页面进入 AD/LDAP 添加页面，查看服务器地址、端口和 TLS 开关配置。
• 预期结果：连接方式与地址组合一致：

  StartTLS = ldap://<AD 地址>:389 + TLS 开启
  LDAPS    = ldaps://<AD 证书域名>:636 + TLS 开启

• 异常处理：如果地址、端口和 TLS 开关不匹配，按第 2 步或第 3 步修正。

2. 检查 StartTLS 配置

• 检查项：确认 StartTLS 使用普通 LDAP 地址和 389 端口，并在同一连接上升级为 TLS 加密连接。
• 命令/UI 路径：在 ZSphere AD/LDAP 添加页面检查以下配置：

  服务器类型：WindowsAD
  服务器地址：ldap://<AD 地址>:389
  TLS：开启

• 预期结果：服务器地址保持为 ldap://<AD 地址>:389，测试连接成功。
• 异常处理：如果配置为 ldap://<AD 地址>:636 并开启 TLS，应改回：

  ldap://<AD 地址>:389

ldap://<AD 地址>:636 + TLS 开启 会在 LDAPS 端口上发起 StartTLS 请求，AD/LDAP 服务器通常会关闭连接，并可能触发 LDAP connection has been closed unexpected。

3. 检查 LDAPS 配置

• 检查项：确认 LDAPS 从连接建立开始即使用 TLS/SSL 加密连接，并使用证书中的域名访问。
• 命令/UI 路径：在 ZSphere AD/LDAP 添加页面检查以下配置：

  服务器类型：WindowsAD
  服务器地址：ldaps://<AD 证书域名>:636
  TLS：开启

• 预期结果：服务器地址使用 ldaps:// 协议、AD/LDAP 服务器证书中的域名和 636 端口，测试连接成功。
• 异常处理：如果配置为 ldaps://<AD 服务器 IP>:636，且 AD/LDAP 服务器证书未包含该 IP 地址，应改为证书中的域名，例如：

  ldaps://<AD 证书域名>:636

4. 检查管理节点是否能解析 AD/LDAP 证书域名

• 检查项：确认 ZSphere 管理节点可以将 AD/LDAP 服务器证书中的域名解析到正确 IP。
• 命令/UI 路径：登录 ZSphere 管理节点，执行：

  getent hosts <AD 证书域名>

• 预期结果：命令返回 AD/LDAP 服务器 IP。例如：

  <AD 服务器 IP> <AD 证书域名>

• 异常处理：如果没有返回结果，应配置 DNS，或在明确客户允许的情况下临时添加 hosts 解析：

  echo "<AD 服务器 IP> <AD 证书域名>" >> /etc/hosts
  getent hosts <AD 证书域名>

确认解析正常后，再回到 ZSphere 管理页面重新测试连接。

5. 核对 AD/LDAP 基础参数

• 检查项：确认 AD/LDAP 基础参数填写正确。
• 命令/UI 路径：在 ZSphere AD/LDAP 添加页面检查以下字段：

  基本 DN：<基本 DN>
  用户 DN：<绑定用户 DN>
  登录属性：<登录属性>
  过滤条件：<用户过滤条件>

• 预期结果：基本 DN、用户 DN、登录属性、过滤条件与客户 AD/LDAP 环境一致，绑定账号密码正确。
• 异常处理：如果 DN、登录属性、过滤条件或密码不正确，应由客户 AD/LDAP 管理员确认后重新填写。不要将客户密码明文写入交付文档、KB 附件或截图中。

6. 重新测试并收集失败信息

• 检查项：修正配置后重新测试连接，并记录仍然失败时的证据。
• 命令/UI 路径：在 ZSphere AD/LDAP 添加页面点击测试连接。
• 预期结果：测试连接成功，保存 AD/LDAP 服务器配置后可按现场策略同步用户。
• 异常处理：如果仍然失败，应收集以下信息后提交技术支持继续分析：
• ZSphere 版本。
• AD/LDAP 服务器类型和版本。
• 当前服务器地址、端口、TLS 开关状态。
• 基本 DN、用户 DN、登录属性和过滤条件，密码需脱敏。
• 管理节点 getent hosts <AD 证书域名> 的执行结果。
• ZSphere 管理页面错误提示和相关任务时间。
• 管理节点中与 AD/LDAP 测试连接时间对应的日志。

补充信息

• StartTLS 与 LDAPS 的关键区别如下：

• 如果现场普通 LDAP 389 端口可用，且 StartTLS 测试通过，可优先使用：

  ldap://<AD 地址>:389 + TLS 开启

• 如果客户要求必须使用 LDAPS，应先确认 AD/LDAP 服务器证书和管理节点域名解析完整，再使用：

  ldaps://<AD 证书域名>:636 + TLS 开启