funflix

影视资源分享文本的结构化采集、解析与网盘链接校验。

完整设计见 docs/DESIGN.md。

流水线

source ──采集──> raw_document ──LLM 抽取──> extraction
（频道/水位）      （原始文本）                  │
                                              ▼
                                    media + resource ──校验──> link_check
                                   （作品）  （网盘链接）

每一层各自幂等、可单独重跑。当前进度：

快速开始

pip install -e ".[dev]"

# 建库
alembic upgrade head

# 登记一个 Telegram 频道并采集一次
funflix source add https://t.me/s/<频道名>
funflix source collect
funflix source list

# 起服务
funflix serve --reload
# 接口文档 http://127.0.0.1:8000/docs

配置

所有配置项走 FUNFLIX_ 前缀的环境变量或 .env：

接口

采集源

原始文本

查询

/media 的关键词匹配走 services/search.py 的后端抽象：PostgreSQL 上用 pg_trgm 容错匹配并按相似度排序，其余方言回落 LIKE，调用方无感知。

PostgreSQL 上的三条实测结论（tests/test_search_pg.py，5 万行）：

📌 批量导入后记得 VACUUM。GIN 索引默认开着 fastupdate，新行先进一个待合并 列表；合并前规划器认为索引很贵（实测位图扫描启动代价 2515 vs 合并后 64）， 于是绕开它走全表扫描。autovacuum 会自动处理，赶时间就手动 VACUUM ANALYZE media;。

⚠️ DESIGN §7.3 还规划了 SqliteFtsBackend（FTS5 虚拟表），目前尚未实现。 也就是说 SQLite 部署上关键词搜索仍是 LIKE %x% 全表扫描 —— 几千条无所谓， 上万条就会明显变慢。数据量起来之前先用 PostgreSQL，或者补上 FTS5 后端。

鉴权

写接口（POST/PATCH/DELETE /sources、/sources/{id}/collect）需要 X-API-Key：

export FUNFLIX_ADMIN_API_KEY=$(openssl rand -hex 32)
curl -X POST localhost:8000/api/v1/sources \
     -H "X-API-Key: $FUNFLIX_ADMIN_API_KEY" \
     -d '{"url": "https://t.me/s/某频道"}'

未配置该变量时管理接口一律返回 403（默认关闭比默认放行安全）。CLI 不走 HTTP，不受影响。

⚠️ 查询接口目前仍是开放的，其中 /resources 会成页返回网盘链接与提取码， 整库可在 总数/200 次请求内翻完。要暴露到公网的话，先给它也加上鉴权或限流。

设计要点

• 水位用消息 ID 而不是时间。ID 单调且精确，不受时钟漂移、同秒多条消息、消息编辑改时间戳的影响。
• 水位按「见到的最大 ID」推进，不是「成功落库的最大 ID」。否则一条无正文的纯图片消息会永久卡住采集。
• 首次接入只取最新一页。想补历史就显式回拨 cursor_message_id，避免接入老频道时把整个历史拉下来。
• 入口按 content_hash 去重。同一条分享被多个源重复抓到时在这里挡住，不会走到后面按次计费的 LLM 抽取。
• 时间统一 UTC-aware。UTCDateTime 抹平了 SQLite（读回 naive）与 PostgreSQL（读回 aware）的行为差异，写入 naive 会直接报错。

开发

pytest              # 测试
ruff check .        # lint
ruff format .       # 格式化

# 改了模型后生成迁移
alembic revision --autogenerate -m "描述"

跑 PostgreSQL 那部分测试

默认测试全在 SQLite 上，走的是 LikeSearchBackend；而生产上真正跑的是 PgTrgmSearchBackend，两者的关键词子句一行代码都不共用。所以 SQLite 全绿 并不能说明 PG 上是对的。tests/test_search_pg.py 补这一块，默认跳过：

export FUNFLIX_TEST_PG_URL='postgresql+asyncpg://用户@/库名'
pytest tests/test_search_pg.py

其中 test_keyword_query_uses_the_trgm_index 断言的是查询计划而不是结果。 similarity(a,b) > 阈值 和 a % b 结果完全一样，只有后者走索引 —— 写错了 结果依旧正确、测试依旧全绿，只是慢几百倍。这种退化只有查执行计划才拦得住。