知识库

Gitee

以 Markdown 格式查看

Gitee 连接器用于把已批准 Gitee 仓库中的源码文件、Issue 和 Pull Request 纳入艾维斯知识检索。它不是 Gitee 权限同步器；Gitee token 决定艾维斯能抓取什么内容，索引后的搜索可见性由艾维斯连接器访问范围控制。

适用场景

场景建议
代码库问答为单个项目或同一受众的一组仓库创建连接器，并绑定对应 Agent 或文档集。
README 与技术文档检索先启用源码文件，并优先使用默认分支或稳定发布分支。
Issue / PR 决策追溯启用 Issue 和 Pull Request，让 Agent 可以检索需求背景、讨论和处理记录。
私有仓库使用专用 Gitee 私人令牌，并将连接器设置为艾维斯私有群组可见。
多团队仓库按 owner、项目或受众拆分连接器，避免一个 token 和一个连接器覆盖过宽。

当前索引内容

Gitee 连接器以一个仓库所有者和一个或多个仓库名称作为范围。它只索引表单中明确列出的仓库，不会自动发现该 token 可访问的全部仓库。

Gitee 内容索引行为
源码文件启用包含源码文件后，连接器会读取目标分支的递归文件树，并索引可作为文本处理的文件。仓库名称、分支、路径和文件类型会写入元数据。
Issue启用包含 Issue后，连接器会读取所有状态的 Issue，并把标题、正文、评论、状态、作者和标签纳入文档。
Pull Request启用包含 Pull Request后，连接器会读取所有状态的 PR，并把标题、正文、评论、状态和作者纳入文档。当前不会索引 diff、commit、流水线、评审状态或代码变更详情。
仓库层级每个仓库会作为父级目录节点显示，便于在搜索结果中识别来源仓库。

文件索引有内置保护：超过 1 MB 的文件、二进制文件、*.min.js、*.min.css，以及 .git、.venv、__pycache__、build、dist、node_modules、target、vendor 等目录下的文件会被跳过。常见文本源码、配置文件、Markdown、YAML、JSON、SQL、README、LICENSE、Dockerfile、Makefile 等会被纳入候选范围。

当前连接器不索引 Gitee Wiki、Release、里程碑、代码提交、仓库统计、流水线或仓库设置。

前置条件

  • 已确认目标仓库位于 gitee.com。当前连接器固定访问 https://gitee.com/api/v5，不支持自托管 Gitee 主机地址。
  • 已准备一个专用于艾维斯索引的 Gitee 私人令牌。可从 Gitee 私人令牌页面创建。
  • 令牌所属账号可以读取目标仓库、Issue、Pull Request 和目标分支文件。只做索引时，不要授予写入、Hook 或管理员类权限。
  • 已确认仓库所有者和仓库路径。例如 https://gitee.com/openmodels/search 中，仓库所有者是 openmodels，仓库名称是 search。
  • 已规划艾维斯访问范围。只要连接器可见，用户就可能搜索到该连接器索引的全部内容。
  • 网络策略允许艾维斯后端访问 gitee.com。

Gitee 官方帮助中把私人令牌用于仓库 API 或镜像操作时通常要求包含 project 权限。实际权限界面可能随 Gitee 版本变化；请以目标租户中能读取仓库、Issue、PR 和文件 API 为准，并保持最小权限。

配置数据获取入口

配置数据获取方式
Gitee 私人令牌登录 Gitee 后从 私人令牌页面 创建专用 token；权限说明可参考 Gitee 帮助：申请包含 project 权限的私人令牌。
仓库所有者从仓库 URL https://gitee.com/{owner}/{repo} 中取 {owner}，只填写路径片段，不填写完整 URL。
仓库名称从仓库 URL https://gitee.com/{owner}/{repo} 中取 {repo}。需要批量配置时先确认这些仓库属于同一 owner 和同一访问受众。
分支在仓库的分支列表或默认分支设置中确认。留空时连接器使用仓库默认分支。
文件、Issue、Pull Request API 可读性可用 Gitee API v5 文档 验证 token 是否能读取目标仓库、Issue、Pull Request 和文件内容。

创建 Gitee 私人令牌

在 Gitee 个人设置中打开私人令牌，创建一个专用于艾维斯的 token。建议描述中写明用途，例如 aivis-gitee-indexer，并只选择索引所需的仓库读取权限。

创建后只复制一次令牌，并直接保存到艾维斯凭据。不要把真实令牌写入文档、截图、工单、聊天记录、Agent 指令或代码仓库。

在艾维斯中配置

在管理后台打开连接器，选择 Gitee。先创建或选择 Gitee 凭据，再填写仓库范围和内容类型。

字段填写方式说明
Gitee 私人令牌粘贴专用 token用于访问 Gitee API。保存后通常不会明文展示。
连接器名称例如 研发知识库用于管理员识别连接器和日志。
仓库所有者例如 openmodels只能填写 owner 路径片段，不要填写完整 URL。
Gitee 仓库例如 search、web-ui只填写仓库名称。最多 100 个，不能重复。
分支例如 main、master、release/v1留空时使用每个仓库的默认分支。
包含源码文件默认开启读取目标分支的可索引文本文件。
包含 Issue默认开启读取所有状态 Issue 的正文与评论。
包含 Pull Request默认开启读取所有状态 PR 的正文与评论，不读取 diff。

至少需要开启一种内容类型。仓库所有者和仓库名称只能使用安全路径片段：字母、数字、点、下划线和短横线，且不能以空字符、斜杠或完整 URL 形式填写。

同步行为

标准管理后台创建的 Gitee 连接器使用轮询索引，并支持 checkpoint 续跑。一个同步 pass 会按仓库顺序处理，每个仓库再按已启用内容类型依次处理：文件、Issue、Pull Request。

阶段同步细节
文件解析配置分支；分支为空时使用仓库默认分支。连接器会冻结该分支当前 commit 的文件树，再按路径顺序处理可索引文件。
Issue按页读取所有状态的 Issue，并只输出同步时间窗口内更新过的条目。每个 Issue 会继续读取评论。
Pull Request按页读取所有状态的 PR，并只输出同步时间窗口内更新过的条目。每个 PR 会继续读取评论。
清理删除或不再匹配范围的文档依赖连接器清理 / prune 设置。需要删除验证时，应运行完整同步并确认旧文档已清理。

如果仓库非常大，请先用单仓库、单内容类型测试。连接器对单个 blob 有 1 MB 上限，对评论和总文档清单也有保护阈值；超过阈值时可能跳过文件或中断同步。

权限边界

Gitee token 决定艾维斯能摄取哪些仓库内容，但连接器不会把 Gitee 仓库成员、企业角色、私有仓库权限、分支保护或单个 Issue 权限同步到艾维斯。

因此，搜索访问只由艾维斯连接器的访问设置控制：

艾维斯访问设置含义
私有群组只有选定艾维斯群组可搜索该连接器产生的全部文档。推荐用于私有仓库、客户项目和内部项目。
公开所有可使用该知识范围的艾维斯用户都可能搜索到索引内容。仅当仓库内容可以面向这些用户公开时使用。
自动同步权限Gitee 当前不支持此模式。创建时选择权限同步会被拒绝。

不要把 Gitee 连接器配置成“共享代理”来绕过 Gitee 仓库权限。对于不同团队、客户、项目或保密等级，应使用不同 token、不同连接器和不同艾维斯私有群组。

验证

  1. 用测试仓库创建连接器，确认凭据可以读取目标仓库。
  2. 搜索 README、配置文件或代表性源码片段，确认源码文件已索引。
  3. 搜索一个已知 Issue 标题、正文关键词和评论关键词，确认 Issue 范围符合预期。
  4. 搜索一个已知 PR 标题、正文关键词和评论关键词，确认 PR 范围符合预期，并确认 diff 代码片段不会作为 PR 内容出现。
  5. 搜索未列出的仓库、未选分支或被跳过目录中的文件，确认不会返回结果。
  6. 使用群组内账号和群组外账号分别测试，确认艾维斯访问边界符合预期。
  7. 修改一个测试文件或评论后等待下一轮同步，确认增量更新可被检索。

常见问题排查

现象优先检查项
认证失败或 Gitee API 请求失败token 是否复制完整、是否过期或被撤销，网络是否能访问 gitee.com。
仓库校验失败仓库所有者和仓库名称是否只填路径片段，token 账号是否能打开目标仓库。
自托管 Gitee 无法配置当前连接器固定访问 https://gitee.com/api/v5，不支持自定义 Gitee 主机。
只索引了部分仓库确认仓库列表未遗漏、未重复，且没有超过 100 个仓库上限。
文件没有出现检查是否关闭了包含源码文件，分支是否正确，文件是否超过 1 MB、位于跳过目录、是二进制或 minified 文件。
Issue 或 PR 没有出现检查对应内容开关是否开启，token 是否能读取目标仓库的 Issue / PR API，以及条目是否在同步时间窗口内更新。
搜索结果包含群组外用户不该看到的内容这是艾维斯访问范围配置问题。将连接器改为私有群组，或按受众拆分连接器。
令牌泄露立即在 Gitee 中撤销或重新生成令牌，并更新艾维斯凭据；随后重新运行验证。

安全与维护建议

  • 每个环境使用独立 token，例如生产、测试和演示环境分开。
  • 每个敏感项目使用独立连接器，便于停用、审计和调整访问群组。
  • 定期复核仓库列表、分支、内容开关、访问群组和 token 负责人。
  • 仓库归属或名称变更后，同步更新连接器配置，并运行一次完整验证。
  • 长期不用时，先停用艾维斯连接器，再撤销 Gitee token。

官方参考

相关页面