第22篇|Python 项目打包与部署:让别人也能用你写的工具

这篇文章填补开发和上线之间的空白——虚拟环境规范管理、Docker 容器化、部署到云服务器、GitHub Actions 自动部署，带你走完一个 Python 项目从本地到生产的完整链路。

前言

前面做了那么多项目，但它们都只能在你自己电脑上跑。

如果想让同事、朋友或者全世界的用户访问你的工具，就需要部署（Deploy）。这是很多自学者卡住的地方：代码写好了，却不知道怎么"发出去"。

这篇文章不涉及 Kubernetes 这类复杂话题，只讲最实用的路径：

本地代码 → Docker 打包 → 上传云服务器 → 跑起来

我们用第 18 篇的 FastAPI Todo API 作为部署对象。

一、第一步：规范项目结构

部署前先整理项目，养成规范习惯：

todo-api/
├── app/
│   ├── __init__.py
│   └── main.py           # FastAPI 主程序
├── tests/
│   └── test_main.py      # 测试文件
├── .env                  # 本地环境变量（不提交）
├── .env.example          # 环境变量模板（提交）
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

.gitignore（务必配置）：

# Python
__pycache__/
*.pyc
*.pyo
.pytest_cache/
venv/
.venv/

# 环境变量（含密码，绝对不提交）
.env

# 编辑器
.vscode/
.idea/

# 系统文件
.DS_Store

.env.example（模板文件，告知他人需要哪些变量）：

# 复制此文件为 .env 并填入真实值
APP_SECRET_KEY=your_secret_key_here
DATABASE_URL=sqlite:///./todos.db
DEBUG=false

二、规范 requirements.txt

# 在虚拟环境中安装完依赖后，生成精确版本锁文件
pip freeze > requirements.txt

# requirements.txt（精确版本，保证可复现）
fastapi==0.109.0
uvicorn[standard]==0.27.0
pydantic==2.5.3
python-dotenv==1.0.0

分离生产和开发依赖（推荐）：

# requirements.txt（生产依赖）
fastapi==0.109.0
uvicorn[standard]==0.27.0

# requirements-dev.txt（开发专用，不上生产服务器）
pytest==7.4.4
httpx==0.26.0         # FastAPI 测试客户端依赖
black==23.12.1        # 代码格式化

三、Docker 容器化

3.1 为什么用 Docker？

Docker 解决了"在我电脑上能跑"的问题。容器把应用和它需要的所有环境（Python 版本、依赖包、系统库）打包在一起，在任何服务器上行为完全一致。

类比前端：Docker 就像把你的 Node.js 版本、node_modules、构建配置全部打包成一个镜像，对方拿到后直接运行，不需要自己 npm install。

3.2 编写 Dockerfile

# Dockerfile
# 使用官方 Python 3.11 精简版作为基础镜像
FROM python:3.11-slim

# 设置工作目录
WORKDIR /app

# 先复制依赖文件（利用 Docker 层缓存，依赖不变时不重新安装）
COPY requirements.txt .

# 安装依赖（不生成 .pyc 文件，不缓存 pip 包）
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

# 声明容器监听的端口（文档用途，不实际开放端口）
EXPOSE 8000

# 容器启动命令
# --host 0.0.0.0：监听所有网络接口（容器内必须这样设置）
# --workers 2：启动 2 个工作进程
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

3.3 构建和运行

# 构建镜像（在项目根目录执行）
docker build -t todo-api:latest .

# 查看构建好的镜像
docker images

# 本地运行容器测试
docker run -d \
  --name todo-api \
  -p 8000:8000 \
  -e APP_SECRET_KEY=mysecret \
  todo-api:latest

# 查看运行状态
docker ps

# 查看容器日志
docker logs todo-api

# 停止并删除容器
docker stop todo-api && docker rm todo-api

3.4 docker-compose（推荐）

docker-compose 用 YAML 文件管理容器配置，比敲一堆 docker run 参数方便很多：

# docker-compose.yml
version: "3.9"

services:
  api:
    build: .
    container_name: todo-api
    ports:
      - "8000:8000"
    environment:
      - APP_SECRET_KEY=${APP_SECRET_KEY}
      - DEBUG=false
    volumes:
      - ./data:/app/data   # 挂载数据目录，容器重启后数据不丢失
    restart: unless-stopped   # 服务器重启后自动启动

  # 可以轻松添加其他服务（数据库、Redis 等）
  # db:
  #   image: postgres:15
  #   ...

# 启动所有服务
docker-compose up -d

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f api

# 停止所有服务
docker-compose down

四、部署到云服务器

4.1 购买和配置服务器

以腾讯云轻量应用服务器为例（阿里云 ECS 操作类似）：

1. 购买最低配置（2核2G，约 24 元/月，够用了）
2. 选择 Ubuntu 22.04 系统
3. 设置安全组规则，开放 22（SSH）、80（HTTP）、443（HTTPS）、8000 端口

4.2 服务器初始化

# SSH 连接服务器
ssh ubuntu@your_server_ip

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Docker（官方一键脚本）
curl -fsSL https://get.docker.com | sh

# 把当前用户加入 docker 组（避免每次都要 sudo）
sudo usermod -aG docker $USER

# 安装 docker-compose
sudo apt install docker-compose-plugin -y

# 验证安装
docker --version
docker compose version

4.3 上传代码并启动

# 方式一：git clone（推荐，有代码仓库的情况下）
git clone https://github.com/yourname/todo-api.git
cd todo-api

# 配置环境变量
cp .env.example .env
nano .env   # 填入真实的密钥

# 启动
docker compose up -d

# 验证
curl http://localhost:8000
# {"message":"Hello FastAPI！"}

五、GitHub Actions 自动部署

每次改完代码，手动 SSH 上去 git pull 再重启，太繁琐了。用 GitHub Actions 实现自动化：推送代码到 main 分支，自动部署到服务器。

5.1 配置 GitHub Secrets

在 GitHub 仓库 → Settings → Secrets and variables → Actions 里添加：

5.2 编写 CI/CD 工作流

# .github/workflows/deploy.yml
name: Deploy to Server

on:
  push:
    branches: [main]   # 推送到 main 分支时触发

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      # 1. 检出代码
      - name: Checkout code
        uses: actions/checkout@v4

      # 2. SSH 连接服务器并部署
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            cd ~/todo-api

            # 拉取最新代码
            git pull origin main

            # 重新构建并启动容器（--build 强制重新构建镜像）
            docker compose up -d --build

            # 清理旧镜像（节省磁盘空间）
            docker image prune -f

            echo "✅ 部署完成！"

推送代码后，在 GitHub → Actions 页面可以看到工作流执行情况。

六、验证部署

# 在服务器上检查容器状态
docker compose ps

# 测试 API 是否正常
curl http://your_server_ip:8000
curl http://your_server_ip:8000/docs

# 查看实时日志
docker compose logs -f --tail=50

访问 http://your_server_ip:8000/docs，看到 Swagger 文档就说明部署成功了！

小结

一次性配置，长期受益：

配置好 GitHub Actions 之后，以后每次改完代码只需要 git push，服务器会在 30 秒内自动更新。这套流程对任何 Python Web 项目都通用，不局限于 FastAPI。

3 个关键习惯：

1. .env 绝对不提交，用 .env.example 做模板
2. requirements.txt 锁定精确版本，避免"今天能跑明天不行"
3. Dockerfile 先 COPY requirements.txt 再 pip install，充分利用层缓存，构建更快

下篇预告

第 23 篇：Python 调用 AI 大模型 API：OpenAI / Claude / 国内模型全对比

部署能力有了，下一篇进入最热门的方向——调用 AI 大模型 API。OpenAI、Claude、通义、Kimi，每个都跑通一遍，还有打字机效果的流式输出实现。