从零开始构建一个生产级 Flask Web 应用：实战指南

myflaskapp/
├── app/                          # 核心代码
│   ├── __init__.py               # 应用工厂
│   ├── config.py                 # 多环境配置
│   ├── extensions.py             # 所有扩展统一注册
│   ├── models/                   # SQLAlchemy 模型
│   │   └── user.py
│   ├── auth/                     # 认证蓝图
│   │   ├── __init__.py
│   │   ├── forms.py
│   │   ├── routes.py
│   │   └── templates/auth/
│   ├── main/                     # 主蓝图
│   │   └── routes.py
│   ├── admin/                    # Flask-Admin 或自定义后台
│   ├── api/                      # RESTful API 蓝图（可选）
│   ├── static/                   # CSS/JS（建议用 Vite 构建）
│   ├── templates/                # Jinja2 模板
│   └── utils/                    # 工具函数
├── migrations/                   # Alembic 迁移
├── tests/                        # pytest 测试
├── instance/                     # 生产数据库（Git 忽略）
├── .env                          # 环境变量
├── .flaskenv                     # Flask CLI 变量
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
├── gunicorn.conf.py
└── run.py                        # 生产入口

# app/__init__.py
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager
from flask_wtf.csrf import CSRFProtect
from flask_talisman import Talisman
from flask_compress import Compress

# 全局扩展实例（延迟初始化）
db = SQLAlchemy()
migrate = Migrate()
login_manager = LoginManager()
csrf = CSRFProtect()
compress = Compress()

def create_app(config_name=None):
    app = Flask(__name__, instance_relative_config=True)
    
    # 加载配置
    app.config.from_object('app.config.DefaultConfig')
    if config_name:
        app.config.from_object(f'app.config.{config_name}')
    app.config.from_envvar('FLASK_CONFIG_FILE', silent=True)
    app.config.from_pyfile('../instance/config.py', silent=True)

    # 初始化扩展
    db.init_app(app)
    migrate.init_app(app, db)
    login_manager.init_app(app)
    login_manager.login_view = 'auth.login'
    login_manager.login_message_category = 'warning'
    csrf.init_app(app)
    compress.init_app(app)
    
    # HTTPS 强制 + 安全头（生产必备）
    Talisman(app, 
             force_https=True,
             strict_transport_security=True,
             session_cookie_secure=True,
             content_security_policy={
                 'default-src': "'self'",
                 'script-src': "'self' 'unsafe-inline'",
                 'style-src': "'self' 'unsafe-inline'"
             })

    # 注册蓝图
    from .auth import auth_bp
    from .main import main_bp
    from .admin import admin_bp
    
    app.register_blueprint(auth_bp, url_prefix='/auth')
    app.register_blueprint(main_bp)
    app.register_blueprint(admin_bp, url_prefix='/admin')

    # 自定义错误页面
    @app.errorhandler(404)
    def not_found(e):
        return render_template('errors/404.html'), 404

    @app.errorhandler(500)
    def server_error(e):
        return render_template('errors/500.html'), 500

    return app

# app/config.py
import os
from datetime import timedelta

class DefaultConfig:
    SECRET_KEY = os.environ.get('SECRET_KEY') or 'dev-key-change-me'
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or \
        'postgresql://user:pass@localhost/myflaskapp'
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    
    # Session & Cookie 安全
    SESSION_COOKIE_HTTPONLY = True
    SESSION_COOKIE_SAMESITE = 'Lax'
    PERMANENT_SESSION_LIFETIME = timedelta(days=7)
    
    # 文件上传
    MAX_CONTENT_LENGTH = 16 * 1024 * 1024  # 16MB
    UPLOAD_FOLDER = '/var/www/myflaskapp/uploads'

class ProductionConfig(DefaultConfig):
    DEBUG = False
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')

class DevelopmentConfig(DefaultConfig):
    DEBUG = True
    SQLALCHEMY_ECHO = True

# app/models/user.py
from app.extensions import db, login_manager
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash

class User(UserMixin, db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    password_hash = db.Column(db.String(255))
    is_admin = db.Column(db.Boolean, default=False)
    created_at = db.Column(db.DateTime, default=db.func.now())

    def set_password(self, password):
        self.password_hash = generate_password_hash(password)

    def check_password(self, password):
        return check_password_hash(self.password_hash, password)

@login_manager.user_loader
def load_user(id):
    return User.query.get(int(id))

# Dockerfile（多阶段构建，体积仅 85MB）
FROM python:3.12-slim as builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
EXPOSE 8000
CMD ["gunicorn", "-c", "gunicorn.conf.py", "run:app"]

# gunicorn.conf.py
workers = 4
worker_class = "gevent"          # 推荐 gevent，支持 WebSocket
threads = 4
bind = "0.0.0.0:8000"
accesslog = "/var/log/gunicorn/access.log"
errorlog = "/var/log/gunicorn/error.log"
loglevel = "info"
timeout = 120
keepalive = 5