lldap 0.6.3 介绍与选型指南

目标读者：正在为家庭实验室或中小团队选择"统一认证用户源"的架构师与运维工程师。 信息基准：本文全部版本号、社区数据、功能描述均取自官方公开资料（GitHub lldap/lldap 仓库、Releases 与随版本发布的官方文档），查询日期为 2026-10-19。本文为认知与选型文档，不包含本地实测部署过程；部署、配置与运维请见本系列《lldap Docker Compose 部署指南》《lldap 0.6.3 配置参数详解》《lldap 日常运维手册》。

一、环境信息

二、软件概述

lldap 是一个用 Rust 编写的轻量级认证服务器：对上暴露一个标准 LDAP 查询接口和一个自带用户管理 Web UI 的 HTTP 服务，对下把用户、组数据落在 SQL 数据库中（默认 SQLite，可切 MySQL/MariaDB/PostgreSQL）。它的定位一句话概括："轻量 LDAP + Web UI 用户管理"——把传统目录服务里"架一套 slapd、手写 LDIF、再装个 phpLDAPadmin"的三件套，收敛成一个开箱即用的单服务。

官方 FAQ 对其定位有明确表述：lldap 的目标是用简单的方式为自托管应用提供集中认证的用户源，而不是实现完整 LDAP 规范。LDAP 接口侧只支持一个较小的、只读的协议子集（查询/绑定，外加密码重置扩展），所有写操作（建用户、建组、改属性）都收敛到 Web UI 与 GraphQL API 完成。

v0.6.3 版本脉络（官方 Releases，2026-10-19 实查）：

从节奏看，lldap 属于"年更一到两版"的稳态维护型项目：不追求高频发版，重大变化集中在 0.6.x 主线内。

三、核心架构

以下架构描述整理自官方仓库 docs/architecture.md（随 v0.6.3 发布，2026-10-19 核对）。

3.1 进程模型

lldap 是单个二进制文件，同时监听两个端口：

• LDAP 端口（默认 3890）：对外提供 LDAP v3 绑定与查询，供各类支持 LDAP 认证的应用（如《Authelia 4.39 介绍与选型指南》《Authentik 介绍与选型指南》、Nextcloud、Jellyfin 等）接入；
• HTTP 端口（默认 17170）：三合一——/auth 认证 API（JWT）、/api/graphql 用户管理 GraphQL API、以及静态托管的 WASM 管理前端。

官方明确说明：HTTP 端口不支持原生 HTTPS，生产环境需在前面挂一层反向代理做 TLS 卸载；而 LDAPS（LDAP over TLS）原生支持，可通过配置证书启用。

3.2 认证机制：OPAQUE 零知识证明

这是 lldap 最有辨识度的安全设计：Web 登录采用 OPAQUE 协议（RFC 9380）——密码永远不离开客户端，由客户端向服务端证明"我知道密码"（零知识证明）。OPAQUE 服务端记录再以 Argon2 哈希，并用配置中的服务端密钥（key_seed/key_file）加密后落库。官方文档强调：即便数据库整库泄露，攻击者拿到的也只是一段必须逐用户暴力破解才能验证口令的密文 blob，不能像传统 LDAP 那样直接读出或离线比对哈希。

代价是 LDAP 简单绑定仍需客户端传明文密码到服务端（这是 LDAP 协议本身的限制），官方建议将 LDAP 端口限制在内网，仅把 Web 端口暴露出去。

Web 登录流程（官方 architecture.md）：
浏览器 ──OPAQUE 登录──▶ /auth/login
        （密码不出客户端，服务端只做零知识验证）
        ◀── JWT（1 天有效）+ Refresh Token（30 天，HTTP-only Cookie）

LDAP 客户端流程：
应用 ──LDAP Simple Bind──▶ 3890 端口
        （明文密码进服务端校验，建议限内网）

传统 LDAP 服务端存储 SSHA/SHA512-crypt 等口令哈希，数据库泄露后攻击者可离线爆破；LLDAP 存储的是经服务端密钥加密的 OPAQUE 注册 blob，验证必须在线进行且依赖服务端密钥。即使服务端密钥泄露，官方文档指出攻击者仍需"对每个用户独立做一次昂贵的暴力搜索"才能验证口令，无法批量离线比对。代价是：服务端密钥（key_seed）一旦变更，所有已存口令全部失效——这一点在容量规划与密钥管理时必须写进变更流程。

3.3 数据模型与存储

• 目录树结构固定：用户固定挂载在 OU=people，组固定挂载在 OU=groups，由 base_dn 派生（如 dc=example,dc=com 下即 cn=admin,ou=people,dc=example,dc=com）。这是"有主见（opinionated）"的简化设计，换来的是零 schema 配置成本；
• 存储后端可插拔：默认 SQLite（单文件 users.db），官方文档提供向 MySQL/MariaDB/PostgreSQL 迁移的完整手册（docs/database_migration.md）；
• 自定义属性：v0.6.x 起 schema 可在 Web UI 中扩展（用户级与组级），存放如 mail、avatar、自定义业务字段。

四、功能特性

基于官方文档与 v0.6.x 变更日志（2026-10-19 核对）：

v0.6.3 的变更（官方 Release Notes，2026-04-30）要点：

• 移除未使用的依赖；
• Password reset endpoint 现在限定为管理员可访问；
• 修复 ui_config 相关问题；
• 同步 v0.6.2 中 password reset page 的安全修复到文档示例；
• 新增支持在 http_url 中指定自定义端口用于密码重置链接。

五、快速上手

以下安装路径均引自官方文档 docs/install.md（随 v0.6.3 发布），本文不做本地实测；实测部署请参见《lldap Docker Compose 部署指南》与《lldap 0.6.3 配置参数详解》。

5.1 安装方式总览

官方文档给出的安装路径：

1. 各主流发行版软件源：Arch（AUR）、Debian/Ubuntu（openSUSE Build Service 第三方源）、CentOS/Fedora/OpenSUSE（同 OBS 源）、FreeBSD（rc.d）；
2. 官方预编译二进制：GitHub Release 直接下载；
3. 其他形态（Kubernetes、TrueNAS SCALE 等，详见官方 install.md）。

Debian/Ubuntu 软件源路径（官方文档引用）通过 OBS 项目 home:Masgalor:LLDAP 提供，包含 lldap 主包与 lldap-extras、lldap-migration-tool、lldap-set-password 等配套包，安装后配置文件位于 /etc/lldap/lldap_config.toml，随包附带 systemd 单元 lldap.service，默认管理员账号为 admin（官方文档注明默认口令为 password，应立即在 Web UI 修改）。

5.2 官方预编译二进制（最小上手路径）

Release 资产（官方页面 2026-10-19 实查）提供 amd64-lldap.tar.gz、aarch64-lldap.tar.gz、armhf-lldap.tar.gz 三种架构包，解压即得 lldap 主程序与 lldap_set_password、lldap_migration_tool 工具。标准落位方式：

# 1. 下载（v0.6.3 资产 amd64-lldap.tar.gz，官方 sha256 于 2026-10-19 核对）
curl -LO https://github.com/lldap/lldap/releases/download/v0.6.3/amd64-lldap.tar.gz
sha256sum amd64-lldap.tar.gz
# 官方资产实测校验值：e80b50ef39be61de9f1d75182b1e1fa5d82c672261c7e34fd8ffec5455ed3883

# 2. 解压落位（包内含 lldap、lldap_set_password、lldap_migration_tool、app/ 前端资源）
sudo tar xzf amd64-lldap.tar.gz -C /opt
# 3. 准备 /etc/lldap/lldap_config.toml 配置（完整逐项解析见lldap 0.6.3 配置参数详解）
# 4. 启动：lldap run --config-file /etc/lldap/lldap_config.toml（生产建议配 systemd，见lldap 日常运维手册）

5.3 首次登录

服务启动后，浏览器访问 http://<服务器IP>:17170 进入管理界面，使用配置文件中的管理员账号（默认 admin）登录即可开始建用户/建组；下游应用以 LDAP URL ldap://<服务器IP>:3890 与对应 DN 前缀接入。

六、适用场景与限制

6.1 适合的场景

• 自托管应用矩阵的统一用户源：家庭实验室/中小团队的 Jellyfin、Nextcloud、Gitea、《Authelia 4.39 介绍与选型指南》《Authentik 介绍与选型指南》等应用的 LDAP 认证后端；
• 不想维护 slapd 的运维：需要"数据库级备份/恢复"（拷一个 SQLite 文件或 SQL dump 即可）与图形化用户管理的团队；
• 资源受限的节点：官方 AUR 页面对 lldap-bin 的描述即"适合资源受限系统"；本文实测常态内存约 2.3 MiB（详见《lldap 0.6.3 配置参数详解》环境实测）。

6.2 明确的限制（选型前必读）

七、同类选型对比

以下数据全部于 2026-10-19 实查：GitHub 项目页与 Releases 页面（lldap、glauth、keycloak、389ds）、OpenLDAP 官网（openldap.org）。Keycloak 与 lldap 在选型上是"互补/重叠"关系，故单列其"LDAP 能力"维度说明。

7.1 量化对比总表

7.2 选型决策建议

• 选 lldap：自托管应用的统一认证用户源 + 想要图形化管理 + 资源敏感。下游应用（[《Authelia 4.39 介绍与选型指南》](https://www.quzuo.net/document/ao7cgAvGtzVB)[《Authentik 介绍与选型指南》](https://www.quzuo.net/document/Jnno3q1iAxI9)、Nextcloud、Jellyfin 等）只需一个"能查询的 LDAP"，lldap 覆盖度足够；
• 选 OpenLDAP / 389DS：需要完整 LDAP 语义（自定义 schema 演进、syncrepl 复制、复杂 ACL）或既有目录体系对接；
• 选 Keycloak：需要的是 SSO/IAM 能力（OIDC/SAML、社交登录、身份联邦）。它不提供 LDAP 服务端——典型组合是 lldap 做用户源 + Keycloak 通过 User Federation 消费 lldap，两者是互补而非替代；
• 选 glauth：开发/测试/CI 中的轻量 LDAP 模拟或转发代理场景；
• 需要 OIDC 原生输出但想保持轻量：可评估《Authentik 介绍与选型指南》《ZITADEL v4.19.5 介绍与选型指南》（两者均可将 lldap 作为认证后端），对比维度见各自专栏文档。

7.3 数据来源与时效声明

八、参考链接

1. lldap 官方仓库：https://github.com/lldap/lldap
2. lldap v0.6.3 Release：https://github.com/lldap/lldap/releases/tag/v0.6.3
3. 官方安装文档（随源码）：https://github.com/lldap/lldap/blob/main/docs/install.md
4. 官方架构文档（随源码）：https://github.com/lldap/lldap/blob/main/docs/architecture.md
5. 官方 FAQ（含与 OpenLDAP/FreeIPA 对比）：https://github.com/lldap/lldap/blob/main/docs/faq.md
6. OPAQUE 协议（RFC 9380）：https://datatracker.ietf.org/doc/rfc9380/
7. OpenLDAP 官网：https://www.openldap.org/
8. Keycloak 官方仓库：https://github.com/keycloak/keycloak
9. glauth 官方仓库：https://github.com/glauth/glauth
10. 389 Directory Server 官方仓库：https://github.com/389ds/389-ds-base
11. 本系列文档：《lldap Docker Compose 部署指南》《lldap 0.6.3 配置参数详解》《lldap 日常运维手册》