• 后端
• 认证鉴权

本篇指南讲解如何在 OpenCloud（Go 编写的轻量级文件托管 / WebDAV 服务，fork 自 ownCloud Infinite Scale）中停用其内置 LDAP 服务，并将底层目录换成 LLDAP，从而复用 LLDAP 的用户与组体系。读完本文，你将掌握 OpenCloud 全套OC_LDAP_*环境变量的含义与取值，能够独立完成从 LLDAP 侧准备 bind 用户、到 OpenCloud 侧落地配置、再到登录过滤与权限边界验证的完整实战流程。

OpenCloud 与 LLDAP 的集成思路

OpenCloud 是一个用 Go 编写的轻量级文件托管 / WebDAV 服务，它是 ownCloud Infinite Scale（oCIS）的一个分支。与 oCIS 类似，OpenCloud 自带一个 OIDC 身份提供者（IdP）和一个内置 LDAP 服务器，并且官方支持接入第三方 OIDC 提供者。

本示例配置走的是一条更精细的路径：保留 OpenCloud 自身的通用认证 / OIDC 基础设施不动，只把其底层的 LDAP 服务器替换为 LLDAP。这样 OpenCloud 的前端登录、OIDC 流程仍然由它自己负责，而用户、密码、组的存储与查询全部落到 LLDAP 上。由于集成完全通过环境变量完成，无需修改 OpenCloud 镜像或源码，配置既轻量又可复现。

仓库中与本主题直接相关的姊妹篇 OCIS 集成示例 也采用了同样的思路（OCIS_EXCLUDE_RUN_SERVICES: idm+OCIS_LDAP_*变量），OpenCloud 的变量命名与其一脉相承，可作为对照参考。

前置准备：LLDAP 侧的基础设施

在配置 OpenCloud 之前，需要确认 LLDAP 侧已具备以下前提，其中大部分都对应 LLDAP 的默认值：

LLDAP 自身的配置通过 TOML 文件或LLDAP_前缀环境变量完成（见 lldap_config.docker_template.toml，其中ldap_base_dn、ldap_port分别对应LLDAP_LDAP_BASE_DN、LLDAP_LDAP_PORT）。只要 LLDAP 与 OpenCloud 处于同一网络，且ldap_host允许外部连接，OpenCloud 即可通过ldap://<lldap_ip>:3890访问。

创建专用 bind 用户

OpenCloud 需要一个 LDAP bind 用户来执行搜索与绑定。强烈建议不要直接使用 LLDAP 的admin账号，而是创建一个专用服务账号（例如bind_user），并把它加入 LLDAP 的lldap_strict_readonly组。

lldap_strict_readonly是 LLDAP 内建的特殊权限组。从 crates/access-control/src/lib.rs 的权限解析逻辑可以看到，LLDAP 按成员身份确定权限等级：

permission: if is_in_group("lldap_admin".into()) { Permission::Admin } else if is_in_group("lldap_password_manager".into()) { Permission::PasswordManager } else if is_in_group("lldap_strict_readonly".into()) { Permission::Readonly } else { Permission::Regular },

即lldap_admin>lldap_password_manager>lldap_strict_readonly> 普通用户。处于lldap_strict_readonly组的 bind 用户可以执行目录查询，但不能修改他人密码、不能执行管理操作，适合作为对外暴露凭据的服务账号。这正是后面OC_LDAP_SERVER_WRITE_ENABLED取值判断的关键：如果 bind 用户属于lldap_strict_readonly，则 OpenCloud 侧必须声明只读。

配置注入方式：环境变量

OpenCloud 的所有 LDAP 集成项均通过环境变量配置，本示例采用的是 dotenv 风格的键值对：

• 在 FreeBSD 上，这些变量由/usr/local/etc/opencloud/config.env提供；
• 在 Linux 上，可以在 Docker / Docker Compose 的environment:段中直接注入。

仓库的 OpenCloud 示例配置 即以此形式给出，下面的讲解将以它为骨架逐项展开。

环境变量逐项详解

连接与传输安全

# Replace with actual IP and Port OC_LDAP_URI=ldap://<lldap_ip>:3890 # Remove the following if you use LDAPS and your cert is not self-signed OC_LDAP_INSECURE="true"

• OC_LDAP_URI：LDAP 服务器地址。默认明文 LDAP 走3890端口，正好对应 LLDAP 的默认监听端口 server/src/configuration.rs。若 LLDAP 配置了 LDAPS（[ldaps_options]，默认端口6360，见 lldap_config.docker_template.toml），则写成ldaps://...。
• OC_LDAP_INSECURE：是否跳过对 LDAP 服务器证书的校验。当使用明文 LDAP、或使用自签名证书的 LDAPS 时设为"true"；若你的 LDAPS 证书由受信任 CA 签发，可移除该项。

bind 身份

# Replace with your bind-user; can be in OC_LDAP_BIND_DN="cn=<bind_user>,ou=people,dc=example,dc=com" OC_LDAP_BIND_PASSWORD="<secret>"

• OC_LDAP_BIND_DN：bind 用户的完整 DN。LLDAP 的目录中用户一律挂在ou=people之下，命名属性为cn，因此形如cn=bind_user,ou=people,dc=example,dc=com。这与 LLDAP 默认 admin 用户的 DN 结构（cn=admin,ou=people,dc=example,dc=com）完全一致。
• OC_LDAP_BIND_PASSWORD：bind 用户的密码。

目录范围与 ID 属性

OC_LDAP_GROUP_BASE_DN="ou=groups,dc=example,dc=com" OC_LDAP_GROUP_SCHEMA_ID=entryuuid OC_LDAP_USER_BASE_DN="ou=people,dc=example,dc=com" OC_LDAP_USER_SCHEMA_ID=entryuuid

• OC_LDAP_USER_BASE_DN/OC_LDAP_GROUP_BASE_DN：搜索用户与组的子树根 DN，分别对应 LLDAP 的ou=people与ou=groups目录。
• OC_LDAP_USER_SCHEMA_ID/OC_LDAP_GROUP_SCHEMA_ID：OpenCloud 用来充当对象唯一 ID 的 LDAP 属性，统一取entryuuid。LLDAP 为每个用户、组都生成 UUID 作为主键（内部以uuid属性承载），并以entryUUID作为符合 RFC 标准的对外属性名对外暴露。该做法在姊妹篇 OCIS 集成示例 中同样出现（OCIS_LDAP_USER_SCHEMA_ID: "entryuuid"），说明这是两代产品的通用约定：用稳定不变的 UUID 作为身份锚点，避免把会变的uid/cn当作主键。

登录范围过滤（可选）

# Only allow users from specific group to login; remove this if everyone's allowed OC_LDAP_USER_FILTER='(&(objectClass=person)(memberOf=cn=<opencloud_users>,ou=groups,dc=example,dc=com))'

• OC_LDAP_USER_FILTER：限定哪些用户可以登录 OpenCloud。上面的过滤器要求用户同时满足两个条件：具有objectClass=person，且其memberOf属性包含cn=<opencloud_users>,ou=groups,dc=example,dc=com这个组。
• LLDAP 在服务 LDAP 查询时会根据目录结构生成memberOf关系，因此这一过滤器可以直接复用 LLDAP 中已建好的组（例如在 LLDAP 里创建一个名为opencloud_users的组并加入成员）。若不做任何限制，删除该行即可让所有 LLDAP 用户登录。
• 注意值中的引号：整行使用单引号包裹，内部使用双引号，这是 dotenv / shell 环境中保证 LDAP 过滤器字符串正确传递的标准写法。

用户禁用机制（未测试项）

# Other options have not been tested OC_LDAP_DISABLE_USER_MECHANISM="none"

OC_LDAP_DISABLE_USER_MECHANISM控制 OpenCloud 如何识别"已禁用"用户。示例中取"none"，即不启用禁用机制。原文档明确标注"Other options have not been tested"，因此除"none"之外的其他取值（例如基于组的禁用机制）在 LLDAP 场景下没有经过验证，按原样保留即可，不要贸然改动。

写权限开关

# If you bind-user is in lldap_strict_readonly set to false (this hides "forgot password"-buttons) OC_LDAP_SERVER_WRITE_ENABLED="false" # If your bind-user can change passwords: OC_LDAP_SERVER_WRITE_ENABLED="true" # Not tested, yet!

OC_LDAP_SERVER_WRITE_ENABLED决定 OpenCloud 是否认为自己可以对 LDAP 目录执行写操作（例如改密码、改属性）。两个取值需要结合 LLDAP 的权限模型来选择：

• "false"（推荐，且经过验证）：当 bind 用户属于lldap_strict_readonly组时，它在 LLDAP 侧只有只读权限（crates/access-control/src/lib.rs），因此 OpenCloud 必须以只读模式接入。原文档特别指出：设置为false时，OpenCloud 界面会隐藏"忘记密码"（forgot password）按钮——这是避免用户走一个注定失败的密码重置流程的合理行为。
• "true"（未测试）：仅当你的 bind 用户具备改密能力（例如属于lldap_password_manager组）时才应考虑。原文档明确标注Not tested, yet!，即该组合在 LLDAP + OpenCloud 场景下尚未得到验证，生产环境慎用。

停用内置 LDAP

# Don't start built-in LDAP, because it's replaced by LLDAP OC_EXCLUDE_RUN_SERVICES="idm"

OC_EXCLUDE_RUN_SERVICES="idm"是本次替换的核心开关：它让 OpenCloud 不再启动自己内置的 LDAP / 身份管理服务（idm），从而彻底把目录职责移交给 LLDAP。对照 OCIS 集成示例 中的OCIS_EXCLUDE_RUN_SERVICES: idm，可见这是该技术路线的标准动作。

完整配置示例

将以上全部变量整合后，即得到开箱即用的完整配置（来自 example_configs/opencloud.md）：

# Replace with actual IP and Port OC_LDAP_URI=ldap://<lldap_ip>:3890 # Remove the following if you use LDAPS and your cert is not self-signed OC_LDAP_INSECURE="true" # Replace with your bind-user; can be in OC_LDAP_BIND_DN="cn=<bind_user>,ou=people,dc=example,dc=com" OC_LDAP_BIND_PASSWORD="<secret>" OC_LDAP_GROUP_BASE_DN="ou=groups,dc=example,dc=com" OC_LDAP_GROUP_SCHEMA_ID=entryuuid OC_LDAP_USER_BASE_DN="ou=people,dc=example,dc=com" OC_LDAP_USER_SCHEMA_ID=entryuuid # Only allow users from specific group to login; remove this if everyone's allowed OC_LDAP_USER_FILTER='(&(objectClass=person)(memberOf=cn=<opencloud_users>,ou=groups,dc=example,dc=com))' # Other options have not been tested OC_LDAP_DISABLE_USER_MECHANISM="none" # If you bind-user is in lldap_strict_readonly set to false (this hides "forgot password"-buttons) OC_LDAP_SERVER_WRITE_ENABLED="false" # If your bind-user can change passwords: OC_LDAP_SERVER_WRITE_ENABLED="true" # Not tested, yet! # Don't start built-in LDAP, because it's replaced by LLDAP OC_EXCLUDE_RUN_SERVICES="idm"

部署时替换五个占位符即可：<lldap_ip>（LLDAP 容器或主机的 IP）、<bind_user>（bind 用户名）、<secret>（bind 密码）、<opencloud_users>（限定登录的组名）。在 Docker Compose 中把这些键值放入服务的environment:段，或写入 FreeBSD 的/usr/local/etc/opencloud/config.env后重启 OpenCloud。

权限边界与已知限制

• OpenCloud 目前没有（文档化的）方式给 LDAP 用户或组授予管理员权限。这意味着即使 LLDAP 侧将该用户放入lldap_admin组，OpenCloud 也无法据此识别其管理员身份，管理员权限仍需通过 OpenCloud 自己的机制授予。这是接入前需要明确的预期管理。
• OC_LDAP_SERVER_WRITE_ENABLED="true"与OC_LDAP_DISABLE_USER_MECHANISM的非"none"取值均未测试，不要在生产环境未经验证地启用。
• bind 用户建议锁定在lldap_strict_readonly组，配合OC_LDAP_SERVER_WRITE_ENABLED="false"形成最小权限闭环；同时它能隐藏 OpenCloud 界面上无意义的"忘记密码"入口。该组由 LLDAP 在首次启动时自动创建（见 server/src/main.rs 中对lldap_strict_readonly的引导逻辑），无需手工建组。

验证与排障思路

配置完成后，可按以下顺序验证整条链路是否打通：

1. 验证 LLDAP 侧目录可达：从 OpenCloud 所在主机确认ldap://<lldap_ip>:3890端口可达，且OC_LDAP_BIND_DN对应的用户能正常绑定。
2. 检查 OpenCloud 日志：若启动后用户列表为空或登录失败，重点核对OC_LDAP_USER_BASE_DN/OC_LDAP_GROUP_BASE_DN是否与 LLDAP 的ldap_base_dn（默认dc=example,dc=com）一致，以及OC_LDAP_USER_FILTER中的组名是否真实存在于 LLDAP。
3. 验证登录过滤：分别用过滤组内、组外的用户尝试登录，确认memberOf过滤按预期生效。
4. 确认内置 LDAP 已停用：OC_EXCLUDE_RUN_SERVICES="idm"生效后，OpenCloud 不应再监听自己的 LDAP 端口，所有目录请求应落到 LLDAP 上。
5. 如需更细的调试信息，可参考 OCIS 集成示例 中的同族变量（OCIS_LDAP_*、GRAPH_LDAP_SERVER_WRITE_ENABLED等）作为对照，两者在 schema、过滤、写权限的处理语义上高度一致。

关联仓库资源

• OpenCloud 集成示例（本文配置源文件）
• OCIS（ownCloud Infinite Scale）集成示例
• LLDAP 配置模板（环境变量说明）
• 权限组解析逻辑
• LLDAP 服务器配置默认值
• 示例配置索引（含各客户端接入文档）

• 后端
• 认证鉴权