NewsPy

使用 Python 实现的 NewsNow 新闻采集和 MCP 服务项目。

技术栈

• 包管理: uv (Rust编写的高性能Python包管理器)
• MCP服务: fastmcp v3.2.4 (Model Context Protocol SDK)
• 爬虫: httpx + BeautifulSoup4/lxml
• 数据库: SurrealDB (支持嵌入式文件存储和远程服务器)
• RSS支持: feedparser-rs
• Python版本: 3.12+

项目结构

newspy/
├── newspy/
│   ├── sources/          # 数据源采集器
│   │   ├── __init__.py   # 数据源注册表
│   │   ├── base.py       # 基础爬虫类
│   │   ├── ithome.py     # IT之家
│   │   ├── baidu.py      # 百度热搜
│   │   ├── bilibili.py   # B站热搜/热门视频
│   │   ├── github.py     # GitHub Trending
│   │   ├── rss_source.py # RSS数据源
│   │   └── ...
│   ├── database/         # 数据库操作
│   │   ├── __init__.py
│   │   ├── cache.py      # SurrealDB缓存管理
│   │   └── models.py     # 数据模型
│   ├── settings.py       # 集中配置文件
│   ├── cli.py            # CLI入口点
│   ├── mcp_tool.py       # MCP服务器
│   └── cron.py           # 定时采集脚本
├── scripts/              # 辅助脚本
│   ├── mcp_client.py     # MCP客户端测试
│   └── db_manage.py      # 数据库管理
├── pyproject.toml        # 项目配置 (支持命令行入口点)
├── uv.lock               # 依赖锁定文件
└── CRON.md               # 定时任务详细说明

快速开始

# 安装依赖
uv sync

# 查看所有可用命令
uv run newspy --help
uv run newspy-mcp --help
uv run newspy-cron --help

命令行工具

项目提供三个命令行入口点：

1. newspy - 测试和数据库管理工具

# 列出所有数据源
uv run newspy list

# 测试单个数据源
uv run newspy test ithome -v

# 测试所有数据源
uv run newspy test-all

# 随机获取资讯
uv run newspy random -n 10

# 数据库操作
uv run newspy db --list          # 列出所有缓存
uv run newspy db -s ithome       # 查询指定源缓存
uv run newspy db --clear         # 清空数据库

2. newspy-mcp - MCP服务器

# 启动MCP服务器 (stdio模式)
uv run newspy-mcp

# MCP工具:
# - get_cached_news: 从数据库缓存读取最新资讯
# - get_latest_news: 获取指定数据源的最新资讯
# - list_all_sources: 列出所有可用数据源

3. newspy-cron - 定时采集

# 采集所有数据源
uv run newspy-cron

# 采集指定数据源
uv run newspy-cron -s ithome baidu github

# 设置crontab（每15分钟执行一次）
crontab -e
# 添加：*/15 * * * * cd /path/to/newspy && uv run newspy-cron >> /var/log/newspy-cron.log 2>&1

详细说明请查看 CRON.md。

配置系统

Newspy 使用 settings.py 进行集中配置（类似 Django 风格），所有配置项都支持环境变量覆盖。

环境变量配置

# 代理配置（支持 http/https/socks5）
export NEWSPY_PROXY="http://127.0.0.1:7890"
# 或使用系统代理
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

# 请求超时（秒）
export NEWSPY_TIMEOUT=15

# 数据库连接路径
## 本地文件存储
export NEWSPY_DB_URL="file:///data/newspy"
## websocket服务
export NEWSPY_DB_URL="ws://localhost:8000"

# 禁用特定数据源（逗号分隔）
export NEWSPY_DISABLED="hackernews,github"

# 每个数据源最大新闻条数（0表示不限制）
export NEWSPY_MAX_NEWS=50

# 日志级别
export NEWSPY_LOG_LEVEL=INFO

主要配置项

配置项	环境变量	默认值	说明
PROXY	NEWSPY_PROXY	None	HTTP/SOCKS5代理
REQUEST_TIMEOUT	NEWSPY_TIMEOUT	10	请求超时（秒）
DATABASE_URL	NEWSPY_DB_URL	file://~/.cache/newspy	数据库连接
CACHE_TTL	NEWSPY_CACHE_TTL	1800000	缓存过期时间（毫秒）
CRON_CONCURRENCY	NEWSPY_CONCURRENCY	4	采集并发数
LOG_LEVEL	NEWSPY_LOG_LEVEL	INFO	日志级别
DISABLED_SOURCES	NEWSPY_DISABLED	[]	禁用的数据源
MAX_NEWS_PER_SOURCE	NEWSPY_MAX_NEWS	0	每源最大新闻数

数据源

项目支持 20+ 个数据源，包括：

科技类

• ithome - IT之家
• kr36 - 36氪
• github - GitHub Trending
• juejin - 掘金
• solidot - Solidot
• devto - Dev.to

新闻类

• baidu - 百度热搜
• toutiao - 今日头条
• ifeng - 凤凰新闻
• thepaper - 澎湃新闻
• cankaoxiaoxi - 参考消息
• sputniknewscn - 俄罗斯卫星通讯社

财经类

• wallstreetcn - 华尔街见闻
• gelonghui - 格隆汇
• xueqiu - 雪球
• jin10 - 金十数据

社区类

• nowcoder - 牛客网

视频类

• bilibili - B站热搜/热门视频
• kuaishou - 快手
• douyin - 抖音

其他

• cls - 财联社电报
• ghxi - GHXI
• tencent - 腾讯新闻
• rss_source - RSS数据源（支持自定义）

数据库

Newspy 使用 SurrealDB 作为数据库：

• 嵌入式模式: 默认使用文件存储 (file://~/.cache/newspy)
• 服务器模式: 支持连接远程 SurrealDB 服务器
• 数据格式: JSON 文档存储，支持复杂查询

数据库管理

# 查看数据库状态
uv run newspy db --list

# 查询特定数据源
uv run newspy db -s ithome

# 清空数据库
uv run newspy db --clear

# 或手动删除数据库文件
rm -rf ~/.cache/newspy

添加新数据源

1. 在 newspy/sources/ 目录创建新文件
2. 继承 BaseCrawler 类并实现 crawl() 方法
3. 在 newspy/sources/__init__.py 中注册数据源

示例：

# newspy/sources/example.py
from typing import Any

from .base import BaseCrawler, NewsItem


class ExampleCrawler(BaseCrawler):
    async def crawl(self) -> list[NewsItem]:
        # 实现采集逻辑
        items = []
        # ... 采集代码 ...
        return items


def create_crawler(source_id: str, config: dict[str, Any]) -> BaseCrawler:
    return ExampleCrawler(source_id, config)

然后在 __init__.py 中注册：

from .example import create_crawler as example_factory

def init_all_sources():
    register_source("example", example_factory)
    # ... 其他数据源

开发指南

安装开发依赖

uv sync --group dev

代码风格

# 使用 ruff 进行代码检查和格式化
uv run ruff check .
uv run ruff format .

类型检查

uv run mypy newsy

测试

uv run pytest

故障排查

常见问题

1. 采集失败: 检查网络连接，某些数据源可能需要代理
2. 数据库错误: 确保没有多个进程同时写入数据库
3. 依赖问题: 运行 uv sync 重新安装依赖
4. 代理问题: 设置 Newspy_PROXY 环境变量

日志调试

# 设置详细日志
export NEWSPY_LOG_LEVEL=DEBUG

# 查看cron日志
tail -f /var/log/newspy-cron.log

性能优化

• 并发数: 根据服务器性能调整 Newspy_CONCURRENCY（建议4~16）
• 采集频率: 根据数据源更新频率调整（热榜类515分钟，新闻类3060分钟）
• 数据库: 默认的 SurrealDB 嵌入式模式适合单进程，高并发场景建议使用 SurrealDB Server

许可证

本项目采用 MIT 许可证。