> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Jira > 为 Jira Cloud 或 Server/Data Center 配置议题索引，并明确内容与权限边界。 ## 索引内容 Jira 连接器会把每个匹配的议题转换为一个可搜索文档。它可以索引凭据可见的全部议题、由项目键指定的单个项目，或自定义 JQL 查询匹配的议题。OpenCore 会为每次索引查询追加自己的 `updated` 时间窗口。 | 议题数据 | 索引行为 | | ------ | ---------------------------------------------------------------------------------------------------------------- | | 内容 | 议题描述与评论会合并为一个文本分段。仅当 Jira 返回 `comment.author.emailAddress`，且它与**评论邮箱黑名单**条目进行区分大小写的精确匹配时，评论才会被忽略。若未返回邮箱，评论仍会被索引。 | | 元数据与层级 | 在字段可用时保留键、摘要、项目、类型、状态、优先级、解决结果、标签、日期、报告人、经办人与父级。项目与 Epic 会显示为层级节点。 | | 附件 | 此连接器不会获取附件文件或附件中提取的文本。 | | 筛选与限制 | 部署级标签列表可跳过议题。若议题描述与评论合并后的大小超过部署的工单大小限制，该议题会被跳过；当前默认限制为 100 KiB。 | 请勿在自定义 JQL 中添加 `updated` 或其他时间条件，也不要添加 `ORDER BY` 子句。这些表达式会与连接器的轮询和分页逻辑冲突。 ## 前置条件 * 确认 Jira 站点的 Base URL，例如 Jira Cloud 的 `https://.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 Cloud | `jira_user_email: `、`jira_api_token: ` | 存在邮箱字段时，OpenCore 使用邮箱加 token 的 basic authentication，并调用 Jira REST API v3。 | | 使用 scoped token 的 Jira Cloud | `jira_user_email: `、`jira_api_token: ` | 使用 Cloud 凭据字段，并在连接器上启用**使用 scoped token**。 | | Jira Server 或 Data Center | `jira_api_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/`。 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 限流窗口恢复，再重新验证或索引。 | ## 相关页面 * [连接器与索引](/opencore/knowledge/connectors) * [索引设置](/opencore/knowledge/index-settings)