Wiki.js 2.x 升级至 3.x 的架构变化与注意事项

一、核心架构演变：从通用抽象到专精垂直重构

在 Wiki.js 2.x 时代，系统定位于“广泛兼容的团队知识库”，其架构设计不可避免地受到了跨数据库抽象、混合渲染模型以及单租户拓扑的约束。Wiki.js 3.x（由 Requarks 团队重写）对这些核心机制进行了彻底解构，主要体现在以下四个核心维度的架构演变：

1. 数据库层：废除多数据库抽象，独占并榨干 PostgreSQL 原生能力

Wiki.js 2.x 使用了 Knex.js 与 Objection.js 作为 ORM 抽象层，兼顾支持 PostgreSQL、MySQL、MariaDB、Microsoft SQL Server 以及 SQLite。这种广泛兼容的代价极其沉重：核心业务代码不得不局限于各类数据库交集的“最小通用 SQL 子集”，无法充分发挥高级关系型数据库的特有性能。

在 Wiki.js 3.x 中，官方完全移除了所有非 PostgreSQL 数据库的代码路径，将 PostgreSQL 定为唯一支持的数据库引擎。这一激进的架构重塑带来了显著的架构红利：

• 树形层级目录的高性能查询：利用 PostgreSQL 的递归公共表表达式（Recursive CTEs），以极低消耗一次性检索出完整的页面层级树，彻底消除了 2.x 中在 Node.js 内存中递归拼装页面路由树的 IO 瓶颈。
• 深层元数据与配置存储：全面采用 PostgreSQL 原生 JSONB 字段存储页面的自定义属性、扩展元数据及修订历史变更，兼顾无模式（Schema-less）灵活性与强类型索引检索性能。
• 多语言模糊检索与纠错：深度绑定 PostgreSQL 的 pg_trgm（Trigram 索引）与全文搜索扩展，实现毫秒级即搜即得与拼写模糊容错，摆脱了 2.x 对第三方复杂搜索引擎或低效 SQL LIKE '%keyword%' 模糊查询的重度依赖。
• 原生事件驱动通知：借助 PostgreSQL 原生的 LISTEN / NOTIFY 机制，各后台实例间无需外置 Redis 即可在分布式集群中实现秒级缓存失效与事件广播。

2. 渲染与视图层：从 MPA/SPA 混合模型演进为全站现代 SPA

Wiki.js 2.x 采用了分裂的视图渲染模型：普通用户的知识库阅读端是传统的服务端渲染（MPA）多页面应用，每次点击文章链接都会触发整页刷新和 DOM 重建；而管理控制台则是基于 Vue 2 + Vuetify 的独立单页应用（SPA）。

Wiki.js 3.x 统一了这一鸿沟，将整个系统重构为基于 Vue 3 + Quasar 框架的全站 SPA，并配合首屏服务端渲染（SSR）。这使得普通读者在浏览文章、翻阅左侧目录树、切换语言版本时，均由客户端路由器无缝驱动，不再经历白屏刷新；同时 Quasar 框架提供了强大的自适应布局与手势支持，显著提升了移动端与平板端的交互质感。

3. 内容引擎与多站点拓扑：原生 Multi-Site 与实时多人协同

在 2.x 中，一个 Wiki.js 实例只能服务单一的逻辑知识库体系，若企业需要为不同部门（如研发中心、人事行政、对外公开文档）搭建彼此隔离的站点，必须维护多套 Docker 容器与独立的端口配置。

Wiki.js 3.x 从核心路由层引入了原生 Multi-Site（多站点/多租户）架构。单个 Wiki.js 实例和单套 PostgreSQL 数据库，即可绑定多个不同的域名或子路径，托管若干个完全独立的 Wiki 站点。各站点拥有独立的权限策略、主题外观、导航栏结构与存储目标，同时共享底层的用户账户池与系统核心配置。此外，3.x 将编辑器重构为基于 Monaco 核心的多人协同编辑引擎，支持 WebSocket 协议下的协同状态感知，彻底替代了 2.x 时代的独占式锁机制。

4. 存储流水线细分：文本与媒体附件的解耦分流

在 2.x 时代，外部存储同步（如 Git、AWS S3）往往是“全盘同步”。当知识库包含大量高分辨率图片或 PDF 附件时，直接同步到 Git 仓库会导致仓库体积爆炸，拉取与推送频繁超时。

Wiki.js 3.x 支持为每个站点配置多存储目标规则路由。团队可以将纯文本 Markdown 页面定向同步至 GitHub 仓库（通过 GitHub GraphQL API 与 Webhooks 进行秒级双向事件同步），而将上传的图片、视频、附件二进制大文件分流持久化至 AWS S3、MinIO 或 Azure Blob Storage，实现内容与资产的高效分治。

二、升级前置条件与数据库适配决策

由于 3.x 对数据库引擎的专精限制，升级绝非简单地在 docker-compose.yml 中把镜像版本修改为 3.x 即可。在正式开始升级操作之前，系统管理员必须根据当前 2.x 实例的真实环境，依次通过以下三道前置评估关卡。

三、标准升级操作步骤与执行流程

当确认当前实例已使用合规的 PostgreSQL 数据库后，升级应按照“环境停机冷备 → 编排配置适配 → 触发自动化 Schema 迁移 → 功能冒烟验收”的标准四步法依次推进。

步骤 1 实例停机与全量冷备

升级过程中数据库 Schema 的变更在应用层是单向不可逆的。若未经备份直接升级且中途发生中断，旧版 2.x 将无法再识别被修改后的表结构。因此必须实施严格的停机备份：

# 1. 进入现存 2.x 部署目录并优雅停止 Wiki.js 服务容器（保留数据库运行）
cd /opt/wikijs
docker-compose stop wiki

# 2. 对 PostgreSQL 数据库执行一致性全量逻辑备份 (以 Docker 内置 pg 容器为例)
docker exec -t wikijs-db-1 pg_dump -U wiki -d wiki -Fc -f /var/lib/postgresql/data/backup_v2_preupgrade.dump

# 3. 复制备份文件至外部安全归档目录
docker cp wikijs-db-1:/var/lib/postgresql/data/backup_v2_preupgrade.dump ./backup_v2_preupgrade.dump

# 4. 打包本地上传的静态资源附件目录与配置文件
tar -czvf wikijs_v2_data_backup.tar.gz ./data/ config.yml

步骤 2 容器编排更新与环境变量规范化

Wiki.js 3.x 推荐采用统一标准的 DATABASE_URL 格式替代 2.x 常见的零散变量配置（如 DB_HOST、DB_PORT、DB_USER），以减少解析歧义。编辑 docker-compose.yml 文件：

version: '3.8'

services:
  wiki:
    image: requarks/wiki:3.x
    restart: unless-stopped
    environment:
      # 统一使用标准数据库连接字符串格式
      - DATABASE_URL=postgres://wiki:SecretPassword123@db:5432/wiki?sslmode=disable
      - PORT=3000
      # 生产环境反代域名配置
      - HA_MODE=false
    ports:
      - "3000:3000"
    volumes:
      - ./data:/wiki/data
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=wiki
      - POSTGRES_USER=wiki
      - POSTGRES_PASSWORD=SecretPassword123
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

步骤 3 启动容器并执行自动化 Schema 迁移

在后台启动新版本容器。Wiki.js 3.x 在首次启动时，会自动连接 PostgreSQL 检测当前表的版本签名。当识别到 2.x 历史表时，会依次按事务执行数据表结构重写：

# 启动新版本服务
docker-compose up -d

# 紧密跟踪容器输出日志，观察 Migration 推进过程
docker-compose logs -f wiki

在日志中，您应能观察到 Running migration: ...、Converting page hierarchy to CTE structure 以及 Creating pg_trgm indices 等关键信息。根据历史文章与版本数量的不同，迁移耗时通常在数秒到数分钟不等。在此期间严禁手动强制重启容器，否则可能造成数据库状态锁定或迁移中断。

步骤 4 服务冒烟测试与系统验证

当日志显示 Wiki.js is ready at http://0.0.0.0:3000 时，打开浏览器访问知识库并核实以下关键功能项：

1. 身份鉴权验证：使用原有的管理员账号与常规成员账号登录，验证密码哈希转换与组织权限映射是否完好。
2. 页面树与渲染验证：检查左侧导航树结构是否层级完好，打开不同编辑格式（Markdown、富文本）的代表性文档，验证图片、表格与代码高亮是否渲染无误。
3. 重建全文搜索索引：登录后台管理面板（Administration），进入 Search Engine 模块，手动点击 Rebuild Index，触发 PostgreSQL pg_trgm 针对历史页面内容的完整分词与三元模型索引构建。
4. 存储同步状态核验：进入 Storage 模块，检查原配置的 Git 或云存储凭据状态，执行一次手动“Sync Now”以确认数据上报通路畅通。

四、关键注意事项与高风险防范

基于生产环境的工程经验，升级至 3.x 过程中最常遇到的故障通常不是代码 Bug，而是由外部依赖、权限隐患以及回滚机制缺失导致的运维事故。务必掌握以下关键防线：

1. 数据 Schema 变更单向不可逆与应急回滚方案

Wiki.js 官方并不提供从 3.x 数据表降级回 2.x 的“逆向回退脚本”。一旦 3.x 启动并完成了表结构的 ALTER TABLE 操作，旧版 2.x 容器直接挂载该数据库将必定报错。

2. 外部原生扩展依赖（Native Extensions）的变化

Wiki.js 3.x 在图片处理、PDF/EPUB 导出等高级功能上采用了更现代的底层工具链：

• Sharp 图片缩放引擎：依赖 C++ 编译的底层 libvips 库。若使用官方容器镜像，底层已正确打包；但若采用宿主机 Node.js 源码直接部署，需确保宿主系统具备相应的编译环境和 GLIBC 版本。
• Pandoc 与 Chromium (Puppeteer)：如果您的团队需要频繁将 Wiki 页面导出为 PDF 格式，3.x 依赖 Chromium 无头浏览器环境。在容器环境下需确认宿主机分配了充足的内存资源（建议 Wiki 容器分配至少 2GB 内存），避免导出大文档时触发 OOM 崩溃。

3. 反向代理（Reverse Proxy）的 WebSocket 升级配置

由于 Wiki.js 3.x 全面引入了客户端 SPA 实时路由通信与多人协同编辑机制，反向代理（如 Nginx、Caddy、Traefik）必须正确转发 WebSocket 升级头。若未正确配置，前端在协同编辑时会降级为频繁的高频 HTTP 轮询甚至报错无法连通。

# Nginx 核心配置片段示例
location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    # 必须显式传递 Upgrade 头以保障 WebSocket 与实时协同
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

4. 生产就绪度（Production Readiness）与业务选型建议

对于生产环境的升级决策，团队应建立理性的评估模型：

• 推荐立即规划升级的场景：团队已在使用 PostgreSQL、对文章加载速度有较高要求、期望使用 Multi-Site 统一管理多个子部门知识库、需要多人在线协作编辑的团队。
• 建议延后升级或谨慎验证的场景：知识库重度依赖复杂的企业级专属第三方认证插件、或当前数据库仍深绑在 MySQL/SQLite 且缺乏中转迁移维护窗口的场景。建议先搭建独立的 3.x 测试实例，完成文档导入与业务验证后，再执行生产切流。

五、结语

Wiki.js 从 2.x 向 3.x 的跨越，代表了开源知识库系统向云原生、高性能与专精数据库底座演进的必然趋势。尽管独占 PostgreSQL 与重构全站 SPA 在初期带来了一定的迁移门槛，但它所换来的是无与伦比的页面响应速度、更加坚固的事务一致性以及原生的多站点管理能力。只要在升级前落实好数据库类型甄别、做好全量逻辑备份、依序执行自动化迁移脚本，便能稳健平滑地完成这次核心技术栈的跃迁。