Files

T

bwstudio 1214bfdf4a 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。

2026-09-05 20:46:12 +08:00

3.7 KiB

Raw Blame History

Pear Admin Flask - 部署指南

本文档面向把本项目部署到生产环境的运维 / 二次开发者。请结合根目录的 README.md 与 docs/SECURITY.md 一起阅读。

0. 环境要求

项目	版本
Python	3.8（推荐 3.11）
SQLite	3.x（仅开发用）
MySQL	5.7+ / 8.0（生产推荐）
操作系统	Windows / Linux 均可

1. 克隆代码

git clone https://gitea.bwhome.top/bwadmin/pear-admin-flask.git
cd pear-admin-flask

如仓库使用自签证书导致 SEC_E_WRONG_PRINCIPAL 报错，可临时关闭 SSL 校验：git -c http.sslVerify=false clone <url>。长期建议把根证书导入到系统信任库。

2. 创建虚拟环境 + 安装依赖

# Linux / macOS
python -m venv venv
source venv/bin/activate

# Windows (cmd)
python -m venv venv
venv\Scripts\activate.bat

pip install -r requirements.txt

3. 配置 .env

复制模板：

cp .env.example .env   # Linux
copy .env.example .env # Windows

按需修改（生产模式 SECRET_KEY 必填，参见下文）：

PEAR_ENV=production
SECRET_KEY=<用 python -c "import secrets; print(secrets.token_urlsafe(48))" 生成>

# MySQL 示例
SQLALCHEMY_DATABASE_URI=mysql+pymysql://user:pass@127.0.0.1:3306/pear?charset=utf8mb4

# 邮件（可选）
MAIL_SERVER=smtp.qq.com
MAIL_USE_SSL=true
MAIL_PORT=465
MAIL_USERNAME=your_account@qq.com
MAIL_PASSWORD=your_authorization_code_here

⚠️ .env 文件已在 .gitignore 中，不会被提交到 git。

4. 数据库初始化

# 1) 生成迁移脚本
flask db migrate
# 2) 升级到当前 head
flask db upgrade
# 3) 导入 admin 基础数据（用户 / 角色 / 菜单）
flask admin init

MySQL 用户需提前建库：

CREATE DATABASE pear DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'pear'@'%' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON pear.* TO 'pear'@'%';
FLUSH PRIVILEGES;

5. 启动

5.1 开发

# Linux
make run
# Windows
start.bat

5.2 生产

推荐用 gunicorn（pip install gunicorn），或反向代理到 waitress：

# Linux
PEAR_ENV=production gunicorn -w 4 -b 0.0.0.0:5000 app:app

# Windows
pip install waitress
PEAR_ENV=production waitress-serve --port=5000 app:app

5.3 健康检查

服务起来后：

curl http://127.0.0.1:5000/healthz
# 200 OK → {"status":"ok","db_ok":true,...}
# 503    → {"status":"degraded","db_ok":false,...}

6. 反向代理（Nginx 示例）

server {
    listen 80;
    server_name pear.example.com;

    location / {
        proxy_pass         http://127.0.0.1:5000;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }

    location = /healthz {
        proxy_pass http://127.0.0.1:5000/healthz;
        access_log off;
    }
}

7. 升级流程

git pull
source venv/bin/activate
pip install -r requirements.txt
flask db migrate
flask db upgrade
# 重启进程
systemctl restart pear-admin-flask

8. 常见问题

现象	处理
`[ProConfig] 生产环境必须通过环境变量 SECRET_KEY 传入强随机密钥`	在 `.env` 或系统环境变量中设置 `SECRET_KEY`。
`SEC_E_WRONG_PRINCIPAL` 克隆失败	`git -c http.sslVerify=false clone ...` 或导入根证书。
启动后 `/` 跳转到登录页	正常。后台默认账号 `admin` / 密码 `123456`，请立即修改。
数据库表缺失	`flask db upgrade` 后 `flask admin init`。

3.7 KiB Raw Blame History Unescape Escape