hot-news-api/TROUBLESHOOTING.md

运行错误解决方案

错误汇总

根据日志，您遇到了以下几类错误：

1. ValueError: 'ellipsis' object is not iterable ✅ 已修复

错误信息：

ValueError: [TypeError("'ellipsis' object is not iterable"), TypeError('vars() argument must have __dict__ attribute')]

原因： 在 FastAPI 的 Query 参数中直接使用 ... (Ellipsis) 作为默认值是不正确的语法。

修复内容：

• ✅ app/api/v1/web_tools.py - get_meta 函数的 url 参数
• ✅ app/api/v1/daily_news.py - search_news 函数的 keyword 参数

修改前：

url: str = Query(
    ...,  # ❌ 错误
    description="..."
)

修改后：

url: str = Query(
    default=...,  # ✅ 正确
    description="..."
)

---

2. Redis 连接失败 ⚠️ 需要启动 Redis 服务

错误信息：

Error parsing JSON: Error 10061 connecting to localhost:6379. 由于目标计算机积极拒绝，无法连接。

原因： Redis 服务未启动或配置不正确。项目依赖 Redis 进行数据缓存。

解决方案：

Windows 系统

方式 A: 使用 Windows Subsystem for Linux (WSL)

# 1. 安装 Redis (如果未安装)
sudo apt-get update
sudo apt-get install redis-server

# 2. 启动 Redis
sudo service redis-server start

# 3. 验证 Redis 是否运行
redis-cli ping
# 应返回：PONG

方式 B: 使用 Docker（推荐）

# 1. 安装 Docker Desktop for Windows
# 下载地址：https://www.docker.com/products/docker-desktop

# 2. 运行 Redis 容器
docker run -d -p 6379:6379 --name redis redis:latest

# 3. 验证
docker ps | grep redis

方式 C: 使用 Windows 原生版本

# 1. 下载 Redis for Windows
# GitHub: https://github.com/microsoftarchive/redis/releases

# 2. 解压后运行
redis-server.exe

# 3. 测试连接
redis-cli.exe

配置修改（可选）

如果 Redis 不在默认端口 6379，需要修改配置文件：

文件： config/config.yaml

redis:
  host: localhost  # 或您的 Redis 服务器 IP
  port: 6379       # 或您的 Redis 端口
  db: 0
  password: ""     # 如果有密码

---

3. MySQL 数据库连接问题 ⚠️ 需要配置

检查配置文件： config/config.yaml

确保 MySQL 配置正确：

database:
  host: localhost
  user: root
  password: your_password
  db: hot_news
  charset: utf8mb4
  autocommit: true

创建数据库：

CREATE DATABASE hot_news CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

---

4. 爬虫抓取失败 ⚠️ 正常现象（首次运行）

错误信息：

2026-03-26 23:39:25 - app - INFO - crawler shaoshupai failed. 0 news fetched
2026-03-26 23:39:31 - app - INFO - crawler weibo failed. 0 news fetched
2026-03-26 23:39:41 - app - INFO - crawler zhihu failed. 0 news fetched
2026-03-26 23:39:43 - app - INFO - crawler 36kr failed. 0 news fetched

原因分析：

1. Redis 未连接 - 没有缓存存储，导致爬虫数据无法保存
2. 网络问题 - 部分网站可能需要代理或反爬对抗
3. 首次运行 - 初始化可能需要时间

解决步骤：

第一步：启动必需服务

# 1. 启动 MySQL
# Windows 服务管理器中启动，或使用命令
net start MySQL80  # 根据您的服务名调整

# 2. 启动 Redis
# 如果使用 Docker
docker start redis

# 如果使用 WSL
sudo service redis-server start

# 如果使用原生 Windows 版本
redis-server.exe

第二步：验证连接

# 测试 MySQL 连接
mysql -h localhost -u root -p
# 输入密码后应能登录

# 测试 Redis 连接
redis-cli ping
# 应返回：PONG

第三步：重新启动应用

cd e:\hot_news-main
python run.py

---

完整的启动流程

前置条件检查清单

• Python 3.8+ 已安装
• MySQL 数据库已安装并运行
• Redis 服务已安装并运行
• Chrome/Chromium 浏览器已安装（用于 Selenium）
• 依赖包已安装：pip install -r requirements.txt

标准启动步骤

# 1. 启动 MySQL
net start MySQL80

# 2. 启动 Redis（选择一种方式）
# Docker 方式
docker start redis

# WSL 方式
wsl sudo service redis-server start

# 3. 验证服务
redis-cli ping  # 应返回 PONG

# 4. 启动应用
cd e:\hot_news-main
python run.py

访问 Swagger 文档

启动成功后，访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• API 测试: http://localhost:8000/health

---

常见问题排查

Q1: Redis 无法启动

Windows Docker 方式：

# 检查 Docker 是否运行
docker ps

# 如果 Docker Desktop 未启动，请先启动 Docker Desktop

WSL 方式：

# 检查 WSL 状态
wsl status

# 重启 Redis 服务
wsl sudo service redis-server restart

Q2: MySQL 连接被拒绝

解决方法：

-- 以 root 用户登录 MySQL
mysql -u root -p

-- 授权远程访问（如果需要）
GRANT ALL PRIVILEGES ON hot_news.* TO 'root'@'localhost' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;

Q3: 爬虫仍然失败

检查项：

1. 网络连接是否正常
2. 是否需要代理（某些网站可能限制访问）
3. Chrome 浏览器是否已安装
4. ChromeDriver 版本是否匹配

临时方案： 如果某些平台持续失败，可以暂时忽略，其他平台仍可正常工作。项目支持 22+ 个平台，部分平台不可用不影响整体功能。

---

快速测试脚本

创建测试文件 test_connection.py：

"""
测试数据库和缓存连接
使用方法：python test_connection.py
"""

import sys

# 测试 Redis 连接
print("🔴 测试 Redis 连接...")
try:
    import redis
    r = redis.Redis(host='localhost', port=6379, db=0)
    r.ping()
    print("✅ Redis 连接成功！")
except Exception as e:
    print(f"❌ Redis 连接失败：{e}")
    print("   请启动 Redis 服务：")
    print("   - Docker: docker run -d -p 6379:6379 --name redis redis:latest")
    print("   - WSL: sudo service redis-server start")
    sys.exit(1)

# 测试 MySQL 连接
print("\n🔵 测试 MySQL 连接...")
try:
    import pymysql
    conn = pymysql.connect(
        host='localhost',
        user='root',
        password='your_password',  # 修改为您的密码
        database='hot_news',
        charset='utf8mb4'
    )
    print("✅ MySQL 连接成功！")
    conn.close()
except Exception as e:
    print(f"❌ MySQL 连接失败：{e}")
    print("   请检查：")
    print("   1. MySQL 服务是否启动")
    print("   2. 数据库 hot_news 是否存在")
    print("   3. 用户名密码是否正确")
    sys.exit(1)

print("\n✅ 所有连接测试通过！可以启动应用了。")
print("\n启动命令：python run.py")

运行测试：

python test_connection.py

---

总结

当前已修复的错误：

• ✅ ValueError: ellipsis 对象错误

需要您手动处理的错误：

• ⚠️ 启动 Redis 服务（参考上述方案）
• ⚠️ 配置 MySQL 数据库（如未配置）
• ⚠️ 爬虫失败（启动 Redis 后通常会恢复正常）

按照上述步骤操作后，系统应该可以正常运行。如有其他问题，请查看具体错误日志。