企业云档案系统搭建与使用全流程实操手册

环境依赖与基础环境配置

在开始部署云档案系统之前，必须确保服务器环境满足运行要求。本指南基于Linux环境（推荐Ubuntu 20.04或CentOS 7+）进行实操演示，使用Docker容器化部署以隔离环境依赖，避免冲突。

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

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

接下来，安装Docker及Docker Compose。如果服务器已安装Docker，请确保版本高于20.10。

```bash 安装Docker curl -fsSL https://get.docker.com | bash sudo usermod -aG docker $USER 安装Docker Compose sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose ```

创建项目目录结构，用于存放配置文件和数据持久化。这种结构化目录管理有助于后期维护和备份。

```bash mkdir -p /data/cloud-archive/{postgres,redis,media,export,consume} cd /data/cloud-archive ```

核心服务部署配置

我们将使用docker-compose.yml文件来定义服务。该文件包含了Web应用、PostgreSQL数据库、Redis缓存、以及文档转换工具的完整配置。请在/data/cloud-archive目录下创建该文件：

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

将以下完整配置复制到文件中。请注意，不要修改卷挂载的路径，除非你更改了上一步的目录结构。

```yaml version: '3.5' services: broker: image: docker.io/library/redis:7 restart: always volumes: - ./redis:/data db: image: docker.io/library/postgres:15 restart: always volumes: - ./postgres:/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: - ./media:/usr/src/paperless/media - ./export:/usr/src/paperless/export - ./consume:/usr/src/paperless/consume env_file: - .env environment: PAPERLESS_REDIS: redis://broker:6379 PAPERLESS_DBHOST: db gotenberg: image: docker.io/gotenberg/gotenberg:7 restart: always command: - "gotenberg" - "--chromium-disable-routes" environment: DISABLE_ROUTES: 1 tika: image: apache/tika:latest restart: always ```

接着，在同级目录下创建环境变量文件.env，用于定义系统核心参数：

```bash nano .env ```

填入以下关键配置。请务必修改PAPERLESS_ADMIN_PASSWORD为高强度的管理员密码。

```ini 管理员账户配置 PAPERLESS_ADMIN_USER=admin PAPERLESS_ADMIN_PASSWORD=your_secure_password_here 系统基础配置 PAPERLESS_URL=http://localhost:8000 PAPERLESS_TIME_ZONE=Asia/Shanghai PAPERLESS_OCR_LANGUAGE=chi_sim+eng 性能优化配置 PAPERLESS_TASK_WORKERS=2 PAPERLESS_THREADS_PER_WORKER=2 ```

启动服务与初始化验证

配置文件准备就绪后，执行以下命令拉取镜像并启动所有服务容器：

```bash cd /data/cloud-archive docker-compose up -d ```

首次启动需要下载镜像，请耐心等待。启动后，使用以下命令查看容器状态，确保所有服务均为Up (healthy)状态：

```bash docker-compose ps ```

如果看到webserver服务不断重启，请使用docker-compose logs -f webserver查看日志。通常是因为数据库连接未就绪或权限问题。检查/data/cloud-archive/media目录的权限，确保容器可写入：

```bash sudo chown -R $USER:$USER /data/cloud-archive ```

服务正常后，访问 http://服务器IP:8000 即可看到登录界面。使用.env中配置的admin账号和密码登录。

反向代理与HTTPS安全配置

为了生产环境安全，必须配置Nginx反向代理并启用HTTPS。首先安装Nginx：

```bash sudo apt-get install -y nginx ```

为云档案系统创建Nginx配置文件：

```bash sudo nano /etc/nginx/sites-available/cloud-archive.conf ```

写入以下配置，将server_name替换为你的实际域名：

```nginx server { listen 80; server_name archive.yourdomain.com; client_max_body_size 100M; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_redirect off; } } ```

启用配置并重启Nginx：

```bash sudo ln -s /etc/nginx/sites-available/cloud-archive.conf /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl restart nginx ```

安装Certbot并申请SSL证书，开启自动HTTPS：

```bash sudo apt-get install -y certbot python3-certbot-nginx sudo certbot --nginx -d archive.yourdomain.com ```

证书申请成功后，修改/data/cloud-archive/.env文件中的PAPERLESS_URL为https://archive.yourdomain.com，并重启容器：

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

OCR识别与全文检索优化

云档案的核心功能是OCR（光学字符识别）。系统默认配置了中英文混合识别（chi_sim+eng）。如果需要处理特定文档，可调整配置。

对于大量PDF文档，建议调整Tika和Gotenberg的内存限制。编辑docker-compose.yml，在webserver服务下添加：

```yaml environment: ... 其他环境变量 OMP_THREAD_LIMIT: 1 ```

为了提高检索效率，建议定期重建索引。进入容器执行：

```bash docker-compose exec webserver python3 manage.py document_index reindex ```

如果遇到中文乱码或识别率低的问题，可能需要安装额外的字体。将字体文件挂载到容器内：

```yaml 在docker-compose.yml的webserver volumes下添加 - ./fonts:/usr/share/fonts/truetype/custom ```

放入字体文件后，重启容器并更新字体缓存：

```bash docker-compose exec webserver fc-cache -fv ```

数据备份与恢复策略

数据安全至关重要，必须设置自动化备份脚本。创建备份脚本backup.sh：

```bash nano /data/scripts/backup.sh ```

写入以下脚本内容，实现数据库和附件文件的打包备份：

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

赋予执行权限并设置定时任务（Cron），每天凌晨2点执行：

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

恢复数据时，先恢复数据库，再恢复文件：

```bash 恢复数据库 cat /data/backups/db_backup_20230101.sql | docker-compose exec -T db psql -U paperless paperless 恢复文件 tar -xzf /data/backups/media_backup_20230101.tar.gz -C /data/ ```

常见故障排查与性能调优

在使用过程中，可能会遇到文档无法预览或消费卡顿的问题。

1. 文档无法预览： 检查Gotenberg服务日志，通常是PDF转换超时。可在.env中增加PAPERLESS_CONSUMER_POLLING=60延长轮询间隔。

2. 消费速度慢： 如果上传大量文件后处理缓慢，可临时增加Worker数量。修改.env中的PAPERLESS_TASK_WORKERS=4并重启。

3. 存储空间不足： 建议挂载独立的NAS或云存储到/media目录。修改docker-compose.yml中的volumes指向外部存储路径即可。

通过以上步骤，你已经完成了一套高可用、安全的云档案系统的搭建与配置。严格按照本指南操作，可确保系统在生产环境稳定运行。