Python Web项目打包（Wheel）与服务器部署全流程

以下是使用Wheel打包Python Web项目并部署到服务器的完整方案，以Flask/Django项目为例：

---

一、本地开发环境准备

# 项目结构示例
mywebapp/
├── src/                  # 源码目录
│   ├── __init__.py
│   ├── app.py            # Flask主应用
│   └── views.py
├── requirements.txt      # 依赖文件
├── setup.py              # 打包配置
└── wsgi.py               # WSGI入口

二、创建setup.py打包配置

# setup.py
from setuptools import setup, find_packages

setup(
    name="mywebapp",
    version="0.1.0",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    install_requires=[
        "flask>=2.0.0",
        "gunicorn>=20.0.0",
        # 其他依赖...
    ],
    entry_points={
        'console_scripts': [
            'webapp-start = wsgi:run_app'  # 启动命令
        ]
    },
    include_package_data=True,  # 包含静态文件
    python_requires=">=3.8",
)

三、创建WSGI入口文件

# wsgi.py
from src.app import create_app

def run_app():
    app = create_app()
    app.run(host='0.0.0.0', port=5000)
    
if __name__ == "__main__":
    run_app()

四、打包生成Wheel文件

# 安装构建工具
pip install wheel setuptools

# 生成wheel包
python setup.py bdist_wheel

# 生成文件：dist/mywebapp-0.1.0-py3-none-any.whl

---

五、服务器端部署流程

1. 传输文件到服务器

scp dist/mywebapp-0.1.0-py3-none-any.whl user@server:/opt/webapps/
scp requirements.txt user@server:/opt/webapps/

2. 服务器环境准备

# 创建虚拟环境
python -m venv /opt/venvs/webapp-venv
source /opt/venvs/webapp-venv/bin/activate

# 安装wheel和依赖
pip install --upgrade pip
pip install wheel
pip install mywebapp-0.1.0-py3-none-any.whl

# 或直接从requirements安装
pip install -r requirements.txt

3. 配置生产环境变量

# 创建环境配置文件
echo "export FLASK_ENV=production" >> /etc/profile.d/webapp.sh
echo "export SECRET_KEY='your_prod_key'" >> /etc/profile.d/webapp.sh
source /etc/profile

4. 使用Gunicorn启动服务

# 直接启动
gunicorn "wsgi:run_app()" -w 4 -b 0.0.0.0:8000

# 或使用打包时注册的命令
webapp-start --daemon

---

六、高级部署方案（Systemd服务）

1. 创建Systemd服务文件

# /etc/systemd/system/webapp.service
[Unit]
Description=My Web Application
After=network.target

[Service]
User=webuser
Group=www-data
WorkingDirectory=/opt/webapps
EnvironmentFile=/etc/webapp_env
ExecStart=/opt/venvs/webapp-venv/bin/gunicorn "wsgi:run_app()" -w 4 -b 0.0.0.0:8000
Restart=always

[Install]
WantedBy=multi-user.target

2. 环境变量文件

# /etc/webapp_env
FLASK_ENV=production
DATABASE_URL=postgresql://user:pass@db:5432/proddb
SECRET_KEY=your_secure_key

3. 启动服务

sudo systemctl daemon-reload
sudo systemctl start webapp
sudo systemctl enable webapp

---

七、部署优化技巧

1. 静态文件处理 - 配置Nginx反向代理：

# /etc/nginx/sites-available/webapp
server {
    listen 80;
    server_name yourdomain.com;

    location /static/ {
        alias /opt/webapps/static/;
        expires 30d;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

2. 自动化部署脚本：

#!/bin/bash
# deploy.sh
rsync -avz --exclude='.git/' ./ user@server:/opt/webapps/
ssh user@server "cd /opt/webapps && 
               source /opt/venvs/webapp-venv/bin/activate && 
               pip install --upgrade mywebapp-*.whl &&
               sudo systemctl restart webapp"

3. 配置健康检查：

# 在app.py中添加
@app.route('/health')
def health_check():
    return jsonify(status="OK"), 200

---

八、版本更新流程

1. 修改代码后更新版本号（setup.py）
2. 重新构建wheel包
3. 上传新wheel文件到服务器
4. 在虚拟环境中升级：

pip install --upgrade mywebapp-0.2.0-py3-none-any.whl

5. 重启服务：

sudo systemctl restart webapp

---

九、方案优势

1. 隔离性强：虚拟环境隔离依赖
2. 可重复部署：wheel文件包含所有代码
3. 版本管理：精确控制部署版本
4. 服务化：Systemd保证进程持续运行
5. 资源优化：Nginx处理静态文件减轻Python压力

通过此方案，您可以实现Python Web项目的标准化打包和可靠的生产环境部署，适用于Flask、Django、FastAPI等主流Web框架。