Gishi1/fanficfare-service

FanFicFare 即服务

一个小型 HTTP API，使用真正的
FanFicFare 引擎
（即驱动 Calibre 插件的同一套代码）将同人小说故事 URL 转换为 EPUB
（以及规范化的 WorkBundle JSON）。这就是
Calaloud 在
POST /ff/add 和 POST /ff/work 处所期望的、缺失的“worker”。

Calaloud 是一个瘦客户端，有意不捆绑 FanFicFare——
本服务就是它所指向的获取后端（默认 http://host:8787）。

契约

| 端点 | 方法 | 请求体 | 响应 |
|----------|--------|------|----------|
| /health | GET | — | {"ok": true} |
| /ff/add | POST | {"url": ""} | EPUB 字节（application/epub+zip） |
| /ff/work | POST | {"url": ""} | WorkBundle JSON（{work, chapters[]}） |

可选的 Bearer 认证：设置 FFF_API_KEY；之后每个请求都必须发送
Authorization: Bearer 。

CORS 完全开放（），因此 Android WebView / 浏览器可以调用它。

请求体（POST /ff/add、/ff/work）

{
"url": "https://archiveofourown.org/works/12345",
"siteCredentials": {
"archiveofourown": { "username": "user", "password": "pass", "adult": true }
},
"adultContentDefault": false
}

- siteCredentials：可选的按站点登录。键是 FFF 站点 section
（例如 archiveofourown、fanfictionnet、fanfiction_net、spacebattles）。
本服务会自动将 URL 映射到其主要站点 section。
- adultContentDefault：如果为 true，则为所有站点请求成人内容，除非
被 siteCredentials 中按站点的 adult 覆盖。

Calaloud 的设置界面提供了管理这些内容的 UI；它们会随
每个抓取请求一起发送。

WorkBundle 结构

对应 Calaloud 的 types.ts：

{
"work": {
"id": "fanficfare:",
"url": "",
"title": "...",
"author": "...",
"series": "...",
"tags": ["..."],
"summary": "...",
"wordCount": 0,
"chapterCount": 3,
"complete": true,
"updatedAt": "ISO8601",
"source": "fanficfare"
},
"chapters": [
{ "workId": "...", "index": 0, "title": "Chapter 1", "html": "...", "text": "..." }
]
}

wordCount/complete/updatedAt 来自 FanFicFare 元数据；章节
从生成的 EPUB 的 OPF spine 中解析（与 Calaloud 在
src/lib/epubImport.ts 中使用的逻辑相同）。

本地运行

uv sync
FFF_PORT=8787 uv run uvicorn app:app --host 0.0.0.0 --port 8787

在 Docker 中运行

docker build -t fanficfare-service .
docker run --rm -p 8787:8787 -e FFF_API_KEY=changeme fanficfare-service

环境变量

| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| FFF_HOST | 0.0.0.0 | 绑定地址 |
| FFF_PORT | 8787 | 端口 |
| FFF_API_KEY |  | 所有 /ff/ 端点的可选 bearer token |
| FFF_CONFIG_DIR | /config | personal.ini / defaults.ini 的目录（bind-mount） |
| FFF_USE_FLARESOLVERR | false | 启用 FlareSolverr 代理（需要 FFF_FLARESOLVERR_URL） |
| FFF_FLARESOLVERR_URL | http://flaresolverr:8191 | FlareSolverr API URL |
| FFF_USE_CLOUDSCRAPER | false | 使用 cloudscraper 抓取器（基础 Cloudflare 绕过） |
| FFF_PROXY_HTTP |  | 用于 RequestsFetcher 的 HTTP 代理（例如 socks5://tor:9050） |
| FFF_PROXY_HTTPS |  | 用于 RequestsFetcher 的 HTTPS 代理（例如 socks5://tor:9050） |

代理 / 抓取器优先级：FFF_USE_FLARESOLVERR > FFF_USE_CLOUDSCRAPER > FFF_PROXY_HTTP/HTTPS > 无。

使用 Tor / FlareSolverr 部署（推荐）

AO3、FFN 及其他网站会屏蔽数据中心 IP。该服务与用户的 Docker 栈集成：

docker-compose.services.yml (Calaloud reference)
services:
fanficfare:
image: fanficfare-service:latest
environment:
- FFF_API_KEY=changeme
- FFF_PROXY_HTTP=socks5://tor:9050
- FFF_PROXY_HTTPS=socks5://tor:9050
depends_on:
- tor

tor:
image: peterdavehello/tor-socks:latest
ports: ["9050:9050", "9051:9051"]

或者使用 FlareSolverr 代替 Tor：

fanficfare:
environment:
- FFF_USE_FLARESOLVERR=true
- FFF_FLARESOLVERR_URL=http://flaresolverr:8191
depends_on:
- flaresolverr

flaresolverr:
image: ghcr.io/flaresolverr/flaresolverr:latest
ports: ["8191:8191"]

站点凭据（两种选项）

1. 通过 API 按请求传递（Calaloud UI）：在每次
/ff/add 或 /ff/work 调用中发送 siteCredentials。无服务器端持久化。
2. 挂载 personal.ini：将包含 personal.ini 的目录绑定挂载
到 /config，并设置 FFF_CONFIG_DIR=/config。FFF 会自动从那里读取凭据
（与 Calibre 插件相同）。

测试

health
curl localhost:8787/health

add -> save epub
curl -X POST localhost:8787/ff/add -H 'Content-Type: application/json' \
-d '{"url":"https://archiveofourown.org/works/12345"}' -o story.epub \
-H 'Authorization: Bearer changeme'

work -> normalized bundle
curl -X POST localhost:8787/ff/work -H 'Content-Type: application/json' \
-d '{"url":"https://archiveofourown.org/works/12345"}' \
-H 'Authorization: Bearer changeme'

with credentials + adult
curl -X POST localhost:8787/ff/work -H 'Content-Type: application/json' \
-d '{"url":"https://archiveofourown.org/works/12345","siteCredentials":{"archiveofourown":{"username":"u","password":"p","adult":true}}}' \
-H 'Authorization: Bearer changeme'