很多团队的知识库里囤着几百篇从 Confluence 时代攒下来的文档换到 sward 的时候第一反应往往是直接搬文件夹行不行真动起手来才发现根本不是那回事。sward 是一款主打轻量、树形结构和 Markdown 编辑体验的知识库工具而 Confluence 的数据模型、页面树、附件路径、宏块和权限体系和它完全不一样导入不是复制粘贴而是一次翻译。这篇博文我不想泛泛讲概念直接把我把 Confluence 空间完整迁移到 sward 的整个过程拆给你看导出方式怎么选、目录结构怎么映射、图片相对路径怎么修、哪些格式注定要丢、用什么顺序排错最省时间。无论你是几十篇的个人知识库还是上千页的团队空间照着这个思路走能少踩很多坑。1. 迁移场景与方案选型1.1 先搞清楚为什么迁再决定怎么迁迁移前先想明白一件事你换到 sward 是图什么。是嫌 Confluence 太笨重、用 Java 技术栈部署维护成本高还是单纯想要一套以 Markdown 为第一公民、支持 Git 化管理文档的轻量方案这个答案直接决定你要拿走多少数据、丢弃多少数据。如果你是嫌 Confluence 的编辑体验太别扭想在 sward 里继续保留页面层级和富文本排版那导出时就要保留 HTML 结构如果你后续打算把文档放进代码仓库、让团队用 PR 评审文档那迁移目标就是干净的 Markdown 文件排版信息尽量扁平化图片统一放到 assets 目录如果只是想把历史文档归档留底那其实导出 HTML 附件包就够了连 sward 都不用建太多结构。我最开始接手的一个团队空间就是这么个情况Confluence 跑了五年沉淀了 300 多篇页面里面有不少是离职同事留下的半成品文档——标题齐全但内容没写完附件乱挂图片散落在个人目录里。这种历史包袱不能无脑全搬迁移本身就是一次清理机会。先确定哪些空间真正活跃、哪些页面还有人看剩下的归档到单独空间或者干脆不迁。1.2 常见迁移路径横向对比Confluence 导出数据大致有四条路各有各的局限我列个表帮你快速选型迁移方式产出物保留程度适合场景主要坑点空间级 HTML 导出一个 zip内含 index.html 和附件目录页面树、富文本、图片基本保留整体搬迁、页面数量多宏块变成乱码、相对路径需重写单篇页面手动导出每篇一个 HTML 或 PDF单页完整但层级丢失只需要挑几篇重点文档手工量大索引关系全没REST API 拉取JSON 数据可转 Markdown可控性最强可编程处理批量操作、定制迁移脚本需要写代码字段结构要花时间啃XML 空间备份一个超大 XML 文件全量数据但结构难读纯备份、灾难恢复导入 sward 前仍要二次转换大多数团队的主方案是API 拉取转 Markdown 附件批量同步再配合空间 HTML 导出作为兜底。HTML 导出的好处是省事但坏处同样明显Confluence 的宏块比如 {code}, {tip}, {warning}会以特殊标记或占位符的形式出现在正文里在 sward 里不仅不好看还影响全文搜索页面间互相引用的链接会在导入后指向旧地址点进去全是 404。相比之下API 路径虽然前期要做点准备工作但换来的是一份干净、可二次加工的 Markdown 源文件。你之后想批量替换链接、修图片路径、统一标题风格都只对文本做操作就行。这个自由度是 HTML 导出给不了的。1.3 迁移不只是内容搬家还是数据治理说到这儿我想提一个容易被忽略的观点Confluence 到 sward 的迁移本质上是一次数据治理动作而不是简单的文件复制。你平时在数据治理项目里听到的字段映射、模板校验、导入日志、失败回滚这些词放到文档迁移里全都适用。Confluence 里一篇文章包含的信息远不止你看到的标题和正文。它有创建人、修改人、创建时间、修改时间、版本号、标签、父子页面关系、评论、附件、限制浏览权限。sward 的元数据模型不一定全部支持那就要明确数据映射策略哪些字段直接复制哪些字段要合并哪些字段干脆放弃。我建议至少保留来源链接、原始创建日期、责任人这三项迁移后有人翻旧文档时还能追溯到源头知道这篇文章最初是谁写的、为了什么需求写的。这个决策过程最好写成一张映射表团队里每个空间可以对照着讨论。我见过有人迁移后才发现整个团队都靠标签体系组织文档而 sward 里没有对应的标签系统结果几百篇文章变成一棵巨大的目录树找东西全靠记忆。如果你也有类似需求提前规划好目录树和命名规范比迁移完再整理省十倍的力气。2. 迁移前准备Confluence 数据导出的完整拆解2.1 空间级 HTML 导出怎么看附件和路径先讲最基础的在 Confluence 管理后台进入目标空间选择右侧的空间工具 - 导出空间选 HTML 格式系统会把整个空间打包成一个 zip 文件。解压后你会看到这样一个结构export/ ├── index.html ├── pages/ │ ├── 页面A.html │ ├── 子目录/ │ │ └── 页面B.html │ └── ... ├── attachments/ │ ├── 图片.png │ └── ... └── stylesheet.css这个包里 index.html 是一个索引页记录了所有页面的树状关系也就是你空间侧边栏那个页面层级。pages 目录里的 HTML 文件正文中图片引用是相对路径附件链接也是相对路径。理论上只要保持整个 export 目录结构不变在浏览器里打开 index.html整个空间就能离线浏览。但要注意HTML 导出有个绕不开的毛病宏块。比如你在 Confluence 里插入了一个警告信息宏导出 HTML 后它可能会以一段特殊的 div 结构存在类名类似confluence-information-macro。这些渲染后的样式在 sward 里没法识别导入后会留下大块空壳 div 和凌乱的 CSS class。所以 HTML 包适合作为备份或者在浏览器里检索参考不建议直接作为导入源文件。2.2 REST API 拉取页面正文转 Markdown如果你想要干净的 Markdown那就走 API。Confluence 的 REST API 并不复杂核心接口就两个列全部页面GET /rest/api/content?spaceKeySPACEKEYexpandbody.storage,version,metadata.labelslimit25start0取附件列表GET /rest/api/content/{pageId}/child/attachment用 Python 写个脚本拉数据body 字段拿到的就是页面正文的存储格式storage format本质上是 XHTML。拿到之后用 Html2Text 或者 Pandoc 转成 Markdown都能得到八九不离十的结果。这里有个判断要早做是保留 Confluence 的 storage 格式里那些 div 包裹的宏块还是直接丢弃。我的建议是绝大多数 Confluence 宏比如代码块、tips、警告、引用在 sward 里都有对应表达方式转换时可以直接把它映射成 Markdown 的代码块、引用块、警告等语法。但有些业务强相关的宏比如Jira 问题列表或用户信息宏导出后只是一段链接或者空白 div这种就直接舍掉迁移后手动补一个文档链接即可。脚本里我还会顺手把body.storage里的附件引用地址记下来形如/download/attachments/{pageId}/filename.png后续配合附件接口批量下载再在 Markdown 里把路径替换成 sward 的相对路径。这一步不做导入后你看到的全是一地碎图。2.3 XML 空间备份到底有没有用Confluence 也支持把整个空间导出成 XML这个文件里保留了页面正文storage 格式、评论、附件元数据、标签、权限设置设计初衷是同版本 Confluence 之间的灾备恢复。但把它作为 sward 迁移的数据源就特别折腾XML 本身是单文件大文档几百个页面挤在一起结构嵌套很深附件内容一般只记录元数据真正的二进制文件还是另外挂着的。你要从 XML 里把页面正文抽出来再转 Markdown等于先解构一套复杂的序列化格式再去做一遍 HTML 转换工作量翻倍还容易在编码和转义上翻车。所以我的结论很直接XML 备份留作原系统存档就行迁移数据主源应该用 API。只有当你的 Confluence 版本太老、API 不好使的时候才考虑解析 XML而且要写好稳健的解析脚本先把所有正文节点抽出来看一遍再动手转换。2.4 导出过程中的权限与附件完整性检查导出前有个细节容易被忽略附件的下载权限。Confluence 支持对单个附件或页面做限制如果你的账号没有对应权限API 返回的附件列表里根本没有这个文件但页面正文里的图片引用还在这就会导致导入后出现大量找不着的链接。我在迁移时遇到过这种情况排查半天发现是某个旧页面当初用仅限制查看的方式挂了个附件导出账号不是所有者附件在 API 里直接缺失了。解决办法是查看空间权限确保执行导出的账号有空间管理员权限并且把所有页面的限制查看临时移除或者用管理员账号导出。迁移完再在 sward 里按需设置权限即可。另外附件文件名可能会有中文、空格、特殊字符Confluence 的下载链接会对文件名做 URL 编码但 HTML 导出里的文件名可能是原始名两个来源的映射关系要对齐。写脚本时统一用文件名解码后做匹配别拿 URL 编码后的字符串直接拼路径。3. sward 数据导入能力解析3.1 它支持哪几种导入通道sward 的导入通道按我的实践经验来看主要有三条本地 Markdown 批量导入、文件夹结构同步导入、API 导入。每条通道的定位不太一样。本地 Markdown 批量导入适合你手上已经有一批 .md 文件的情况界面操作最简单选中文件夹就能导入。等于你先把 Confluence 的内容整理成本地 Markdown 文件再把整个目录拖进 sward。这种方式的优点是所见即所得目录层级直接对应 sward 的页面层级缺点是图片和附件处理要靠约定你得在 Markdown 里写相对路径把图片放在指定目录再一起导入。文件夹结构同步导入更像是一种基于目录的扫描式导入你在本地看到的文件树就是导入后的页面树。它适合团队里已经有人维护了一批 Markdown 文档仓库想整体进 sward 做协作的情况。但要注意如果本地目录里混着不是文档的杂项文件导入时要么忽略要么会变成附件需要先清理。API 导入则是走 sward 提供的开放接口可以精确控制页面创建、更新、层级移动适合在迁移脚本里调用。它的好处是能保留你想要的元数据比如创建时间和作者信息坏处是需要处理接口的速率限制和字段校验。如果前面 API 拉取 Confluence 数据已经写了 Python 脚本那最后这一步自然也是用它。3.2 目录树映射Confluence 页面层级如何变成 sward 树Confluence 的页面树是一种父页面-子页面的层级而 sward 的知识库目录树本质上也是树理论上可以直接对应。但实际操作中经常出问题Confluence 允许一个页面的层级很深十层八层都会存在但 sward 的目录设计更适合三层到四层以内太深了侧边栏折叠起来非常难找。所以迁移前要给空间做一个层级瘦身动作。我的经验是把四层以上的页面重新规划要么提升为独立顶层分组要么合并成文档里的章节。比如 Confluence 里产品文档-用户手册-高级功能-自定义规则-示例这样的五级结构导入 sward 后可以改为两层顶层用户手册二级页面高级功能自定义规则和示例作为该页面下的小节标题而不是再拆成单独页面。这样做的另一个好处是搜索体验更好。sward 的全文搜索对页面标题的权重很高你一个页面里覆盖多个小主题标题做关键词命中概率更高而深目录树里的页面标题往往很短搜索时容易漏。3.3 字段映射与模板化校验真正的导入不能只把 Markdown 塞进去就完事。我给团队定了一套数据导入校验规则灵感来自数据治理项目里 Excel 模板导入的做法必填字段校验每篇导入的 Markdown 必须有 H1 标题没有标题的页面自动按文件名建但这会导致后期排序混乱不如导入前在脚本里就补全。标签映射Confluence 里的标签如果 sward 不支持就把它转成目录前缀或者文档内标签语法而不是丢掉。附件引用闭环所有 Markdown 里的本地图片路径必须指向实际存在的文件脚本里要做存在性检查不存在的文件要单独生成一个缺失清单而不是静默忽略。空页面过滤历史遗留的空壳页面直接跳过避免导入后产生大量无内容节点。这些校验最好都写在导入脚本里输出一份迁移报告包括导入总数、成功数、失败数、缺失附件数。谁负责迁移、谁负责后续清理一看报告就明白。4. 实战Confluence 数据迁入 sward 的完整流程4.1 第一步导出整理与页面清单建立我的流程从梳理页面清单开始。写一个 Python 脚本调用 Confluence API把空间里所有页面的标题、ID、父页面 ID、版本号、创建时间、更新时间、作者信息拉下来存成一份 CSV。这份 CSV 就是整个迁移的地图。import requests import csv base_url https://your-confluence.example.com space_key DEV auth (admin, your-api-token) page_list [] start 0 limit 25 while True: resp requests.get( f{base_url}/rest/api/content?spaceKey{space_key} fexpandbody.storage,version,metadata.labelslimit{limit}start{start}, authauth, verifyFalse ) data resp.json() for item in data.get(results, []): page_list.append({ id: item[id], title: item[title], parent_id: item[parentId] if parentId in item else , version: item[version][number], created: item[version][when], author: item[version][by][displayName], }) if len(data.get(results, [])) limit: break start limit with open(pages.csv, w, newline, encodingutf-8-sig) as f: writer csv.DictWriter(f, fieldnames[id, title, parent_id, version, created, author]) writer.writeheader() writer.writerows(page_list)这段代码没什么高深逻辑但跑完之后你能看到哪些页面没有父页面也就是顶层页面哪些页面存在孤儿引用父页面 ID 指向已删除的页面。后面建目录树就靠这份 CSV 了。4.2 第二步正文清洗与格式转换拿到页面正文后清洗环节是整个迁移里最花时间的也是最容易翻车的地方。正文清洗我一般分成这几个子步骤第一步转 Markdown。用 Pandoc 或 Python 的html2text把 storage HTML 转成 Markdown。Pandoc 对表格、代码块、列表的还原度更好但你也得检查代码块里的语言标注。Confluence 的 {code:java} 导出后可能变成pre节点Pandoc 不一定能自动带上语言标识需要脚本里根据原始的 macro 信息补上。第二步清理宏块残留。我在脚本里维护一个映射表比如把{info}提示宏转成引用块{code}转成代码块{panel}转成普通引用块。凡是映射表里没有的宏一律删掉外层 div保留内部文本。这一步做完后的 Markdown 看起来干净多了但也需要人工扫一遍重点页面确认没有丢失关键提示信息。第三步处理图片路径。Confluence 的图片引用通常是ac:image ri:attachment ri:filenamearchitecture.png / /ac:image转成 Markdown 之后会变成类似或的东西。你要做的是把附件下载下来统一放到assets/images/目录再把 Markdown 里的引用改为这种 sward 能识别的路径。这里有个细节如果同一个文件名出现在多个页面目录下直接按文件名去重会冲突。我的做法是给文件重命名保留页面 ID 前缀比如12345_architecture.png。虽然文件名丑了点但绝对不重名还能反向定位它原来属于哪个页面。4.3 第三步层级重建与批量导入层级重建我用一个递归函数跑 CSV先建所有顶层页面再递归创建子页面。此处我直接调用 sward 的 APIdef create_sward_page(title, content_md, parent_idNone): payload { title: title, content: content_md, parent_id: parent_id, } # 这里按你实际使用的 sward 接口结构调整字段 resp requests.post(https://your-sward.example.com/api/pages, jsonpayload, headers{Authorization: Bearer YOUR_TOKEN}) if resp.status_code 201: return resp.json()[id] else: log_error(ffailed to create {title}: {resp.text}) return None def build_tree(rows, parent_id): # rows 是以父 ID 分组的页面记录 for row in rows.get(parent_id, []): new_id create_sward_page(row[title], row[md_content], parent_id) if new_id is not None: build_tree(rows, new_id)跑批量导入之前强烈建议先拿一个测试空间试跑 5 到 10 篇页面确认层级、图片、标题三级内容都正常再放全量。直接全量导入一旦层级算法有 bug几百个页面变成一堆无父级的平铺文件收拾起来比导入本身还痛苦。导入过程中我还会持续关注日志哪些页面创建失败、哪些页面标题重复、哪些附件路径找不到。日志文件不只是事后看的也是给团队里其他成员同步进度的工具。4.4 第四步导入后的校验清单导入完成不代表迁移结束我会按一份固定清单逐项巡检随机抽查顶层页面的子页面数量确认层级没有扁平化。检查每个页面里的图片引用点击后图片能否正常显示。全文搜索几个高频关键词确认搜索能命中迁移后正文。把原来的 Confluence 页面打开一份对比排版和表格结构。检查历史版本是否保留。sward 如果不支持多版本那至少把 Confluence 的版本号记录到页面引言区方便追溯内容变更范围。这些校验项我建议整理成一个共享文档分配给不同成员分头检查。如果全是迁移负责人一个人检查很容易因为刚搬完太累而忽略细节之后被团队同学发现缺图反而更尴尬。4.5 细节心得导入时应该保留哪些元信息最后分享一个我个人的习惯每篇导入 sward 的页面底部我会自动追加一个迁移来源小段落。内容格式大致是这样本文迁移自 Confluence 页面《xxx》原文链接https://...最后修改时间2024-06-xx迁移时间2024-08-xx迁移人xxx。这看起来像多此一举但实际价值很大。团队成员以后遇到不清楚的历史文档至少知道它来自哪里、什么时候迁过来的、找谁问细节。而且原文链接保留住后续如果发现导入有偏差还能回去核对原文。个人归档类的知识库可以不加团队协作级别的迁移强烈建议加上。5. 常见问题与排查技巧实录5.1 Markdown 里中文和特殊字符乱码乱码问题在 Windows 环境最常出现因为导出的 CSV 或 Markdown 文件默认编码可能是 GBK而脚本里用 UTF-8 读取标题里的中文直接变成乱码。我的排查思路很简单先用文本编辑器打开源文件看 Meta 信息里的 charset。现象是明明是一个正常的中文标题导入后变成了两个字的乱码那基本确定是编码声明和实际编码不一致。处理办法是统一把所有中间文件用 UTF-8 重新保存Python 脚本读写文件时显式指定encodingutf-8不要依赖系统默认编码。另外 Confluence API 返回的 JSON 本身是 UTF-8问题基本不会出在这但如果你用了html2text这类库要注意它的输出编码参数别让它把字符转义成 HTML 实体。导入前检查 Markdown 原文内容里如果出现amp;、lt;这种实体就要在清洗环节先反转义。5.2 图片和附件大面积显示不出来导入后图片大面积裂开原因九成是路径没对齐。我碰到过三种情况第一种是 Markdown 里写的是绝对路径但附件文件夹里的文件名经过了 URL 编码实际磁盘上的文件名可能是a%20b.png。这种问题最好在下载附件时统一做一次unquote解码再用解码后的文件名匹配 Markdown 里的引用。第二种是附件确实不存在API 返回了 404。这种情况要单独拉一个缺失附件清单逐个确认是不是被物理删除还是导出账号权限不够。权限不够导致的缺失换管理员账号导出即可真被删了那就手动在 sward 里补一个文字说明。第三种是相对路径计算错误。如果你把 Markdown 文件放到 sward 的子目录但图片放在根目录的assets下那图片引用就得写成../assets/images/a.png。我建议统一所有页面从 sward 根路径开始写引用也就是/assets/images/a.png这种绝对形式避免不同层级页面的相对路径换算不一致。5.3 页面层级导入后错乱父页面全丢了这种情况往往不是 API 接口的问题而是你的建树算法有问题。最常见的原因是对顶层页面的判定写错了。Confluence 里如果一个页面没有父页面接口可能直接不返回parentId字段但有时候删除父页面后子页面的parentId会指向一个不存在的 ID。你在 CSV 里看到父页面 ID 为 123但页面列表里没有 123这就是孤儿子节点。我在建树时加了一道防线先按parent_id排序构建一个所有存在的页面 ID 集合递归前先检查子页面的父 ID 是否在这个集合里不在的话就把这个子页面提升为顶层页面同时打一条日志。这样至少保证每个页面都能出现在树上不会莫名其妙丢失。还有一个低级错误是同时开启多个导入进程导致两层页面被并发创建成顶层这种就别用并发老老实实按父节点串行创建。5.4 表格和代码块排版惨不忍睹Confluence 的表格在 HTML 里用一堆class控制宽度、边框、合并单元格。转成 Markdown 后简单表格没有问题但合并单元格和单元格内换行很容易丢。我在导入后抽查了十几个表格页面有几处内容直接挤在一起阅读体验很差。排查后发现是 Html2Text 对td内嵌套ul的转换不彻底把列表压缩成了一段长文本。这种情况没有一劳永逸的通用方案我最后的处理方式是清洗脚本里专门针对表格区域做单独处理遇到td里的ul或ol先把它提取出来转成 Markdown 列表后再放回到表格单元格里。要是表格特别复杂我干脆保留为代码块形式的简单表格而不是强行转成 Markdown 表格。代码块的语言标注是另一个常翻车点。Pandoc 对pre标签不会额外补语言类型所以{code:python}的宏一旦丢失Markdown 里就是一个写满代码但没有语言高亮的代码块。我的映射表会在清洗阶段识别这类宏给代码块补上python标识确保 sward 渲染时命中语法高亮。5.5 导入过程越来越慢甚至超时导出的数据量大、页面数多sward 的 API 如果对单次请求体大小有限制你一次性把整篇长文档塞进去就会超时。尤其是那些带大量图片的 long-form 文章正文 Markdown 可能就有几十 KB加上附件简直是重体力活。我的经验是给每篇长文档的 Markdown 内容做截断校验超过一定大小就分两次调用先创建空页面框架再用更新接口补内容。同时在脚本里加入重试逻辑遇到429限流或5xx服务器错误时等待几秒重试而不是直接抛异常中断。批量任务还有一个小技巧每隔一段时间统计一下成功和失败的数量如果失败率突然升高先停一停看是不是触发了接口限流不然白白浪费后面的请求配额。5.6 链接失效页面间互相引用全变成死链页面间引用在 Confluence 里长这样[看这里](https://old-confluence.example.com/pages/viewpage.action?pageId123456)。导入 sward 后这些链接仍然是旧系统的线上地址打开就会跳回 Confluence。如果你希望迁移后链接仍然可用就要把旧链接里的pageId映射成 sward 的页面 ID。做法不复杂建树函数里保存一份Confluence 页面 ID - sward 页面 ID的映射字典再对正文里的所有链接做一次正则替换。import re def replace_confluence_links(md_content, id_map): def repl(match): page_id match.group(1) if page_id in id_map: return f](/pages/{id_map[page_id]}) return match.group(0) return re.sub(r\]\(.*?pageId(\d)(?:.*?)?\), repl, md_content)但如果你的 Confluence 实例已经下线那链接就只能指向导入时生成的迁移来源段落里的旧地址或者干脆把链接文本保留后缀写原链接已失效可询问文档责任人。这种处理方式对团队比较友好至少不会让成员点一个死链之后默默关掉。6. 迁移之后真正的工作才开始内容搬进了 sward只是换了个游泳池。如果你的团队过去依赖 Confluence 的模板、工作流和权限体系那迁移后要尽快建立对应的协作习惯否则 sward 很快就变成一个大家都不爱打开的新文库。我个人实际经验里最有效的三件事是开一次迁移说明会把目录结构讲清楚定一个文档规范标题层级、图片目录、附件命名都写成文档每个月做一次文档体检把长期没有更新的页面归档减少目录噪音。还有一个小技巧迁移后不要立刻关闭 Confluence保留至少一个月的只读访问期。团队里一旦有人发现 sward 里某篇文档有误还能回到 Confluence 对照原文。这一个月听起来很长但历史文档的价值恰恰体现在这个兜底能力上。我这几次迁移能平稳落地就是靠这个重叠期。最后一个建议所有迁移脚本、映射表、迁移报告都放到 sward 里建一个工程维护空间存起来。下次再有新空间要搬迁或者你换一个知识库工具直接复用这些脚本不用重新踩一遍坑。迁移从来不是一个瞬间动作它更像一套方法论的沉淀跑顺了一次后面就是复制粘贴的事。
很多团队的知识库里囤着几百篇从 Confluence 时代攒下来的文档换到 sward 的时候第一反应往往是直接搬文件夹行不行真动起手来才发现根本不是那回事。sward 是一款主打轻量、树形结构和 Markdown 编辑体验的知识库工具而 Confluence 的数据模型、页面树、附件路径、宏块和权限体系和它完全不一样导入不是复制粘贴而是一次翻译。这篇博文我不想泛泛讲概念直接把我把 Confluence 空间完整迁移到 sward 的整个过程拆给你看导出方式怎么选、目录结构怎么映射、图片相对路径怎么修、哪些格式注定要丢、用什么顺序排错最省时间。无论你是几十篇的个人知识库还是上千页的团队空间照着这个思路走能少踩很多坑。1. 迁移场景与方案选型1.1 先搞清楚为什么迁再决定怎么迁迁移前先想明白一件事你换到 sward 是图什么。是嫌 Confluence 太笨重、用 Java 技术栈部署维护成本高还是单纯想要一套以 Markdown 为第一公民、支持 Git 化管理文档的轻量方案这个答案直接决定你要拿走多少数据、丢弃多少数据。如果你是嫌 Confluence 的编辑体验太别扭想在 sward 里继续保留页面层级和富文本排版那导出时就要保留 HTML 结构如果你后续打算把文档放进代码仓库、让团队用 PR 评审文档那迁移目标就是干净的 Markdown 文件排版信息尽量扁平化图片统一放到 assets 目录如果只是想把历史文档归档留底那其实导出 HTML 附件包就够了连 sward 都不用建太多结构。我最开始接手的一个团队空间就是这么个情况Confluence 跑了五年沉淀了 300 多篇页面里面有不少是离职同事留下的半成品文档——标题齐全但内容没写完附件乱挂图片散落在个人目录里。这种历史包袱不能无脑全搬迁移本身就是一次清理机会。先确定哪些空间真正活跃、哪些页面还有人看剩下的归档到单独空间或者干脆不迁。1.2 常见迁移路径横向对比Confluence 导出数据大致有四条路各有各的局限我列个表帮你快速选型迁移方式产出物保留程度适合场景主要坑点空间级 HTML 导出一个 zip内含 index.html 和附件目录页面树、富文本、图片基本保留整体搬迁、页面数量多宏块变成乱码、相对路径需重写单篇页面手动导出每篇一个 HTML 或 PDF单页完整但层级丢失只需要挑几篇重点文档手工量大索引关系全没REST API 拉取JSON 数据可转 Markdown可控性最强可编程处理批量操作、定制迁移脚本需要写代码字段结构要花时间啃XML 空间备份一个超大 XML 文件全量数据但结构难读纯备份、灾难恢复导入 sward 前仍要二次转换大多数团队的主方案是API 拉取转 Markdown 附件批量同步再配合空间 HTML 导出作为兜底。HTML 导出的好处是省事但坏处同样明显Confluence 的宏块比如 {code}, {tip}, {warning}会以特殊标记或占位符的形式出现在正文里在 sward 里不仅不好看还影响全文搜索页面间互相引用的链接会在导入后指向旧地址点进去全是 404。相比之下API 路径虽然前期要做点准备工作但换来的是一份干净、可二次加工的 Markdown 源文件。你之后想批量替换链接、修图片路径、统一标题风格都只对文本做操作就行。这个自由度是 HTML 导出给不了的。1.3 迁移不只是内容搬家还是数据治理说到这儿我想提一个容易被忽略的观点Confluence 到 sward 的迁移本质上是一次数据治理动作而不是简单的文件复制。你平时在数据治理项目里听到的字段映射、模板校验、导入日志、失败回滚这些词放到文档迁移里全都适用。Confluence 里一篇文章包含的信息远不止你看到的标题和正文。它有创建人、修改人、创建时间、修改时间、版本号、标签、父子页面关系、评论、附件、限制浏览权限。sward 的元数据模型不一定全部支持那就要明确数据映射策略哪些字段直接复制哪些字段要合并哪些字段干脆放弃。我建议至少保留来源链接、原始创建日期、责任人这三项迁移后有人翻旧文档时还能追溯到源头知道这篇文章最初是谁写的、为了什么需求写的。这个决策过程最好写成一张映射表团队里每个空间可以对照着讨论。我见过有人迁移后才发现整个团队都靠标签体系组织文档而 sward 里没有对应的标签系统结果几百篇文章变成一棵巨大的目录树找东西全靠记忆。如果你也有类似需求提前规划好目录树和命名规范比迁移完再整理省十倍的力气。2. 迁移前准备Confluence 数据导出的完整拆解2.1 空间级 HTML 导出怎么看附件和路径先讲最基础的在 Confluence 管理后台进入目标空间选择右侧的空间工具 - 导出空间选 HTML 格式系统会把整个空间打包成一个 zip 文件。解压后你会看到这样一个结构export/ ├── index.html ├── pages/ │ ├── 页面A.html │ ├── 子目录/ │ │ └── 页面B.html │ └── ... ├── attachments/ │ ├── 图片.png │ └── ... └── stylesheet.css这个包里 index.html 是一个索引页记录了所有页面的树状关系也就是你空间侧边栏那个页面层级。pages 目录里的 HTML 文件正文中图片引用是相对路径附件链接也是相对路径。理论上只要保持整个 export 目录结构不变在浏览器里打开 index.html整个空间就能离线浏览。但要注意HTML 导出有个绕不开的毛病宏块。比如你在 Confluence 里插入了一个警告信息宏导出 HTML 后它可能会以一段特殊的 div 结构存在类名类似confluence-information-macro。这些渲染后的样式在 sward 里没法识别导入后会留下大块空壳 div 和凌乱的 CSS class。所以 HTML 包适合作为备份或者在浏览器里检索参考不建议直接作为导入源文件。2.2 REST API 拉取页面正文转 Markdown如果你想要干净的 Markdown那就走 API。Confluence 的 REST API 并不复杂核心接口就两个列全部页面GET /rest/api/content?spaceKeySPACEKEYexpandbody.storage,version,metadata.labelslimit25start0取附件列表GET /rest/api/content/{pageId}/child/attachment用 Python 写个脚本拉数据body 字段拿到的就是页面正文的存储格式storage format本质上是 XHTML。拿到之后用 Html2Text 或者 Pandoc 转成 Markdown都能得到八九不离十的结果。这里有个判断要早做是保留 Confluence 的 storage 格式里那些 div 包裹的宏块还是直接丢弃。我的建议是绝大多数 Confluence 宏比如代码块、tips、警告、引用在 sward 里都有对应表达方式转换时可以直接把它映射成 Markdown 的代码块、引用块、警告等语法。但有些业务强相关的宏比如Jira 问题列表或用户信息宏导出后只是一段链接或者空白 div这种就直接舍掉迁移后手动补一个文档链接即可。脚本里我还会顺手把body.storage里的附件引用地址记下来形如/download/attachments/{pageId}/filename.png后续配合附件接口批量下载再在 Markdown 里把路径替换成 sward 的相对路径。这一步不做导入后你看到的全是一地碎图。2.3 XML 空间备份到底有没有用Confluence 也支持把整个空间导出成 XML这个文件里保留了页面正文storage 格式、评论、附件元数据、标签、权限设置设计初衷是同版本 Confluence 之间的灾备恢复。但把它作为 sward 迁移的数据源就特别折腾XML 本身是单文件大文档几百个页面挤在一起结构嵌套很深附件内容一般只记录元数据真正的二进制文件还是另外挂着的。你要从 XML 里把页面正文抽出来再转 Markdown等于先解构一套复杂的序列化格式再去做一遍 HTML 转换工作量翻倍还容易在编码和转义上翻车。所以我的结论很直接XML 备份留作原系统存档就行迁移数据主源应该用 API。只有当你的 Confluence 版本太老、API 不好使的时候才考虑解析 XML而且要写好稳健的解析脚本先把所有正文节点抽出来看一遍再动手转换。2.4 导出过程中的权限与附件完整性检查导出前有个细节容易被忽略附件的下载权限。Confluence 支持对单个附件或页面做限制如果你的账号没有对应权限API 返回的附件列表里根本没有这个文件但页面正文里的图片引用还在这就会导致导入后出现大量找不着的链接。我在迁移时遇到过这种情况排查半天发现是某个旧页面当初用仅限制查看的方式挂了个附件导出账号不是所有者附件在 API 里直接缺失了。解决办法是查看空间权限确保执行导出的账号有空间管理员权限并且把所有页面的限制查看临时移除或者用管理员账号导出。迁移完再在 sward 里按需设置权限即可。另外附件文件名可能会有中文、空格、特殊字符Confluence 的下载链接会对文件名做 URL 编码但 HTML 导出里的文件名可能是原始名两个来源的映射关系要对齐。写脚本时统一用文件名解码后做匹配别拿 URL 编码后的字符串直接拼路径。3. sward 数据导入能力解析3.1 它支持哪几种导入通道sward 的导入通道按我的实践经验来看主要有三条本地 Markdown 批量导入、文件夹结构同步导入、API 导入。每条通道的定位不太一样。本地 Markdown 批量导入适合你手上已经有一批 .md 文件的情况界面操作最简单选中文件夹就能导入。等于你先把 Confluence 的内容整理成本地 Markdown 文件再把整个目录拖进 sward。这种方式的优点是所见即所得目录层级直接对应 sward 的页面层级缺点是图片和附件处理要靠约定你得在 Markdown 里写相对路径把图片放在指定目录再一起导入。文件夹结构同步导入更像是一种基于目录的扫描式导入你在本地看到的文件树就是导入后的页面树。它适合团队里已经有人维护了一批 Markdown 文档仓库想整体进 sward 做协作的情况。但要注意如果本地目录里混着不是文档的杂项文件导入时要么忽略要么会变成附件需要先清理。API 导入则是走 sward 提供的开放接口可以精确控制页面创建、更新、层级移动适合在迁移脚本里调用。它的好处是能保留你想要的元数据比如创建时间和作者信息坏处是需要处理接口的速率限制和字段校验。如果前面 API 拉取 Confluence 数据已经写了 Python 脚本那最后这一步自然也是用它。3.2 目录树映射Confluence 页面层级如何变成 sward 树Confluence 的页面树是一种父页面-子页面的层级而 sward 的知识库目录树本质上也是树理论上可以直接对应。但实际操作中经常出问题Confluence 允许一个页面的层级很深十层八层都会存在但 sward 的目录设计更适合三层到四层以内太深了侧边栏折叠起来非常难找。所以迁移前要给空间做一个层级瘦身动作。我的经验是把四层以上的页面重新规划要么提升为独立顶层分组要么合并成文档里的章节。比如 Confluence 里产品文档-用户手册-高级功能-自定义规则-示例这样的五级结构导入 sward 后可以改为两层顶层用户手册二级页面高级功能自定义规则和示例作为该页面下的小节标题而不是再拆成单独页面。这样做的另一个好处是搜索体验更好。sward 的全文搜索对页面标题的权重很高你一个页面里覆盖多个小主题标题做关键词命中概率更高而深目录树里的页面标题往往很短搜索时容易漏。3.3 字段映射与模板化校验真正的导入不能只把 Markdown 塞进去就完事。我给团队定了一套数据导入校验规则灵感来自数据治理项目里 Excel 模板导入的做法必填字段校验每篇导入的 Markdown 必须有 H1 标题没有标题的页面自动按文件名建但这会导致后期排序混乱不如导入前在脚本里就补全。标签映射Confluence 里的标签如果 sward 不支持就把它转成目录前缀或者文档内标签语法而不是丢掉。附件引用闭环所有 Markdown 里的本地图片路径必须指向实际存在的文件脚本里要做存在性检查不存在的文件要单独生成一个缺失清单而不是静默忽略。空页面过滤历史遗留的空壳页面直接跳过避免导入后产生大量无内容节点。这些校验最好都写在导入脚本里输出一份迁移报告包括导入总数、成功数、失败数、缺失附件数。谁负责迁移、谁负责后续清理一看报告就明白。4. 实战Confluence 数据迁入 sward 的完整流程4.1 第一步导出整理与页面清单建立我的流程从梳理页面清单开始。写一个 Python 脚本调用 Confluence API把空间里所有页面的标题、ID、父页面 ID、版本号、创建时间、更新时间、作者信息拉下来存成一份 CSV。这份 CSV 就是整个迁移的地图。import requests import csv base_url https://your-confluence.example.com space_key DEV auth (admin, your-api-token) page_list [] start 0 limit 25 while True: resp requests.get( f{base_url}/rest/api/content?spaceKey{space_key} fexpandbody.storage,version,metadata.labelslimit{limit}start{start}, authauth, verifyFalse ) data resp.json() for item in data.get(results, []): page_list.append({ id: item[id], title: item[title], parent_id: item[parentId] if parentId in item else , version: item[version][number], created: item[version][when], author: item[version][by][displayName], }) if len(data.get(results, [])) limit: break start limit with open(pages.csv, w, newline, encodingutf-8-sig) as f: writer csv.DictWriter(f, fieldnames[id, title, parent_id, version, created, author]) writer.writeheader() writer.writerows(page_list)这段代码没什么高深逻辑但跑完之后你能看到哪些页面没有父页面也就是顶层页面哪些页面存在孤儿引用父页面 ID 指向已删除的页面。后面建目录树就靠这份 CSV 了。4.2 第二步正文清洗与格式转换拿到页面正文后清洗环节是整个迁移里最花时间的也是最容易翻车的地方。正文清洗我一般分成这几个子步骤第一步转 Markdown。用 Pandoc 或 Python 的html2text把 storage HTML 转成 Markdown。Pandoc 对表格、代码块、列表的还原度更好但你也得检查代码块里的语言标注。Confluence 的 {code:java} 导出后可能变成pre节点Pandoc 不一定能自动带上语言标识需要脚本里根据原始的 macro 信息补上。第二步清理宏块残留。我在脚本里维护一个映射表比如把{info}提示宏转成引用块{code}转成代码块{panel}转成普通引用块。凡是映射表里没有的宏一律删掉外层 div保留内部文本。这一步做完后的 Markdown 看起来干净多了但也需要人工扫一遍重点页面确认没有丢失关键提示信息。第三步处理图片路径。Confluence 的图片引用通常是ac:image ri:attachment ri:filenamearchitecture.png / /ac:image转成 Markdown 之后会变成类似或的东西。你要做的是把附件下载下来统一放到assets/images/目录再把 Markdown 里的引用改为这种 sward 能识别的路径。这里有个细节如果同一个文件名出现在多个页面目录下直接按文件名去重会冲突。我的做法是给文件重命名保留页面 ID 前缀比如12345_architecture.png。虽然文件名丑了点但绝对不重名还能反向定位它原来属于哪个页面。4.3 第三步层级重建与批量导入层级重建我用一个递归函数跑 CSV先建所有顶层页面再递归创建子页面。此处我直接调用 sward 的 APIdef create_sward_page(title, content_md, parent_idNone): payload { title: title, content: content_md, parent_id: parent_id, } # 这里按你实际使用的 sward 接口结构调整字段 resp requests.post(https://your-sward.example.com/api/pages, jsonpayload, headers{Authorization: Bearer YOUR_TOKEN}) if resp.status_code 201: return resp.json()[id] else: log_error(ffailed to create {title}: {resp.text}) return None def build_tree(rows, parent_id): # rows 是以父 ID 分组的页面记录 for row in rows.get(parent_id, []): new_id create_sward_page(row[title], row[md_content], parent_id) if new_id is not None: build_tree(rows, new_id)跑批量导入之前强烈建议先拿一个测试空间试跑 5 到 10 篇页面确认层级、图片、标题三级内容都正常再放全量。直接全量导入一旦层级算法有 bug几百个页面变成一堆无父级的平铺文件收拾起来比导入本身还痛苦。导入过程中我还会持续关注日志哪些页面创建失败、哪些页面标题重复、哪些附件路径找不到。日志文件不只是事后看的也是给团队里其他成员同步进度的工具。4.4 第四步导入后的校验清单导入完成不代表迁移结束我会按一份固定清单逐项巡检随机抽查顶层页面的子页面数量确认层级没有扁平化。检查每个页面里的图片引用点击后图片能否正常显示。全文搜索几个高频关键词确认搜索能命中迁移后正文。把原来的 Confluence 页面打开一份对比排版和表格结构。检查历史版本是否保留。sward 如果不支持多版本那至少把 Confluence 的版本号记录到页面引言区方便追溯内容变更范围。这些校验项我建议整理成一个共享文档分配给不同成员分头检查。如果全是迁移负责人一个人检查很容易因为刚搬完太累而忽略细节之后被团队同学发现缺图反而更尴尬。4.5 细节心得导入时应该保留哪些元信息最后分享一个我个人的习惯每篇导入 sward 的页面底部我会自动追加一个迁移来源小段落。内容格式大致是这样本文迁移自 Confluence 页面《xxx》原文链接https://...最后修改时间2024-06-xx迁移时间2024-08-xx迁移人xxx。这看起来像多此一举但实际价值很大。团队成员以后遇到不清楚的历史文档至少知道它来自哪里、什么时候迁过来的、找谁问细节。而且原文链接保留住后续如果发现导入有偏差还能回去核对原文。个人归档类的知识库可以不加团队协作级别的迁移强烈建议加上。5. 常见问题与排查技巧实录5.1 Markdown 里中文和特殊字符乱码乱码问题在 Windows 环境最常出现因为导出的 CSV 或 Markdown 文件默认编码可能是 GBK而脚本里用 UTF-8 读取标题里的中文直接变成乱码。我的排查思路很简单先用文本编辑器打开源文件看 Meta 信息里的 charset。现象是明明是一个正常的中文标题导入后变成了两个字的乱码那基本确定是编码声明和实际编码不一致。处理办法是统一把所有中间文件用 UTF-8 重新保存Python 脚本读写文件时显式指定encodingutf-8不要依赖系统默认编码。另外 Confluence API 返回的 JSON 本身是 UTF-8问题基本不会出在这但如果你用了html2text这类库要注意它的输出编码参数别让它把字符转义成 HTML 实体。导入前检查 Markdown 原文内容里如果出现amp;、lt;这种实体就要在清洗环节先反转义。5.2 图片和附件大面积显示不出来导入后图片大面积裂开原因九成是路径没对齐。我碰到过三种情况第一种是 Markdown 里写的是绝对路径但附件文件夹里的文件名经过了 URL 编码实际磁盘上的文件名可能是a%20b.png。这种问题最好在下载附件时统一做一次unquote解码再用解码后的文件名匹配 Markdown 里的引用。第二种是附件确实不存在API 返回了 404。这种情况要单独拉一个缺失附件清单逐个确认是不是被物理删除还是导出账号权限不够。权限不够导致的缺失换管理员账号导出即可真被删了那就手动在 sward 里补一个文字说明。第三种是相对路径计算错误。如果你把 Markdown 文件放到 sward 的子目录但图片放在根目录的assets下那图片引用就得写成../assets/images/a.png。我建议统一所有页面从 sward 根路径开始写引用也就是/assets/images/a.png这种绝对形式避免不同层级页面的相对路径换算不一致。5.3 页面层级导入后错乱父页面全丢了这种情况往往不是 API 接口的问题而是你的建树算法有问题。最常见的原因是对顶层页面的判定写错了。Confluence 里如果一个页面没有父页面接口可能直接不返回parentId字段但有时候删除父页面后子页面的parentId会指向一个不存在的 ID。你在 CSV 里看到父页面 ID 为 123但页面列表里没有 123这就是孤儿子节点。我在建树时加了一道防线先按parent_id排序构建一个所有存在的页面 ID 集合递归前先检查子页面的父 ID 是否在这个集合里不在的话就把这个子页面提升为顶层页面同时打一条日志。这样至少保证每个页面都能出现在树上不会莫名其妙丢失。还有一个低级错误是同时开启多个导入进程导致两层页面被并发创建成顶层这种就别用并发老老实实按父节点串行创建。5.4 表格和代码块排版惨不忍睹Confluence 的表格在 HTML 里用一堆class控制宽度、边框、合并单元格。转成 Markdown 后简单表格没有问题但合并单元格和单元格内换行很容易丢。我在导入后抽查了十几个表格页面有几处内容直接挤在一起阅读体验很差。排查后发现是 Html2Text 对td内嵌套ul的转换不彻底把列表压缩成了一段长文本。这种情况没有一劳永逸的通用方案我最后的处理方式是清洗脚本里专门针对表格区域做单独处理遇到td里的ul或ol先把它提取出来转成 Markdown 列表后再放回到表格单元格里。要是表格特别复杂我干脆保留为代码块形式的简单表格而不是强行转成 Markdown 表格。代码块的语言标注是另一个常翻车点。Pandoc 对pre标签不会额外补语言类型所以{code:python}的宏一旦丢失Markdown 里就是一个写满代码但没有语言高亮的代码块。我的映射表会在清洗阶段识别这类宏给代码块补上python标识确保 sward 渲染时命中语法高亮。5.5 导入过程越来越慢甚至超时导出的数据量大、页面数多sward 的 API 如果对单次请求体大小有限制你一次性把整篇长文档塞进去就会超时。尤其是那些带大量图片的 long-form 文章正文 Markdown 可能就有几十 KB加上附件简直是重体力活。我的经验是给每篇长文档的 Markdown 内容做截断校验超过一定大小就分两次调用先创建空页面框架再用更新接口补内容。同时在脚本里加入重试逻辑遇到429限流或5xx服务器错误时等待几秒重试而不是直接抛异常中断。批量任务还有一个小技巧每隔一段时间统计一下成功和失败的数量如果失败率突然升高先停一停看是不是触发了接口限流不然白白浪费后面的请求配额。5.6 链接失效页面间互相引用全变成死链页面间引用在 Confluence 里长这样[看这里](https://old-confluence.example.com/pages/viewpage.action?pageId123456)。导入 sward 后这些链接仍然是旧系统的线上地址打开就会跳回 Confluence。如果你希望迁移后链接仍然可用就要把旧链接里的pageId映射成 sward 的页面 ID。做法不复杂建树函数里保存一份Confluence 页面 ID - sward 页面 ID的映射字典再对正文里的所有链接做一次正则替换。import re def replace_confluence_links(md_content, id_map): def repl(match): page_id match.group(1) if page_id in id_map: return f](/pages/{id_map[page_id]}) return match.group(0) return re.sub(r\]\(.*?pageId(\d)(?:.*?)?\), repl, md_content)但如果你的 Confluence 实例已经下线那链接就只能指向导入时生成的迁移来源段落里的旧地址或者干脆把链接文本保留后缀写原链接已失效可询问文档责任人。这种处理方式对团队比较友好至少不会让成员点一个死链之后默默关掉。6. 迁移之后真正的工作才开始内容搬进了 sward只是换了个游泳池。如果你的团队过去依赖 Confluence 的模板、工作流和权限体系那迁移后要尽快建立对应的协作习惯否则 sward 很快就变成一个大家都不爱打开的新文库。我个人实际经验里最有效的三件事是开一次迁移说明会把目录结构讲清楚定一个文档规范标题层级、图片目录、附件命名都写成文档每个月做一次文档体检把长期没有更新的页面归档减少目录噪音。还有一个小技巧迁移后不要立刻关闭 Confluence保留至少一个月的只读访问期。团队里一旦有人发现 sward 里某篇文档有误还能回到 Confluence 对照原文。这一个月听起来很长但历史文档的价值恰恰体现在这个兜底能力上。我这几次迁移能平稳落地就是靠这个重叠期。最后一个建议所有迁移脚本、映射表、迁移报告都放到 sward 里建一个工程维护空间存起来。下次再有新空间要搬迁或者你换一个知识库工具直接复用这些脚本不用重新踩一遍坑。迁移从来不是一个瞬间动作它更像一套方法论的沉淀跑顺了一次后面就是复制粘贴的事。
路由协议验证)
