Realms Wiki安全加固指南:CSRF防护、HTML过滤、私有Wiki与页面锁定完整实践
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 请求自动携带令牌。
具体来说,项目在前端有三个令牌注入点:
- 编辑器页面:realms/modules/wiki/templates/wiki/edit.html 通过模板生成
csrf_token变量; - AJAX 提交:realms/modules/wiki/static/js/editor.js 在每次非 GET 请求前设置
X-CSRFToken请求头,保存、重命名、删除页面都必须携带; - 回滚表单:历史版本回滚按钮所在的隐藏表单内置令牌,见 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。它的效果是全局性的:
- 匿名用户的
ALLOW_ANON自动变为False(见 realms/config/init.py),未登录用户无法访问首页、页面、历史、对比、订阅等任何接口——每个视图都做了同样的守卫检查,例如 realms/modules/wiki/views.py 的page()与 realms/modules/wiki/views.py 的index(); - 配合
"REGISTRATION_ENABLED": false(定义见 realms/config/init.py)关闭注册入口,只保留管理员手动开号的渠道,注册逻辑在 realms/modules/auth/local/views.py 中校验; - 若开启
RECAPTCHA_ENABLE(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 就完成了一次完整的安全加固。