# 查价中台 — 服务器部署指南

将本项目**整个目录**上传到 Linux 服务器后，按下列步骤操作。

## 一、服务器要求

| 项 | 建议 |
|----|------|
| 系统 | Ubuntu 22.04 / Debian 12 |
| CPU | 2 核+ |
| 内存 | **4GB+**（RPA 浏览器占内存） |
| 磁盘 | 20GB+ |
| 软件 | Docker 24+、Docker Compose V2 |
| 网络 | 可访问 `www.mothership.com` |

```bash
# 安装 Docker（如未安装）
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
# 重新登录后生效
```

## 二、上传与配置（人工填写）

```bash
cd /opt/chajia          # 你的项目目录

# 1. 复制环境变量模板
cp deploy/.env.production.example .env

# 2. 编辑 .env — 必须修改以下项（搜索 CHANGE_ME）：
nano .env
```

### 必须人工填写的项

| 变量 | 说明 |
|------|------|
| `MYSQL_ROOT_PASSWORD` | 数据库强密码 |
| `JWT_SECRET` | 随机密钥，例：`openssl rand -base64 32` |
| `PUBLIC_DOMAIN` | 对外域名，如 `quote.yourcompany.com` |
| `HOST_SERVICE_TOKENS` | 给外部系统的 API Token（JSON 单行） |
| `CUSTOMER_REGISTRY` | 客户 ID，与 token 中 `customerId` 一致 |
| `MOTHERSHIP_EMAIL` / `MOTHERSHIP_PASSWORD` | 仅当 Mothership 要求登录时填写 |

### 可选修改

| 变量 | 说明 |
|------|------|
| `APP_PORT` | 默认 3000，仅本机监听 |
| `RPA_SELECTOR_*` | Mothership 页面改版时需更新 |

## 三、一键部署

```bash
chmod +x deploy/install.sh
bash deploy/install.sh
```

脚本将自动：构建镜像 → 启动 MySQL/Redis/Web/Worker/Scheduler → 数据库迁移 → 种子数据。

### 配置 Nginx 反代（对外提供 HTTPS API）

**仅 HTTP（内网或临时测试）：**

```bash
# 先改 deploy/nginx/chajia.http.conf 里的 server_name，或设置 .env 的 PUBLIC_DOMAIN
bash deploy/install.sh --nginx-http
```

**HTTPS（生产推荐）：**

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

# 2. 先 HTTP 部署拿到证书
bash deploy/install.sh --nginx-http
sudo certbot certonly --nginx -d quote.yourcompany.com

# 3. 切换 HTTPS 配置（install 会按 PUBLIC_DOMAIN 替换域名）
bash deploy/install.sh --nginx-ssl
```

或手动复制并修改：

- `deploy/nginx/chajia.http.conf` → `/etc/nginx/sites-available/chajia`
- `deploy/nginx/chajia.ssl.conf` → 有证书后使用

## 四、部署后检查清单（人工）

- [ ] `docker compose -f deploy/docker-compose.yml ps` 五个服务均为 `Up`
- [ ] `curl -I http://127.0.0.1:3000` 返回 200/307
- [ ] 浏览器打开 `https://你的域名/admin/alerts` 能进管理端
- [ ] **修改默认管理员密码**（seed 默认：`admin_demo` / `Demo@123`）
- [ ] 用外部 Token 调 `POST /api/addresses/mothership-candidates` 返回 `code: 0`
- [ ] 完整询价：`POST /api/quotes` → 轮询 `GET /api/quotes/{id}` 得到 4 档报价
- [ ] 防火墙：只开放 **80/443**，**不要**暴露 3306/6379/3000

## 五、给外部系统的调用说明

**Base URL：** `https://你的域名`

**请求头：**

```http
Authorization: Bearer <HOST_SERVICE_TOKENS 里的 token>
X-Customer-Id: CUST_001
Content-Type: application/json
```

**流程：**

1. `POST /api/addresses/mothership-candidates` — 地址联想  
2. `POST /api/quotes` — 提交询价  
3. `GET /api/quotes/{quote_id}` — 每 2 秒轮询，最长约 30 秒  

详细字段见 `docs/查价系统-PRD.md` 第 4、5 章，或 [`deploy/API.md`](./API.md)。  
**第三方完整对接文档：** [`deploy/第三方对接指南.md`](./第三方对接指南.md)（含自测脚本 `scripts/test-host-api.ps1` / `.sh`）。

## 六、常用运维命令

```bash
# 查看日志
docker compose -f deploy/docker-compose.yml logs -f next-app
docker compose -f deploy/docker-compose.yml logs -f rpa-worker

# 重启
docker compose -f deploy/docker-compose.yml restart

# 停止
docker compose -f deploy/docker-compose.yml down

# 更新代码后重新部署
git pull
bash deploy/install.sh
```

## 七、目录说明

```
deploy/
├── .env.production.example   # 生产环境变量模板 → 复制为项目根 .env
├── docker-compose.yml        # 生产 Compose（MySQL/Redis 不对外暴露）
├── install.sh                # 一键部署脚本
├── nginx/
│   ├── chajia.http.conf      # HTTP 反代
│   └── chajia.ssl.conf       # HTTPS 反代
└── README.md                 # 本文件
```

## 八、故障排查

| 现象 | 处理 |
|------|------|
| 询价一直 `processing` | 查 `rpa-worker` 日志；确认 `RPA_MOCK_MODE=false` 且 Worker 在运行 |
| 地址联想 503 | Worker 未就绪或 Mothership 不可达 |
| RPA 登录失败 | 填写 `MOTHERSHIP_EMAIL/PASSWORD`；或检查 `.rpa` 卷内 storageState |
| 迁移失败 | `docker compose -f deploy/docker-compose.yml run --rm rpa-worker npx prisma migrate deploy` |

## 九、安全提醒

- 勿将 `.env` 提交到 Git  
- 每个外部系统使用独立 Service Token  
- 生产环境 `RPA_MOCK_MODE` 必须为 `false`  
- 定期备份 `mysql_data` 卷：`docker volume inspect chajia-prod_mysql_data`

## 十、使用宝塔 / 已有 MySQL（不用 Docker 内置库）

若数据库已在宝塔创建（库名 `chajia`，字符集 `utf8mb4`）：

1. 上传并导入 [`deploy/database/chajia.sql`](../database/chajia.sql)（或 `chajia.sql.gz`）
2. 详见 [`deploy/database/README.md`](../database/README.md)
3. 在 `.env` 设置 `DATABASE_URL` 指向宝塔 MySQL，并调整 compose **去掉** `mysql` 服务或勿启动它