Docker部署档案软件单机版专用版全流程实操

一、环境准备与依赖安装

在开始部署档案软件单机版专用版之前，必须确保操作系统环境干净且依赖完备。本指南基于Linux环境（推荐Ubuntu 20.04或22.04 LTS）进行实操演示，Windows用户建议先配置WSL2环境。以下操作均在root权限或具有sudo权限的用户下执行。

更新系统源并安装必要的工具包。执行以下命令，确保系统处于最新状态并安装curl与git工具：

```bash sudo apt-get update sudo apt-get install -y curl git ```

接着，安装Docker与Docker Compose。这是运行单机版档案软件的核心容器化环境。执行官方的一键安装脚本：

```bash curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER ```

注意：执行完用户组修改后，必须注销当前用户并重新登录，或者执行以下命令使权限生效，否则后续启动容器会报错：

```bash newgrp docker ```

为了确保Docker Compose插件可用，检查其版本：

```bash docker compose version ```

若输出版本号，说明环境准备完成。如果提示未找到命令，请单独安装docker-compose插件：

```bash sudo apt-get install -y docker-compose-plugin ```

二、目录结构规划与创建

为了保证数据的安全管理与迁移，单机版专用版需要规范的目录结构。我们将在/opt目录下创建paperless-ngx项目目录，并规划数据、媒体、导出及消费目录。

执行以下命令创建主目录及子目录：

```bash sudo mkdir -p /opt/paperless-ngx cd /opt/paperless-ngx sudo mkdir -p data export media consume db ```

设置目录权限非常重要，这直接关系到容器能否读写文件。将当前用户设置为目录所有者：

```bash sudo chown -R $USER:$USER /opt/paperless-ngx ```

此时，目录结构已建立完毕。各目录功能说明如下：

• data：存储数据库数据及配置文件。
• export：存放处理完毕并导出的文档。
• media：存放原始文档及生成的预览图。
• consume：监控目录，放入此处的文件会被自动抓取并归档。
• db：PostgreSQL数据库的持久化挂载点。

三、Docker Compose配置文件编写

这是部署单机版专用版的核心步骤。我们需要创建一个docker-compose.yml文件，定义Web服务、数据库、缓存及OCR识别服务。

在/opt/paperless-ngx目录下创建并编辑文件：

```bash nano docker-compose.yml ```

将以下完整配置内容复制粘贴到文件中。该配置已针对单机版进行了优化，包含中文OCR支持及本地文件映射：

```yaml version: "3.8" services: broker: image: docker.io/library/redis:7 restart: always volumes: - ./redisdata:/data db: image: docker.io/library/postgres:15 restart: always volumes: - ./db:/var/lib/postgresql/data environment: POSTGRES_USER: paperless POSTGRES_PASSWORD: paperless POSTGRES_DB: paperless webserver: image: ghcr.io/paperless-ngx/paperless-ngx:latest restart: always depends_on: - db - broker ports: - "8000:8000" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000"] interval: 30s timeout: 10s retries: 5 volumes: - ./data:/usr/src/paperless/data - ./media:/usr/src/paperless/media - ./export:/usr/src/paperless/export - ./consume:/usr/src/paperless/consume environment: PAPERLESS_REDIS: redis://broker:6379 PAPERLESS_DBHOST: db PAPERLESS_DBPASS: paperless 设置管理员用户名和密码，首次启动生效 PAPERLESS_ADMIN_USER: admin PAPERLESS_ADMIN_PASSWORD: your_secure_password 设置时区为上海时间 PAPERLESS_TIME_ZONE: Asia/Shanghai 配置OCR语言，支持简体中文和英文 PAPERLESS_OCR_LANGUAGE: chi_sim+eng PAPERLESS_OCR_LANGUAGES: chi_sim+eng 禁用自动更新，保持单机版稳定 PAPERLESS_ENABLE_UPDATE: false 设置URL前缀，如果需要反向代理可修改 PAPERLESS_URL: http://localhost:8000 gotenberg: image: docker.io/gotenberg/gotenberg:7 restart: always volumes: - ./gotenbergdata:/data tika: image: docker.io/apache/tika:latest restart: always volumes: data: media: export: ```

按Ctrl+X，然后按Y，最后按Enter保存并退出编辑器。

关键配置项解读：

• PAPERLESS_ADMIN_USER与PAPERLESS_ADMIN_PASSWORD：预置管理员账号，请务必将your_secure_password修改为高强度密码。
• PAPERLESS_OCR_LANGUAGE：设置为chi_sim+eng，确保系统能准确识别中文文档内容。
• ports：映射宿主机8000端口到容器8000端口，访问地址即为http://服务器IP:8000。

四、启动服务与初始化

配置文件就绪后，即可拉取镜像并启动服务。在docker-compose.yml所在目录下执行：

```bash docker compose up -d ```

参数-d表示后台运行。首次运行会自动下载约1.5GB的镜像文件，具体时间取决于网络速度。请耐心等待，直到命令行提示容器已启动。

查看容器运行状态，确保所有服务均为Up状态：

```bash docker compose ps ```

正常输出应包含webserver、db、broker、gotenberg、tika五个服务，且Status列显示Up。如果webserver服务反复重启，请使用以下命令查看日志排查错误：

```bash docker compose logs webserver ```

通常常见的错误是目录权限不足，确保第三步的chown命令已正确执行。

五、访问与基本使用

服务启动成功后，打开浏览器，访问：

http://localhost:8000（如果是远程服务器，请替换为对应的服务器IP地址）。

使用配置文件中设置的管理员账号登录。默认用户名为admin，密码为您设置的your_secure_password。

登录成功后，进入主界面。此时系统已就绪，可以进行文档归档操作：

1. 上传文档：点击右上角的“上传”按钮，选择本地PDF或图片文件。
2. 查看处理状态：上传后，系统会自动进行OCR识别。在“文档”列表中，稍等片刻即可看到文档内容已被索引。
3. 搜索测试：在搜索框输入文档中的中文关键词，验证OCR识别效果。如果能够搜到，说明中文语言包配置正确。
4. 自动归档测试：将一个PDF文件直接上传到服务器的/opt/paperless-ngx/consume目录下，系统会自动检测并将其拉入数据库进行归档，无需手动上传。

六、数据备份与恢复策略

作为单机版专用版，数据安全完全依赖本地维护。必须建立定期备份机制。我们编写一个简单的脚本来备份数据库和文件。

创建备份脚本：

```bash nano /opt/paperless-ngx/backup.sh ```

写入以下内容：

```bash !/bin/bash BACKUP_DIR="/opt/paperless-ngx/backups" DATE=$(date +%Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR 备份PostgreSQL数据库 docker compose exec -T db pg_dump -U paperless paperless > $BACKUP_DIR/db_backup_$DATE.sql 打包媒体文件和配置文件 tar -czf $BACKUP_DIR/data_backup_$DATE.tar.gz ./media ./export ./data 删除7天前的备份 find $BACKUP_DIR -type f -mtime +7 -delete echo "Backup completed: $DATE" ```

赋予执行权限：

```bash chmod +x /opt/paperless-ngx/backup.sh ```

执行手动备份测试：

```bash ./backup.sh ```

若需恢复数据，操作步骤如下：

1. 停止服务：docker compose down
2. 恢复数据库：docker compose up -d db，等待数据库启动后，执行cat backups/db_backup_xxx.sql | docker compose exec -T db psql -U paperless paperless。
3. 恢复文件：tar -xzf backups/data_backup_xxx.tar.gz。
4. 启动全部服务：docker compose up -d。

七、常见问题排查

在部署和使用过程中，可能会遇到以下典型问题，请按方案处理：

1. 端口8000被占用

如果服务器上已有其他服务占用了8000端口，修改docker-compose.yml中的ports映射，例如改为"8080:8000"，并修改PAPERLESS_URL环境变量对应端口，然后重启：docker compose up -d --force-recreate。

2. 中文无法识别或显示乱码

确保docker-compose.yml中PAPERLESS_OCR_LANGUAGE设置为chi_sim+eng。如果下载镜像时网络不稳定，可能导致语言包下载不完整。解决方法是重新构建webserver镜像或清理缓存后重启。

3. 消费目录不自动识别

检查consume目录的权限。如果文件是通过root用户复制进去的，容器内的paperless用户可能无法读取移动。执行：sudo chmod -R 777 /opt/paperless-ngx/consume临时解决，或确保文件归属权正确。

4. 内存占用过高

OCR处理非常消耗内存。如果单机配置较低（如1GB内存），建议在docker-compose.yml中限制Tika和Gotenberg的内存资源，或者在webserver环境变量中添加PAPERLESS_OCR_THREADS=1以减少并发线程。