Confluence、语雀与 Notion 团队知识库架构手册
一次离职把知识库的真实结构暴露出来
项目准备发布时，值班工程师搜索“支付回调重试”，找到了三份标题相近的文档：一份在团队目录，一份在前同事的私人页面，一份从旧系统导入后失去了附件。最新结论藏在私人页面里，链接对大多数人返回无权限；页面创建者已经离职，自动化使用的个人 Token 也随账号停用。管理员虽然能看到账号，却不能立刻回答四个问题：哪一份才是事实源，谁能修改，备份能否恢复，旧平台能否退出。
这不是编辑器不好用，而是团队把“能写页面”误当成了“知识可以持续经营”。真正的知识库至少有四层对象：租户或工作区决定身份与安全策略，空间或知识库划分管理边界，页面树表达上下文，页面中的块、附件、数据库和外部链接承载内容。权限、搜索、导出和 API 都沿着这些对象工作；对象建错后，模板越漂亮，重复页面往往越多。
先用一个可删除的试点库承载“支付平台运行手册”，不要直接搬生产文档。试点准备两个测试身份：kb-editor 负责创建和修改，kb-auditor 只读；再准备一个由管理员持有的集成身份。所有示例使用虚构域名、假工单号和无效凭据，例如 sk_test_DO_NOT_USE，绝不能把真实密钥拿来验证搜索或权限。
先把三种对象模型摆在同一张图上
Confluence Cloud 以站点中的 space 作为主要管理容器，页面、live doc、白板、数据库和附件都归入空间。页面可以形成父子树，空间有唯一 key；修改 key 会影响依赖旧 key 的应用和链接。空间 owner 只有一个，但可以指向用户或组，space admin 可以有多个。官方的空间创建说明和内容类型说明应当在建模时一起看，不能只看页面编辑器。
语雀把个人或团队协作放在空间中，以结构化知识库组织文档。对研发团队，空间适合表达组织归属，知识库适合表达产品、平台或稳定责任域，目录再表达读者路径。语雀空间产品页同时列出了知识库、任务和话题等协作入口；建立工程知识库时，应避免把任务状态和长期技术事实混在一棵目录中。
Notion 以 workspace 为租户级容器，teamspace 管理团队区域，page 既是内容也是其他页面的父节点；页面内部由 block 组成，database 与 data source 还会给页面增加结构化属性。teamspace 可以是 open、closed 或 private，页面通常继承上级访问设置，也可以单独调整。官方的teamspace 管理说明、共享与权限说明和开发者文档中的data source 对象分别描述了管理、协作和 API 看到的不同侧面。
三者不能按“都有文件夹和页面”粗暴等同。Confluence 的空间是强管理边界，适合把产品或平台拆成可授权、可导出的区域；语雀的知识库和目录更接近成册的阅读结构；Notion 的页面嵌套与数据库组合更自由，适合把知识、项目和结构化清单放在同一工作区，但自由度也更容易制造权限继承和数据关系上的隐性耦合。
一个稳妥的初始映射如下：
| 治理对象 | Confluence | 语雀 | Notion | 设计影响 |
|---|---|---|---|---|
| 企业身份容器 | Atlassian 组织与站点 | 企业或团队空间 | organization 与 workspace | SSO、成员、域名与安全策略放在这里 |
| 管理责任域 | space | 知识库 | teamspace 或受控顶层 page | owner、默认访问、导出和生命周期以此盘点 |
| 阅读结构 | 页面树 | 目录与文档 | page 与 subpage | 树表达上下文，不代替标签和元数据 |
| 结构化数据 | database 等内容对象 | 数据表等文稿能力按租户实测 | database、data source、page property | 迁移时通常不能无损映射 |
| 自动化入口 | REST API 与应用 | 开发者入口与 Token 能力 | connection、REST API | 只授权目标容器，禁止个人凭据常驻 |
不要按部门无限建空间。稳定责任域比临时项目组更适合作为一级容器，例如“支付平台”“研发效能”“客户交付”。一个跨团队项目可以在这些空间里分别保存运行手册、ADR 和接口说明，再由项目首页聚合链接；项目结束后，稳定知识仍留在真正负责它的空间。
从零启用一个可回收的试点
这三种产品的云版本都不需要在开发机安装服务端。浏览器是最小入口，桌面客户端只改善使用体验，不改变权限和数据归属。Confluence 另有 Data Center 自托管产品；如果法规、网络隔离或数据驻留要求迫使团队自托管，应单独评估基础设施、升级、应用兼容和灾备成本，不能把 Cloud 的操作步骤照搬过去。产品形态变化应从Atlassian Confluence 产品入口、语雀空间入口和Notion 产品入口重新确认。
在 Confluence 建立空间
由组织管理员创建试点站点或在现有站点分配 Confluence 访问，不用个人邮箱创建公司事实源。让具有 Create Space 全局权限的管理员新建 PAY-RUNBOOK-LAB，用途选择知识库或自定义，owner 指向 kb-platform-owners 组。在空间权限中让 kb-platform-editors 可查看和新增内容，让 kb-platform-readers 只能查看；匿名访问保持关闭。
新建“支付平台运行手册”根页面，再创建“服务入口”“回调重试”“故障复盘”三个子页面。由 space admin 创建运行手册模板，加入 service、owner、status、source_repo、review_cycle 等字段或占位说明，并给模板生成的页面统一加标签。
Confluence 的空间权限会对用户、组和其他来源做加法合并。从个人授权中移除编辑权，不代表该用户通过某个组获得的编辑权也消失。空间权限说明明确列出了 View、Add、Delete、Restrictions、Export 和 Admin 等能力；内容限制说明再在页面级收紧查看或编辑。权限定制、访客、安全管理和导出控制是否可用，以目标租户界面和Confluence 定价与能力对比为准。
在语雀建立空间和知识库
由企业管理员创建或接管公司空间，先设置至少两名长期管理员，再邀请 kb-editor 与 kb-auditor。在空间内创建 支付平台运行手册-试点 知识库，归属必须是企业空间，不能放在员工个人空间后再靠分享链接维持。将知识库可见性设为仅指定团队成员，关闭互联网公开；kb-editor 获得可编辑角色，kb-auditor 获得只读角色。
创建“首页”“服务入口”“回调重试”“故障复盘”，在目录中固定顺序，并从首页链接代码仓库、工单系统和告警面板。从模板中心或空间模板能力创建运行手册模板。模板中的 owner 必须是组或岗位，不把员工姓名当作唯一责任人。
语雀的界面、空间版本与企业能力会持续变化。成员角色、单篇分享、模板、导出格式、API Token 和身份管理是否可用，应在目标租户逐项点开验证；语雀定价页用于核对套餐，语雀开发者入口与官方 Node.js SDK用于确认 API 和 Token 入口。官方 SDK 展示了 users、groups、repos、docs 等对象，但不能据此推断所有租户都已开放相同能力。
在 Notion 建立 workspace 与 teamspace
由公司域账号创建 workspace，至少保留两名 workspace owner；需要集中管控时，再接入已核验的域名、SSO 或 SCIM 能力。新建 Payment Platform Lab teamspace。研发共享内容可用 closed；只有特定成员能够发现的敏感区域才考虑 private，并先在目标租户和Notion 定价页确认该访问类型可用。
将 kb-platform-editors 组设为可编辑，将审计组设为只读；禁止把“所有 workspace 成员”误设为 full access。新建运行手册根页面与三个 subpage。再建一个 Runbook Index database，属性使用 Owner、Status、System、Last reviewed、Source URL，每条记录指向一个页面。保存数据库模板，让新页面自动带上章节骨架和属性默认值；用 Status 区分 draft、verified、deprecated，而不是在标题中堆状态前缀。
Notion 会采用用户获得的最宽访问级别。页面对子页面的权限会继承，teamspace 与单页分享又可能叠加。组权限、页面权限和 teamspace 设置要一起检查；组与页面共享说明列出了 Full access、Can edit、Can comment、Can view 等级。private teamspace、集中内容搜索、SCIM、导出禁用和安全控制是否可用，采购前必须在目标租户与Notion 定价页逐项确认。
用同一组正反实验比较权限、模板和搜索
三个试点都创建同样的内容，才有可比较的证据。先在“回调重试”页面写入以下无敏感测试数据：
标题：支付回调重试
Owner：kb-platform-owners
Status：verified
Source URL：https://example.invalid/payments/runbook
唯一检索串：KB-LAB-CANARY-7F3A
错误示例：sk_test_DO_NOT_USE正向实验：该看到的人能找到、能导出
先以 kb-editor 创建页面并套用模板，再以 kb-auditor 登录：
从空间或 teamspace 首页沿目录打开“回调重试”。搜索完整 canary，再搜索“支付 回调 重试”。尝试修改正文，确认只读身份没有编辑入口或提交被拒绝。
导出单页；有空间级导出权限时，再导出整个试点容器。解压导出包，检查标题、正文、附件和内部链接，记录哪些对象被转换或丢失。
预期结果不是“三家按钮都能点”，而是四条不变量同时成立：只读用户能从目录和搜索找到授权页面；不能保存修改；导出包含 canary 和附件；导出后能从首页走到子页面。搜索刚创建的页面可能存在索引延迟，应记录从创建到可检索的时间分布，不要把一次秒级命中写成容量承诺。
Confluence 搜索支持短语和逻辑操作符，但特殊字符处理有自己的语义，查询规则见Confluence 搜索语法。Notion API 的 Search 更适合按页面或 data source 标题找对象，并不保证穷举连接可访问的所有文档，也不保证刚授权后立即出现；官方搜索限制要求对索引延迟保留重试入口。语雀则应在目标空间同时验证标题、正文、目录和权限过滤，保存搜索词、身份和命中页面 URL 作为证据。
反向实验：权限泄漏和隐藏页面必须稳定暴露
先创建 薪酬演练-DO-NOT-PUBLISH 页面，内容仍然只放假数据。把页面限制为 owner 组可见，然后执行四次故障注入：
使用 kb-auditor 直接打开 URL，预期是拒绝访问或页面不可见。使用 kb-auditor 搜索完整标题，预期结果中不出现该页面；若只隐藏正文却泄露标题，也要记为失败。临时把父页面或 teamspace 分享给全员，检查子页面是否因继承而变得可见。
临时创建互联网公开链接，再从无登录浏览器访问；验证后立即关闭公开链接并复测。
Confluence 常见误判来自授权叠加：用户看似已被单独移除，却仍在有 View 权限的组中。Notion 常见误判来自 teamspace、组、页面和父页面中某一路仍提供更宽权限。语雀要特别检查知识库可见性、文档单独分享和空间成员角色是否同时生效。故障证据至少包含测试身份、目标 URL、权限面板截图或导出、搜索结果和最终恢复动作，不能只写“访问失败”。
再做一个敏感信息反例：在页面中加入 sk_test_DO_NOT_USE 后，确认平台搜索能找到它，导出包也包含它。这证明权限系统不是密钥系统，删除页面也不等于凭据轮换。实验结束后删除假值；真实凭据必须放在密钥管理器中，知识库只保存 secret 名称、用途、owner、轮换入口和应急流程。
模板不是排版，而是知识的最小契约
运行手册模板至少需要以下语义字段：
service: payment-callback
owner_group: kb-platform-owners
status: verified
source_repo: https://example.invalid/scm/payment
source_revision: <commit-or-release>
review_trigger: release-or-incident
data_classification: internal
replacement: ""service 决定归属；owner_group 决定谁接收访问请求和过期提醒；status 把草稿、已验证和已废弃内容分开；source_revision 让读者知道页面对应哪次发布；review_trigger 使用事件而非万能日历数字；data_classification 决定能否邀请访客、公开或导出；replacement 让废弃页面指向替代内容。
Confluence 的空间管理员可以创建带变量、占位文本和标签的模板，行为见模板创建说明。Notion 的 database template 更擅长给结构化属性和页面骨架设置默认值。语雀模板要在目标空间验证继承、可见性和更新行为。三者都不应假设“修改模板会自动修复历史页面”；模板版本变更后，应用查询或人工抽查找出旧字段页面，再做显式迁移。
模板还要防止三个坏习惯。第一，不把 owner 写成单个人名；第二，不把“最后更新”当成“内容正确”；第三，不把附件上传成功当成源文件可维护。架构图、OpenAPI、ADR 和配置样例如果原本由 Git 管理，知识库应嵌入构建产物并链接到固定 revision，不能上传一份无人知道来源的副本。
把知识库接入项目，而不是替代代码仓库
仓库继续保存需要评审、构建和版本化的事实，例如 ADR、OpenAPI、AsyncAPI、Mermaid、PlantUML、Structurizr DSL 与运行配置；知识库承担发现、解释、协作和受控发布。一次项目接入可以这样落地：
在仓库的服务清单中保存知识库 canonical URL 和页面 ID，不保存个人分享链接。CI 生成接口文档或架构图后，把固定 revision 的产物发布到受控附件位置，知识库页面引用它。页面写清源码仓库、工单、监控、告警和 ADR 的反向链接。
发布流程只更新机器管理的块或附件，不覆盖人工维护的故障说明。API Token 由 CI 密钥库注入，使用集成身份，并只访问目标空间或页面树。
Confluence Cloud REST API v2 把 page、space、attachment 等作为资源，入口见REST API v2。先用只读请求探测身份和页面，再开放写入：
export CONFLUENCE_BASE_URL='https://<tenant>.atlassian.net/wiki'
export CONFLUENCE_EMAIL='<service-account@example.invalid>'
export CONFLUENCE_API_TOKEN='<inject-from-secret-store>'
export CONFLUENCE_PAGE_ID='<test-page-id>'
curl --fail-with-body --silent --show-error \
--user "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
--header 'Accept: application/json' \
"$CONFLUENCE_BASE_URL/api/v2/pages/$CONFLUENCE_PAGE_ID"预期返回页面 ID、spaceId、title 和 version 等字段。401 指向身份或 Token 错误，403 指向权限不足，404 既可能是 ID 错，也可能是资源没有向调用方暴露。不要为消除 404 直接授予全站访问；先让管理员确认页面所在空间，再检查集成身份是否只被加入目标组。
Notion connection 同时受 capability 和页面分享控制。只给 connection 勾选需要的 Read、Insert 或 Update content 能力，再把运行手册根页面分享给它；connection 获得父页面后才能沿子树访问。API 版本不要写死在脚本里，从Notion API 版本与升级说明选定并在项目变量中固定：
export NOTION_TOKEN='<inject-from-secret-store>'
export NOTION_API_VERSION='<approved-api-version>'
curl --fail-with-body --silent --show-error \
--request POST 'https://api.notion.com/v1/search' \
--header "Authorization: Bearer $NOTION_TOKEN" \
--header "Notion-Version: $NOTION_API_VERSION" \
--header 'Content-Type: application/json' \
--data '{"query":"支付回调重试","page_size":10}'返回 200 但结果为空时，先检查页面是否分享给 connection，再考虑索引延迟；缺少 read capability 通常得到权限错误；查询未分享的 data source 可能表现为 404。这些差异是重要故障证据，不能把所有空结果都解释为“搜索坏了”。connection capabilities给出了最小权限语义。
语雀自动化先做准入探测。进入开发者页面确认目标空间是否提供 Token、目标 API、调用限额和组织授权；再用一个无生产内容的知识库运行官方 SDK 最小读取。SDK 示例中的 Token 页面和对象集合可在官方仓库查看。若开发者入口、Token 或目标对象在租户中不可用，就把自动发布标记为不满足，而不是抓取登录 Cookie 或使用浏览器脚本绕过授权。个人 Token 即使能用，也不能成为长期 CI 凭据。
任何自动化都要保存资源 ID、请求 ID、HTTP 状态、重试次数和最后成功 revision，日志中对 Authorization、Cookie、页面正文和导出下载地址做脱敏。写入使用幂等键或稳定页面 ID，禁止每次构建按标题新建页面；标题可重复，ID 才是可靠引用。
导出成功不等于能够恢复
迁移演练从“可读导出”开始，但终点必须是“在隔离容器中恢复并验收”。三家导出的格式映射不同：页面可能变为 HTML、Markdown、PDF 或 Word，数据库可能变成 CSV，评论、版本历史、宏、嵌入、细粒度权限和自动化通常无法完整落入通用格式。
Confluence 可以导出页面或空间，也可以由管理员创建站点数据备份。站点备份说明明确指出备份用途、附件选项以及用户组设置并非完整复制；部分内容类型也可能不能完整导出。空间 Export 权限尤其敏感，因为空间导出可能包含调用者平时无权查看的内容，授权前要阅读空间权限细节。
Notion 支持页面和 workspace 导出为 HTML、Markdown/CSV 等格式，PDF、子页面和导出控制是否可用要从目标租户确认。导出说明还指出：导出者无权访问的私人页面不会进入包，workspace 导出也不能靠重新上传立即还原成原工作区。导入说明列出了 ZIP、Markdown、HTML、CSV 等映射与文件数量、格式限制。
语雀应在试点知识库的菜单中逐一确认可用导出格式和导出权限，再从定价页复核当前方案。若目标是退出语雀，验收必须包含正文、目录、图片、附件、表格、画板、评论、公式和内部链接；缺少任何关键对象都要设计单独迁移通道。未被官方稳定支持的批量导出，不应依赖抓 Cookie 的第三方扩展承担企业备份。
每次导出后，用独立目录检查包，而不是把 ZIP 直接视为备份：
mkdir -p kb-restore-lab
unzip -q '<export-file>.zip' -d kb-restore-lab
find kb-restore-lab -type f -print | sort > kb-restore-lab/file-list.txt
grep -R -n 'KB-LAB-CANARY-7F3A' kb-restore-lab
grep -R -n -E 'https?://|src=|href=' kb-restore-lab \
> kb-restore-lab/link-and-asset-report.txt预期至少找到 canary，附件出现在包内或有可访问的受控引用，首页链接能指向导出的子页面。grep 找不到 canary 说明正文未导出、格式无法按文本检查或权限导致页面缺失；链接仍指向原租户说明退出后会断；只有 CSV 而没有数据库视图、公式或关系定义，说明迁移只能恢复数据，不能恢复行为。
恢复演练在隔离 workspace 或测试站点进行。抽取高价值页面、深层页面、带附件页面、受限页面和结构化数据库作为样本，重新导入后比较标题、正文哈希、附件数、内部链接、访问矩阵和搜索命中。通用格式恢复通常会产生新页面 ID，所以项目仓库、工单和监控中的反向链接也要纳入迁移清单。
离职回收要先转移责任，再停账号
员工离职时直接停账号，最容易留下私人页面、孤儿 teamspace、个人 Token 和无法处理的访问请求。正确顺序从盘点开始：
查询该用户拥有的空间、知识库、teamspace、顶层页面、模板、集成与公开链接。把业务内容移动到公司容器，owner 转给组或继任者；私人草稿由数据与人事规则决定是否移交。创建新的服务凭据并让自动化切换，验证成功后撤销个人 Token。
从权限组、访客列表、公开分享和外部协作中移除用户。停用或移除账号，再用审计身份复查其旧 URL、搜索结果和自动化任务。
Confluence 支持转移内容 owner，space 或 product admin 也可以处理内容所有权，操作条件见内容 owner 转移说明。受停用账号设置的页面限制可能需要管理员恢复权限。Notion 移除成员后会立即失去 workspace 访问，其 Private 区域页面不会自动变成团队资产；成员、访客和重新加入行为见workspace 身份说明。teamspace 没有 owner 时，workspace owner 应补任 owner。
语雀离职演练必须确认个人空间文档是否已经迁入企业空间、知识库管理员是否至少有两人、个人创建的 Token 是否全部撤销。无法由企业管理员接管的内容不应继续作为生产事实源。每次演练都用继任者账号完成“搜索、编辑、导出、处理访问请求、轮换集成凭据”五个动作，只有账号列表变干净还不算交接成功。
敏感信息要按数据流而不是页面标题治理
“只有内部员工能看”不是敏感数据策略。页面正文、评论、历史版本、附件、搜索索引、通知邮件、导出包、API 响应、第三方应用和 AI 功能都可能复制内容。团队应先给数据分级，再决定允许落入哪些对象：
公开资料可以进入公开空间，但发布动作要有 owner 和复核。内部工程资料可进入公司知识库，默认不允许匿名访问。客户数据、日志样本和工单截图必须先脱敏，附件保留期与正文一致。
密码、私钥、Token、恢复码和生产 Cookie不进入知识库，只保存密钥系统引用。法务、人事和安全事件使用独立受控容器，并验证管理员恢复、导出和审计能力。
外部访客只加入单一协作容器，不加入默认全员组；公开链接设置 owner、用途和复查触发器；集成只获得目标页面树；导出文件写入加密存储并限制下载者。平台提供的 DLP、审计日志、数据驻留、客户管理密钥、AI 数据控制等能力都可能受方案和区域影响，应从各自安全与定价页面逐项核验，不能由产品名称推断。
容量与成本从“活跃席位”扩展到退出代价
采购表只写每席价格，会漏掉真正拖慢团队的成本。至少建立这些计量项：活跃成员与访客数、闲置席位、空间和页面总量、附件字节、导出耗时与失败率、API 调用量和限流、搜索无结果率、受限页面比例、孤儿 owner 数、公开链接数、第三方集成数，以及恢复抽样通过率。
价格、免费额度、存储、访客、SSO、SCIM、审计、搜索管理、导出禁用、API 限额和支持服务都可能变化，不把金额或固定套餐边界写进架构决策。评审时现场打开Confluence 定价页、语雀定价页和Notion 定价页，把实际地区、计费周期、成员数与必需能力代入报价；合同中同时确认数据导出、账号停用、超额、支持和终止后的数据取回方式。
容量测试不需要一开始制造百万页面。先把真实分布做成样本：浅层短页、深层长页、大附件、数据库、受限页和跨空间链接。连续导入多轮后观察搜索延迟、目录可用性、导出时长、失败重试和 API 限流是否随规模恶化。演示阈值只能验证流程，生产阈值要由团队页面增长率、恢复目标和供应商限制共同决定。
选型时看失败模式，而不是编辑器手感
Confluence 更适合已经使用 Atlassian 生态、需要清晰 space 管理、复杂权限、技术文档模板和 Jira 关联的组织。代价是权限来源多、应用生态会增加升级与数据导出复杂度，Cloud 与 Data Center 还形成两套不同的运维和迁移责任。
语雀更适合中文团队、重视成册目录和低学习成本、主要服务国内协作场景的知识沉淀。决策前要在真实企业空间验证身份管理、API、批量导出、审计、数据治理和采购支持；如果自动化与可迁移性是硬要求，这些验证结果应优先于编辑体验。
Notion 更适合希望把文档、数据库和轻量工作流组合起来的团队。页面与 block 模型灵活，数据库模板能快速形成业务索引；相应风险是页面嵌套、关系属性和多路分享容易形成隐性耦合，通用导出也不能重建所有视图、公式、权限和自动化。
供应商锁定可以拆成五种可测成本：内容格式锁定看富文本和块能否转换；身份锁定看成员、组和离职能否批量处理；链接锁定看页面 ID 改变后有多少外部反向链接；自动化锁定看 API、Webhook 和应用是否可替代；治理锁定看审计、DLP、保留和法律导出是否能迁移。每项都必须在试点中留下导出和恢复证据。
如果三者仍然难分胜负，就用同一份运行手册完成权限正反实验、搜索 canary、API 只读探测、全量导出、隔离恢复和离职交接，再比较失败数量与修复成本。能把页面写得漂亮的产品很多，能让知识在人员变化、权限收紧、平台故障和供应商退出后仍然可找、可信、可恢复，才适合成为团队的长期知识基础设施。
试点结束后的清理与回滚
试点不能留下公开链接、测试席位和长期有效 Token。按依赖从外向内清理：先停止 CI 和集成任务，撤销 Token 或 connection，再关闭匿名与外部分享；随后导出最终证据，删除测试页面、数据库、知识库或 teamspace；最后移除测试成员和权限组。保留的只有脱敏后的实验记录、导出清单、能力差异和选型结论。
如果试点已经被真实项目引用，不能直接删除。先把 canonical URL 切换到旧系统或替代平台，扫描仓库和工单中的旧链接，完成冒烟后再归档旧容器。回滚成功的判据是：原有事实源重新可读，编辑入口明确，自动化使用旧凭据体系正常运行，试点域名或页面 ID 不再被生产链路调用。
长期运行时，每个管理容器至少有两个 owner，权限主要授予组，模板字段有版本，公开链接和集成有责任人，导出按事件和风险触发，恢复演练使用隔离环境。这样，搜索不到文档、离职后无人接管、导出后无法恢复就不再是偶发事故，而会在进入生产知识库之前被稳定暴露。