# 域名部署配置文档

> **使用宝塔面板部署？** 请直接参考 [deploy/宝塔部署指南.md](deploy/宝塔部署指南.md)，本文档为详细配置说明。

## 域名规划

| 域名 | 用途 | 说明 |
|------|------|------|
| `dda.gaowenbu.cn` | 管理员端 (web-admin) | Vue 3 前端 + API 反向代理 |
| `ddy.gaowenbu.cn` | 业务员端 (web-sales) | Vue 3 前端 + API 反向代理 |
| 后端服务 | FastAPI API 服务 | 监听 `127.0.0.1:8000`，由 Nginx 代理 |

## 架构说明

```
用户浏览器
  ├── dda.gaowenbu.cn ──→ Nginx ──→ web-admin/dist (静态文件)
  │                         │
  │                         └──→ /api/* ──→ FastAPI (127.0.0.1:8000)
  │
  └── ddy.gaowenbu.cn ──→ Nginx ──→ web-sales/dist (静态文件)
                            │
                            └──→ /api/* ──→ FastAPI (127.0.0.1:8000)

微信小程序 ──→ dda.gaowenbu.cn/api/* ──→ Nginx ──→ FastAPI
```

## 一、已修改的配置文件

### 1.1 后端 `backend/.env`（已修改）

| 配置项 | 开发环境值 | 生产环境值 | 说明 |
|--------|-----------|-----------|------|
| `APP_ENV` | `dev` | `prod` | ✅ 已改为 prod |
| `BASE_URL` | _(无)_ | `https://dda.gaowenbu.cn` | ✅ 新增，用于生成文件绝对 URL |
| `CORS_ALLOW_ORIGINS` | `http://localhost:5173,http://localhost:5174` | `https://dda.gaowenbu.cn,https://ddy.gaowenbu.cn` | ✅ 已改为生产域名 |
| `AUTH_TOKEN_STORE_PATH` | `D:/tmp/...` (Windows) | `/tmp/order-flow-auth/revoked_tokens.json` | ✅ 已改为 Linux 路径 |
| `LOCAL_UPLOAD_DIR` | _(无)_ | `/tmp/order-flow-oss/local-uploads` | ✅ 新增，Linux 路径 |

### 1.2 后端 `backend/app/core/config.py`（已修改）

新增两个配置字段：
- `base_url: str` — 后端公网访问地址，别名 `BASE_URL`
- `local_upload_dir: str` — 本地上传目录，别名 `LOCAL_UPLOAD_DIR`

### 1.3 后端 `backend/app/main.py`（已修改）

本地上传目录从硬编码 `D:/tmp/...` 改为从 `settings.local_upload_dir` 读取。

### 1.4 后端 `backend/app/api/files.py`（已修改）

文件上传返回的 URL 从硬编码 `http://127.0.0.1:8000/uploads/...` 改为从 `settings.base_url` 读取。

### 1.5 前端 `frontend/web-admin/.env`（新建）

```env
VITE_API_BASE_URL=https://dda.gaowenbu.cn
VITE_ENABLE_DEMO_FALLBACK=false
```

### 1.6 前端 `frontend/web-sales/.env`（新建）

```env
VITE_API_BASE_URL=https://ddy.gaowenbu.cn
VITE_ENABLE_DEMO_FALLBACK=false
```

### 1.7 前端 Vue 组件（已修改 4 个文件）

以下文件从硬编码 `http://127.0.0.1:8000` 改为导入 `config.js` 的 `apiBaseUrl`：

| 文件 | 原始写法 | 修改后 |
|------|---------|--------|
| `web-admin/src/views/DriverPage.vue` | `import.meta.env.VITE_API_BASE_URL \|\| 'http://127.0.0.1:8000'` | `import { apiBaseUrl } from '../config'` |
| `web-admin/src/views/DriverTaskDetailPage.vue` | `import.meta.env.VITE_API_BASE_URL \|\| 'http://127.0.0.1:8000'` | `import { apiBaseUrl } from '../config'` |
| `web-admin/src/views/OrderTrackingPage.vue` | `import.meta.env.VITE_API_BASE_URL \|\| 'http://127.0.0.1:8000'` | `import { apiBaseUrl } from '../config'` |
| `web-sales/src/views/OrderFormPage.vue` | `import.meta.env.VITE_API_BASE_URL \|\| "http://localhost:8000"` | `import { apiBaseUrl } from '../config'` |

### 1.8 微信小程序 `frontend/mini-app/config.js`（已修改）

```js
// 开发环境: const apiBaseUrl = "http://127.0.0.1:8000";
// 生产环境:
const apiBaseUrl = "https://dda.gaowenbu.cn";
```

---

## 二、Nginx 配置（部署到服务器）

已生成两份 Nginx 配置文件，位于 `deploy/nginx/` 目录：

### 2.1 部署步骤

```bash
# 1. 安装 Nginx（如未安装）
sudo apt update && sudo apt install -y nginx

# 2. 复制配置文件
sudo cp deploy/nginx/dda.gaowenbu.cn.conf /etc/nginx/sites-available/
sudo cp deploy/nginx/ddy.gaowenbu.cn.conf /etc/nginx/sites-available/

# 3. 创建软链接启用站点
sudo ln -sf /etc/nginx/sites-available/dda.gaowenbu.cn.conf /etc/nginx/sites-enabled/
sudo ln -sf /etc/nginx/sites-available/ddy.gaowenbu.cn.conf /etc/nginx/sites-enabled/

# 4. 删除默认站点（可选）
sudo rm -f /etc/nginx/sites-enabled/default

# 5. 测试配置
sudo nginx -t

# 6. 重载 Nginx
sudo systemctl reload nginx
```

### 2.2 前端文件部署路径

```
/var/www/order-flow/
  ├── web-admin/dist/    ← 管理员端构建产物
  └── web-sales/dist/    ← 业务员端构建产物
```

部署前端文件：

```bash
# 创建目录
sudo mkdir -p /var/www/order-flow/web-admin/dist
sudo mkdir -p /var/www/order-flow/web-sales/dist

# 复制构建产物（在本地构建后上传，或在服务器上构建）
# 方式一：本地构建后 scp 上传
scp -r frontend/web-admin/dist/* user@server:/var/www/order-flow/web-admin/dist/
scp -r frontend/web-sales/dist/* user@server:/var/www/order-flow/web-sales/dist/

# 方式二：在服务器上构建
cd frontend/web-admin && npm install && npm run build
cd frontend/web-sales && npm install && npm run build
```

### 2.3 后端部署

```bash
# 安装 Python 依赖
cd backend && pip install -r requirements.txt

# 运行数据库迁移
alembic upgrade head

# 启动后端服务（推荐用 systemd 管理）
uvicorn backend.app.main:app --host 127.0.0.1 --port 8000
```

### 2.4 后端 systemd 服务文件（参考）

```ini
# /etc/systemd/system/order-flow.service
[Unit]
Description=Order Flow Backend
After=network.target mysql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/order-flow
EnvironmentFile=/var/www/order-flow/backend/.env
ExecStart=/usr/local/bin/uvicorn backend.app.main:app --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable order-flow
sudo systemctl start order-flow
```

---

## 三、HTTPS 配置（推荐）

使用 Let's Encrypt 免费证书：

```bash
# 安装 certbot
sudo apt install -y certbot python3-certbot-nginx

# 申请证书并自动配置 HTTPS
sudo certbot --nginx -d dda.gaowenbu.cn -d ddy.gaowenbu.cn

# 证书自动续期
sudo certbot renew --dry-run
```

---

## 四、部署前检查清单

### 服务器环境
- [ ] Nginx 已安装并运行
- [ ] Python 3.10+ 已安装
- [ ] MySQL 数据库可访问（当前配置 `fn.taisan.online:33306`）
- [ ] Redis 已安装（如需要）

### DNS 解析
- [ ] `dda.gaowenbu.cn` A 记录指向服务器 IP
- [ ] `ddy.gaowenbu.cn` A 记录指向服务器 IP

### 后端配置
- [ ] `backend/.env` 中 `APP_ENV=prod`
- [ ] `backend/.env` 中 `BASE_URL=https://dda.gaowenbu.cn`
- [ ] `backend/.env` 中 `CORS_ALLOW_ORIGINS` 包含两个域名
- [ ] `backend/.env` 中 `SECRET_KEY` 已修改为随机强密钥
- [ ] `backend/.env` 中数据库连接信息正确
- [ ] `AUTH_TOKEN_STORE_PATH` 指向 Linux 有效路径
- [ ] `LOCAL_UPLOAD_DIR` 指向 Linux 有效路径

### 前端配置
- [ ] `frontend/web-admin/.env` 中 `VITE_API_BASE_URL=https://dda.gaowenbu.cn`
- [ ] `frontend/web-sales/.env` 中 `VITE_API_BASE_URL=https://ddy.gaowenbu.cn`
- [ ] 前端已重新构建 (`npm run build`)
- [ ] 构建产物已部署到 `/var/www/order-flow/`

### 微信小程序
- [ ] 微信公众平台后台配置合法域名 `dda.gaowenbu.cn`
- [ ] `frontend/mini-app/config.js` 中 `apiBaseUrl` 已更新
- [ ] 小程序已重新提交审核

### 安全
- [ ] `backend/.env` 不可被外部直接访问
- [ ] 已配置 HTTPS（Let's Encrypt 或其他证书）
- [ ] 防火墙仅开放 80/443 端口
- [ ] `.env` 文件权限设为 `600`（仅 owner 可读写）

---

## 五、本地开发环境恢复

如果需要恢复本地开发环境，将以下配置改回：

```bash
# backend/.env
APP_ENV=dev
BASE_URL=http://127.0.0.1:8000
CORS_ALLOW_ORIGINS=http://localhost:5173,http://localhost:5174
AUTH_TOKEN_STORE_PATH=D:/tmp/order-flow-auth/revoked_tokens.json
LOCAL_UPLOAD_DIR=D:/tmp/order-flow-oss/local-uploads

# frontend/web-admin/.env
VITE_API_BASE_URL=http://127.0.0.1:8000

# frontend/web-sales/.env
VITE_API_BASE_URL=http://127.0.0.1:8000

# frontend/mini-app/config.js
const apiBaseUrl = "http://127.0.0.1:8000";
```

---

## 六、修改文件总览

| 文件 | 操作 | 说明 |
|------|------|------|
| `backend/.env` | 修改 | APP_ENV、BASE_URL、CORS、路径配置 |
| `backend/.env.example` | 修改 | 新增 BASE_URL、LOCAL_UPLOAD_DIR 文档 |
| `backend/app/core/config.py` | 修改 | 新增 base_url、local_upload_dir 字段 |
| `backend/app/main.py` | 修改 | 本地上传目录改用配置 |
| `backend/app/api/files.py` | 修改 | 文件 URL 改用配置 |
| `frontend/web-admin/.env` | 新建 | 生产环境 API 地址 |
| `frontend/web-sales/.env` | 新建 | 生产环境 API 地址 |
| `frontend/web-admin/src/views/DriverPage.vue` | 修改 | 使用 config.js |
| `frontend/web-admin/src/views/DriverTaskDetailPage.vue` | 修改 | 使用 config.js |
| `frontend/web-admin/src/views/OrderTrackingPage.vue` | 修改 | 使用 config.js |
| `frontend/web-sales/src/views/OrderFormPage.vue` | 修改 | 使用 config.js |
| `frontend/mini-app/config.js` | 修改 | 生产 API 地址 |
| `deploy/nginx/dda.gaowenbu.cn.conf` | 新建 | 管理员端 Nginx 配置 |
| `deploy/nginx/ddy.gaowenbu.cn.conf` | 新建 | 业务员端 Nginx 配置 |
| `域名部署配置.md` | 新建 | 本文档 |