Gogs集成LDAP

核心结论	说明
Gogs 支持本地账号 + LDAP 账号并存	LDAP 只是新增认证源，不会禁用本地管理员账号
绑定 DN 用于查询用户树	不建议使用 LDAP 管理员账号，建议创建只读查询账号
用户过滤规则决定谁能登录	常见条件是 `objectClass=posixAccount` 且 `uid=%s`
Gogs 用户必须有邮箱属性	LDAP 条目中需要有 `mail`，否则用户创建或登录可能失败

1.简介

Gogs 可以通过 LDAP 接入统一账号体系。常见场景：

公司已有 OpenLDAP / AD；
Git 服务希望复用统一账号密码；
保留 Gogs 本地管理员账号，普通用户走 LDAP；
后续给 Jenkins、Drone、Harbor 等系统统一认证打基础。

本文记录 Gogs 集成 LDAP 的核心配置和排查点。

2.说明

2.1 配置入口

使用管理员账号登录 Gogs：

1
管理面板 -> 认证管理源 -> 添加新的源

认证类型选择：

1
LDAP via BindDN

如果 LDAP 服务允许匿名查询，也可以使用匿名方式，但生产环境更建议使用专门的只读绑定账号。

2.2 LDAP 示例结构

假设 LDAP 用户结构如下：

1
2
3
4
dc=example,dc=com
└── ou=People
    ├── uid=zhangsan,ou=People,dc=example,dc=com
    └── uid=lisi,ou=People,dc=example,dc=com

用户条目示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
dn: uid=zhangsan,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: posixAccount
uid: zhangsan
cn: Zhang San
sn: Zhang
mail: zhangsan@example.com
uidNumber: 10001
gidNumber: 10001
homeDirectory: /home/zhangsan

需要注意：Gogs 需要邮箱属性，建议 LDAP 用户条目中维护 mail。

2.3 Gogs 配置项说明

配置项	示例	说明
认证名称	`openldap`	登录页展示和内部识别用，按环境命名即可
安全协议	`Unencrypted` / `LDAPS`	内网测试可明文，生产建议 LDAPS 或 StartTLS
主机地址	`openldap.default.svc.cluster.local`	K8s 内可填 Service DNS，虚拟机可填 IP
主机端口	`389` / `636`	LDAP 默认 389，LDAPS 默认 636
绑定 DN	`cn=readonly,dc=example,dc=com`	用于查询用户的账号 DN
绑定密码	`******`	绑定 DN 的密码
用户搜索基准	`ou=People,dc=example,dc=com`	从哪个 DN 开始搜索用户
用户过滤规则	`(&(objectClass=posixAccount)(uid=%s))`	`%s` 会替换为用户登录名
管理员过滤规则	可选	命中后授予 Gogs 管理权限，谨慎配置
邮箱属性	`mail`	Gogs 用户邮箱来源
名称属性	`cn`	Gogs 用户显示名来源
用户名属性	`uid`	Gogs 用户名来源

常用过滤规则：

1
(&(objectClass=posixAccount)(uid=%s))

如果是 AD，常见写法可能是：

1
(&(objectClass=user)(sAMAccountName=%s))

2.4 配置建议

2.4.1 不建议使用 LDAP 管理员账号绑定

不建议：

1
cn=admin,dc=example,dc=com

建议创建只读账号：

1
cn=readonly,dc=example,dc=com

原因：Gogs 只需要查询用户，不需要修改 LDAP 数据。绑定账号权限越小，泄露后的影响越小。

2.4.2 保留本地管理员账号

Gogs 支持本地认证和 LDAP 认证并存。建议保留一个本地管理员账号，用于：

LDAP 服务故障时登录后台；
过滤规则配置错误时回滚；
首次集成 LDAP 时做兜底。

2.4.3 生产环境使用加密连接

内网测试可以使用 389 明文端口。生产建议：

方案	端口	说明
LDAP	389	明文，不建议跨网络使用
StartTLS	389	先连接 LDAP，再升级 TLS
LDAPS	636	直接 TLS 连接

2.5 命令行验证 LDAP

在配置 Gogs 前，建议先用 ldapsearch 验证。

1
2
3
4
5
6
ldapsearch -x \
  -H ldap://ldap.example.com:389 \
  -D "cn=readonly,dc=example,dc=com" \
  -W \
  -b "ou=People,dc=example,dc=com" \
  "(&(objectClass=posixAccount)(uid=zhangsan))"

重点确认返回结果中包含：

1
2
3
uid: zhangsan
mail: zhangsan@example.com
cn: Zhang San

如果 ldapsearch 查不到，Gogs 一定也查不到。先修 LDAP 查询，再配置 Gogs。

2.6 常见问题

问题	原因	处理
登录提示账号不存在	用户搜索基准或过滤规则错误	用 `ldapsearch` 复现查询
登录后邮箱为空或报错	LDAP 用户缺少 `mail` 属性	补充 `mail` 或修改邮箱属性映射
绑定失败	绑定 DN 或密码错误	确认 DN 完整路径和密码
K8s 中连不上 LDAP	Service DNS、端口、NetworkPolicy 问题	Pod 内执行 `nc -vz ldap 389`
只有部分用户能登录	过滤规则限制过严	检查 `objectClass`、`ou`、`uid`
管理员权限异常	管理员过滤规则误匹配	谨慎配置管理员过滤规则

K8s 内连通性测试：

1
2
kubectl run ldap-test --rm -it --image=busybox:1.36 -- sh
nc -vz openldap.default.svc.cluster.local 389

如果需要 ldapsearch，可以使用带 LDAP 工具的镜像或临时调试容器。

2.7 配置截图

原配置界面如下，仅作参考，实际以当前 Gogs 版本为准。

3.总结

Gogs 集成 LDAP 的关键是绑定 DN、搜索基准、用户过滤规则和邮箱属性；
绑定 DN 建议使用只读账号，不建议使用 LDAP 管理员；
用户过滤规则要先用 ldapsearch 验证，避免在 Gogs 页面反复试错；
LDAP 用户条目建议维护 mail、uid、cn 等属性；
生产环境建议使用 LDAPS 或 StartTLS，并保留本地管理员账号兜底。

目录