Debian Python项目部署流程解析

Debian Python项目部署流程解析

一 环境准备与依赖管理

• 更新系统并安装基础工具与编译依赖：sudo apt update && sudo apt upgrade，随后安装 build-essential、libssl-dev、libffi-dev、zlib1g-dev、libncursesw5-dev、libgdbm-dev、libsqlite3-dev、tk-dev、libbz2-dev 等，用于保障本地编译与常见 C 扩展顺利安装。
• 安装 Python 3 与 pip：sudo apt install python3 python3-pip。
• 使用虚拟环境隔离依赖：python3 -m venv venv && source venv/bin/activate。
• 依赖管理建议：
  • 使用 requirements.txt：pip install -r requirements.txt；生成锁定文件：pip freeze > requirements.txt。
  • 复杂项目可用 pip-tools（requirements.in → pip-compile → requirements.txt → pip-sync）提升可复现性。
  • 亦可使用 Poetry 进行依赖与打包一体化管理。

二 传统部署 Gunicorn + Nginx（WSGI，适合 Flask/Django）

• 安装组件：pip install gunicorn；sudo apt install nginx。
• 启动应用（示例）：gunicorn -c gunicorn_config.py myproject.wsgi:application，其中配置可指定 bind = ‘127.0.0.1:8000’、workers = 3。
• 配置 Nginx 反向代理（/etc/nginx/sites-available/myproject）：
  • 示例：
    • server { listen 80; server_name your_domain_or_ip;
      location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }
    • 静态资源可单独 location /static/ { alias /path/to/static; }
  • 启用站点：sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled；检查配置：sudo nginx -t；重启：sudo systemctl restart nginx。
• 以 systemd 托管 Gunicorn（/etc/systemd/system/myproject.service）：
  • 示例：
    • [Unit] Description=gunicorn daemon for myproject; After=network.target
    • [Service] User=your_user; Group=www-data; WorkingDirectory=/path/to/myproject; ExecStart=/path/to/venv/bin/gunicorn -c /path/to/gunicorn_config.py myproject.wsgi:application
    • [Install] WantedBy=multi-user.target
  • 启动与开机自启：sudo systemctl daemon-reload && sudo systemctl start myproject && sudo systemctl enable myproject。
• 防火墙放行：sudo ufw allow ‘Nginx Full’。
• 可选 HTTPS：sudo apt install certbot python3-certbot-nginx；sudo certbot --nginx -d your_domain。

三 备选方案 uWSGI + Nginx（WSGI，适合高并发与复杂进程管理）

• 安装 uWSGI：pip install uwsgi。
• uWSGI 配置示例（uwsgi.ini）：
  • [uwsgi]
    • module = wsgi:app
    • master = true
    • processes = 5
    • socket = myproject.sock
    • chmod-socket = 660
    • vacuum = true
    • die-on-term = true
• Nginx 配置（/etc/nginx/sites-available/myproject）：
  • server { listen 80; server_name your_domain_or_ip;
    • location / { include uwsgi_params; uwsgi_pass unix:/tmp/uwsgi.sock; }
  • }
  • 启用站点并重启 Nginx（同上）。
• 启动 uWSGI：uwsgi --ini uwsgi.ini（生产环境建议配合 systemd 或 Emperor 管理）。

四 容器化部署 Docker（一致性与可移植性）

• 示例 Dockerfile：
  • FROM python:3.9-slim
  • WORKDIR /app
  • COPY requirements.txt .
  • RUN pip install --no-cache-dir -r requirements.txt
  • COPY . .
  • CMD [“gunicorn”, “-w”, “4”, “-b”, “0.0.0.0:8000”, “app:app”]
• 构建与运行：docker build -t my-python-app .；docker run -d -p 8000:8000 my-python-app。
• 说明：也可在 Docker 中使用 uWSGI 或 ASGI 服务器（如 Uvicorn/Hypercorn） 以适配异步框架。

五 部署后验证与常见问题处理

• 访问验证：通过 http://服务器IP或域名 检查页面与接口可达性；静态资源路径与媒体文件需与 Nginx 配置一致。
• 日志排查：
  • Nginx：/var/log/nginx/error.log、access.log
  • 应用/Gunicorn：journalctl -u myproject.service 或应用日志文件
• 防火墙与安全：启用 UFW 放行 Nginx Full；对外仅暴露 80/443，管理端口限制来源。
• 依赖冲突与可复现性：优先使用 虚拟环境；锁定依赖版本（requirements.txt 或 poetry.lock/pip-tools）；必要时分离系统包与 pip 包来源，减少冲突。
• 静态文件与媒体文件：生产环境建议由 Nginx 直接托管，提升性能与缓存命中。