OpenCore文档与知识连接器

Jira

以 Markdown 格式查看

索引内容

Jira 连接器会把每个匹配的议题转换为一个可搜索文档。它可以索引凭据可见的全部议题、由项目键指定的单个项目，或自定义 JQL 查询匹配的议题。OpenCore 会为每次索引查询追加自己的 updated 时间窗口。

议题数据索引行为
内容议题描述与评论会合并为一个文本分段。仅当 Jira 返回 comment.author.emailAddress，且它与评论邮箱黑名单条目进行区分大小写的精确匹配时，评论才会被忽略。若未返回邮箱，评论仍会被索引。
元数据与层级在字段可用时保留键、摘要、项目、类型、状态、优先级、解决结果、标签、日期、报告人、经办人与父级。项目与 Epic 会显示为层级节点。
附件此连接器不会获取附件文件或附件中提取的文本。
筛选与限制部署级标签列表可跳过议题。若议题描述与评论合并后的大小超过部署的工单大小限制，该议题会被跳过；当前默认限制为 100 KiB。

请勿在自定义 JQL 中添加 updated 或其他时间条件，也不要添加 ORDER BY 子句。这些表达式会与连接器的轮询和分页逻辑冲突。

前置条件

  • 确认 Jira 站点的 Base URL，例如 Jira Cloud 的 https://<JIRA_SITE>.atlassian.net，或 Jira Server/Data Center 的根 URL。
  • 对于 Jira Cloud，为能够浏览范围内全部项目和议题的用户创建 API token，并准备该用户的邮箱。
  • 对于 Jira Server 或 Data Center，为具备所需浏览权限的用户创建 Personal Access Token。
  • 如果使用有范围限制的 Jira Cloud token，请保留普通站点 Base URL，并在连接器表单中启用 使用 scoped token。OpenCore 会解析站点 Cloud ID，并通过 Atlassian scoped API 主机发送 API 请求。
  • 如果使用自动同步权限，token 还需要访问项目权限方案、项目角色、用户、群组与群组成员。

凭据

Jira 部署OpenCore 凭据值认证行为
Jira Cloudjira_user_email: <JIRA_USER_EMAIL>、jira_api_token: <JIRA_API_TOKEN>存在邮箱字段时，OpenCore 使用邮箱加 token 的 basic authentication，并调用 Jira REST API v3。
使用 scoped token 的 Jira Cloudjira_user_email: <JIRA_USER_EMAIL>、jira_api_token: <JIRA_SCOPED_TOKEN>使用 Cloud 凭据字段，并在连接器上启用使用 scoped token。
Jira Server 或 Data Centerjira_api_token: <JIRA_PERSONAL_ACCESS_TOKEN>将 Jira 用户邮箱留空。OpenCore 会省略该字段，使用 token authentication 并调用 Jira REST API v2。

Base URL 与范围设置属于连接器，而不是凭据。不要把项目 URL 粘贴到 Base URL 字段。

在 OpenCore 中配置

  1. 在管理后台打开连接器，选择 Jira，并为 Jira 部署创建凭据。
  2. 输入 Jira 根 Base URL。OpenCore 会先移除末尾斜杠，再构建 API 与议题链接。
  3. 仅在使用有范围限制的 Jira Cloud token 时启用使用 scoped token。
  4. 在应如何索引您的 Jira？下选择全部、项目或 JQL 查询。选择项目时只填写项目键；选择 JQL 查询时不要加入时间条件或 ORDER BY。
  5. 可以在评论邮箱黑名单中添加评论作者邮箱地址。匹配区分大小写且必须完全相同，并依赖 Jira 返回 comment.author.emailAddress，因此不能作为可靠的隐私边界。索引后应逐一验证目标作者。
  6. 选择文档访问模式，设置刷新与清理选项，创建连接器并运行首次索引。

权限

凭据决定 OpenCore 能获取哪些议题。未使用自动同步权限时，用户搜索时不会重新检查 Jira 访问权限：受限内容应使用 OpenCore 私有群组；仅当所有 OpenCore 账号都可以搜索全部已索引议题时才使用公开。

当部署提供并选择自动同步权限时，OpenCore 会读取每个项目的 BROWSE_PROJECTS 权限方案，并把解析出的项目访问权限应用于该项目的每个议题。它识别 anyone、直接用户与群组，以及项目角色中的 actor。Jira 群组及其成员邮箱会另行同步。

只要 holder map 中存在 applicationRole，applicationRole 当前按 OpenCore 公开处理。OpenCore 不会同步该角色背后的 Jira 许可证成员，因此所有 OpenCore 账号都可能搜索该项目已索引的议题，包括没有 Jira license 的账号。如果此范围过宽，请不要为该连接器使用自动同步；应改用 OpenCore 私有群组，并缩小项目或 JQL 范围。

这是项目级静态权限解析。连接器不会单独评估 issue security level，reporter 或 assignee 等动态 holder 也不会转换为逐议题 ACL。仅包含不支持或动态 holder 的方案可能解析为空的私有访问。依赖同步权限前，应使用有代表性的受限项目进行测试。

验证

  1. 验证凭据。选择全部时会列出项目；选择项目时会打开该项目；使用自定义 JQL 时会执行有限结果的搜索。
  2. 运行一次索引，并搜索范围内某个议题描述与一条评论。
  3. 确认所选项目或自定义 JQL 范围外的议题不存在。
  4. 选择一条 Jira API 响应中包含 comment.author.emailAddress、且邮箱大小写与配置条目相同的目标评论，确认该评论不存在。再测试大小写不匹配或未返回作者邮箱的评论，确认它仍会被索引。同时确认无法搜索仅存在于附件中的文本。
  5. 打开结果链接，确认其使用配置的 Base URL 与 /browse/<ISSUE_KEY>。
  6. 如果使用自动同步权限，请测试 anyone、applicationRole、直接分配、群组分配、项目角色与 issue security 场景。对于 applicationRole，应包含一个没有 Jira license 的 OpenCore 账号，并确认公开映射是否可接受。

故障排除

症状检查项
验证返回 401替换过期或无效的 API token 或 Personal Access Token，并确认 Cloud 邮箱与 token 所有者匹配。
验证返回 403为凭据授予所选项目或 JQL 的浏览权限。权限同步还需要访问权限方案、角色、用户与群组。
项目验证提示项目不存在检查项目键是否精确，并确认凭据能够看到该项目。
自定义 JQL 被拒绝或轮询遗漏议题移除时间条件与 ORDER BY；OpenCore 会追加自己的 updated 范围。
目标评论在配置黑名单后仍存在确认 Jira 返回了 comment.author.emailAddress，并且它与配置值进行区分大小写的精确匹配。邮箱缺失或大小写不同都不会过滤评论；隐私边界应依赖 OpenCore 访问控制与连接器范围，而不是此字段。
议题缺失检查项目或 JQL 范围、部署级标签跳过配置、工单大小限制与议题浏览权限。
附件文本缺失这是预期行为；Jira 连接器不会获取附件。
自动同步访问范围过宽或过窄applicationRole holder 会让项目对所有 OpenCore 账号公开，包括没有 Jira license 的账号。issue security 与动态 holder 不会解析为逐议题 ACL。如果任一映射不合适，应改用私有群组和更窄的连接器范围，而不是自动同步。
验证报告限流等待 Jira 限流窗口恢复，再重新验证或索引。

相关页面