Confluence Server 连接器
Genly 连接 Confluence Server 中的页面、博客文章、附件、评论、空间、标签、点赞及相关元数据，对页面、博客文章和附件进行解析与索引，并在检索过程中继承原系统权限。
- 当前支持
- Confluence Server 6.5
- 同步机制
- 完整抓取 + Webhook 增量
- 访问边界
- 继承原系统权限
- 数据位置
- 客户私有环境
一、主要功能
- Genly 会抓取 Confluence 页面（包括其父/子层级结构）、博客文章、标签、附件、评论等数据。
- Genly 会遵循所有用户访问权限，确保用户只能看到其有权访问的文档搜索结果。当用户点击搜索结果时，会跳转到 Confluence Web 应用程序，由该应用程序执行权限控制。
- 连接器采用“完整抓取 + Webhook 增量监听 + 权限补偿扫描”的混合同步机制。对于页面、博客、附件、标签、点赞、内容权限、空间权限以及用户/组关系等变更，系统可以在事件触发后进行近实时采集和异步处理；其中内容类变更会继续进入解析和索引流程，最终搜索可见时间取决于解析、入库和索引任务完成情况。评论新增或编辑会作为页面/博客的附属互动数据同步，可在对应内容详情中查看，但评论正文当前不作为独立全文索引对象。已删除且从未被系统同步过的内容无法再从 Confluence 补抓，只能基于历史快照进行清理。
- 所有数据都存储在客户的私有环境中，确保没有数据离开客户环境。
- Genly 使用 Atlassian 的标准 Confluence REST API 来获取所有数据。
- Confluence 6.5 版本没有原生的 Webhook 能力，为了实现近实时的数据同步，Genly 提供自研的 Confluence 插件，通过监听 Confluence 事件来实现 Webhook 能力。
二、支持的版本
- 支持 Confluence Server 6.5 版本。您可以联系您的 Confluence 管理员来获得版本信息。
- Genly 将计划支持 Confluence DataCenter/Cloud 版本。
三、抓取内容与索引范围
Genly Confluence 连接器会抓取三类不同的数据：内容、身份和活动，以确保索引快速、全面且安全可管理。
3.1 内容
- 抓取页面、博客文章、空间、附件、页面评论、标签、点赞数等内容，索引页面、博客文章、附件等内容。
- 页面保留原始层级结构，博客文章以年月生成层级结构，两者均通过标准内容列表 API 抓取。
- 连接器配置的账号信息可以访问到特定的受限页面，则可以为受限页面建立索引，同时在检索结果中仍会执行权限控制。
3.2 活动数据和 Webhook
Genly 会处理创建、更新、删除、移动以及权限变更等事件，以实现快速更新。下面是 Genly 自研插件支持的变更事件。
3.2.1 内容类事件
| 事件 ID | Confluence 事件类 | 说明 |
|---|---|---|
confluence_page_created | PageCreateEvent | 页面创建 |
confluence_page_updated | PageUpdateEvent | 页面更新 |
confluence_page_trashed | PageTrashedEvent | 页面移入回收站 |
confluence_blogpost_created | BlogPostCreateEvent | 博客创建 |
confluence_blogpost_updated | BlogPostUpdateEvent | 博客更新 |
confluence_blogpost_trashed | BlogPostTrashedEvent | 博客移入回收站 |
confluence_attachment_created | AttachmentCreateEvent | 附件创建 |
confluence_attachment_updated | AttachmentUpdateEvent | 附件更新 |
confluence_attachment_removed | AttachmentRemoveEvent | 附件删除 |
confluence_comment_created | CommentCreateEvent | 评论创建 |
confluence_comment_updated | CommentUpdateEvent | 评论更新 |
confluence_comment_removed | CommentRemoveEvent | 评论删除 |
confluence_like_created | LikeCreatedEvent | 点赞创建 |
confluence_like_removed | LikeRemovedEvent | 点赞取消 |
3.2.2 空间、标签与权限事件
| 事件 ID | Confluence 事件类 | 说明 |
|---|---|---|
confluence_space_created | SpaceCreateEvent | 空间创建 |
confluence_space_removed | SpaceRemoveEvent | 空间删除 |
confluence_label_added | LabelAddEvent | 标签添加 |
confluence_label_removed | LabelRemoveEvent | 标签移除 |
confluence_content_permission_changed | ContentPermissionEvent | 内容权限变化 |
confluence_space_permission_saved | SpacePermissionSaveEvent | 空间权限保存 |
confluence_space_permission_removed | SpacePermissionRemoveEvent | 空间权限移除 |
3.2.3 用户、组与成员关系事件
| 事件 ID | 事件类 | 说明 |
|---|---|---|
confluence_user_created | UserCreateEvent / UserCreatedEvent | 用户创建 |
confluence_user_removed | UserRemoveEvent | 用户删除 |
confluence_user_deactivated | UserDeactivateEvent | 用户禁用 |
confluence_user_reactivated | UserReactivateEvent | 用户恢复启用 |
confluence_user_profile_picture_updated | UserProfilePictureUpdateEvent | 用户头像更新 |
confluence_user_renamed | DirectoryUserRenamedEvent | 用户重命名 |
confluence_user_signup | UserSignupEvent | 用户注册 |
crowd_user_email_changed | UserEmailChangedEvent | Crowd 用户邮箱变更 |
crowd_user_edited | UserEditedEvent | Crowd 用户信息编辑 |
confluence_group_created | GroupCreateEvent / GroupCreatedEvent | 组创建 |
confluence_group_removed | GroupRemoveEvent / GroupDeletedEvent | 组删除 |
crowd_group_updated | GroupUpdatedEvent | Crowd 组更新 |
crowd_group_membership_created | GroupMembershipCreatedEvent | 组成员新增 |
crowd_group_membership_deleted | GroupMembershipDeletedEvent | 组成员删除 |
3.3 身份数据
- 抓取 Confluence 中所有用户信息，包括用户名、账户名、邮箱等。
- 针对可能存在的 Confluence 版本太低，Confluence 中的用户信息和身份提供商数据不一致的情况，Genly 管理端还提供了人员信息手动匹配的能力。
四、已知限制
- 评论和点赞数据没有被索引，但是可以通过搜索被评论页面、博客查找相关评论。
- 已删除的页面、博客、附件、空间等无法被抓取。
- 权限被收回后，连接器账号可能无法继续读取受限页面、博客或附件。此时系统可以通过权限事件刷新可见范围，但如果需要重新抓取正文或附件本体，可能会因为账号无权限而失败。
- 对于“删除前发生、但 Webhook 没有送达或连接器任务未运行”的变更，系统只能依赖下一次完整抓取或历史快照发现差异；如果对象在完整抓取前已经被删除，就无法再抓取其内容。
- 用户、组或外部目录对象被删除后，详情接口可能已经查不到完整信息。组织同步会尽量使用事件里的用户名、组名以及历史组织数据做删除或解绑，但无法补齐已消失对象的完整资料。
五、更新频率
| 数据类别 | 抓取频率 | Webhook 增量能力 | 说明 |
|---|---|---|---|
| 身份数据 | 每 12-24 小时一次 | 支持 | 包括用户、组、成员关系。Webhook 可处理用户/组新增删除、成员加入移除；计划抓取用于校准外部目录差异、漏投事件和历史基线。若组织变更频繁或权限依赖强，建议每 12 小时；一般场景每天一次即可。 |
| 内容数据（页面/博客文章/附件/评论/点赞/标签） | 每 24 小时一次（根据实际数据量调整） | 支持 | 包括页面、博客、附件、评论、点赞、标签等。页面、博客、附件的新增、编辑、删除可通过 Webhook 近实时触发；评论、点赞、标签作为页面/博客附属数据，在父内容重拉时刷新。完整抓取用于发现 Webhook 漏投、补齐元数据、校准删除状态。 |
| 空间权限 | 不单独做空间权限完整抓取 | 支持触发空间回填 | 当前系统没有“仅按空间权限维度”的定时完整抓取任务。空间权限变化会通过 Webhook 触发该空间下内容的权限回填，最终仍落到页面/博客等内容级可见范围上；完成时间取决于空间下页面、博客、附件数量以及 Confluence API 响应速度。 |
| 内容权限 | 随文档完整抓取建立快照；权限校准任务每 1-3 小时处理队列 | 支持 | 页面/博客级权限变化可通过 Webhook 触发单篇内容刷新。权限校准任务不是重新枚举所有空间权限或所有内容权限，而是消费文档采集写入的页面级权限扫描队列，对队列中的内容重新拉取权限快照并同步。 |
表中的“Webhook 增量”指的是事件触发后系统开始采集和处理变更，不等于用户立刻能在搜索中看到最终结果。对于内容类变更，系统还需要完成文件上传、元数据入库、解析和索引流程；最终可搜索时间取决于当前队列积压、文件大小、解析耗时和索引服务处理速度。
六、抓取的工作方式
抓取器遵循传统抓取策略，包括利用 API 以及以下方式获取和更新数据：
- 身份抓取：更新和添加人员数据，包括用户、账号和邮箱信息。
- Webhook：是应用程序发送的消息，用于实时通知 Genly 发生变更；随后 Genly 会启动抓取，或在下一次抓取中获取该变更。
- 内容抓取：全量抓取应用程序的整个已定义范围。
七、所需权限
设置此连接器的用户必须具有管理员权限。所需 Confluence 账号，需要有同步内容的访问权限。
八、设置说明
执行以下步骤，将 Confluence Server 连接到 Genly。
8.1 为 Genly 创建服务账户
- 以管理员身份登录 Confluence。
- 前往用户管理。
- 使用任意名称、邮箱和密码创建用户。
- 点击编辑组。
- 将服务账户添加到 confluence-administrators。
8.2 新建 Confluence 数据源
- 在 Genly 管理端数据源中新建 Confluence 数据源，设置页面中输入服务器的基础 URL。例如，https://confluence.mydomain.com。
- 在用户名和密码中填写 8.1 创建的账号和密码。
- 点击测试连接，测试 Confluence 实例的连通性。
- 点击保存，创建 Confluence 数据源。
8.3 新建 Confluence 身份连接器
- 进入 Genly 管理端人员组织，点击其他应用同步。
- 点击新增人员同步，选择 Confluence，在弹窗中选择 Confluence 数据源实例。
- 点击创建，完成身份连接器的创建。
8.4 安装 Confluence 插件与新建 Confluence 连接器
- 进入 Genly 管理端连接器，点击添加连接器。
- 选择 Confluence，点击下一步，选择 Confluence 数据源实例。
- 在确认连接步骤中，点击【插件】，下载 Confluence 插件。
- 在 Confluence 管理后台进入插件管理页面，上传并安装 Confluence 插件。
- 确认 Atlassian WebHooks Genly Plugin 已安装并启用。
- 在 Genly 管理端点击测试连接，点击下一步，选择 Confluence 中特定的空间或者全部空间进行同步，勾选下方需要同步的内容，如需同步标签，请先在知识标签中创建扁平结构的标签体系。
- 点击下一步，完成 Confluence 连接器的创建。
九、Confluence API 端点
| 用途 | 路径 | 方法 |
|---|---|---|
| 校验 Confluence 连接和认证是否可用 | /rest/api/user/current | GET |
| 获取空间列表，用于完整抓取时枚举同步范围 | /rest/api/space?start={start}&limit={limit} | GET |
| 获取指定空间下的页面列表 | /rest/api/space/{spaceKey}/content/page?start={start}&limit={limit}&expand=body.storage,body.export_view,version,history,space,ancestors | GET |
| 获取指定空间下的博客文章列表 | /rest/api/space/{spaceKey}/content/blogpost?start={start}&limit={limit}&expand=body.storage,body.export_view,version,history,space,ancestors | GET |
| 获取页面/博客详情、正文、版本、历史、空间和祖先节点 | /rest/api/content/{id}?expand=body.storage,body.export_view,version,history,space,ancestors | GET |
| 获取内容操作限制，用于解析页面/博客级查看和编辑权限 | /rest/api/content/{id}/restriction/byOperation | GET |
| 获取内容附件列表，用于附件采集和附件事件富化 | /rest/api/content/{id}/child/attachment?start={start}&limit={limit}&expand=version,history,container,metadata,extensions | GET |
| 下载附件二进制内容 | {downloadUrl}，通常来自附件 _links.download，例如 /download/attachments/... | GET |
| 获取内容标签列表 | /rest/api/content/{id}/label?start={start}&limit={limit} | GET |
| 获取内容评论列表和评论正文 | /rest/api/content/{id}/child/comment?start={start}&limit={limit}&expand=body.storage,version | GET |
| 获取内容点赞列表 | /rest/likes/1.0/content/{id}/likes | GET |
| 使用 CQL 查询全量用户，主用于组织全量同步和匿名权限兜底 | /rest/api/search?cql=type=user&start={start}&limit={limit} | GET |
| 获取单个用户信息，用于 username 到 userKey 的换算 | /rest/api/user?username={username} | GET |
| 获取用户信息，组织流中也会按 key 或 username 查询用户基础资料 | /rest/api/user?key={userKey} 或 /rest/api/user?username={username} | GET |
| 获取用户所属组，用于组织流中补齐用户最新组关系 | /rest/api/user/memberof?key={userKey} 或 /rest/api/user/memberof?username={username} | GET |
| 获取用户邮箱和头像等移动端档案信息 | /rest/mobile/1.0/profile/{username} | GET |
| 获取用户组列表，用于组织全量同步和用户兜底枚举 | /rest/api/group?start={start}&limit={limit} | GET |
| 获取指定用户组成员 | /rest/api/group/{groupName}/member?start={start}&limit={limit} | GET |
| 获取空间权限集合，用于将空间权限展开为内容可见用户 | /rpc/json-rpc/confluenceservice-v2?os_authType=basic，body method 为 getSpacePermissionSets | POST |
| 查询当前已有 Webhook 注册 | /rest/webhooks/1.0/webhook | GET |
| 注册 Webhook 监听器 | /rest/webhooks/1.0/webhook | POST |
| 删除指定 Webhook 监听器 | /rest/webhooks/1.0/webhook/{id} | DELETE |