feat(datasource): 新增 Git 仓库数据源连接器与 push webhook 自动同步 - #2747
Conversation
支持从任意 git 服务（内网 GitLab/Gitea/GitHub 等）同步文档： - go-git 本地克隆，按数据源/仓库/分支哈希隔离目录，并发互斥 - commit 游标增量：新增/修改/删除/重命名，force-push 降级全量 - Markdown/HTML 相对路径图片内联为 data URI - 每仓库 checkpoint，超时重试续跑；仅同步 6 种纯文本格式
- 公开端点 POST /api/v1/datasource/webhooks/git/:id（Auth 前注册，同 IM 回调模式） - GitLab X-Gitlab-Token 常量时间比对；GitHub X-Hub-Signature-256 HMAC 验签 - 密钥两级：settings.webhook_secret > GIT_REPO_WEBHOOK_SECRET，未配置 fail-closed - URL 归一化匹配（容忍 scheme/.git 后缀/大小写）+ 分支过滤 - 分支删除/非分支推送/仓库不匹配返回 200 忽略，防平台重试 - ManualSync 重构出 enqueueSync(trigger)，新增 WebhookSync；审计记录 trigger 来源 - 前端数据源编辑页展示 webhook 回调 URL 提示卡（复制按钮，密钥不回显）
- 10-datasource.md：能力对比表补 GitLab/Git Repo 两列，注册说明更正为 9 类型，
新增 GitLab/Git Repo 连接器详解与「Push Webhook 自动触发」章节
- 02-api-infra.md：新增公开 webhook 端点说明（鉴权头、密钥配置、响应码、curl 示例）
- swagger 三件套由 make docs 重新生成（含 /datasource/webhooks/git/{id}）
- .env.example：登记 GIT_REPO_WEBHOOK_SECRET 与 GIT_REPO_STORAGE_BASE_DIR
- internal/datasource/README.md：API 端点清单补 webhook 小节
|
Suggestion from adding this connector: lower the cost of adding a new datasource connector I just went through the full flow of adding a new connector (git_repo) in this PR, and wanted to share a concrete observation about extension friction — hopefully useful for the maintainers. What's already good: the The friction I hit: adding one connector touched 4 separate places and required recompiling the whole binary:
For a repo that explicitly positions datasource connectors as an extension point, 3-4 manual edit sites + a full rebuild feels heavier than necessary. Two pragmatic improvements that would keep the current architecture while lowering the cost:
Happy to help draft any of these if the maintainers are interested. |
|
感谢提供此数据源，是否有充分进行测试，已经相关可用截图，方便我们审核 |
可以正常识别基于vuepress编写的知识库内容，其中markdown执行的相对路径的图片也完成了处理并且能够正常显示
|
直接同步了vuepress的git仓库，提交git即可通过webhook发起同步操作
|
| // credentials go in the access_token credential field); an absolute local path | ||
| // is allowed so tests can clone from a throwaway bare repo and local checkouts | ||
| // can be synced directly. | ||
| func normalizeRepoURL(raw string) (string, error) { |
There was a problem hiding this comment.
repo_url 需要增加 ValidateURLForSSRF，对应的transport也要尽可能使用 datasource/httpclient.go 的 SSRF 安全客户端
| # GIT_REPO_WEBHOOK_SECRET= | ||
| # git_repo 数据源：本地克隆存储根目录覆盖（默认 LOCAL_STORAGE_BASE_DIR/git-repos）。 | ||
| # GIT_REPO_STORAGE_BASE_DIR= | ||
| # 统一文件大小限制（MB，默认 50）。影响单文件上传、docreader gRPC 消息、frontend Nginx请求体、浏览器客户端校验。属部署期配置：Go/Nginx/docreader/浏览器四层启动时读一次，运行中改不生效，改后须同步重启四层。 |
There was a problem hiding this comment.
感觉不需要增加默认的环境变量配置，直接按空间租户隔离
评审意见：repo_url 需要增加 ValidateURLForSSRF，对应 transport 尽可能使用 datasource/httpclient.go 的 SSRF 安全客户端。 - normalizeRepoURL 对归一化后的 URL 调用 utils.ValidateURLForSSRF，私网/回环/ link-local/云元数据等目标在配置期即被拒绝，内网 git 服务器可经 SSRF_WHITELIST/SSRF_WHITELIST_EXTRA 放行 - ensureSSRFTransport 通过 go-git 传输注册表将 http/https 协议替换为 datasource.NewConnectorHTTPClient 的客户端（拨号期+重定向二次校验，防 DNS 重绑定），clone/fetch/ls-remote 全部走 SSRF 防护 - 新增 ssrf_test.go；webhook/handler 测试 fixture 改用公开域名以通过校验 - 文档与 .env.example 补充 SSRF 校验说明
…_DIR 评审意见：不需要增加默认的环境变量配置，直接按空间租户隔离。 - 删除 GIT_REPO_STORAGE_BASE_DIR，克隆统一落在 <LOCAL_STORAGE_BASE_DIR>/git-repos/<租户ID>/<数据源ID>/<sha1(url+branch)>/ - repoStorageBase 直接读 LOCAL_STORAGE_BASE_DIR（默认 /data/files）， 目录隔离由 cloneDirFor 按 tenantID/dsID 保证 - .env.example 与 datasource 文档同步更新；connector_test 改用 LOCAL_STORAGE_BASE_DIR 重定向临时存储
2 participants
概述
新增 Git 仓库（git_repo）数据源连接器，支持从任意 git 服务（内网 GitLab / Gitea / GitHub 等）同步文档；并为 git_repo 数据源增加 GitLab / GitHub push webhook 自动触发同步。
变更内容
1. Git 仓库数据源连接器（
d536a00f）git diff --name-status，仅处理变更文件；force-push / 历史重写自动降级全量重枚举SyncDeletions按数据源范围隔离删除逻辑data:URI 内联，随文档入库2. Push Webhook 自动触发（
7c87b560）POST /api/v1/datasource/webhooks/git/:id（认证中间件之前注册，同 IM 回调模式）X-Gitlab-Token常量时间比对；GitHubX-Hub-Signature-256（及旧版 sha1）HMAC 验签settings.webhook_secret> 环境变量GIT_REPO_WEBHOOK_SECRET；均未配置时 fail-closed（403）.git后缀 / host 大小写）+ 分支过滤；分支删除 / 非分支推送 / 仓库不匹配返回 200 忽略（避免平台重试）ManualSync重构出enqueueSync(trigger)，新增WebhookSync；审计与日志记录trigger来源（manual / webhook / scheduled）3. 文档（
6b5e9d26）website-docs/03-features/10-datasource.md：能力对比表补 GitLab / Git Repo 两列，注册说明更正为 9 类型，新增 GitLab / Git Repo 连接器详解与「Push Webhook 自动触发」章节website-docs/04-api/02-api-infra.md：公开 webhook 端点说明（鉴权、响应码、curl 示例）.env.example：登记GIT_REPO_WEBHOOK_SECRET、GIT_REPO_STORAGE_BASE_DIRinternal/datasource/README.md：API 端点清单补 webhook 小节测试验证
go build ./...全量编译通过vue-tsctype-check 通过备注
docs/swagger.{json,yaml,go}）由make docs重新生成，含/datasource/webhooks/git/{id}；其中顺带补齐了上游近期已改注释但未再生成的路由（memory / mcp 等），PR diff 中 swagger 文件较大属此原因