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。
90 lines
2.8 KiB
Markdown
90 lines
2.8 KiB
Markdown
# 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-Session（filesystem / 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` 已接入负载均衡 / 容器探活
|