feat(ops): 环境变量化配置 + 健康检查 + 启动脚本 + 部署/安全文档
主要变更： config - 引入 python-dotenv，从 .env 加载 SECRET_KEY / MAIL_* / SQLALCHEMY_DATABASE_URI - 拆分 BaseConfig / DevConfig / ProConfig，PEAR_ENV 控制切换 - ProConfig 在 init_app() 校验 SECRET_KEY，禁止使用默认值 ops - 新增 /healthz 端点：DB 探活 + 环境名 + 时间戳，失败返回 503 - 新增 start.bat (Windows) / Makefile (跨平台) 一键启动 / 初始化 - 新增 .env.example 模板；.gitignore 排除 .env / logs / vscode 等 - 新增 docs/DEPLOY.md（部署指南）和 docs/SECURITY.md（安全清单） - app.py 不再硬编码 debug=False，交给配置类决定 本提交不包含上一次会话的其它工作树修改（模板/导航相关），后续单独 PR。
This commit is contained in:
bwstudio
@@ -1,24 +1,40 @@
|
||||
import os
|
||||
|
||||
from dotenv import load_dotenv
|
||||
from flask import Flask
|
||||
|
||||
from applications.common.script import init_script
|
||||
from applications.config import BaseConfig
|
||||
from applications.config import BaseConfig, get_config_by_name
|
||||
from applications.extensions import init_plugs
|
||||
from applications.view import init_bps
|
||||
|
||||
# 项目根目录 = 本文件父目录的父目录
|
||||
BASE_DIR = os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
|
||||
|
||||
|
||||
def create_app():
|
||||
app = Flask(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
|
||||
# 1) 先加载 .env（在 BaseConfig 读取 os.environ 之前）
|
||||
# override=False：环境变量优先级高于 .env，便于 CI/CD 在部署时再覆盖
|
||||
load_dotenv(os.path.join(BASE_DIR, ".env"), override=False)
|
||||
|
||||
# 引入配置
|
||||
app.config.from_object(BaseConfig)
|
||||
app = Flask(BASE_DIR)
|
||||
|
||||
# 注册flask组件
|
||||
# 2) 根据 PEAR_ENV / FLASK_ENV 选择配置类，默认 dev
|
||||
env_name = os.environ.get("PEAR_ENV") or os.environ.get("FLASK_ENV") or "dev"
|
||||
config_cls = get_config_by_name(env_name)
|
||||
app.config.from_object(config_cls)
|
||||
|
||||
# 3) 把 BaseConfig 默认值里没写、但 .env 可能写了的 SQLALCHEMY_DATABASE_URI 等再覆盖一次
|
||||
if os.environ.get("SQLALCHEMY_DATABASE_URI"):
|
||||
app.config["SQLALCHEMY_DATABASE_URI"] = os.environ["SQLALCHEMY_DATABASE_URI"]
|
||||
|
||||
# 3.5) 让配置类有机会做运行时校验（例如 ProConfig 强制要求 SECRET_KEY）
|
||||
if hasattr(config_cls, "init_app"):
|
||||
config_cls.init_app(app)
|
||||
|
||||
# 4) 注册 flask 组件 / 蓝图 / 命令
|
||||
init_plugs(app)
|
||||
|
||||
# 注册蓝图
|
||||
init_bps(app)
|
||||
|
||||
# 注册命令
|
||||
init_script(app)
|
||||
|
||||
return app
|
||||
|
||||
+105
-59
@@ -1,84 +1,130 @@
|
||||
import logging
|
||||
import os
|
||||
import secrets
|
||||
from datetime import timedelta
|
||||
|
||||
|
||||
class BaseConfig:
|
||||
# 超级管理员账号
|
||||
SUPERADMIN = 'admin'
|
||||
def _env_bool(key: str, default: bool = False) -> bool:
|
||||
"""读取布尔环境变量，兼容 true/1/yes/on（大小写不敏感）。"""
|
||||
val = os.environ.get(key)
|
||||
if val is None:
|
||||
return default
|
||||
return val.strip().lower() in {"1", "true", "yes", "on"}
|
||||
|
||||
# 系统名称
|
||||
|
||||
def _env_str(key: str, default: str = "") -> str:
|
||||
val = os.environ.get(key)
|
||||
return val if val is not None and val != "" else default
|
||||
|
||||
|
||||
class BaseConfig:
|
||||
"""通用配置：所有环境共有的项。子类按需覆盖。"""
|
||||
|
||||
# ---- 应用基础 ----
|
||||
SUPERADMIN = 'admin'
|
||||
SYSTEM_NAME = 'Pear Admin'
|
||||
|
||||
# 主题面板的链接列表配置
|
||||
SYSTEM_PANEL_LINKS = [
|
||||
{
|
||||
"icon": "layui-icon layui-icon-auz",
|
||||
"title": "官方网站",
|
||||
"href": "http://www.pearadmin.com"
|
||||
},
|
||||
{
|
||||
"icon": "layui-icon layui-icon-auz",
|
||||
"title": "开发文档",
|
||||
"href": "http://www.pearadmin.com"
|
||||
},
|
||||
{
|
||||
"icon": "layui-icon layui-icon-auz",
|
||||
"title": "开源地址",
|
||||
"href": "https://gitee.com/Jmysy/Pear-Admin-Layui"
|
||||
}
|
||||
{"icon": "layui-icon layui-icon-auz", "title": "官方网站", "href": "http://www.pearadmin.com"},
|
||||
{"icon": "layui-icon layui-icon-auz", "title": "开发文档", "href": "http://www.pearadmin.com"},
|
||||
{"icon": "layui-icon layui-icon-auz", "title": "开源地址", "href": "https://gitee.com/Jmysy/Pear-Admin-Layui"},
|
||||
]
|
||||
|
||||
# 上传图片目标文件夹
|
||||
# ---- 上传 ----
|
||||
UPLOADED_PHOTOS_DEST = 'static/upload'
|
||||
UPLOADED_FILES_ALLOW = ['gif', 'jpg', 'jpeg', 'png', 'webp']
|
||||
UPLOADS_AUTOSERVE = True
|
||||
|
||||
# JSON 配置
|
||||
# ---- JSON ----
|
||||
JSON_AS_ASCII = False
|
||||
|
||||
# 配置多个数据库连接的连接串写法示例
|
||||
# HOSTNAME: 指数据库的IP地址、USERNAME：指数据库登录的用户名、PASSWORD：指数据库登录密码、PORT：指数据库开放的端口、DATABASE：指需要连接的数据库名称
|
||||
# MSSQL: f"mssql+pymssql://{USERNAME}:{PASSWORD}@{HOSTNAME}:{PORT}/{DATABASE}?charset=cp936"
|
||||
# MySQL: f"mysql+pymysql://{USERNAME}:{PASSWORD}@{HOSTNAME}:{PORT}/{DATABASE}?charset=utf8mb4"
|
||||
# Oracle: f"oracle+cx_oracle://{USERNAME}:{PASSWORD}@{HOSTNAME}:{PORT}/{DATABASE}"
|
||||
# SQLite "sqlite:/// database.db"
|
||||
# Postgres f"postgresql+psycopg2://{USERNAME}:{PASSWORD}@{HOSTNAME}:{PORT}/{DATABASE}"
|
||||
# Oracle的第二种连接方式
|
||||
# dsnStr = cx_Oracle.makedsn({HOSTNAME}, 1521, service_name='orcl')
|
||||
# connect_str = "oracle://%s:%s@%s" % ('{USERNAME}', ' {PASSWORD}', dsnStr)
|
||||
|
||||
# 在SQLALCHEMY_BINDS 中设置：'{数据库连接别名}': '{连接串}'
|
||||
# 最后在models的数据模型class中，在__tablename__前设置 __bind_key__ = '{数据库连接别名}' 即可，表示该数据模型不使用默认的数据库连接，改用“SQLALCHEMY_BINDS”中设置的其他数据库连接
|
||||
# SQLALCHEMY_BINDS = {
|
||||
# 'testMySQL': 'mysql+pymysql://test:123456@192.168.1.1:3306/test?charset=utf8',
|
||||
# 'testMsSQL': 'mssql+pymssql://test:123456@192.168.1.1:1433/test?charset=cp936',
|
||||
# 'testOracle': 'oracle+cx_oracle://test:123456@192.168.1.1:1521/test',
|
||||
# 'testSQLite': 'sqlite:///database.db
|
||||
# }
|
||||
|
||||
# 数据库的配置信息
|
||||
# ---- 数据库 ----
|
||||
# 默认走项目根目录下的 pear.db（与 instance/ 同一级，Flask 2.x 行为）。
|
||||
# 生产环境推荐通过 SQLALCHEMY_DATABASE_URI 环境变量切换到 MySQL。
|
||||
SQLALCHEMY_DATABASE_URI = 'sqlite:///../pear.db'
|
||||
SQLALCHEMY_TRACK_MODIFICATIONS = False
|
||||
|
||||
# 默认日志等级
|
||||
# ---- 日志 ----
|
||||
LOG_LEVEL = logging.WARN
|
||||
|
||||
# 发信设置
|
||||
MAIL_SERVER = 'smtp.qq.com'
|
||||
MAIL_USE_TLS = False
|
||||
MAIL_USE_SSL = True
|
||||
MAIL_PORT = 465
|
||||
MAIL_USERNAME = '123@qq.com'
|
||||
MAIL_PASSWORD = 'XXXXX' # 生成的授权码
|
||||
MAIL_DEFAULT_SENDER = MAIL_USERNAME
|
||||
# ---- Session ----
|
||||
PERMANENT_SESSION_LIFETIME = timedelta(days=7)
|
||||
SESSION_TYPE = "filesystem"
|
||||
SESSION_PERMANENT = False
|
||||
SESSION_USE_SIGNER = True
|
||||
|
||||
# 插件配置，填写插件的文件名名称，默认不启用插件。
|
||||
# ---- 安全 / 密钥 ----
|
||||
# SECRET_KEY 的优先级：
|
||||
# 1. 环境变量 SECRET_KEY
|
||||
# 2. .env 中的 SECRET_KEY
|
||||
# 3. 自动生成一个临时随机值（仅用于开发启动；生产模式强制要求外部传入）
|
||||
SECRET_KEY = os.environ.get("SECRET_KEY") or "pear-system-flask"
|
||||
|
||||
# ---- Mail（默认占位；环境变量可覆盖）----
|
||||
MAIL_SERVER = _env_str("MAIL_SERVER", "smtp.qq.com")
|
||||
MAIL_USE_TLS = _env_bool("MAIL_USE_TLS", False)
|
||||
MAIL_USE_SSL = _env_bool("MAIL_USE_SSL", True)
|
||||
MAIL_PORT = int(_env_str("MAIL_PORT", "465"))
|
||||
MAIL_USERNAME = _env_str("MAIL_USERNAME", "123@qq.com")
|
||||
MAIL_PASSWORD = _env_str("MAIL_PASSWORD", "XXXXX") # QQ 邮箱授权码
|
||||
MAIL_DEFAULT_SENDER = _env_str("MAIL_DEFAULT_SENDER", MAIL_USERNAME)
|
||||
|
||||
# ---- 插件 ----
|
||||
PLUGIN_ENABLE_FOLDERS = []
|
||||
|
||||
# Session 设置
|
||||
PERMANENT_SESSION_LIFETIME = timedelta(days=7)
|
||||
|
||||
SESSION_TYPE = "filesystem" # 默认使用文件系统来保存会话
|
||||
SESSION_PERMANENT = False # 会话是否持久化
|
||||
SESSION_USE_SIGNER = True # 是否对发送到浏览器上 session 的 cookie 值进行加密
|
||||
class DevConfig(BaseConfig):
|
||||
"""开发环境配置：DEBUG=True，详细日志。"""
|
||||
|
||||
SECRET_KEY = "pear-system-flask"
|
||||
DEBUG = True
|
||||
TESTING = False
|
||||
LOG_LEVEL = logging.INFO
|
||||
# 开发环境下 SECRET_KEY 自动生成（每次启动都不同，仅用于本地调试）。
|
||||
SECRET_KEY = os.environ.get("SECRET_KEY") or secrets.token_urlsafe(48)
|
||||
|
||||
|
||||
class ProConfig(BaseConfig):
|
||||
"""生产环境配置：DEBUG=False，强制要求外部传入 SECRET_KEY。"""
|
||||
|
||||
DEBUG = False
|
||||
TESTING = False
|
||||
LOG_LEVEL = logging.WARN
|
||||
|
||||
# 生产推荐使用 MySQL，例如：
|
||||
# SQLALCHEMY_DATABASE_URI=mysql+pymysql://user:pass@host:3306/pear?charset=utf8mb4
|
||||
SQLALCHEMY_DATABASE_URI = os.environ.get(
|
||||
"SQLALCHEMY_DATABASE_URI",
|
||||
BaseConfig.SQLALCHEMY_DATABASE_URI,
|
||||
)
|
||||
|
||||
@classmethod
|
||||
def init_app(cls, app):
|
||||
"""Flask 在 app.config.from_object 之后调用此钩子。
|
||||
|
||||
生产模式要求：必须从环境变量传入强随机 SECRET_KEY，
|
||||
否则启动失败 —— 防止线上仍用默认密钥。
|
||||
"""
|
||||
secret = os.environ.get("SECRET_KEY")
|
||||
if not secret or secret == "pear-system-flask":
|
||||
raise RuntimeError(
|
||||
"[ProConfig] 生产环境必须通过环境变量 SECRET_KEY 传入强随机密钥，"
|
||||
"禁止使用默认值。可用以下命令生成：\n"
|
||||
" python -c \"import secrets; print(secrets.token_urlsafe(48))\""
|
||||
)
|
||||
app.config["SECRET_KEY"] = secret
|
||||
|
||||
|
||||
# 暴露给外部按名字取
|
||||
config_map = {
|
||||
"dev": DevConfig,
|
||||
"development": DevConfig,
|
||||
"pro": ProConfig,
|
||||
"production": ProConfig,
|
||||
}
|
||||
|
||||
|
||||
def get_config_by_name(name: str):
|
||||
"""根据名字取配置类，未知名字退回 DevConfig。"""
|
||||
if not name:
|
||||
return DevConfig
|
||||
return config_map.get(name.strip().lower(), DevConfig)
|
||||
|
||||
@@ -1,11 +1,16 @@
|
||||
from applications.view.system import register_system_bps
|
||||
from applications.view.public import bp as public_bp # public 包的入口就是 nav_bp
|
||||
from applications.view.public import bp as public_bp, register_public_bp # public 包的入口就是 nav_bp
|
||||
from applications.view.health import bp as health_bp
|
||||
from applications.extensions.init_plugins import broadcast_execute
|
||||
|
||||
|
||||
def init_bps(app):
|
||||
# 健康检查端点（无需登录，应在负载均衡/容器探活里使用）
|
||||
app.register_blueprint(health_bp)
|
||||
|
||||
# 前台公开蓝图（无需登录）
|
||||
app.register_blueprint(public_bp)
|
||||
register_public_bp(app)
|
||||
|
||||
# 后台系统蓝图（需要登录 + 权限码）
|
||||
register_system_bps(app)
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
"""
|
||||
健康检查端点（无需登录）
|
||||
|
||||
- GET /healthz
|
||||
用于探活/负载均衡/容器 readinessProbe。
|
||||
返回:
|
||||
{
|
||||
"status": "ok" | "degraded",
|
||||
"db_ok": true | false,
|
||||
"env": "dev" | "production",
|
||||
"system": "Pear Admin",
|
||||
"timestamp": "2026-09-05T17:00:00+08:00"
|
||||
}
|
||||
|
||||
HTTP 状态码：
|
||||
200 - 全部正常
|
||||
503 - DB 不可达（用于触发 k8s readinessProbe 失败）
|
||||
"""
|
||||
from datetime import datetime, timedelta, timezone
|
||||
import os
|
||||
|
||||
from flask import Blueprint, current_app, jsonify
|
||||
from sqlalchemy import text
|
||||
|
||||
from applications.extensions import db
|
||||
|
||||
bp = Blueprint("health", __name__)
|
||||
|
||||
|
||||
def _beijing_now() -> str:
|
||||
"""返回 +08:00 时区 ISO8601 时间字符串。"""
|
||||
tz = timezone(timedelta(hours=8))
|
||||
return datetime.now(tz).isoformat()
|
||||
|
||||
|
||||
@bp.get("/healthz")
|
||||
def healthz():
|
||||
# 优先按 PEAR_ENV/FLASK_ENV 取环境名；兜底按 DEBUG 反推
|
||||
env = (
|
||||
os.environ.get("PEAR_ENV")
|
||||
or os.environ.get("FLASK_ENV")
|
||||
or current_app.config.get("PEAR_ENV")
|
||||
or ("dev" if current_app.config.get("DEBUG") else "production")
|
||||
)
|
||||
system_name = current_app.config.get("SYSTEM_NAME", "Pear Admin")
|
||||
|
||||
# DB 探活：跑一个最轻量的 SELECT 1
|
||||
db_ok = True
|
||||
db_error = None
|
||||
try:
|
||||
db.session.execute(text("SELECT 1"))
|
||||
except Exception as e: # noqa: BLE001 - 这里就是要把异常吃掉，转换成 False
|
||||
db_ok = False
|
||||
db_error = str(e)
|
||||
finally:
|
||||
try:
|
||||
db.session.rollback()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
payload = {
|
||||
"status": "ok" if db_ok else "degraded",
|
||||
"db_ok": db_ok,
|
||||
"env": env,
|
||||
"system": system_name,
|
||||
"timestamp": _beijing_now(),
|
||||
}
|
||||
if db_error:
|
||||
payload["db_error"] = db_error
|
||||
|
||||
return jsonify(payload), (200 if db_ok else 503)
|
||||
Reference in New Issue
Block a user