LeafWiki反向代理认证详解:HTTP Header对接外部SSO,5个关键参数讲透

原创2026-10-14 10:58:211,448 阅读

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 个关键参数把整套机制讲透 🛡️

LeafWiki 反向代理认证部署后的 Markdown 编辑与实时预览界面

工作原理: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,会把所有人(含管理员)锁在门外,务必先验证再上线。

LeafWiki 单点登录成功后的知识库页面浏览视图

完整配置示例: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 个坑

  1. 只开总开关、忘了 --trusted-proxy-ips:Header 认证等于裸奔,务必与可信代理 IP 成对出现
  2. Header 名与代理侧不一致:Remote-User 是默认值,但很多 SSO 组件注入的是 X-Forwarded-User,两边要一字不差
  3. --login-url 配错锁死全站:设置后连 /login 都会被重定向,上线前先用浏览器验证该地址可达
  4. 默认角色想设为 admin:服务器会直接拒绝启动;自动创建的用户需管理员手动提权

延伸阅读

配好这 5 个参数,LeafWiki 就能无缝融入你现有的 SSO 体系:用户在 IdP 登录一次,进入 Wiki 时无感、免密、开箱即用 🚀

登录后查看全文
leafwiki