LDAP 多域控认证（部署版）¶
部署版支持为同一 LDAP 身份目录配置多个域控地址。登录时按配置顺序连接；在提交用户密码之前遇到允许切换的服务故障时，尝试下一个地址。
本文的“多域控”指共享账号、目录结构和认证规则的多个控制器，例如同一 AD 域的副本。它不提供多个独立 AD 域之间的账号路由，也不通过逐域尝试密码查找用户。独立身份源需要自定义认证时，请参阅 LDAP 自定义认证与 Func 属性加工。
升级与兼容性¶
使用前，请确认部署的 Studio 后端版本包含 LDAPClientSet.authMode 和 LDAPClientSet.server.hosts 配置能力。仅更新帮助文档或 Func 脚本不会为旧版后端增加功能。
现有单地址部署无需修改配置：authMode 缺省或为 builtin，且 server.hosts 未配置、为 null 或 [] 时，仍使用原单地址认证链路。新增的认证总超时和外部函数配置不会改变该链路。不要为单纯升级添加一个只有原地址的 hosts 列表；非空列表意味着主动启用新链路。
开启前请确认：
- 所有候选域控使用相同的
baseDN、服务账号、用户搜索条件、TLS 配置和mapping；同一用户在各副本上的exterId一致。 - 候选域控均可从 Studio 后端容器访问，CA 文件已挂载到容器，证书包含所连接的域名。
- 目录允许使用搜索结果中的用户 DN 进行 SIMPLE 密码验证，并通过 LDAPS 或 StartTLS 保护密码传输。服务账号的绑定方式与最终用户密码验证是两个步骤。
- 使用支持该能力的官方服务启动方式；新链路要求可中断的网络和 DNS 运行环境。自定义启动方式出现
gevent_runtime或gevent_dns配置错误时，应修正启动环境。
配置多个域控¶
按 应用配置说明，在 Launcher 的 forethought-core 命名空间修改 Core 配置。以下为 LDAPS 示例，请将域名、DN、证书路径和占位密码替换为实际配置；保留现有用户的身份映射。
LDAPClientSet:
enable: true
authMode: builtin
authTimeoutSeconds: 20
server:
# 非空 hosts 完全替代 host；失败后不会回退到 host。
hosts:
- "ldaps://ldap-a.example.com:636"
- "ldaps://ldap-b.example.com:636"
connect_timeout: 6
use_ssl: true
get_info: SCHEMA
tls:
validate: CERT_REQUIRED
ca_certs_file: "/config/ldap/ca.pem"
connection:
authentication: SIMPLE
client_strategy: SAFE_SYNC
receive_timeout: 5
startTls: false
baseDN: "dc=example,dc=com"
bindDN: "cn=studio-reader,ou=service,dc=example,dc=com"
bindPassword: "<服务账号密码>"
searchAttribute: "uid"
personObjectClass: "inetOrgPerson"
mapping:
exterId: uid
username: uid
email: mail
mobile: mobile
AD 环境通常需要按实际目录调整 searchAttribute（例如 sAMAccountName）和 personObjectClass（例如 person）。不要直接套用示例覆盖原有的 mapping.exterId。
如使用 StartTLS，将候选地址改为 ldap://域名:389，设置 server.use_ssl: false、startTls: true，保留证书校验。新链路先完成 TLS 握手再绑定服务账号；不要同时启用 LDAPS 与 StartTLS。
| 配置项 | 说明 |
|---|---|
server.hosts |
最多 8 个地址，按填写顺序尝试，相同字符串去重。支持域名、ldap://域名:端口、ldaps://域名:端口，不包含账号密码、路径、查询参数或片段。需要指定端口时直接写在地址中。 |
server.host |
仅在 hosts 为空时作为单地址使用。非空 hosts 不会与它拼接。 |
authTimeoutSeconds |
新链路的认证及属性准备总时限，整数 1～60 秒，默认 20 秒；所有候选地址共用，不是每个地址各有 20 秒。不包含后续账号事务和登录授权码处理。 |
server.connect_timeout |
单次连接超时，默认 6 秒，受剩余总时限限制。 |
connection.receive_timeout |
接收超时，默认 5 秒，受剩余总时限限制。 |
connection.client_strategy |
新链路仅支持 SAFE_SYNC，未配置时使用该值。不要配置 lazy: true；建议不设置 auto_bind，由认证流程控制连接、TLS 和绑定顺序。 |
| 其他 LDAP 配置 | 继续共用原有 server.tls、connection、startTls、baseDN、bindDN、bindPassword、搜索条件与 mapping，不需要为每个控制器复制配置。 |
通过环境变量配置列表时，使用 JSON 数组字符串，例如：
STUDIO__LDAPClientSet__server__hosts='["ldaps://ldap-a.example.com:636","ldaps://ldap-b.example.com:636"]'
修改配置后，勾选 Launcher 的修改配置后自动重启相关服务并确认，确保所有承载登录请求的副本使用同一份配置。
哪些故障会切换域控¶
每次认证从列表第一个地址开始。切换用于处理服务不可用，不用于绕过认证拒绝。
| 情况 | 是否继续下一个地址 |
|---|---|
| 提交用户密码之前发生 DNS、连接、网络通信故障 | 是，但证书校验失败除外，且必须仍有总时限 |
| 服务账号绑定或搜索阶段返回 LDAP busy/unavailable（51/52） | 是，且必须仍有总时限 |
| 服务账号密码错误、权限不足、搜索配置或 schema 错误 | 否，先修正配置 |
| CA 不受信任、证书与域名不匹配 | 否，先修正证书或地址 |
| 未找到用户，或搜索到多个用户 | 否，检查账号同步与唯一搜索条件 |
| 用户密码错误 | 否，不向其他控制器重复提交密码 |
| 用户密码已提交，此后超时、断连或服务不可用 | 否，结果可能不确定，不自动重放密码 |
| 总时限耗尽 | 否，本次认证失败 |
因此，某个域控缺少用户时，不会继续去其他独立目录“找同名账号”。请先确保副本同步与身份一致性。
登录与验收¶
用户仍在部署版登录页选择 LDAP 登录，输入原有用户名和密码，无需选择域控。工作空间权限继续使用现有 SSO 映射规则。
建议先使用专用测试账号验证，再开放给现有用户：
- 所有地址健康时登录成功，原有用户仍进入原账号，工作空间和角色符合预期。
- 在受控测试中模拟首地址连接不可达，确认第二地址可登录，整体耗时受总时限约束。
- 输入错误密码，确认不会因尝试多个控制器增加密码重试次数；检查目录侧锁号策略。
- 验证证书错误、服务账号错误、查不到用户均失败，不通过切换绕过错误。
- 使用两个控制器分别核对同一用户的身份字段与授权所需组属性，确认一致。
mapping.exterId 对应 LDAP 用户的稳定身份。改变映射字段或字段值可能创建新账号；不要依靠相同邮箱或用户名自动合并身份。
回退¶
保留升级前配置。需要恢复旧单地址认证时，将 authMode 设为 builtin，清空或删除 server.hosts，恢复原 server.host 及原有连接、TLS 和映射配置，然后重启相关服务。只修改 host 而保留非空 hosts 不会生效。
回退配置不会自动合并已经创建的账号，也不会恢复已变更的角色映射。若同时更改了属性加工或身份映射，应先核对账号及授权影响。