# 生产部署与数据对齐

## 1. 当前项目是否能在 Docker 中单独运行

- **能**。爬虫镜像 `Dockerfile.crawler` 自包含 Python 3.11 + `crawler/requirements.txt`（含 dashscope），无宿主机 Python 版本依赖。
- **两种常见用法**：
  - **docker-compose 一起跑**：API + 爬虫都在容器内，共用一个命名卷 `app-data`，天然对齐。
  - **爬虫单独 Docker、API 在宿主机**：爬虫容器通过挂载宿主机上的 **同一个** `server/data.db`，并设置 `API_BASE` 指向宿主机 API，即可单独运行且数据一致。

## 2. 数据对齐（必须满足）

| 角色   | 使用的 DB 路径（示例）        | 说明 |
|--------|-------------------------------|------|
| Node API | `process.env.DB_PATH` 或 `server/data.db` | 见 `server/db.js`、`docker-entrypoint.sh` |
| 爬虫（Docker 内） | `DB_PATH=/data/data.db`，且 `/data/data.db` 由宿主机同一文件挂载 | 见 `Dockerfile.crawler`、`crawler/config.py` |

**原则**：API 和爬虫必须读写 **同一个 SQLite 文件**。否则会出现「爬虫写了库、API 读不到」或反之。

- **docker-compose 全容器**：两边都用卷 `app-data`，路径均为 `/data/data.db`，自动对齐。
- **API 宿主机 + 爬虫 Docker**：宿主机 API 的 `DB_PATH` 指向例如 `$PROJECT/server/data.db`；爬虫启动时用 `-v $PROJECT/server/data.db:/data/data.db` 和 `-e DB_PATH=/data/data.db`，即对齐。

## 3. 生产脚本与用法

### 3.1 爬虫单独 Docker（API 在宿主机，如 PM2）

```bash
# 首次：构建镜像并启动爬虫容器（会读 .env 中的 DASHSCOPE_API_KEY）
./scripts/production-start.sh

# 或分步：
docker build -t usa-dashboard-crawler:latest -f Dockerfile.crawler .
./scripts/run-crawler-docker-standalone.sh
```

可调环境变量（在运行脚本前 export 或写在 .env）：

- `PROJECT_ROOT`：项目根目录，默认当前目录；用于解析 `server/data.db`。
- `DB_FILE`：宿主机 DB 绝对路径，默认 `$PROJECT_ROOT/server/data.db`。
- `API_BASE`：爬虫通知 API 的地址，默认 `http://host.docker.internal:3001`（Linux 下脚本会自动加 `--add-host=host.docker.internal:host-gateway`）。
- `DASHSCOPE_API_KEY`：阿里云 DashScope，启用 AI 清洗（可选）。

### 3.2 docker-compose 全栈（API + 爬虫都在容器）

```bash
# 启动
docker compose up -d
# 或传入 DASHSCOPE_API_KEY
DASHSCOPE_API_KEY=sk-xxx docker compose up -d

# 停止
docker compose down
```

此时 API 与爬虫共用卷 `app-data`，DB 路径均为 `/data/data.db`，无需额外对齐。

### 3.3 宿主机 API（PM2）使用的 DB 路径

确保 PM2 启动 API 时使用的 DB 与爬虫挂载的是同一文件，例如：

- 在 ecosystem 或启动命令里设置：`DB_PATH=/www/wwwroot/www.airtep.com2/usa/server/data.db`
- 或项目根目录即部署目录时，不设则默认为 `server/data.db`（相对路径以进程 cwd 为准）。

## 4. 检查清单

- [ ] API 与爬虫使用**同一 DB 文件**（见上表）。
- [ ] 爬虫能访问到 API：`API_BASE` 在「爬虫单独 Docker」场景下指向宿主机（如 `http://host.docker.internal:3001`），在 compose 场景下为 `http://api:3001`。
- [ ] 若需 AI 清洗：在爬虫侧设置 `DASHSCOPE_API_KEY`（compose 或 standalone 脚本的 .env/环境变量）。
- [ ] 首次部署或无 DB 时：先创建并初始化 DB（例如 `DB_PATH=server/data.db node server/seed.js`），再启动爬虫容器。