签入版本

config/app.py

@@ -0,0 +1,126 @@
+"""
+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', 'v3.0.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', '')