GitProxy 2.3 介绍与选型指南

目标：在动手部署前判断 GitProxy 是不是你要的 Git 推送审批网关。本篇基于官方仓库、官方文档站、GitHub Releases 与 shields.io/npm 徽章的联网溯源（检索日期 2026-10-25），讲清它的定位、架构、功能边界与硬要求，并与「平台分支保护」「Gitolite 权限」「商业合规网关」做量化对比。部署、参数与命令的逐步实测不在本篇展开。

一、信息基准

本篇是认知与选型文档，先交代「信息从哪来、以哪个版本为基准」，便于读者判断时效并自行复核。

1.1 查询与版本基准

• 检索日期：2026-10-25。
• 基准版本：GitProxy v2.3.0。依据：官方 GitHub Releases atom 订阅源中最新条目为 v2.3.0（条目更新时间 2026-10-17），npm 包 @finos/git-proxy 最新版本徽章同为 v2.3.0。
• v2.3.0 变更要点（Release Notes 原文摘要）：新增 PostgreSQL 存储后端（经 proxy.config.json 配置，含 AWS RDS/Aurora IAM 认证与迁移文件）、改进插件系统、修复 v2.2 的 Unreferenced commits in pack 错误。
• 写作方式：不做本地安装实测；所有版本、特性、量化数据均来自官方来源，随文标注出处。

1.2 官方来源清单

二、软件概述

GitProxy 是部署在开发者与上游 Git 仓库之间的「推送审批代理」：开发者照常 clone 仓库，但把 git push 指向 GitProxy；GitProxy 对推送做规则检查与安全扫描，拦截后进入审批队列，由审批人（reviewer）在 Web 管理台批准后，提交才真正进入上游仓库。

一句话定位（官方 README 原文）："Deploy custom push protections and policies on top of Git"——在 Git 之上部署自定义的推送保护与策略。

核心身份信息：

💡 说明：FINOS 是由高盛、摩根大通、花旗等金融机构联合发起的开源基金会，「Graduated（毕业）」是其项目生命周期的最高成熟度等级，代表项目在社区治理、安全与合规流程上通过了基金会评审。

三、核心架构

GitProxy 的本质是一个 Git Smart HTTP/SSH 协议代理 + 规则引擎 + 审批工作流，三者跑在同一个 Node.js 进程中，另带一个 React 管理 UI。

3.1 推送链路

完整链路如下（官方 README 的时序图转述）：

1. 开发者 git clone 上游仓库（如 gitea.local:3000/admin/hello-gitproxy.git）；
2. 开发者执行 git remote add proxy http://<gitproxy>:8000/<上游主机>/<组织>/<仓库>.git，把推送目标指向 GitProxy；
3. git push proxy main：GitProxy 接收推送，逐条执行处理链检查；
4. 任一检查失败即拒绝并返回原因；全部通过则拦截推送、生成审批记录与可分享的审批链接；
5. 审批人在 Web 管理台查看 diff、提交元数据，批准或驳回；
6. 批准后开发者重新执行同样的 git push，GitProxy 校验到「该提交已获批」，放行并转发到上游仓库。

3.2 处理链（Chain）步骤

每次推送在 GitProxy 内部按固定顺序经过一条处理链，v2.3.0 实测链路（来自推送记录的 step 序列，自上而下）：

💡 技术拓展：「在推送路径上做合规拦截」不止 GitProxy 一种实现思路。常见方案对比——

方案	原理	特点	适用场景
服务端钩子（pre-receive hook）	在 Git 服务端接收推送时执行脚本	与平台强绑定，只能拒不能「待审」	单平台、规则简单
推送代理（GitProxy）	代理推送流量，集中执行规则+审批队列	平台中立、有人工审批工作流	跨平台、强合规
CI 事后扫描	提交入库后由 CI 扫描再补救	不阻断推送，属于事后发现	一般质量门禁

GitProxy 采用「推送代理」路线：在推送到达真实仓库之前集中拦截，兼顾平台中立与人工审批。

3.3 部署形态

• 单进程 Node.js 服务：对外暴露 Git 代理端口（HTTP 8000 / HTTPS 8443）与管理服务端口（HTTP 8080 / HTTPS 8444，同端口承载 REST API 与 React UI）；
• 数据存储：默认嵌入式 NeDB（零依赖落盘文件），可选 MongoDB、PostgreSQL（v2.3.0 新增）；
• 配置：单个 proxy.config.json 文件驱动全部行为；
• 分发：npm 全局包（npx -- @finos/git-proxy）与 Docker 镜像（finos/git-proxy）。

四、功能特性

依据 README、文档站与 v2.3.0 Release Notes 归纳：

1. 推送审批工作流：推送默认拦截入队；审批人查看 diff 与提交元数据后批准/驳回（驳回必填理由）；批准需勾选 attestation（合规确认问卷，问题可配置）。
2. 四眼原则（Four-eyes）：服务端强制「不能批准/驳回自己的推送」，批准人必须在仓库的 canAuthorise 名单内。
3. 仓库白名单：只有列入 authorisedList 的上游仓库才允许经代理推送。
4. 提交内容校验：提交消息禁用词（字面量+正则）、作者邮箱域名白名单、隐藏提交检测、pack 安全限制（对象数、解压体积、膨胀率，防 zip-bomb 类攻击）。
5. Secrets 扫描：内置 gitleaks 扫描开关与 diff 内容扫描（字面量/正则/自定义 provider）。
6. 多 SCM 提供方：github、gitlab、forgejo（gitea/codeberg 同族）等，推送时回调上游 API 复核推送人权限。
7. 双协议支持：HTTP/HTTPS 与 SSH 推送代理，二者走同一套扫描与审批。
8. 认证与集成：本地账号、Active Directory、OpenID Connect 三种登录方式；REST API（Cookie 会话或 JWT）；外部 pre-receive 钩子；插件系统（v2.3.0 改进）；上游 HTTP 代理出口配置。
9. 管理 UI：React 管理台，覆盖推送队列、审批操作、仓库、用户、配置查看。

五、快速开始（最小可用示例）

以下为官方 README 给出的最小路径（本系列《Docker Compose 部署指南》篇有完整的本地化实测版本）：

# 1. 启动 GitProxy（需要 Node.js 运行时）
npx -- @finos/git-proxy

# 2. 克隆上游仓库并把推送指向 GitProxy
git clone https://github.com/octocat/Hello-World.git && cd Hello-World
git remote add proxy http://localhost:8000/yourGithubUser/Hello-World.git

# 3. 推送（默认配置下会被拦截，等待审批）
git push proxy main

⚠️ 注意：默认配置会拦截一切推送。要让推送能通过检查进入审批队列，必须先把目标仓库 URL 写进 proxy.config.json 的 authorisedList，并为该仓库配置 canPush/canAuthorise 名单。

六、适用场景与限制

6.1 适用场景

• 强合规行业的开源贡献管控：金融、医疗等行业要求员工对外推送代码前经安全与法律合规审批——这正是 GitProxy 的设计初衷（FINOS 成员场景）。
• 内网仓库外发闸门：企业内 Git 服务器（Gitea/GitLab）的仓库需要外发到公共平台时，用 GitProxy 做统一出口审批。
• 跨平台统一推送策略：上游同时有 GitHub、GitLab、Gitea 时，用一套规则集中管控。
• 个人最佳实践强制：官方 README 提到也可用于单人环境，强制自己的提交通过检查。

6.2 限制与边界

• 需要审批人力：审批队列意味着每次推送都要等人工批准，不适合高频推送的日常开发主干；它管的是「外发/合入受保护仓库」这类低频高敏操作。
• 只拦推送，不管拉取：clone/fetch 仍直连上游，GitProxy 不代理读流量。
• 社区规模尚小：262 Star / 184 Fork（2026-10-25），生态与现成插件有限，自定义规则可能需要自己写插件。
• 运行时要求：需要 Node.js 运行环境（官方镜像基于 Node 24）；生产存储建议 MongoDB 或 PostgreSQL，默认 NeDB 面向小规模。
• UI 仅英文：管理台为英文界面，审批人需要基本英文阅读能力。

七、同类选型对比

GitProxy 的替代路线主要有三条：平台自带分支保护、Gitolite 细粒度权限、商业合规网关。量化对比（检索日期 2026-10-25）：

选型建议（「如果…则…」）：

• 如果团队只用单一平台且只需要分支保护（强制 PR、状态检查、签名提交）——用平台自带分支保护即可，不必引入 GitProxy。
• 如果需要对自建 SSH Git 服务做极细粒度（按分支/按路径）的权限控制，且无审批工作流诉求——选 Gitolite。
• 如果已在购买 GitHub GHAS / GitLab Ultimate，且审批发生在 MR 环节即可满足合规——直接用商业模块，避免多维护一个组件。
• 如果身处强合规行业、需要「推送出站前的人工审批队列 + 四眼原则 + secrets 扫描」，且上游可能是多个不同平台或自建 Gitea——选 GitProxy，它是该细分场景下目前少见的开源专职方案，且有 FINOS 治理背书。

八、参考链接

• 官方仓库：https://github.com/finos/git-proxy
• 官方文档站：https://git-proxy.finos.org
• Releases（atom）：https://github.com/finos/git-proxy/releases.atom
• npm 包：https://www.npmjs.com/package/@finos/git-proxy
• FINOS 官网：https://www.finos.org
• Gitolite 官方：https://gitolite.com/gitolite/index.html