一、环境基础准备与容器化部署
解决维护成本的核心在于将手工运维转化为自动化运维。本方案基于Docker容器化技术，构建一套包含自动备份、自动更新、日志监控的零维护成本档案系统。我们选用开源的Paperless-ngx作为档案软件核心，它功能强大且完全免费。
在服务器上安装Docker及Docker Compose。执行以下命令完成安装，该命令适用于大多数Linux发行版：
1. 安装Docker
```bash
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
systemctl enable docker && systemctl start docker
```
2. 安装Docker Compose
```bash
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
```
3. 创建项目目录结构
执行以下命令创建标准的数据持久化目录，确保数据与容器分离，避免升级丢失：
```bash
mkdir -p /data/archives/{postgres,redis,data,export,media,backup,logs}
cd /data/archives
```
二、编写完整编排文件
在/data/archives目录下创建docker-compose.yml文件。该文件集成了档案系统核心、数据库、自动更新工具Watchtower、备份工具Restic以及日志监控Loki。请直接复制以下完整内容，不要遗漏任何配置项：
```yaml
version: "3.8"
services:
1. 档案系统核心服务
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"
volumes:
- ./data:/usr/src/paperless/data
- ./media:/usr/src/paperless/media
- ./export:/usr/src/paperless/export
- ./logs:/usr/src/paperless/logs
env_file: docker-compose.env
environment:
PAPERLESS_REDIS: redis://broker:6379
PAPERLESS_DBHOST: db
PAPERLESS_DBUSER: paperless
PAPERLESS_DBPASS: paperless
PAPERLESS_DBNAME: paperless
2. 自动更新组件 Watchtower
每天凌晨3点检查并更新所有镜像，自动维护系统安全
watchtower:
image: containrrr/watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WATCHTOWER_SCHEDULE=0 0 3
- WATCHTOWER_CLEANUP=true
- WATCHTOWER_POLL_INTERVAL=86400
restart: always
3. 自动备份组件 Restic
每天凌晨4点将数据备份到本地./backup目录
backup:
image: restic/restic:latest
volumes:
- ./data:/source/data:ro
- ./media:/source/media:ro
- ./postgres:/source/postgres:ro
- ./backup:/backup
environment:
RESTIC_REPOSITORY: /backup
RESTIC_PASSWORD: "YourStrongPasswordHere"
BACKUP_CRON: "0 0 4 "
首次运行前需手动执行初始化，此处脚本会自动判断
RESTIC_INIT_ARGS: "--init"
command: >
sh -c "restic snapshots || restic init &&
echo '0 0 4 restic backup /source && restic forget --keep-daily 7 --keep-weekly 4' | crontab - &&
crond -f"
restart: always
4. 日志监控组件 Loki
loki:
image: grafana/loki:latest
ports:
- "3100:3100"
volumes:
- ./loki-config.yml:/etc/loki/local-config.yaml
command: -config.file=/etc/loki/local-config.yaml
restart: always
5. 日志采集组件 Promtail
promtail:
image: grafana/promtail:latest
volumes:
- ./logs:/var/log/paperless:ro
- ./promtail-config.yml:/etc/promtail/config.yml:ro
command: -config.file=/etc/promtail/config.yml
restart: always
```
三、配置环境变量与日志采集
为了确保系统正常运行，需要补充环境变量文件和日志采集配置。这些配置决定了系统的语言、管理员权限及日志处理规则。
1. 创建环境变量文件
在同级目录下创建docker-compose.env文件，填入以下关键配置：
```ini
设置管理员用户名和密码，首次启动生效
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=your_secure_password
设置时区，确保文档处理时间准确
PAPERLESS_TIME_ZONE=Asia/Shanghai
设置OCR语言包，支持中文识别
PAPERLESS_OCR_LANGUAGE=chi_sim+eng
配置站点URL，若通过域名访问请修改
PAPERLESS_URL=http://localhost:8000
```
2. 配置Loki日志接收
创建loki-config.yml文件，定义日志存储路径：
```yaml
server:
http_listen_port: 3100
common:
path_prefix: /var/lib/loki
storage:
filesystem:
chunks_directory: /var/lib/loki/chunks
rules_directory: /var/lib/loki/rules
replication_factor: 1
ring:
instance_addr: localhost
kvstore:
store: inmemory
schema_config:
configs:
- from: 2020-10-24
store: boltdb-shipper
object_store: filesystem
schema: v11
index:
prefix: index_
period: 24h
ruler:
storage:
type: local
local:
directory: /var/lib/loki/rules
```
3. 配置Promtail日志推送
创建promtail-config.yml文件，将日志推送到Loki：
```yaml
server:
http_listen_port: 9080
positions:
filename: /tmp/positions.yaml
clients:
- url: http://loki:3100/loki/api/v1/push
scrape_configs:
- job_name: paperless-logs
static_configs:
- targets:
- localhost
labels:
job: paperless
__path__: /var/log/paperless/.log
```
四、启动与初始化操作
所有配置文件就绪后，执行以下命令启动整套体系。该过程会自动拉取镜像、构建容器网络并启动服务。
1. 启动所有服务
```bash
docker-compose up -d
```
2. 检查服务状态
执行docker-compose ps，确保所有服务的State均为Up。如果遇到数据库启动失败，通常是权限问题，请检查/data/archives/postgres目录的属主是否为999或70（PostgreSQL UID）。
3. 初始化备份仓库
虽然我们在Compose中配置了自动初始化，但建议首次手动执行一次备份以确保密码和路径正确：
```bash
docker-compose exec backup restic init
docker-compose exec backup restic backup /source
```
4. 验证自动更新
Watchtower默认每天凌晨3点运行。为了测试其是否有效，可以手动强制触发一次检查（临时修改Compose中的schedule环境变量为 并重启，或者等待自动运行）。查看日志确认：
```bash
docker-compose logs -f watchtower
```
五、日常维护与故障排查
系统搭建完成后，日常维护工作基本降为零。以下针对可能出现的极端情况提供恢复方案。
1. 数据恢复操作
如果主数据损坏，利用Restic进行快照恢复。首先查看备份列表：
```bash
docker-compose exec backup restic snapshots
```
选择快照ID进行恢复，将数据恢复到一个临时目录以策安全：
```bash
docker-compose exec backup restic restore latest --target /restore
```
2. 查看系统日志
通过Loki接口查询日志，或者直接查看本地文件：
```bash
tail -f /data/archives/logs/paperless.log
```
3. 性能优化建议
如果文档处理速度较慢，可以修改docker-compose.yml中webserver服务的environment，增加PAPERLESS_TASK_WORKERS=4（根据CPU核心数调整），并增加内存限制。修改后执行docker-compose up -d即可生效，Watchtower会自动更新容器，不会丢失数据。
