LLDAP 与 OneDev 集成指南：Generic LDAP 外部认证源完整配置-育师

后端
认证鉴权

【免费下载链接】lldap

Light LDAP implementation

项目地址：https://gitcode.com/gh_mirrors/ll/lldap

本指南讲解如何将轻量级 LDAP 服务器 LLDAP 配置为 OneDev 的 Generic LDAP 外部认证源，实现用户使用 LLDAP 中的账号名直接登录 OneDev。文章以仓库内 example_configs/onedev.md 为基础，逐项解释每个配置字段的含义、与 LLDAP 内部数据模型的对应关系，并结合源码说明底层实现，帮助你在自建环境中一次配置成功。

前置条件：确认 LLDAP 与 OneDev 均已就绪

开始配置前，需要确认以下前提：

LLDAP 已安装并完成初始化：管理员的 DN 与密码、LDAP 监听端口均已可用。安装方式可参考仓库内 docs/install.md，Docker 部署可参考 lldap_config.docker_template.toml 中给出的默认配置模板。
OneDev 可访问 LLDAP：OneDev 所在的网络环境需要能访问 LLDAP 的 LDAP 端口（默认3890）或 LDAPS 端口（默认6360）。
基础 DN 已确认：LLDAP 默认使用dc=example,dc=com作为 base DN，实际部署中请替换为你自己配置的域名 DN。

OneDev 中的配置步骤

在 OneDev 界面中，依次进入Administration > External Authentication Source > Authenticator，选择Generic LDAP类型，然后按下表填写各项参数。

配置项	填写值
LDAP URL	`ldap://lldap_ip_or_hostname:3890`或`ldaps://lldap_ip_or_hostname:6360`
Authentication Required	开启（On）
Manager DN	`uid=admin,ou=people,dc=example,dc=com`
Manager Password	你的 bind 用户密码
User Search Base	`ou=people,dc=example,dc=com`
User Search Filter	`(&(uid={0})(objectclass=person))`
User Full Name Attribute	`displayName`
Email Attribute	`mail`
User SSH Key Attribute	留空
Group Retrieval	选择 "Search Groups Using Filter"
Group Search Base	`ou=groups,dc=example,dc=com`
Group Search Filter	`(&(uniqueMember={0})(objectclass=groupOfUniqueNames))`
Group Name Attribute	`cn`
Create User As Guest	关闭（Off）
Default Group	选择 "No Default Group"
Timeout	`300`

重要：将表格中所有dc=example,dc=com替换为你实际配置的域名。LLDAP 默认配置文件 lldap_config.docker_template.toml 中的ldap_base_dn默认值即为dc=example,dc=com，你可以扩展为任意数量的dc段，且不要求真实拥有该域名。

完成上述设置后，OneDev 用户即可使用 LLDAP 中创建的用户名直接登录。

逐项解读：配置字段与 LLDAP 内部实现的对应关系

LDAP URL 与端口

LLDAP 默认监听两个端口，见 server/src/configuration.rs 中的默认值定义：

LDAP 明文端口3890（ldap_port默认值），对应ldap://host:3890；
LDAPS 加密端口6360（ldaps_options.port默认值），对应ldaps://host:6360。

LDAPS 不是默认开启的，需要在 lldap_config.docker_template.toml 的[ldaps_options]段中设置：

[ldaps_options] # 是否启用 LDAPS enabled = true # 监听端口 port = 6360 # 证书文件路径 cert_file = "/data/cert.pem" # 私钥文件路径 key_file = "/data/key.pem"

如果 OneDev 与 LLDAP 在同一内网且传输链路可信，直接使用明文3890即可；跨网络环境建议启用 LDAPS。启用 LDAPS 后，OneDev 的 LDAP URL 填写ldaps://lldap_ip_or_hostname:6360。

Manager DN：bind 管理员账户

OneDev 需要用一个有查询权限的账号执行初始 bind。LLDAP 的默认管理员由 lldap_config.docker_template.toml 中的ldap_user_dn和ldap_user_pass决定：

ldap_user_dn = "admin"会创建 LDAP 用户uid=admin,ou=people,dc=example,dc=com（实际为cn=admin，LLDAP 的字段映射对uid/cn均兼容，见下文）；
ldap_user_pass为该用户的密码，同时用于 LDAP bind 与管理界面登录。

从源码看，LLDAP 的 bind 流程位于 crates/ldap/src/password.rs 的do_bind，其会调用域处理器的bind接口验证用户名密码，拒绝匿名 bind（Anonymous bind not allowed）。因此 OneDev 的 "Authentication Required" 必须开启。

用户搜索：Search Base 与 Search Filter

User Search Baseou=people,dc=example,dc=com：LLDAP 将用户统一存放在ou=people子树下，每个用户的 DN 形如uid=<user_id>,ou=people,dc=example,dc=com。该 DN 组装逻辑见 crates/ldap/src/core/user.rs。
User Search Filter(&(uid={0})(objectclass=person))：{0}是 OneDev 注入的登录用户名。LLDAP 在 crates/ldap/src/core/utils.rs 的map_user_field中将uid映射到用户主键UserColumn::UserId，将objectclass映射到用户对象类；同时 crates/ldap/src/core/user.rs 定义了默认用户对象类集合["inetOrgPerson", "posixAccount", "mailAccount", "person"]，其中包含person，因此该过滤器可以命中所有 LLDAP 用户。

用户属性映射：displayName、mail 与 SSH Key

User Full Name Attribute =displayName：map_user_field中cn、displayname、display_name均映射到用户的显示名字段（UserColumn::DisplayName），对应 LLDAP 用户界面中的显示名称。
Email Attribute =mail：mail（以及email）映射到用户邮箱字段UserColumn::Email，对应 LLDAP 用户资料中的邮箱。
User SSH Key Attribute = 留空：LLDAP 未内置 SSH Key 属性，因此留空即可。若 OneDev 强制要求填写，可以忽略（LLDAP 的 LDAP 服务本身不强制返回该属性）。

组检索：Search Groups Using Filter

OneDev 支持从 LDAP 拉取组信息用于权限管理，配置为 "Search Groups Using Filter" 并填写：

Group Search Baseou=groups,dc=example,dc=com：LLDAP 将组统一存放在ou=groups子树，组 DN 形如uid=<group_name>,ou=groups,dc=example,dc=com，组装逻辑见 crates/ldap/src/core/group.rs。
Group Search Filter(&(uniqueMember={0})(objectclass=groupOfUniqueNames))：{0}同样由 OneDev 注入当前用户。LLDAP 在 crates/ldap/src/core/utils.rs 的map_group_field中：
- uniqueMember/member映射到组成员属性，返回值为组成员的完整 DN（uid=<user>,ou=people,base_dn，见 crates/ldap/src/core/group.rs）；
- objectclass映射到组对象类，默认对象类为["groupOfUniqueNames", "groupOfNames"]（crates/ldap/src/core/group.rs），其中包含groupOfUniqueNames，因此过滤器可以命中所有 LLDAP 组。
Group Name Attribute =cn：组名可通过cn、uid、displayName等属性读取，均映射到组显示名（GroupFieldType::DisplayName）。

新用户行为：Create User As Guest 与 Default Group

Create User As Guest = Off：新登录用户将以普通用户身份创建，而非访客（Guest）身份，便于后续在 OneDev 中授予开发权限。
Default Group = No Default Group：不为新用户自动分配任何默认组。如果你希望自动同步 LLDAP 的组到 OneDev，可以保留该默认选项，依赖上面的组过滤配置。

Timeout = 300

OneDev 与 LLDAP 之间的 LDAP 操作超时时间（秒）。若用户量较大或网络延迟较高，可适当调大。

常见问题与排查建议

登录提示 bind 失败：检查 Manager DN 是否写成了cn=admin之外的值。LLDAP 对 DN 的解析基于uid=<id>,ou=people|groups,<base_dn>结构（见 crates/ldap/src/core/utils.rs），同时字段映射对uid与cn均兼容，因此uid=admin,ou=people,dc=example,dc=com可以正常 bind。
搜索无结果：确认dc=example,dc=com是否全部替换为实际 base DN，且用户/组确实创建在ou=people/ou=groups下。
LDAPS 连接失败：确认已在[ldaps_options]中启用enabled = true并正确配置证书与私钥路径；LLDAP 启动日志会打印监听端口（见 server/src/ldap_server.rs）。
用户能登录但组未同步：确认 OneDev 的组过滤配置使用的是 "Search Groups Using Filter" 且过滤条件包含objectclass=groupOfUniqueNames，该对象类是 LLDAP 组的默认对象类之一。

配置完成后，在 OneDev 使用 LLDAP 中任意已创建用户的用户名登录即可验证。更完整的配置项说明可参考 lldap_config.docker_template.toml，仓库内还有大量其他应用的集成示例，位于 example_configs 目录下，例如 example_configs/nextcloud.md、example_configs/gitea.md、example_configs/gitlab.md 等，可用于交叉验证 LLDAP 的 LDAP 行为是否符合预期。