Git Harbor · 本地 Git 拉取管理器

通过浏览器管理大型 Git 仓库下载、暂停、恢复和更新。适合 Unreal Engine 等源码仓库。Python 标准库实现，无需 npm install 或 pip install。

源码仓库 · 问题反馈 · 参与贡献 · MIT License

大仓库模式按已完成的 Git 对象批次恢复下载；不承诺中断数据包的逐字节续传。详见下方的恢复机制与适用范围。

启动

需要 Python 3.10+ 和 Git 2.43+（推荐最新版 Git for Windows）。当前开发和测试环境为 Windows、Python 3.12、Git 2.55。

先克隆项目，也可通过 GitHub 的 Code → Download ZIP 下载并解压：

git clone https://github.com/GShenLin/GitHabor.git
cd GitHabor

Windows 用户：

1. 双击本目录的 start.bat。
2. 浏览器自动打开 http://127.0.0.1:8765。
3. 输入 Git 地址后会自动获取分支下拉列表，默认分支带有标记；也可点击「刷新」重新获取。保留「自动选择」时，新仓库使用默认分支，已有仓库使用当前分支。输入最终仓库目录的完整路径，点击「开始拉取」。例如 D:\Projects\UnrealEngine；不要只填希望存放多个仓库的父目录。
4. 在任务卡片上暂停、继续、看日志；完成后点击「打开文件夹」或「拉取更新」。

网络代理设置

点击左侧「下载工作台」「已完成仓库」下方的「设置」，即可管理网络代理。

• 默认关闭代理，直接连接网络。如果出现 Failed to connect to github.com port 443，可开启代理后重试。
• 开启后的默认地址为 http://127.0.0.1:17891，可按代理软件的 HTTP / 混合代理端口修改；支持 HTTP、HTTPS、SOCKS5 和 SOCKS5H 地址。启动前请确保代理软件正在运行。
• 点击「保存设置」生效。设置保存在本机 data/settings.json，重启后保留；未保存的更改不会生效。
• 分支查询、仓库下载、更新，以及 Git LFS / 子模块的 HTTP / HTTPS 连接使用此设置。关闭时，程序会为 Git 子进程禁用代理环境变量并设置直连；不会修改系统或全局 Git 配置。SSH 连接仍使用自己的 SSH 配置。
• 保存后，从下一次 Git 操作或重试开始应用；正在传输的连接不会中断。填写了仓库地址时，保存设置后会自动重新获取分支。
• 代理只解决网络连接问题，私有仓库仍需在本机 Git 登录具有访问权限的账号。通过 python server.py 启动也使用相同设置。

服务运行期间保留启动窗口。关掉浏览器不会停止下载；退出服务请在启动窗口按 Ctrl+C，等待当前 Git 命令结束。下次启动后，未完成任务显示为暂停，点击继续即可。不要在传输期间强行结束 Git 进程或关闭电脑。

命令行也可启动。macOS / Linux 可使用 python3 server.py，但目前主要在 Windows 上验证；系统文件夹选择器需要 Python 提供 Tkinter：

python server.py
python server.py --port 8766 --no-browser

默认端口被占用时，先查看原服务是否已经运行。不要对同一个数据目录同时运行多个服务实例。

功能

• Git HTTPS / SSH / git:// / file:// / 本地路径，支持指定分支。
• 输入地址后自动查询远端分支（仅查询引用，不下载仓库），支持手动刷新和默认分支标记；查询超时、空仓库和认证失败会显示提示。
• 空目录新建仓库；已有普通 Git 仓库输入相同 origin 地址即可接管更新。暂不支持 .git 是文件的 worktree / 子模块目录。
• 大仓库模式：首轮只下载单分支最近一次提交的目录和树，再以 32 / 128 / 512 个文件对象为一批补齐当前版本。
• 完整历史模式：获取所选分支的完整可达历史，使用标准 Git 传输。
• 串行任务队列，实时 Git 日志、对象进度、传输速度原始输出。
• 网络暂时故障自动指数退避重试，最多 5 次；耗尽后可手动继续。认证失败等非网络错误直接显示原因。
• 安全暂停、磁盘保存任务、重启恢复；已完成任务独立列表。
• 更新前检查当前分支和工作区，只使用 merge --ff-only，不做 reset、clean 或强制覆盖。
• 可选 Git LFS、递归子模块下载；LFS 需要另行安装 Git LFS。
• 目录选择器和 Windows 资源管理器打开文件夹。

“断点续传”的准确含义

Git 通常无法像 HTTP 文件下载器一样从中断 pack 的任意字节继续。工具实现的是持久化的对象批次恢复：

1. 通过 --filter=blob:none 获取提交和目录信息。
2. 查询目标版本的文件对象，并在本地对象库中检查哪些已经完整存在。
3. 分批请求缺失对象，每批成功后 Git 会保存为有效对象包。
4. 暂停或重启后重新检查本地对象，跳过已完成批次。
5. 所需文件对象齐备后才执行工作区 checkout。

已完成批次不会整库重下；当前失败批次、单个超大文件对象仍可能重传。 批次按对象数量划分，不是固定 MB 大小。页面百分比表示当前版本的文件对象数量进度，不代表字节比例。

暂停是安全暂停：点击后等待当前 Git 命令/对象批次结束；网络速度连续 45 秒低于 1 KB/s 时 HTTP 传输会失败并进入重试/暂停。因此服务器打包、单个大对象、子模块或标准模式传输期间可能需要较长时间才进入暂停。

远端必须支持 Git partial clone / filter 才能获得分批恢复收益。不支持时 Git 会退回普通传输，页面会显示提示。完整历史模式、子模块及已有普通仓库的首次 fetch 使用 Git 原生恢复能力，没有逐批续传保证。

默认大仓库模式是浅克隆，不包含全部历史，也不下载所有分支或标签。如需要完整提交历史，可在完成后自行执行 git fetch --unshallow origin；大仓库模式历史版本的文件可能仍需按需联网获取。--unshallow 仅适用于浅仓库。

设计依据：Git partial clone、git fetch、git clone。

Unreal Engine 使用

• 地址可填 https://github.com/EpicGames/UnrealEngine.git，分支填写你有权限访问的目标分支，或留空使用默认分支。
• 私有仓库需要你已取得该仓库访问权限，并在本机 Git 凭据管理器登录；SSH 需要可用密钥和已信任的服务器主机密钥。可先在终端运行 git ls-remote 仓库地址 HEAD 验证访问权限。
• 地址里不要粘贴用户名、密码或 token。工具优先复用系统 Git 凭据；HTTPS 访问 GitHub 时，如果获取分支、下载或更新遇到凭据缺失 / 失效，会自动调用 Git Credential Manager 打开浏览器登录，并在成功后自动重试一次。浏览器已有 GitHub 会话时可能自动完成，否则按页面提示登录或授权。
• 浏览器登录使用「设置」中保存的代理，最多等待 3 分钟。多个请求共用一次登录，短时间内重复刷新不会反复弹窗；取消或超时后会显示提示，稍后可点击刷新或继续任务重试。需要安装 Git Credential Manager（Git for Windows 可选组件）。其他托管平台和 SSH 仍使用各自的凭据配置。登录不会赋予额外仓库访问权限。
• 仓库下载成功之后，Unreal 的 Setup.bat 下载依赖和 GenerateProjectFiles.bat 生成工程仍需自行运行。此工具管理 Git 仓库，不代替 Unreal 依赖下载器。
• 默认跳过 LFS 文件内容和子模块；需要时创建任务时勾选对应选项。未勾选 LFS 时，LFS 文件可能只是指针文件。

数据与边界

通常只需运行 start.bat 或 python server.py。高级用途：旧服务正在下载大型数据包、又希望立即使用更新后的页面时，可运行 python upgrade_frontend.py，在 http://127.0.0.1:8766 提供页面并将任务操作转发到 8765 的原服务。该模式不创建第二个下载任务管理器，原服务需要保持运行；正常启动无需这个辅助程序。

• data/settings.json 保存网络代理开关与地址，默认关闭代理。
• data/tasks.json 保存任务状态及最近 180 行日志。完整下载数据在用户指定的仓库目录 .git/objects 中。
• 只监听 127.0.0.1；网页和服务必须在这台电脑上运行。不能直接双击 web/index.html，页面需要本地后端才能运行 Git 和打开文件夹。
• 仅接收本机 Host / Origin，请求修改需要当前页面令牌；不开放公网服务。
• 如果强制结束 Git 或断电造成 Git .lock 文件残留，应先确认没有任何 Git 进程在使用该仓库，再由用户检查处理。工具不会擅自删除锁文件。
• 当前不包括任务删除、完整下载历史日志导出、跨电脑远程控制或 Git 仓库权限配置。

验证

python -m unittest discover -s tests -v
node --check web/app.js

集成测试使用真实的本地 Git 远端，验证分批暂停后重启续传、增量更新、中文路径、完整历史模式、分叉与未提交修改保护、远端不支持 filter 的回退、重复路径保护以及 API 跨站请求拦截。测试不需要 GitHub 账号，也不下载真实 Unreal 仓库。

许可证

本项目采用 MIT License。