从其他平台迁移数据到 Wiki.js 的方法与注意事项

作者：望舒

时间：2026-11-03

详细讲解从 Confluence、MediaWiki、Notion 等知识库平台迁移数据到 Wiki.js 的技术路径、端到端操作步骤、典型格式转换规则以及关键排错注意事项。

文章目录

将存量知识库从其他平台平稳迁移至 Wiki.js，核心逻辑在于将异构文档转换为符合 CommonMark/GFM 规范的 Markdown 源文件，补齐带有标题与标签的 YAML Frontmatter 元数据头，并依托 Wiki.js 原生提供的 Git 存储双向同步（Git Storage Sync）机制完成自动化批量拉取与页面索引构建。本文将系统梳理主流迁移路径、端到端实施步骤、语法转换规则以及避免数据丢失的高频注意事项。

从其他平台迁移数据到 Wiki.js 的方法与注意事项 — 图 1：从不同源知识库平稳过渡至 Wiki.js 的技术架构与数据流向

一、迁移路径与技术选型

Wiki.js 采用“数据库存储元数据 + 存储引擎（Storage Provider）持久化物理文件”的双层解耦架构。所有的页面正文既保存在关系型数据库（如 PostgreSQL、MySQL、SQLite）中，也可以与远端 Git 仓库保持实时双向同步。在实施数据迁移前，需要根据团队存量知识的体量与技术栈选择合适的路径。

1. Git 存储同步路径（官方推荐，工业级方案）

该方案是官方最成熟、容错率最高的批量导入方式。基本做法是：本地编写脚本将源平台文档清洗为标准的 .md 文件与附件，推送到专用的 Git 仓库（如 GitLab、GitHub 或 Gitea），然后在 Wiki.js 管理后台配置该 Git 存储提供商，触发 Import Everything 任务。Wiki.js 内置的文件解析器会自动提取文件头部 Frontmatter，并在数据库中批量生成对应路由与页面记录。

2. GraphQL API 批处理路径（编程式精准写入）

Wiki.js 提供了完整的 GraphQL API。通过调用 pages.create 变更（Mutation），可以在脚本中精准指定页面的 content、description、editor、isPublished、locale、path、tags 与 title。该方案适合需要严格映射原始历史作者、指定发布时间戳或无法挂载中间 Git 仓库的自动化 CI/CD 环境。

3. 底层数据库直接注入（严格受限，不推荐）

直接向 Wiki.js 的 pages 表执行 SQL 插入通常会导致不可挽回的逻辑损坏。Wiki.js 页面与版本审计（pageHistory）、搜索索引、页面树路径（pageTree）以及权限策略（userRights）紧密联动，脱离系统业务层写入的数据极易造成前台路由 404 错误与搜索引擎索引崩溃。

二、基于 Git 存储的通用标准迁移流程

以最稳妥的“中转 Git 仓库 + 存储拉取”为例，整体迁移划分为规范的五个阶段。无论数据源是来自 Confluence、MediaWiki、Notion 还是自建知识库，均应遵循严密的工序推进。

步骤 1：源平台数据导出与本地暂存

从源系统导出全量数据包，解压到本地独立的中转工作区（如 staging/raw/）。确保所有图片、文档附件（PDF、Excel 等）被一并提取并保持相对目录完整性。对于大型空间，建议按业务模块或空间分组导出，降低单次批处理的内存与排错压力。

步骤 2：格式清洗与 Markdown 规范化

使用通用转换工具（如 Pandoc）或语言编写的处理脚本，将源系统的 HTML、XML 或专有语法（如 Wikitext）统一转为标准 GFM（GitHub Flavored Markdown）。在该阶段需剥离源平台专有的样式代码（如 Confluence 的 Macro 标记、内联行内样式 style="..."），修正复杂表格对齐，并重写代码块语言声明。

步骤 3：注入 YAML Frontmatter 与 Slug 路径规整

Wiki.js 依赖 Markdown 文件首部的 YAML 格式 Frontmatter 识别文章标题、描述与标签。同时，Wiki.js 的路由完全取决于文件在仓库中的相对路径与文件名。例如文件 dev/ops/docker-guide.md 导入后将映射为路由 /dev/ops/docker-guide。在此步骤中，须确保文件名称与目录名称全部规范为小写字母及短横线。

---
title: "Docker 容器编排运维手册"
description: "生产环境 Docker Compose 部署规范与安全加固"
published: true
date: 2026-10-31T08:00:00.000Z
tags:
  - docker
  - devops
  - linux
editor: markdown
---

# Docker 容器编排运维手册

正文从此处开始编写，遵循标准 CommonMark 规范...

步骤 4：推送 Git 仓库并触发 Wiki.js 导入

在本地将规整完毕的文档目录与静态资产目录初始化为 Git 仓库并推送到代码托管服务器：

# 进入处理完成的工作目录
cd staging/normalized/
git init -b main
git add .
git commit -m "feat: initial migration commit for wiki.js import"
git remote add origin git@git.company.internal:wiki/knowledge-base.git
git push -u origin main

登录 Wiki.js 管理员面板，依次进入 Administration → Storage → Git。配置远程仓库的 SSH 私钥或 Access Token，设定默认分支（如 main），将同步模式设为双向或单向拉取，保存后点击右上角的 Import Everything 按钮。

执行观察提示

导入过程中，可打开浏览器开发者工具或观察 Wiki.js 的服务端日志容器输出（docker logs -f wikijs）。终端将持续打印 [STORAGE] Importing page: dev/ops/docker-guide ... OK。待日志恢复闲置，即代表全量拉取完成。

步骤 5：重建搜索索引与链路抽检

Git 存储的底层批量拉取为了保障写入性能，默认不会即时触发耗时的全文分词。导入完毕后，必须手动进入 Administration → Search Engine，点击 Rebuild Index 重建全局检索索引，随后在生产前台对目录树层级、图片渲染与页面内部链接进行针对性校验。

三、典型源平台的针对性转换技巧

不同知识库平台在语法结构、富文本标记及附件存储机制上存在显著差异。针对 Confluence、MediaWiki 和 Notion，需要采用专门的语法转换与路径重映射策略。

1. Atlassian Confluence 迁移要点

Confluence 页面采用专有的 XHTML Storage Format。建议在空间管理中导出为 HTML 格式包，随后借助 Pandoc 进行语法降级：

宏组件重写：Confluence 常见的 info、tip、warning 提示块需通过正则表达式清洗为 GFM 引用块（如 > [!NOTE] 或 > [!WARNING]）。
附件路径修复：Confluence HTML 导出包中图片通常存放在 attachments/ 文件夹，并在 HTML 中使用动态参数引用。转换脚本需将图像重命名后统一挪至 assets/images/ 目录下，并将 Markdown 图片链接规范为 ![alt](/assets/images/filename.png)。
层级页面处理：Confluence 允许同名页面存在于不同父级下。迁移到 Wiki.js 时，必须按照其父子嵌套结构创建对应深度的文件夹目录，防止同名覆盖。

2. MediaWiki 迁移要点

MediaWiki 采用 XML 数据库导出（Dump）。Wikitext 具有高度模板化和分类标签特征：

内部链接语法转换：MediaWiki 的双中括号链接 [[页面名称|显示文本]] 必须清洗为标准 Markdown 链接 [显示文本](/path/to/slug)。
图片缩略图语法：MediaWiki 独有的 [[File:demo.png|thumb|center|说明]] 需解析出文件名并转为 ![说明](/assets/demo.png)。
分类转标签：底部的 [[Category:开发指南]] 应当被脚本截获，提取文本并自动写入 YAML Frontmatter 的 tags 数组中。

3. Notion 迁移要点

Notion 官方支持将工作区导出为包含 Markdown 和 CSV 的 ZIP 压缩包：

剥离 32 位 UUID 后缀：Notion 导出时会在每个目录名和文件名末尾附加长哈希字符串（例如 API Documentation 8f2a1b...md）。在推入 Wiki.js 前，必须通过批处理脚本剥离末尾的 UUID，并将驼峰与空格替换为小写短横线 api-documentation.md。
重构同名容器目录：当 Notion 页面包含子页面时，Notion 会同时生成一个同名 Markdown 文件和一个同名子文件夹。在 Wiki.js 中，对应容器页可命名为该目录下的 index.md 或保持对应层级，以保证导航树能顺畅展开。

四、核心注意事项与高频陷阱排查

在批量数据迁移中，最容易引起生产故障的往往不是文本本身，而是路由兼容性、静态附件引用、Git 双向同步冲突以及权限配置。

校验维度	高频故障表现	根本原因	标准解决规程
路由与 Slug	前台访问返回 404 Not Found	文件名含有大写字母、空格、非 ASCII 字符或路径大小写不匹配	1. 全量文件名与文件夹名统一清洗为小写字母与短横线（如 `system-arch.md`）。 2. 检查系统 Localization 设置中的默认语言代码前缀（是否开启语言路径嵌套）。
附件与图片	正文图片碎裂、PDF 无法下载	Markdown 使用了跨级相对路径（如 `../../img/1.png`）或硬编码旧域名	1. 所有静态媒体文件集中存放于仓库的 `assets/` 目录。 2. 正文内图片统一使用以 `/assets/` 开头的绝对根路径引用。
全文检索	新建页面无法被顶部搜索框搜出	Git Storage 批量拉取跳过了实时全文分词队列	登录管理员后台，进入 Search Engines，手动执行 Rebuild Index。若使用 PostgreSQL FTS，需确认数据库字符集配置支持中文分词。
Git 覆盖风险	线上编辑的文档被随后的 Git 同步覆盖回退	未开启双向同步，或 Git 仓库发生了非快进（non-fast-forward）强制合并	1. 迁移期间设定为单向导入（Import Only）。 2. 正式投产后切换为双向同步（Bi-directional），并为 Wiki.js 机器人配置独立的 Git 提交凭据。
用户与权限	所有历史文档作者统一变成了系统管理员 Admin	通过 Git 导入时，系统默认将当前执行导入的任务凭据指派为文章作者	如需保留原始作者元数据，需在数据迁移脚本中调用 GraphQL API 结合预创建的用户 UUID 批量写入，或在迁移完成后通过 SQL 脚本映射修复 `creatorId`。

生产环境割接安全原则

在执行正式环境导入前，务必对 Wiki.js 关联的底层数据库（PostgreSQL/MySQL）创建全量快照备份（例如 pg_dump）。一旦在批量拉取过程中发生大规模目录树冲突或路由错位，最快捷且安全的止损方式即为回退数据库快照并清空目标 Git 分支，切勿在生产环境对损坏数据进行手动单篇修复。

五、迁移后验证清单与收尾工作

当数据全量拉取并且全文索引重建完毕后，需依照以下核验清单完成系统收尾验收：

目录树完整性巡检：在 Wiki.js 侧边栏展开导航树，抽检各级子目录，确认层级嵌套深度与源系统保持一致，不存在脱壳孤岛页面。
断链探测排查：编写简单的自动化 HTTP 状态码爬虫（或使用 linkchecker 命令行工具），对站点内所有内嵌 href 和 src 进行扫描，确保无 404、403 异常链接。
特殊排版渲染抽验：重点抽查包含代码块高亮（SQL、Python、Shell）、KaTeX 数学公式、嵌套多行表格以及折叠面板的页面，确认渲染器配置已启用相应模块。
配置定时备份：在 Administration → Storage 中启用日常定时同步或备份到 S3 对象存储，确保迁移成果得到持续可靠的数据保护。