一个基于 GNE(GeneralNewsExtractor) 的多站点新闻抓取工具。
它可以把网页新闻的标题、发布时间、作者、正文、图片自动提取出来,并按时间范围筛选,适合需要定时收集多个网站新闻、通知或公告的场景。
- 输入一篇新闻文章网址,直接输出标题、发布时间、作者、正文、图片;
- 配置多个网站列表页,自动抓取“最近 N 天”的新闻;
- 自动识别大多数常见日期格式;
- 页面正文由 JavaScript 加载时,自动使用 Chrome/Chromium 渲染后再提取;
- 抓取结果自动存入 SQLite,避免重复抓取;
- 使用 Docker 一键部署,并提供部署后的冒烟测试与实时新闻抓取验证。
注意:GNE 本身是“正文抽取器”,不是通用爬虫框架。本工具负责请求网页,GNE 负责从 HTML 中提取新闻正文。
| 文件 / 目录 | 作用 |
|---|---|
news_crawler.py |
多站点批量抓取主程序 |
url_extract.py |
单条文章网址抽取工具 |
api.py |
FastAPI 应用入口(uvicorn api:app) |
news_api/ |
新闻查询 API、异步任务与 SQLite 读模型 |
api_smoke.py |
API 离线冒烟测试(CI 使用) |
sources.json |
仓库自带的空站点配置模板 |
sources.local.json |
本地私人站点配置(被 Git 忽略,不会提交) |
Dockerfile |
容器镜像定义(含 Playwright Chromium) |
docker-compose.yml |
Docker Compose 编排(挂载配置与数据目录) |
docker/entrypoint.sh |
容器统一入口(run/init/test/api/smoke/live-news/shell) |
docker-deploy.sh / docker-deploy.bat |
Docker 一键部署脚本(Linux·macOS / Windows) |
smoke_test.py |
部署后的离线自检脚本 |
verify_live_news.py |
实时新闻抓取验证(默认抽取 10 静态 / 10 JS 渲染 / 10 视频) |
article_archive.py |
公告原文归档:抓取时保留原始快照,索引存库、正文存 gzip 文件 |
backfill_archives.py |
给历史文章补原文快照(默认用库内正文,--fetch-html 才重抓) |
live_news_pool.json |
实时验证页面池(100 静态 / 50 JS 渲染 / 50 视频) |
AGENTS.md |
多 Agent 协作与开发说明(架构、规范、发布流程) |
gne/ |
新闻抽取核心库(重构版,按字段拆分于 gne/extractors/) |
tests/ |
上游自带测试 HTML 样本 |
Docker 部署只需要:
- Docker(含 Docker Compose v2,Docker Desktop 或 Docker Engine 均可)
- 能访问 Docker Hub / PyPI 的网络
本地 Python 环境(可选,主要用于开发):
- Python 3.10+,
pip install -e ".[browser,api]"; ⚠️ 本项目发行包名同样是gne(与 PyPI 上游 GeneralNewsExtractor 相同)。本仓库不向 PyPI 发布,但pip install -e .生成的gne-1.1.2.dist-info与已安装的上游gne在同一环境会互相覆盖,请使用独立虚拟环境,不要与 PyPI 的gne混装。
先在项目根目录(首次使用可执行 git clone https://github.com/Logic769/news-crawler.git && cd news-crawler)操作。
Docker 方式把运行环境(Python、依赖、Playwright Chromium)全部封装进镜像,一次构建即可在 Windows / Linux / macOS 上一致运行;更新时只需重新构建镜像,数据与配置通过挂载保留,便于统一管理和跨平台更新。
Linux / macOS:
chmod +x docker-deploy.sh
./docker-deploy.shWindows(PowerShell 或直接双击):
.\docker-deploy.bat脚本会自动完成:构建镜像 → 初始化数据库 → 运行冒烟测试,看到 SMOKE TEST PASSED 即表示成功。
# 1. 准备私有站点配置(首次)
cp sources.json sources.local.json # Windows 用:Copy-Item sources.json sources.local.json
# 然后按“多站点批量抓取”章节填写站点
# 2. 构建镜像
docker compose build
# 3. 初始化数据库 + 冒烟测试
docker compose run --rm crawler init
docker compose run --rm crawler smokedocker compose run --rm crawler run --config sources.local.json --days 3常用参数:--days、--since、--workers、--limit-per-source、--force。
测试列表解析:
docker compose run --rm crawler test --config sources.local.json --name <站点名>仓库内置 live_news_pool.json(100 个静态文本页 / 50 个 JS 渲染页 / 50 个视频页,覆盖国内媒体、高校与政府网站),从中随机抽取页面做真实抽取:
# 默认抽取 10 静态 + 10 JS 渲染 + 10 视频,全部通过才算成功
docker compose run --rm crawler live-news
# 指定数量或固定随机种子(便于复现失败)
docker compose run --rm crawler live-news --static 10 --dynamic 10 --video 10 --seed 20261030该命令访问公开新闻站点,覆盖直接 HTTP、Chromium 渲染与视频页三条抽取路径。抽到的页面失效时会自动从池中补抽(日志打印 REPLACED PAGES),补不足目标数量则直接失败;失败时按日志里的 LIVE NEWS SEED 用 --seed 复现。池子维护方法见 AGENTS.md 第 10 章。
- 私有站点配置
sources.local.json以只读方式挂载进容器,不会打包进镜像,也不会提交到 Git; - 数据库落在宿主机
./data/news.db(容器内/app/data/news.db),重新构建镜像不会丢失; - 已有的旧
news.db可直接移动到data/news.db继续使用; - 首次使用裸
docker compose run前请确保已存在sources.local.json(否则 Docker 会把只读挂载点建成目录导致报错);docker-deploy.sh/.bat已自动处理; - 容器默认以 root 运行,以规避 Windows/Linux 之间 bind mount 的 UID 权限不一致;如需更高安全可改用非 root 用户 + 命名卷;
- 默认镜像自带浏览器:默认构建即安装 Playwright Chromium(
INSTALL_BROWSER=1),可处理 JS 动态页面与视频页;仅在确定不需要浏览器时用INSTALL_BROWSER=0构建精简版。 - 视频页适配:对
/shipin/、/video/等视频页,改用页面 meta、JSON-LD 与 URL 日期提取标题、简介与发布时间,避免正文过短和发布时间误判(默认镜像已带 Chromium,可渲染后再判断)。 - 构建可复现:基础镜像按 digest 固定(
Dockerfile的FROM ...@sha256:...),依赖版本由docker/constraints.txt锁定(源自uv.lock);升级依赖请同步uv.lock与docker/constraints.txt。
# PyPI 镜像加速
PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple docker compose build
# 同时加速 Playwright 浏览器下载
PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright \
docker compose build不需要 JS 渲染、希望镜像更小:
INSTALL_BROWSER=0 docker compose build(之后遇到动态页面将无法回退渲染)。
git pull
docker compose build # 重新构建镜像
docker compose run --rm crawler smoke # 可选:验证数据与配置都在宿主机挂载目录中,更新镜像不影响已有数据。
docker-compose.yml 提供 scheduler 服务:默认每天 09:00 / 15:00(Asia/Shanghai)执行一次抓取,抓取成功后自动调用 news-insight 的 POST /v1/jobs 提交分析作业。
docker compose up -d scheduler # 启动定时采集(restart unless-stopped)
docker compose logs -f scheduler # 查看下次触发时间与抓取日志
docker compose run --rm scheduler scheduler --once # 立即执行一次,便于验证| 环境变量 | 默认值 | 说明 |
|---|---|---|
SCHEDULE_TIMES |
09:00,15:00 |
每日触发时间,逗号分隔 |
SCHEDULE_TIMEZONE |
Asia/Shanghai |
调度时区 |
CRAWL_DAYS |
3 |
每次抓取的最近天数 |
INSIGHT_URL |
http://host.docker.internal:8020 |
采集成功后触发的分析服务;设为空则只采集不分析 |
INSIGHT_API_KEY |
空 | 调用 insight /v1/jobs 时携带的 X-API-Key |
ANALYZE_LIMIT |
1000 |
单次分析作业上限 |
调度器使用 data/.crawl.lock 文件锁防止上一轮未结束时重复启动;单轮抓取失败只记日志,下一轮照常执行。整轮只产生错误、没有任何有效产出时 news_crawler.py run 返回非零退出码,调度器不会提交分析作业。若只想手动抓取,保持 scheduler 服务不启动即可。
抓取结果除了直接读 SQLite,还可以通过标准 HTTP API 提供给下游系统。API 与抓取共用同一个数据库,默认只读查询;抓取动作通过异步任务执行。
docker compose up -d api
docker compose logs -f api
curl http://localhost:8000/v1/health- Swagger 文档:http://localhost:8000/docs
- OpenAPI:http://localhost:8000/openapi.json
- 容器内固定监听
8000;宿主机端口用NEWS_API_PORT覆盖(例如NEWS_API_PORT=9000 docker compose up -d api)。 - 只启动 API 不会自动抓取;抓取仍用
crawler服务或下面的异步任务。
| 环境变量 | 默认值 | 说明 |
|---|---|---|
NEWS_DB |
/app/data/news.db |
SQLite 路径(compose 已设置) |
NEWS_CONFIG |
代码内 sources.json;compose 设为 /app/sources.local.json |
站点配置路径 |
NEWS_API_KEY |
空 | 设置后所有 /v1 业务接口校验 API Key;/v1/health 与文档保持开放 |
NEWS_API_BIND |
127.0.0.1 |
仅 compose 的宿主机监听地址;需要局域网访问时设为 0.0.0.0 |
NEWS_API_PORT |
8000 |
仅 compose 的宿主机映射端口 |
NEWS_JOB_WORKERS |
1 |
异步任务并发数;SQLite 单写者,建议保持 1 |
NEWS_TIMEZONE |
Asia/Shanghai |
默认时区,用于无时区时间与日期过滤 |
NEWS_CORS_ORIGINS |
空 | 逗号分隔的允许来源;为空不启用 CORS |
NEWS_ALLOW_PRIVATE_URLS |
空(关闭) | 允许 extract 抓取回环/内网地址;仅可信环境开启 |
NEWS_EXTRACT_ALLOW_BROWSER |
空(关闭) | 允许 extract 在直接抓取失败时回退无头浏览器;仅在可信环境开启 |
NEWS_MAX_PENDING_JOBS |
50 |
排队 + 运行中的作业上限,超出返回 429;相同类型与参数的未完成作业会复用 |
NEWS_REQUIRE_AUTH |
空(关闭) | 设为 1 时要求必须配置 NEWS_API_KEY,否则业务接口一律返回 401 |
NEWS_INSECURE_SSL |
空(关闭) | 设为 1/true/yes/on 时,证书校验失败会打印 WARNING 并降级为不校验重试;默认直接抛错,避免中间人攻击 |
NEWS_BACKUP_DIR |
/app/backups(compose) |
站点配置写入前的 JSON 备份目录;每次 /v1/admin/sites 变更都会在此保留一份 sources_local_<时间戳>.json |
安全提示:未设置
NEWS_API_KEY时接口完全开放。compose 默认只监听127.0.0.1;如需局域网访问,请同时设置强随机NEWS_API_KEY再改NEWS_API_BIND=0.0.0.0。extract默认拒绝回环、内网与保留地址,并在每次 HTTP 重定向时重新校验目标;默认还禁用浏览器回退,避免通过页面 JS 绕过地址限制。确需抓取内网新闻时设置NEWS_ALLOW_PRIVATE_URLS=1;确需浏览器渲染时再加NEWS_EXTRACT_ALLOW_BROWSER=1。开启
NEWS_EXTRACT_ALLOW_BROWSER=1等于放弃上述地址限制:Chromium 会自行解析 DNS 并跟随跳转,extract只对初始 URL 与 HTTP 层的每一跳做校验。另外 DNS 解析与真正建连是两次独立查询,仍存在 DNS rebinding 的理论窗口。因此公网部署请始终设置NEWS_API_KEY(或NEWS_REQUIRE_AUTH=1),并保持浏览器回退关闭。
用
docker compose部署时,API 的变量通过 compose 的白名单透传,需要在项目根目录的.env或当前 shell 中设置后才生效(例如NEWS_API_KEY=... docker compose up -d api)。
设置 API Key 的示例(bash):
NEWS_API_KEY=change-me docker compose up -d api
curl -H "X-API-Key: change-me" http://localhost:8000/v1/articles
# 也支持:-H "Authorization: Bearer change-me"| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/health |
健康检查,不需要 API Key |
| GET | /v1/articles |
分页查询文章列表 |
| GET | /v1/articles/{id} |
文章详情(始终包含正文) |
| GET | /v1/articles/{id}/archives |
该文章的原文快照列表(raw_html 原始页面 / api_response 接口响应 / body_html 清洗正文) |
| GET | /v1/archives/{archive_id} |
下载某份原文快照(直接返回解压后的内容,带 X-Archive-SHA256) |
| GET | /v1/sources |
按站点聚合的统计 |
| GET/POST/PUT/DELETE | /v1/admin/sites |
管理站点配置:列表、新增、按 name 更新、删除;写入前自动备份到 NEWS_BACKUP_DIR。接口型源(api 配置)只能在原配置上修改分类/地区/时区/渲染/启停等非接口字段,抓取地址与 XPath 由接口配置维护 |
| GET | /v1/stats |
全库统计 |
| POST | /v1/jobs |
创建异步任务(crawl 或 extract) |
| GET | /v1/jobs |
任务列表 |
| GET | /v1/jobs/{id} |
任务状态与结果 |
/v1/health 在数据库异常时返回 503 和 {"error":{"code":"database_unavailable","status":503,"message":"数据库不可用"}},可直接作为容器健康检查探针。其余错误统一为 {"error":{"code":"http_error","status":<HTTP 状态码>,"message":"..."}};参数校验失败时 code 为 validation_error、status 为 422,并额外带 details。
# 最近发布(默认只返回 status=ok,列表不含正文)
curl "http://localhost:8000/v1/articles?page_size=20"
# 需要正文时显式开启
curl "http://localhost:8000/v1/articles?include_content=true&page_size=5"
# 按站点、时间范围、关键词过滤
curl "http://localhost:8000/v1/articles?source=chinanews&published_from=2026-10-01&published_to=2026-10-30&q=经济"
# 查看全部状态(ok/old/no_content/unknown_date/error)
curl "http://localhost:8000/v1/articles?status=all&page_size=50"| 参数 | 说明 |
|---|---|
status |
ok(默认)、old、no_content、unknown_date、error、all |
source |
站点名,对应配置里的 name |
published_from / published_to |
日期或 ISO 时间;只写日期时按 NEWS_TIMEZONE 解释,结束日期包含当天。项目申报行 publish_time 为空,会被这两个参数排除 |
deadline_from / deadline_to |
项目申报专用:按 deadline 过滤(站点墙钟),只写日期时结束日期包含当天;带时区偏移的时间只取墙钟部分,不做时区换算;与 published_from/published_to 同时传会 AND 成空集,请二选一 |
q |
标题、列表标题、正文的模糊搜索 |
page / page_size |
分页,page_size 最大 100 |
order |
published_desc(默认)、published_asc、updated_desc、deadline_desc、deadline_asc |
include_content |
列表是否返回正文,默认 false |
文章对象中的关键字段:
| 字段 | 说明 |
|---|---|
id |
稳定文章 ID(按 source + url 生成),详情接口使用 |
title / author |
标题、作者 |
published_at |
带时区的 ISO 8601 发布时间,例如 2026-10-30T10:00:00+08:00 |
published_at_utc |
同一时间的 UTC 表示,以 Z 结尾 |
published_raw |
数据库里的原始发布时间字符串 |
publish_time_source |
发布时间来源:xpath(详情页配置的 XPath)、labeled_text(“发布时间:…”标签)、meta(meta/JSON-LD/time 标签)、text(正文扫描)、video_meta(视频页 meta)、detail(其他详情页来源)、list(回退列表页日期);历史行或无法判定时可能为空字符串 |
publish_time_raw |
详情页抽取到的发布时间文本(XPath 场景可能是匹配出的日期子串;文本扫描可能只有“09月30日”这类无年份日期),便于核对日期为什么被回退 |
list_publish_time |
列表页解析出的日期;详情日期缺失或与列表相差过大时用于交叉校验 |
title_source |
标题来源:article_title_xpath(配置的标题 XPath 实际命中)、gne_default(未命中时回退 GNE 自动识别)或 list_title(项目申报列表行使用列表标题) |
deadline / deadline_raw |
项目申报专用:解析后的截止时间(YYYY-MM-DD HH:MM:SS)与列表页原文;新闻站点为空 |
project_status |
项目申报专用:列表页的申报状态文本(如“申报中”“已截止”);新闻站点为空 |
timezone |
该文章写入时使用的站点时区(落库保存,站点配置变化不影响历史数据;unknown_date 等没有发布时间的结果不会写入该列,API extract 路径同样如此) |
content / content_length |
正文与字数(已归一化为单行;列表默认不返回,详情始终返回) |
raw_content |
GNE 原始正文,保留段落换行;只在 GET /v1/articles/{id} 详情返回,列表(含 include_content=true)为 null;v4 之前入库的历史行为空,需 --force 重抓,或用 backfill_raw_content.py 回填(先 --dry-run 看候选数,再 --limit 50 小批试跑;容器内必须显式传 --db /app/data/news.db,命令见 AGENTS.md §8) |
body_html |
清洗后的正文 HTML(v9 新增,供下游详情页渲染):白名单标签/属性,去掉脚本、事件属性与可执行 URL;与 raw_content 一样只在详情接口返回,列表默认不返回;历史行可用 backfill_body_html.py 回填(只写 body_html,不改 content/raw_content/status/updated_at,可重复运行;修复抽取器后重刷已有行用 --overwrite;接口型源拿不到原始 HTML 时用 --from-raw 从 raw_content 派生安全 HTML) |
images |
图片 URL 数组 |
status / error |
抓取状态与错误信息 |
时间排序与过滤基于数据库内的站点本地时间字符串。若同时接入不同时区的来源,分页排序与
published_from/published_to区间可能存在偏差:建议统一各站点的timezone,或在展示层用published_at_utc做二次校准。升级前写入的老数据没有timezone列,会回落到当前配置推断。详情页日期若晚于当前时间超过 1 天,视为不可信:不会再自动减一年,而是回退到列表页日期;列表日期也缺失时记
unknown_date。GNE 的文本扫描可能只抽到
09月30日这类无年份日期:主抓取路径会优先用列表日期的年份补齐;列表日期也缺失时,以及 API 单 URL extract 没有列表日期可交叉校验时,这类日期会记unknown_date,不会按当前年猜测。
old分支的publish_time_source取决于判定时机:列表阶段就确认超出窗口时记list;详情抓取后才发现超出窗口时保留详情来源(xpath/labeled_text/meta/text)。publish_time_raw与当前publish_time同步:回退到列表日期时清空,不再保留旧详情原文;unknown_date本次没有可信发布时间,新插入行会保留本次抽取文本便于排查,已有行则保留旧值与旧时间配对,避免“旧时间挂新来源”;新行的publish_time_source为空字符串,已有行保留旧来源。
详情示例:
curl "http://localhost:8000/v1/articles/<article_id>"创建任务后立即返回 202 和任务 ID,用任务详情轮询结果。任务持久化在 SQLite 的 crawl_jobs 表,服务重启时 queued 任务会继续执行,中断的 running 任务会标记为失败。排队与运行中的作业总数受 NEWS_MAX_PENDING_JOBS 限制,超出返回 429;相同类型与参数的未完成作业会复用同一任务 ID;已完成作业保留 30 天后自动清理。
任务写库采用“部分更新”语义:某次抓取失败只会把该文章标记为
error并记录原因,已经成功抓到的正文、标题、发布时间不会被清空。
# 按 sources.local.json 抓取最近 3 天
curl -X POST http://localhost:8000/v1/jobs \
-H "Content-Type: application/json" \
-d '{"type":"crawl","days":3}'
# 只抓某个站点,并限制条数
curl -X POST http://localhost:8000/v1/jobs \
-H "Content-Type: application/json" \
-d '{"type":"crawl","source":"chinanews","days":1,"limit_per_source":5}'
# 抓取单篇文章(默认 source=on_demand)
curl -X POST http://localhost:8000/v1/jobs \
-H "Content-Type: application/json" \
-d '{"type":"extract","url":"https://example.com/article.html"}'
# 轮询
curl http://localhost:8000/v1/jobs/<job_id>crawl 参数:source、days、since(YYYY-MM-DD)、workers、limit_per_source、force。
extract 参数:url(必填)、source。
extract 的目标地址在提交时即校验:回环、内网与保留地址返回 400(除非设置 NEWS_ALLOW_PRIVATE_URLS=1)。抓取或抽取失败时作业状态为 failed,同时该 URL 在 articles 中留一条 status=error 记录,便于后续重试。
查询与抓取可以同时进行;但手动
docker compose run crawler run与crawl任务都会写同一个 SQLite,建议错开执行,或把NEWS_JOB_WORKERS保持为 1。
docker compose run --rm --entrypoint python crawler -X utf8 url_extract.py "https://example.com/article.html"把网址替换成真实新闻文章页。成功后会在终端输出 JSON:
{
"url": "https://example.com/article.html",
"title": "新闻标题",
"publish_time": "2026-09-07 18:00:00",
"author": "作者",
"content": "新闻正文……",
"images": []
}推荐使用 sources.local.json 保存自己的站点配置,这样即使以后提交代码,也不会把站点列表公开:
Windows:
Copy-Item sources.json sources.local.jsonLinux / macOS:
cp sources.json sources.local.json用任意文本编辑器打开 sources.local.json,在 sources 数组中添加站点:
{
"workers": 16,
"days": 3,
"timezone": "Asia/Shanghai",
"delay": 0.3,
"sources": [
{
"name": "example",
"list_url": "https://example.com/news.html",
"item_xpath": "//ul[contains(@class,'news-list')]/li",
"title_xpath": ".//a",
"url_xpath": ".//a/@href",
"date_xpath": ".//*[contains(@class,'time')]",
"date_format": "%Y-%m-%d",
"timezone": "Asia/Shanghai",
"date_skew_days": 7
}
]
}| 字段 | 是否必填 | 说明 |
|---|---|---|
name |
必填 | 站点唯一标识,例如 ncu_news |
enabled |
可选 | 默认 true;设为 false 时 load_config 会在抓取前过滤掉该源,便于临时停用而不删配置 |
list_url |
二选一 | 新闻列表页地址 |
list_urls |
二选一 | 多个固定列表页地址组成的数组(旧版分页方式;单 list_url 站点请优先用 pagination) |
item_xpath |
必填 | 定位每条新闻节点的 XPath |
title_xpath |
可选 | 标题 XPath,不填默认取第一个 a 标签 |
url_xpath |
可选 | 详情页链接 XPath,不填默认取第一个 a 标签的 href |
date_xpath |
可选 | 发布日期 XPath,不填则从整条节点文本中自动识别 |
date_format |
可选 | 日期格式,例如 %Y-%m-%d、%Y-%m-%d %H:%M |
timezone |
可选 | 站点时区,默认 Asia/Shanghai;未配置时继承顶层 timezone,空串或非法时区名在加载配置时同样回退到顶层(默认 Asia/Shanghai),其中非法时区名会记一条 WARNING,不会静默使用运行环境本地时区 |
article_title_xpath |
可选 | 详情页标题 XPath。用于 <title> 写的是站点名、真标题在正文 h1 的站点(如科技部计划通知)。推荐直接写标题元素(如 //h1[@class='article-title']),会取其全部文本(含 <em> 等子元素);写成 //h1/text() 只能取第一个直接文本节点,标题含子标签时会截断。以 string( 开头的表达式会被忽略。不配这个字段时,GNE 还有一层兜底:<title> 被判定为站点名(不超过 24 字、以“网站/门户/官网/平台/系统/首页/新闻网”之一结尾、且不含 - 之类分隔符)、页面又恰好只有一个非空 h1(8–200 字、自身也不像站点名)时,会用该 h1 作为标题(display:none 等不可见节点——含 h1 自身或任一祖先容器,style 里的制表符/换行/全角空格会被归一——与 <template>/<noscript> 里的模板 h1 不计入唯一性);多 h1 页面保持原行为,宁可留站点名也不猜。注意唯一 h1 也可能是机构名(如“XX省科学技术厅”),这层兜底只保证不会停在站点名,不保证一定取到文章标题;按 class 或外部样式表隐藏的 h1(如 sr-only)无法识别;<title> 不以这些词结尾的机构名(如“XX省人民政府”)也不会被识别,这类站点请显式配 article_title_xpath |
article_publish_time_xpath |
可选 | 详情页发布时间 XPath。用于正文里更早出现无关时间、页头日期才是真发布时间的站点;推荐写包含日期的元素(如 //p[contains(@class,'article__subTitle')]/span[1])。以 string( 开头或非法表达式会被忽略 |
article_body_xpath |
可选 | 详情页正文容器 XPath,透传给 GNE 的 body_xpath。用于默认密度算法被页面其他长文本块带偏、或正文抽不出来的站点(例://div[@id='ivs_content'])。必须是元素节点表达式:写成 //div/@id、//div/text() 这类属性/文本表达式,或表达式未命中、命中的容器没有文本时,都会记一条 WARNING 并回退整页 //body,不会中断抓取;命中多个节点时只用第一个并记 WARNING(建议写成唯一元素表达式);以 string( 开头或非法表达式在加载配置时就被忽略。正文与配图仍会在该容器内按密度算法取最佳子块(容器内并列多个正文块时可能只取一段),收窄容器也会漏掉容器外的配图。视频页(/shipin/、/video/ 等)走 meta 抽取,优先于本字段 |
date_skew_days |
可选 | 详情日期与列表日期允许相差的天数,默认 7,范围 0–365;超过时改用列表日期,避免正文里的未来时间或站内推荐日期污染发布时间 |
listing_type |
可选 | 列表类型:news(默认)或 project_application。项目申报模式把列表本身当作数据源,见下方“项目申报列表” |
deadline_xpath |
可选 | 项目申报:截止时间所在单元格 XPath(相对条目节点) |
deadline_format |
可选 | 项目申报:截止时间格式,默认回退 date_format |
project_status_xpath |
可选 | 项目申报:申报状态所在单元格 XPath |
content_required |
可选 | 项目申报:是否必须抓到详情正文。默认 false(登录墙/无正文仍记 ok 并存列表字段);设为 true 退回新闻语义(无正文记 no_content/error) |
pagination |
可选 | 自动分页配置对象,见下方“自动分页(可选)”;只对单个 list_url 生效,配置 list_urls 时仍按固定地址列表抓取(不受 max_pages/stop_when_older_than_cutoff 影响) |
api |
可选 | 接口型源配置对象,见下方“接口型源(可选)”。配置后不再抓列表页 HTML,改为直接请求 JSON 接口翻页;与 list_url/list_urls/pagination 互斥(同时配置时以 api 为准并记一条 debug 日志) |
render |
可选 | 设为 true 表示列表页需要用 Chrome 渲染后再解析 |
delay |
可选 | 每个请求之间的等待秒数,默认 0.3(接口型源同样是"两次请求之间",最后一页抓完不再等待) |
顶层还可以配置
workers(同时处理几个站点,默认 16)和days(默认抓取天数)。内存提示:
workers是站点级线程数;开启浏览器回退时,每个线程可能各自启动一个 Chromium(约 200–300 MB)。workers=16建议至少 4 GB 可用内存;小内存机器或 JS 站点较多时请调低--workers,否则可能被 OOM Kill。
列表页是 index_2.html 这类固定模板时,不必再手写 list_urls:
"pagination": {
"mode": "template",
"url_template": "https://example.com/news/index_{page}.html",
"total_pages_regex": "index_(\\d+)\\.html",
"start": 2,
"max_pages": 50,
"stop_when_older_than_cutoff": true,
"stop_after_known_pages": 0
}| 字段 | 默认值 | 说明 |
|---|---|---|
mode |
none |
none 只抓 list_url;template 按 url_template 生成后续页;next 跟随“下一页”链接;auto 有模板用模板,否则跟随下一页 |
url_template |
空 | 页码模板,必须包含 {page};缺少占位符时 template 模式回退为只抓首页,auto 模式改走下一页 |
last_url_xpath |
空 | 尾页链接 XPath;命中元素时读取 href/onclick/data-page/value 和文本作为候选,最终取最大页码(data-page="12" 这类纯数字直接作为页码)。不填时从整页 HTML 用 total_pages_regex 探测 |
next_url_xpath |
空 | “下一页”链接 XPath;支持相对地址,也兼容常见 onclick=location.href=... 写法 |
total_pages_regex |
(?:index_|page[=/])(\\d+) |
从 HTML 提取最大页码的正则,捕获组必须是数字(表格中 \| 表示正则里的或) |
start |
1 |
模板模式从第几页开始生成(第 1 页始终是 list_url,通常设为 2);范围 1–1000 |
max_pages |
50 |
最多抓取页数(含 list_url 计 1 页,后续页最多 max_pages-1 个);范围 1–500 |
stop_when_older_than_cutoff |
true |
当前页最晚日期早于抓取窗口起点时停止翻页(整页每条都能解析出日期且都早于窗口才停,避免置顶旧文或缺失日期导致漏抓);项目申报模式不按发布日期早停,窗口判断只看 deadline |
stop_after_known_pages |
0 |
连续 N 页链接都已入库时停止(增量运行);范围 0–100,默认 0 关闭;仅 template/next/auto 模式生效。开启后若上次运行更后页失败,可能提前停止,建议确认完整抓取后再开 |
未配置 render: true 时,列表页解析为空会自动用 Chrome 渲染一次,并基于渲染后的 DOM 重新解析与继续翻页。自动分页会在页内按 URL 去重,并在 test 命令输出页数与停止原因(如 cutoff、known_pages、no_next、max_pages、empty、fetch_failed、done)。
自动分页会为列表页启用 SSRF 地址白名单:配置的 list_url/list_urls 是唯一可信目标,且要求 scheme + host + port 完全一致;其他目标必须是公网地址,并且只允许 http 80 / https 443 端口。指向配置主机其他端口的链接会被拒绝;同端口无法按路径区分,配置主机本身视为可信。带地址校验的列表页请求为直连(不读取 HTTP(S)_PROXY),文章详情页保持原有代理行为。浏览器回退时每个请求都会重新校验,但 Playwright 自行解析 DNS,无法像 HTTP 路径那样在连接层钉扎 IP,残余 DNS rebinding 风险需由出口网络策略兜底。
有些站点的列表页是纯前端渲染(SPA),DOM 里连详情链接都没有,只有后端 JSON 接口能拿到数据。这类站点用 api 声明成接口型源:爬虫不再抓列表页 HTML,而是按接口翻页取条目;接口返回的正文随条目一起进库,不再请求详情页、也不跑 GNE(详情页往往还是同一个 SPA,抓下来同样没有正文)。此时条目的 title_source 记为 api_field,便于下游区分「接口列表给的标题」与「详情页抽取的标题」。
{
"name": "shpolicy_ssme",
"api": {
"url": "https://shpolicy.ssme.sh.gov.cn/governmentCloudApi/chatSNet/policyDoc",
"method": "POST",
"payload": {"area": "上海市", "newsCategory": null, "name": null, "department": null},
"headers": {"Referer": "https://shpolicy.ssme.sh.gov.cn/knowledge/"},
"items_path": "data.respData.dataList",
"total_path": "data.respData.total",
"page_param": "pageNum",
"page_size_param": "pageSize",
"page_size": 100,
"start_page": 1,
"max_pages": 20,
"url_field": "originalURL",
"id_field": "id",
"title_field": "name",
"date_field": "publishTime",
"content_field": "content",
"content_is_html": true
},
"timezone": "Asia/Shanghai",
"delay": 0.8
}| 字段 | 默认值 | 说明 |
|---|---|---|
url |
必填 | 接口地址;含 {page} 时按页替换 |
method |
POST |
GET 或 POST;其他值记 WARNING 并回退 POST。请求方法只看这个字段,与 payload 无关 |
payload |
空 | 请求体基础字段,只在 POST 模式生效(GET 模式不会传递 payload,写进去的筛选条件会被静默丢弃);页码与每页条数会合并进去。带 body 的 GET 只属于直接调用 fetch_json 的底层契约,源配置里做不到 |
base_url |
接口地址的 scheme://host/ |
补全接口返回的相对链接("/p/1.html")时用的基准;接口与详情页不同域时显式写,例如 https://www.example.com/ |
headers |
空 | 额外请求头,如 Referer(不少接口校验来源) |
items_path |
必填 | 条目数组的点号路径,支持数组下标(如 data.list.0.items);为空记 ERROR,该站点不会有数据 |
total_path |
空 | 总数点号路径,用于提前判断是否还有下一页 |
page_param |
pageNum |
页码参数名(仅 POST 生效,见下方“GET 模式的页码”) |
page_size_param |
pageSize |
每页条数参数名(仅 POST 生效) |
page_size |
20 |
每页条数,范围 1–500;超出接口实际上限时以接口返回条数为准(偏大会导致“不足一页即末页”的判断提前触发) |
start_page |
1 |
起始页码,范围 1–10000 |
max_pages |
20 |
最多请求页数,范围 1–500 |
url_field |
originalURL |
详情链接字段名;取不到时用 url_template 的 {id} 兜底,两者都没有则跳过该条并记 WARNING |
url_template |
空 | 详情链接模板,如 https://example.com/detail/{id},{id} 由 id_field 填充 |
id_field |
id |
条目 ID 字段名(供 url_template 使用,也写进 entry) |
title_field |
name |
标题字段名,经 clean_title() 清洗后入库 |
date_field |
publishTime |
发布日期字段名;字段为空时才回退解析详情链接里的日期路径(字段有值但解析失败则留给 process_entry 按 unknown_date 处理,不猜) |
date_format |
空 | 日期格式,默认交给 parse_datetime 自动识别 |
content_field |
content |
正文字段名;有值时随条目入库,跳过详情页抓取 |
content_is_html |
true |
正文字段是 HTML 时先转纯文本(保留段落换行,顺带取出 <img> 配图) |
author_field |
空 | 作者字段名 |
stop_when_older_than_cutoff |
true |
整页日期都早于抓取窗口时停止翻页(与 HTML 分页同口径;项目申报模式不据此早停) |
stop_after_known_pages |
0 |
连续 N 页条目都已入库时停止;范围 0–100,默认关闭 |
不支持与项目申报模式组合:listing_type: project_application 与 api 同时配置时,load_config 会记一条 WARNING。项目申报走的是列表字段路径,不读接口给的正文、也没有截止时间字段映射,结果是正文被丢弃、deadline 为空;需要这种数据源时请改用新闻模式,或等后续补上 deadline_field 映射。
GET 模式的页码:只有 method: POST 会把 page_param/page_size_param 合并进请求体;GET 模式不拼查询串,页码只能靠 url 里的 {page} 占位符(例如 https://example.com/api/list?page={page}&size=50)。两者都没有时每页都会请求同一个 URL,靠跨页 URL 去重后第一页就因“没有新条目”停止,只会拿到首页数据。GET 模式同样不发送 page_size,但采集器仍用它判断末页(本页条数少于 page_size 即视为最后一页),所以 page_size 必须设成接口每页实际返回的条数,否则第一页就会被当成末页。
与列表页配置的关系:api 与 list_url/list_urls/pagination 互斥,同时配置时以 api 为准并记一条 debug 日志。接口请求与 HTML 抓取共用同一套网络层(总时限、解压体积上限、NEWS_INSECURE_SSL 降级),响应编码按 Content-Type 的 charset → UTF-8 → GB18030 依次尝试(政务系统的 GBK 接口很常见,直接 UTF-8 硬解会让整批字段静默变乱码;声明的 charset 解不开而降级成功时记一条 INFO 日志,便于排查到底按哪个编码解的)。headers 只用于补正 Referer/Cookie 这类站点要求的头,它会覆盖默认 User-Agent,写错会直接导致接口拒绝。
地址校验:接口型源以配置的 api.url 作可信锚点——只有该 origin 允许指向内网地址,其余重定向目标必须是公网 http 80 / https 443,连接层还会按真实解析出的 IP 再校验一次(防 DNS rebinding)。重定向到不同 origin 时会剥掉 Cookie/Authorization 请求头,避免接口凭据被恶意 302 送到第三方。这条校验路径会禁用环境代理(直连),与 API extract 的 url_validator 路径同一取舍。
test 命令会打印接口采集页数、停止原因(cutoff/known_pages/done/empty/fetch_failed/max_pages)与解析条数:
docker compose run --rm crawler test --config sources.local.json --name shpolicy_ssme项目申报公告的列表页本身就是完整数据:标题、截止时间、申报状态和详情链接都在表格里,而详情页常需要登录。把站点声明为项目申报类型后:
deadline_xpath解析出的截止时间写入deadline/deadline_raw,不会被当成publish_time;列表页自身的发布日期仍按date_xpath正常写入publish_time/publish_time_utc/list_publish_time(publish_time_source=list),两者互不影响;未配置date_xpath的列表(只有截止时间列)项目行published_at为空,按发布时间排序会排在末尾;配置了date_xpath但单元格文本无法解析成日期(如“待定”)时,项目行不会退回去解析 URL 里的日期路径,publish_time保持空或沿用旧值——新闻模式仍保留这一回退。/v1/articles提供order=deadline_desc|deadline_asc与deadline_from/deadline_to专门查询项目公告;published_from/published_to只命中配置了date_xpath的项目行;project_status_xpath解析出的状态写入project_status;title与list_title都写列表标题,title_source=list_title;列表标题取自title_xpath,若写的是属性(如.//a/@title),属性值里的字面量 HTML 标记会被清掉(新闻站点同样处理),避免标题里出现标签碎片。清洗规则(clean_title())只认常见标签名:br/p/div/span/strong/em/sub/sup带不带属性都删(标签名后的属性窗口不限长,带长style的标签也整段删除,不留半截开标签);单字母标签b/i/u/a只删成对写法(<b>加粗</b>保留中间文本)与带属性/自闭合/孤立结束标签,孤立的<b>这类写法按普通文本保留,以免误伤A <B> C这种比较表达式;其余标签(<h1>、<li>等)原样保留。注意这是纯文本清洗:标题正文本身在讨论标签写法时(如「如何删除<br>标签」)同样会被删;属性窗口不限长后,「<+ 标签名 + 较远>」形状的普通文本也会被整段删除(如「当 a <b 时,成本 > 收入」→「当 a 收入」),同属纯文本清洗的已知取舍;content_required: false(默认)时,详情页抓不到正文、或正文短于 100 字(登录墙占位)不会记为失败,只保存列表字段,下次运行也不会重复重试;需要正文的站点请显式设为true;- 截止时间早于抓取窗口起点(
--days/--since)的条目记为old,避免每次重跑都处理历年公告;--force可强制重抓; - 已入库的
ok/old行会在后续运行中按列表字段刷新title/list_title/title_source/deadline/deadline_raw/project_status/publish_time/list_publish_time(延期、标题修订、截止状态变化都无需重抓详情);刷新时publish_time_utc按该行自己记录的timezone换算——本次没拿到新列表日期、沿用旧墙钟时用行内时区,避免站点配置改过时区后把旧墙钟按新时区重算;行内timezone为空(v6 之前入库的历史行)时,已有publish_time_utc直接沿用,没有才按站点当前时区换算并记一条 WARNING,两种情况都不把猜测写回timezone(「口径未知」保持未知,日后可用--force重算);接受本次列表日期时用站点当前时区换算,并把该时区同步写回行内timezone,保证墙钟与 UTC 口径始终自洽;站点配置的timezone缺失或非法时,load_config已按顶层timezone(默认Asia/Shanghai)归一,列表日期的墙钟格式化与 UTC 换算使用同一时区;只有直接调用_refresh_project_listing传空timezone_name时才改用行内时区换算并记一条 WARNING,不会把行内已知时区清成 NULL,两者都缺时publish_time_utc留空并记 WARNING;行内timezone若存了非法名(如历史版本写入的Asia/Shangha)或首尾带空白,刷新时先按归一后的时区换算 UTC,再把合法名写回该行,避免继续让get_timezone()回落运行环境时区;纯空白视为「口径未知」,刷新时归一成 NULL,不会留在库里污染/v1/sources的时区分组(归一目标始终是站点当前配置:行内记录的原意与配置不同,如历史行写Asia/Tokyo、站点现配置Asia/Shanghai,则按配置换算并写回,原意无法从数据本身恢复,只能--force重抓);原old行若截止时间原文非空且变得不可解析(如“常年受理”)会恢复为ok,content_required: true时继续抓正文(列表截止时间单元格为空时保留旧deadline与old状态,不会恢复);content_required由false改为true后,正文缺失的ok行也会自动补抓;正文重试(含old恢复ok)只更新status/error,保留旧的publish_time/publish_time_utc时不把站点当前timezone写进行内(否则下一轮刷新会按错误时区重算旧墙钟),行内时区缺失时保持 NULL; - 同一 URL 从新闻模式切换为项目模式时,未配置
date_xpath的站点会清空历史publish_time/publish_time_source/publish_time_raw/list_publish_time;配置了date_xpath的站点则改写成列表日期并把publish_time_source归一为list(值相同但来源仍是xpath等历史详情来源的行也会被纠正),而本次列表日期解析失败时沿用旧值(避免列表页临时抖动把已有日期抹掉);此时若旧值来自新闻模式的详情日期,publish_time_source保持xpath等原值并记一条 WARNING,要清空需临时移除date_xpath重抓;若该行连可沿用的本地墙钟都没有(publish_time为空),则publish_time_source/publish_time_raw/list_publish_time一并清空,不会留下只有来源没有日期的半截状态;content/raw_content/author/images始终保留(可能残留旧新闻正文,查询侧请以title_source=list_title或站点配置识别项目行,不要只按deadline;deadline_from/deadline_to只对有可解析截止时间的项目行生效;项目切回新闻模式并重新抓取后旧deadline/deadline_raw/project_status仍会保留,这类新闻行也可能命中截止时间过滤、或被按project_status误判为项目行,查询侧请按站点/字段区分行类型) - 无年份的截止时间(如“11月30日”)按列表发布日期(缺失时按当前时间)取最近的合法年份:列表状态为已截止时以列表发布日期为下界、抓取时刻为上界,在该区间内取最近的合法年份(例:2025-12-20 发布、原文“1月15日”、2026-02-01 抓取 → 2026-01-15;列表发布日期缺失时只约束上界;区间内无候选时
deadline留空、仅保留原文),否则取不早于该日期的最近年份,不会被减一年;配置了无年份deadline_format(如%m月%d日)时同样按基准年补齐;注意重抓历年已截止公告时,无年份截止时间可能随抓取年份后移(“取最近合法年份”的已知取舍,已有deadline的行可用--force之外的常规运行保留原值)。
{
"name": "svc20_stcsm",
"list_url": "https://svc20.stcsm.sh.gov.cn/project",
"listing_type": "project_application",
"item_xpath": "//tr[contains(@class,'ant-table-row')]",
"title_xpath": ".//a[contains(@class,'detailLink')]",
"url_xpath": ".//a[contains(@class,'detailLink')]/@href",
"deadline_xpath": "./td[2]",
"deadline_format": "%Y-%m-%d %H:%M:%S",
"project_status_xpath": "./td[3]",
"render": true,
"delay": 0.8
}先只测试一个站点,确认标题、链接、日期能正确解析:
docker compose run --rm crawler test --config sources.local.json --name 你的站点标识如果输出为空、标题重复或日期不对,需要调整该站点的 XPath。
docker compose run --rm crawler run --config sources.local.json --days 3常用参数:
| 参数 | 作用 |
|---|---|
--days 3 |
抓取最近 3 天 |
--since 2026-09-01 |
从指定日期开始抓取 |
--workers 16 |
同时处理 16 个站点 |
--limit-per-source 20 |
每个站点最多处理 20 条(只计实际处理的条目,已入库被跳过的不占名额) |
--force |
忽略数据库已有记录,强制重新抓取 |
结果默认保存在项目目录的 data/news.db 中。
查看最近抓取的文章:
SELECT source, title, publish_time, url
FROM articles
WHERE status = 'ok'
ORDER BY publish_time DESC;只查看最近 3 天:
SELECT source, title, publish_time, url
FROM articles
WHERE status = 'ok'
AND datetime(publish_time) >= datetime('now', '-3 days', 'localtime')
ORDER BY publish_time DESC;也可以用图形工具 DB Browser for SQLite 打开 data/news.db。
每篇文章抓到页面时会存一份快照,用于事后核对站点是否改版、公告是否被撤下。覆盖 ok、unknown_date 以及项目申报的 no_content 分支(正文抽不出来但页面确实抓到了);项目申报的 old 在截止时间早于窗口时抓取前就返回,不抓页面也不归档。
- 存哪里:索引在库里(
article_archives表),内容写成 gzip 文件放在库文件同级的data/archive/<article_id 前两位>/<article_id>/<时间>_<kind>.gz,旁边附一份.meta.json便于脱离数据库核对来源; - kind 有三种:
raw_html(详情页原始 HTML)、api_response(接口型源返回的条目 JSON)、body_html(历史行回填的清洗正文); - 不会重复占盘:同一条文章的同一种内容按 sha256 去重,反复重抓只留一份;
- 保留一年:过期快照由每轮抓取末尾的清理搬进
data/archive_trash/<日期>/,不硬删除; - 归档失败不影响抓取:写盘或写索引出错只记日志,已入库的文章照常可用。
历史文章(本功能上线前入库的)可以用 backfill_archives.py 补快照,默认只拿库内已有正文生成,不联网:
# 先看候选数
docker compose run --rm --entrypoint python crawler -X utf8 backfill_archives.py --db /app/data/news.db --dry-run
# 小批补快照(默认用库内 body_html / raw_content,不联网)
docker compose run --rm --entrypoint python crawler -X utf8 backfill_archives.py --db /app/data/news.db --limit 500
# 需要真正的原始页面时才重抓(受 --delay 限速)
docker compose run --rm --entrypoint python crawler -X utf8 backfill_archives.py --db /app/data/news.db --fetch-html --limit 20| 状态 | 含义 |
|---|---|
ok |
成功抓取且发布时间在时间范围内 |
old |
已确认超出时间范围,不会重复抓取 |
skip |
数据库已有记录,本次跳过 |
no_content |
正文提取失败 |
unknown_date |
无法解析发布日期 |
error |
抓取过程出错 |
list_empty |
列表页没有解析到条目 |
- 读取配置文件中的站点列表;
- 抓取新闻列表页 HTML;
- 按 XPath 解析出标题、链接、发布日期;
- 过滤出最近 N 天的文章;
- 逐篇抓取详情页;
- 用 GNE 提取标题和正文;必要时使用 Chrome 渲染;
- 结果写入 SQLite,按
(source, url)去重。
请先安装 Docker Desktop(Windows/macOS)或 Docker Engine + Compose v2(Linux),并确保重新打开终端后 docker --version 能正常输出版本。
本项目使用 Compose v2(docker compose)。请升级 Docker Desktop 或安装 Compose v2 插件;旧的 docker-compose(v1)不再推荐。
说明目标页面正文由 JavaScript 动态加载。默认镜像已自带 Playwright Chromium,工具会自动回退渲染;如果仍失败,请检查容器内浏览器是否可正常启动(docker compose run --rm crawler smoke)。
不会。只要把站点配置放在 sources.local.json,该文件已被 .gitignore 忽略。
不会。单个文章异常会被记录为 error,其他文章和站点会继续抓取。
Docker 方式:
git pull
docker compose build- 抓取公开网站前,请阅读目标网站的
robots.txt、服务条款和访问频率要求; - 请合理设置
delay,避免对目标网站造成压力。
本项目沿袭上游 GeneralNewsExtractor 的授权方式,以 GNU GPL v3(GPL-3.0-only) 发布,完整文本见 LICENSE。
按 GPLv3 的要求,向他人传递本项目或其修改版的副本时,必须遵守 GPLv3 的相应条件:传递修改后的源代码时,整个作品需按 GPLv3 授权;传递目标代码时,需按 GPLv3 第 6 节规定的方式(随附源代码、书面要约或同等网络访问等)提供对应的源代码。仅在本地运行或修改、或仅通过网络提供服务而不向他人传递副本,不触发上述义务。如需在 GPLv3 之外以其它许可证分发本项目或其修改版,请联系相关版权所有者取得另行授权。