# xianyu

**Repository Path**: myThinking/xianyu

## Basic Information

- **Project Name**: xianyu
- **Description**: 闲鱼工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 闲鱼搜索机器

一个面向闲鱼搜索、结果治理、定时任务和二手商识别的内部工具。

当前项目已经包含：
- 实时搜索页 `/realtime-search`
- 任务搜索页 `/task-search`
- 结果页 `/results`
- 异步脚本页 `/async-script`
- 二手商管理页 `/sellers-page`
- 系统配置页 `/system-config`
- 定时调度
- 商品收藏 / 删除 / 批量操作
- 卖家标记二手商
- 商品标记“卖完了”
- Webhook / Feishu 通知
- SQL 单文件基线

---

## 目录说明

- `app/`：FastAPI 应用代码
- `sql/schema.sql`：当前唯一数据库结构基线
- `sql/README.md`：SQL 使用说明
- `browser_data/`：Playwright 持久化浏览器数据目录
- `logs/`：运行日志与调试截图
- `docker-compose.yml`：Docker Compose 部署方案
- `Dockerfile`：应用镜像构建文件

---

## 运行依赖

- Python 3.11+（本地部署）
- MySQL 8.0+
- Playwright Chromium
- Linux / macOS 均可

Python 依赖见：

```bash
requirements.txt
```

---

## 环境变量

先复制一份模板：

```bash
cp .env.example .env
```

关键配置：

```env
DATABASE_URL=mysql://root:password@127.0.0.1:3306/xianyu
SEARCH_TIMEOUT=180
DEFAULT_REGION_PROVINCE=广东
DEFAULT_REGION_CITY=广州
DEFAULT_SORT_MODE=latest
HEADLESS=true
SCHEDULER_ENABLED=true
SCHEDULER_POLL_SECONDS=30
STRICT_REGION_DEFAULT=false
PERSISTENT_CONTEXT_DIR=./browser_data
NOTIFY_WEBHOOK_URL=
FEISHU_WEBHOOK_URL=
```

说明：
- `DATABASE_URL`：数据库连接串
- `HEADLESS`：是否无头浏览器
- `SCHEDULER_ENABLED`：是否启用调度器
- `PERSISTENT_CONTEXT_DIR`：浏览器持久化目录
- `STRICT_REGION_DEFAULT`：默认是否开启严格地区过滤

---

# 一、本机部署方案

## 1. 创建虚拟环境并安装依赖

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium
```

## 2. 准备 MySQL 数据库

创建数据库，例如：

```sql
CREATE DATABASE xianyu CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

## 3. 初始化表结构

执行：

```bash
mysql -uroot -p xianyu < sql/schema.sql
```

如果数据库名不是 `xianyu`，改成你的实际库名即可。

## 4. 配置环境变量

```bash
cp .env.example .env
```

然后按你的实际环境修改 `.env`，重点是：
- `DATABASE_URL`
- 通知 webhook（如果需要）

## 5. 启动服务

开发模式：

```bash
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

生产/常规运行：

```bash
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

## 6. 打开页面

浏览器访问：

```text
http://127.0.0.1:8000/dashboard
```

常用页面：
- `/dashboard`
- `/realtime-search`
- `/task-search`
- `/results`
- `/async-script`

---

# 二、Docker Compose 部署方案

适合快速拉起 MySQL + 应用服务。

## 1. 准备环境变量

```bash
cp .env.example .env
```

默认 `docker-compose.yml` 中：
- MySQL 服务名：`mysql`
- App 服务名：`app`
- 容器内数据库连接：`mysql://root:password@mysql:3306/xianyu`

如果你改了数据库密码或库名，记得同步修改：
- `.env`
- `docker-compose.yml`

## 2. 初始化数据库并启动服务

直接执行：

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

当前 `docker-compose.yml` 已包含一个一次性初始化服务：

- `db-init`

它会在 MySQL 健康后自动执行：

- `sql/schema.sql`

然后应用服务 `app` 再启动。

## 3. 查看日志

```bash
docker compose logs -f app
docker compose logs -f mysql
```

如果你只想单独重跑初始化，也可以手动执行：

```bash
docker compose run --rm db-init
```

## 4. 访问服务

```text
http://127.0.0.1:8000/dashboard
```

## 5. 停止服务

```bash
docker compose down
```

如果想保留数据库数据，直接 `down` 即可；
如果连数据卷一起清理：

```bash
docker compose down -v
```

---

# 三、部署后建议检查项

## 1. 服务健康检查

访问：

```text
http://127.0.0.1:8000/
```

应返回类似：

```json
{"name":"xianyu-search-machine","status":"ok"}
```

## 2. 数据库是否初始化成功

至少确认以下表存在：
- `xianyu_products`
- `xianyu_search_tasks`
- `xianyu_search_runs`
- `xianyu_search_task_logs`
- `xianyu_dealer_detection_tasks`
- `xianyu_dealer_detection_task_logs`

## 3. 浏览器目录是否可写

项目依赖 Playwright 持久化目录：
- `browser_data/`

日志目录也需要可写：
- `logs/`

---

# 四、运行注意事项

## 1. 匿名优先模式

当前搜索链路已切到更保守的匿名优先模式：
- 尽量不依赖登录
- 尽量减少高风险 UI 点击
- 页数过大时会自动降级

## 2. 页数保护

未登录优先模式下：
- 请求页数超过 3
- 后端会自动降到 3

返回结果中会包含：
- `requested_max_pages`
- `effective_max_pages`
- `max_pages_capped`

## 3. 风控 / 验证码

闲鱼网页端可能触发：
- 登录弹层
- baxia 风控验证码

当前系统已支持：
- 更明确的错误提示
- 最近拦截截图展示

但这不代表可以稳定绕过目标站风控。

## 4. SQL 使用原则

当前只保留：

- `sql/schema.sql`

它的定位是：
- **新环境初始化基线**

不建议把它当作所有历史环境的增量迁移脚本反复执行。

---

# 五、常用命令

## 本机启动

```bash
source .venv/bin/activate
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

## 安装 Playwright 浏览器

```bash
python -m playwright install chromium
```

## Docker Compose 启动

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

## Docker Compose 单独执行数据库初始化

```bash
docker compose run --rm db-init
```

---

# 六、后续建议

如果后面还会频繁调整数据库结构，建议二选一：

1. 继续维护 `sql/schema.sql` 作为单文件基线
2. 正式启用迁移工具（如 Aerich），把变更流程规范化