ai-goofish-monitor Documentation

基于 Playwright 和AI实现的闲鱼多任务实时/定时监控与智能分析系统，配备了功能完善的后台管理UI。帮助用户从闲鱼海量商品中，找到心仪产品。

15,122 stars Python Python 4 files · ~2,860 tokens #ai#ai-assistant#ai-tools#automation#gemini#goofish#open-source#openai
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy ai-goofish-monitor on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name ai-goofish-monitor -p 8000:8000 --restart always usagi-org/ai-goofish-monitor:latest
Configured Services & Ports
⚙️ app
image: build locally
🔌 Ports: 8000:8000
docker-compose.yml
yaml (docker-compose.yml) 
services:
  app:
    build: .
    container_name: ai-goofish-monitor-app
    init: true
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - .:/app
      - /app/dist
    restart: unless-stopped

Technical Documentation: Usagi-org/ai-goofish-monitor

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

闲鱼智能监控系统

[中文] ｜ English

基于 Playwright 和 AI 的闲鱼多任务实时监控，提供完整的 Web 管理界面。

核心特性

  • Web 可视化管理: 任务管理、账号管理、AI 标准编辑、运行日志、结果浏览
  • AI 驱动: 自然语言创建任务，多模态模型深度分析商品
  • 多任务并发: 独立配置关键词、价格、筛选条件和 AI Prompt
  • 高级筛选: 包邮、新发布时间范围、省/市/区三级区域筛选
  • 即时通知: 支持 ntfy.sh、企业微信、Bark、Telegram、Webhook等多渠道
  • 定时调度: 支持 Cron 配置周期性任务
  • 账号与代理轮换: 多账号管理、任务绑定账号、代理池轮换与失败重试
  • Docker 部署: 一键容器化部署

截图

🐳 Docker 部署（推荐）

bash
git clone https://github.com/Usagi-org/ai-goofish-monitor && cd ai-goofish-monitor
cp .env.example .env
vim .env # 填写相关配置项
docker compose up -d
docker compose logs -f app
docker compose down

如果镜像无法访问或下载速度慢，可尝试使用加速：

bash
docker pull ghcr.nju.edu.cn/usagi-org/ai-goofish:latest
docker tag ghcr.nju.edu.cn/usagi-org/ai-goofish:latest ghcr.io/usagi-org/ai-goofish:latest
docker compose up -d
  • 默认 Web UI 地址：http://127.0.0.1:8000
  • Docker 镜像已内置 Chromium，无需宿主机额外安装浏览器。
  • 官方镜像地址：ghcr.io/usagi-org/ai-goofish:latest
  • 更新镜像：docker compose pull && docker compose up -d
  • 如果你修改了 .env 中的 SERVER_PORT，请同步更新 docker-compose.yaml 里的端口映射。
  • docker-compose.yaml 默认会把 SQLite 主库挂载到 ./data:/app/data，数据库文件默认为 data/app.sqlite3
  • 目前默认持久化这些目录：
    • data/ SQLite 主存储（任务、结果、价格历史）
    • state/ 登录状态 cookie 文件
    • prompts/ 任务提示词
    • logs/ 运行日志
    • images/ 商品图片与任务临时图片目录
    • config.json、jsonl/、price_history/ 首次升级到 SQLite 时用于兼容导入的旧数据源

数据存储与迁移

  • 当前在线主存储为 SQLite，默认路径 data/app.sqlite3
  • 可通过环境变量 APP_DATABASE_FILE 自定义数据库路径；Docker 默认设置为 /app/data/app.sqlite3
  • 应用启动时会自动建库建表，并尝试从旧的 config.json、jsonl/、price_history/ 导入一次历史数据
  • state/、prompts/、logs/、images/ 仍然是文件系统目录，不在 SQLite 中
  • 商品图片会临时落到 images/task_images_<task_name>/，任务结束后默认会清理
  • 首次升级完成并确认 data/app.sqlite3 中数据正确后，可视部署方式决定是否继续保留旧的 config.json、jsonl/、price_history/ 挂载

最少配置

变量 说明 必填
OPENAI_API_KEY AI 模型 API Key 是
OPENAI_BASE_URL OpenAI 兼容接口地址 是
OPENAI_MODEL_NAME 支持图片输入的模型名称 是
WEB_USERNAME / WEB_PASSWORD Web UI 登录账号密码，默认 admin/admin123 否

其余配置见下方“配置说明”。

第一次使用

  1. 打开默认 Web UI http://127.0.0.1:8000 并登录。
  2. 进入“闲鱼账号管理”，使用 Chrome 扩展 导出并粘贴闲鱼登录态 JSON。
  3. 登录态文件会保存到 state/ 目录，例如 state/acc_1.json。
  4. 回到“任务管理”，创建任务并绑定账号后即可运行。

创建第一个任务

  • AI判断：填写“详细需求”，提交后会弹出独立进度弹窗，后台异步生成分析标准。
  • 关键词判断：填写关键词规则，任务会直接创建，不经过 AI 生成流程。
  • 区域筛选：已改为省 / 市 / 区三级选择器，数据基于闲鱼页面抓取快照内置。

用户使用说明

点击展开 Web UI 功能说明

任务管理

  • 支持 AI 创建、关键词规则、价格范围、新发布范围、区域筛选、账号绑定、定时规则。
  • AI 任务创建是后台 job 流程，提交后会打开单独的进度弹窗。
  • 区域筛选会显著缩小结果集，默认留空。

账号管理

  • 支持导入、更新、删除闲鱼账号登录态。
  • 每个任务可指定账号，也可不绑定并交给系统自动选择。

结果查看与运行日志

  • 结果页和导出功能现在从 SQLite 查询，不再直接扫描 jsonl 文件。
  • 日志页按任务展示运行过程，便于排查登录态失效、风控和 AI 调用问题。

系统设置

  • 可查看系统状态、编辑 Prompt、调整代理与轮换相关配置。

开发者开发

环境要求

  • Python 3.10+
  • Node.js + npm（本地验证 Node v20.18.3 可完成前端构建）
  • Playwright CLI 与 Chromium，首次运行前建议执行 python3 -m pip install playwright && python3 -m playwright install chromium
  • Chrome / Edge 浏览器（Linux 环境也可使用 Chromium；start.sh 会先检查浏览器是否存在）
bash
git clone https://github.com/Usagi-org/ai-goofish-monitor
cd ai-goofish-monitor
cp .env.example .env

一键启动

bash
chmod +x start.sh
./start.sh

start.sh 会先检查 Playwright CLI 和浏览器前置条件；在前置条件满足后自动安装项目依赖、构建前端、复制构建产物并启动后端。

手动启动

bash
# 后端
python -m src.app
# 或
uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload

# 前端
cd web-ui
npm install
npm run dev
  • FastAPI 启动时会自动初始化 SQLite，并在首次启动时尝试导入旧的 config.json/jsonl/price_history
  • spider_v2.py 默认从 SQLite 读取任务；只有显式传入 --config 时才会走 JSON 配置兼容模式
  • 默认数据库路径为 data/app.sqlite3
  • Vite 开发服务器会将 /api、/auth、/ws 代理到 http://127.0.0.1:8000。
  • npm run build 先生成 web-ui/dist/，start.sh 再复制到仓库根目录 dist/。
  • FastAPI 负责提供根目录 dist/index.html 和 dist/assets/。
  • ./start.sh 默认输出访问地址 http://localhost:8000 和 API 文档 http://localhost:8000/docs。

测试与校验

bash
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest
cd web-ui && npm run build

任务创建 API

点击展开 API 行为说明

  • POST /api/tasks/generate
    • decision_mode=ai：返回 202 和 job，需要继续轮询进度。
    • decision_mode=keyword：直接返回已创建任务。
  • GET /api/tasks/generate-jobs/{job_id}：查询 AI 任务生成进度。
  • POST /auth/status：校验 Web UI 登录凭据。

配置说明

点击展开常用配置项

AI 与运行时

  • OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL_NAME：AI 模型接入必填项。
  • PROXY_URL：为 AI 请求单独指定 HTTP/SOCKS5 代理。
  • RUN_HEADLESS：是否以无头模式运行爬虫；Docker 中应保持 true。
  • SERVER_PORT：后端监听端口，默认 8000。
  • LOGIN_IS_EDGE：本地环境可切换为 Edge 内核；Docker 镜像未内置 Edge，容器内会固定使用 Chromium。
  • PCURL_TO_MOBILE：是否将 PC 商品链接转换为移动端链接。

通知

  • NTFY_TOPIC_URL
  • GOTIFY_URL / GOTIFY_TOKEN
  • BARK_URL
  • WX_BOT_URL
  • TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID / TELEGRAM_API_BASE_URL
  • WEBHOOK_*

代理轮换与失败保护

  • PROXY_ROTATION_ENABLED
  • PROXY_ROTATION_MODE
  • PROXY_POOL
  • PROXY_ROTATION_RETRY_LIMIT
  • PROXY_BLACKLIST_TTL
  • TASK_FAILURE_THRESHOLD
  • TASK_FAILURE_PAUSE_SECONDS
  • TASK_FAILURE_GUARD_PATH

完整示例见 .env.example。

Web 界面认证

点击展开认证说明

  • Web UI 当前使用登录页收集账号密码，并通过 POST /auth/status 校验。
  • 登录成功后，前端会在浏览器本地保存登录状态，用于路由守卫和 WebSocket 初始化。
  • 默认账号密码为 admin/admin123，生产环境请务必修改。

🚀 工作流程

下图描述了单个监控任务从启动到完成的核心处理逻辑。主服务运行于 src.app，按用户操作或定时调度启动一个或多个任务进程。

mermaid
graph TD
    A[启动监控任务] --> B[选择账号/代理配置];
    B --> C[任务: 搜索商品];
    C --> D{发现新商品?};
    D -- 是 --> E[抓取商品详情 & 卖家信息];
    E --> F[下载商品图片];
    F --> G[调用AI进行分析];
    G --> H{AI是否推荐?};
    H -- 是 --> I[发送通知];
    H -- 否 --> J[保存记录到 SQLite];
    I --> J;
    D -- 否 --> K[翻页/等待];
    K --> C;
    J --> C;
    C --> L{触发风控/异常?};
    L -- 是 --> M[账号/代理轮换并重试];
    M --> C;

常见问题

点击展开常见问题

AI 任务创建为什么不是立即完成？

AI 模式会先生成分析标准，再创建任务。现在该流程已改为后台 job，提交后会显示独立进度弹窗，避免表单长时间卡住。

区域筛选为什么默认建议留空？

区域筛选会显著减少搜索结果，适合明确只看某个区域的场景。若你先验证整体市场，建议先不填。

本地页面打开后提示前端构建产物不存在？

说明根目录 dist/ 缺失。可直接执行 ./start.sh，或先在 web-ui/ 里执行 npm run build，再确认构建产物已复制到仓库根目录。

`./start.sh` 为什么提示缺少 Playwright 或浏览器？

这是脚本的前置检查。请先安装 Playwright CLI 与 Chromium，并确保系统中可用 Chrome / Edge（Linux 环境也可用 Chromium），然后重新执行 ./start.sh。

致谢

点击展开致谢内容

本项目在开发过程中参考了以下优秀项目，特此感谢：

以及感谢LinuxDo相关人员的脚本贡献

以及感谢 LinuxDo 社区。

以及感谢 ClaudeCode/Gemini/Codex 等模型工具，解放双手 体验Vibe Coding的快乐。

注意事项

点击展开注意事项详情

  • 请遵守闲鱼的用户协议和robots.txt规则，不要进行过于频繁的请求，以免对服务器造成负担或导致账号被限制。
  • 本项目仅供学习和技术研究使用，请勿用于非法用途。
  • 本项目采用 MIT 许可证 发布，按"现状"提供，不提供任何形式的担保。
  • 项目作者及贡献者不对因使用本软件而导致的任何直接、间接、附带或特殊的损害或损失承担责任。
  • 如需了解更多详细信息，请查看 免责声明 文件。

Star History

Overview (`chrome-extension/README.md`)

Xianyu Login State Extractor Chrome Extension

This Chrome extension helps extract complete login state information from Xianyu (Goofish) for use with the monitoring robot. It also records browser environment hints and request headers to better mimic a real session.

Installation

  1. Open Chrome and navigate to chrome://extensions
  2. Enable "Developer mode" in the top right corner
  3. Click "Load unpacked" and select the chrome-extension directory
  4. The extension icon should now appear in your toolbar

Usage

  1. Navigate to https://www.goofish.com
  2. Log in to your account
  3. Click the extension icon in the toolbar
  4. Click "Extract Login State" (collects cookies + environment + headers，自动过滤无用/超大字段)
  5. The complete JSON will be displayed - click "Copy to Clipboard"
  6. Save the JSON文本到 xianyu_state.json（或自定义文件名）即可

Features

  • Extracts all cookies including HttpOnly cookies
  • Captures browser environment (UA, locale, timezone, screen size, device memory, hardware concurrency)
  • Captures observed request headers for the current tab
  • Captures localStorage/sessionStorage snapshot for the current domain（会自动丢弃超大或无用字段）
  • Outputs a single JSON payload, ready for the monitoring robot
  • Copy to clipboard with real-time status feedback

How It Works

The extension uses the chrome.cookies API to access all cookies for the .goofish.com domain, including those with the HttpOnly flag set. This bypasses the normal JavaScript security restrictions that prevent access to these cookies.

Overview (`tests/README.md`)

测试指南

本项目使用 pytest 作为测试框架。以下是运行测试的指南。

安装依赖

在运行测试之前，请确保已安装所有开发依赖项：

bash
pip install -r requirements.txt

运行测试

运行所有测试

bash
pytest

运行特定测试文件

bash
pytest tests/integration/test_api_tasks.py

运行特定测试函数

bash
pytest tests/unit/test_utils.py::test_safe_get_nested_and_default

生成覆盖率报告

bash
coverage run -m pytest
coverage report
coverage html  # 生成 HTML 报告

测试文件结构

text
tests/
├── __init__.py
├── conftest.py              # 共享 fixtures（API/CLI/样例数据）
├── fixtures/                # 贴近真实的样例数据（搜索/用户/评价/任务配置）
│   ├── config.sample.json
│   ├── ratings.json
│   ├── search_results.json
│   ├── state.sample.json
│   ├── user_head.json
│   └── user_items.json
├── integration/             # 关键链路集成测试（API/CLI/解析器）
│   ├── test_api_tasks.py
│   ├── test_cli_spider.py
│   └── test_pipeline_parse.py
└── unit/                    # 核心纯函数单元测试
    ├── test_domain_task.py
    └── test_utils.py

编写新测试

  1. 新增测试放在 tests/integration/ 或 tests/unit/
  2. 文件名以 test_ 开头，函数名以 test_ 开头
  3. 测试采用同步执行（不依赖 pytest-asyncio）
  4. 外部依赖（Playwright/AI/通知/网络）统一 mock
  5. 使用 tests/fixtures/ 的样例数据，避免依赖真实网络

注意事项

  1. 目标是离线可跑且稳定复现
  2. 集成测试优先覆盖真实运行链路（API、CLI、解析器）
  3. 如需新增真实场景样例，统一补充到 tests/fixtures/

Live smoke（真实冒烟测试）

  • 目录：tests/live/
  • 默认关闭；仅当显式设置 RUN_LIVE_TESTS=1 时才会执行
  • 推荐命令：
bash
RUN_LIVE_TESTS=1 \
LIVE_TEST_ACCOUNT_STATE_FILE=/absolute/path/to/account.json \
LIVE_TEST_KEYWORD="MacBook Pro M2" \
pytest tests/live -m live -v
  • 一键脚本：
bash
./run_live_smoke.sh
./run_live_smoke.sh --without-generation
  • 可选环境变量：
    • LIVE_TEST_TASK_NAME
    • LIVE_EXPECT_MIN_ITEMS（默认 1）
    • LIVE_TEST_DEBUG_LIMIT（默认 1，只抓取/分析前 N 个新商品）
    • LIVE_TIMEOUT_SECONDS（默认 180）
    • LIVE_ENABLE_TASK_GENERATION（脚本默认 1；设为 0 或使用 --without-generation 可关闭真实 AI 任务生成慢用例）
  • live 套件会在临时工作目录中启动真实 uvicorn，并清空通知相关 env，避免污染仓库根目录或向真实通知通道发消息。

Overview (`web-ui/README.md`)

Vue 3 + TypeScript + Vite

This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 <script setup> SFCs, check out the script setup docs to learn more.

Learn more about the recommended Project Setup and IDE Support in the Vue Docs TypeScript Guide.

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai Browse ai catalog → #ai-assistant Browse ai-assistant catalog → #ai-tools Browse ai-tools catalog → #automation Browse automation catalog → #gemini Browse gemini catalog → #goofish Browse goofish catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →