从 Confluence 迁移到 Baklib：baklib-cli + AI 方案

Confluence 的内容量大、文档层级深、相互引用复杂——迁移最大的门槛不是技术，而是如何完整保留文档结构与关联关系。

本文提供一套完整迁移方案，覆盖从 Confluence 导出 → baklib dam upload 附件 → AI 转换 → baklib kb push 创建页面，全部通过 Baklib CLI 操作。

前置准备

安装 baklib-cli

npm install -g @baklib/baklib-cli
baklib --version   # 确认安装成功（需 Node ≥ 20）

安装相关技能

npx skills add baklib-tools/skills --skill baklib-cli
npx skills add baklib-tools/skills --skill baklib-bke-markdown

• baklib-cli：终端管理站点、知识库、DAM 的命令行工具
• baklib-bke-markdown：BKE Markdown 格式规范——Baklib 的正文交换格式，在标准 Markdown 上扩展了 dam-id 引用、文件卡片、链接卡片等语法

配置认证

执行需鉴权的操作前配好 Token：

baklib config set-token "<你的 Open API Token>"
baklib config show   # 确认生效

Token 从 Baklib 控制台获取。也可通过环境变量注入（适用于 CI/脚本）：

export BAKLIB_TOKEN="<your-token>"

第一步：从 Confluence 导出内容

Confluence 提供两种批量导出方式。

方式一：Space 级别 HTML 导出（推荐）

进入 Space tools → Content Tools → Export，选择 HTML 格式。HTML 导出会保留文档标题、层级关系、附件链接和页面顺序。下载 ZIP 包后解压，得到按页面命名的 HTML 文件目录树。

confluence-export/
├── index.html
├── SPACE-Setup-Guide/
│   ├── index.html
│   └── attachments/
│       ├── image001.png
│       └── diagram.pdf
├── Product-Requirements/
│   ├── index.html
│   └── attachments/
│       └── spec-v2.docx
└── Meeting-Notes/
    ├── 2025-Q4-Review.html
    └── 2026-Q1-Planning.html

方式二：REST API 拉取（适合持续同步）

通过 Confluence REST API 逐页面拉取 body.storage，与 HTML 导出结构一致。适合增量同步，但受 Atlasian 速率限制。

耗时参考：200 页的 Space 导出约 3-5 分钟。

第二步：上传附件到 Baklib DAM

用 baklib dam upload 将 Confluence 页面中的图片和附件上传到 Baklib 资源库：

# 单文件上传
baklib dam upload --file-path ./confluence-export/SPACE-Setup-Guide/attachments/image001.png

# 批量上传
for file in ./confluence-export/*/attachments/*; do
  baklib dam upload --file-path "$file"
done

上传成功后 CLI 返回资源的 ID。记录下文件路径与 DAM ID 的映射关系，下一步转换正文时会用到。

第三步：AI 转换 HTML 为 BKE Markdown

这一步由 AI 完成，做两件事。

替换附件引用

将 Confluence HTML 中的附件路径替换为 Baklib DAM 的 dam-id 引用：

<!-- Confluence HTML 原文 -->
<img src="@AX@attachment@image001.png"/>

<!-- 转换为 BKE Markdown -->
![说明文字](dam-id:42)

非图片附件使用文件卡片语法：

[](文件名.pdf "dam-id:43 dam-type:pdf")

结构转换

将 HTML 标题、列表、表格、代码块、Confluence 宏指令转换为 BKE Markdown。BKE 格式参考已安装的 baklib-bke-markdown 技能中的 references/ 目录。

提示词模板：

将 Confluence HTML 转换为 BKE Markdown：
1. 文档标题作为 H1，H2/H3/H4 保留层级
2. {code:lang} → ```lang
3. {panel}/{info} → blockquote
4. 表格保留
5. 图片使用 ![alt](dam-id:N)
6. 附件使用 [](文件名 "dam-id:N dam-type:pdf")
7. 删除 {column}/{section} 等布局宏
8. 内部链接保留标题文本，删除页面 ID

耗时参考：AI 转换 200 页约 40-60 分钟（API 并行处理），附件替换可预先脚本化。

第四步：用 CLI 创建页面

转换完成的 Markdown 文件用 baklib kb push 写入 Baklib 知识库。

kb push 从 Markdown 文件自动创建或更新 KB 文章，frontmatter 中指定目标位置：

---
space_id: <目标知识库 ID>
title: 文章标题
published: true
---

正文内容...

# 单篇推送
baklib kb push --file ./confluence-markdown/setup-guide.md

# 批量推送
for file in ./confluence-markdown/*.md; do
  baklib kb push --file "$file"
done

目录结构保持：Confluence Space 的多级目录通过 frontmatter 中的 parent_id 参数保持层级关系。建议先创建父级页面记录 ID，再批量推送子页面。

对外发布场景：如果内容需要作为帮助中心或文档站对外发布，用 baklib site pages create 写入站点页面：

baklib site pages create --site-id <目标站点 ID> \
  --title "页面标题" \
  --file ./page-content.json

耗时参考：kb push 单篇约 2-3 秒。200 页约 10-15 分钟。

完整流程一览

# 1. 安装 CLI 与技能
npm install -g @baklib/baklib-cli
npx skills add baklib-tools/skills --skill baklib-cli
npx skills add baklib-tools/skills --skill baklib-bke-markdown

# 2. 配置 Token
baklib config set-token "<your-token>"

# 3. 上传附件
for file in ./confluence-export/*/attachments/*; do
  baklib dam upload --file-path "$file"
done

# 4. AI 将 HTML 转换为 BKE Markdown（含 dam-id 替换）
#    （这一步在 AI 对话中完成）

# 5. 批量创建知识库文章
for file in ./confluence-markdown/*.md; do
  baklib kb push --file "$file"
done

迁移时间线

步骤	100 页 Space	500 页 Space
Confluence 导出	5 分钟	15 分钟
附件上传到 DAM	2-3 分钟	5-10 分钟
AI 格式转换	20 分钟	90 分钟
kb push 创建页面	5-10 分钟	15-30 分钟
内容校验修复	1-2 小时	4-6 小时
用户培训切换	1-2 天	3-5 天

常见问题

Q：Confluence 导出不包含评论。需要迁移吗？
A：评论与平台绑定，迁移后无实际价值。建议在 Baklib 中重新开启讨论，或在导出前截屏保存关键评论。

Q：历史版本能保留吗？
A：Confluence 导出仅含最新版本。通过 API 逐版本拉取再重建的工作量不划算，通常不保留。

Q：权限怎么处理？
A：导出 Confluence 的权限配置清单，在 Baklib 中按群组和角色重新分配。Baklib 支持三级权限体系，可映射「只读/编辑/管理员」。

Q：迁移期间内容还在更新怎么办？
A：周五导出全量 → 周末转换导入 → 周一 Confluence 设为只读，Baklib 开始使用。切换日前的增量内容单独导出补入。