企业官网建设流程全解析

• 后端
• 认证鉴权

本篇指南基于 LLDAP 官方示例 example_configs/gogs.md 整理，面向需要为自建 Gogs 代码托管服务接入轻量 LDAP 目录（LLDAP）做统一登录的运维与开发者。读完本文，你将掌握两条完整可落地的接入路径：通过 Gogs 管理后台的「LDAP (Simple Auth)」向导式配置，以及通过conf/auth.d/*.conf文件进行 Bind DN 方式的高级配置，并理解 LLDAP 默认端口（3890/6360）、目录结构（ou=people、ou=groups）与只读绑定账号权限（lldap_strict_readonly）等关键背景，保证配置一次通过。

LLDAP 侧的准备工作：理解目录结构与默认端口

在动手配置 Gogs 之前，先确认 LLDAP 服务端的三个事实，它们直接决定 Gogs 表单里要填的值。

端口：LLDAP 默认在3890端口提供未加密的 LDAP 服务，在6360端口提供 LDAPS 服务。这两个默认值可以在源码中确认：server/src/configuration.rs 中ldap_port默认3890，server/src/configuration.rs 中 LDAPSport默认6360；同时 server/src/cli.rs 也注明 CLI 参数--ldap-port默认 3890、server/src/cli.rs 中--ldaps-port默认 6360，且都可通过LLDAP_LDAP_PORT、LLDAP_LDAPS_OPTIONS__PORT环境变量覆盖。注意：这是 LLDAP 的刻意选择，与标准 LDAP 的 389/636 不同，务必以你自己的config.toml或 docker compose 端口映射为准，不要想当然填 389 或 636。

目录结构：LLDAP 的用户统一放在ou=people,<base_dn>，组统一放在ou=groups,<base_dn>，这是 README.md 明确说明的布局。默认 base DN 为dc=example,dc=com，因此用户bob的完整 DN 是cn=bob,ou=people,dc=example,dc=com，组family在cn=family,ou=groups,dc=example,dc=com。

权限组：LLDAP 预置三个内置权限组（服务启动时自动创建，见 server/src/main.rs）：lldap_admin（管理组，拥有 Web UI 全部权限）、lldap_password_manager（可改他人密码）、lldap_strict_readonly（严格只读）。权限判定逻辑在 crates/access-control/src/lib.rs：用户按「lldap_admin>lldap_password_manager>lldap_strict_readonly> 普通用户」的顺序匹配取权限。强烈建议为 Gogs 这类下游服务单独创建绑定账号并加入lldap_strict_readonly，而不是把 LLDAP 的admin密码交给 Gogs，以避免把完整管理权限暴露给单一服务。

方式一：Simple Auth（推荐，管理后台图形化配置）

这是最简单、最适合不熟悉 LDAP 的用户的路径，全程在 Gogs 的 Web 管理界面完成。

操作入口：登录 Gogs 管理员账号 → 进入Administration（管理后台）→ 选择Authentication（认证）→ 点击添加认证源。

各字段填写要点：

• 认证类型（Type）：选择LDAP (Simple Auth)。
• 认证源名称（Name）：任意起名，例如lldap，仅用于在 Gogs 后台区分多个认证源。
• 安全协议（Security Protocol）：LLDAP 只兼容两个选项——LDAPS（需要先在 LLDAP 配置中启用 LDAPS，见下文）和Unencrypted（明文）。Gogs 界面里的 StartTLS 等选项与 LLDAP 不兼容，不要选。
• 主机（Host）：LLDAP 服务器的 IP 或 FQDN（如果你配置了 DNS）。
• 端口（Port）：以你的实际配置为准。一般规律是：未加密用3890，LDAPS 用6360——但务必回查你的config.toml或 docker compose 端口映射，因为端口可能被改过或做了映射。
• 用户 DN（User DN）：必须遵循uid=%s,ou=people,<your_base_dn>的格式，%s会被 Gogs 替换为登录用户名。例如 base DN 为dc=example,dc=com时填uid=%s,ou=people,dc=example,dc=com。
• 用户过滤器（User Filter）：推荐(&(objectClass=person)(uid=%s))。注意这里用uid=%s而用户 DN 里也用uid=%s是可行的——DN 用于建立绑定上下文，过滤器用于定位用户条目，二者由 Gogs 分别独立使用。
• 用户名属性（Username Attribute）：uid。
• 名字属性（Given Name）：givenName。
• 姓氏属性（Surname）：sn。
• 邮箱属性（Email）：mail。

其余字段：如果你不熟悉 LDAP，其余字段（如 Bind DN、Bind Password、Admin Filter、组成员过滤等）建议全部留空。留空时 Gogs 会直接用用户自己提供的凭据做绑定验证，行为最接近「Simple Auth」语义。

启用 LDAPS 的前提：LLDAP 侧需在 lldap_config.docker_template.toml 的[ldaps_options]中设置enabled=true并配置cert_file/key_file（对应环境变量LLDAP_LDAPS_OPTIONS__ENABLED、LLDAP_LDAPS_OPTIONS__PORT、LLDAP_LDAPS_OPTIONS__CERT_FILE、LLDAP_LDAPS_OPTIONS__KEY_FILE，见 server/src/cli.rs），否则 Gogs 连接 LDAPS 端口会失败。

方式二：Bind DN（配置文件方式，更精细的权限控制）

当需要把 LDAP 绑定凭据、搜索范围、管理员判断逻辑等全部固化在 Gogs 侧、或想用独立只读账号（而非用户自己的账号）执行搜索时，采用 Bind DN 方式。以下配置改编自 Gogs 官方仓库conf/auth.d/ldap_bind_dn.conf.example，在 Gogs 容器内，该文件应放在conf/auth.d/some_name.conf，例如：

$ cat /srv/git/gogs/conf/auth.d/ldap_bind_dn.conf id = 101 type = ldap_bind_dn name = LDAP BindDN is_activated = true is_default = true [config] host = ldap.example.com port = 6360 # 0 - Unencrypted, 1 - LDAPS, 2 - StartTLS security_protocol = 1 # You either need to install the LDAPS certificate into your trust store - # Or skip verification altogether - for a restricted container deployment a sane default. skip_verify = true bind_dn = uid=<binduser>,ou=people,dc=example,dc=com bind_password = `yourPasswordInBackticks` user_base = dc=example,dc=com attribute_username = uid attribute_name = givenName attribute_surname = sn attribute_mail = mail attributes_in_bind = false # restricts on the `user_base`. filter = (&(objectClass=person)(uid=%s)) # The initial administrator has to enable admin privileges. # This is only possible for users who were logged in once. # This renders the following filter obsolete; Though its response is accepted by Gogs. admin_filter = (memberOf=cn=<yourAdminGroup>,ou=groups,dc=example,dc=com)

逐项说明：

• 顶层字段id、type = ldap_bind_dn、name、is_activated、is_default是 Gogs 认证源注册信息，其中id在 Gogs 内部需唯一。
• host/port：LLDAP 地址与端口，含义同方式一，未加密3890、LDAPS6360。
• security_protocol：取值含义已写在注释里——0未加密、1LDAPS、2StartTLS。LLDAP 仅支持前两者。
• skip_verify = true：跳过 LDAPS 证书校验。若你的 LLDAP 证书未安装进 Gogs 容器的系统信任库，这是受限容器部署下省去证书管理的务实默认；若已把证书装进信任库，可改为false以启用完整校验。
• bind_dn/bind_password：Gogs 用这对凭据先绑定 LLDAP 完成搜索授权。bind_dn指向你为集成创建的专用账号，格式为uid=<binduser>,ou=people,<base_dn>。注意密码用反引号包裹，这是 Gogs 配置文件的约定，避免特殊字符被解析。
• user_base：搜索根，通常就是 base DN，如dc=example,dc=com。
• attribute_username = uid、attribute_name = givenName、attribute_surname = sn、attribute_mail = mail：把 LLDAP 用户的属性映射为 Gogs 的用户名字段。
• attributes_in_bind = false：不把用户属性作为绑定参数参与绑定。
• filter：(&(objectClass=person)(uid=%s))，限定搜索范围为user_base，%s为登录用户名。
• admin_filter：(memberOf=cn=<yourAdminGroup>,ou=groups,dc=example,dc=com)，命中该过滤器的 LLDAP 用户在 Gogs 中成为管理员。注释中的说明值得注意——Gogs 的初始管理员必须先登录一次才能授予管理权限，因此该过滤器的实际作用有限，Gogs 仍会接受它的响应，保留它可以作为后续管理员的判断依据。

两个关键注意点：

1. 绑定账号必须属于lldap_strict_readonly：文中示例的binduser应是 LLDAP 中创建的专用账号，并加入lldap_strict_readonly组。这样 Gogs 只能读取目录做认证，无法通过这个账号修改任何用户数据。这正对应 README.md 的官方建议：大多数 LDAP 集成应使用lldap_strict_readonly或lldap_password_manager组的用户，避免把完整管理权限授予外部服务。
2. <yourAdminGroup>按需替换：尖括号只是便于阅读的占位符，实际填写时要去掉；如果不需要管理员映射，整行admin_filter可以直接省略。

端口与安全协议核对清单

由于「端口写错」是接入失败最常见的原因，这里把核对动作固化成一个清单：

1. 查看 LLDAP 的config.toml（或 Docker 环境变量）：ldap_port/LLDAP_LDAP_PORT决定未加密端口（默认 3890）；[ldaps_options] enabled与port/LLDAP_LDAPS_OPTIONS__PORT决定 LDAPS 端口（默认 6360）。
2. 若 LLDAP 跑在 Docker 里，还要核对 docker compose 的端口映射（例如"3890:3890"的左侧宿主机端口），Gogs 连接的是宿主机暴露出来的端口。官方 Docker 镜像在 Dockerfile 中声明ENV LDAP_PORT=3890。
3. 在 Gogs 侧填写端口后，建议先在 LLDAP 所在主机上用ldapsearch或 Gogs 后台的测试按钮验证连通性，再保存认证源。

版本与兼容性说明

本文档描述的配置方案已在Gogs v0.14+dev上实测通过，测试环境为podman 4.3.1（见 example_configs/gogs.md）。由于 LLDAP 刻意保持轻量、并非完整功能 LDAP 服务器（README.md 也提醒 LDAP 浏览工具类服务通常不受支持），如果你的 Gogs 版本较新或较旧，字段名与conf/auth.d目录约定可能略有差异，建议以你所用 Gogs 版本的官方文档为准，核心的 DN、过滤器与属性映射逻辑不受影响。

• 后端
• 认证鉴权