DjangoAdmin_Flask_EleVue/config/app.py

"""
Flask 基础配置模块
=============================================================

包含 Flask 应用运行所需的基础配置项，如应用名称、版本、
运行地址、端口、调试模式、文件存储路径等。

依赖：config/__init__.py 中的 _load_env_file() 已提前加载 .env
"""

import os
import platform

# ============================================================
# 应用基础配置
# ============================================================

# 应用名称 - 用于界面标题、日志标识、API文档标题等
# 从环境变量读取，默认值为 DEMO
FLASK_NAME = os.getenv('FLASK_NAME', 'DEMO')

# 应用版本号 - 用于版本追踪、API版本控制和更新检测
# 格式遵循语义化版本规范 v主版本.次版本.补丁版本
FLASK_VERSION = os.getenv('FLASK_VERSION', 'v2.8.0')

# 应用秘钥 - 用于Session加密、CSRF保护、签名生成
# 生产环境务必使用强随机字符串，长度至少32字符
# 生成命令：python -c "import secrets; print(secrets.token_hex(32))"
FLASK_SECRET_KEY = os.getenv('FLASK_SECRET_KEY', '')

# 应用运行地址 - 127.0.0.1 仅本地访问，0.0.0.0 允许外部访问
# 生产环境建议使用 0.0.0.0 配合 Nginx 反向代理
FLASK_HOST = os.getenv('FLASK_HOST', '127.0.0.1')

# 应用运行端口 - 确保端口未被其他服务占用
# 常用端口：8021（开发）、80（HTTP）、443（HTTPS）
FLASK_PORT = int(os.getenv('FLASK_PORT', 8021))

# 站点域名 - 用于定时任务、邮件模板、微信回调等场景构建完整URL
# 自动根据 HOST 和 PORT 生成，生产环境建议手动配置为真实域名
FLASK_SITE_DOMAIN = f'http://{FLASK_HOST}:{FLASK_PORT}'

# 应用启动文件 - Flask 入口文件名
# 通常为 app.py 或 base.py
FLASK_APP = os.getenv('FLASK_APP', 'base.py')

# 应用环境变量 - development（开发环境）/ production（生产环境）
# 不同环境会加载不同的配置，如日志级别、调试开关等
FLASK_ENV = os.getenv('FLASK_ENV', 'development')

# 是否调试模式 - True 开启调试 / False 关闭调试
# 开发环境开启可获得详细错误信息和自动重载
# 生产环境必须设为 False，否则会暴露敏感信息
FLASK_DEBUG = os.getenv('FLASK_DEBUG', 'True') == 'True'

# 是否禁用自动重启 - True 禁用 / False 启用
# 仅在 FLASK_DEBUG=True 时生效，生产环境无关
# 设为 True 可避免频繁重启导致的问题
FLASK_USE_RELOADER = os.getenv('FLASK_USE_RELOADER', 'True') == 'True'

# 是否演示模式 - True 演示模式（限制操作权限）/ False 正常模式
# 演示模式下会禁用删除、修改等危险操作
# 默认关闭，防止 .env 缺失时误入演示模式
FLASK_DEMO = os.getenv('FLASK_DEMO', 'False') == 'True'

# 系统环境 - windows / linux / darwin（macOS）
# 用于适配不同操作系统的文件路径、命令等差异
FLASK_SYSTEM = platform.system().lower()

# ============================================================
# 路径配置
# ============================================================

# 应用根目录 - 项目的最顶层目录
# 用于定位模板、静态资源、上传文件等
FLASK_ROOT_PATH = os.path.abspath(os.path.dirname(os.path.dirname(__file__)))

# 应用模板路径 - Jinja2 模板文件存放目录
# 用于渲染 HTML 页面
FLASK_TEMPLATE_FOLDER = os.path.join(FLASK_ROOT_PATH, 'templates')

# 应用静态资源路径 - CSS、JS、图片等前端资源存放目录
# 通过 /static/ 路由访问
FLASK_STATIC_FOLDER = os.path.join(FLASK_ROOT_PATH, 'static')

# 应用文件存储路径 - 用户上传文件的存储目录
# 建议与代码分离，方便备份和迁移
FLASK_UPLOAD_DIR = os.getenv('FLASK_UPLOAD_DIR', os.path.join(FLASK_ROOT_PATH, 'uploads'))

# 临时文件路径 - 用于存放临时文件（如导入导出时的缓存）
# 建议定期清理，避免占用过多磁盘空间
FLASK_TEMP_PATH = FLASK_UPLOAD_DIR + '/temp'

# 应用图片域名 - 用于生成图片完整URL
# 生产环境应配置为CDN域名或文件服务域名
# 示例：https://cdn.example.com 或 http://images.example.com
FLASK_FILE_URL = os.getenv('FLASK_FILE_URL', '')

# ============================================================
# 文件上传安全配置
# ============================================================

# 允许上传的文件扩展名（逗号分隔，带点号）
# 生产环境务必严格配置，防止上传危险文件
# 安全扩展名：图片、文档、压缩包、音视频
# 危险扩展名：.py、.exe、.sh、.bat、.php、.jsp、.asp 等
UPLOAD_ALLOWED_EXTS = os.getenv(
    'UPLOAD_ALLOWED_EXTS',
    '.jpg,.jpeg,.png,.gif,.bmp,.webp,.svg,.ico,.txt,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.mp3,.mp4,.zip,.rar,.7z'
)

# 上传文件大小上限（MB）- 超过此大小将被拒绝上传
# 防止用户上传超大文件导致磁盘空间耗尽或带宽拥堵
# 建议根据业务需求调整：普通文件 10MB，高清图片 20MB，视频 100MB+
UPLOAD_MAX_SIZE_MB = int(os.getenv('UPLOAD_MAX_SIZE_MB', 10))

# ============================================================
# CORS 跨域配置
# ============================================================

# 允许的源（逗号分隔，如 http://localhost:8001,https://admin.example.com）
# 配置后支持携带凭证（Cookie、Authorization头等）
# 未配置则允许所有源（*）但不允许携带凭证
# 生产环境应明确列出允许的前端域名，避免使用通配符
# 示例：http://localhost:8080,https://admin.yourdomain.com
CORS_ALLOWED_ORIGINS = os.getenv('CORS_ALLOWED_ORIGINS', '')