> 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. # Gitee > 配置 Gitee 代码仓库连接器，将索引限制在明确批准的仓库、分支和内容类型内。 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 私人令牌页面](https://gitee.com/profile/personal_access_tokens/new)创建。 * 令牌所属账号可以读取目标仓库、Issue、Pull Request 和目标分支文件。只做索引时，不要授予写入、Hook 或管理员类权限。 * 已确认仓库所有者和仓库路径。例如 `https://gitee.com/openmodels/search` 中，仓库所有者是 `openmodels`，仓库名称是 `search`。 * 已规划艾维斯访问范围。只要连接器可见，用户就可能搜索到该连接器索引的全部内容。 * 网络策略允许艾维斯后端访问 `gitee.com`。 Gitee 官方帮助中把私人令牌用于仓库 API 或镜像操作时通常要求包含 `project` 权限。实际权限界面可能随 Gitee 版本变化；请以目标租户中能读取仓库、Issue、PR 和文件 API 为准，并保持最小权限。 ## 配置数据获取入口 | 配置数据 | 获取方式 | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Gitee 私人令牌 | 登录 Gitee 后从 [私人令牌页面](https://gitee.com/profile/personal_access_tokens/new) 创建专用 token；权限说明可参考 [Gitee 帮助：申请包含 project 权限的私人令牌](https://gitee.com/help/articles/4336)。 | | 仓库所有者 | 从仓库 URL `https://gitee.com/{owner}/{repo}` 中取 `{owner}`，只填写路径片段，不填写完整 URL。 | | 仓库名称 | 从仓库 URL `https://gitee.com/{owner}/{repo}` 中取 `{repo}`。需要批量配置时先确认这些仓库属于同一 owner 和同一访问受众。 | | 分支 | 在仓库的分支列表或默认分支设置中确认。留空时连接器使用仓库默认分支。 | | 文件、Issue、Pull Request API 可读性 | 可用 [Gitee API v5 文档](https://gitee.com/api/v5/swagger) 验证 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。 ## 官方参考 * [Gitee 帮助：申请包含 project 权限的私人令牌](https://gitee.com/help/articles/4336) ## 相关页面 * [连接器与索引](/aivis/knowledge/connectors) * [索引设置](/aivis/knowledge/index-settings) * [用户、群组与角色](/aivis/governance/users-and-groups)