Papermerge 部署教程：从环境自检到跑通第一篇文档 OCR 索引
【免费下载链接】papermergeOpen Source Document Management System for Digital Archives (Scanned Documents)项目地址: https://gitcode.com/gh_mirrors/pa/papermerge
Papermerge 是一款专为扫描文档设计的开源文档管理系统（DMS），入库时自动执行 OCR、建立索引并支持全文检索。这篇 Papermerge 部署教程面向想在自有服务器或 NAS 上跑起它的新手，全程基于 Docker Compose 完成。
它适合谁 / 解决什么问题
判断要不要装，看下面三类场景是否命中你：
- 手头有一批扫描的发票、合同、票据，想按关键字直接搜到原文，而不是翻文件柜
- 希望用层级文件夹加彩色标签组织数字档案，并给团队成员分配不同权限
- 坚持自托管部署，不愿把文档存进第三方云服务
它支持 PDF、TIFF、JPEG、PNG 四种格式，界面是仿桌面文件浏览器风格，左侧列表、右侧预览。
图1：Papermerge 主界面——左侧为文件夹与文档缩略图列表，右侧展示 OCR 识别后的账单细节与元数据
📋 部署前自检清单
开始之前先确认宿主机满足前提，其余依赖全部交给 Docker 处理：
- 操作系统：已安装 Docker 与 Docker Compose 的 Linux
- 内存：2GB 及以上；磁盘：20GB 及以上可用空间
- 网络：能正常拉取容器镜像
在准备安装 Papermerge 的目录执行获取代码的命令：
git clone https://gitcode.com/gh_mirrors/pa/papermerge cd papermerge预期结果：当前目录下出现 papermerge 目录，内含 docker、config、papermerge 等子目录。
🚀 部署实操
编排定义在项目的 docker/ 目录中，先进入该目录：
cd docker四条服务的启动命令都写在 docker/docker-compose.yml 里。
启动全部组件：
docker-compose up -d该命令自动拉取主应用（eugenci/papermerge）、PostgreSQL 数据库、Redis 缓存、worker 工作节点四套镜像并后台启动。首次拉取镜像需要几分钟，请耐心等待。
确认启动状态：
docker-compose ps预期结果：app、db、redis、worker 四项全部显示 Up，部署步骤完成。
🗝️ 首次进入与默认信息
默认访问信息如下，初始账号由 docker/scripts/create_user.py 在容器首次启动时自动创建：
- 访问地址：http://localhost:8000
- 用户名：admin
- 密码：admin
- 权限：超级管理员
登录后立即进入账户设置修改默认密码，这是必须执行的安全动作。
完成标志：浏览器打开后看到登录页，用 admin/admin 成功进入 Home 文档面板，即部署成功。
图2：文档列表与预览窗格——可见标签、文件夹层级以及 OCR 完成状态标记
⚙️ 配置速查表
高频配置集中在 docker/config/ 目录，均为 Python 文件：
| 文件 | 管什么 | 典型改动 |
|---|---|---|
| docker/config/papermerge.config.py | OCR 语言、数据库连接 | OCR_DEFAULT_LANGUAGE 默认语言，OCR_LANGUAGES 增加语种 |
| docker/config/app.production.py | 主应用生产设置 | DEBUG 开关、日志级别与输出文件 |
| docker/config/worker.production.py | worker 进程设置 | 数据库连接、Redis broker 地址 |
| docker/docker-compose.yml | 容器编排 | ports 端口映射、volumes 数据卷 |
| docker/scripts/create_user.py | 初始账号创建 | 修改初始用户名与密码 |
改完配置后重新执行 docker-compose up -d 使变更生效。
🩺 故障排查
Q：服务起不来，页面打不开怎么办？
查看日志定位原因：
docker-compose logs -f该命令实时输出各容器日志。重点看 app 与 db 两栏的报错；数据库首次初始化较慢，可稍等片刻再刷新页面。
Q：默认端口 8000 被占用，如何修改？
编辑 docker-compose.yml，把 app 服务的 ports 映射 "8000:8000" 改为 "8080:8000"，再重启容器，随后改用 http://localhost:8080 访问。
Q：OCR 识别结果乱码或错字？
多半是语言不匹配。检查 papermerge.config.py 中的 OCR_LANGUAGES 是否包含文档语种，以及 OCR_DEFAULT_LANGUAGE 是否设置正确，改完重启容器。
Q：数据如何备份？
核心数据只存在两个命名卷里：postgres_data7 存数据库，media_root 存原始文档。定期备份这两个卷即可完整恢复，不要遗漏媒体卷。
📈 进阶玩法
跑顺之后，可以按需尝试以下方向：
- 自定义字段与多语种 OCR：为不同文档类型定义金额、日期等元数据字段，配合 OCR_LANGUAGES 处理混语种扫描件，把非结构化扫描变成可统计的结构化数据
- 自动化规则（Automate）：在管理面板配置规则，让新入库文档按关键字自动归入对应文件夹并打标签，省去手工整理
- REST API 对接：Papermerge 提供 OpenAPI 规范的 REST API，可用于扫描目录批量入库或与其他系统做数据同步
部署完成后的下一步指引
到这里，主应用、数据库、缓存、工作节点四个组件已全部跑通，文档入库后即可通过全文检索直接定位原文。更深的用法——权限体系、邮件附件导入、备份策略等——请查阅 Papermerge 官方文档站点；遇到部署或使用问题，到该项目的元仓库（meta-repository）提交 issue，那里同时跟踪项目状态与已知问题。
【免费下载链接】papermergeOpen Source Document Management System for Digital Archives (Scanned Documents)项目地址: https://gitcode.com/gh_mirrors/pa/papermerge
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
