Git 局域网仓库搭建与同步维护说明（VMware Ubuntu Server + Windows）

本文记录本次从零搭建 Ubuntu 22.04 Server（虚拟机）Git bare 中心仓 + Windows 客户端同步 的完整流程、推荐配置、踩坑与维护方式。适用于“一个人多台 Windows + 一台 Linux 仓库服务器”。

1. 目标架构

• Ubuntu VM（局域网固定 IP）：只承担 Git 中心仓（bare）与 SSH 服务
• Windows 多台：作为开发机，clone / commit / push
• 业务运行机（可选）：例如另一台 Linux 跑交易/服务，通过 git pull 部署（本文不展开业务部署）

2. VMware 虚拟机建议（只装仓库）

2.1 选型

• Ubuntu Server 22.04.x（推荐）：更轻、更稳
• 网络：VMware 网卡选 Bridged（桥接），让 VM 获得局域网 IP（Windows 才能 ssh/git）
• 磁盘：虚拟磁盘文件放到 Windows 大盘；容量建议 40–60GB 起步（只存代码通常足够；若会存大量数据/回测产物再加大）

2.2 固定 IP（安装向导 Manual IPv4）

你已验证网段为 192.168.8.0/24，示例：

• Subnet：192.168.8.0/24
• Address：192.168.8.50（示例；避免与 DHCP 冲突）
• Gateway：以 Windows ipconfig 的 Default Gateway 为准（常见 192.168.8.1）
• Name servers：223.5.5.5,119.29.29.29（或 8.8.8.8,1.1.1.1）

装完验证：

ip a
ping -c 3 <gateway>
ping -c 3 223.5.5.5

3. Ubuntu：安装基础服务

sudo apt update
sudo apt upgrade -y
sudo apt install -y git openssh-server ufw
sudo systemctl enable --now ssh

防火墙（可选）：

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

4. 用户与权限（强烈建议不要用 root 当 Git 用户）

创建专用用户（示例 dev）：

sudo adduser dev
sudo usermod -aG sudo dev

创建 bare 仓库目录：

sudo mkdir -p /srv/git
sudo chown -R dev:dev /srv/git

创建 bare 仓库（示例 okx.git）：

sudo -u dev -H bash -lc 'cd /srv/git && git init --bare okx.git'

验证目录：

ls -la /srv/git/okx.git

5. bare 仓库默认分支（HEAD）对齐 main

5.1 现象

Windows 推送的是 main，但 VM 上直接：

git --git-dir=/srv/git/okx.git log -1 --oneline

可能提示 master 没有提交（因为 HEAD 仍指向 master）。

5.2 处理

先确认分支存在：

git --git-dir=/srv/git/okx.git show-ref --heads

将 HEAD 指向 main（注意权限：需要 dev 用户执行）：

sudo -u dev git --git-dir=/srv/git/okx.git symbolic-ref HEAD refs/heads/main

验证：

git --git-dir=/srv/git/okx.git log -1 --oneline main
sudo -u dev git --git-dir=/srv/git/okx.git log -1 --oneline

5.3 权限踩坑（本次真实遇到）

• 错误：Unable to create '/srv/git/okx.git/HEAD.lock': Permission denied
• 原因：bare 仓库属主是 dev，但你用另一个用户执行写操作

• 正确做法：

  • 日常维护 bare：sudo -u dev git --git-dir=/srv/git/okx.git ...
  • 或：SSH 登录用户与仓库属主一致（推荐长期一致）

不建议随意 chown 改变仓库属主；若改来改去，容易导致 git push 权限再次异常。

6. Windows：SSH Key 与首次推送

6.1 生成 SSH key（PowerShell）

ssh-keygen -t ed25519 -C "dev@okx"

6.2 公钥安装到 VM（示例）

type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh dev@192.168.8.88 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"

测试登录：

ssh dev@192.168.8.88

7. Windows：初始化仓库并 push（本次真实流程）

7.1 常见错误 A：不在 git 仓库目录

现象：

fatal: not a git repository ...

处理：先 cd 到包含 .git 的项目根目录，或 git clone 新工作区。

7.2 常见错误 B：未配置提交身份

现象：

Author identity unknown

处理（全局配置示例）：

git config --global user.name "dekun"
git config --global user.email "dekun@local"

7.3 常见错误 C：没有提交就 push

现象：

error: src refspec main does not match any

处理：先 git add + git commit 产生提交，再 push。

7.4 添加 remote 并推送

git branch -M main
git remote add origin ssh://dev@192.168.8.88:/srv/git/okx.git
git push -u origin main

推送成功标志：远端出现 refs/heads/main，本地 branch 'main' set up to track 'origin/main'。

8. 日常同步（维护）建议流程

8.1 Windows 开发机

git pull --rebase
# ...开发...
git add -A
git commit -m "feat: ..."
git push

8.2 另一台 Windows（第二台开发机）

git clone ssh://dev@192.168.8.88:/srv/git/okx.git
cd okx

8.3 VM 上查看仓库最新提交（只读）

git --git-dir=/srv/git/okx.git log -5 --oneline main

8.4 需要写操作（例如改 HEAD、hooks、gc）

统一：

sudo -u dev git --git-dir=/srv/git/okx.git <command>

9. 仓库卫生（强烈建议）

9.1 Python 缓存不要进仓库

建议 .gitignore 至少包含：

__pycache__/
*.py[cod]

9.2 密钥与大文件

• 不要把 .env、API KEY、私钥、巨型 csv/模型权重提交进 Git
• 需要大文件可用 Git LFS 或外部对象存储（另开方案）

10. 备份策略（个人也建议做）

10.1 最简单：定期 git bundle

在 VM：

sudo -u dev bash -lc 'git --git-dir=/srv/git/okx.git bundle create /backup/okx-$(date +%F).bundle --all'

10.2 复制整个 bare 目录

把 /srv/git/okx.git 复制到另一块盘 / NAS（注意权限与一致性）。

11. 本次相关“排障经验”索引（方便你以后搜）

• HEAD.lock: Permission denied：bare 属主与执行用户不一致 → 用 sudo -u dev ... 或统一 SSH 用户
• src refspec main does not match any：本地没有提交 / 没有 main → 先 commit
• Author identity unknown：未配置 user.name/email
• fatal: not a git repository：当前目录不是仓库根

12. 记录信息（请按你的实际填写）

• VM IP：192.168.8.88
• Git SSH 用户：dev
• bare 路径：/srv/git/okx.git
• 默认分支：main