bwstudio
1214bfdf4a
主要变更： 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。
165 lines
3.7 KiB
Markdown
165 lines
3.7 KiB
Markdown
# 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. 克隆代码
|
||
|
||
```bash
|
||
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. 创建虚拟环境 + 安装依赖
|
||
|
||
```bash
|
||
# 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
|
||
|
||
复制模板：
|
||
|
||
```bash
|
||
cp .env.example .env # Linux
|
||
copy .env.example .env # Windows
|
||
```
|
||
|
||
按需修改（**生产模式 SECRET_KEY 必填**，参见下文）：
|
||
|
||
```dotenv
|
||
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. 数据库初始化
|
||
|
||
```bash
|
||
# 1) 生成迁移脚本
|
||
flask db migrate
|
||
# 2) 升级到当前 head
|
||
flask db upgrade
|
||
# 3) 导入 admin 基础数据（用户 / 角色 / 菜单）
|
||
flask admin init
|
||
```
|
||
|
||
MySQL 用户需提前建库：
|
||
|
||
```sql
|
||
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 开发
|
||
|
||
```bash
|
||
# Linux
|
||
make run
|
||
# Windows
|
||
start.bat
|
||
```
|
||
|
||
### 5.2 生产
|
||
|
||
推荐用 `gunicorn`（`pip install gunicorn`），或反向代理到 `waitress`：
|
||
|
||
```bash
|
||
# 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 健康检查
|
||
|
||
服务起来后：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:5000/healthz
|
||
# 200 OK → {"status":"ok","db_ok":true,...}
|
||
# 503 → {"status":"degraded","db_ok":false,...}
|
||
```
|
||
|
||
## 6. 反向代理（Nginx 示例）
|
||
|
||
```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. 升级流程
|
||
|
||
```bash
|
||
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`。 |
|