# 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`。 |