AutoDL -使用 Git 结合 GitHub 管理代码（笔记）

核心目标：

在 AutoDL 服务器上方便地获取、修改和同步代码。

利用 GitHub 作为中央代码仓库，实现版本控制、备份和协作。

保持本地开发环境（如果有的话）与 AutoDL 服务器环境的代码同步。

全流程步骤：

阶段一：准备工作 (在本地和 GitHub 上)

1. 拥有 GitHub 账户: 如果没有，先去 GitHub官网 注册一个账户。
2. 创建 GitHub 仓库 (Repository):
   • 登录 GitHub。
   • 点击右上角的 "+" 号，选择 "New repository"。
   • 填写仓库名称（例如 my-dl-project）。
   • 选择 Public (公开) 或 Private (私有)。私有仓库现在免费用户也可以创建。
   • 建议：勾选 "Add a README file" (会自动初始化仓库，方便后续克隆)。
   • 可选：可以添加 .gitignore 文件（选择 Python 模板可以自动忽略一些常见文件，如 __pycache__、虚拟环境等）和 license (许可证)。
   • 点击 "Create repository"。

阶段二：配置 AutoDL 服务器环境

1. 连接到 AutoDL 服务器: 通过 SSH 客户端（如 MobaXterm, Termius, 或系统自带的 ssh 命令）连接到你的 AutoDL 实例。

2. 检查/安装 Git:

   • 在服务器终端输入 git --version 检查 Git 是否已安装。
   • 如果未安装（或版本过低），根据 AutoDL 提供的操作系统（通常是 Ubuntu/Debian）进行安装： 

     sudo apt update
     sudo apt install git -y
     

3. 配置 Git 用户信息:

   • 设置你的 Git 用户名和邮箱，这会出现在你的提交记录里。强烈建议使用与你 GitHub 账户关联的邮箱。 

     git config --global user.name "Your Name"  # 替换成你的 GitHub 用户名或真实姓名
     git config --global user.email "youremail@example.com" # 替换成你的 GitHub 注册邮箱
     

   • 你可以通过 git config --list 来查看配置是否成功。

4. 配置 AutoDL 与 GitHub 的连接方式 (选择一种):

   • 方式一：HTTPS + PAT (个人访问令牌) - 推荐初学者

     • 优点: 配置相对简单，不需要管理 SSH 密钥。
     • 缺点: 每次 push/pull 可能需要输入用户名和 PAT（可以通过 Git Credential Manager 缓存）。
     • 步骤:
       1. 生成 PAT:
          • 登录 GitHub -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic) 或 Fine-grained tokens。
          • 点击 "Generate new token" (选择 classic 或 fine-grained，classic 更简单通用)。
          • 给 Token 起个名字 (e.g., autodl-access)。
          • 设置过期时间 (Expiration)。
          • 关键: 勾选权限 (Scopes)。对于基本的克隆、推送、拉取，勾选 repo 权限即可。
          • 点击 "Generate token"。
          • 立即复制生成的 Token (例如 ghp_xxxxxxxx)，这个 Token 只会显示一次，请妥善保管。
       2. 使用: 当你在 AutoDL 上执行需要认证的操作 (如 git clone, git push) 时，如果提示输入密码 (Password for 'https://github.com')，请输入你刚刚生成的 PAT，而不是你的 GitHub 登录密码。
       3. (可选) 缓存凭证: 为了避免每次都输入 PAT，可以配置 Git 凭证助手： 

          git config --global credential.helper store # 简单存储，但密码明文保存在 ~/.git-credentials
          # 或者更安全的选项 (可能需要额外安装)
          # git config --global credential.helper cache # 默认缓存15分钟
          # git config --global credential.helper 'cache --timeout=3600' # 缓存1小时
          

          首次输入 PAT 后，后续操作在缓存有效期内将不再需要输入。

   • 方式二：SSH - 推荐长期使用

     • 优点: 更安全，配置好后 push/pull 无需重复输入密码/令牌。
     • 缺点: 配置步骤稍多。
     • 步骤:
       1. 在 AutoDL 服务器上生成 SSH 密钥对: 

          ssh-keygen -t ed25519 -C "youremail@example.com" # 推荐使用 ed25519 算法，替换成你的 GitHub 邮箱
          # 或者使用 RSA 算法: ssh-keygen -t rsa -b 4096 -C "youremail@example.com"
          

          • 会提示你保存密钥文件的位置（默认是 ~/.ssh/id_ed25519 或 ~/.ssh/id_rsa），直接回车即可。
          • 会提示你设置密码 (passphrase)，可以设置一个增加安全性，也可以直接回车留空（留空的话后续操作更方便，但私钥安全性稍低）。
       2. 将公钥添加到 GitHub:
          • 查看并复制公钥内容： 

            cat ~/.ssh/id_ed25519.pub # 如果你生成的是 ed25519
            # 或者 cat ~/.ssh/id_rsa.pub # 如果你生成的是 rsa
            

          • 登录 GitHub -> Settings -> SSH and GPG keys -> New SSH key。
          • 给 Key 起个标题 (e.g., autodl-server)。
          • 将刚才复制的公钥内容粘贴到 "Key" 文本框中。
          • 点击 "Add SSH key"。
       3. 测试 SSH 连接: 

          ssh -T git@github.com
          

          • 首次连接会询问 Are you sure you want to continue connecting (yes/no/[fingerprint])? 输入 yes。
          • 如果看到类似 Hi YourUsername! You've successfully authenticated, but GitHub does not provide shell access. 的消息，说明 SSH 配置成功。如果设置了 passphrase，这里会要求输入。

阶段三：核心 Git 工作流

1. 克隆 (Clone) 仓库到 AutoDL:

   • 进入你希望存放项目的 AutoDL 服务器目录 (例如 cd /root/autodl-tmp)。
   • 去 GitHub 仓库页面，点击绿色的 "Code" 按钮。
   • 根据你选择的连接方式，复制对应的 URL:
     • HTTPS: 复制 https://github.com/YourUsername/my-dl-project.git
     • SSH: 复制 git@github.com:YourUsername/my-dl-project.git
   • 在 AutoDL 终端执行克隆命令： 

     # 使用 HTTPS (如果选择方式一)
     git clone https://github.com/YourUsername/my-dl-project.git
     
     # 使用 SSH (如果选择方式二)
     git clone git@github.com:YourUsername/my-dl-project.git
     

   • 这会在当前目录下创建一个名为 my-dl-project 的文件夹，并将 GitHub 仓库的所有内容下载下来。
   • 进入项目目录：cd my-dl-project

2. 日常开发与修改:

   • 在 AutoDL 上使用你喜欢的编辑器（如 vim, nano, 或通过 VS Code Remote SSH 等）修改代码文件。
   • 添加新的文件。

3. 查看状态 (Status):

   • 在项目目录下，随时可以使用 git status 查看当前文件的状态（哪些文件被修改了、哪些是新增的、哪些在暂存区）。

4. 添加 (Add) 更改到暂存区:

   • 将你想要提交的更改添加到暂存区。
   • 添加单个文件：git add path/to/your/file.py
   • 添加所有修改和新建的文件：git add .

5. 提交 (Commit) 更改到本地仓库:

   • 将暂存区的更改提交到本地 Git 仓库，并附带一条描述性的消息。 

     git commit -m "Your descriptive commit message"
     # 例如: git commit -m "feat: Implement data loading module"
     # 例如: git commit -m "fix: Correct calculation error in loss function"
     

   • 良好的 Commit Message 非常重要，有助于追踪历史记录。

6. 拉取 (Pull) 远程更新 (非常重要！):

   • 在推送 (Push) 自己的更改之前，或者开始工作之前， 养成先拉取远程仓库最新更改的习惯，以避免或减少冲突。 

     git pull origin main # 或者你当前工作的分支名，例如 master
     

   • 如果远程仓库有你本地没有的更新，这会将它们合并到你的本地仓库。
   • 处理冲突 (Merge Conflicts): 如果你本地的修改和远程拉下来的更新修改了同一个文件的同一部分，Git 可能无法自动合并，会产生冲突。你需要：
     • git status 会提示哪些文件有冲突。
     • 手动编辑这些文件，解决冲突标记 (<<<<<<<, =======, >>>>>>>)，保留你想要的代码。
     • 解决冲突后，再次 git add <conflicted_file>。
     • 然后 git commit (可以不用 -m，Git 会自动生成一个合并的提交信息，你也可以修改它)。

7. 推送 (Push) 本地提交到 GitHub:

   • 将你本地的提交上传到 GitHub 远程仓库。 

     git push origin main # 或者你当前工作的分支名
     

   • 如果是第一次推送一个新分支，可能需要使用 git push -u origin <branch_name> 来建立本地分支与远程分支的关联。

阶段四：进阶与最佳实践

1. 分支 (Branching):

   • 不要直接在 main (或 master) 分支上进行大量的开发工作。
   • 为新功能、修复 Bug 等创建新的分支：git checkout -b feature/new-data-augmentation
   • 在新分支上进行开发、Add、Commit。
   • 完成后，切换回主分支 (git checkout main)，拉取最新代码 (git pull origin main)。
   • 合并你的功能分支：git merge feature/new-data-augmentation (或者在 GitHub 上发起 Pull Request 进行 Code Review 后合并)。
   • 推送主分支和（可选）删除已合并的本地分支：git push origin main, git branch -d feature/new-data-augmentation。

2. .gitignore 文件:

   • 这是非常重要的文件，用于告诉 Git 忽略哪些文件或目录，避免将不需要或敏感的文件（如大型数据集、模型权重、日志文件、虚拟环境、API 密钥、配置文件中的密码等）提交到仓库。
   • 在项目根目录创建 .gitignore 文件。
   • 示例内容 (针对 Python ML 项目): 代码段

     # PyCharm files
     .idea/
     
     # Python cache files
     __pycache__/
     *.pyc
     *.pyo
     
     # Virtual environment
     venv/
     env/
     .env
     
     # Data files (often large, manage separately)
     data/
     *.csv
     *.tsv
     *.json
     *.pkl
     *.npy
     *.npz
     
     # Model checkpoints (large)
     checkpoints/
     models/
     *.pt
     *.pth
     *.h5
     *.ckpt
     
     # Logs
     logs/
     *.log
     
     # Jupyter Notebook checkpoints
     .ipynb_checkpoints/
     
     # OS generated files
     .DS_Store
     Thumbs.db
     
     # Secrets (NEVER commit secrets!)
     secrets.yaml
     config.ini # If it contains sensitive info
     *.key
     

   • 注意: .gitignore 应该在这些文件被 git add 之前创建和配置。如果已经添加了不想跟踪的文件，需要先用 git rm --cached <file> 将其从暂存区移除，然后再添加到 .gitignore。

3. 处理大数据文件/模型:

   • Git 本身不适合管理非常大的二进制文件（如>100MB的数据集、模型权重）。
   • 方案一（推荐）: 不将它们纳入 Git 版本控制。使用云存储（如 AutoDL 自带的数据集、对象存储服务 S3/OSS 等）管理这些大文件，在代码中读取它们。
   • 方案二: 使用 Git LFS (Large File Storage)。这是一个 Git 扩展，可以将大文件存储在单独的服务器上，而在 Git 仓库中只保存指向这些文件的指针。需要在本地和服务器都安装和配置 Git LFS (git lfs install)，并使用 git lfs track "*.pth" 等命令指定要跟踪的大文件类型。

4. 同步本地和服务器:

   • 如果你在本地也开发，流程类似：在本地修改 -> Add -> Commit -> Pull -> Push。
   • 然后在 AutoDL 服务器上 git pull origin main 来获取本地推送的更新。
   • 反之亦然，在服务器上修改并 Push 后，在本地 git pull。

总结:

这个流程的核心就是 Clone -> (Pull) -> Modify -> Add -> Commit -> (Pull) -> Push 的循环。理解每个命令的作用，养成良好的提交习惯（小步提交、清晰的提交信息），善用分支和 .gitignore，就能有效地在 AutoDL 这类服务器上利用 Git 和 GitHub 管理你的代码了。对于连接方式，SSH 更为长久方便，HTTPS+PAT 更易上手。