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
2026-09-05 20:46:12 +08:00
parent 9ba96bcc3e
commit 1214bfdf4a
12 changed files with 665 additions and 72 deletions
+89
View File
@@ -0,0 +1,89 @@
# Pear Admin Flask - 安全指南
## 1. 密钥(SECRET_KEY
`SECRET_KEY` 用于 Flask `session` 签名、`csrf_token`、Flask-Session
等。**一旦泄露,攻击者可伪造任意管理员会话。**
要求:
- 长度 ≥ 32 字节(推荐 48+);
- 高熵随机(`secrets.token_urlsafe(48)` / `openssl rand -base64 48`);
- **禁止**使用默认值 `pear-system-flask`
- **禁止**把 `.env` / 含密钥的部署脚本提交到 git。
开发模式自动生成的密钥仅供本地调试,**重启即失效**。
## 2. 凭据(Mail / DB
所有凭据通过 `.env` 注入,代码里只放占位符。强烈建议:
- 生产数据库单独建用户,**只授必要的库权限**;
- Mail 使用**授权码**而非登录密码(QQ / 163 / Gmail 均提供);
- 定期轮换凭据,并在变更后重启服务。
## 3. 默认管理员账号
`flask admin init` 会写入默认账号 `admin / 123456`,**首次登录后必须立即修改密码**。
可执行:
```bash
# 1) 登录后台 → 用户管理 → 修改 admin 密码;
# 2) 或直接 SQL
sqlite3 pear.db "UPDATE rbac_user SET password='<pbkdf2:sha256:...>' WHERE username='admin';"
```
## 4. Cookie / Session
`SESSION_COOKIE_HTTPONLY = True`(默认)与 `SESSION_COOKIE_SAMESITE = 'Lax'`
已经在配置中体现。生产部署在 HTTPS 下请额外设置:
```python
SESSION_COOKIE_SECURE = True
```
> 若启用 Flask-Sessionfilesystem / redis),请把 `flask_session/`
> 目录排除在 Web 静态目录之外,并定期清理。
## 5. CSRF
本项目基于 `flask_wtf`,所有写操作均有 CSRF 校验。
前端表单务必带上 `{{ csrf_token() }}` 或请求头 `X-CSRFToken`
## 6. 上传文件
`UPLOADED_PHOTOS_DEST = static/upload`,后缀白名单已限制为图片。
但**用户可上传 SVG / 伪装为图片的 JS** 等——建议:
- 上传目录关闭脚本执行(Nginx: `location ^~ /static/upload/ { ... }`);
- 后端校验真实文件类型(`python-magic`),而非仅看后缀。
## 7. 限流
`Flask-Limiter` 已挂载(`applications/extensions/init_limit.py`)。
生产模式请按业务需求调整默认速率,避免误伤。
## 8. 日志
`LOG_LEVEL` 控制根 logger 输出等级。生产推荐 `WARN` / `ERROR`
**不要把 `SECRET_KEY`、用户密码、token 写入日志。**
## 9. 依赖漏洞
建议在 CI 中加入 `pip-audit`
```bash
pip install pip-audit
pip-audit -r requirements.txt
```
## 10. 上线前 Checklist
- [ ] `PEAR_ENV=production`
- [ ] `SECRET_KEY` 已替换为强随机值
- [ ] 数据库用户仅授必要权限
- [ ] 默认 admin 密码已修改
- [ ] HTTPS 已上线(`SESSION_COOKIE_SECURE` 同步开启)
- [ ] `flask_session/` 目录已加入备份策略
- [ ] `static/upload/` 已禁用脚本执行
- [ ] `pip-audit` 跑过
- [ ] `/healthz` 已接入负载均衡 / 容器探活