选ldap3而非go-ldap因v2已归档不维护，v3支持TLS、连接池及RFC 4511，但升级需适配Bind返回值变化、默认禁用TLS验证等差异，且AD连接必须正确配置LDAP_URL、BIND_DN、BIND_PASSWORD、USER_SEARCH_BASE四参数并分步搜索与绑定。
为什么选 ldap3 而不是 go-ldap
Go 生态里没有官方 LDAP 客户端，主流是 go-ldap（原 gopkg.in/ldap.v2）和 ldap（来自 github.com/go-ldap/ldap/v3）。但 go-ldap v2 已归档、不维护，v3 是其延续，支持 TLS、连接池、RFC 4511 兼容性好；而很多老项目还在用已停更的 v2，升级后常报 ldap.LDAPResult 类型不匹配或 Bind 返回值结构变化。别硬套旧教程里的 v2 示例——v3 的 Conn.Bind() 不再返回错误码整数，而是直接 panic 或返回 error，且默认不启用 TLS 验证，生产环境极易出现 LDAP Result Code 49 "Invalid Credentials" 却查不出原因。
连接 AD 必须设对的 4 个参数
只填 LDAP_URL 和 BASE_DN 肯定连不上 Active Directory。AD 默认禁用明文 LDAP（端口 389），且强制要求绑定账号有足够权限搜索用户。这四个字段缺一不可：
-
LDAP_URL：必须带协议，优先用ldaps://dc.corp.example.com:636；若只能走 389，则需额外调用conn.StartTLS()，且证书必须可信 -
BIND_DN：服务账号完整 DN，如CN=svc-gin-auth,OU=ServiceAccounts,DC=corp,DC=example,DC=com，不能是用户名 -
BIND_PASSWORD：从环境变量读，os.Getenv("LDAP_BIND_PW")，绝不可硬编码 -
USER_SEARCH_BASE：用户所在 OU，不是整个BASE_DN，例如OU=Employees,DC=corp,DC=example,DC=com；填错会返回LDAP Result Code 32 "No Such Object"
认证逻辑不能跳过“搜索 + 单独 bind”两步
用服务账号直接 Bind 用户凭据是严重漏洞——等于把服务账号密码暴露给任意登录请求。正确流程必须分两步：
- 先用服务账号连接，执行搜索：
filter := fmt.Sprintf("(&(objectClass=user)(sAMAccountName=%s))", username)，范围限定在USER_SEARCH_BASE - 检查结果唯一性：
if len(entries) != 1→ 拒绝登录（防模糊匹配、重名） - 提取
entries[0].DN，新建一个*ldap.Conn实例（不要复用服务账号连接），仅用于本次验证：err := userConn.Bind(entries[0].DN, password) - 务必设
userConn.SetTimeout(5 * time.Second)，避免阻塞；失败时立即userConn.Close()
Gin 中间件怎么写才不踩坑
别在中间件里全局复用一个 *ldap.Conn——它不是线程安全的，高并发下会 panic。正确做法是每次请求新建连接，或用连接池（ldap.NewPool），但池配置容易出错：
- 连接池最大空闲数设太小（如
MaxIdleConns: 2）→ 并发稍高就卡住，日志里反复出现ldap pool: no idle connection - 没设
IdleTimeout→ 连接长时间闲置后被防火墙断开，下次复用时报read: connection reset by peer - 中间件里别用
c.Abort()后还继续执行后续 handler；建议统一返回gin.H{"code": 401, "msg": "LDAP auth failed"}并显式c.Abort() - 密码字段必须从
c.PostForm("password")或 JSON body 读取后立即清空内存：defer func() { for i := range pwd { pwd[i] = 0 } }()
最易被忽略的是证书校验：AD 域控自签名证书很常见，但 ldap.DialURL 默认校验 CA，必须显式传入 &ldap.DialOptions{TLSConfig: &tls.Config{InsecureSkipVerify: true}} ——仅限内网测试；生产环境应把域控 CA 证书加入系统信任链，而非关闭校验。
