# 外贸

**Repository Path**: cloud-order-taking/foreign-trade

## Basic Information

- **Project Name**: 外贸
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 外贸拓客系统（Python）+ 可视化管理后台（Vue3）

> 完整总结文档请查看：`项目总结与运行说明.md`  
> **使用者快速上手（配置含义、首页各块说明）**：[`快速上手指南.md`](./快速上手指南.md)

本项目包含两部分：

- 采集器：搜索 API + 抓取 + 提取 + 评分（Python）
- 管理后台：FastAPI + SQLite + Vue3，用于查看/筛选/跟进线索

## 项目目录结构

```text
.
├─ backend/                      # FastAPI 后端 + SQLite + seed/import 脚本
│  ├─ app/
│  │  ├─ main.py
│  │  ├─ db.py
│  │  ├─ models.py
│  │  ├─ schemas.py
│  │  ├─ services.py
│  │  └─ routers/
│  │     └─ leads.py
│  ├─ scripts/
│  │  ├─ seed.py
│  │  └─ import_csv.py
│  ├─ data/
│  ├─ requirements.txt
│  └─ README.md
├─ frontend/                     # Vue3 管理页面
│  ├─ src/
│  │  ├─ api/
│  │  ├─ components/
│  │  ├─ pages/
│  │  ├─ router/
│  │  ├─ App.vue
│  │  └─ main.js
│  ├─ package.json
│  ├─ vite.config.js
│  └─ README.md
├─ src/leadgen/                  # 原有采集器核心代码
├─ tests/
├─ config.example.yaml
└─ pyproject.toml
```

## 一键启动说明（分别启动即可）

### 1) 启动后端

```bash
cd backend
python -m venv .venv
. .venv/Scripts/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 9999
```

访问 OpenAPI 文档：`http://127.0.0.1:9999/docs`

### 2) 初始化示例数据（可选）

```bash
cd backend
python -m scripts.seed
```

### 3) 启动前端

```bash
cd frontend
npm install
npm run dev
```

默认页面：`http://127.0.0.1:5173`

## 环境变量

### 采集器（根目录 `.env`）

```env
GOOGLE_API_KEY=your_google_api_key
GOOGLE_CSE_ID=your_custom_search_engine_id
SEARCHAPI_API_KEY=your_searchapi_api_key
SERPER_API_KEY=your_serper_api_key
SERPAPI_API_KEY=your_serpapi_api_key
```

## 搜索 API 多供应商切换

`config.yaml` 的 `search` 节支持主供应商 + 降级供应商：

```yaml
search:
  provider: google_cse
  fallback_providers: ["searchapi", "serper", "serpapi"]
  max_results_per_query: 10
  timeout_seconds: 20
  retry_attempts: 3
```

- `provider` 可选：`google_cse`、`searchapi`、`serper`、`serpapi`
- `fallback_providers` 按顺序兜底，当主供应商无结果或失败时自动尝试
- 只配置你实际使用到的 API Key 即可

### 前端（`frontend/.env`）

```env
VITE_API_BASE_URL=http://127.0.0.1:9999
```

## 采集结果写入数据库

如果你已有采集器导出的 CSV（如 `output/leads.csv`），可执行：

```bash
cd backend
python -m scripts.import_csv --file ../output/leads.csv
```

## 前端一键触发真实采集

线索列表页已提供“开始采集真实数据”按钮，会调用：

- `POST /api/crawl/run`
- `GET /api/crawl/status`
- `GET /api/crawl/config`（读取配置）
- `PUT /api/crawl/config`（保存配置）

请求体示例：

```json
{
  "config_path": "../config.yaml",
  "limit_per_query": 5
}
```

说明：

- `config_path` 支持相对项目根目录路径或绝对路径
- 采集会调用你当前配置的搜索 provider（`google_cse/searchapi/serper/serpapi`）
- 采集完成后会将结果 upsert 到 SQLite，前端自动刷新列表
- 前端会自动轮询采集状态并展示进度（已处理查询/已搜索/已入库）
- 可在前端点击“修改采集配置”直接编辑国家/产品/排除词/provider 等，并保存到配置文件

## 服务器快速部署（Docker）

前提：服务器已安装 Docker 与 Docker Compose（插件）。

1. 将仓库放到服务器，进入项目根目录。
2. 准备配置与密钥文件（与本地开发相同）：

   ```bash
   cp config.example.yaml config.yaml
   cp .env.example .env
   # 编辑 config.yaml / .env（搜索 API Key 等）
   ```

3. 构建并启动：

   ```bash
   docker compose up -d --build
   ```

   `Dockerfile.backend` **默认已使用清华 PyPI 镜像**，并加长 `pip` 超时与重试，缓解「装完 fastapi 后 uvicorn 报 `(from versions: none)`」这类**实为网络中断、并非无包**的错误。

   若在**海外**构建需改用官方源：

   ```bash
   docker compose build --no-cache --build-arg PIP_INDEX_URL=https://pypi.org/simple --build-arg PIP_TRUSTED_HOST=pypi.org api
   ```

4. 访问：

   - **管理后台**：`http://<服务器IP>:9988/`（Nginx 容器内 80 映射到宿主机 9988）
   - **接口文档**：`http://<服务器IP>:9988/docs` 或 `http://<服务器IP>:9999/docs`
   - **健康检查**：`http://<服务器IP>:9988/health`

说明：

- SQLite 使用**目录绑定** `./backend/data` → 容器内 `/app/backend/data`（文件即 `backend/data/leads.db`）。与本地 `uvicorn` 开发时路径一致；把本地该文件（或整个 `data` 目录）上传到服务器同路径即可带上数据。
- 若曾用旧版 compose 的命名卷 `lead_data`，数据在卷里而不在项目目录；迁移可把卷内 `leads.db` 拷出到 `backend/data/` 后再启动，或执行：`docker run --rm -v foreign-trade_lead_data:/from -v "$(pwd)/backend/data:/to" alpine cp /from/leads.db /to/`（卷名以 `docker volume ls` 为准）。
- 生产环境若前端与后端域名不同，构建前端时设置 `VITE_API_BASE_URL` 为后端地址，并配置后端环境变量 `CORS_ORIGINS`（逗号分隔）；内网测试可将 `CORS_ORIGINS=*`（会关闭 `allow_credentials`）。
- 修改 `config.yaml` / `.env` 后，执行 `docker compose restart api` 使变更生效（或整栈 `docker compose restart`）。

**部署后「看不到本地数据」排查：**

1. **必须在放 `docker-compose.yml` 的目录下执行** `docker compose up`，宿主机库路径为 **`<该目录>/backend/data/leads.db`**。用 `ls -la backend/data/leads.db` 确认文件存在且大小大于 0。
2. 上传后执行 **`docker compose restart api`**（或 `down` 再 `up`），避免进程仍挂着旧挂载。
3. 浏览器访问 **`http://<服务器IP>:9999/health`**（或经 Nginx：`http://<服务器IP>:9988/health`），查看 JSON 里的 **`db_path`、`db_file_exists`、`lead_row_count`**：`db_file_exists` 为 false 说明挂载目录里没有库文件；`lead_row_count` 大于 0 说明库里有数据。
4. 列表页**默认不展示「黑名单」状态线索**；若 `lead_row_count` 有数但列表空，在筛选里把状态改为 **「黑名单」** 或其它状态试一次。