终极指南：如何快速集成ELK Stack实现Paperless异常行为监控告警

【免费下载链接】paperless Scan, index, and archive all of your paper documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless

Paperless是一款强大的文档扫描、索引和归档工具，能帮助用户轻松管理纸质文档。本文将详细介绍如何为Paperless集成ELK Stack（Elasticsearch、Logstash、Kibana），实现日志分析与异常行为监控告警，提升系统的稳定性和可维护性。

为什么需要ELK Stack监控Paperless？

在使用Paperless处理大量文档时，系统可能会出现各种异常情况，如文档处理失败、OCR识别错误、权限问题等。通过ELK Stack，我们可以集中收集、分析Paperless的日志数据，实时监控系统运行状态，及时发现并解决问题。

Paperless日志系统架构

Paperless的日志配置主要在src/paperless/settings.py文件中定义。默认配置如下：

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "consumer": {
            "class": "documents.loggers.PaperlessLogger",
        }
    },
    "loggers": {
        "documents": {
            "handlers": ["consumer"],
            "level": os.getenv("PAPERLESS_CONSUMER_LOG_LEVEL", "INFO"),
        },
    },
}

从配置中可以看出，Paperless使用了自定义的PaperlessLogger类来处理日志，日志级别可通过环境变量PAPERLESS_CONSUMER_LOG_LEVEL设置，默认为INFO级别。

一键安装ELK Stack步骤

1. 安装Docker和Docker Compose

ELK Stack可以通过Docker快速部署，首先确保系统已安装Docker和Docker Compose。

2. 创建docker-compose.yml文件

创建一个包含Elasticsearch、Logstash和Kibana的docker-compose.yml文件：

version: '3'
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.14.0
    environment:
      - discovery.type=single-node
    ports:
      - "9200:9200"
  logstash:
    image: docker.elastic.co/logstash/logstash:7.14.0
    volumes:
      - ./logstash/pipeline:/usr/share/logstash/pipeline
    ports:
      - "5044:5044"
  kibana:
    image: docker.elastic.co/kibana/kibana:7.14.0
    ports:
      - "5601:5601"
    depends_on:
      - elasticsearch

3. 启动ELK Stack

运行以下命令启动ELK Stack：

docker-compose up -d

配置Paperless日志输出到ELK Stack

1. 修改Paperless日志配置

编辑src/paperless/settings.py文件，添加Logstash日志处理器：

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "consumer": {
            "class": "documents.loggers.PaperlessLogger",
        },
        "logstash": {
            "class": "logstash.TCPLogstashHandler",
            "host": "logstash",
            "port": 5044,
            "version": 1,
            "message_type": "python-logstash",
            "fqdn": False,
            "tags": ["paperless"],
        },
    },
    "loggers": {
        "documents": {
            "handlers": ["consumer", "logstash"],
            "level": os.getenv("PAPERLESS_CONSUMER_LOG_LEVEL", "INFO"),
        },
    },
}

2. 安装logstash库

pip install python-logstash

3. 重启Paperless服务

docker restart paperless_webserver paperless_consumer

配置Logstash处理Paperless日志

创建Logstash配置文件

在logstash/pipeline目录下创建logstash.conf文件：

input {
  tcp {
    port => 5044
    codec => json
  }
}

filter {
  json {
    source => "message"
  }
  date {
    match => ["timestamp", "ISO8601"]
    target => "@timestamp"
  }
}

output {
  elasticsearch {
    hosts => ["elasticsearch:9200"]
    index => "paperless-%{+YYYY.MM.dd}"
  }
  stdout { codec => rubydebug }
}

在Kibana中创建异常监控告警

1. 创建索引模式

1. 打开Kibana界面（http://localhost:5601）
2. 进入Management > Index Patterns
3. 创建索引模式paperless-*

2. 创建可视化面板

创建一个监控Paperless关键指标的可视化面板，如文档处理数量、错误率等。

3. 设置异常告警

1. 进入Alerts > Create alert
2. 设置告警条件，如错误日志数量超过阈值
3. 配置告警通知方式，如邮件、Slack等

常见异常场景及监控规则

1. 文档处理失败

监控规则：当level为ERROR且包含"Failed to process document"关键字的日志出现时触发告警。

2. OCR识别错误

监控规则：当level为WARNING且包含"OCR failed"关键字的日志出现时触发告警。

3. 磁盘空间不足

监控规则：当系统日志中出现"disk full"关键字时触发告警。

总结

通过本文介绍的方法，你可以快速为Paperless集成ELK Stack，实现日志的集中管理和异常监控告警。这将帮助你及时发现并解决系统问题，提高Paperless的稳定性和可靠性。

如果你想深入了解Paperless的日志系统，可以查看src/documents/loggers.py文件，其中定义了Paperless的自定义日志处理器。

希望本文对你有所帮助，如有任何问题，欢迎在项目的Issue中提出。

【免费下载链接】paperless Scan, index, and archive all of your paper documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless