从 GitHub 弃权到 Gitee：一次私有仓库备份的血泪史

日期：2026-07-15
背景：公司暂未开通内部 Git 服务，需要把基于芋道精简版的 IoT 二次开发项目备份到云端私有仓库。

---

一、目标与准备

项目	说明
代码基座	yudao-boot-mini fork，新增 yudao-module-iot 等模块
首选方案	GitHub 私有仓库 https://github.com/<账号>/<仓库名>.git
备选方案	Gitee 私有仓库 https://gitee.com/<账号>/<仓库名>.git
本地分支	<feature-branch>（如 JDK17 开发线）
上游远程	origin 保留指向芋道官方 Gitee，方便日后拉更新

本地已有一次业务提交（IoT 模块 + SQL 脚本），尚未推送到任何自有远程。

---

二、GitHub：为什么折腾半天上不去

2.1 直连：超时

关 VPN 后执行 git push，报错：

fatal: unable to access 'https://github.com/<账号>/<仓库名>.git/':
Failed to connect to github.com port 443 ...

国内网络访问 GitHub 443 端口不稳定，直连基本指望不上。

2.2 系统代理（127.0.0.1:7897）：假通真断

代理客户端进程在跑、端口也在监听，但 VPN 未开时：

• git push → RPC failed; curl 55 Connection was reset
• 或 schannel: SSL/TLS connection failed

教训：端口 LISTENING ≠ 代理真的在转发 GitHub 流量。

2.3 TUN 模式：能打开网页，push 仍挂

开 TUN 后浏览器访问 github.com 返回 200，但首次 push 整个 fork 历史时：

• 本地 Enumerating objects → Writing objects: 100%（约 178MB / 31 万对象）都完成了
• 终端卡在 Total 316255 (delta ...) 一动不动
• 最终 RPC failed; curl 55 Send failure: Connection was aborted

本地 git  ──上传 pack（~178MB）──▶  GitHub
         ◀──等待服务端解包 + 写 refs──  （VPN 一抖就断）

这不是成功。只有看到下面才算推上去：

To https://github.com/<账号>/<仓库名>.git
 * [new branch]      <branch> -> <branch>

2.4 为什么这么大

第一次往空仓库推的是整个芋道 fork 的完整 git 历史，不是只有 IoT 增量。体积大、耗时长，对代理稳定性要求极高——不稳定 VPN 下反复失败很正常。

2.5 GitHub 侧常用缓解手段（供后人参考）

git -c http.postBuffer=524288000 `
    -c http.version=HTTP/1.1 `
    -c http.lowSpeedLimit=0 `
    -c http.lowSpeedTime=999999 `
    push -u <remote> <branch> --progress

• 认证用 Personal Access Token，不是登录密码
• Writing objects: 100% 后可能还要等 5～15 分钟，期间不要关 TUN

若全量历史实在推不上去，可退而求其次推单提交快照（git checkout --orphan），体积小很多，但丢失历史。

结论：在不稳定代理环境下，我放弃了 GitHub。

---

三、转投 Gitee：国内线路更友好

3.1 添加自有远程

保留 origin（上游），新增备份远程：

cd <项目根目录>
git remote add backup https://gitee.com/<账号>/<仓库名>.git

3.2 推送

git push -u backup <branch>

或使用项目内脚本：

.\scripts\push-gitee.ps1

Gitee 走国内线路，无需 VPN，首次全量 push 成功率远高于 GitHub。

实测：同一仓库（约 177MB / 31 万对象），Gitee 约 1 分钟完成（含 remote: Resolving deltas 进度条）；GitHub 在相同体积下多次卡在 Writing objects: 100% 后断开。

3.3 验证

git ls-remote backup

能看到 commit hash 即表示远程已有内容。

---

四、推送前安全检查（必做）

检查项	说明
本地配置文件	application-local.yaml 含数据库/Redis 真实密码 → 勿提交
.gitignore	已排除 KNOWLEDGE.md、openspec/、platform-site/、docs/ 等
认证	Gitee 使用账号 + 密码，或私人令牌

---

五、远程一览（推荐布局）

origin   → gitee.com/yudaocode/yudao-boot-mini   # 上游，只拉不推
backup   → gitee.com/<你的账号>/<你的仓库>         # 自有备份，可推
github   → github.com/<你的账号>/<你的仓库>        # 可选，网络好时再推

---

六、后记

• GitHub 私有仓：适合有稳定国际网络的环境；国内 + 不稳定 VPN = 折磨。
• 首次 push 体积：fork 大项目的完整历史很重；Gitee 会提示个别文件 >50MB，属正常警告，不影响推送。
• 远程建议：origin 留上游，backup 作自有仓库，GitHub 远程可保留以备网络好转时再试。

祝后来人 push 一次成功，不用写第二篇 blog。