第 9 课：用 GitHub 管理项目版本

第三阶段 · 阿里云 ECS 与宝塔面板 · 面向 macOS 和 Windows 的 Docker 初学者

本课完成标准

你能够：

• 解释 Git、GitHub、仓库、提交和标签；
• 把 student-management-api 推送到 GitHub；
• 用 .gitignore 排除 venv、缓存和秘密；
• 在 ECS 上使用 clone 拉取项目；
• 使用标签发布指定版本；
• 为生产环境单独保存 .env。

1. 先理解 Git、GitHub 和 ECS

本地 Git（提交代码版本）
          │ push / pull
          ▼
GitHub 仓库（远程保存和协作）
          │ clone / pull
          ▼
ECS（构建和运行发布版本）

名词	小白解释
仓库 repository	项目文件和历史记录的集合
提交 commit	对当前代码状态拍一张有说明的快照
分支 branch	一条独立的开发线，例如 main
标签 tag	给某个提交取一个版本名，例如 v1.0.0
clone	第一次把远程仓库复制到服务器
pull	服务器更新已经存在的仓库

2. 检查本地 Git

macOS Terminal 和 Windows PowerShell 都可以运行：

git --version

如果没有 Git，使用 Git 官方下载页面 安装。然后进入真实项目目录：

# macOS
cd /Users/andy/Documents/code/student-management-api

# Windows PowerShell（替换为你的实际路径）
cd C:\path\to\student-management-api

git status

git status 会告诉你当前目录是不是 Git 仓库，以及哪些文件有变化。不要在错误的父目录执行 git init，否则可能把多个项目放进同一个仓库。

3. 创建 .gitignore，先保护秘密

在项目根目录创建 .gitignore：

venv/
.venv/
__pycache__/
*.py[cod]
.env
.env.*
!.env.example
.DS_Store
.vscode/
.idea/
.pytest_cache/
.mypy_cache/
htmlcov/
*.log

真实项目的 static、migrations、源码和依赖文件通常需要提交；本机虚拟环境、缓存、日志和生产密码不应该提交。

**注意：**如果 .env 以前已经被提交过，仅添加 .gitignore 不会自动删除历史。应立即撤销凭据、修改密码，再清理 Git 历史。

可以创建一个不含真实密码的 .env.example：

DB_HOST=填写服务器内部地址
DB_PORT=3306
DB_NAME=student_db
DB_USER=student_app
DB_PASSWORD=请填写生产环境密码
SECRET_KEY=请生成随机值

4. 初始化、提交和推送

如果项目还没有 Git 仓库：

git init
git branch -M main
git add .
git status
git commit -m "chore: prepare project for deployment"

先阅读 git status，确认没有 .env、密码、私钥或本机 venv。然后在 GitHub 创建一个仓库，建议先设为 Private，再复制仓库地址：

git remote add origin https://github.com/你的账号/student-management-api.git
git push -u origin main

如果已经有 origin，先查看：

git remote -v

不要把 Token 直接写进 remote URL，也不要把 Token 发给老师或提交到命令记录。

5. 用提交和标签标记发布版本

git log --oneline -5
git status
git tag -a v1.0.0 -m "first production candidate"
git push origin v1.0.0

标签指向一个确定的提交。以后服务器可以拉取 v1.0.0，而不是依赖某个随时变化的分支。

**发布习惯：**提交信息写“做了什么”，例如 fix: validate student number，不要只写 update。

6. 在 ECS 上拉取项目

通过 SSH 登录 ECS，在适合的目录执行：

mkdir -p /www/wwwroot
cd /www/wwwroot
git clone https://github.com/你的账号/student-management-api.git
cd student-management-api
git status
git checkout v1.0.0

如果仓库是公开的，这种 clone 可以直接完成。生产项目更建议使用 Private 仓库，并使用 SSH Deploy Key 或 GitHub Token 进行认证。

方式	适合场景	注意事项
SSH Deploy Key	ECS 只读拉取一个仓库	私钥只保存在 ECS，公钥配置到该仓库
Fine-grained Token	需要 HTTPS 拉取	限制仓库和权限，定期轮换
宝塔文件管理器	Git 暂时不可用的备用上传	不能替代版本记录

不要把 SSH 私钥、GitHub Token、数据库密码写进代码、Dockerfile、compose.yaml 或聊天内容。

7. 发布新版本

本地修改后：

git add .
git commit -m "feat: improve student list"
git push origin main

服务器更新前先查看当前版本，再拉取：

cd /www/wwwroot/student-management-api
git fetch --tags
git pull --ff-only
git log --oneline -3

更稳妥的生产方式是切换到经过测试的标签：

git fetch --tags
git checkout v1.0.1

真实发布会在后续课程中接 Docker Compose、迁移和回滚流程。

8. 生产环境 .env 放在哪里？

将生产配置放在 ECS 项目目录或宝塔管理的安全位置，但确保它被 .gitignore 排除：

cd /www/wwwroot/student-management-api
touch .env
chmod 600 .env

在第 12、13 课中，Compose 会读取这个文件。不要在课程文件或聊天中填写真实密码。

9. 一分钟自测

问题 1：为什么要把 .env 写进 .gitignore？

• A. 防止数据库密码和密钥进入仓库
• B. 让 Git 自动安装 Python
• C. 让 Docker 删除镜像

问题 2：ECS 第一次获取远程项目通常使用什么命令？

• A. git clone
• B. git erase
• C. docker pull student-management-api

答案：1A，2A。

本课通关证据

git status
git log --oneline -3
git tag

# ECS
git clone ...
git checkout v1.0.0

完成标准：GitHub 有项目代码和版本标签；.env 没有被提交；ECS 能拉取指定版本；认证凭据没有写入代码或命令 URL。

如果遇到错误，请贴操作系统、完整命令和完整输出，并隐藏 Token、私钥和数据库密码。

参考：GitHub Git 入门。

---

← 第 8 课：通过宝塔安装 MySQL · 第 10 课：ECS 项目准备 →