文档管理市场有个怪象：企业级OCR服务按页收费，个人开发者想自建又卡在训练模型。Paperless-ngx最近把全套API免费开放，相当于把原本藏在Docker镜像里的能力拆成了乐高积木。
这个项目本质是「扫描仪+搜索引擎+文件柜」的三合一。收据、发票、手写便签丢进去，自动识别文字、提取关键信息、生成可检索的索引。区别只在于——以前你得用它的Web界面，现在能用curl直接调。
部署比装个Chrome插件还快
官方给的Docker Compose配置只有80行。mkdir建目录、wget拉配置、docker compose up -d启动，三步完事。本地8000端口打开就能看到管理后台，创建超级用户的命令也打包好了。
这背后是SQLite方案的功劳。不需要额外起Postgres，单机跑测试环境足够。生产环境切到Postgres+Redis只是改一行配置的事，但入门门槛被压到了地板。
token认证是标准做法。export两个环境变量，后续所有curl命令都能复用。没有OAuth2的跳转噩梦，也没有API Key的复杂轮换——对自托管场景来说，这种「够用就好」的设计反而省心。
上传接口藏着自动化野心
POST /documents/post_document/这个端点支持multipart/form-data，意味着你能同时传文件和元数据。title、correspondent、tags三个字段，对应的是后续检索的三大维度。
真正有意思的是后台流水线：文件落地后自动触发OCR，文字提取完再跑分类模型，最后把结果写进搜索索引。整个过程异步完成，API立刻返回200，不用轮询等处理。
tags字段支持传ID数组，2,5这种写法说明它内部做了多对多关联。correspondent设计成独立实体而非纯文本，是为了做归一化——"Acme Corp"和"ACME CORPORATION"会被识别成同一家。
搜索语法比Elasticsearch克制
全文检索用query参数，空格分隔的关键词默认走AND逻辑。试了下invoice+march+2026，返回结果包含任意匹配项，相关性排序靠内置的评分算法。
过滤条件的设计很产品经理思维：tags__id__in对应标签多选，created__date__gt/lt做时间范围，correspondent__name模糊匹配。双下划线语法借鉴了Django ORM，熟悉Python Web开发的人秒懂。
这些参数能组合使用。比如先按日期缩小范围，再用correspondent精确定位，最后用query做全文检索——三层漏斗下来，几千份文档里找特定发票只需几十毫秒。
文档获取的四种姿势
DOC_ID替换后，/documents/{id}/返回完整元数据，包括OCR提取的纯文本content字段。想要原始PDF用/download/，缩略图用/thumb/，单独抽文字用jq过滤content。
这种分层设计照顾了不同场景：财务系统对接可能只需要元数据，邮件附件预览要缩略图，合规审计必须保留原始扫描件。一个端点拆四个，比把所有东西塞在一个JSON里更省带宽。
jq的用法在示例里出现频率很高，说明目标用户被预设为命令行熟练工。这也解释了为什么没提供官方SDK——curl+shell脚本足够覆盖90%的自动化需求。
标签体系的自动化钩子
创建标签时有个is_inbox_tag布尔值，这是Paperless-ngx的特色功能。标记为inbox的标签会自动应用给新文档，配合matching_algorithm能做智能分类。
algorithm字段取值1代表「任意匹配」，配合match字段里的关键词。比如correspondent设match为"acme"，所有包含该词的文档会自动关联到Acme Corp——相当于简易版的规则引擎。
document_type同理。Invoice类型匹配"invoice"关键词，系统收到新发票时自动打标签、归档、触发后续流程。这套机制让「零人工介入」的文档处理成为可能。
项目GitHub星标数已经过万，但中文社区讨论度意外偏低。可能是自托管的门槛挡住了非技术用户，而企业用户更倾向买现成的SaaS。现在API完全开放，会不会催生出一批基于它的垂直应用？
热门跟贴