Papermerge 介绍与选型指南

目标：认知 Papermerge 的定位、架构与功能全貌，并用可量化维度与站内 Paperless-ngx、Docspell、Mayan EDMS、Papra 等同类方案做选型对比。

本篇为认知篇，全部内容来自联网溯源（来源与查询日期随文标注），不含本地实测。

一、环境信息

本篇讨论的版本基线与信息源如下（查询日期均为 2026-11-01）：

💡 版本节奏提示：3.5.3 镜像推送于 2025-08-18，截至 2026-11-01 约 14 个月未发新稳定版；3.6 系列仍处 alpha（最新 3.6.0a16，推送于 2026-01-15），且 3.6 计划放弃 SQLite 支持（来源：Docker Hub tags 与官方文档溯源，2026-11-01）。另注意 2.x 与 3.x 架构差异大（2.x 最后稳定 2.1.9，发布于 2023-04-01），网上老教程多属 2.x，选型与部署时务必区分。

二、软件概述

Papermerge 是一款面向扫描件文档（数字档案）的自托管文档管理系统（DMS）：用 OCR 从扫描影像中抽取文本、建立索引并支持全文检索，界面刻意做成"桌面文件浏览器"的观感——双栏文档浏览、拖拽、彩色标签、层级文件夹，支持 PDF、TIFF、JPEG、PNG，定位是文档的长期存储（来源：papermerge-core README，查询日期 2026-11-01）。

项目维护背景值得留意：OSS 版现由社区维护团队接管，原作者 Eugen Ciur 已转向 Papermerge Cloud（SaaS）。官方 README 明确说明两者不共享代码，功能与发版节奏可能不同；docs.papermerge.com 是 Cloud 版文档，自托管版文档在 docs.papermerge.io（来源：README Status 段与注记，查询日期 2026-11-01）。

核心概念（来源：官方文档 settings 与 README Feature Highlights，查询日期 2026-11-01）：

三、核心架构

3.x 采用"单个 webapp 镜像 + 可插拔 worker 镜像"的渐进式架构，官方文档明确其设计哲学是避免大一统单体、走 Unix 路线：小而专的部件 + 清晰接口 + 按需组合（来源：docs.papermerge.io developer-manual/architecture，页脚 June 1, 2026）：

                  ┌────────────────────────────────┐
  浏览器 ────────▶ │ webapp（papermerge:3.5.3）      │ 容器内 nginx:80 + Django
                  │ = REST API + 前端 UI            │ 自带基础 auth server（签发 JWT）
                  │ + 内置基础认证服务               │ 可替换为 Keycloak/Authelia
                  └───┬──────────────┬─────────┬───┘
            元数据/文档 │        任务队列  │         │ 索引同步
                      ▼               ▼(Redis)   ▼
              ┌──────────────┐   ┌──────────┐  ┌─────────────────┐
              │ PostgreSQL / │   │ Celery:  │  │ Solr 或 Xapian  │
              │ SQLite / MySQL│   │ ocr/i3/  │  │ 全文检索后端     │
              └──────────────┘   │ s3/path_ │  └─────────────────┘
                                 │ tmpl 队列 │         ▲
                                 └────┬─────┘         │ i3worker 同步
                                      ▼               │
                    ┌─────────────────────────────────┴──────┐
                    │ ocrworker / i3worker / s3worker /      │
                    │ path-tmpl-worker（独立镜像，按需部署）    │
                    └────────────────────────────────────────┘

要点解读（来源：developer-manual/architecture 与 admin-manual/version-matrix，查询日期 2026-11-01）：

1. webapp 单镜像：内部是 nginx(:80) + Django REST API + 前端；启动时自动执行数据库迁移，并按环境变量自动创建超级用户。全部分配置走环境变量 PAPERMERGE__<SECTION>__<KEY>，其中仅 PAPERMERGE__SECURITY__SECRET_KEY 与 PAPERMERGE__AUTH__PASSWORD 为必填。
2. 核心 REST API 本身不做认证：它只信任上游 HTTP 头（Remote-User 或 Authorization: Bearer <JWT>）传入的"当前用户"；认证逻辑放在上游的 auth server（官方自带一个基础版，源码在 papermerge/auth-server，镜像 auth-server:1.1.5 供内部使用）。基础版不支持 2FA 与用户注册流程，设计上即可用 Keycloak、Authelia 等替换。
3. worker 经 Redis（Celery）异步解耦：webapp 是任务生产者，worker 是消费者，队列名为 ocr、i3、s3、path_tmpl。OCR worker 做光学识别；i3 worker 把数据库数据同步进检索索引（每次 OCR 完成后由 OCR worker 通知 i3 更新索引）；s3 worker 把本地 media 存储与 S3 对象存储双向同步；path-tmpl worker 在路径模板变更时重算海量文档的存储路径。
4. 渐进式部署：官方 compose 文档按步骤给出 最小 webapp+PostgreSQL → 持久化 media → +Redis/worker → +Solr/i3 → +S3 的递进方案，按需取用。
5. 检索后端二选一：默认 Xapian（xapian:////index_db，本地目录），或 Solr（solr://HOST:PORT/INDEX）；上传文件不入库，存于文件系统 media root。
6. 官方 3.5.3 版本矩阵：papermerge/papermerge:3.5.3、papermerge/auth-server:1.1.5、papermerge/ocrworker:0.3.1、papermerge/path-tmpl-worker:0.4.1、papermerge/s3worker:0.5.1、papermerge/i3worker:0.3、postgres:16.1、redis:7.2、solr:9.7（来源：docs admin-manual/version-matrix，查询日期 2026-11-01）。

四、功能特性

按官方 README Feature Highlights 与文档逐项归纳（来源：papermerge-core README 与 docs，查询日期 2026-11-01）：

1. 桌面感 Web UI：双栏文档浏览器、拖拽上传、彩色标签、层级文件夹；UI 多语言。
2. 文档处理：OCR 识别、OCRed 文本叠加层（可下载带 OCR 文本层的 PDF，扫描件变可搜索文件）、全文检索、文档版本管理、页面管理（删除/重排/剪切/移动/抽页）。
3. 组织与元数据：文档类型（类别）+ 按类型的自定义字段；Jinja 路径模板决定文档存储布局。
4. 多用户与共享：多用户、组所有权、文档/文件夹跨用户与组共享。
5. 认证集成：OIDC（OAuth 2.0）、LDAP、remote user 头认证三类外置身份体系接入（来源：docs settings/auth 页）。
6. 对象存储与 CDN：s3worker 同步 S3 兼容存储；FILE_SERVER=s3 时由 AWS CloudFront 分发文档（官方 demo 实例即此形态），支撑无状态横向扩容（来源：architecture 文档 S3 段）。
7. OpenAPI 合规 REST API：实例内 User Menu → REST API 提供 swagger 交互文档；token 无 Web UI，需 create_token.sh 生成（详见本专栏《Papermerge 3.5.3 API 使用详解》）。

五、快速开始（最小可用示例）

以下为官方 Docker 文档给出的最小单容器方式（来源：docs.papermerge.io setup/docker，查询日期 2026-11-01，非本文实测）：

docker run -p 12000:80 \
    -e PAPERMERGE__SECURITY__SECRET_KEY=abc \
    -e PAPERMERGE__AUTH__PASSWORD=pass123 \
    papermerge/papermerge:3.5.3

浏览器访问 http://localhost:12000，凭据为 admin / pass123。官方明确此形态不含搜索与 OCR，仅作快速演示；数据库默认落到容器内 SQLite（sqlite:////db/db.sqlite3）。Apple M1/M2 芯片需先 docker pull --platform linux/amd64 papermerge/papermerge:3.5.3。生产形态（PostgreSQL + Redis + OCR/i3 worker + Solr 全栈）的实操方案见本专栏《Papermerge 3.5.3 Docker Compose 部署指南》。

六、适用场景与限制

适用（来源：README 定位与 docs 架构篇，查询日期 2026-11-01）：

• 个人/小团队的扫描件、票据、合同长期归档，核心诉求是"OCR 出文本层 + 全文检索"；
• 偏好渐进式部署：先用单容器跑通，再按需要加 worker/检索引擎，而不是一上来养一篮子服务；
• 需要把扫描件回灌为可搜索 PDF（OCR 文本叠加层可下载）的场景；
• 已有 Keycloak/Authelia 等统一认证设施，想把 DMS 挂进去的团队。

限制与风险：

1. 社区规模小：papermerge-core 约 551 星（shields.io 徽章，2026-11-01），约为 Paperless-ngx 的 1/85，第三方教程与集成生态少，遇坑多要自己读源码。
2. 发版节奏放缓 + 维护交接：稳定版 3.5.3 推送于 2025-08-18，至 2026-11-01 无新稳定版，3.6 仍 alpha；OSS 版由社区团队接管、原作者转向 SaaS，长期维护活跃度需评估。
3. 内置认证过于基础：无 2FA、无用户注册流程（官方文档明示属设计取舍，需外置 IdP 补齐）。
4. OCR 语言包自担责任：OCR__LANG_CODES 仅是 UI 下拉展示配置，官方文档原文强调"worker 里是否真有这些语言由你负责"（来源：docs settings/ocr，查询日期 2026-11-01）。
5. 无邮件入库通道：README 功能清单与文档均未提供 IMAP/邮件收割能力（对比 Paperless-ngx、Docspell），扫描之外的情报入口需自行脚本化走 REST API。
6. 2.x/3.x 断层：3.x 移除了 2.x 的 papermanage CLI 全家桶，迁移与运维脚本不可复用；3.6 计划弃 SQLite，默认库形态将变。

七、同类选型对比

量化对比（星数/版本/许可证均于 2026-11-01 取自 shields.io 徽章与 GitHub 仓库页；站内同类篇为各组件实测基线）：

数据解读：

• 上手曲线：Papermerge 是唯一能"一个容器先跑起来、组件逐个加"的渐进式设计；Paperless-ngx 单容器即可跑通最小闭环但组件隐含一体；Docspell/Mayan 起步即多服务。
• 社区与迭代：Paperless-ngx 星数约为 Papermerge 的 85 倍且截至查询日仍在周级发版；Papermerge 约 14 个月无新稳定版，求助可得性需计入成本。
• 功能侧重：Papermerge 的差异化在"扫描档案长期存储 + OCR 文本叠加层下载 + 路径模板 + S3/CDN 无状态扩容"；Paperless-ngx 强在消费端自动化（邮件/规则/机器学习分类）；Mayan 强在流程合规与权限。

选型建议（"如果…则…"）：

• 如果你要纯扫描件长期归档、喜欢渐进式加组件、或已有 S3/CDN 设施 → Papermerge 契合（即本专栏，部署见《Papermerge 3.5.3 Docker Compose 部署指南》）；
• 如果你要中文档案为主、社区大、邮件/规则自动化多 → Paperless-ngx 更稳妥（见站内《Paperless-ngx 介绍与选型指南》）；
• 如果你是 JVM 运维背景、档案以德/英语为主、想要实体识别建议工作流 → Docspell（见站内《Docspell 介绍与选型指南》）；
• 如果你是流程合规导向（工作流、权限矩阵、审计）→ Mayan EDMS（见站内《Mayan EDMS 介绍与选型指南》）；
• 如果你要极简单体部署、Node 技术栈 → Papra（见站内《Papra 26.7.1 介绍与选型指南》）。

八、参考链接

• 官方文档站：https://docs.papermerge.io/latest （setup/docker、setup/docker-compose、developer-manual/architecture、admin-manual/version-matrix、settings/overview、settings/ocr、settings/auth、rest-api/overview，页脚 June 1, 2026，查询日期 2026-11-01）
• GitHub 仓库：https://github.com/papermerge/papermerge-core （README "Papermerge OSS"，shields.io 徽章 stars=551，AGPL-3.0，查询日期 2026-11-01）
• 认证服务源码：https://github.com/papermerge/auth-server （内置基础 auth server）
• Docker Hub：https://hub.docker.com/r/papermerge/papermerge/tags （3.5.3 推送于 2025-08-18；3.6.0a16 推送于 2026-01-15）
• Papermerge Cloud（SaaS，独立代码库）：https://papermerge.com
• 站内同类参考：《Paperless-ngx 介绍与选型指南》《Docspell 介绍与选型指南》《Mayan EDMS 介绍与选型指南》《Papra 26.7.1 介绍与选型指南》