LeafWiki 介绍与选型指南

LeafWiki（perber/leafwiki）实体甄别、Go 单二进制架构与功能全景、五条部署形态、与 django-wiki/Gitit/AmuseWiki/Wiki.js/Outline 的量化选型对比、适用边界与风险评估（v0.14.2，2026-11-01 溯源）。

LeafWikiLeafWiki文档管理WikiDocs2026/11/01

LeafWiki 介绍与选型指南

查询日期：2026-11-01。本文为联网溯源篇，全部量化数据来自官方仓库、官网与徽章接口，本地实测数据见本专栏部署篇与 API 篇。

一、实体甄别与身份确认

组件发现池中的候选名 LeafWiki 对应唯一可自托管部署的真实实体，甄别结论如下：

项目结论取证来源
仓库全名perber/leafwiki（GitHub）官网 leafwiki.com 博客、GHCR 包页、raw 仓库文件
实现语言Go（后端单二进制）+ React/Vite（前端，构建时内嵌）官方 README「Stack: Go · React (Vite) · SQLite」
形态自托管 Wiki 引擎 / 团队知识库，单可执行文件 + SQLite + 磁盘 Markdown官方 README 首段定位
许可证MITGHCR 包页
GitHub 星数1.2kshields.io 徽章 JSON（2026-11-01 查询）
最新稳定版v0.14.2shields.io release 徽章 JSON（2026-11-01 查询），README 源码构建示例引用 v0.13.0 为近期特性线
官方站点https://leafwiki.com（含演示站 demo.leafwiki.com，每小时重置）官网与 README

甄别说明：检索中同名干扰项仅有美国华盛顿大学 IT 部门的内部文档系统「Leaf Docs」（uwrit/leaf，与本项目无关，非通用自托管组件）。可部署实体唯一指向 perber/leafwiki，即 GHCR 公开包 ghcr.io/perber/leafwiki（MIT License，作者 perber，接受 GitHub Sponsors/Ko-fi 捐赠的个人主导开源项目）。

二、它解决什么问题

官方 README 的定位一句话：「Self-hosted wiki. Single Go binary. SQLite + Markdown stored on disk」——面向「用文件夹而不是信息流思考」的工程师与自托管玩家。它明确对标的是这类反馈：看完 Wiki.js 或 Outline 后觉得「为了我要的那点东西，运维代价太大了」。

核心设计取舍：

  • 零外部依赖：不需要 Postgres、Redis、Node.js 运行时，一个二进制 + 一个数据目录即全部；
  • 内容不锁定：页面正文以纯 Markdown 文件落盘（带 leafwiki_* 前置元数据），应用外可直接读，备份就是停服后 cp -r；
  • 结构化导航：显式树形层级 + 手动页面排序，而不是扁平笔记流；
  • 刻意窄化：官方直接列出「不适合」场景（见第六章），不做 Confluence/Notion 替代。

三、功能全景（官方 README 溯源）

核心功能：

  • 树形导航与手动排序（排序与文件名解耦）
  • 标题+正文全文检索，支持标签过滤；页面标签全局可检索
  • 反向链接与链接状态审计（入链/出链/断链，管理员有断链专项视图）
  • 内置 Markdown 编辑器：实时预览、快捷键、内部链接自动补全、图片 Ctrl+V 粘贴
  • 并发编辑乐观锁（版本冲突拒绝后写入）
  • Markdown 扩展：表格、任务列表、脚注、callout（:::info/:::warning）、折叠块、Mermaid 图、KaTeX 数学块（$$...$$）、净化后的内嵌 HTML、PDF 嵌入（可指定页码）

访问模式（三态）：

  1. 内部 Wiki（默认）：读写均需登录；
  2. 公开只读（--public-access）：匿名可读、登录可编辑；
  3. 完全开放（--disable-auth）：免登录读写，仅限可信内网。

角色体系：admin / editor / viewer 三级。

运营特性：

  • 反向代理友好（--base-path、--trusted-proxy-ips + Remote-User 头反代认证，v0.10+）
  • 自动快照（ZIP 含 SQLite 库，默认每 24h、保留 10 份）与离线恢复命令
  • 可选 Git 备份（v0.11.3，实验性，SSH/HTTPS 推送远端仓库）
  • SMTP 邮件（v0.13.0：找回密码、用户邀请）
  • TOTP 双因子（需配置加密密钥启用）；外部 SSO 登录/登出跳转 URL
  • Prometheus /metrics 独立监听
  • ZIP 批量导入（编辑器/管理员可用，支持 Obsidian 风格 wiki 链接改写）
  • UI 内置英/德/西三语；自定义样式表、<head> 注入、品牌化（logo/favicon/站名）；暗色模式与移动端适配

官方声明的未就绪项：API Keys（管理员按角色授权的程序访问）标注「in development, not yet ready for use」。

四、部署形态与平台支持

官方提供五条安装路径（README Install 章节）：

形态说明平台
单二进制GitHub Releases 下载 leafwiki-<版本>-<os>-<arch> + .sha256 校验linux-amd64/arm64/386、darwin-amd64/arm64、windows-amd64
Linux 安装脚本install.sh 一键装为 systemd 系统服务，update.sh 升级；Ubuntu/Debian/Raspbian 实测amd64/arm64
Compose 编排官方 compose 片段（服务 + 数据卷 + 环境变量）任意支持者
Kubernetes官方 docs/install/kubernetes.md：Deployment + PVC + Service + Ingress（含 Gateway API 变体）任意
源码构建Go + Node.js，make build 产出与发布版一致的内嵌前端自包含二进制任意

32 位 x86 Linux（如 Intel Atom 上的 Alpine）仅二进制路径支持（无 CGO 构建，兼容 musl），安装脚本与官方发布产物不覆盖。默认监听 127.0.0.1:8080，数据目录默认 ./data。

五、量化选型对比（对照站内 Wiki 家族实测篇）

星数与版本均为 2026-11-01 经 shields.io/官方包页查询；站内实测篇给出部署与运维一手数据：

维度LeafWiki《django-wiki 介绍与选型指南》《Gitit 介绍与选型指南》《AmuseWiki 介绍与选型指南》Wiki.jsOutline
GitHub 星数1.2k1.9k2.3k22129k41k
实现语言GoPython/DjangoHaskellPerlNode.jsNode.js
最新稳定版v0.14.20.13.0（2026-07-31）0.16.x 线2.619（2026-10-10）持续发布持续发布
外部依赖无（SQLite+磁盘 MD）Postgres/MySQL + Django 全家桶无（Git 仓库存储）SQLite + Perl 运行时PostgreSQL 必需PostgreSQL + Redis 必需
部署产物单二进制/编排文件pip 源码工程 + WSGI单可执行文件Debian 包/编排栈需构建 Node 应用需构建 Node 应用
内容存储Markdown 文件 + SQLite 元数据数据库Git 仓库数据库 + 文件Git 或数据库可选数据库
全文检索内置（SQLite 索引）需搭 SearchHandler（如 Elasticsearch）内置内置内置多引擎内置
实时协作无（乐观锁）无无无无有
权限模型三角色 + 三访问模式 + 反代 SSODjango 组权限，较细三级角色多级编辑者细粒度细粒度
定位轻量结构化团队文档/RunbookDjango 项目内嵌 Wiki命令行派，Wiki=Git 仓库出版级文档/电子书全能型 Wiki团队知识库产品化

解读：

  • 与 django-wiki 相比：LeafWiki 不需要把整个 Django 栈请进服务器，运维面从「Web 应用 + 数据库 + WSGI」收敛为「一个进程 + 一个目录」；代价是权限模型只有三级角色，没有对象级细粒度授权。
  • 与 Gitit 相比：两者同为单可执行文件路线，Gitit 以 Git 仓库为唯一真相（版本历史免费获得），LeafWiki 以「Markdown 文件 + SQLite 元数据」为真相、历史靠 opt-in 修订功能与自动快照；LeafWiki 的现代编辑器、反链审计、标签检索更强，Gitit 的命令行工作流与多标记语言（Pandoc）更广。
  • 与 AmuseWiki 相比：AmuseWiki 面向出版排版（Text::Amuse），社区规模小（221 星）；LeafWiki 面向日常团队 Wiki，交互体验现代得多。
  • 与 Wiki.js / Outline 相比：官方 README 点名对比的就是这两个「太重」的参照物——41k/29k 星的功能全面性换来 Postgres/Redis 依赖与升级复杂度；LeafWiki 用刻意窄化换零依赖与 cp -r 备份。

六、官方口径的适用与不适用

README「Good fit / not a fit」原文归纳：

适合：个人 Wiki、工程笔记与 Runbook、团队内部/家庭实验室文档、已有 Markdown 或 Obsidian 库需要结构化 Wiki 界面、小团队要树形导航而非扁平笔记流、低运维开销的自托管环境。

不适合：需要复杂企业权限或审批流的组织；需要实时协同编辑；寻找 Confluence/Notion 替代品的团队。官方强调「LeafWiki 刻意比这些系统窄，聚焦本身就是价值」。

七、项目成熟度与风险评估

  • 版本线：v0.x 快速迭代（v0.7 安全旗标、v0.8.2 base-path、v0.10 反代认证、v0.11.3 Unix socket 与 Git 备份、v0.12 管理员引导参数、v0.13.0 SMTP、v0.14.2 当前稳定），特性以「Since」列逐个标注，升级前需核对发布说明；
  • 社区规模：1.2k 星、个人主导（作者 perber，Sponsors/Ko-fi 模式），bus factor 低，但 MIT 许可 + 内容纯 Markdown 落盘，弃坑风险的数据锁定代价接近零——这是「内容不锁定」设计的直接风险对冲；
  • 未就绪功能：API Keys 明确标注开发中；Git 备份标注实验性；
  • 安全注意：明文 HTTP 必须显式 --allow-insecure 否则认证 Cookie 不工作；JWT secret 短于 32 字符会告警；--inject-code-in-header 不做净化，仅限可信代码。

八、选型结论

在「自托管、低运维、Markdown 为真相」三条同时成立的需求下，LeafWiki 是当前该细分里完成度最高的 Go 单二进制方案：树形导航、全文检索、标签、反链审计、快照/恢复、三访问模式与角色权限构成完整的团队 Wiki 最小闭环，且官方给出从裸二进制到 Kubernetes 的完整安装矩阵。若你需要实时协作、细粒度企业权限或 Confluence 级功能面，应转向 Outline/企业产品；若你是命令行优先且想让版本控制成为存储底座，Gitit 更对味。

后续阅读（本专栏实测篇）：

取证清单（查询日期 2026-11-01）：

  • 官方 README：https://raw.githubusercontent.com/perber/leafwiki/HEAD/README.md（特性、安装矩阵、适用性、操作模式原文）
  • 最新稳定版徽章：https://img.shields.io/github/v/release/perber/leafwiki.json → v0.14.2
  • 星数徽章：https://img.shields.io/github/stars/perber/leafwiki.json → 1.2k
  • GHCR 包页：https://ghcr.io/perber/leafwiki（MIT License、作者、发布物）
  • 官网博客（作者自述设计动机）：https://leafwiki.com/blog/a-beer-a-go-binary-and-a-wiki/
  • 竞品数据：站内已交付实测篇 + https://img.shields.io/github/stars/{jgm/gitit,requarks/wiki,outline/outline}.json
LeafWiki 介绍与选型指南 - Quzuo