content-harvester

内容采集服务。给一个来源页 URL,用真实有头浏览器逐个打开内容详情页,抓出每条内容的元数据(标题 / 详情页 URL / 封面图 / 媒体地址);若调用方下发了对象存储(MinIO/S3)配置,顺带把媒体拉下来、连同封面一起上传,把媒体地址换成对象存储上的稳定 URL(很多站点的媒体地址带 expires 签名、一小时左右就失效)。结果以 resources 列表回传。

支持两类内容:视频(m3u8 → yt-dlp+ffmpeg 转 mp4 上传,source_type=video)和 图集(套图详情页里成百上千张图,逐张下载上传,source_type=image、content_type=article、回传 images[] 数组——主站对 images 数组会自动跑图片 OCR 审核)。按 content_url 路径(/videos/·/video/ ↔ 视频,/photos/·/photo/ ↔ 图集)或载荷里的 media_kind 自动选 scraper。

主要给「启源 AI 平台」主站调用:主站「多内容数据采集」任务里来源大类选「内容网站」时,把作业 POST 给本服务,本服务返回 resources,主站写进资源库。

当前内置 xchina.co 的视频 scraper(core/scraper.py)和图集 scraper(core/scraper_photos.py);接别的来源就再加一个 scraper 模块。

前身是个 Tkinter GUI 视频下载器,已废弃改造成本服务。详细设计见 PRD-minio-upload.md,实现速查见 CLAUDE.md。

---

1. 功能

采集流程(一次作业)

1. 收到 POST /agents/{id}/invoke(载荷来自主站),校验 token、source_kind、content_url host 白名单,从载荷取 MinIO 配置,生成 job_id,立即返回 {"task_id": job_id, "status":"running"},作业转后台异步跑(进程内单作业串行,防风控)。
2. 按 content_url 路径(或载荷 media_kind)选 scraper:视频(/videos/·/video/)走 XChinaScraper,图集(/photos/·/photo/)走 XChinaPhotoScraper。用有头 Chromium(容器里靠 Xvfb 提供虚拟显示)打开来源页:
   • 系列页 → 取页内卡片(视频:.item.video;图集:.item.photo)里的详情链接,按 start_page..end_page 翻页(默认只爬给定页);
   • 详情页 → 直接采这一条。
3. 逐个打开详情页:处理广告中转页;遇 Cloudflare JS 质询页等它自动放行(最多 ~24s);抓 标题、简介/正文(实在没有就用标题——主站资源库对空正文会拒收)、封面图 URL:
   • 视频:简介=meta/og/jsonld 描述 + 详情面板文本 + 标签;封面=截屏 tab 图 → og:image/JSON-LD thumbnail/<video poster> → 页面最大图(排除 logo/占位);视频地址=扫页面 HTML 里的 .m3u8/.mp4 + 嗅探网络响应。
   • 图集:从详情页 div.img[role=img] 的 background-image 解析图片 URL 模板(实测 https://img.xchina.io/photos2/{detailId}/{NNNN}_600x0.webp,NNNN 四位补零序号),从「601P」文本 / 分页器估出总张数 total,构造 images = [模板.format(n=1..min(total, max_images))](对末张做 HEAD 校验,不通过则回退逐页加载 /photo/id-{detailId}/{N}.html 抓 bg-image);封面=images[0];正文 = 标题 + 模特/系列/日期/标签/共N张图。
4. 若调用方给了完整 MinIO 配置:
   • 视频:用 yt-dlp(并发分片)+ ffmpeg(无损 remux)把 m3u8 拉成 xchina/<id>.mp4 上传,封面上传 xchina/<id>.<ext>,video_url/cover_image 换成对象存储 URL,原始地址留 extra_data.original_m3u8/original_cover,记 minio_object_video/minio_object_cover/video_bytes。
   • 图集:逐张下载(边下边传边删,不囤盘)上传 xchina/<detailId>/{NNNN}.<ext>,images[] 整体换成对象存储 URL(单张失败则该项保留原图床地址),封面=已上传的第一张,记 extra_data 的 minio_objects_images/images_uploaded/images_failed/original_images_count/original_cover(image_total/image_count/image_capped 在 to_ingest_dict 时写)。 临时文件用完即删,不长期落盘。
5. 作业结束:status=succeeded(只要至少抓到一条)/ failed(0 条且有抓取错误)。主站轮询 GET /tasks/{job_id} 拿结果。

降级(任一环节出问题不让整作业白跑)

情况	行为
未给完整 MinIO 配置	不上传,video_url 保留原始 m3u8,extra_data.upload_skipped_reason="minio config absent",作业仍 succeeded
某详情页被 Cloudflare 卡住等不出来	该条进 item_errors,不计入 resources,不影响其它条
m3u8 下载/合并失败、视频超 MAX_VIDEO_MB、MinIO 上传失败	该条降级:video_url 保留原始地址,extra_data.upload_skipped_reason 记原因,仍作为一条 resource 回传
封面下载/上传失败	cover_image 保留原图床地址,不致命
整作业 0 条 resources 且有 item_errors	status=failed,error 汇总前几条原因

---

2. 技术栈与结构

• FastAPI + uvicorn —— HTTP 服务。
• Playwright(Chromium,有头模式)+ Xvfb —— 抓页面。有头是必须的:Cloudflare 的 JS 质询对真实有头浏览器才会自动放行,无头 chromium-headless-shell 会被一眼识破。容器里用 docker-entrypoint.sh 起一个 Xvfb :99 提供虚拟显示。x86_64 上还可改用真实 Google Chrome 通道(BROWSER_CHANNEL=chrome)更稳。
• yt-dlp + ffmpeg —— m3u8 分片下载 + 合并成 mp4。ffmpeg 是 apt install 进镜像的,不碰宿主机。
• minio SDK —— 上传对象存储(fput_object),兼容 S3 协议。
• 作业模型 —— 进程内内存级 job 注册表 + asyncio.create_task 后台跑;asyncio.Lock 串行化(同一时刻只跑一个浏览器作业,防站点风控);作业状态只在内存,服务重启即丢——主站靠轮询拿结果,够用。重计算(yt-dlp/minio 都是同步库)用 asyncio.to_thread 跑,不阻塞事件循环。
• 不持有任何密钥 —— MinIO 凭据、token 都由部署方/调用方提供(env 或 invoke 载荷),仓库里不含。日志里不打印 secret_key 等敏感值。

core/
  browser.py        # Playwright 持久化 BrowserContext(资料目录可挂卷),反自动化参数 / zh-CN / Asia-Shanghai
  scraper.py        # xchina.co 视频 scraper:系列页翻页、详情页解析(标题/简介/封面/m3u8)、广告中转页、Cloudflare 质询等待;导航/反爬 helper 也给图集 scraper 复用
  scraper_photos.py # xchina.co 图集 scraper(继承 XChinaScraper 复用导航 helper):系列页 .item.photo 翻页、详情页解析图片 URL 模板 + 总张数 + 模特/系列/日期/标签,construct-or-paginate 收集 images[]
  media.py          # MinioConfig(从载荷/env 解析)、download_video(yt-dlp+ffmpeg)、download_cover、download_image、head_ok、upload_to_minio、extract_video_id(=extract_detail_id)
  models.py         # ScrapedItem(media_kind=video|photo;to_ingest_dict 按 media_kind 出 source_type=video|image;字段对齐主站 ResourceIngestItem)、ScrapeResult
server/
  app.py        # FastAPI:/agents/{id}/invoke(按 content_url/agent_id/media_kind 选视频或图集)、/tasks/{id}、/tasks/{id}/cancel、/healthz;Bearer 鉴权;SSRF host 白名单
  jobs.py       # 内存 job 表 + 后台执行 + 单并发串行;_process_uploads 按 media_kind 分流(视频:yt-dlp/ffmpeg;图集:逐张下载上传)+ 降级 + 临时目录清理
Dockerfile          # base mcr.microsoft.com/playwright/python;apt 装 xvfb + ffmpeg;ENTRYPOINT 起 Xvfb → uvicorn
docker-entrypoint.sh
requirements.txt    # playwright / fastapi / uvicorn / requests / yt-dlp / minio
PRD-minio-upload.md # 设计文档
CLAUDE.md           # 给 AI / 维护者的实现速查

加新来源:新建 core/scraper_<site>.py(实现 run(url, start, end) -> ScrapeResult),在 server/jobs.py::_make_scraper 里按 media_kind / content_url host 选用对应 scraper。core/media.py、server/app.py 基本不用动(图集类记得 ScrapedItem.media_kind="photo"、填 images)。

---

3. HTTP 接口

实现的是主站 lobster 执行器的调用契约(主站 agent-system-backend/app/services/lobster_client.py::call_lobster_agent:POST /agents/{id}/invoke 取 task_id → 轮询 /tasks/{id} 直到 status∈{succeeded,failed} → 用 output/error)。

POST /agents/{agent_id}/invoke

请求体(= 主站发来的合并载荷):

字段	必填	说明
content_url	是	来源页 / 详情页 URL;host 必须在 ALLOWED_HOSTS 白名单(默认 xchina.co)
source_kind	否	非 website 直接 400
media_kind	否	video / photo;不给则按 content_url 路径(/videos/·/video/ ↔ video,/photos/·/photo/ ↔ photo)或 agent_id(含 photo → photo)自动判断
max_images	否	图集每个套图最多抓多少张,默认 DEFAULT_MAX_IMAGES(100),上限 MAX_IMAGES_CAP(2000);仅 photo 生效
platform_name	否	作为 source_name,默认 xchina
start_page / end_page	否	默认 1/start_page(即只爬给定页/这一条);区间超 MAX_PAGES 会被截断
minio_endpoint / minio_access_key / minio_secret_key / minio_bucket	否	四者齐全才启用上传;缺则降级。也可改由本服务 env 提供(MINIO_*),载荷优先
_crawl_config 等其它字段	—	本服务忽略,主站自己用

响应:{"task_id": "<job_id>", "status": "running"},立即返回。

GET /tasks/{task_id}

{
  "status": "running" | "succeeded" | "failed",
  "output": {                       // succeeded 时
    "resources": [
      // —— 视频条目 ——
      {
        "source_type": "video", "content_type": "video",
        "source_name": "xchina",
        "source_url": "https://xchina.co/video/id-XXXX.html",   // 主站资源库按它去重
        "title": "...", "summary": "...",
        "content": "...",            // 正文(保证非空,实在没有就是标题)——主站对空正文拒收
        "cover_image": "<对象存储URL 或 原图床URL>",
        "video_url":   "<对象存储URL 或 原始m3u8URL>",
        "extra_data": {
          "referer": "...", "page_no": 1, "collector": "xchina", "video_id": "XXXX",
          "original_m3u8": "...", "original_cover": "...",
          "minio_object_video": "xchina/XXXX.mp4", "minio_object_cover": "xchina/XXXX.jpg", "video_bytes": 78167166
          // 没上传则有:"upload_skipped_reason": "minio config absent | ... | video too large: ... | minio upload failed: ..."
        }
      },
      // —— 图集条目 ——
      {
        "source_type": "image", "content_type": "article",      // 注意:content_type 是 article(主站枚举只有 article/video)
        "source_name": "xchina",
        "source_url": "https://xchina.co/photo/id-XXXX.html",
        "title": "...", "summary": "模特 · 系列 · N张",
        "content": "标题\n模特: .. · 系列: .. · 日期: .. · 共 N 张图 · 标签: ..",
        "cover_image": "<已上传第一张的对象存储URL,或原图床URL>",
        "images": ["<对象存储URL>", ...],                        // 主站对 images 数组会自动跑图片 OCR 审核(命中 ad/minor/non_frontal 的会被剔除;全空则资源 soft delete)
        "video_url": null,
        "extra_data": {
          "referer": "...", "page_no": 1, "collector": "xchina", "video_id": "XXXX",
          "image_total": 601, "image_count": 100, "image_capped": true,   // image_total=站点上的总张数,image_count=本次回传的张数(受 max_images 限)
          "base_prefix": "https://img.xchina.io/photos2/XXXX", "detail_id": "XXXX",
          "img_template": "https://img.xchina.io/photos2/XXXX/{n:04d}_600x0.webp",
          "minio_objects_images": ["xchina/XXXX/0001.webp", ...], "images_uploaded": 100, "original_cover": "...",
          "original_images_count": 100, "images_failed": 0           // images_failed 仅当有单张失败时出现
          // 没上传则有:"upload_skipped_reason": "minio config absent | ..."
        }
      }
      // ...
    ],
    "pages_scanned": 1,
    "item_errors": [ {"source_url": "...", "reason": "..."} ]
  },
  "error": null | "...",
  "log_tail": ["HH:MM:SS ...", ...]   // 最近 80 行作业日志
}

每条 resources[i] 的顶层字段就是主站 ResourceIngestItem 的字段集,主站可直接 model_validate 入库。

其它

• POST /tasks/{task_id}/cancel —— 标记取消(仅 running 时有效)。
• GET /healthz —— {"ok": true, "headless": false, "allowed_hosts": [...]}。
• 鉴权:设了 HARVESTER_TOKEN 则所有 /agents/* /tasks/* 要求 Authorization: Bearer <token>(即主站对应 Skill 的 lobster_api_key);没设则不鉴权(仅限内网/本地)。
• 并发:进程内单作业串行;已有作业在跑时新作业排队。

---

4. 配置(环境变量)

变量	默认	说明
HARVESTER_TOKEN	空	Bearer token;空=不鉴权
HEADLESS	0	0=有头(容器内靠 Xvfb,过 Cloudflare 必须);1=无头(本地调试,过不了详情页)
BROWSER_CHANNEL	空	x86_64 可设 chrome(需 Dockerfile 里 playwright install chromium chrome);arm64 无 Chrome 包
BROWSER_PROFILE_DIR	/data/browser_profile	持久浏览器资料目录(挂卷;可预置过了 Cloudflare 的 cookie 作为反爬退路)
ALLOWED_HOSTS	xchina.co	content_url host 白名单(SSRF 防护),逗号分隔
MAX_PAGES	50	单作业最多翻页数
DEFAULT_MAX_IMAGES	100	图集每个套图默认抓多少张(载荷 max_images 覆盖)
MAX_IMAGES_CAP	2000	单套图抓图张数硬上限(载荷给再大也截到这)
CONCURRENT_FRAGMENTS	8	yt-dlp 并发分片数
MAX_VIDEO_MB	0	单视频大小上限(0=不限),超过则跳过上传、降级保留原媒体地址
TMP_DIR	/tmp	临时下载目录(<TMP_DIR>/content-harvester/<jobid>/,用完即删)
MINIO_ENDPOINT / MINIO_ACCESS_KEY / MINIO_SECRET_KEY / MINIO_BUCKET	空	对象存储配置;invoke 载荷里没传时的兜底

---

5. 部署

Docker(推荐)

git clone -b dev https://git.aidfxn.com/admin/content-harvester.git
cd content-harvester
docker build -t content-harvester .          # base 镜像 ~1GB+,首次几分钟;之后改代码增量很快
docker run -d --name content-harvester \
  --restart unless-stopped \
  --network <主站 docker compose 的网络名> \  # 跟主站 backend 同一个 docker 网络,让主站能用 http://content-harvester:8000 访问
  -p 8019:8000 \                              # host 端口随意,主要给本机直接调试用
  -e HARVESTER_TOKEN=<和主站 Skill 的 lobster_api_key 一致> \
  -e MINIO_ENDPOINT=<...> -e MINIO_BUCKET=<...> -e MINIO_ACCESS_KEY=<...> -e MINIO_SECRET_KEY=<...> \
  -v content-harvester-profile:/data/browser_profile \
  --memory=2g --cpus=2 \
  content-harvester
curl -s localhost:8019/healthz   # {"ok":true,"headless":false,...}

镜像里已含 xvfb(有头浏览器)+ ffmpeg(yt-dlp 合并 m3u8)。资源占用主要是 Chromium 内存(给 2g 够用)+ 下载视频时的临时磁盘(每条用完即删,同一时刻最多一个视频在磁盘上;超大视频用 MAX_VIDEO_MB 限);ffmpeg 合并很轻(无损 remux,几秒)。

MinIO 凭据也可不用 env,改由主站把绑定的 minio_* Skill 变量并入 invoke 载荷下发(见下「与主站交互」)——那样本服务 env 里不放任何密钥。

更新

• dev:有自动部署 —— .gitea/workflows/deploy.yml,push 到 dev 分支(或 gitea 上 workflow_dispatch)→ dev 开发机的 runner 自动 docker build + 重建 content-harvester 容器 + healthz 检查。前置:在该仓库的 Gitea Actions secrets 里配一个 CH_ENV_FILE(等价于 .env.dev 全文,HARVESTER_TOKEN + 4 个 MINIO_* + 可选项)。
• prod / 手动:master/prod 不走那个工作流,仍手动:cd <部署目录> && git pull origin <dev|master> && docker build -t content-harvester . && docker rm -f content-harvester && docker run -d ... content-harvester(完整命令、各环境的服务器/目录/容器/凭据见 DEPLOY.md 与本地运维记录,不入库)。

---

6. 与主站的交互

调用链

用户在主站「任务创建」选采集 Skill(lobster 执行器),来源大类=内容网站,地址填来源页 URL
        │  task.input_params = { source_kind:"website", content_url:"...", start_page?, end_page?, _crawl_config:{dedupe_strategy,default_status,visibility} }
        ▼
主站 TaskService.create() → 不阻塞,asyncio.create_task(_run_lobster_task_bg)
        │  _dispatch_lobster:① 解析该 Skill 绑定的 Skill 变量(含 minio_* 等)→ 并入 payload(Skill 变量同名覆盖 input_params)
        │                    ② POST {lobster_api_url}/agents/{agent_id}/invoke  body=payload  Authorization: Bearer {lobster_api_key}
        │                    ③ 轮询 GET {lobster_api_url}/tasks/{task_id}(crawl 类超时 CRAWL_LOBSTER_TIMEOUT,默认 7200s)
        ▼
content-harvester:抓页面 → 下 m3u8 转 mp4 → 传 MinIO → 回传 output.resources
        ▼
主站 _dispatch_lobster 把结果写回 task.result(={success,output,error,duration_ms}),task.status=SUCCEEDED
        │  _run_lobster_task_bg:成功后调 _maybe_ingest_to_resource_pool(task)
        │    从 task.result.output.resources 逐条 ResourceIngestItem.model_validate
        │    组 ResourceIngestRequest(task_id/skill_id/created_by/product_id + _crawl_config 里的 dedupe_strategy/default_status/visibility)
        │    ResourcePoolService.ingest_resources():内容审核(违规 block)→ 写 ResourcePool → 派 AI 改标题/润色正文任务
        ▼
资源库列表出现这些内容,video_url/cover_image 指向 MinIO,长期有效;走的是和 TG 采集完全相同的入库/审核/润色流程。

主站需要的配套(已在 agent-system-backend 做好)

app/services/task_service.py 5 处改动:① 非批次 lobster 任务改 asyncio.create_task(_run_lobster_task_bg) 后台执行,不内联阻塞创建请求;② _run_lobster_task_bg 成功后调 _maybe_ingest_to_resource_pool(原来只有 script 执行器走入库);③ _maybe_ingest_to_resource_pool 兼容从 task.result["output"]["resources"] 取(lobster 嵌套结构);④ _dispatch_lobster 把 _resolve_skill_variables 解出的 Skill 变量并入发给远端的 payload;⑤ crawl 类 lobster 任务轮询超时改 CRAWL_LOBSTER_TIMEOUT(env,默认 7200s)。前端 agent-system-frontend 不用改(CrawlerTaskBlock 已有 source_kind=website)。

主站侧配置(运维一次性)

「Skill 管理」新建/编辑一个采集 Skill:

• executor_type=lobster、skill_category=crawl
• lobster_api_url=http://content-harvester:8000(同 docker compose 网络)、lobster_api_key=<HARVESTER_TOKEN>、lobster_agent_id=任意(如 xchina)
• input_schema 含 source_kind 字段(前端才渲染采集表单)+ 声明 content_url(必填),可选 start_page/end_page
• (可选,若不想在 content-harvester 容器里配 MinIO env)变量关联里勾上 minio_endpoint/minio_access_key/minio_secret_key/minio_bucket 这几个 Skill 变量,值由运维在主站填——_dispatch_lobster 会把它们并入 payload 下发

注意:这是个独立的 Skill,跟原有「多类型数据采集」(script 执行器,跑 clawler 脚本,主打 Telegram)并存——执行器类型互斥(RB-13),不能合成一个。用户建任务时选哪个 Skill 就走哪条采集路径。

已知行为 / 注意点

• 主站资源库对空 content 直接拒收(reason:"正文为空,不予入库",且 _maybe_ingest_to_resource_pool 只记 log 不抛错 → 任务仍 SUCCEEDED 但资源没进库)。所以本服务保证每条 content 非空(抓不到描述就用标题兜底)。
• 入库成功后主站会自动派 AI 改标题任务,资源库里的 title 会被润色掉(如「0144 小雪」→「小雪:怀旧风格丝袜摄影大赏」),属预期。文本内容审核、AI 正文润色也一并跑(和 TG 采集同一套)。
• 图片 OCR 审核:图集回传的 images[] 数组主站会自动逐张排 OCR 审核任务,命中 BLOCK_TAGS(ad/minor/non_frontal)的图会被从 images 里剔除;若一条资源最后 content/images/video 全空 → 主站把它 soft delete。所以图集抓得多 = OCR 任务多、且不少图会被判 minor/non_frontal 被剔——这是预期,max_images 就是用来控这个量级的。视频资源只有单个 cover_image(不在 images 里),不走这套 OCR。
• m3u8 媒体地址带 expires 签名约 1h 失效——所以才在采集时就转 mp4 上传对象存储;不上传的话资源库里那个 URL 一会儿就 403。图集图 URL(img.xchina.io/photos2/...)不带签名、较稳定,但仍统一转存对象存储(脱离对源站可用性的依赖)。
• 性能:视频每条 15s 抓页 + 几十秒几分钟下载 + 上传;图集每个套图 ~5-10s 抓页 + 逐张下载上传(600px webp 每张几十 KB,100 张约 1-2 分钟)。CRAWL_LOBSTER_TIMEOUT 默认 7200s 够用。多页/大量内容会很慢,属预期(单作业串行)。

---

7. 反爬 / 限制

• 详情页常被 Cloudflare 挡:只有真实有头浏览器(HEADLESS=0 + Xvfb,或真实 Chrome)才能自动过 JS 质询;_assert_not_blocked 会等质询自动放行(最多 ~24s),仍卡住则该条进 item_errors。
• 站点策略变化(改成交互式验证码、改 DOM 结构)可能导致采集失效。退路:在桌面环境用同一套 Chromium 持久目录登录 / 过一次验证,把 browser_profile 目录拷进容器挂载的卷。站点结构变了就改对应的 core/scraper*.py(选择器/正则/JS 片段)。
• 单并发是有意的;并发跑多个浏览器作业容易触发站点风控。