武汉档案软件实操指南：Docker十分钟部署Paperless

一、环境准备与Docker安装

在开始部署之前，我们需要准备一台干净的服务器。为了保证系统的稳定性和兼容性，推荐使用CentOS 7.9或Ubuntu 20.04及以上版本的操作系统。本指南将以Ubuntu 22.04为例进行演示。核心依赖环境为Docker和Docker Compose，这是实现一键部署的关键。

执行以下命令更新系统源并安装必要的依赖工具：

```bash sudo apt-get update sudo apt-get install -y curl git gnupg2 apt-transport-https ca-certificates software-properties-common lsb-release ```

接下来，安装Docker。为了确保下载速度和稳定性，我们直接使用官方安装脚本：

```bash curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh ```

安装完成后，将当前用户添加到docker组，以便后续操作无需sudo：

```bash sudo usermod -aG docker $USER newgrp docker ```

安装Docker Compose插件（新版Docker已自带Compose插件，若为旧版需单独安装）：

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

验证安装是否成功：

```bash docker --version docker compose version ```

二、创建项目目录结构

为了规范管理“武汉档案软件”的数据，我们将在服务器的/opt目录下创建一个专门的项目文件夹。所有的配置文件、上传的档案数据、数据库文件都将存储在此处，便于后续备份和迁移。

执行以下命令创建目录结构：

```bash sudo mkdir -p /opt/wuhan_archive/{data,consume,export,media,db} sudo chown -R $USER:$USER /opt/wuhan_archive ```

目录用途说明：

• data：存储Paperless的核心配置数据及索引文件。
• consume：监控文件夹，放入此处的PDF会自动被识别归档。
• export：导出文件夹，用于存放导出的原始文档。
• media：存储文档的缩略图及预览图。
• db：持久化PostgreSQL数据库文件。

三、编写Docker Compose配置文件

这是部署的核心环节。我们将创建一个docker-compose.yml文件，定义Web服务、数据库、缓存服务以及必要的任务队列。请确保配置内容完整且格式正确。

进入项目目录并创建文件：

```bash cd /opt/wuhan_archive 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_DB: paperless POSTGRES_USER: paperless POSTGRES_PASSWORD: paperless webserver: image: ghcr.io/paperless-ngx/paperless-ngx:latest restart: always depends_on: 2. - db 3. - 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 env_file: - .env environment: PAPERLESS_REDIS: redis://broker:6379 export-worker: image: {webserver.image} restart: always depends_on: - db - broker volumes: - ./data:/usr/src/paperless/data - ./media:/usr/src/paperless/media - ./export:/usr/src/paperless/export env_file: - .env environment: PAPERLESS_REDIS: redis://broker:6379 command: /usr/src/paperless/src/manage.py document_exporter consumer: image: {webserver.image} restart: always depends_on: - db - broker volumes: - ./data:/usr/src/paperless/data - ./media:/usr/src/paperless/media - ./consume:/usr/src/paperless/consume env_file: - .env environment: PAPERLESS_REDIS: redis://broker:6379 command: /usr/src/paperless/src/manage.py document_consumer volumes: data: media: redisdata: ```

保存并退出编辑器（Ctrl+X, Y, Enter）。

四、配置环境变量文件

为了避免敏感信息直接暴露在Compose文件中，我们创建一个.env文件来存储系统配置。这里将设置管理员账号、时区（Asia/Shanghai）以及OCR语言包。

创建并编辑.env文件：

```bash nano .env ```

输入以下配置内容：

```ini 设置管理员用户名和密码 PAPERLESS_ADMIN_USER=admin PAPERLESS_ADMIN_PASSWORD=your_secure_password_here 设置时区为上海时间，确保档案归档时间准确 PAPERLESS_TIME_ZONE=Asia/Shanghai 设置OCR语言为简体中文和英文，确保能识别中文档案 PAPERLESS_OCR_LANGUAGE=chi_sim+eng 设置站点URL（如果有域名，请替换为实际域名） PAPERLESS_URL=http://localhost:8000 启用自动删除已处理文件 PAPERLESS_CONSUMPTION_DIR=/usr/src/paperless/consume PAPERLESS_CONSUMPTION_DELETE=1 ```

注意：请务必修改PAPERLESS_ADMIN_PASSWORD为您自己的强密码。

五、启动服务与初始化

配置文件准备就绪后，即可启动所有容器。Docker Compose会自动拉取镜像并按照依赖顺序启动服务。

执行启动命令：

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

首次启动需要下载镜像，大约需要3-5分钟，具体取决于网络速度。可以通过以下命令查看服务运行状态：

```bash docker compose ps ```

当所有服务的Status都显示为Up (healthy)时，表示服务已成功启动。此时，系统会自动根据.env文件中的配置创建管理员账号。

六、系统配置与实操验证

打开浏览器，访问http://服务器IP:8000。你将看到Paperless的登录界面。使用刚才设置的管理员账号和密码进行登录。

1. 设置中文界面

登录后，默认界面可能是英文。点击右上角的用户头像 -> Settings -> Interface。在Language选项中，选择“简体中文”，然后点击保存。页面刷新后即可显示中文界面。

2. 验证OCR识别功能

为了验证“武汉档案软件”的核心功能，我们需要测试中文文档的识别能力。

• 点击左侧菜单的上传文档。
• 选择一张包含中文字符的图片或PDF文件进行上传。
• 上传完成后，系统会自动进入处理队列。点击右上角的“任务队列”图标，可以看到OCR识别的进度。
• 处理完成后，点击文档进入详情页。右侧边栏会显示“文档内容”，这里应该能看到准确识别出的中文文字。

3. 使用监控文件夹归档

这是实现批量归档的高效方式。在服务器本地，将需要归档的档案文件复制到/opt/wuhan_archive/consume目录下。

```bash cp /path/to/your/local_file.pdf /opt/wuhan_archive/consume/ ```

Paperless的Consumer容器会自动检测到新文件，并将其拉入系统进行OCR处理和归档。处理完毕后，consume目录下的原文件会被自动删除（根据之前的配置）。

七、数据备份与维护

对于档案管理系统，数据安全是重中之重。我们需要定期备份数据库和上传的文档文件。

创建一个简单的备份脚本backup.sh：

```bash nano /opt/wuhan_archive/backup.sh ```

脚本内容如下：

```bash !/bin/bash DATE=$(date +%Y%m%d_%H%M%S) BACKUP_DIR="/opt/backups/wuhan_archive" mkdir -p $BACKUP_DIR 备份数据库 docker compose exec -T db pg_dump -U paperless paperless > $BACKUP_DIR/db_$DATE.sql 打包数据文件 tar -czf $BACKUP_DIR/data_$DATE.tar.gz /opt/wuhan_archive/data /opt/wuhan_archive/media /opt/wuhan_archive/export 删除7天前的备份 find $BACKUP_DIR -type f -mtime +7 -delete ```

赋予执行权限并设置定时任务：

```bash chmod +x /opt/wuhan_archive/backup.sh (crontab -l 2>/dev/null; echo "0 2 /opt/wuhan_archive/backup.sh") | crontab - ```

以上配置将每天凌晨2点自动执行备份，并保留最近7天的数据。

八、常见问题排查

在部署过程中，如果遇到服务无法启动，请优先检查以下两点：

• 端口冲突：如果服务器8000端口被占用，请修改docker-compose.yml中的ports映射，例如改为"8080:8000"。
• 权限问题：确保/opt/wuhan_archive及其子目录的所有者为当前运行Docker的用户，否则容器内无法写入数据。