OpenLDAP 集成

本指南演示如何为 OPL 数据空间配置 OpenLDAP 认证，包括：

用 Docker 启动一个测试用 OpenLDAP
导入示例用户
在 OPL 数据空间中配置 LDAP 登录
排查常见错误

1. 用 Docker 启动 OpenLDAP

最快的测试方式是用 Docker。下面的 docker-compose.yml 会启动一个 OpenLDAP 容器，以及一个可选的 phpLDAPadmin Web 管理界面。

version: "3.9"
services:
  ldap:
    image: osixia/openldap:1.5.0
    container_name: openldap
    environment:
      LDAP_ORGANISATION: "Example Inc"
      LDAP_DOMAIN: "example.org"
      LDAP_ADMIN_PASSWORD: admin
      LDAP_TLS: "false"
    volumes:
      - ./ldap/var:/var/lib/ldap
      - ./ldap/etc:/etc/ldap/slapd.d
    ports:
      - "389:389"
    networks: [ldapnet]

  phpldapadmin:
    image: osixia/phpldapadmin:0.9.0
    environment:
      PHPLDAPADMIN_LDAP_HOSTS: "ldap"
    ports:
      - "6443:443"
    networks: [ldapnet]

networks:
  ldapnet:
    driver: bridge

说明：

osixia/openldap 会根据 LDAP_DOMAIN 和 LDAP_ADMIN_PASSWORD 自动生成基本目录结构
osixia/phpldapadmin 提供图形化管理界面，默认在 https://localhost:6443

启动：

docker-compose up -d

然后查看日志确认 LDAP 已启动：

docker logs openldap

看到 started slapd 一类信息就说明服务正常。

2. 导入示例用户

为了测试登录，需要在 LDAP 目录中加入一个示例用户。创建 seed.ldif：

seed.ldif
dn: ou=users,dc=example,dc=org
objectClass: organizationalUnit
ou: users

dn: uid=jdoe,ou=users,dc=example,dc=org
objectClass: inetOrgPerson
cn: John Doe
sn: Doe
uid: jdoe
mail: jdoe@example.org
userPassword: {PLAIN}password123

密码说明

为了演示方便，这里用了明文密码。生产环境应使用哈希密码，例如用 slappasswd 或 openssl passwd 生成。

导入方式：

docker cp seed.ldif openldap:/seed.ldif
docker exec openldap ldapadd -x -D "cn=admin,dc=example,dc=org" -w admin -f /seed.ldif

如果成功，会看到 adding new entry 一类输出。

3. 验证 LDAP 是否可访问

在配置 OPL 数据空间之前，先用 ldapsearch 验证 LDAP 服务和用户条目都正常：

ldapsearch -x -H ldap://localhost:389 \
  -D "cn=admin,dc=example,dc=org" -w admin \
  -b "dc=example,dc=org" "(uid=jdoe)"

如果能返回 jdoe 的条目，说明 LDAP 侧没问题。

4. 配置 OPL 数据空间

环境变量

为 OPL 数据空间设置以下变量：

信息

这些环境变量通常只在首次启动时读取。若实例已经跑过，后续应通过管理面板修改，除非你设置了 ENABLE_PERSISTENT_CONFIG=false。

ENABLE_LDAP="true"

LDAP_SERVER_LABEL="OpenLDAP"
LDAP_SERVER_HOST="localhost"
LDAP_SERVER_PORT="389"
LDAP_USE_TLS="false"
LDAP_VALIDATE_CERT="false"

LDAP_APP_DN="cn=admin,dc=example,dc=org"
LDAP_APP_PASSWORD="admin"

LDAP_SEARCH_BASE="dc=example,dc=org"
LDAP_ATTRIBUTE_FOR_USERNAME="uid"
LDAP_ATTRIBUTE_FOR_MAIL="mail"

# 可选的额外过滤条件，例如按组限制
# LDAP_SEARCH_FILTER="(memberOf=cn=allowed-users,ou=groups,dc=example,dc=org)"

在 UI 中配置

你也可以直接在管理员界面里配置：

使用管理员账号登录
进入 设置 > 通用
启用 LDAP Authentication
填写对应字段
保存并重启 OPL 数据空间

5. 登录测试

打开一个新的无痕窗口，访问你的 OPL 数据空间：

登录名：jdoe
密码：password123

首次登录成功后， OPL 数据空间会自动创建一个本地用户，默认角色为 User。管理员之后可以再提升权限。

6. 常见错误排查

`port must be an integer`

LDAP authentication error: port must be an integer

原因：

LDAP_SERVER_PORT 被写成了带引号的字符串
LDAP_SERVER_HOST 里错误地包含了 ldap:// 或 http://

修正方式：

用 LDAP_SERVER_PORT=389
LDAP_SERVER_HOST 只写主机名或 IP，例如 localhost

`[SSL: UNEXPECTED_EOF_WHILE_READING]`

这是 TLS 握手失败，通常意味着客户端和 LDAP 服务端在加密方式上不一致。

处理方式：

不打算使用 TLS：LDAP_USE_TLS="false"，连接 389
使用 LDAPS：服务端监听 636，并设置 LDAP_SERVER_PORT="636"、LDAP_USE_TLS="true"
使用 StartTLS：服务端必须支持 StartTLS，仍然连接 389，并把 LDAP_USE_TLS="true"

`err=49` / Invalid Credentials

这表示 LDAP 服务端拒绝了绑定请求，通常是用户名 DN 或密码不对。

排查建议：

确认输入的是正确的明文密码
确认用户 DN 正确，例如 uid=jdoe,ou=users,dc=example,dc=org
直接用 ldapwhoami 验证：

ldapwhoami -x -H ldap://localhost:389 \
  -D "uid=jdoe,ou=users,dc=example,dc=org" -w "password123"

如果这里都失败，问题在 LDAP 端，不在 OPL 数据空间。

如需重置密码，可以用 ldapmodify 或 ldappasswd。初次测试时，先用 {PLAIN} 明文密码通常最省事，之后再切换到更安全的哈希格式。

1. 用 Docker 启动 OpenLDAP​

2. 导入示例用户​

3. 验证 LDAP 是否可访问​

4. 配置 OPL 数据空间​

环境变量​

在 UI 中配置​

5. 登录测试​

6. 常见错误排查​

port must be an integer​

[SSL: UNEXPECTED_EOF_WHILE_READING]​

err=49 / Invalid Credentials​