Fisherboy 文档

本页端到端地说明 Fisherboy 的工作方式：核心概念、Web UI、下载能力、REST 与 MCP API，以及高级配置。

概念

作业与 envelope

Fisherboy 所做的一切都是一个作业。你提交一个作业（一个 URL 加上若干选项），它被加入 Redis 队列，一个 worker 运行流水线，结果存储为一个 envelope——一个单一对象，保存着提取出的内容（content_md）、结构化记录、爬取树、发现的链接和元数据。你轮询该作业，直到其状态变为 ok。

分级取数（仅在被封锁时升级）

Fisherboy 不到万不得已绝不动用沉重的浏览器。它先尝试最廉价的方法，仅当门控检测到封锁或验证码时才升级：

• 第 0 级——使用 httpx 的静态 HTTP。快速且廉价；适用于大多数静态页面。
• 第 1 级——使用 curl_cffi 的 TLS 指纹，使请求在网络层看起来像真实浏览器的请求。
• 第 2 级——隐身浏览器（Camoufox / Patchright），用于重度 JavaScript 和反爬页面；此级别也驱动隐藏 API 捕获。
• 第 3 级——真实浏览器（nodriver / Playwright），作为最后手段。

成功的级别会按域名缓存（TIER_CACHE_TTL_S），因此对同一站点的下一次请求会从上次成功之处开始。高级别采用惰性导入——基础镜像保持轻量，每个级别仅在其库已安装时才启用。升级上限由 MAX_FETCH_TIER 设置，作业上的 tier_hint 可建议一个起始点。

隐藏 API 捕获

单页应用和动态列表是从它们通过 XHR/fetch 获取的 JSON 渲染而来的。与其与渲染后的 HTML 较劲，Fisherboy 可以监听这些网络响应并保留页面已经消费的 JSON——通常是该数据最可靠、最完整的来源。在作业中通过 capture_api 逐个启用。

隐私模式

隐私模式按作业选择并受角色约束（在 privacy_matrix.yaml 中定义，绝不硬编码）。流水线采用失败即关闭策略：若匿名化失败，则不交付任何原始数据。

• 不透明（opaco）——每个实体变为一个稳定的带类型标记，例如 «PERSON_1» 或 «ID_2»。LLM 基于标记进行推理，永不看到 PII；原始数据无法恢复。
• 可逆（reversible）——相同的掩码处理，但会保留一个加密的“标记到值”映射，以便日后可通过 POST /api/revert（一次性、受角色约束）重新还原。该映射使用 Fernet 密钥（REVERSIBLE_KEY）加密，并在 REVERSIBLE_TTL_S 后过期。
• 直接（directo）——原始输出，仅用于非敏感数据。

针对高风险 PII（身份证号、电子邮件、IP、Luhn 校验有效的卡号、电话），始终会运行一次确定性的正则处理。当 ANONIMAL_URL 指向一个 Anonimal 实例时，会在其之上运行完整的 NER；独立运行时仅回退到内置的正则处理。

若某角色不允许所请求的模式，网关将返回 403——它绝不会悄悄降级。

角色

Fisherboy 有三个访问级别，各有独立密码与能力限制（允许哪些级别、代理、API 捕获、验证码求解器、爬取和狼蛛）。角色在 REST 和 MCP 两者上均强制执行。

角色	不透明	可逆	直接
humano	是	—	—
angel	是	是	—
dios	是	是	是

大致而言：humano 拥有廉价级别且没有昂贵的“武器”；angel 增加浏览器、代理和捕获（但无验证码求解器）；dios 拥有一切。狼蛛和浏览器 Cookie 读取在 sidekick 模式下被否决。

使用 Web UI

在 standalone 模式下，Fisherboy 会在服务 URL（例如 http://localhost:8000）挂载其自带的 Web UI。使用角色密码登录后，你可以：

1. 粘贴一个 URL，选择输出（markdown、llms_txt 或 json）以及你的角色所允许的隐私模式。
2. 可选择启用附加功能——分页、API 捕获、爬取深度、狼蛛、代理、Cookie。
3. 运行该作业；结果会在一个模态编辑器中打开。

内置编辑器

结果在一个带三个标签页的模态编辑器中打开：

• Markdown——带实时预览的工具栏。
• JSON——一个带校验的编辑器。
• 表格——一个可编辑的表格；JSON ↔ 表格只是切换标签页而已。

你可以将结果下载为 .md、.json 或 .csv。你可以下载整个 envelope、仅数据（内容 + 记录 + 树 + 链接），或一个扁平的记录数组。一键即可将结果发送至 Escriba 进行进一步转换、匿名化、分块和导出。

下载

除页面文本外，Fisherboy 还能拉取媒体与平台数据：

• 文件——直接的文件下载。
• 视频——通过 yt-dlp（YouTube、Vimeo 及其他众多平台）。镜像中捆绑的 ffmpeg 会将视频 + 音频混流为高质量 mp4；没有它时，下载会回退为最佳的渐进式单一文件。
• 图库 / 图片——通过 gallery-dl（Instagram、X、Reddit、Pinterest、Tumblr、Flickr、DeviantArt 等）。
• 评论 / 平台数据——多平台；Instagram 帖子评论以及关注者/正在关注数据使用 instaloader，它需要会话 Cookie（IG_SESSIONID），并仅限 dios 角色。

REST API

POST /api/jobs            # 校验 schema、角色 × 隐私模式、回调与代理（SSRF）；入队 → 202
GET  /api/jobs/{job_id}   # 状态与结果（即 "envelope"）
POST /api/proxy/test      # 通过代理转发一个请求；返回出口 IP + 国家 + 延迟
POST /api/revert          # 重新还原假名化的内容（可逆模式）
POST /api/login           # 角色登录（Cookie 会话）
GET  /healthz             # 存活探测
GET  /metrics             # Prometheus 指标

提交一个作业并轮询它：

curl -X POST http://localhost:8000/api/jobs \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/article","rol":"angel","privacy_mode":"opaco"}'
# → { "job_id": "…", "status": "pendiente" }

curl http://localhost:8000/api/jobs/<job_id>
# → 当 status == "ok" 后，得到带匿名化 content_md 的 envelope

作业字段

字段	说明
url	要抓取的页面。
rol	humano / angel / dios。
privacy_mode	opaco / reversible / directo（受角色约束）。
output_format	markdown / llms_txt / json。
tier_hint	建议的起始级别，0–3。
crawl_depth	蜘蛛爬取的深度。
max_pages	页面预算（受 CRAWL_MAX_PAGES 限制）。
paginate	扫遍分页。
capture_api	捕获隐藏的 XHR/fetch JSON。
tarantula	将每个节点的内容 + API 捕获到数据树中。
extract_schema	用于结构化提取的 JSON Schema（配合 output_format=json）。
proxy	按作业覆盖代理。
cookies	用于该请求的会话 Cookie。
callback_url	在完成时接收 envelope 的 Webhook。

注意

作业与状态值使用项目原始的西班牙语标识符（例如 rol、privacy_mode 的取值 opaco/reversible/directo，以及状态 pendiente/ok）。

MCP

同一条流水线以 MCP 工具形式暴露（submit_job、get_job、revert），因此 n8n、Claude Code 或 Escriba 无需手写 HTTP 即可入队：

python -m app.mcp_server      # 需要 fastmcp

MCP 服务器的角色上限由 MCP_ROLE 设置（它不信任调用方所声称的角色）。

高级配置

代理

以任意格式粘贴代理——host:port、host:port:user:pass、user:pass@host:port 或完整 URL——Fisherboy 会将其规范化（支持 socks5）。测试按钮（或 POST /api/proxy/test）会通过它转发一个请求，并返回你的出口 IP + 国家 + 延迟，若无法连接还会给出可操作的提示。用 PROXIES 配置一个代理池，用 PROXY_ROTATION（round_robin / random / sticky）选择轮换方式，并调整 PROXY_COOLDOWN_S 和 PROXY_ATTEMPTS。作业可用自己的 proxy 覆盖该池。

Cookie

无需浏览器扩展即可访问登录后或特定地区的页面。将 Cookie 粘贴为 Netscape cookies.txt、JSON 或 name=value 键值对，或直接从本地浏览器读取它们（Chrome / Firefox / Edge / Brave）。浏览器 Cookie 读取仅限独立模式，并在 sidekick 模式下被否决。

验证码

默认的反验证码策略是通过升级来预防（CAPTCHA_SOLVER=none）：取数门控检测到验证码后升一级。也可选用外部 API 求解器，通过 CAPTCHA_SOLVER=external、CAPTCHA_SOLVER_URL 和 CAPTCHA_SOLVER_KEY 配置（受角色门控）。

分页

在作业上设置 paginate 以扫遍多页列表。Fisherboy 能处理常见方案——ASP.NET 回发、“下一页”链接以及 ?page= 查询模式。总数受 max_pages 和硬性的 CRAWL_MAX_PAGES 上限约束。

浏览器级别

对于第 2 和第 3 级，可用 BROWSER_HEADLESS、BROWSER_SETTLE_S（加载后等待）、BROWSER_SCROLL（触发懒加载）、BROWSER_LOCALE 和 BROWSER_USER_AGENT 来调整无头浏览器。

蜘蛛与狼蛛（深度爬取）

• 蜘蛛——沿内部链接深入成树（带区段范围限定），最多至 crawl_depth，可选与分页结合。
• 狼蛛——深度模式：它遍历每个节点，并将其内容以及其隐藏 API 一并捕获到单个数据树中。狼蛛受限于高级角色，并在 sidekick 模式下被否决。

当 RESPECT_ROBOTS=1 时，多页爬取会遵守 robots.txt。

安全与限制

Fisherboy 采用失败即关闭并经过加固：反 SSRF（解析 DNS；封锁私有/环回/链路本地/云元数据地址段，在每次重定向跳转和每次浏览器请求时重新校验，包括代理覆盖）、按作业的密钥清除（代理凭据、验证码密钥、Cookie 绝不出现在 envelope 或 Webhook 中）、REST 和 MCP 上的角色门控、速率限制（MAX_JOBS_PER_MIN）、硬性的页面与字节上限（CRAWL_MAX_PAGES、JOB_MAX_TOTAL_BYTES），以及非 root 容器。在对外暴露之前，请查阅生产清单——切勿在生产环境中设置 ALLOW_PRIVATE_TARGETS=1 或 FISHERBOY_OPEN_GOD=1。

可选的持久化与可观测性

Postgres + pgvector 持久化是可选的（DATABASE_URL，外加用于向量存储的 EMBEDDINGS_ENABLED）；没有它时，系统仅依靠 Redis 运行并优雅降级。可通过 docker-compose.observability.yml 启用 Prometheus + Loki + Grafana 栈。