📚 课程目录第3章 Confluence空间目录规范

3. Confluence空间目录规范

适用场景

新团队首次搭建Confluence知识库，需要统一的空间目录结构。
已有Confluence站点因空间混乱、权限失控、内容检索困难而需要重构。
多部门、多项目并行，需要通过标准化命名和层级避免空间冲突和权限泄露。
需要将Confluence与Jira项目关联，实现“项目-知识库-文档”的自动映射。

前置条件

条件项	说明
Confluence系统管理员权限	至少拥有“Confluence管理员”全局权限，可创建空间、配置权限模板。
团队目录骨架已确定	需与各业务线负责人确认空间分类维度（按部门/项目/产品线/文档类型）。
Jira项目列表就绪	若需双向关联，需取得Jira项目KEY和名称。
权限模板清单	明确每个空间的读者、贡献者、管理员角色及对应的AD组或邮件组。
已有旧空间清单	若迁移，需导出旧空间内容并整理为CSV清单。

操作步骤

制定空间命名规则
采用三段式结构：<分类前缀>-<项目/部门短名>-<文档类型>，例如 PRD-MARKETING-REQ、KB-ENGINEERING-API。
- 前缀：PRD（项目研发）、KB（知识库）、OPS（运维）、HR（人事）、FIN（财务）。
- 短名：统一使用Jira Project Key或部门英文缩写。
- 文档类型：REQ（需求）、DESIGN（设计）、RELEASE（发版）、GUIDE（手册）。
设计空间层级结构
所有空间平级，不设子空间，但通过“页面树 + 全局标签”实现逻辑层级。空间命名中的三部分构成软分类标签。

示例空间目录图（仅文字说明）：
空间列表：
PRD-PROJ-A-REQ　　（项目A需求空间）
PRD-PROJ-A-DESIGN　（项目A设计空间）
KB-ENGINEERING-API　（工程团队API知识库）
OPS-PROD-MONITOR　（生产监控运维空间）
配置权限模板
创建3个全局权限模板：
- 只读模板：所有登录用户可查看，仅管理员可编辑。
- 项目团队模板：项目团队成员可贡献（创建/编辑），管理员为PM+TL。
- 内部公开模板：全员可查看和评论，仅文档所有者可编辑。
在空间创建时直接选择对应模板，避免逐个设置。

批量创建空间

使用Confluence REST API或内置的“从模板创建空间”功能。推荐使用脚本批量创建并关联权限模板。

# 批量创建空间示例（伪代码）
curl -u admin:password -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRD-PROJ-A-REQ",
    "name": "项目A需求空间",
    "description": "项目A所有需求文档",
    "permissionTemplate": "项目团队模板"
  }' \
  "https://confluence.example.com/rest/api/space"

迁移旧空间内容
若存在旧空间，按以下步骤迁移：
1. 导出旧空间为XML/CSV压缩包。
2. 按新命名规则创建目标空间。
3. 利用Confluence“从导入”功能或第三方工具（如Scribe）迁移页面。
4. 更新所有内部链接（使用Confluence“重定向”插件或手动修正）。
验证与发布
定期抽取空间列表，核对命名符合度、权限模板覆盖率、内容完整度。

输入输出物

类型	输入物	输出物
文件	《空间命名规则表.xlsx》《权限模板定义文档》	所有新空间已创建并配置权限
数据	旧空间CSV清单	迁移结果报告（含失败列表）
配置	Jira项目KEY与Confluence空间KEY映射表	Confluence管理员后台中新增的空间记录

责任边界

Confluence系统管理员：负责审批空间命名、创建全局权限模板、执行批量创建和迁移脚本。
部门/项目组长：提交空间需求表，确认空间内页面的初始分类。
文档负责人：负责本空间内页面树的初始搭建，并在空间创建后3个工作日内完成“欢迎页”和“文档目录页”的设立。
QA团队：验收空间命名、权限配置的正确性，确保旧链接可跳转。

记录材料

编号	记录名称	保存位置	保留期限
R1	空间创建审批单	Jira项目“Confluence运营”	项目结束后6个月
R2	权限模板变更日志	Confluence系统管理 → 全局权限	永久
R3	空间迁移操作记录	Confluence审计日志 + 操作员本地日志	1年

异常处理

常见异常及解决措施：

空间KEY冲突：命名规则中前缀+短名应有全局唯一性，若冲突则添加流水号后缀，例如 PRD-PROJ-A-REQ-001。
批量创建REST API返回403：检查API Token权限，确保用户属于“confluence-administrators”组。
旧链接失效：迁移后旧空间保留为只读状态6个月，并在旧空间首页添加重定向链接。
权限模板未覆盖新空间：创建后立即执行“批量权限同步”脚本，每4小时自动扫描未分配模板的空间。

验收标准

所有空间名称严格遵循三段式规则（前缀-短名-类型），且与Jira项目或部门一一对应。
每个空间的权限配置可从Confluence“空间设置 → 权限”中直接看到对应的模板名称。
随机抽查5个空间，其页面树包含至少一个欢迎页和一个目录页。
迁移后，原空间中所有页面的URL在新空间内可通过重定向访问，且页面内容完整。
无孤立空间（无任何页面的空间）残留。
管理员可在任一空间下通过标签 space-category:product 等过滤出同一分类的所有空间。