企业内部最重的知识资产往往躺在 Confluence 里——项目文档、运维手册、决策记录，几百上千页，靠标题和标签翻找越来越像大海捞针。Amazon Q Business（下文简称 Q）提供了语义搜索和 Actions 机制，能把 Confluence 从"被动存档"变成"主动回答"。这篇文章走一遍完整接入流程：建知识库、配 Actions、用 Spaces 组织资源，每一步都给出可直接改造的配置。
为什么值得接入
传统 Confluence 搜索依赖关键词匹配，问一句"上季度华东区退款率是多少"，搜不到不是因为内容不存在，而是标题里没写这几个字。Q 的语义检索把自然语言问题映射到文档语义向量，即使原文写的是"Q3 refund ratio — East China region 12.4%"，也能命中。
更关键的是 Actions：Q 不只是检索，还能执行操作——创建页面、更新状态、添加评论，把"查文档"升级为"查+改"。
第一步：在 Q 中创建 Confluence 知识库
进入 AWS Console → Amazon Q Business → 创建应用（Application），然后在应用内添加数据源，选择 Confluence Cloud。
核心配置项：
| 配置项 | 说明 |
|---|---|
| Confluence URL | https://your-org.atlassian.net/wiki |
| Auth 方式 | OAuth 2.0（推荐）或 Personal Access Token |
| 空间筛选 | 可限定只索引特定 Space，避免把 HR 内部文档混进技术检索 |
| 同步频率 | 默认每 24 小时全量同步；增量同步需额外配置 |
用 CLI 创建应用和知识库的示例：
# 1. 创建 Q Business 应用
aws qbusiness create-application \
--region us-east-1 \
--display-name "confluence-kb-app" \
--identity-type IAM_IDC
# 记下返回的 applicationId，后续命令用 APP_ID 替代
# 2. 创建数据源（Confluence Cloud connector）
aws qbusiness create-data-source \
--application-id APP_ID \
--index-id INDEX_ID \
--display-name "confluence-cloud-ds" \
--type "CONFLUENCE_CLOUD" \
--configuration '{"confluenceUrl":"https://your-org.atlassian.net/wiki","authMode":"OAUTH2","spaceKeys":["ENG","OPS"]}'
注意：OAuth 2.0 方式需要在 Atlassian Developer Console 先注册一个 OAuth 客户端，拿到 client ID/secret 后填入 Q 的数据源配置。Personal Access Token 方式更简单但权限范围不可细粒度控制，适合测试环境。
同步启动后，Q 会拉取指定 Space 内所有页面、附件文本和评论，构建语义索引。首次同步耗时取决于文档量，千页级别大约 10-15 分钟。
第二步：配置 Actions——让 Q 能操作 Confluence 页面
Actions 是 Q 的"手脚"。检索只返回答案，Actions 能替你执行后续步骤。
在 Q 应用设置中添加 Custom Action，指向 Confluence REST API。下面是一个 YAML 格式的 Action 定义示例（Q Business 的 Action Schema）：
actions:
- name: createConfluencePage
description: "在指定 Confluence Space 中创建新页面"
parameters:
- name: spaceKey
type: STRING
required: true
description: "目标 Space 的 key，如 ENG"
- name: title
type: STRING
required: true
description: "新页面标题"
- name: content
type: STRING
required: false
description: "页面正文（Confluence storage format XHTML）"
api:
method: POST
url: "https://your-org.atlassian.net/wiki/rest/api/content"
headers:
Authorization: "Bearer {{confluenceToken}}"
Content-Type: "application/json"
body:
type: "page"
title: "{{title}}"
space:
key: "{{spaceKey}}"
body:
storage:
value: "{{content}}"
representation: "storage"
- name: searchConfluencePages
description: "按关键词搜索 Confluence 页面并返回摘要"
parameters:
- name: query
type: STRING
required: true
api:
method: GET
url: "https://your-org.atlassian.net/wiki/rest/api/search?cql=type=page+and+text~\"{{query}}\"&limit=5"
headers:
Authorization: "Bearer {{confluenceToken}}"
配置要点：
confluenceToken需要在 Q 的 Secrets Manager 中存好，Action 执行时动态引用。content字段用 Confluence storage format（一种 XHTML），简单文本可以用<p>{{content}}</p>包裹，复杂格式需要前端转换。- 搜索 Action 用 CQL（Confluence Query Language），
text~是模糊匹配，比精确text=更适合自然语言场景。
实际对话效果示例：
用户：帮我在 ENG 空间创建一个页面，标题写"API 网关迁移计划"，内容写"目标：2024 Q4 前完成 v2 到 v3 的全量切换"
Q：已创建页面 "API 网关迁移计划"（ENG 空间），链接：
https://your-org.atlassian.net/wiki/spaces/ENG/pages/12345
第三步：用 Spaces 组织多源资源
Q 的 Spaces 不是 Confluence 的 Space——它是一个逻辑分组，把不同数据源和 Actions 按业务场景聚合。
典型组织方式：
# 创建一个聚焦运维场景的 Space
aws qbusiness create-space \
--application-id APP_ID \
--display-name "ops-war-room" \
--description "运维告警排查与变更记录"
# 把 Confluence OPS 空间的数据源和查/改 Actions 绑定到这个 Space
aws qbusiness update-space \
--application-id APP_ID \
--space-id SPACE_ID \
--data-source-ids "confluence-ops-ds" \
--action-ids "searchConfluencePages,createConfluencePage"
这样，在 ops-war-room Space 里提问，Q 只检索运维相关文档，只暴露运维相关操作，不会把产品需求文档混进来，也不会误触发财务系统的 Action。
接入检查清单与取舍建议
上线前逐项确认：
| 检查项 | 要点 |
|---|---|
| 权限边界 | OAuth scope 限定只读+写页面，不要给管理员权限；Q 端 IAM policy 限定只访问对应应用 |
| 空间筛选 | 先只接入 1-2 个低敏感度 Space 试跑，确认检索质量后再扩大范围 |
| 同步延迟 | 全量同步有窗口期，刚发布的页面可能 24 小时后才可检索；关键变更可手动触发 start-data-source-sync |
| Action 安全 | 创建/修改类 Action 加审批流程——Q 可以先返回"拟执行操作"，用户确认后再调用 API |
| 成本 | Q Business 按用户数和检索量计费；Actions 调用额外计费，高频自动化场景先算账 |
取舍上，如果团队只用 Confluence 做轻量文档、页数不超过两百，内置搜索够用，接入 Q 的 ROI 不高。页数过千、跨 Space 查询频繁、或者需要"查完就改"的闭环场景，才值得投入这套集成。
整套流程从建知识库到配 Actions 到组织 Spaces，核心思路是：让 Q 读懂你的文档语义，再给它操作文档的手，最后按场景圈定范围防止越界。跑起来之后，最明显的改变不是"搜索变快了"，而是同事不再问"那个文档在哪"，而是直接问"那个问题怎么解决"——Q 把定位文档和提取答案合成了一步。