共享服务器下 Git 版本管理实战（Linux/macOS/Windows）

这个场景非常典型：

• 代码仓库：https://github.com/your-username/your-repo.git
• 服务器：固定为 Linux
• 使用方式：多人共用同一个 Linux 系统用户
• 本地电脑：可能是 Linux / macOS / Windows
• 目标：既要规范用 Git 管理版本，又不能把个人凭证留在共享机器上

这篇教程把完整流程整理成可复用版本：所有仓库操作都在 Linux 服务器执行，本地电脑相关步骤按 Linux / macOS / Windows 分别给出命令。

一、先确认仓库状态（Linux 服务器）#

先进入项目目录，确认当前分支、远程地址、工作区状态：

cd /path/to/your/project
git branch --show-current
git remote -v
git status

预期重点：

• 当前分支是 main
• origin 指向你的仓库
• 先识别是否有不该提交的大目录（如 checkpoints/、outputs/、external/）

二、先做提交边界清理：补 .gitignore#

这一步的目的不是“立刻提交”，而是先把实验产物和本地依赖从源码中隔离。

示例（按你项目实际调整）：

# local configs
configs/paths.sh

# experiment artifacts
checkpoints/
outputs/
logs/

# caches
data/
.cache/

# local external deps
external/

补完后再看状态：

git status

如果结果里主要剩下源码和文档改动，说明提交边界已经干净。

三、共享账号场景下的 Git 身份配置（只配当前仓库）#

多人共用一个 Linux 用户时，不要用全局身份，避免污染他人项目。

先做前置检查：git config user.email 里要填的邮箱，必须先在 GitHub 账号里添加并完成验证。

GitHub 邮箱设置路径：

Settings -> Emails -> Add email address -> Verify

然后再回到服务器配置仓库级身份：

git config user.name "your-github-username"
git config user.email "your-email@example.com"

验证：

git config --get user.name
git config --get user.email

推荐原则：

• 用仓库级配置（不加 --global）
• 不使用 credential.helper store
• 不在共享机器长期保存个人 PAT/私钥
• 如果开启了 GitHub 邮箱隐私策略，优先使用 GitHub 提供的 noreply 邮箱做 user.email

四、把远程切到 SSH#

GitHub SSH URL 固定格式：

git@github.com:<用户名>/<仓库名>.git

例如：

git@github.com:your-username/your-repo.git

设置并验证：

git remote set-url origin git@github.com:your-username/your-repo.git
git remote -v

五、核心安全做法：用 SSH Agent Forwarding（不在服务器留私钥）#

5.1 在本地电脑准备 SSH key（按你的本机系统执行）#

如果你本地还没有 key，先生成：

• Linux / macOS

ssh-keygen -t ed25519 -C "your-email@example.com"

• Windows（PowerShell）

ssh-keygen -t ed25519 -C "your-email@example.com"

加载 key 到 agent：

• Linux / macOS

ssh-add ~/.ssh/id_ed25519
ssh-add -l

• Windows（PowerShell）

Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519
ssh-add -l

5.2 配置 SSH 别名并开启转发（本地电脑）#

配置文件路径：

• Linux / macOS：~/.ssh/config
• Windows：C:\Users\<你用户名>\.ssh\config

配置示例：

Host <server-alias>
  HostName <你的服务器IP或域名>
  User <服务器用户名>
  IdentityFile ~/.ssh/id_ed25519
  ForwardAgent yes

然后登录服务器（任意系统本机都一样）：

ssh -A <server-alias>

5.3 在 GitHub 账号里添加 SSH 公钥（关键主步骤）#

先在本地电脑读取公钥（按你的本机系统执行）：

• Linux / macOS

cat ~/.ssh/id_ed25519.pub

• Windows（PowerShell）

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

然后到 GitHub 网页完成绑定：

1. 右上角头像 -> Settings
2. 左侧进入 SSH and GPG keys
3. 点击 New SSH key
4. Key type 选择 Authentication Key
5. Title 填一个容易识别的名称（例如 my-laptop-agent-forward）
6. Key 粘贴整行公钥
7. 点击 Add SSH key

这一段必须完成，否则后面的 ssh -T git@github.com 很可能出现 Permission denied (publickey)。

5.4 在服务器上验证 agent 转发#

ssh-add -l

如果能看到你本地 key 的指纹，说明转发已生效。

六、第一次连 GitHub 的认证与排错#

在服务器上测试：

ssh -T git@github.com

你遇到过的报错是：

git@github.com: Permission denied (publickey).

这通常表示“这把公钥还没绑定到目标 GitHub 账号”，不是服务器命令错了。

解决步骤：

1. 确认你已经完成上面的 Settings -> SSH and GPG keys -> New SSH key
2. 检查粘贴的是完整公钥（包含开头 ssh-ed25519 和中间长串内容）
3. 保存后重新测试：

ssh -T git@github.com

通过标志通常是类似：Hi your-username! You've successfully authenticated...

七、开始版本管理并推送#

建议每个明确阶段做一次小提交：

git add <files>
git commit -m "feat: your change"
git push origin main

针对你的这类实验项目，推荐把提交拆小：

• chore: add gitignore for artifacts and local deps
• docs: add api compatibility notes
• feat: add baseline scripts

这样回滚和审阅都会轻松很多。

如果 git push 因邮箱策略被拒绝（常见于开启了 “Block command line pushes that expose my email”）：

1. 到 GitHub Settings -> Emails 确认邮箱已验证，或复制你的 noreply 邮箱
2. 在仓库重新设置：

git config user.email "your-noreply-email@users.noreply.github.com"

3. 用新邮箱重做提交并推送：

git commit --amend --reset-author --no-edit
git push origin main

八、共享机器最佳实践清单#

1. Git 身份用仓库级配置，不用全局。
2. 不把个人私钥长期放在共享 Linux 账号目录。
3. 不使用 credential.helper store 明文落盘 PAT。
4. 用 ssh -A 转发本地凭证，断开会话即失效。
5. 按功能阶段做小提交，避免把大文件和临时产物混入历史。

结语#

这套流程本质上做了两件事：

• 把“代码版本管理”做规范（清晰提交边界 + 小步提交）
• 把“共享账号安全”做正确（本地持有私钥 + 会话转发认证）

如果后续你要继续在这个仓库迭代，直接复用这一套即可。