Wiki.js 2.5 介绍与选型指南

目标：为团队在「搭建自托管知识库 / Wiki 系统」时提供 Wiki.js 的全景认知与选型依据。本文基于官方文档站 docs.requarks.io、GitHub 仓库 requarks/wiki、Docker Hub requarks/wiki 的公开信息溯源编写，全部版本号、活跃度数据均实查并标注来源与查询日期（2026-10-18），未做本地安装实测（安装实测见部署篇）。

一、环境信息（信息基准）

本文是认知篇，不依赖本地环境安装，信息基准如下，读者可按清单复核最新状态。

• 信息查询日期：2026-10-18（文中所有活跃度、版本号数据的采集时间）
• 版本依据：
  • 最新稳定版：v2.5.315（GitHub Releases，发布于 2026-09-25，实查地址 https://github.com/requarks/wiki/releases）
  • 下一代 3.0 尚在 Beta：3.0.0-beta.672（2026-10-13，未转正，仅供关注，不建议生产使用）
  • Docker Hub 上 requarks/wiki:2 浮动 tag 当前对应 2.5.316（2026-10-02 构建），2.5 浮动 tag 与固定小版本 tag 2.5.315 均可用（实查 https://hub.docker.com/r/requarks/wiki/tags）
• 官方来源清单：
  • 官网：https://js.wiki
  • 官方文档站：https://docs.requarks.io
  • GitHub 仓库：https://github.com/requarks/wiki（开发主仓库，历史上曾托管于 GitLab，现已以 GitHub 为准）
  • Docker Hub：https://hub.docker.com/r/requarks/wiki；GitHub Packages：https://ghcr.io/requarks/wiki
  • Discord 社区与官方 Demo：https://docs.requarks.io（文档站首页入口）
• 本文基准版本：Wiki.js 2.5.315（稳定线 2.5.x，全文以此版本统一叙述）

💡 说明：Wiki.js 3.0 为在研大版本，官方已明确 3.0 起将仅支持 PostgreSQL 数据库（其余数据库引擎不再支持，见官方 Requirements 页），选型时若计划长期升级到 3.x，应直接以 PostgreSQL 为数据库底座。

二、软件概述

本节给出 Wiki.js 的身份定位、许可与版本活跃度，帮助读者快速判断它「是什么、谁在维护、当前状态如何」。

• 一句话定位：Wiki.js 是一个基于 Node.js 的现代、轻量且强大的开源 Wiki / 知识库应用，以 Markdown 为内容核心，强调「简洁的界面 + 强大的权限与扩展体系」（官方自述：A modern, lightweight and powerful wiki app built on NodeJS, Git and Markdown，来源 v2.5.315 仓库 package.json description，查询日期 2026-10-18）。
• 当前版本：最新稳定版 2.5.315（2026-09-25 发布）；2.5.x 为当前生产推荐版本线；3.0 处于公开 Beta 迭代中。
• 开源许可：AGPL-3.0（GNU Affero 通用公共许可证 v3.0，实查 GitHub 仓库 license 标识与 LICENSE 文件，查询日期 2026-10-18）。AGPL 对「通过网络向用户提供服务」的场景也有开源义务，商用闭源集成需评估该许可的传染性要求。
• 维护方与历史：由 Nicolas Giard（GitHub ID：NGZI）主导的 requarks 组织维护，仓库创建于 2016-08-16，持续迭代至今约十年，未归档、活跃开发中（实查仓库元数据 stargazerCount/createdAt/isArchived，查询日期 2026-10-18）。
• 社区活跃度（2026-10-18 实查）：GitHub Stars 29,048、Forks 3,325、Watchers 319。
• 技术栈：服务端 Node.js（2.5.315 官方要求 Node.js ≥ 20，实查仓库 package.json engines 字段），前端 Vue.js（渐进式单页应用），API 层为 GraphQL（Apollo Server），数据访问层为 ORM（Objection.js/Knex），支持多数据库引擎。

2.1 版本发布节奏（实查记录）

Wiki.js 2.x 线持续维护，3.x 线高频 Beta 发布。以下为 2026-10-18 通过 GitHub Releases Atom 源实查到的最近发布序列（节选）：

关键解读：Beta 线保持每周 2~3 个构建的高频迭代，稳定线 2.5.x 以「月级」节奏发布修订版；生产环境应固定使用 2.5.x 稳定 tag（如 requarks/wiki:2.5.315），不要使用 latest。

三、核心架构

本节从部署形态、模块化设计与数据链路三个角度拆解 Wiki.js 的架构，理解它有助于后续配置与排障。

• 单体应用 + 独立数据库：Wiki.js 以单个 Node.js 进程运行（内置 HTTP 服务，默认端口 3000），状态全部落在数据库中（页面、用户、组、配置、版本历史均入库），应用本身无本地状态文件（上传资产默认落库，也可配置到文件系统/S3 等存储模块）。因此扩容、备份、迁移的核心都是「数据库」。
• B/S 架构：浏览器访问 Web UI；程序化访问走 GraphQL API（端点 /graphql）；静态资源由应用直接伺服。
• 模块化设计（Wiki.js 的核心卖点）：四类可插拔模块，均可在管理后台启用/配置，无需重启进程：

关键解读：一个 Wiki.js 实例可以「Git 仓库为主存储 + PostgreSQL 为索引/元数据」，实现内容版本化与灾备；也可以同时挂 LDAP 与本地账号两套认证。实测环境（部署篇）默认启用的是「数据库存储 + DB 搜索 + Local 认证 + Markdown 编辑器」这套最小组合。

💡 技术拓展：Wiki 内容的「存储后端」不止 Wiki.js 的 storage 模块一种思路。同类产品对比：MediaWiki 以「数据库为唯一事实源」（文件仅存附件）；DokuWiki 以「纯文本文件为唯一事实源」（无数据库）；Outline 以「PostgreSQL 存储 + 可选 Slack 集成」。Wiki.js 介于两者之间——数据库承载运行时，同时通过 storage 模块把内容镜像到 Git/S3 等。选型时按「是否需要内容版本化外置」取舍：需要 Git 化内容管理选 Wiki.js 优势明显，纯静态文件思路则 DokuWiki 更贴合。

本文/本方案实际采用 Wiki.js 的「数据库 + 存储模块」混合模型，理由是页面元数据（权限、标签、历史）在数据库中检索效率高，同时保留 Git 备份能力。

• 高可用（2.3+）：多副本部署（Kubernetes/Docker Swarm）时开启 HA_ACTIVE=1（要求 PostgreSQL 数据库），实例间通过数据库广播变更，避免「改了页面别的副本没刷新」。

四、功能特性

本节按「内容、编辑、权限、认证、搜索、扩展」六个维度罗列 2.5.x 的主要功能，均来自官方文档站与仓库 README（查询日期 2026-10-18）。

1. 内容与编辑
   • 双编辑器：可视化富文本编辑器 + Markdown 源码编辑器（每个页面可自选默认编辑器）。
   • 原生 Markdown 渲染管线，支持 Mermaid 图表、PlantUML、LaTeX 数学公式、代码高亮、Emoji 等渲染扩展。
   • 页面历史版本（diff 对比与回滚）、页面树管理、多语言（每个页面有 locale 维度，支持同一内容多语言版本）。
   • 标签、评论（内置评论或 Disqus 等第三方）、页面评分。
2. 权限与认证
   • 基于组的权限模型：组（Group）内配置权限集 + 页面规则（Page Rules，可按路径/locale/标签匹配读写权限）。
   • 认证策略可叠加：本地账号 + LDAP/OIDC/SAML/OAuth2 等企业认证并行，支持双因素（2FA）。
   • Guest 匿名访问组、只读公开站点一键切换。
3. 搜索
   • 内置 DB 搜索开箱即用；PostgreSQL pg_trgm 模糊搜索；可外接 Elasticsearch、Meilisearch 提升体验。
4. 资产管理
   • 图片/附件上传入库（或文件系统/S3），文件夹结构管理，图片直贴编辑器。
5. 扩展与集成
   • GraphQL API（本文系列有 API 专篇）、Webhook、自定义 CSS/JS 注入、主题系统（含暗色模式）。
   • 内容外置：Git 双向同步、S3 兼容对象存储、主流网盘。
6. 运维友好
   • 管理后台可视化完成全部配置（无需改配置文件即可改大多数运行参数）；健康检查端点；多实例 HA；遥测可关闭。

五、快速上手（官方示例）

本节引自官方文档的最小部署示例（来源：https://docs.requarks.io/install/docker，查询日期 2026-10-18），供读者预览部署形态；完整可复现的部署实操（含真实回显与首次安装向导实测）见本专栏部署篇。

官方 Docker 单容器示例（需自备 PostgreSQL 数据库）：

docker run -d -p 8080:3000 --restart unless-stopped --name wiki \
  -e DB_TYPE=postgres \
  -e DB_HOST=db \
  -e DB_PORT=5432 \
  -e DB_USER=wikijs \
  -e DB_PASS=wikijsrocks \
  -e DB_NAME=wiki \
  requarks/wiki:2

官方推荐的 Docker Compose 形态（wiki + postgres 双服务，节选自同一文档页）：

version: "3"
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: wiki
      POSTGRES_PASSWORD: wikijsrocks
      POSTGRES_USER: wikijs
    logging:
      driver: "none"
      options:
        max-size: "10m"
        max-file: "3"
    volumes:
      - db-data:/var/lib/postgresql/data
  wiki:
    image: ghcr.io/requarks/wiki:2
    depends_on:
      - db
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: wiki
      DB_USER: wikijs
      DB_PASS: wikijsrocks
    restart: unless-stopped
    ports:
      - "80:3000"

volumes:
  db-data:

💡 说明：官方示例的镜像 tag 为浮动 :2，ghcr.io/requarks/wiki 与 docker.io/requarks/wiki 为同一构建的两个人口。生产建议固定小版本（如 2.5.315）并自行管理数据库密码（不要照抄示例密码）。

首次启动后浏览 http://<服务器IP>:端口 即进入初始化向导，完成站点地址确认与管理员账号创建即可使用。完整的向导流程实测、中文语言包安装、页面与 API 实测见本专栏部署篇与 API 篇。

六、适用场景与限制

6.1 适用场景

• 团队知识库 / 内部 Wiki：组-页面规则权限体系贴合「按目录/空间分级授权」的诉求，LDAP/OIDC 对接企业账号体系。
• 技术文档站：Markdown 优先、Git 外置存储（内容可进代码仓库走评审）、暗色模式与代码高亮对开发者友好。
• 中小规模公开文档门户：公开只读模式 + SEO 设置 + 自定义主题，可充当产品手册站。
• 多语言文档：页面级 locale 模型天然支持中英双版本维护。

6.2 限制与注意（实查官方文档，查询日期 2026-10-18）

• 必须独占（子）域名：官方 Requirements 明确「Wiki.js requires a dedicated sub-domain / domain（e.g. wiki.example.com），不能映射到子目录（subfolder）」。反向代理时根路径必须整体转发给 Wiki.js。
• 数据库选型受 3.0 影响：MySQL/MariaDB/MSSQL/SQLite 在 2.5 可用，但 3.0 起仅支持 PostgreSQL；新部署建议直接 PostgreSQL。
• SQLite 不推荐生产使用（官方明示），仅适合临时评估。
• 资源要求（官方 Requirements）：单核 CPU 可运行（建议 2 核以启用后台任务）；Linux 建议 ≥ 1GB 内存（进程常驻约 70MB，渲染/索引有短时峰值）；磁盘 ≥ 1GB 起步（视上传资产量增长）。
• 3.0 迁移路径：官方承诺 3.0 发布后提供导出/导入迁移工具，但 2.x→3.x 属大版本跨越，升级前必须演练备份恢复。
• 无内置多人实时协同编辑：编辑为「单人编辑-保存」模型，需协同写作场景应评估 Outline 等。

七、同类选型对比

本节横向对比 Wiki.js 与同赛道主流自托管 Wiki 的关键维度。所有数据实查于 2026-10-18，来源标注在各列。

7.1 候选概览与社区活跃度

关键解读：Outline 星数最高但已转 BSL 源可用许可（对「提供文档服务给第三方」的商用形态有额外限制，内部使用不受影响）；BookStack 是 MIT 许可最宽松；Wiki.js 居中且 2.5 线十年持续维护；MediaWiki 是维基百科同款，生态与扩展最多但技术栈老旧（PHP + 复杂模板体系），适合大型社区百科而非轻量团队知识库。

7.2 功能与形态对比

关键解读与选型建议：

• 要「知识库 + 内容 Git 化 + 多语言」：Wiki.js 最合适——存储模块的 Git 双向同步是同类中最完整的，页面级 locale 也是四者中唯一原生覆盖多语言的。
• 要「最像 Notion 的现代编辑体验」且组织内部使用：Outline 编辑体验最佳，但注意 BSL 许可与多组件部署成本。
• 要「零门槛给非技术团队用（书/章节结构）+ 宽松许可」：BookStack，MIT 许可对二次开发最友好。
• 要「大型社区百科、海量条目、成熟扩展生态」：MediaWiki，接受较高的运维与模板学习成本。
• 公网文档门户：Wiki.js 与 BookStack 都可胜任；Wiki.js 的主题/暗色模式与渲染扩展更现代，BookStack 结构更「图书化」。

八、参考链接

1. Wiki.js 官网：https://js.wiki
2. Wiki.js 官方文档（安装/配置/模块）：https://docs.requarks.io
3. GitHub 仓库（Releases/tags）：https://github.com/requarks/wiki
4. Docker Hub 镜像（tags 列表）：https://hub.docker.com/r/requarks/wiki
5. GitHub Packages（ghcr.io）：https://ghcr.io/requarks/wiki
6. 系统要求（官方 Requirements）：https://docs.requarks.io/install/requirements
7. Docker 部署（官方，含环境变量表）：https://docs.requarks.io/install/docker
8. Outline 仓库与许可：https://github.com/outline/outline（LICENSE：BSL 1.1）
9. BookStack 仓库与 Releases：https://github.com/BookStackApp/BookStack
10. MediaWiki 版本信息页：https://www.mediawiki.org/wiki/Special:Version