如果你在一个 Confluence 实例里同时维护着五六个 Space一定遇到过这种体验想搜个发布失败排查记录你知道它一定在知识库里但不知道落在哪个空间于是只能搜一次、点开、发现不是、再换一个空间名继续搜。这事的根因是 Confluence 默认搜索不会主动按你脑子里的空间范围去过滤而 CQLConfluence Query Language恰恰就是用来解决这个问题的。没错这里说的 CQL 是 Confluence 的检索语法不是强化学习里那个保守 Q 学习也不是数字后端跑 DRC 时看的 space 间距纯粹是 Atlassian 知识库的查询语言。今天我把用 CQL 同时指定多个 space 检索这件事讲透从基本语法到优先级陷阱再到可复用的搜索链接和 API 脚本一次说清楚。1. 为什么默认搜索满足不了你多个 Space 检索的真实场景1.1 一个团队五六个 Space 时的典型需求我自己的知识库就是这么乱起来的产品需求放 PRD 空间研发文档放 DEV 空间线上故障复盘放 OPS 空间新人培训和制度流程又单独拉了个 HR 空间后来还因为某个专项项目拆出来一个 PROJ 空间。大家写的时候都很守规矩内容确实都进 Confluence 了但找的时候没人记得住这条笔记当初是在哪个空间写的。于是出现了一个高频动作在全局搜索框里输入关键词点开一条结果发现不在预期空间关掉再换一个空间筛选条件重新搜。遇到关键词又比较通用、命中结果特别多的时候这个动作会重复到让人怀疑人生。真正需要的是这样一句话帮我在这五个空间里把所有标题或正文包含发布失败的页面全部列出来按最近更新时间排一下。1.2 默认搜索和 UI 筛选看起来够用但这些限制很要命肯定有人会说搜索结果页左侧有筛选栏不是可以勾选 Space 吗能勾新版本 Cloud 也确实支持在结果里再按空间过滤。但它是事后过滤有几个问题筛选条件是点出来的没法保存成一段文本换一个关键词重新搜索之前勾选的空间基本就丢了要重新点一遍没法把我要搜哪几个空间这个条件发给同事更没法放进脚本和 API如果团队有二十个空间你在 UI 上一个个勾选点完一轮的心情不会太好。CQL 的价值恰恰在于把筛选条件变成一段可复制、可分享、可自动化的文本。同样是搜发布失败我可以写成(space DEV OR space OPS) AND text ~ 发布失败这段文本放在哪里都能用而且表达得准确空间范围由我控制关键词由我控制谁来执行都一样。1.3 CQL 的入口比你想的多你可能以为 CQL 只能写在某个高级搜索页面里实际上一共有三个常用入口右上角全局搜索框直接输入space DEV这类语句时大部分版本会自动按 CQL 解析搜索页面的高级搜索模式这个是最稳的入口输入完直接语法高亮REST API/rest/api/search?cql...传参适合写脚本、做自动巡检、集成到其他内部工具里。所以我的习惯是临时手工查东西怎么方便怎么来一旦发现某个搜索条件要反复用立刻把它转成 CQL存成书签或写进脚本。后面几个章节全部围绕这个目的展开。2. 核心语法与优先级陷阱别让 AND 和 OR 混在一起翻车2.1 从一个 Space 扩展到多个 Space先看最简单的单空间检索锁死只搜 DEV 空间space DEV如果只想搜这个空间里标题带发布的页面space DEV AND title ~ 发布到这里思路都很直接。扩展到多个空间多数人第一反应是把条件用 AND 连起来比如space DEV AND space OPS这个语句在逻辑上是错误的因为一个页面不可能同时属于两个空间所以它的结果大概率是空。正确的多空间表达是用 OR 把 space 条件并列space DEV OR space OPS到这里是指定多个 Space 检索的最基础写法。注意space字段也可以直接写成space.key但日常使用space就够了。2.2 混用 AND 和 OR 时谁先执行这是我在团队内部分享时几乎每次都要强调的坑。假设你要搜 DEV 和 OPS 两个空间里包含回滚方案的页面第一次上手的人很可能写出space DEV OR space OPS AND text ~ 回滚方案看到这个语句你以为表达的是(space DEV OR space OPS) AND text ~ 回滚方案但 CQL 和大多数查询语言一样AND 的优先级高于 OR。上面那句实际会被解析成space DEV OR (space OPS AND text ~ 回滚方案)后果是什么DEV 空间里所有页面都会被拉出来不管有没有回滚方案这几个字OPS 空间则只有包含关键词的页面能进去。结果一眼看去就像搜到了但又不完全对DEV 空间混进来一堆无关结果非常干扰判断。为什么容易踩这个坑因为人是按自然语序思考的A 和 B 里搜 C读起来很顺但机器是严格按运算符优先级解析的。我自己第一次写多空间 CQL 时也中招过不是在搜索框里试出来的是在 REST API 返回里发现总数莫名巨大排查了半天才意识到是 DEV 空间在裸奔。2.3 括号的正确姿势解决方式很简单把空间条件整体括起来再做关键词叠加(space DEV OR space OPS) AND text ~ 回滚方案这个写法才是在 DEV 和 OPS 两个空间里搜回滚方案的正确语义。括号可以继续嵌套比如标题和正文都可能出现关键词时(space DEV OR space OPS) AND (title ~ 回滚 OR text ~ 回滚方案)再多一层类型限制(space DEV OR space OPS) AND (title ~ 回滚 OR text ~ 回滚方案) AND type page括号不是用来装饰的它是在明确告诉解析器这一坨是一个整体条件。只要你的 CQL 里同时出现多个 OR 和 AND就用括号把空间组、关键词组、类型组分别包起来。宁可多打一对括号也不要赌解析顺序。2.4 IN 语法能不能用很多从 JQL 转过来的人会习惯性写space IN (DEV,OPS)。这个写法我不能说绝对不行在 Cloud 版本和部分较新的数据中心版本上确实能跑通但在老版本 Server 上我亲眼见过它直接报语法错误而且报错信息还比较隐晦。所以我的建议是如果只是自己本地临时用IN可以试试如果这段 CQL 要写进文档、分享给团队、跑在自动化脚本里一律用 OR 展开。space DEV OR space OPS是每个版本都能认的标准写法兼容性最稳。做知识库工具的人最怕的就是在我机器上能跑老老实实用通用语法能省掉很多跨环境问题。3. 从能搜到到搜得准一句话 CQL 的综合配比3.1 用 type 限制内容类型Confluence 里可搜索的内容类型不止页面一种还有博客、评论、附件。如果你只是想找页面不写type page的话可能会混入一堆评论内容。比如有人发了一条评论说这个方案有问题回滚方案见 XX 页你的关键词正好命中这条评论就会排到结果里扰乱判断。加类型限制(space DEV OR space OPS) AND text ~ 发布失败 AND type page如果你想同时搜页面和博客但排除评论和附件可以这样(space DEV OR space OPS) AND text ~ 发布失败 AND (type page OR type blogpost)这个习惯建议从第一天用 CQL 就建立起来。不加类型限制等于把所有未知内容都塞进结果集后续筛选成本更高。3.2 title 和 text标题与正文的检索差异CQL 里最常用的两个文本字段是title和text。它们的区别很直观title ~ 关键词只匹配页面标题text ~ 关键词匹配页面正文内容范围更大title ~ 关键词 OR text ~ 关键词标题和正文都算适合不确定这条笔记写在标题还是正文里的场景。举个例子你想跨多个空间搜应急预案相关的页面如果标题里带应急预案但正文只是顺带提了一句只用text依旧能搜到反过来正文里详述了预案内容但标题是0312 故障记录你用title ~ 应急预案就会漏掉。日常检索我默认写成(space DEV OR space OPS OR space PRD) AND (title ~ 应急预案 OR text ~ 应急预案) AND type page这会比单一字段检索多出很多有价值的结果。另外CQL 的~是模糊/包含匹配多个关键词想表达同时出现时不建议直接写text ~ 发布 失败因为带空格的字符串容易被当作短语匹配处理。稳妥做法是拆成两个条件用 AND 连接(space DEV OR space OPS) AND text ~ 发布 AND text ~ 失败这样语义明确发布和失败必须在正文中同时出现。3.3 排除空间和无效页面指定多个 Space 的正向用法是 OR但有时候反向排除更实用。比如团队有 ARCHIVE 归档空间里面的历史内容已经失去时效性你不想每次搜出来一堆陈年旧账(space DEV OR space OPS OR space PRD) AND text ~ 发布失败 AND space ! ARCHIVE注意这里用!表示不等于。多空间检索时我一般会在 CQL 里同时保留允许空间列表和排除空间列表两个维度。允许列表负责圈定主范围排除列表负责剔除归档空间和临时测试空间双保险。如果还要排除某类内容同样用!... AND type ! comment这个操作符看起来简单但很多人不知道 CQL 里可以直接用不等号做排除以为一定要写NOT。实际上!在大多数版本里都是可用的阅读上也比较直观。3.4 一个可以直接抄的团队检索模板最后给一个综合模板假设你们有 DEV、OPS、PRD 三个常用空间ARCHIVE 和 TMP 需要排除检索条件是标题或正文包含发布失败、且正文还提到回滚的页面(space DEV OR space OPS OR space PRD) AND (title ~ 发布失败 OR text ~ 发布失败) AND text ~ 回滚 AND type page AND space ! ARCHIVE AND space ! TMP实际执行时不需要换行连续写即可。这个模板覆盖了空间限定、字段选择、类型限定、排除列表四个维度已经能满足团队知识库 80% 的跨空间检索需求。我在内部 Wiki 上还放了一张常用字段速查表方便同事直接对着抄字段作用示例space限定空间space DEVtitle匹配标题title ~ 发布text匹配正文text ~ 发布失败type限定类型type pagecreator限定创建人creator zhang.sanparent限定父页面parent 123456label按标签检索label devops4. 踩坑实录引号、特殊字符、权限和链接编码4.1 Space Key 与 Space Name 别混用CQL 的space字段既可以用 Space Key短代码如 DEV、OPS也可以用 Space Name可读名称如研发中心。但这里有个容易被忽视的问题Space Key 是唯一的Space Name 不一定。我就遇到过两个不同部门把空间都命名为项目文档的情况用space 项目文档去搜结果只返回其中一个空间的内容另一个被静默忽略了。排查半天后换成 Space Key问题立刻消失。所以凡是写进 CQL 的 space 条件一律用 Key。你可以在 Confluence 的空间管理后台看到每个空间的 Key通常是一串大写字母或数字。4.2 引号与特殊字符的处理CQL 里的字符串值一般用英文双引号包裹。space DEV这种不带引号的写法在简单场景下也能解析但一旦值里出现空格、冒号、连字符等字符不带引号非常容易报语法错误。我的习惯是所有值都加双引号一致性好不容易出幺蛾子。如果关键词本身包含英文双引号就比较难受了。不同版本对转义的支持不一致有的用\有的直接用单引号还有的直接报错。遇到这种情况我的建议是别和语法死磕换一个不含引号的近义词来搜。你是来找知识的不是来和解析器搏斗的。还有一类特殊字符要注意版本号、路径、IP 地址。比如你要搜v1.2.0或/var/log/nginx先给关键词加双引号再放到~后面。虽然底层分词大多能处理但加上引号至少能避免被解析器误解。4.3 权限不同搜索结果不同这一点在做自动化时尤其重要CQL 的搜索结果强制受查看权限过滤。同一个 CQL管理员搜出来 80 条普通员工可能只有 40 条这是 Confluence 的正常行为不是你的语法写错了。如果你用 REST API 做团队知识巡检建议用一个有各空间查看权限的服务账号去跑而不是拿个人账号。拿个人账号跑出来的结果天然缺了一块报告里还看不出任何异常这才是最坑的地方。4.4 让 CQL 变成可分享链接的 URL 编码CQL 不只能写在搜索框里也能直接拼到 URL 上这样你可以把搜遍三个空间变成一个书签或一条发给同事的链接。但 URL 里的 CQL 必须编码否则括号、等号、引号、空格都会出问题。举个例子原始 CQL(space DEV OR space OPS) AND text ~ 发布失败编码后长这样%28space%3D%22DEV%22ORspace%3D%22OPS%22%29ANDtext~%22%E5%8F%91%E5%B8%83%E5%A4%B1%E8%B4%A5%22把这段拼在搜索地址后面即可。不同版本的搜索路径不太一样Cloud 常见的是/wiki/search?cqlServer 老版本可能是/dosearchsite.action?cql以你实际环境为准。我一般不用手写编码直接用 Python 生成from urllib.parse import quote cql (space DEV OR space OPS) AND text ~ 发布失败 encoded quote(cql, safe~) url fhttps://your-wiki.example.com/wiki/search?cql{encoded} print(url)safe~是让波浪线保留原样其他特殊字符自动编码。这样生成的书签链接直接发给同事就能用。5. 把多 Space 检索固化成团队日常入口5.1 书签与团队手册里的固定搜索入口我认为 CQL 最大的价值不是临时写一条查询而是把查询固化成团队的基础设施。我自己的浏览器书签栏里放着几条高频搜索跨 DEV/OPS/PRD 搜页面、排除归档空间搜历史记录、按标签搜运维相关内容。每次点开就是直达结果不用重新组织语言。团队 Wiki 的欢迎页里也可以放一个常用搜索区块把编码好的链接列出来。这个动作成本很低但收益很明显新人不用再问我应该去哪个空间找 XX 文档点一下链接就是答案。还需要注意维护。Space 的 Key 一般不会变但空间名称、归档状态会变书签链接里的排除列表也要定期检查。我之前有一条链接写了AND space ! TMP后来 TMP 空间彻底删了条件也没意义了但留着也不碍事只是不再发挥过滤作用。5.2 用 REST API 把 CQL 变成自动巡检小脚本如果团队知识库规模大了或者你想定期检查某些关键词是否及时更新REST API 是更合适的姿势。Confluence 提供了搜索接口直接把 CQL 作为参数传进去返回 JSON 结果。下面是一个最小可用的 Python 示例import requests wiki https://your-domain.atlassian.net/wiki api f{wiki}/rest/api/search headers {Authorization: Bearer 你的API_TOKEN} cql (space DEV OR space OPS) AND text ~ 发布失败 AND type page resp requests.get(api, params{cql: cql, limit: 50}, headersheaders) resp.raise_for_status() data resp.json() for item in data.get(results, []): title item.get(title) url item.get(url) or item.get(content, {}).get(_links, {}).get(webui) print(title, url)如果你们的内网环境不支持 Bearer Token也可以用 Basic Auth把 headers 换成HTTPBasicAuth(你的邮箱, API_TOKEN)。Cloud 环境推荐用 API TokenServer 环境可以看版本选择 Personal Access Token 或传统密码认证。拿到结果之后你可以做很多事情统计每个 Space 的知识覆盖情况、检查某个关键词的页面是否都在归档空间里、把结果汇总后丢给内部机器人定时播报。CQL 在这里的角色就是稳定、可重复执行的检索标准。5.3 我的空间拼接习惯长 OR 不要手写最后一个实践经验多空间检索的空间列表别在 CQL 里硬编码成一大坨。如果你有八个空间手写space A OR space B OR ...很容易抄错而且每次增删空间都要改整段字符串。我习惯在脚本里用列表动态拼接spaces [DEV, OPS, PRD, SUPPORT] space_cql ( OR .join(fspace {s} for s in spaces) ) keyword 发布失败 cql f{space_cql} AND text ~ {keyword} AND type page print(cql) # 输出: (space DEV OR space OPS OR space PRD OR space SUPPORT) AND text ~ 发布失败 AND type page以后空间有增删只改spaces这一个列表就行CQL 主体不用动。这个习惯在做自动化报告时尤其重要因为空间列表经常会因为项目立项、团队重组而变动。最后聊点个人习惯。我刚开始用 CQL 时也想一步到位把所有语法背下来后来发现真正高频的就是 space、title、text、type、! 这几个字段加括号能把这几个用溜日常 80% 的跨空间检索问题都能解决。剩下的语法用到再查文档也来得及。还有一件事搜索条件一旦写成 CQL记得定期回来维护空间改名、归档、新建都需要同步更新不然过半年你的书签搜出来的结果可能连你自己都看不懂了。
如果你在一个 Confluence 实例里同时维护着五六个 Space一定遇到过这种体验想搜个发布失败排查记录你知道它一定在知识库里但不知道落在哪个空间于是只能搜一次、点开、发现不是、再换一个空间名继续搜。这事的根因是 Confluence 默认搜索不会主动按你脑子里的空间范围去过滤而 CQLConfluence Query Language恰恰就是用来解决这个问题的。没错这里说的 CQL 是 Confluence 的检索语法不是强化学习里那个保守 Q 学习也不是数字后端跑 DRC 时看的 space 间距纯粹是 Atlassian 知识库的查询语言。今天我把用 CQL 同时指定多个 space 检索这件事讲透从基本语法到优先级陷阱再到可复用的搜索链接和 API 脚本一次说清楚。1. 为什么默认搜索满足不了你多个 Space 检索的真实场景1.1 一个团队五六个 Space 时的典型需求我自己的知识库就是这么乱起来的产品需求放 PRD 空间研发文档放 DEV 空间线上故障复盘放 OPS 空间新人培训和制度流程又单独拉了个 HR 空间后来还因为某个专项项目拆出来一个 PROJ 空间。大家写的时候都很守规矩内容确实都进 Confluence 了但找的时候没人记得住这条笔记当初是在哪个空间写的。于是出现了一个高频动作在全局搜索框里输入关键词点开一条结果发现不在预期空间关掉再换一个空间筛选条件重新搜。遇到关键词又比较通用、命中结果特别多的时候这个动作会重复到让人怀疑人生。真正需要的是这样一句话帮我在这五个空间里把所有标题或正文包含发布失败的页面全部列出来按最近更新时间排一下。1.2 默认搜索和 UI 筛选看起来够用但这些限制很要命肯定有人会说搜索结果页左侧有筛选栏不是可以勾选 Space 吗能勾新版本 Cloud 也确实支持在结果里再按空间过滤。但它是事后过滤有几个问题筛选条件是点出来的没法保存成一段文本换一个关键词重新搜索之前勾选的空间基本就丢了要重新点一遍没法把我要搜哪几个空间这个条件发给同事更没法放进脚本和 API如果团队有二十个空间你在 UI 上一个个勾选点完一轮的心情不会太好。CQL 的价值恰恰在于把筛选条件变成一段可复制、可分享、可自动化的文本。同样是搜发布失败我可以写成(space DEV OR space OPS) AND text ~ 发布失败这段文本放在哪里都能用而且表达得准确空间范围由我控制关键词由我控制谁来执行都一样。1.3 CQL 的入口比你想的多你可能以为 CQL 只能写在某个高级搜索页面里实际上一共有三个常用入口右上角全局搜索框直接输入space DEV这类语句时大部分版本会自动按 CQL 解析搜索页面的高级搜索模式这个是最稳的入口输入完直接语法高亮REST API/rest/api/search?cql...传参适合写脚本、做自动巡检、集成到其他内部工具里。所以我的习惯是临时手工查东西怎么方便怎么来一旦发现某个搜索条件要反复用立刻把它转成 CQL存成书签或写进脚本。后面几个章节全部围绕这个目的展开。2. 核心语法与优先级陷阱别让 AND 和 OR 混在一起翻车2.1 从一个 Space 扩展到多个 Space先看最简单的单空间检索锁死只搜 DEV 空间space DEV如果只想搜这个空间里标题带发布的页面space DEV AND title ~ 发布到这里思路都很直接。扩展到多个空间多数人第一反应是把条件用 AND 连起来比如space DEV AND space OPS这个语句在逻辑上是错误的因为一个页面不可能同时属于两个空间所以它的结果大概率是空。正确的多空间表达是用 OR 把 space 条件并列space DEV OR space OPS到这里是指定多个 Space 检索的最基础写法。注意space字段也可以直接写成space.key但日常使用space就够了。2.2 混用 AND 和 OR 时谁先执行这是我在团队内部分享时几乎每次都要强调的坑。假设你要搜 DEV 和 OPS 两个空间里包含回滚方案的页面第一次上手的人很可能写出space DEV OR space OPS AND text ~ 回滚方案看到这个语句你以为表达的是(space DEV OR space OPS) AND text ~ 回滚方案但 CQL 和大多数查询语言一样AND 的优先级高于 OR。上面那句实际会被解析成space DEV OR (space OPS AND text ~ 回滚方案)后果是什么DEV 空间里所有页面都会被拉出来不管有没有回滚方案这几个字OPS 空间则只有包含关键词的页面能进去。结果一眼看去就像搜到了但又不完全对DEV 空间混进来一堆无关结果非常干扰判断。为什么容易踩这个坑因为人是按自然语序思考的A 和 B 里搜 C读起来很顺但机器是严格按运算符优先级解析的。我自己第一次写多空间 CQL 时也中招过不是在搜索框里试出来的是在 REST API 返回里发现总数莫名巨大排查了半天才意识到是 DEV 空间在裸奔。2.3 括号的正确姿势解决方式很简单把空间条件整体括起来再做关键词叠加(space DEV OR space OPS) AND text ~ 回滚方案这个写法才是在 DEV 和 OPS 两个空间里搜回滚方案的正确语义。括号可以继续嵌套比如标题和正文都可能出现关键词时(space DEV OR space OPS) AND (title ~ 回滚 OR text ~ 回滚方案)再多一层类型限制(space DEV OR space OPS) AND (title ~ 回滚 OR text ~ 回滚方案) AND type page括号不是用来装饰的它是在明确告诉解析器这一坨是一个整体条件。只要你的 CQL 里同时出现多个 OR 和 AND就用括号把空间组、关键词组、类型组分别包起来。宁可多打一对括号也不要赌解析顺序。2.4 IN 语法能不能用很多从 JQL 转过来的人会习惯性写space IN (DEV,OPS)。这个写法我不能说绝对不行在 Cloud 版本和部分较新的数据中心版本上确实能跑通但在老版本 Server 上我亲眼见过它直接报语法错误而且报错信息还比较隐晦。所以我的建议是如果只是自己本地临时用IN可以试试如果这段 CQL 要写进文档、分享给团队、跑在自动化脚本里一律用 OR 展开。space DEV OR space OPS是每个版本都能认的标准写法兼容性最稳。做知识库工具的人最怕的就是在我机器上能跑老老实实用通用语法能省掉很多跨环境问题。3. 从能搜到到搜得准一句话 CQL 的综合配比3.1 用 type 限制内容类型Confluence 里可搜索的内容类型不止页面一种还有博客、评论、附件。如果你只是想找页面不写type page的话可能会混入一堆评论内容。比如有人发了一条评论说这个方案有问题回滚方案见 XX 页你的关键词正好命中这条评论就会排到结果里扰乱判断。加类型限制(space DEV OR space OPS) AND text ~ 发布失败 AND type page如果你想同时搜页面和博客但排除评论和附件可以这样(space DEV OR space OPS) AND text ~ 发布失败 AND (type page OR type blogpost)这个习惯建议从第一天用 CQL 就建立起来。不加类型限制等于把所有未知内容都塞进结果集后续筛选成本更高。3.2 title 和 text标题与正文的检索差异CQL 里最常用的两个文本字段是title和text。它们的区别很直观title ~ 关键词只匹配页面标题text ~ 关键词匹配页面正文内容范围更大title ~ 关键词 OR text ~ 关键词标题和正文都算适合不确定这条笔记写在标题还是正文里的场景。举个例子你想跨多个空间搜应急预案相关的页面如果标题里带应急预案但正文只是顺带提了一句只用text依旧能搜到反过来正文里详述了预案内容但标题是0312 故障记录你用title ~ 应急预案就会漏掉。日常检索我默认写成(space DEV OR space OPS OR space PRD) AND (title ~ 应急预案 OR text ~ 应急预案) AND type page这会比单一字段检索多出很多有价值的结果。另外CQL 的~是模糊/包含匹配多个关键词想表达同时出现时不建议直接写text ~ 发布 失败因为带空格的字符串容易被当作短语匹配处理。稳妥做法是拆成两个条件用 AND 连接(space DEV OR space OPS) AND text ~ 发布 AND text ~ 失败这样语义明确发布和失败必须在正文中同时出现。3.3 排除空间和无效页面指定多个 Space 的正向用法是 OR但有时候反向排除更实用。比如团队有 ARCHIVE 归档空间里面的历史内容已经失去时效性你不想每次搜出来一堆陈年旧账(space DEV OR space OPS OR space PRD) AND text ~ 发布失败 AND space ! ARCHIVE注意这里用!表示不等于。多空间检索时我一般会在 CQL 里同时保留允许空间列表和排除空间列表两个维度。允许列表负责圈定主范围排除列表负责剔除归档空间和临时测试空间双保险。如果还要排除某类内容同样用!... AND type ! comment这个操作符看起来简单但很多人不知道 CQL 里可以直接用不等号做排除以为一定要写NOT。实际上!在大多数版本里都是可用的阅读上也比较直观。3.4 一个可以直接抄的团队检索模板最后给一个综合模板假设你们有 DEV、OPS、PRD 三个常用空间ARCHIVE 和 TMP 需要排除检索条件是标题或正文包含发布失败、且正文还提到回滚的页面(space DEV OR space OPS OR space PRD) AND (title ~ 发布失败 OR text ~ 发布失败) AND text ~ 回滚 AND type page AND space ! ARCHIVE AND space ! TMP实际执行时不需要换行连续写即可。这个模板覆盖了空间限定、字段选择、类型限定、排除列表四个维度已经能满足团队知识库 80% 的跨空间检索需求。我在内部 Wiki 上还放了一张常用字段速查表方便同事直接对着抄字段作用示例space限定空间space DEVtitle匹配标题title ~ 发布text匹配正文text ~ 发布失败type限定类型type pagecreator限定创建人creator zhang.sanparent限定父页面parent 123456label按标签检索label devops4. 踩坑实录引号、特殊字符、权限和链接编码4.1 Space Key 与 Space Name 别混用CQL 的space字段既可以用 Space Key短代码如 DEV、OPS也可以用 Space Name可读名称如研发中心。但这里有个容易被忽视的问题Space Key 是唯一的Space Name 不一定。我就遇到过两个不同部门把空间都命名为项目文档的情况用space 项目文档去搜结果只返回其中一个空间的内容另一个被静默忽略了。排查半天后换成 Space Key问题立刻消失。所以凡是写进 CQL 的 space 条件一律用 Key。你可以在 Confluence 的空间管理后台看到每个空间的 Key通常是一串大写字母或数字。4.2 引号与特殊字符的处理CQL 里的字符串值一般用英文双引号包裹。space DEV这种不带引号的写法在简单场景下也能解析但一旦值里出现空格、冒号、连字符等字符不带引号非常容易报语法错误。我的习惯是所有值都加双引号一致性好不容易出幺蛾子。如果关键词本身包含英文双引号就比较难受了。不同版本对转义的支持不一致有的用\有的直接用单引号还有的直接报错。遇到这种情况我的建议是别和语法死磕换一个不含引号的近义词来搜。你是来找知识的不是来和解析器搏斗的。还有一类特殊字符要注意版本号、路径、IP 地址。比如你要搜v1.2.0或/var/log/nginx先给关键词加双引号再放到~后面。虽然底层分词大多能处理但加上引号至少能避免被解析器误解。4.3 权限不同搜索结果不同这一点在做自动化时尤其重要CQL 的搜索结果强制受查看权限过滤。同一个 CQL管理员搜出来 80 条普通员工可能只有 40 条这是 Confluence 的正常行为不是你的语法写错了。如果你用 REST API 做团队知识巡检建议用一个有各空间查看权限的服务账号去跑而不是拿个人账号。拿个人账号跑出来的结果天然缺了一块报告里还看不出任何异常这才是最坑的地方。4.4 让 CQL 变成可分享链接的 URL 编码CQL 不只能写在搜索框里也能直接拼到 URL 上这样你可以把搜遍三个空间变成一个书签或一条发给同事的链接。但 URL 里的 CQL 必须编码否则括号、等号、引号、空格都会出问题。举个例子原始 CQL(space DEV OR space OPS) AND text ~ 发布失败编码后长这样%28space%3D%22DEV%22ORspace%3D%22OPS%22%29ANDtext~%22%E5%8F%91%E5%B8%83%E5%A4%B1%E8%B4%A5%22把这段拼在搜索地址后面即可。不同版本的搜索路径不太一样Cloud 常见的是/wiki/search?cqlServer 老版本可能是/dosearchsite.action?cql以你实际环境为准。我一般不用手写编码直接用 Python 生成from urllib.parse import quote cql (space DEV OR space OPS) AND text ~ 发布失败 encoded quote(cql, safe~) url fhttps://your-wiki.example.com/wiki/search?cql{encoded} print(url)safe~是让波浪线保留原样其他特殊字符自动编码。这样生成的书签链接直接发给同事就能用。5. 把多 Space 检索固化成团队日常入口5.1 书签与团队手册里的固定搜索入口我认为 CQL 最大的价值不是临时写一条查询而是把查询固化成团队的基础设施。我自己的浏览器书签栏里放着几条高频搜索跨 DEV/OPS/PRD 搜页面、排除归档空间搜历史记录、按标签搜运维相关内容。每次点开就是直达结果不用重新组织语言。团队 Wiki 的欢迎页里也可以放一个常用搜索区块把编码好的链接列出来。这个动作成本很低但收益很明显新人不用再问我应该去哪个空间找 XX 文档点一下链接就是答案。还需要注意维护。Space 的 Key 一般不会变但空间名称、归档状态会变书签链接里的排除列表也要定期检查。我之前有一条链接写了AND space ! TMP后来 TMP 空间彻底删了条件也没意义了但留着也不碍事只是不再发挥过滤作用。5.2 用 REST API 把 CQL 变成自动巡检小脚本如果团队知识库规模大了或者你想定期检查某些关键词是否及时更新REST API 是更合适的姿势。Confluence 提供了搜索接口直接把 CQL 作为参数传进去返回 JSON 结果。下面是一个最小可用的 Python 示例import requests wiki https://your-domain.atlassian.net/wiki api f{wiki}/rest/api/search headers {Authorization: Bearer 你的API_TOKEN} cql (space DEV OR space OPS) AND text ~ 发布失败 AND type page resp requests.get(api, params{cql: cql, limit: 50}, headersheaders) resp.raise_for_status() data resp.json() for item in data.get(results, []): title item.get(title) url item.get(url) or item.get(content, {}).get(_links, {}).get(webui) print(title, url)如果你们的内网环境不支持 Bearer Token也可以用 Basic Auth把 headers 换成HTTPBasicAuth(你的邮箱, API_TOKEN)。Cloud 环境推荐用 API TokenServer 环境可以看版本选择 Personal Access Token 或传统密码认证。拿到结果之后你可以做很多事情统计每个 Space 的知识覆盖情况、检查某个关键词的页面是否都在归档空间里、把结果汇总后丢给内部机器人定时播报。CQL 在这里的角色就是稳定、可重复执行的检索标准。5.3 我的空间拼接习惯长 OR 不要手写最后一个实践经验多空间检索的空间列表别在 CQL 里硬编码成一大坨。如果你有八个空间手写space A OR space B OR ...很容易抄错而且每次增删空间都要改整段字符串。我习惯在脚本里用列表动态拼接spaces [DEV, OPS, PRD, SUPPORT] space_cql ( OR .join(fspace {s} for s in spaces) ) keyword 发布失败 cql f{space_cql} AND text ~ {keyword} AND type page print(cql) # 输出: (space DEV OR space OPS OR space PRD OR space SUPPORT) AND text ~ 发布失败 AND type page以后空间有增删只改spaces这一个列表就行CQL 主体不用动。这个习惯在做自动化报告时尤其重要因为空间列表经常会因为项目立项、团队重组而变动。最后聊点个人习惯。我刚开始用 CQL 时也想一步到位把所有语法背下来后来发现真正高频的就是 space、title、text、type、! 这几个字段加括号能把这几个用溜日常 80% 的跨空间检索问题都能解决。剩下的语法用到再查文档也来得及。还有一件事搜索条件一旦写成 CQL记得定期回来维护空间改名、归档、新建都需要同步更新不然过半年你的书签搜出来的结果可能连你自己都看不懂了。
