从其他平台迁移数据到 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 按钮。

步骤 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 双向同步冲突以及权限配置。

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

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

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