django-wiki 介绍与选型指南

目标：面向需要在自有服务器上评估、选型 Wiki 引擎的团队，说明 django-wiki（PyPI 包名 wiki）的定位、架构、功能边界与同类量化对比，帮助判断"是否该选它"。本文全部结论来自官方与公开渠道联网溯源（查询日期 2026-11-01），不含本地实测；部署与配置实测见本专栏《Debian 13 安装 django-wiki 0.13.0 指南》《django-wiki 0.13.0 配置参数详解》《django-wiki 0.13.0 常用 CLI 命令与工具详解》。

一、环境信息

本文的"环境"即取证渠道，全部为公开网络来源，查询日期均为 2026-11-01：

• PyPI 项目页：https://pypi.org/pypi/wiki/json（最新版本、requires_python、依赖约束、License 分类器）
• GitHub 仓库：https://github.com/django-wiki/django-wiki（releases.atom 发布记录、README 的 Django 支持矩阵）
• 官方文档站：https://django-wiki.readthedocs.io/（Installation、Customization、Settings 三章）
• 星数徽章：https://img.shields.io/github/stars/<owner>/<repo>.svg（未直连 api.github.com，规避限流）
• 站内对照文档：quzuo.net 已有 MediaWiki、Wiki.js、DokuWiki、XWiki、Otter Wiki、AmuseWiki 六个 wiki 专栏（详见第七章对比表内链接）

被评估对象基本信息速览：

二、软件概述

django-wiki 是一个为 Django 框架编写的 wiki 系统（PyPI summary 原文："A wiki system written for the Django framework."）。它不是一个下载即用的独立软件，而是一个需要放进 Django 工程、随工程一起配置与运行的"应用包"：官方 Installation 文档开篇即说明"django-wiki is an application for Django. This means that you need to setup a basic Django project in order to use django-wiki"（查询日期 2026-11-01）。

这一定位决定了它与 MediaWiki、Wiki.js 等"独立站点程序"的根本差异——后两者是装好即得一个完整 wiki 站点，而 django-wiki 得到的是一段可与你既有 Django 业务（认证、后台、ORM、模板体系）无缝共生的 wiki 子系统。典型用法有两种：

1. 独立知识库站点：新建一个最小 Django 工程，只挂 wiki 应用，用 gunicorn/uwsgi 托管（本专栏部署篇即此形态）；
2. 嵌入式 wiki：在已有 Django 产品内加一段 /wiki/ 路由，复用产品自身的用户体系与登录态。

版本节奏（GitHub releases.atom，查询日期 2026-11-01）：

约每半年一版、维护线跟随 Django LTS 推进，节奏稳定但社区规模不大（1.9k 星）。README 给出的 Django 兼容矩阵（查询日期 2026-11-01）：

核心运行依赖（PyPI requires_dist，查询日期 2026-11-01）：

💡 技术拓展：Wiki 引擎的内容存储模型不止"数据库"一种，选型前值得看清全貌——

存储模型	代表	特点	取舍
关系库 + 树结构	django-wiki、MediaWiki、XWiki、Wiki.js	权限/历史/检索强，事务一致	迁移备份要过数据库
平面文件（无数据库）	DokuWiki、WikiDocs	文件即内容，备份=拷目录	高并发与细粒度权限弱
Git 仓库存储	Otter Wiki	内容版本即 git 提交，可 PR 协作	二进制大文件与在线权限弱

django-wiki 属第一类：文章树、修订历史、权限全部落在 Django ORM 管理的数据库表里，内容版本由自身 ArticleRevision 模型承担而非外部 VCS。

三、核心架构

官方文档与源码结构（Settings 参考页、Installation 页，查询日期 2026-11-01）显示 django-wiki 由以下几层构成：

1. 数据模型层。三张核心表承载一切：Article（文章，含 current_revision 指针与读写字段）、ArticleRevision（修订，含 title/content/user_message/previous_revision，历史与回退的依据）、URLPath（URL 树节点，借助 django-mptt 以左嵌套值实现"父路径/子路径"层级，支持移动节点即整棵子树改路径）。文章与 URL 路径分离设计，使"一篇文档挂在树上任意位置、移动不改内容 ID"成为可能。

2. 插件框架层。插件以 ArticlePlugin 关联模型挂到文章上，官方 Installation 文档要求按固定顺序注册（"it's important to maintain the order due to database relational constraints"）。内置插件共 8 个：attachments（附件）、images（图片，走 sorl-thumbnail 出缩略图）、links（文章间链接图谱）、editsection（按小节编辑）、globalhistory（全站修订历史）、help（内置帮助页）、macros（渲染宏）、notifications（订阅通知，基于 django-nyt）。

3. 渲染管线层。内容以 Markdown 书写（WIKI_LANGUAGE 固定为 markdown），渲染链为 Python-Markdown + 内置扩展（codehilite 代码高亮、toc 目录、wikilinks 双链、previewlinks、responsivetable）→ bleach 白名单净化（WIKI_MARKDOWN_SANITIZE_HTML 默认开启，HTML 标签/属性/样式三层白名单）→ 输出 HTML。官方文档明确"不建议关闭 bleach，除非你清楚自己在做什么"。

4. 权限层。复用 Django auth 的 Group/User，在文章与路径两级给出 group_read/group_write/other_read/other_write 字段；全局可用 WIKI_CAN_READ/CAN_WRITE/CAN_DELETE/CAN_MODERATE/CAN_ADMIN 等覆写为函数式策略（默认 None=走模型字段）。匿名可读、匿名不可写是默认姿态（ANONYMOUS=True, ANONYMOUS_WRITE=False）。

5. 通知与邮件层。django-nyt 提供订阅模型，manage.py notifymail 作为常驻/定时任务把订阅变更汇总发邮件（详见本专栏 CLI 篇）。

6. 站点与多租户层。依赖 django.contrib.sites，SITE_ID 必填——同一套库可跑多个 wiki 站点。

编辑器：默认 WIKI_EDITOR = "wiki.editors.markitup.MarkItUp"（官方 Settings 参考页），MarkItUp 是浏览器端 Markdown 编辑辅助组件；官方文档说明该配置可替换为第三方或自研编辑器类。

搜索：PyPI 核心依赖不含任何搜索引擎（查询日期 2026-11-01）——站内全文检索不在开箱能力内，需要自行集成检索方案；对比 Wiki.js/MediaWiki 内置检索，这是 django-wiki 的显著留白。

四、功能特性

按官方文档（Installation/Customization/Settings 三章，查询日期 2026-11-01）归纳：

• 层级 URL 树：文章按 父路径/子路径/ 组织，支持整树移动（moved_to 重定向字段保留旧链接）。
• 完整修订历史：每次保存生成新 ArticleRevision，可对比、可回退、可锁定（locked）与标记删除（deleted）。
• 细粒度权限：全站/分组/用户/文章四层，默认"登录者可写、匿名只读"。
• 账号体系：WIKI_ACCOUNT_HANDLING/WIKI_ACCOUNT_SIGNUP_ALLOWED 控制注册登录页；也可完全复用宿主 Django 项目的 auth。
• 附件与图片：附件带版本历史与容量策略；图片插件生成缩略图并支持响应式表格/灯箱类扩展配置。
• 通知订阅：对文章/分类订阅变更，django-nyt 汇总，notifymail 发信。
• 反滥用：修订频率限流（按用户/匿名分别配 REVISIONS_PER_MINUTES 等）、编辑日志记 IP（LOG_IPS_ANONYMOUS 默认开）。
• 安全渲染：bleach 三层白名单净化 HTML/属性/样式，防 XSS。
• 国际化：README 声明已完整翻译 13 种语言（查询日期 2026-11-01）。
• 可扩展：插件框架 + 可替换编辑器类 + 可覆写 URL 配置类（WIKI_URL_CONFIG_CLASS）+ 模板 block 定制（wiki_site_title/wiki_header_branding 等）。

五、快速开始（最小可用示例）

以下为官方 Installation 文档给出的最小接入流程（来源：django-wiki.readthedocs.io Installation 章，查询日期 2026-11-01；逐步实测与完整产出见本专栏《Debian 13 安装 django-wiki 0.13.0 指南》）：

# 1. 建虚拟环境并安装（包名是 wiki）
python3 -m venv venv
./venv/bin/pip install wiki

# 2. 生成一个 Django 工程
django-admin startproject wikisite

# 3. settings.INSTALLED_APPS 追加（顺序敏感，官方文档原样）：
'django.contrib.sites.apps.SitesConfig',
'django.contrib.humanize.apps.HumanizeConfig',
'django_nyt.apps.DjangoNytConfig',
'mptt',
'sekizai',
'sorl.thumbnail',
'wiki.apps.WikiConfig',
'wiki.plugins.attachments.apps.AttachmentsConfig',
'wiki.plugins.images.apps.ImagesConfig',
'wiki.plugins.macros.apps.MacrosConfig',
'wiki.plugins.help.apps.HelpConfig',
'wiki.plugins.links.apps.LinksConfig',
'wiki.plugins.editsection.apps.EditSectionConfig',
'wiki.plugins.notifications.apps.NotificationsConfig',
'wiki.plugins.globalhistory.apps.GlobalHistoryConfig',

# 4. 工程 urls.py 挂路由（官方文档原样）：
urlpatterns = [
    path("admin/", admin.site.urls),
    path("notifications/", include("django_nyt.urls")),
    path("", include("wiki.urls")),
]

# 5. 建库、建管理员、起服务
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
# 浏览器访问 http://127.0.0.1:8000/ 进入 wiki 根页

⚠️ 说明：官方 Installation 文档另有一节"Pre-requisite: Pillow"，提示 Debian/Ubuntu 需先装 libjpeg/libpng 开发库再编译 Pillow；现代 Pillow 已提供 manylinux 预编译 wheel，常规 x86_64 + 官方 PyPI 场景可跳过该步（本专栏部署篇实测未装开发库直接完成安装）。

六、适用场景与限制

适用：

• 团队/产品已有 Django 技术栈，希望 wiki 与业务系统共用登录、权限、后台与部署管线；
• 内网知识库/文档中心，需要文章树、修订历史、附件、订阅通知这些"重协作"能力；
• 需要以代码方式深度定制渲染与权限（Python 层可覆写点齐全）。

限制与风险（均有来源，查询日期 2026-11-01）：

• 不是独立程序：必须维护一个 Django 工程壳（settings/urls/依赖升级都归你管），对非 Python 团队成本高于部署一个开箱即用的独立 wiki 产品。
• 无官方 REST API：PyPI 上不存在 django-wiki-api 包，官方发行也未内置 API 层；需要 API 读写时只能走 Django ORM/自建视图（本专栏 CLI 篇实测确认）。
• 开箱无全文检索：核心依赖不含检索引擎，检索需自行集成。
• 前端形态较旧：官方模板基于 Bootstrap 3（Customization 文档原文），观感与交互不如 Wiki.js 等现代产品。
• 社区规模中等：1.9k 星、约半年一版；遇到长尾问题主要靠读源码与 GitHub issues。
• GPLv3 许可：作为独立站点使用无碍；若把 django-wiki 源码改完后闭源分发整个产品，需评估 GPL 传染边界（对比 XWiki 的 LGPL、Wiki.js 的 AGPL 各有约束）。

七、同类选型对比

站内已实测过六个同类 wiki 引擎，量化对比如下（星数经 shields.io 徽章取证，查询日期 2026-11-01；版本为该组件站内文档实测版本；"—"表示徽章当次未取到数值）：

¹ MediaWiki 星数取其 GitHub 官方镜像 Wikimedia/mediawiki-core（mediawiki/core 徽章当次未返回数值）。

解读：星数与检索/API 两列最能说明生态位——Wiki.js 以 29k 星和 GraphQL API 代表"现代独立 wiki 产品"路线；MediaWiki 5.2k 星代表"百科级重协作"路线；DokuWiki 4.7k 星代表"零数据库平面文件"路线；django-wiki 1.9k 星、无 API 无检索，明显不是"通用 wiki 产品"竞争者，它的价值全在"Django 生态内嵌"这一条赛道上。

"如果…则…"选型建议：

• 如果你的主系统是 Django（管理后台、用户表都在 Django），wiki 要复用登录与权限 → 选 django-wiki；
• 要一个开箱即用、界面现代、带 API 的独立 wiki → 选 Wiki.js；
• 要百科级讨论/半保护/海量页面 → 选 MediaWiki；
• 内网小团队、不想维护数据库、备份=拷目录 → 选 DokuWiki；
• 要 Java 生态企业级表单应用 → 选 XWiki；
• 想要"内容即 git 仓库"、以 PR 方式协作 → 选 Otter Wiki；
• 文学文本排版/出版向农场 → 选 AmuseWiki。

八、参考链接

• 官网：http://www.django-wiki.org
• GitHub：https://github.com/django-wiki/django-wiki （releases.atom 查询日期 2026-11-01）
• PyPI：https://pypi.org/project/wiki/ （查询日期 2026-11-01，最新 0.13.0）
• 官方文档：https://django-wiki.readthedocs.io/ （Installation / Customization / Settings，查询日期 2026-11-01）
• 发布说明：https://django-wiki.readthedocs.io/en/latest/release_notes.html
• IRC：libera.chat #django-wiki（README）
• 站内系列：本专栏《Debian 13 安装 django-wiki 0.13.0 指南》《django-wiki 0.13.0 配置参数详解》《django-wiki 0.13.0 常用 CLI 命令与工具详解》