# 宝塔面板部署指南

## 域名规划

| 域名 | 用途 | 端口 |
|------|------|------|
| `dda.gaowenbu.cn` | 管理员端 (web-admin) | 80/443 |
| `ddy.gaowenbu.cn` | 业务员端 (web-sales) | 80/443 |
| 后端 API | FastAPI 服务 | 127.0.0.1:8000 |

---

## 一、服务器环境准备

### 1.1 安装宝塔面板

```bash
# CentOS
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh

# Ubuntu/Debian
wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh
```

### 1.2 宝塔面板安装软件

登录宝塔面板后，在「软件商店」中安装：

| 软件 | 版本建议 | 用途 |
|------|---------|------|
| **Nginx** | 1.24+ | 反向代理 + 前端静态文件 |
| **MySQL** | 5.7+ 或 8.0 | 数据库（如果用远程数据库可跳过） |
| **Python 项目管理器** | 最新版 | 管理 Python 虚拟环境和后端进程 |
| **phpMyAdmin** | 可选 | 数据库管理 |

### 1.3 DNS 解析

在域名管理后台添加两条 A 记录：

```
dda.gaowenbu.cn  →  服务器IP
ddy.gaowenbu.cn  →  服务器IP
```

---

## 二、上传代码到服务器

### 2.1 创建项目目录

通过宝塔面板「文件」功能，创建目录：

```
/www/wwwroot/order-flow/
```

### 2.2 上传文件

**方式一：宝塔面板上传**

1. 在本地将项目打包为 zip（排除 `node_modules`、`__pycache__`、`.git`）
2. 在宝塔「文件」页面上传到 `/www/wwwroot/order-flow/`
3. 在线解压

**方式二：Git 拉取（推荐）**

```bash
cd /www/wwwroot/
git clone <你的仓库地址> order-flow
```

### 2.3 上传目录结构

```
/www/wwwroot/order-flow/
├── backend/
│   ├── app/
│   ├── migrations/
│   ├── scripts/
│   ├── .env              ← 生产环境配置（已修改好）
│   ├── requirements.txt
│   └── main.py
├── frontend/
│   ├── web-admin/
│   │   ├── src/
│   │   ├── .env.production   ← 已配置好
│   │   └── package.json
│   └── web-sales/
│       ├── src/
│       ├── .env.production   ← 已配置好
│       └── package.json
└── deploy/
    └── nginx/
        ├── dda.gaowenbu.cn.conf
        └── ddy.gaowenbu.cn.conf
```

---

## 三、部署后端（Python 项目管理器）

### 3.1 安装 Python 项目管理器

宝塔面板 → 软件商店 → 搜索「Python项目管理器」→ 安装

### 3.2 创建 Python 项目

1. 打开「Python项目管理器」
2. 点击「添加项目」，填写：

| 配置项 | 值 |
|--------|---|
| 项目名称 | `order-flow` |
| 项目路径 | `/www/wwwroot/order-flow/backend` |
| Python版本 | `3.10` 或 `3.11` |
| 启动文件 | `main.py` |
| 启动方式 | `uvicorn` |
| 端口 | `8000` |
| 绑定地址 | `127.0.0.1` |
| 开机自启 | ✅ 勾选 |

3. 点击「确定」创建项目

### 3.3 安装依赖

项目创建后，点击项目右侧「终端」按钮，执行：

```bash
# 激虚拟环境会自动创建，手动安装依赖
pip install -r requirements.txt
```

或者在 Python 项目管理器中点击项目 → 「模块」→ 「安装依赖」→ 选择 `requirements.txt`

### 3.4 创建数据库（如果用远程数据库可跳过）

如果需要在本机建数据库：

1. 宝塔面板 → 数据库 → 添加数据库
2. 填写：
   - 数据库名：`order_flow`
   - 用户名：`order_flow`
   - 密码：（设置一个强密码）
   - 访问权限：`本地服务器` 或 `所有人`

3. **修改 `backend/.env` 中的数据库配置**：

```bash
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_DATABASE=order_flow
MYSQL_USER=order_flow
MYSQL_PASSWORD=你设置的密码
```

4. 初始化数据库表：

```bash
cd /www/wwwroot/order-flow/backend
# Python项目管理器的终端中执行
alembic upgrade head
```

### 3.5 启动后端服务

在 Python 项目管理器中点击「启动」或「重启」按钮。

验证后端是否正常：

```bash
curl http://127.0.0.1:8000/api/health
```

---

## 四、部署前端（Nginx 站点）

### 4.1 构建前端

**方式一：在本地构建后上传**

```bash
# 本地执行
cd frontend/web-admin
npm install
npm run build
# 产物在 frontend/web-admin/dist/

cd ../web-sales
npm install
npm run build
# 产物在 frontend/web-sales/dist/
```

将 `dist` 目录上传到服务器对应位置。

**方式二：在服务器上构建**

```bash
cd /www/wwwroot/order-flow/frontend/web-admin
npm install
npm run build

cd /www/wwwroot/order-flow/frontend/web-sales
npm install
npm run build
```

### 4.2 创建站点（管理员端）

1. 宝塔面板 → 网站 → 添加站点
2. 填写：
   - 域名：`dda.gaowenbu.cn`
   - 根目录：`/www/wwwroot/order-flow/frontend/web-admin/dist`
   - PHP版本：`纯静态`

3. 点击「提交」

### 4.3 配置 Nginx 反向代理

1. 点击站点 `dda.gaowenbu.cn` 右侧「设置」
2. 点击「配置文件」，在 `server { }` 块内添加以下内容（在 `location /` 之前）：

```nginx
    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        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;
        proxy_read_timeout 300s;
        proxy_connect_timeout 60s;
    }

    # 上传文件代理
    location /uploads/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
    }
```

3. 点击「伪静态」，添加：

```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

4. 保存并重启 Nginx

### 4.4 创建站点（业务员端）

1. 宝塔面板 → 网站 → 添加站点
2. 填写：
   - 域名：`ddy.gaowenbu.cn`
   - 根目录：`/www/wwwroot/order-flow/frontend/web-sales/dist`
   - PHP版本：`纯静态`

3. 配置 Nginx 反向代理（同上，配置内容完全一样）

---

## 五、配置 HTTPS（SSL 证书）

### 5.1 申请免费证书

1. 宝塔面板 → 网站 → 点击站点 `dda.gaowenbu.cn` → 设置 → SSL
2. 选择「Let's Encrypt」→ 勾选域名 → 点击「申请」
3. 同样操作 `ddy.gaowenbu.cn`

### 5.2 强制 HTTPS

申请成功后，开启「强制HTTPS」开关。

---

## 六、防火墙配置

宝塔面板 → 安全 → 防火墙，确保放行以下端口：

| 端口 | 协议 | 用途 |
|------|------|------|
| 80 | TCP | HTTP |
| 443 | TCP | HTTPS |
| 8888 | TCP | 宝塔面板（建议改端口） |

> 后端 8000 端口不需要对外开放，只通过 Nginx 反向代理访问。

---

## 七、部署后验证清单

### 7.1 服务验证

```bash
# 检查后端是否运行
curl http://127.0.0.1:8000/api/health

# 检查 Nginx 是否正常
curl -I https://dda.gaowenbu.cn
curl -I https://ddy.gaowenbu.cn

# 检查 API 代理是否正常
curl https://dda.gaowenbu.cn/api/health
```

### 7.2 浏览器访问

- [ ] `https://dda.gaowenbu.cn` 能打开管理员登录页
- [ ] `https://ddy.gaowenbu.cn` 能打开业务员登录页
- [ ] 登录功能正常
- [ ] API 请求正常（F12 Network 检查）

### 7.3 微信小程序

- [ ] 微信公众平台后台 → 开发管理 → 服务器域名 → 添加 `https://dda.gaowenbu.cn`
- [ ] 小程序重新提交审核

---

## 八、常见问题排查

### Q1: 页面打开是 404 或空白

检查前端是否构建成功，`dist` 目录是否有 `index.html`。

### Q2: API 请求 502 Bad Gateway

后端服务未启动，检查 Python 项目管理器中的项目状态。

### Q3: API 请求 CORS 错误

检查 `backend/.env` 中 `CORS_ALLOW_ORIGINS` 是否包含当前域名。

### Q4: 数据库连接失败

检查 `backend/.env` 中数据库配置，以及 MySQL 服务是否运行。

### Q5: 上传文件失败

检查 `/tmp/order-flow-oss/local-uploads` 目录权限：

```bash
mkdir -p /tmp/order-flow-oss/local-uploads
chmod 755 /tmp/order-flow-oss/local-uploads
```

### Q6: 静态资源加载慢

Nginx 配置中添加缓存（已在提供的配置中包含）。

---

## 九、日常维护

### 更新代码

```bash
cd /www/wwwroot/order-flow
git pull

# 重新构建前端
cd frontend/web-admin && npm run build
cd ../web-sales && npm run build

# 重启后端
# 在宝塔 Python 项目管理器中点击「重启」
```

### 查看后端日志

```bash
# 宝塔 Python 项目管理器 → 项目 → 日志
# 或直接查看
tail -f /www/wwwroot/order-flow/logs/*.log
```

### 数据库备份

宝塔面板 → 数据库 → 选择数据库 → 备份 → 设置定时备份