Realms Wiki权限管理:本地账号、LDAP、OAuth与反向代理SSO四种认证方式全攻略
Realms Wiki权限管理:本地账号、LDAP、OAuth与反向代理SSO四种认证方式全攻略
Realms Wiki 是一款基于 Git 的 Wiki 系统(灵感来自 Gollum),它的权限管理核心是一套灵活的认证架构:内置本地账号、LDAP 企业目录、OAuth 第三方登录与反向代理 SSO 四种认证方式,可按团队规模自由组合或单独启用。本文将带你快速上手每一种方式的配置要点。
Realms Wiki 采用"插件式模块"设计,认证功能位于 realms/modules/auth/ 目录下,每种方式都是一个独立子模块。启动时系统会读取配置并自动加载对应模块(加载逻辑见 realms/config/init.py):
| 配置项 | 作用 | 默认值 |
|---|---|---|
AUTH_LOCAL_ENABLE |
启用本地账号登录/注册 | True |
LDAP |
提供该配置即启用 LDAP 认证 | 未启用 |
OAUTH |
提供该配置即启用第三方登录 | 未启用 |
AUTH_PROXY |
启用反向代理信任认证 | False |
AUTH_PROXY_HEADER_NAME |
代理传递用户名的请求头名称 | REMOTE_USER |
REGISTRATION_ENABLED |
是否开放用户注册 | True |
💡 所有配置都写在
realms-wiki.json文件中(通过realms-wiki setup命令生成),也可以直接手动编辑该 JSON 文件。
方式一:本地账号认证(默认开箱即用)
本地认证是 Realms Wiki 的默认方式,用户账号和密码存储在后端数据库中,密码使用 bcrypt 强哈希算法加密(加盐强度 12 轮),安全性有保障。
快速上手:创建第一个本地用户
安装完成后,无需任何配置即可通过网页 /register 页面注册登录。若希望管理员先创建账号,可使用命令行工具(源码见 realms/modules/auth/local/commands.py):
# 创建用户(不传密码则自动生成 12 位随机密码并打印)
realms-wiki auth create_user alice alice@example.com
登录逻辑支持用邮箱或用户名登录:系统会判断输入中是否包含 @ 符号来区分两者(见 realms/modules/auth/local/models.py)。登录成功后会话令牌通过 itsdangerous 签名,防止伪造。
常用管理开关
{
"AUTH_LOCAL_ENABLE": true,
"REGISTRATION_ENABLED": false
}
- 将
AUTH_LOCAL_ENABLE设为false可完全关闭本地认证(适合纯 LDAP 或纯代理环境); - 将
REGISTRATION_ENABLED设为false可关闭公开注册,只允许管理员手动建号; - 配置
RECAPTCHA_ENABLE: true后,注册页会自动加入人机验证(逻辑见 realms/modules/auth/local/hooks.py)。
方式二:LDAP 企业目录认证(内部团队首选)
对于已有企业目录(OpenLDAP、Active Directory 等)的团队,Realms Wiki 原生支持 LDAP 认证,核心实现位于 realms/modules/auth/ldap/models.py。它支持两种绑定模式:
1. 直接绑定(Direct Bind)
系统直接把用户名填入 DN 模板,用用户凭据向 LDAP 服务器发起绑定,最简洁:
"LDAP": {
"URI": "ldap://127.0.0.1:389",
"BIND_DN": "uid=%(username)s,ou=People,dc=realms,dc=io",
"KEY_MAP": {
"username": "cn",
"email": "mail"
}
}
2. 搜索后绑定(Bind by Search)
先以服务账号登录目录、搜索用户,找到后再验证密码,适合 DN 规则复杂的目录:
"LDAP": {
"URI": "ldap://127.0.0.1:389",
"BIND_DN": "cn=realms,ou=apps,dc=realms,dc=io",
"BIND_AUTH": "你的服务账号密码",
"USER_SEARCH": {
"base": "ou=users,dc=realms,dc=io",
"filter": "(uid=%(username)s)"
},
"KEY_MAP": {
"username": "cn",
"email": "mail"
}
}
模式判断很简单:配置里有 USER_SEARCH 就走搜索绑定,否则走直接绑定(判断逻辑见 realms/modules/auth/ldap/models.py)。
加密传输:TLS 与 START_TLS
生产环境强烈建议启用加密。使用 ldaps:// 前缀或 "START_TLS": true 开启,并通过 TLS_OPTIONS 指定 CA 证书:
"LDAP": {
"URI": "ldaps://127.0.0.1:686",
"BIND_DN": "uid=%(username)s,ou=People,dc=realms,dc=io",
"TLS_OPTIONS": {
"CA_CERTS_FILE": "/etc/ssl/certs/ldap-ca.pem"
}
}
⚠️ 注意:CA_CERTS_FILE 等证书路径会被启动时校验,文件不存在会直接报错;所有校验规则集中在 realms/modules/auth/ldap/init.py。
方式三:OAuth 第三方登录(适合开源社区)
Realms Wiki 内置 GitHub、Google、Twitter、Facebook 四种 OAuth 提供方,只需在配置中填入申请到的 key 和 secret,登录页就会自动出现对应的 Social Login 按钮(提供方定义见 realms/modules/auth/oauth/models.py):
"OAUTH": {
"github": {
"key": "你的AppKey",
"secret": "你的AppSecret"
},
"google": {
"key": "你的AppKey",
"secret": "你的AppSecret",
"domain": "yourcompany.com"
}
}
实用技巧: Google 登录支持通过 domain 参数限定企业邮箱域名(如 G Suite 域),非该域名的账号会被拒绝(见 realms/modules/auth/oauth/views.py)。配置了 key/secret 的提供方才会显示按钮,其余自动隐藏。
OAuth 用户会话保存在内存中,用户名、邮箱等字段通过各提供方的 field_map 自动映射,无需额外开发。
方式四:反向代理 SSO(Nginx 一行配置搞定)
如果 Wiki 部署在 Nginx 等反向代理之后,且代理已处理鉴权(如 auth_basic、SAML/SSO 网关),可以让 Realms Wiki 完全信任代理传来的用户名,用户无需再看到登录页。
只需两步:
第 1 步,开启代理认证配置:
{
"AUTH_PROXY": true,
"AUTH_PROXY_HEADER_NAME": "REMOTE_USER"
}
第 2 步,在 Nginx 中把认证后的用户名通过请求头传给应用:
location / {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_set_header REMOTE_USER $remote_user;
proxy_set_header Host $http_host;
proxy_pass http://127.0.0.1:5000/;
proxy_redirect off;
}
工作机制:每次请求前,realms/modules/auth/proxy/hooks.py 的钩子会读取 REMOTE_USER 头,存在则自动"无感登录";若头中的用户与当前会话不一致,会先登出旧用户再切换——保证同一时刻只有一个身份生效。
🔒 安全警告:开启
AUTH_PROXY后,必须确保 Realms Wiki 只能经由代理访问(建议只绑定 127.0.0.1 端口)。否则任何人都可以直接伪造REMOTE_USER头冒充任意用户!
四种方式对比:怎么选?
| 认证方式 | 适用场景 | 配置复杂度 | 是否需要数据库 |
|---|---|---|---|
| 本地账号 | 小团队、快速起步 | ⭐ 零配置 | 是 |
| LDAP | 已有企业目录的中型/大型组织 | ⭐⭐⭐ | 否 |
| OAuth | 开源社区、Google/GitHub 用户群 | ⭐⭐ | 否 |
| 反向代理 SSO | 已有统一网关/SSO 体系 | ⭐⭐ | 否 |
四种方式可以共存:登录页(路由定义见 realms/modules/auth/views.py)会按配置自动聚合所有已启用模块的登录表单,用 <hr /> 分隔展示,用户可选择任意入口登录。
权限管理最佳实践清单
- ✅ 生产环境务必修改
SECRET_KEY(默认值是CHANGE_ME),它参与会话签名; - ✅ 关闭不需要的认证入口,缩小攻击面;
- ✅ 需要登录才能访问的 Wiki,设置
PRIVATE_WIKI: true或ALLOW_ANON: false禁止匿名访问(未登录访问会被重定向到登录页,见 realms/modules/auth/init.py); - ✅ LDAP 走
ldaps://或START_TLS加密传输; - ✅ 启用
AUTH_PROXY时严格限制应用只监听内网地址; - ✅ 敏感环境关闭公开注册,配合 reCAPTCHA 防止批量注册。
掌握以上四种认证方式,Realms Wiki 就能从容应对从个人笔记到企业级内部知识平台的各种权限管理需求。