Git连接器

概述

Git连接器提供从Git仓库获取文件并注册到 Fess 索引的功能。

此功能需要 fess-ds-git 插件。

支持的仓库

• GitHub（公共/私有）

• GitLab（公共/私有）

• Bitbucket（公共/私有）

• 本地Git仓库

• 其他Git托管服务

前提条件

1. 需要安装插件

2. 私有仓库需要认证信息

3. 需要仓库的读取访问权限

插件安装

从管理界面的「系统」→「插件」进行安装。

或者，详情请参阅 插件。

配置方法

从管理界面的「爬虫」→「数据存储」→「新建」进行配置。

基本设置

项目	设置示例
名称	Project Git Repository
处理器名称	GitDataStore
启用	开

参数设置

公共仓库示例:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
extractors=text/.*:textExtractor,application/xml:textExtractor,application/javascript:textExtractor,
prev_commit_id=

私有仓库示例（带认证）:

uri=https://username:personal_access_token@github.com/company/private-repo.git
base_url=https://github.com/company/private-repo/blob/master/
extractors=text/.*:textExtractor,application/xml:textExtractor,
prev_commit_id=

参数列表

脚本设置

url=url
host="github.com"
site="github.com/codelibs/fess/" + path
title=name
content=content
cache=""
digest=author.toExternalString()
anchor=
content_length=contentLength
last_modified=timestamp
mimetype=mimetype

可用字段

字段	说明
url	文件的URL
path	仓库内的文件路径
name	文件名
content	文件的文本内容
contentLength	内容长度
timestamp	最后更新时间
mimetype	文件的MIME类型
author	最后提交作者信息 (PersonIdent)
committer	提交者信息 (PersonIdent)。可能与author不同
uri	Git仓库URI

Git仓库认证

GitHub Personal Access Token

1. 在GitHub生成Personal Access Token

访问 https://github.com/settings/tokens:

1. 点击「Generate new token」→「Generate new token (classic)」

2. 输入令牌名称（例: Fess Crawler）

3. 在范围中勾选「repo」

4. 点击「Generate token」

5. 复制生成的令牌

2. 在URI中包含认证信息

uri=https://username:YOUR_GITHUB_TOKEN@github.com/company/repo.git

GitLab Private Token

1. 在GitLab生成Access Token

GitLab的User Settings → Access Tokens:

1. 输入令牌名称

2. 在范围中勾选「read_repository」

3. 点击「Create personal access token」

4. 复制生成的令牌

2. 在URI中包含认证信息

uri=https://username:YOUR_GITLAB_TOKEN@gitlab.com/company/repo.git

使用用户名和密码进行认证

除了在URI中嵌入凭据外，也可以使用 username 和 password 参数指定认证信息：

uri=https://github.com/company/repo.git
username=your_username
password=YOUR_PERSONAL_ACCESS_TOKEN

仅当同时指定 username 和 password 时，凭据才会生效。

Note

Git连接器仅支持HTTP/HTTPS认证（用户名和密码，或访问令牌）。不支持SSH密钥认证（git@... 形式的URI）。请使用HTTPS形式的URI。

提取器设置

按MIME类型的提取器

使用 extractors 参数指定按文件类型的提取器:

extractors=text/.*:textExtractor,application/xml:textExtractor,application/javascript:textExtractor,application/json:textExtractor,

格式: <MIME类型正则表达式>:<提取器名>,

默认提取器

• textExtractor - 用于文本文件

• tikaExtractor - 用于二进制文件（PDF、Word等）

只爬取文本文件

extractors=text/.*:textExtractor,

爬取所有文件

extractors=.*:tikaExtractor,

只爬取特定文件类型

# 只爬取Markdown、YAML、JSON
extractors=text/markdown:textExtractor,text/yaml:textExtractor,application/json:textExtractor,

增量爬取

只爬取上次提交以来的变更

初次爬取后，将上次的提交ID设置到 prev_commit_id:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
prev_commit_id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Note

prev_commit_id 在爬取成功后会自动更新为最新的提交ID。 初次爬取时留空即可处理所有文件，之后的爬取只会处理变更内容。

已删除文件的处理

当设置了 base_url 时，通过Git DiffEntry检测到的已删除文件（ChangeType.DELETE）将自动从索引中删除。

当文件被重命名（ChangeType.RENAME）时，旧路径的文档将被删除，新路径的文件将重新建立索引。

Note

已删除文件的自动删除仅在设置了 base_url 时有效。如果未设置 base_url，文档URL为空，因此不会执行删除操作。

使用示例

GitHub公共仓库

参数:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
extractors=text/.*:textExtractor,application/xml:textExtractor,

脚本:

url=url
host="github.com"
site="github.com/codelibs/fess/" + path
title=name
content=content
last_modified=timestamp
mimetype=mimetype

GitHub私有仓库

参数:

uri=https://username:YOUR_GITHUB_TOKEN@github.com/company/repo.git
base_url=https://github.com/company/repo/blob/main/
extractors=text/.*:textExtractor,application/xml:textExtractor,application/javascript:textExtractor,

脚本:

url=url
title=name
content=content
digest=author.toExternalString()
content_length=contentLength
last_modified=timestamp
mimetype=mimetype

GitLab（自托管）

参数:

uri=https://username:glpat-abc123@gitlab.company.com/team/project.git
base_url=https://gitlab.company.com/team/project/-/blob/main/
extractors=text/.*:textExtractor,
prev_commit_id=

脚本:

url=url
host="gitlab.company.com"
site="gitlab.company.com/team/project/" + path
title=name
content=content
last_modified=timestamp

只爬取文档（Markdown文件）

参数:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
extractors=text/markdown:textExtractor,text/plain:textExtractor,

脚本:

if (mimetype.startsWith("text/")) {
    url=url
    title=name
    content=content
    last_modified=timestamp
}

只爬取特定目录

使用脚本过滤:

if (path.startsWith("docs/") || path.startsWith("README")) {
    url=url
    title=name
    content=content
    last_modified=timestamp
    mimetype=mimetype
}

故障排除

认证错误

症状: Authentication failed 或 Not authorized

确认事项:

1. 确认Personal Access Token是否正确

2. 确认令牌是否有适当的权限（repo 范围）

3. 确认URI格式是否正确:

   # 正确
   uri=https://username:token@github.com/company/repo.git
   
   # 错误
   uri=https://github.com/company/repo.git?token=...
   

4. 确认令牌的有效期

找不到仓库

症状: Repository not found

确认事项:

1. 确认仓库URL是否正确

2. 确认仓库是否存在且未被删除

3. 确认认证信息是否正确

4. 确认是否有仓库访问权限

无法获取文件

症状: 爬取成功但文件数为0

确认事项:

1. 确认 extractors 设置是否适当

2. 确认仓库中是否存在文件

3. 确认脚本设置是否正确

4. 确认目标分支中是否存在文件

MIME类型错误

症状: 特定文件未被爬取

解决方法:

调整提取器设置:

# 爬取所有文件
extractors=.*:tikaExtractor,

# 添加特定MIME类型
extractors=text/.*:textExtractor,application/json:textExtractor,application/xml:textExtractor,

大型仓库

症状: 爬取耗时长或内存不足

解决方法:

1. 使用 extractors 限制目标文件

2. 使用脚本只过滤特定目录

3. 使用增量爬取（设置 prev_commit_id）

4. 调整爬取间隔

分支指定

要爬取默认分支以外的分支，请使用 commit_id 参数指定分支名称或标签：

uri=https://github.com/company/repo.git
base_url=https://github.com/company/repo/blob/develop/
commit_id=develop

URL生成

base_url设置模式

GitHub:

base_url=https://github.com/user/repo/blob/master/

GitLab:

base_url=https://gitlab.com/user/repo/-/blob/main/

Bitbucket:

base_url=https://bitbucket.org/user/repo/src/master/

URL通过直接拼接 base_url 和文件路径生成（不插入分隔符）。因此，base_url 必须以 / 结尾。

在脚本中生成URL

url=url
title=name
content=content

或者，自定义URL:

url="https://github.com/mycompany/repo/blob/main/" + path
title=name
content=content

参考信息

• 数据存储连接器概述 - 数据存储连接器概述

• 数据库连接器 - 数据库连接器

• 数据存储爬取 - 数据存储配置指南

• GitHub Personal Access Tokens

• GitLab Personal Access Tokens