ai-goofish-monitor/FAQ.md

常见问题解答 (FAQ)

本文档整理了用户在使用 AI-Goofish-Monitor 项目时遇到的常见问题和解决方案。

---

Q1: AI 分析与配置

问：为什么日志显示 任务未配置AI prompt，跳过分析 或 AI推荐：待定；原因：无分析？

答： 这是因为您没有为该监控任务启用或正确配置 AI 分析功能。

1. 打开 config.json 文件。
2. 找到您要配置的任务。
3. 确保 enable_ai_analysis 的值是 true。
4. 确保 ai_prompt_file 指向一个真实存在的、为您需求定制的分析标准 .txt 文件。如果您还没有自己的标准，可以先使用 prompts/macbook_criteria.txt 作为模板。

问：创建任务或运行时，提示 "Request timed out", "Connection error", "404错误" 或 函数 get_ai_analysis ... 尝试失败 是什么原因？

答： 这通常是网络问题或AI服务配置错误，表示你的服务器无法连接到 .env 文件中配置的 OPENAI_BASE_URL。请检查：

• API 密钥问题：检查 .env 文件中的 OPENAI_API_KEY 是否正确、有效，或者账户是否余额不足。
• 网络问题：确保您的服务器可以正常访问 OPENAI_BASE_URL 指定的 AI 服务地址。如果在中国大陆，访问国外 AI 服务（如 OpenAI, Gemini）可能需要设置网络代理。现在你可以直接在 .env 文件中配置 PROXY_URL 变量来解决此问题。
• API端点地址错误：确认 OPENAI_BASE_URL 地址填写正确，并且该服务正在正常运行。如果遇到404错误，建议先使用阿里云或火山引擎等国内服务商的API进行调试。
• 模型名称错误：检查 .env 文件中的 OPENAI_MODEL_NAME 是否是您所用服务提供的正确模型。

问：我选择的 AI 模型不支持图片分析怎么办？

答： 本项目的核心优势之一是结合图片进行多模态分析，因此 必须 选择一个支持图片识别（Vision / Multi-modal）的 AI 模型。如果你配置的模型不支持图片，AI 分析会失败或效果大打折扣。请在 .env 文件中将 OPENAI_MODEL_NAME 更换为支持图片输入的模型，例如 gpt-4o, gemini-1.5-pro, deepseek-v2, qwen-vl-plus 等。

问：如何配置使用 Gemini / Qwen 或其他非 OpenAI 的大语言模型？

答： 本项目理论上支持任何提供 OpenAI 兼容 API 接口的模型。关键在于正确配置 .env 文件中的三个变量：

• OPENAI_API_KEY: 你的模型服务商提供的 API Key。
• OPENAI_BASE_URL: 模型服务商提供的 API-Compatible Endpoint 地址。请务必查阅你所使用模型的官方文档，通常格式为 https://api.your-provider.com/v1 (注意，末尾不需要 /chat/completions)。
• OPENAI_MODEL_NAME: 你要使用的具体模型名称，需要模型支持图片识别，例如 gemini-2.5-flash。

• 示例: 如果你的服务商文档说 Completions 接口是 https://xx.xx.com/v1/chat/completions，那么 OPENAI_BASE_URL 就应该填 https://xx.xx.com/v1。

问：为什么AI模型连接测试失败，提示 "Invalid JSON payload received. Unknown name "enable_thinking": Cannot find field" 错误？

答： 这是因为某些AI模型不支持 enable_thinking 参数导致的。项目现在支持通过环境变量 ENABLE_THINKING 来控制是否添加这个参数：

• 解决方案： 在 .env 文件中设置 ENABLE_THINKING=false，然后重新运行AI模型连接测试。
• 默认行为： 从项目v1.0版本开始，默认情况下 ENABLE_THINKING 设置为 false，不会添加 enable_thinking 参数，以兼容更多AI模型。
• 特殊需求： 如果你使用的AI模型需要这个参数，可以将 ENABLE_THINKING 设置为 true。

---

Q3: 登录与反爬虫

问：为什么 xianyu_state.json 文件会自动消失？

答： 当程序检测到 xianyu_state.json 中的登录凭证失效时，会自动删除该文件，以强制您重新登录获取有效的 Cookie。如果遇到此问题，请重新登录闲鱼后通过chrome插件提取cookie。

问：运行一段时间后被闲鱼检测到，提示“异常流量”或需要滑动验证？

答： 这是闲鱼的反爬虫机制。为了降低被检测的风险，可以尝试以下方法：

• 关闭无头模式: 在 .env 文件中设置 RUN_HEADLESS=false。这样浏览器会以有界面的方式运行，当出现滑动验证码时，你可以手动完成验证，程序会继续执行。
• 降低监控频率: 在 config.json 中，适当调大 scheduler_interval_minutes 的值，例如从 5 分钟改为 15 或 30 分钟。
• 使用代理：（进阶）在 .env 文件中配置 PROXY_URL 来避免IP被封禁。
• 重新登录：删除旧的 xianyu_state.json 文件，重新登录闲鱼后通过chrome插件提取cookie。

---

Q4: 环境与部署

问：运行 login.py 或 spider_v2.py 时出现 'gbk' codec can't encode character 相关的编码错误？

答: 这是典型的 Windows 环境下的编码问题。项目代码和日志默认使用 UTF-8 编码。

• 解决方案: 在运行 Python 脚本前，通过设置环境变量强制使用 UTF-8。在 PowerShell 或 CMD 中执行以下命令，然后再运行脚本：

  set PYTHONUTF8=1
  python spider_v2.py
  

  或者使用 chcp 65001 命令切换活动代码页为 UTF-8。

问：运行 login.py 时提示需要 playwright install 或报错 Old Headless mode has been removed from the Chrome binary 怎么办？

答: 这个错误表示 Playwright 运行所需的浏览器文件缺失或版本不兼容。推荐的解决方法是，确保所有依赖都已通过 requirements.txt 正确安装。请在命令行中运行：

```bash
pip install -r requirements.txt
```

如果问题依旧，可以尝试手动安装或更新 chromium 浏览器：

```bash
playwright install chromium
```

问：pyzbar 在 Windows 上安装失败怎么办？

答: pyzbar 在 Windows 上需要额外的 zbar 动态链接库支持。

• 解决方案 (Windows):

  • 方法1 (推荐): 使用 Chocolatey 安装：

    choco install zbar
    

  • 方法2: 手动下载并添加到 PATH：

    1. 从 zbar releases 下载对应版本的 libzbar-64.dll
    2. 将文件放到 Python 安装目录或添加到系统 PATH

  • 方法3: 使用 conda 安装：

    conda install -c conda-forge zbar
    

• Linux 用户: 直接安装系统包即可：

  # Ubuntu/Debian
  sudo apt-get install libzbar0
  
  # CentOS/RHEL
  sudo yum install zbar
  
  # Arch Linux
  sudo pacman -S zbar
  

问：运行 login.py 时提示 ModuleNotFoundError: No module named 'PIL' 是什么原因？

答: 这个错误通常是因为Python版本过低或者依赖包安装不完整导致的。本项目推荐使用 Python 3.10 或更高版本。

• 解决方案:

  • 确保使用 Python 3.10+ 版本运行项目

  • 重新安装依赖包：

    pip install -r requirements.txt
    

  • 如果问题依旧，可以尝试单独安装 Pillow 包：

    pip install Pillow
    

问：使用 Docker 部署时，日志报错 客户端初始化出错。

答: 这通常是 Docker 容器内共享内存不足导致的。在运行 docker run 命令时，请添加 --shm-size=1gb 参数，例如：

docker run --shm-size=1gb -v "$(pwd)":/app ai-goofish-monitor

如果使用 docker-compose，可以在 docker-compose.yaml 中为服务添加 shm_size: '1gb'。

问：我可以在群晖 (Synology) NAS 上通过 Docker 部署吗？

答: 可以。部署步骤与标准的 Docker 部署基本一致。注意：在群晖环境中部署时，可能需要配置Docker镜像仓库访问权限，确保能够正常拉取镜像。

---

Q5: 功能使用问题

问：如何设置定时任务的执行频率？

答： 定时任务的执行频率由 config.json 文件中的全局参数 scheduler_interval_minutes 控制。它定义了调度器每隔多少分钟检查并执行所有已启用的任务。例如，设置为 10，则所有启用的任务会每隔 10 分钟运行一次。