LeafWiki反向代理认证详解:HTTP Header对接外部SSO,5个关键参数讲透
LeafWiki反向代理认证详解:HTTP Header对接外部SSO,5个关键参数讲透
LeafWiki 是一款自托管 Wiki(单个 Go 二进制 + SQLite + 磁盘上的 Markdown),它内置的反向代理认证(Reverse-Proxy Authentication)能力,让你可以不用内置登录表单,直接对接 nginx + OAuth2 Proxy、Keycloak、Dex 等外部 SSO 单点登录:反向代理把已通过认证的用户名通过 HTTP Header 转发给 LeafWiki,LeafWiki 只认"可信代理 IP"发来的这个头,完成免密登录。本文用 5 个关键参数把整套机制讲透 🛡️
工作原理:Header 从哪来、在哪一步生效?
传统登录流程是"用户输密码 → LeafWiki 校验 → 发 JWT Cookie"。反向代理认证则把"认证"这一环外包给上游(nginx、oauth2-proxy 等),LeafWiki 只负责"验明正身":
用户 → SSO 登录 → nginx/oauth2-proxy(认证成功后)
→ 带上 Remote-User: 用户名 的 HTTP 请求 → LeafWiki
→ LeafWiki 检查来源 IP 是否在可信代理白名单
→ 是:按 Header 中的用户名/邮箱匹配用户 → 直接放行
→ 否:忽略 Header,走正常登录流程
核心逻辑在 reverse_proxy.go 中,不同场景的行为可以记成下面这张"决策表":
| 场景 | LeafWiki 的行为 |
|---|---|
| 功能未启用,或请求来自非可信 IP | 忽略 Header,走正常认证(公开接口照常可访问) |
| 可信 IP,但 Header 未携带用户名 | 不干预,公开页面正常浏览,受保护路由仍要求登录 |
| 可信 IP,Header 有效且用户存在 | 直接以该用户身份进入,无需登录 |
| 可信 IP,用户不存在,未开自动创建 | 返回 401 |
| 可信 IP,用户不存在,已开自动创建 | 自动开户(按默认角色)并放行 |
这个设计的精髓是:Header 本身没有任何可信度,LeafWiki 信任的其实是"发这个请求的 IP"。可信代理 IP 的解析逻辑见 trusted_proxies.go,支持单个 IP 和 CIDR 网段(如 172.18.0.0/16),这正是 Docker 网络下必须配置的原因。
5 个关键参数逐个讲透
以下参数自 v0.10.0 起可用(自动创建相关为 v0.12.1+),定义集中在 flags_proxy.go:
1️⃣ --enable-http-remote-user:认证总开关
| 项 | 值 |
|---|---|
| 环境变量 | LEAFWIKI_ENABLE_HTTP_REMOTE_USER |
| 默认值 | false |
一切的前提。开启后,来自可信代理 IP 的请求才会被读取身份 Header。注意:开启此功能前必须先配好 --trusted-proxy-ips,否则任何来源的 Header 都可能被处理,等于把身份认证的门彻底敞开。
2️⃣ --http-remote-user-header-name:身份来自哪个 Header
| 项 | 值 |
|---|---|
| 环境变量 | LEAFWIKI_HTTP_REMOTE_USER_HEADER_NAME |
| 默认值 | Remote-User |
指定承载"用户名或邮箱"的 HTTP 头名称。oauth2-proxy 体系常用 X-Forwarded-User,Dex + oauth2-proxy 组合里也常见 Remote-User。这个值既可以是用户名也可以是邮箱,LeafWiki 会按"标识符"去匹配已有账号——所以改这个参数时,要和代理侧实际注入的 Header 名保持一致,这是新手最常踩的坑之一。
3️⃣ --trusted-proxy-ips:安全底线——只信"自己人"
| 项 | 值 |
|---|---|
| 环境变量 | LEAFWIKI_TRUSTED_PROXY_IPS |
| 默认值 | 空(即不信任任何代理) |
逗号分隔的 IP / CIDR 列表,例如 127.0.0.1,172.18.0.0/16。LeafWiki 只对来自这些地址的请求解析身份 Header,其他来源一律忽略。
- 裸机部署、nginx 与 LeafWiki 同机:
127.0.0.1就够 - Docker 部署:代理容器通常位于
172.17.0.0/16或自定义 bridge 网段,用 CIDR 覆盖 - 多层代理(如 CDN → 网关 → LeafWiki):只把最后一跳代理的地址写进来
4️⃣ --enable-http-remote-user-auto-create:新用户自动开户(v0.12.1+)
| 项 | 值 |
|---|---|
| 环境变量 | LEAFWIKI_ENABLE_HTTP_REMOTE_USER_AUTO_CREATE |
| 默认值 | false(未知用户返回 401) |
不开启时,Header 带来的用户名若在 LeafWiki 中不存在,请求直接被拒(401),适合"账号由管理员预先创建"的严格场景。开启后则自动为陌生人开户,配套两个子参数:
--http-remote-user-default-role:自动开户的角色,可选viewer/editor,默认viewer。严禁设为admin——服务器会直接拒绝启动,防止伪造的 Header 自动"造出"管理员--http-remote-user-email-header-name(环境变量LEAFWIKI_HTTP_REMOTE_USER_EMAIL_HEADER_NAME):指定一个额外 Header 提供邮箱(如X-Forwarded-Email)。若未配置或 Header 为空,则使用不可投递的占位邮箱<用户名>@remote-user.invalid
两个细节值得记住:身份 Header 的值会原样成为新账号的用户名(即使长得像邮箱);自动创建的账号密码是随机且不可知的,用户只能通过可信代理访问,无法用内置登录表单登录。此外,若 Header 声称的邮箱已属于另一个账号,LeafWiki 会返回 401 阻止冲突。
5️⃣ --login-url / --logout-url:SSO 重定向闭环(v0.12.0+)
| 参数 | 环境变量 | 作用 |
|---|---|---|
--login-url |
LEAFWIKI_LOGIN_URL |
未登录访问时,前端重定向到外部 IdP 登录页(如 https://auth.example.com/login),替代内置登录表单 |
--logout-url |
LEAFWIKI_LOGOUT_URL |
登出后跳转到 IdP 登出地址,完成 SSO 会话清理 |
两者独立可选、可只配其一,值必须以 http:// 或 https:// 开头(相对路径会被拒绝启动)。⚠️ 特别提醒:--login-url 一旦设置就无条件生效——包括 /login 页面本身都会被重定向,没有应用内逃生通道。配错一个不可达的 URL,会把所有人(含管理员)锁在门外,务必先验证再上线。
完整配置示例:nginx + LeafWiki 对接 SSO
LeafWiki 侧(以 README 官方示例为准,见 README.md):
./leafwiki \
--jwt-secret=yoursecret \
--admin-password=yourpassword \
--enable-http-remote-user=true \
--http-remote-user-header-name=X-Forwarded-User \
--trusted-proxy-ips=127.0.0.1,172.18.0.0/16 \
--enable-http-remote-user-auto-create=true \
--http-remote-user-email-header-name=X-Forwarded-Email \
--http-remote-user-default-role=viewer \
--login-url=https://auth.example.com/login \
--logout-url=https://auth.example.com/logout
nginx 侧的关键点参考 e2e-proxy/nginx/nginx.conf:先清掉客户端可能伪造的身份头,再按 SSO 认证结果设置:
location / {
# 关键:抹掉客户端直接注入的 Remote-User,防止身份伪造
proxy_set_header Remote-User "";
# 再根据上游 SSO 认证结果设置(oauth2-proxy 等组件会注入该值)
proxy_set_header Remote-User $remote_user;
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
HTTPS 与 Let's Encrypt 的完整 nginx 配置可参考 docs/install/nginx.md;想搭一套 Dex 作为 IdP 做本地演练,仓库里有现成示例 hacks/proxy-auth/dex/config.yaml,注意其中注释也强调了:Dex 侧的用户需要先在 LeafWiki 中存在(除非开启了自动创建)。
新手易踩的 4 个坑
- 只开总开关、忘了
--trusted-proxy-ips:Header 认证等于裸奔,务必与可信代理 IP 成对出现 - Header 名与代理侧不一致:
Remote-User是默认值,但很多 SSO 组件注入的是X-Forwarded-User,两边要一字不差 --login-url配错锁死全站:设置后连/login都会被重定向,上线前先用浏览器验证该地址可达- 默认角色想设为 admin:服务器会直接拒绝启动;自动创建的用户需管理员手动提权
延伸阅读
- 认证中间件实现:internal/http/middleware/auth/reverse_proxy.go
- 可信代理 IP 解析:internal/http/middleware/auth/trusted_proxies.go
- 参数定义与帮助文本:cmd/leafwiki/flags_proxy.go
- 端到端代理认证测试(含自动创建流程):e2e-proxy/proxy_auth_test.go
- 全部 CLI 参数与环境变量速查:README.md
配好这 5 个参数,LeafWiki 就能无缝融入你现有的 SSO 体系:用户在 IdP 登录一次,进入 Wiki 时无感、免密、开箱即用 🚀

