postfix-log-parser 0.1.3

# PostfixLogParser

[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/your-username/PostfixLogParser)
[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://your-username.github.io/PostfixLogParser/)

🚀 **高性能**·**模块化**·**生产级** Postfix日志解析器

将Postfix日志文件高效解析为结构化JSON数据，支持多个核心Postfix组件，提供高准确率的日志解析能力。

## ✨ 核心特性

- 🎯 **多组件支持** - 支持SMTPD、QMGR、CLEANUP、SMTP、ERROR、LOCAL、VIRTUAL等主要组件
- 🚀 **高性能解析** - 基于正则表达式的高效解析算法
- 🏗️ **模块化架构** - 可扩展的组件设计，便于添加新解析器
- 💎 **类型安全** - 基于Rust的强类型系统和内存安全保证
- 📈 **并行处理** - 可选的并行处理支持，适用于大文件处理
- ⚡ **结构化输出** - 支持JSON序列化的结构化日志事件
- 🔧 **易于扩展** - 清晰的组件接口，便于添加新的解析器
- 🛡️ **内存安全** - 基于Rust开发，确保内存安全和线程安全

## 🚀 快速开始

### 命令行使用

```bash
# 克隆项目
git clone <your-repository-url>
cd PostfixLogParser

# 解析日志文件
cargo run --release -- logs/postfix.log

# 快速组件统计分析
cargo run --bin component_stats_fast --release -- logs/postfix.log

# 详细组件统计分析
cargo run --bin component_stats --release -- logs/postfix.log

# 保存结果到文件
cargo run --release -- logs/postfix.log > output.json
```

### 作为库使用

```toml
[dependencies]
postfix-log-parser = "0.1.3"

# 或者启用并行处理
postfix-log-parser = { version = "0.1.3", features = ["parallel"] }
```

简单使用示例：

```rust
use postfix_log_parser::parse_log_line;

fn main() {
    let log_line = "Jun 05 15:40:52 mailserver postfix/smtpd[89]: connect from client.example.com[10.0.0.100]";
    let result = parse_log_line(log_line);

    if let Some(event) = result.event {
        println!("组件: {}", event.component);
        println!("时间戳: {}", event.timestamp);
        println!("置信度: {:.2}", result.confidence);
        
        // 转换为JSON
        let json = serde_json::to_string_pretty(&event).unwrap();
        println!("JSON: {}", json);
    }
}
```

## 🎪 架构设计

### 模块化架构

采用模块化设计，职责分离明确：

```
src/
├── main.rs              # 命令行工具入口
├── lib.rs               # 库接口
├── cli.rs               # 命令行参数处理
├── file_processor.rs    # 文件读取和批处理
├── master_parser.rs     # 主解析器
├── error.rs             # 错误类型定义
├── formatters/          # 格式化输出模块
│   ├── mod.rs           # 格式化器trait定义
│   └── json/            # JSON格式化模块
│       ├── mod.rs       # 主模块与核心逻辑
│       ├── smtpd.rs     # SMTPD事件JSON格式化
│       ├── qmgr.rs      # qmgr事件JSON格式化
│       └── common.rs    # 通用辅助函数
├── components/          # 组件解析器
│   ├── mod.rs
│   ├── smtpd.rs         # SMTPD事件解析器
│   ├── qmgr.rs          # qmgr事件解析器
│   ├── cleanup.rs       # cleanup事件解析器
│   ├── smtp.rs          # smtp事件解析器
│   ├── error.rs         # error事件解析器
│   ├── local.rs         # local事件解析器
│   └── virtual_parser.rs # virtual事件解析器
├── events/              # 事件类型定义
│   ├── mod.rs           # 事件模块导出
│   ├── base.rs          # 基础事件类型
│   ├── smtpd.rs         # SMTPD事件类型
│   ├── qmgr.rs          # qmgr事件类型
│   └── ...              # 其他组件事件类型
└── bin/                 # 分析工具
    ├── component_stats.rs      # 详细组件统计工具
    └── component_stats_fast.rs # 快速组件统计工具
```

### 设计原则

- **单一职责原则** - 每个模块职责明确
- **开放封闭原则** - 可添加新格式化器而不修改现有代码
- **依赖倒置** - 通过trait抽象格式化器接口
- **数据驱动** - 基于真实使用频率指导开发决策
- **高内聚低耦合** - 模块间依赖最小化

## 🛠️ 分析工具

项目提供两个强大的分析工具：

### 1. 详细组件统计工具
```bash
cargo run --bin component_stats --release -- <log_file>
```
- **功能**: 完整解析分析，提供详细的解析质量报告
- **适用**: 中小文件，开发质量验证

### 2. 快速组件统计工具  
```bash
cargo run --bin component_stats_fast --release -- <log_file>
```
- **功能**: 仅提取组件名，专注速度分析
- **适用**: 大文件，快速分析

**示例使用：**
```bash
# 快速分析大文件
cargo run --bin component_stats_fast --release -- /var/log/mail.log

# 查看各组件日志格式示例，用于开发参考
cargo run --bin component_stats_fast --release -- /var/log/mail.log --examples

# 详细解析验证开发质量
cargo run --bin component_stats --release -- logs/test1.log
```

## 📄 输出示例

```json
{
  "raw_log": "Jun 05 15:40:52 mailserver postfix/smtpd[89]: connect from client.example.com[10.0.0.100]:25",
  "timestamp": "2025-06-05T15:40:52Z",
  "hostname": "mailserver",
  "component": "smtpd",
  "process_id": 89,
  "log_level": "Info",
  "event": {
    "Smtpd": {
      "Connect": {
        "client_ip": "10.0.0.100",
        "client_hostname": "client.example.com",
        "port": 25
      }
    }
  },
  "queue_id": null
}
```

## 🛠️ 支持的字段

### 通用字段
- `line_number`: 行号
- `timestamp`: 时间戳 (ISO 8601格式)
- `hostname`: 主机名
- `component`: Postfix组件
- `process_id`: 进程ID
- `log_level`: 日志级别 (Info/Warning/Error)
- `confidence`: 解析置信度 (0.0-1.0)
- `original_line`: 原始日志行

### SMTPD专用字段
- `event_type`: 事件类型
- `client_ip`: 客户端IP地址
- `client_hostname`: 客户端主机名
- `port`: 端口号
- `queue_id`: 队列ID
- `command_stats`: SMTP命令统计
- `reason`: 拒绝/警告原因
- `filter_action`: 过滤器动作
- `warning_type`: 警告分类

### qmgr专用字段
- `event_type`: 事件类型 (message_active, message_removed, message_skipped, config_warning)
- `queue_id`: 队列ID
- `from`: 发件人地址
- `size`: 邮件大小(字节)
- `nrcpt`: 收件人数量
- `reason`: 跳过原因
- `status_details`: 状态详情
- `warning_type`: 警告类型

### cleanup专用字段
- `event_type`: 事件类型 (message_id, queue_file_warning, message_size, header_processing等)
- `queue_id`: 队列ID
- `message_id`: 邮件Message-ID
- `operation`: 操作类型 (mail_queue_enter等)
- `file_path`: 文件路径
- `error_reason`: 错误原因
- `header_name`: 邮件头字段名
- `header_value`: 邮件头字段值
- `size`: 邮件大小(字节)
- `filter_name`: 过滤器名称
- `action`: 处理动作
- `address_type`: 地址类型 (from/to)
- `original_address`: 原始地址
- `rewritten_address`: 重写后地址

## 🔧 API接口

### 主要函数

```rust
// 解析单行日志
pub fn parse_log_line(log_line: &str) -> ParseResult

// 批量解析
pub fn parse_log_lines<I>(log_lines: I) -> Vec<ParseResult>
where
    I: IntoIterator,
    I::Item: AsRef<str>,

// 并行批量解析（需要开启parallel功能）
#[cfg(feature = "parallel")]
pub fn parse_log_lines_parallel<I>(log_lines: I) -> Vec<ParseResult>
where
    I: IntoIterator,
    I::Item: AsRef<str> + Send,
    I::IntoIter: Send,
```

### 核心类型

```rust
pub struct ParseResult {
    pub event: Option<PostfixLogEvent>,
    pub confidence: f32,
    pub parsing_errors: Vec<String>,
}

pub struct PostfixLogEvent {
    pub raw_log: String,
    pub timestamp: DateTime<Utc>,
    pub hostname: String,
    pub component: String,
    pub process_id: u32,
    pub log_level: PostfixLogLevel,
    pub event: ComponentEvent,
    pub queue_id: Option<String>,
}
```

## 📦 安装和编译

### 系统要求

- **Rust版本**: 1.70.0 或更高
- **操作系统**: Linux, macOS, Windows
- **架构**: x86_64, ARM64

### 从源码编译

```bash
# 克隆仓库
git clone https://github.com/your-username/PostfixLogParser.git
cd PostfixLogParser

# 开发模式编译
cargo build

# 发布模式编译（推荐）
cargo build --release

# 运行测试
cargo test

# 运行基准测试
cargo bench

# 运行示例
cargo run --example basic_usage
```

### 作为依赖使用

在您的 `Cargo.toml` 中添加：

```toml
[dependencies]
postfix-log-parser = "0.1.3"
```

或者使用 cargo 添加：

```bash
cargo add postfix-log-parser
```

### 功能特性

```toml
[dependencies]
postfix-log-parser = { version = "0.1.3", features = ["parallel"] }
```

可用特性：
- `parallel`: 启用并行处理支持
- `serde`: JSON序列化支持（默认启用）

## 🧪 测试

项目包含丰富的测试用例：

- **单元测试** - 各组件独立测试
- **集成测试** - 端到端功能测试
- **基准测试** - 性能回归检测
- **示例测试** - 各种日志格式验证

```bash
# 运行完整测试套件
cargo test --release

# 运行基准测试
cargo bench

# 测试示例日志解析
cargo run --release -- logs/test_sample.log
```

## 🤝 贡献指南

我们欢迎所有形式的贡献！请查看我们的贡献指南以了解如何参与：

### 报告问题
- 使用 GitHub Issues 报告bug
- 提供详细的错误信息和重现步骤
- 包含您的环境信息（操作系统、Rust版本等）

### 提交代码
- Fork 本仓库
- 创建特性分支 (`git checkout -b feature/amazing-feature`)
- 提交更改 (`git commit -m 'Add some amazing feature'`)
- 推送分支 (`git push origin feature/amazing-feature`)
- 创建 Pull Request

### 开发环境
```bash
# 安装依赖
cargo build

# 运行测试
cargo test

# 运行示例
cargo run --example basic_usage

# 格式化代码
cargo fmt

# 代码检查
cargo clippy
```

## 📜 许可证

本项目使用 MIT 或 Apache-2.0 双重许可证。

## 🙏 致谢

感谢所有为项目做出贡献的开发者和社区成员。

## 📞 联系方式

- GitHub Issues: [项目Issues页面](https://github.com/your-username/postfix-log-parser/issues)
- 文档: 查看项目文档目录

## 🔒 安全说明

我们重视项目的安全性。如果您发现了安全相关的问题，请通过GitHub Issues或私信联系我们进行负责任的披露。

## 📋 版本历史

### v0.1.3 (当前版本)
- ✅ 实现多个核心组件解析器 (SMTPD, QMGR, CLEANUP, SMTP, ERROR, LOCAL, VIRTUAL等)
- ✅ 高效的解析引擎
- ✅ 完整的JSON输出支持
- ✅ 并行处理支持（可选特性）
- ✅ 模块化架构设计

### 计划中的功能
- 更多组件支持和性能优化
- 实时流处理支持
- 更多输出格式

## ❓ 常见问题

### Q: 支持哪些Postfix版本？
A: 本解析器支持Postfix 2.x和3.x版本的日志格式。经过测试的版本包括2.11, 3.1, 3.4等。

### Q: 性能如何？
A: 项目经过性能优化，支持高效的日志解析。具体性能取决于硬件配置和日志复杂度。

### Q: 支持实时解析吗？
A: 当前版本主要针对文件解析优化。实时流处理支持计划在v0.3.0版本中提供。

### Q: 如何处理非标准日志格式？
A: 解析器设计时考虑了容错性，对于无法解析的行会返回错误信息和建议。您可以通过置信度字段判断解析质量。

### Q: 可以扩展新的组件吗？
A: 是的！项目采用模块化设计，可以轻松添加新的组件解析器。请参考现有组件的实现。

## 📚 文档

### 📖 使用指南
- **[🚀 快速上手指南](docs/QUICK_START.md)** - 5分钟开始使用
- **[📚 完整使用指南](docs/USAGE.md)** - 详细功能说明和示例
- **[📋 API参考文档](docs/API_REFERENCE.md)** - 完整API接口说明
- **[🎪 完整功能演示](demo_project/README.md)** - 实际运行的功能演示项目

### 💻 示例代码
- **[基础使用](examples/basic_usage.rs)** - 单行和批量解析示例
- **[高级用法](examples/advanced_usage.rs)** - 所有组件的详细使用方法
- **[并行处理](examples/parallel_processing.rs)** - 高性能批量处理示例
- **[文件处理](examples/file_processing.rs)** - 多种文件处理方式

### 🔧 开发者资源
- **[组件解析开发进度报告](组件解析开发进度报告.md)** - 详细开发进度
- **[发布指南](发布指南.md)** - 如何发布到crates.io

### 运行示例

```bash
# 快速体验基本功能
cargo run --example basic_usage

# 查看所有组件的使用方法
cargo run --example advanced_usage

# 高性能处理大量数据
cargo run --example parallel_processing --features parallel

# 处理实际日志文件
cargo run --example file_processing -- /path/to/your/mail.log
```