第 10 课：从 GitHub 拉取项目，准备首次部署

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

本课完成标准

你能够：

• 在 ECS 的固定目录拉取指定 Git 版本；
• 确认源码、静态资源和迁移目录存在；
• 创建只存在服务器上的生产 .env；
• 检查秘密没有被 Git 跟踪；
• 为下一课构建真实项目做好准备。

本课使用你的项目 /Users/andy/Documents/code/student-management-api 作为本地参考。

1. 服务器目录应该长什么样？

建议把发布项目放在宝塔常用的网站目录下：

/www/wwwroot/student-management-api/

这不是强制路径，但后续课程中的命令会使用它。固定路径的好处是 Docker Compose、Nginx 和备份脚本都更容易复用。

GitHub（保存代码版本）
          │ git clone
          ▼
ECS 项目目录（构建和运行）

2. 在 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 branch --show-current

私有仓库需要 Deploy Key 或 GitHub Token。不要把真实 Token 写进命令 URL。第一次部署建议固定到已经测试的标签：

git fetch --tags
git checkout v1.0.0

如果仓库尚未使用标签，可以先在分支上验证；正式发布时再建立标签。

3. 检查真实项目目录

在项目根目录执行：

pwd
find . -maxdepth 2 -type f | sort
git status --short

重点确认：

路径	为什么需要
main.py	FastAPI 应用入口
database.py	数据库连接和会话逻辑
models/	SQLModel 模型
routers/、schema/、utils/	接口、数据结构和工具代码
migrations/、alembic.ini	Alembic 数据库迁移
static/	HTML、CSS、JavaScript、图片和字体

**不要把本机虚拟环境复制到服务器镜像。**项目中的 venv、pycache 和 .pyc 是本机生成物，下一课会用 .dockerignore 排除。

4. 检查 Git 是否真的忽略了秘密

在本地项目和 ECS 项目中都可以检查：

git status --short
git check-ignore -v .env venv __pycache__
git ls-files | grep -E '(^|/)(.env|venv|__pycache__)'

如果发现 .env 已被跟踪，仅添加 .gitignore 不够：先撤销并更换真实密码，再清理历史。

你的项目还需要检查 database.py、config.py、migrations/env.py 中是否存在硬编码数据库 URL、密码或密钥。任何真实凭据都应改为从环境变量读取。

5. 创建生产环境 .env

生产 .env 只存在 ECS，不从 GitHub 下载。可使用宝塔文件编辑器，或在 SSH 中创建后设置权限：

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

你的迁移配置已经使用 DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME 这些变量。先创建模板，DB_HOST 的最终值在第 13 课从容器内部验证：

DB_HOST=第13课确定
DB_PORT=3306
DB_USER=student_app
DB_PASSWORD=请填写宝塔创建的密码
DB_NAME=student_db

如果应用还有 JWT 或其他密钥，请按照 config.py 的实际变量名加入 .env。不要把真实值发到聊天或提交 GitHub。

6. 设置项目目录权限

容器构建只需要读取源码，生产配置应尽量限制读取范围：

chmod 750 /www/wwwroot/student-management-api
chmod 600 /www/wwwroot/student-management-api/.env
ls -la /www/wwwroot/student-management-api

不要使用 chmod -R 777。如果宝塔或 Docker 使用了不同的运行用户，后续根据实际报错调整属主和组权限。

7. GitHub 更新后的安全流程

本地推送新版本后，ECS 不要直接覆盖本地修改。先检查状态：

cd /www/wwwroot/student-management-api
git status
git fetch --tags
git log --oneline --decorate -3

如果服务器目录没有手动修改，才使用：

git pull --ff-only

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

git checkout v1.0.1

服务器上的 .env 不属于 Git 版本，切换代码版本不会删除它。

8. 备用方案：宝塔文件管理器上传

Git 不可用时，可以在本地把项目打包后通过宝塔文件管理器上传，再在服务器解压。但这只是临时备用方案：

• 不能替代 Git 提交和版本标签；
• 压缩包不应包含 venv、.env 和缓存；
• 生产发布仍然要记录当前版本和发布日期。

9. 一分钟自测

问题 1：生产 .env 应该从哪里获得？

• A. 只在 ECS 上创建或由安全方式注入
• B. 从 GitHub 直接下载
• C. 写入 Dockerfile

问题 2：为什么要检查 static/ 和 migrations/？

• A. 静态资源和数据库迁移是项目运行所需文件
• B. 它们只用于 GitHub 登录
• C. 它们会自动安装 Docker

答案：1A，2A。

本课通关证据

cd /www/wwwroot/student-management-api
git status
git log --oneline -3
find . -maxdepth 2 -type f | sort
ls -l .env

完成标准：ECS 有正确的项目目录和指定 Git 版本；static、migrations、main.py 存在；.env 权限为 600 且不在 Git 状态中；项目没有提交真实凭据。

如果遇到错误，请贴完整命令和输出，但隐藏密码、Token 与私钥。

---

← 第 9 课：GitHub 版本控制 · 第 11 课：整理真实项目依赖 →