Git连接器

概述

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

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

支持的仓库

GitHub（公共/私有）
GitLab（公共/私有）
Bitbucket（公共/私有）
本地Git仓库
其他Git托管服务

前提条件

需要安装插件
私有仓库需要认证信息
需要仓库的读取访问权限

插件安装

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

或者，详情请参阅插件。

配置方法

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

基本设置

项目	设置示例
名称	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=

参数列表

参数	必需	说明
`uri`	是	Git仓库URI（用于clone）
`base_url`	否	文件显示用的基础URL。如未设置，URL将为空，且已删除文件的自动删除也将被禁用
`username`	否	Git认证用户名。与 `password` 一起使用，作为在URI中嵌入凭据的替代方式
`password`	否	Git认证密码或令牌。与 `username` 一起使用
`extractors`	否	按MIME类型的提取器设置
`default_extractor`	否	当没有MIME模式匹配时的回退提取器（默认：`tikaExtractor`）
`prev_commit_id`	否	上次提交ID（用于增量爬取）。爬取成功后自动更新
`commit_id`	否	目标提交ID（默认：HEAD）。可以指定分支或标签
`ref_specs`	否	Git ref specs（默认：`+refs/heads/:refs/heads/`）
`repository_path`	否	本地仓库路径。如未设置，将创建临时目录并在爬取后删除
`include_pattern`	否	文件路径包含过滤器（正则表达式）
`exclude_pattern`	否	文件路径排除过滤器（正则表达式）
`max_size`	否	索引的最大文件大小（字节，默认：`10000000`）
`cache_threshold`	否	内存和磁盘缓冲切换阈值（字节，默认：`1000000`）

脚本设置

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:

点击「Generate new token」→「Generate new token (classic)」
输入令牌名称（例: Fess Crawler）
在范围中勾选「repo」
点击「Generate token」
复制生成的令牌

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:

输入令牌名称
在范围中勾选「read_repository」
点击「Create personal access token」
复制生成的令牌

2. 在URI中包含认证信息

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

SSH认证

使用SSH密钥的情况:

uri=git@github.com:company/repo.git

Note

使用SSH认证时，需要设置运行 Fess 的用户的SSH密钥。

提取器设置

按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）将自动从索引中删除。

使用示例

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

确认事项:

确认Personal Access Token是否正确
确认令牌是否有适当的权限（repo 范围）

确认URI格式是否正确:

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

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

确认令牌的有效期

找不到仓库

症状: Repository not found

确认事项:

确认仓库URL是否正确
确认仓库是否存在且未被删除
确认认证信息是否正确
确认是否有仓库访问权限

无法获取文件

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

确认事项:

确认 extractors 设置是否适当
确认仓库中是否存在文件
确认脚本设置是否正确
确认目标分支中是否存在文件

MIME类型错误

症状: 特定文件未被爬取

解决方法:

调整提取器设置:

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

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

大型仓库

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

解决方法:

使用 extractors 限制目标文件
使用脚本只过滤特定目录
使用增量爬取（设置 prev_commit_id）
调整爬取间隔

分支指定

要爬取默认分支以外的分支，请使用 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/

base_url 和文件路径组合生成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