Realms Wiki安全加固指南:CSRF防护、HTML过滤、私有Wiki与页面锁定完整实践

原创2026-10-26 22:43:541,752 阅读

Realms Wiki安全加固指南:CSRF防护、HTML过滤、私有Wiki与页面锁定完整实践

Realms Wiki 是一款基于 Git 的开源 Wiki 系统(灵感来自 Gollum),支持 Markdown + HTML 编辑。本文带你快速完成 Realms Wiki 安全加固:启用 CSRF 防护、配置 HTML 过滤、开启私有 Wiki 模式并锁定关键页面,让你的 Wiki 既好用又安全。

为什么 Realms Wiki 需要安全加固?🛡️

Realms Wiki 默认允许匿名访问和提交,页面内容由 Markdown 渲染并支持内嵌 HTML。这带来了两类典型风险:

  • CSRF(跨站请求伪造):恶意网站借助已登录用户的会话,偷偷发起编辑、删除、回滚等操作;
  • XSS(跨站脚本):用户在页面中写入恶意 <script> 或 javascript: 链接,在他人浏览器中执行。

好在 Realms Wiki 内置了完整的安全机制,只需正确配置即可全部启用。

快速开始:获取 Realms Wiki 并完成初始化

如果还没有安装,可先克隆仓库并执行配置向导:

git clone https://gitcode.com/gh_mirrors/re/realms-wiki
cd realms-wiki
realms-wiki setup

setup 命令会引导你生成 realms-wiki.json 配置文件,文中所有安全参数都可以写入该文件。默认配置定义在 realms/config/init.py,配置文件中的值会自动覆盖默认值。

CSRF 防护机制详解:Flask-WTF 如何拦截伪造请求

Realms Wiki 基于 Flask 构建,通过 Flask-WTF 的 CsrfProtect 为所有"改变状态"的请求(新建、编辑、删除、回滚页面)强制校验令牌。

核心初始化在两处完成:

  • 应用工厂中创建并挂载防护实例:realms/init.py 执行 csrf.init_app(app),实例定义见 realms/init.py;
  • 每个表单和 AJAX 请求自动携带令牌。

具体来说,项目在前端有三个令牌注入点:

  1. 编辑器页面:realms/modules/wiki/templates/wiki/edit.html 通过模板生成 csrf_token 变量;
  2. AJAX 提交:realms/modules/wiki/static/js/editor.js 在每次非 GET 请求前设置 X-CSRFToken 请求头,保存、重命名、删除页面都必须携带;
  3. 回滚表单:历史版本回滚按钮所在的隐藏表单内置令牌,见 realms/modules/wiki/templates/wiki/page.html。

💡 给测试同学的提示:项目还专门提供了 realms/lib/flask_csrf_test_client.py——一个在测试环境中自动生成 CSRF 令牌的测试客户端,确保 CI 中 CSRF 防护真实生效而非被绕过。

结论:CSRF 防护是默认开启的,你不需要写任何代码,只要不要用 CSRF_ENABLED = false 关闭它即可。

HTML 过滤与 XSS 防御:渲染前的双重净化

Realms Wiki 的 Markdown 渲染器开启了 html: true,允许页面内嵌 HTML,因此必须对输出做净化。净化逻辑集中在 realms/static/js/mdr.js:

  • MDR.sanitize 默认值为 true,每次渲染后都会调用 html_sanitize() 清洗 HTML;
  • 清洗器 realms/static/js/html-sanitizer-minified.js 基于 Google 的 HTML Sanitizer 策略,移除 <script> 等危险标签与 on* 事件属性;
  • 特别地,代码中额外拦截了 javascript: 伪协议链接——任何 URL 解码后以 javascript: 开头的都会被置空,防止恶意链接点击执行脚本。

此外,页面名称在入库前也会经过 realms/lib/util.py 的 to_canonical() 规范化:去除 ?<>[]{}|\^~% 等危险字符、限制路径长度,避免文件名注入。

这套"渲染后净化 + 危险协议拦截 + 文件名规范化"的组合拳,覆盖了 Wiki 场景下绝大多数 XSS 攻击面。

私有 Wiki 配置:PRIVATE_WIKI 参数实战

当 Wiki 面向团队内部使用时,只需一个参数即可整体"上锁":

"PRIVATE_WIKI": true

该参数定义于 realms/config/init.py。它的效果是全局性的:

🔒 组合拳建议:内部 Wiki 推荐 PRIVATE_WIKI: true + REGISTRATION_ENABLED: false + 强 SECRET_KEY,三者缺一不可。

页面锁定:用 WIKI_LOCKED_PAGES 保护核心文档

对于"首页模板、导航入口"等不允许任何人改动的页面,可以将其加入锁定名单:

"WIKI_LOCKED_PAGES": ["home", "_edit/hbs"]

该参数定义于 realms/config/init.py。锁定的生效点在 realms/modules/wiki/views.py 的 page_write() 视图中——新建(POST)、重命名/更新(PUT)、删除(DELETE)以及历史回滚(见 realms/modules/wiki/views.py)都会先检查目标页是否在锁定名单内,命中即返回 403 与 "Page is locked" 错误。

同时,编辑器界面会给出可视化提示:被锁定页面的"Save"按钮会替换为灰色的 Locked 锁形按钮(realms/modules/wiki/templates/wiki/edit.html),用户一眼就能看出该页面受保护。

安全加固清单:上线前逐项核对 ✅

配置项 推荐值 作用 默认值位置
SECRET_KEY 随机长字符串 会话与签名安全基线(默认为占位符 CHANGE_ME) realms/config/init.py
PRIVATE_WIKI 内部团队设为 true 全站登录墙,匿名用户一律拒绝 realms/config/init.py
REGISTRATION_ENABLED 按需设为 false 关闭公开注册,防账号泛滥 realms/config/init.py
WIKI_LOCKED_PAGES 核心页名单 锁定的页面无法创建/修改/删除/回滚 realms/config/init.py
RECAPTCHA_ENABLE 开放注册时设为 true 注册人机验证 realms/config/init.py
AUTH_PROXY 反向代理认证时设为 true 信任代理头完成登录,注意必须保证只能经代理访问 realms/config/init.py

CSRF 防护与 HTML 净化无需配置,默认已随应用启动(挂载逻辑见 realms/modules/wiki/hooks.py 所在模块的发现机制与应用工厂 realms/init.py)。

常见问题速答

Q1:开启 PRIVATE_WIKI 后,匿名访客访问页面会看到什么? 会被重定向到登录页——各视图统一调用 login_manager.unauthorized() 处理(如 realms/modules/wiki/views.py)。

Q2:锁定页面还能查看历史版本吗? 可以。锁定只拦截写入操作(创建、编辑、删除、回滚),查看与历史对比均不受影响。

Q3:CSRF 令牌失效、提交总被 403 拒绝怎么办? 检查表单中是否携带 csrf_token 字段、AJAX 请求是否设置了 X-CSRFToken 头;同时确认 SECRET_KEY 未被重启后改变(令牌基于该密钥签名)。

总结

Realms Wiki 的安全模型可以概括为"四道防线":🛡️ CSRF 令牌拦截伪造请求、🧼 渲染期 HTML 净化与 javascript: 协议拦截、🔒 PRIVATE_WIKI 全站登录墙、🔐 WIKI_LOCKED_PAGES 页面级锁定。配合修改 SECRET_KEY、按需关闭注册这两项基础动作,个人博客到企业内网知识库都能安心使用。把本文的清单逐项打勾,你的 Realms Wiki 就完成了一次完整的安全加固。

登录后查看全文
realms-wiki