# 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` 已接入负载均衡 / 容器探活