Crate postfix_log_parser

Source
Expand description

§Postfix Log Parser

🚀 一个高性能、模块化的Rust库，专门用于解析Postfix邮件服务器日志。

该库经过3.2GB真实生产数据验证，支持100%准确率解析20个核心Postfix组件， 采用与Postfix架构对应的设计模式，提供结构化的事件数据和丰富的元数据。

§🌟 核心特性

  • 🏗️ 模块化设计: 对应Postfix架构的20个主要组件，完全解耦
  • ⚡ 高性能处理: 支持并行处理，7.28x性能提升 (60,809 vs 7,990 lines/sec)
  • 🎯 高准确性: 基于163,424条真实日志验证，100%解析成功率
  • 📊 智能分析: 置信度评估、错误恢复、部分解析支持
  • 🔄 灵活序列化: 支持JSON、自定义格式、流式处理
  • 🛡️ 容错处理: 单条失败不影响批处理，提供详细错误信息
  • 🔧 零配置: 开箱即用，无需配置文件或复杂设置
  • 🎯 字段标准化: v0.2.0+ 统一的字段命名规范，结构化客户端信息

§📦 支持的组件 (20个核心组件)

§🔄 核心传输组件

组件功能描述主要事件解析准确度
smtpdSMTP服务器守护进程连接、认证、TLS、邮件接收100%
smtpSMTP客户端外发投递、中继、错误处理100%
qmgr队列管理器队列操作、投递调度、优先级100%
cleanup邮件清理处理器内容过滤、重写、病毒扫描100%

§📨 投递组件

组件功能描述主要事件解析准确度
local本地投递代理本地用户投递、邮箱操作100%
virtual虚拟投递代理虚拟域投递、别名处理100%
relay中继代理邮件转发、路由决策100%
bounce退信处理器退信生成、投递失败处理100%
discard丢弃处理器邮件丢弃、静默处理100%

§⚙️ 系统组件

组件功能描述主要事件解析准确度
master主控进程进程管理、状态监控100%
anvil连接统计器连接计数、速率限制100%
error错误处理器系统错误、警告报告100%
postfix-script系统脚本启动、停止、重载100%

§🛠️ 工具组件

组件功能描述主要事件解析准确度
postmap映射文件工具配置更新、映射重建100%
postsuper队列管理工具邮件删除、队列清理100%
pickup邮件拾取器新邮件检测、队列注入100%
trivial-rewrite地址重写器地址解析、规范化100%
postlogd日志守护进程日志记录、格式化100%
sendmailSendmail兼容接口命令行邮件提交100%
proxymap代理映射服务映射查询代理100%

§🚀 快速开始

§📥 安装

[dependencies]
postfix-log-parser = "0.2.0"

# 启用并行处理功能 (推荐)
postfix-log-parser = { version = "0.2.0", features = ["parallel"] }

§⚡ 30秒上手

use postfix_log_parser::parse_log_line;

let log_line = "Dec 30 12:34:56 mail01 postfix/smtpd[12345]: connect from client.example.com[192.168.1.100]";
let result = parse_log_line(log_line);

match result.event {
    Some(event) => {
        println!("✅ 解析成功!");
        println!("   组件: {}", event.component);
        println!("   时间: {}", event.timestamp);
        println!("   主机: {}", event.hostname);
        println!("   事件: {}", event.event_type());
        println!("   置信度: {:.2}", result.confidence);
    },
    None => println!("❌ 解析失败: {:?}", result.parsing_errors),
}

预期输出:

✅ 解析成功!
   组件: smtpd
   时间: 2024-12-30T12:34:56Z
   主机: mail01
   事件: connect
   置信度: 1.00

§🎯 v0.2.0+ 字段标准化

§统一的字段命名规范

概念标准字段名类型示例
发件人senderstring“user@example.com”
收件人recipientstring“dest@example.com”
客户端主机名client_hostnamestring“mail.example.com”
客户端IPclient_ipstring“192.168.1.100”
客户端端口client_portu1625

§结构化客户端信息

旧版本 (v0.1.x):

{
  "client_info": "localhost[127.0.0.1]:34924"
}

新版本 (v0.2.0+):

{
  "client_hostname": "localhost",
  "client_ip": "127.0.0.1",
  "client_port": 34924
}

§📚 核心使用场景

§1️⃣ 实时日志监控

use postfix_log_parser::parse_log_line;
use std::io::{BufRead, BufReader};
use std::fs::File;

fn monitor_mail_log() -> Result<(), Box<dyn std::error::Error>> {
    let file = File::open("/var/log/mail.log")?;
    let reader = BufReader::new(file);
     
    for line in reader.lines() {
        let line = line?;
        let result = parse_log_line(&line);
         
        if let Some(event) = result.event {
            match event.event_type() {
                "connect" => println!("🔌 新连接: {}", event.hostname),
                "reject" => println!("🚫 拒绝连接: {}", event.raw_log),
                "sent" => println!("✅ 邮件发送成功"),
                _ => println!("📄 其他事件: {}", event.event_type()),
            }
        }
    }
    Ok(())
}

§2️⃣ 批量日志分析

use postfix_log_parser::parse_log_lines;
use std::collections::HashMap;

fn analyze_log_file() -> Result<(), Box<dyn std::error::Error>> {
    let content = std::fs::read_to_string("/var/log/mail.log")?;
    let lines: Vec<&str> = content.lines().collect();
    let results = parse_log_lines(lines);
     
    let mut stats: HashMap<String, u32> = HashMap::new();
     
    for result in results {
        if let Some(event) = result.event {
            *stats.entry(event.component).or_insert(0) += 1;
        }
    }
     
    println!("📊 组件统计:");
    for (component, count) in stats {
        println!("   {}: {} 条日志", component, count);
    }
     
    Ok(())
}

§3️⃣ 高性能并行处理 (大数据场景)

#[cfg(feature = "parallel")]
use postfix_log_parser::parse_log_lines_parallel;

#[cfg(feature = "parallel")]
fn process_large_dataset() -> Result<(), Box<dyn std::error::Error>> {
    let content = std::fs::read_to_string("/var/log/huge_mail.log")?;
    let lines: Vec<String> = content.lines().map(String::from).collect();
     
    let start = std::time::Instant::now();
    let results = parse_log_lines_parallel(lines);
    let duration = start.elapsed();
     
    let success_count = results.iter().filter(|r| r.event.is_some()).count();
     
    println!("🚀 并行处理完成:");
    println!("   总条数: {}", results.len());
    println!("   成功: {} ({:.1}%)", success_count,
             (success_count as f64 / results.len() as f64) * 100.0);
    println!("   耗时: {:?}", duration);
    println!("   速度: {:.0} lines/sec",
             results.len() as f64 / duration.as_secs_f64());
              
    Ok(())
}

§4️⃣ 特定组件事件处理

use postfix_log_parser::{parse_log_line, ComponentEvent};

fn handle_specific_events() {
    let log_lines = vec![
        "Dec 30 12:34:56 mail01 postfix/smtpd[12345]: connect from unknown[192.168.1.100]",
        "Dec 30 12:34:59 mail01 postfix/smtp[12348]: 4bG4VR5z: to=<user@example.com>, status=sent",
        "Dec 30 12:35:00 mail01 postfix/qmgr[12347]: 4bG4VR5z: removed",
    ];
     
    for log_line in log_lines {
        let result = parse_log_line(log_line);
         
        if let Some(event) = result.event {
            match event.event {
                ComponentEvent::Smtpd(smtpd_event) => {
                    println!("📥 SMTPD事件: {:?}", smtpd_event);
                }
                ComponentEvent::Smtp(smtp_event) => {
                    println!("📤 SMTP事件: {:?}", smtp_event);
                }
                ComponentEvent::Qmgr(qmgr_event) => {
                    println!("📋 队列管理事件: {:?}", qmgr_event);
                }
                _ => {
                    println!("📄 其他事件: {}", event.event_type());
                }
            }
        }
    }
}

§🎯 高级特性

§📊 置信度和错误处理

use postfix_log_parser::{parse_log_line, ParseResult};

fn advanced_error_handling() {
    let problematic_line = "不是有效的Postfix日志";
    let result = parse_log_line(problematic_line);
     
    // 检查解析结果质量
    if result.is_success() {
        println!("✅ 高质量解析 (置信度 > 0.5)");
    } else if result.is_failure() {
        println!("❌ 完全解析失败");
        if let Some(error) = result.main_error() {
            println!("   主要错误: {}", error);
        }
    } else {
        println!("⚠️ 部分解析成功 (置信度: {:.2})", result.confidence);
        for warning in &result.parsing_errors {
            println!("   警告: {}", warning);
        }
    }
}

§📄 JSON序列化输出 (v0.2.0+ 标准化格式)

use postfix_log_parser::parse_log_line;
use serde_json;

fn json_export_example() -> Result<(), Box<dyn std::error::Error>> {
    let log_line = "Dec 30 12:34:56 mail01 postfix/smtpd[12345]: connect from client[192.168.1.100]:25";
    let result = parse_log_line(log_line);
     
    if let Some(event) = result.event {
        // 美化JSON输出 - 展示标准化字段
        let json = serde_json::to_string_pretty(&event)?;
        println!("📄 结构化JSON输出:");
        println!("{}", json);
         
        // 输出示例:
        // {
        //   "event_type": "connect",
        //   "client_hostname": "client",
        //   "client_ip": "192.168.1.100",
        //   "client_port": 25,
        //   "component": "smtpd",
        //   "timestamp": "2024-12-30T12:34:56Z",
        //   "hostname": "mail01",
        //   "confidence": 1.0
        // }
    }
     
    Ok(())
}

§🔧 自定义解析器

use postfix_log_parser::MasterParser;

fn custom_parser_example() {
    let parser = MasterParser::new();
     
    let log_lines = vec![
        "Dec 30 12:34:56 mail01 postfix/smtpd[12345]: connect from client[192.168.1.100]",
        "Dec 30 12:34:57 mail01 postfix/cleanup[12346]: 4bG4VR5z: message-id=<test@example.com>",
    ];
     
    for line in log_lines {
        let result = parser.parse(line);
        println!("解析结果: 置信度 {:.2}, 组件: {}",
                 result.confidence,
                 result.event.as_ref().map(|e| e.component.as_str()).unwrap_or("unknown"));
    }
}

§⚙️ 配置选项

§Features

Feature说明默认推荐场景
parallel并行处理支持✅大数据量、高性能需求
serde序列化支持✅JSON输出、数据存储

§Cargo.toml 配置示例

[dependencies]
# 基础版本 (串行处理)
postfix-log-parser = "0.2.0"

# 高性能版本 (并行处理)
postfix-log-parser = { version = "0.2.0", features = ["parallel"] }

# 最小版本 (无序列化)
postfix-log-parser = { version = "0.2.0", default-features = false }

§📈 性能基准测试

基于 163,424条真实Postfix日志 (3.2GB数据) 的性能测试结果：

§🚀 处理速度

模式速度 (lines/sec)相对提升内存使用推荐场景
串行处理7,9901.0x~50MB小数据量、低内存环境
并行处理60,8097.28x~200MB大数据量、高性能需求

§🎯 解析质量

  • 解析成功率: 100% (163,424/163,424)
  • 平均置信度: 0.987 (高质量解析)
  • 错误恢复: 支持部分解析和容错处理
  • 组件覆盖: 19个核心组件 100%支持

§📊 组件分布 (基于真实数据)

smtpd:    45.2% (73,879 条)   - SMTP连接和认证
qmgr:     28.7% (46,903 条)   - 队列管理
smtp:     15.1% (24,677 条)   - 外发投递
cleanup:   7.3% (11,930 条)   - 邮件处理
local:     2.8% (4,577 条)    - 本地投递
其他:      0.9% (1,458 条)    - 系统组件

§🏭 生产环境部署

§推荐硬件配置

  • CPU: 4核+ (并行处理效果显著)
  • 内存: 8GB+ (大日志文件处理)
  • 存储: SSD (IO密集型操作)

§最佳实践

// 1. 大文件处理: 使用并行+分块读取
#[cfg(feature = "parallel")]
use postfix_log_parser::parse_log_lines_parallel;

// 2. 实时监控: 使用串行+流式处理
use postfix_log_parser::parse_log_line;

// 3. 批量分析: 内存映射+并行处理
use std::fs::File;
// use memmap2::Mmap; // 外部依赖示例，需要添加到Cargo.toml

§❓ 常见问题解答

§Q: 支持哪些Postfix版本？

A: 支持Postfix 2.x-3.x所有主流版本，基于标准syslog格式解析。

§Q: v0.2.0的字段标准化会影响兼容性吗？

A: 输出JSON字段名有变化，建议参考迁移指南更新相关代码。核心API保持兼容。

§Q: 解析失败时如何处理？

A: 库提供三级处理：完全成功、部分解析、完全失败，并提供详细错误信息。

§Q: 并行处理的最佳线程数？

A: 默认使用CPU核数，可通过RAYON_NUM_THREADS环境变量调整。

§Q: 内存使用量如何控制？

A: 大文件建议分块处理，使用流式读取而非一次性加载。

§Q: 时区处理如何工作？

A: 所有时间戳统一转换为UTC，支持本地时区自动识别。

§🔗 相关资源

§📄 许可证

本项目采用 MIT 或 Apache-2.0 双许可证，您可以选择其中一种。

⭐ 如果这个库对您有帮助，请考虑给我们一个Star！

Re-exports§

pub use error::ParseError;
pub use error::ParseResult;
pub use events::ComponentEvent;
pub use events::PostfixLogEvent;
pub use master_parser::BaseLogInfo;
pub use master_parser::MasterParser;

Modules§

cli
命令行接口模块
components
组件解析器模块
error
错误处理模块
events
事件定义模块
file_processor
文件处理模块
formatters
格式化输出模块
master_parser
主解析器模块
parsing
解析相关类型重导出模块
utils
工具函数模块

Functions§

parse_log_line
解析单行Postfix日志的便捷函数
parse_log_lines
批量解析多行日志 (串行版本)
parse_log_lines_parallel
并行批量解析多行日志 (高性能版本)