# file-watcher

**Repository Path**: jclProject/file-watcher

## Basic Information

- **Project Name**: file-watcher
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-26
- **Last Updated**: 2025-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# File Watcher - 邮件文件监控系统

一个基于 Spring Boot 的邮件文件监控系统，专门用于监控 Maildir 格式的邮件目录，支持邮件内容解码、附件自动下载、多目录监控等功能。

## 功能特性

- 📧 **邮件文件监控**: 专门监控 Maildir 格式的邮件目录，实时检测新邮件
- 🔓 **邮件内容解码**: 支持 Base64、Quoted-Printable 等多种编码格式的邮件内容解码
- 📎 **附件自动下载**: 自动检测、解码并下载邮件中的 Base64 编码附件到本地目录
- 🗂️ **多目录监控**: 支持同时监控多个邮件目录，灵活配置监控策略
- 📡 **Webhook 通知**: 检测到新邮件时自动发送通知到指定的 Webhook 地址
- 💾 **Redis 缓存**: 使用 Redis 缓存邮件处理状态和 UID 映射，支持 30 天过期时间配置
- 🗄️ **MyBatis-Plus 集成**: 使用 MyBatis-Plus 进行数据库操作，支持代码生成和 CRUD
- 🐋 **Doveadm 集成**: 集成 Doveadm 命令行工具，支持邮件服务器操作
- 🔧 **RESTful API**: 提供完整的 API 接口，支持状态查询、手动检查等操作
- 📊 **健康检查**: 内置健康检查端点，支持容器编排和监控

## 技术栈

- **Java 8**
- **Spring Boot 2.7.18**
- **Spring Data JPA**
- **Spring Data Redis**
- **MyBatis-Plus 3.5.3.1**
- **MySQL 8.0**
- **Redis 7.x**
- **Apache Commons IO**
- **Apache HttpClient**
- **Lombok**
- **Maven**

## 项目结构

```
file_watcher/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/filewatcher/
│   │   │       ├── FileWatcherApplication.java      # 主应用类
│   │   │       ├── config/
│   │   │       │   ├── AppConfig.java               # 应用配置
│   │   │       │   └── RedisConfig.java             # Redis配置
│   │   │       ├── controller/
│   │   │       │   └── FileWatcherController.java   # REST控制器
│   │   │       ├── entity/
│   │   │       │   ├── MailContentInfo.java         # 邮件内容信息实体
│   │   │       │   ├── MaildirFileInfo.java         # Maildir文件信息实体
│   │   │       │   ├── MatchResult.java             # 匹配结果实体
│   │   │       │   └── RuEsignHoldingLink.java      # 数据库实体
│   │   │       ├── mapper/
│   │   │       │   └── RuEsignHoldingLinkMapper.java # MyBatis-Plus映射器
│   │   │       ├── service/
│   │   │       │   ├── DoveadmService.java           # Doveadm邮件服务
│   │   │       │   ├── FileWatcherService.java      # 文件监控服务
│   │   │       │   ├── RuEsignHoldingLinkService.java # 数据库服务接口
│   │   │       │   ├── WebhookService.java          # Webhook服务
│   │   │       │   └── impl/
│   │   │       │       └── RuEsignHoldingLinkServiceImpl.java # 服务实现
│   │   │       └── util/
│   │   │           ├── MailContentDecoder.java      # 邮件内容解码工具
│   │   │           └── MailFileMatcherUtil.java     # 邮件文件匹配工具
│   │   └── resources/
│   │       └── application.yml                      # 应用配置文件
│   └── test/
│       └── java/                                    # 测试代码
├── docs/
│   ├── mailcow-integration.md                       # Mailcow集成文档
│   └── multi-directory-monitoring.md               # 多目录监控文档
├── logs/                                            # 日志目录
├── temp/                                            # 临时文件目录
├── target/
│   └── file-watcher-1.0.0.jar                      # 构建产物
├── Dockerfile                                       # Docker镜像构建文件
├── init.sql                                         # 数据库初始化脚本
├── pom.xml                                          # Maven配置文件
└── README.md                                        # 项目说明文档
```

## 快速开始

### 方式一：使用 Docker Compose（推荐）

1. **克隆项目**

   ```bash
   git clone <repository-url>
   cd file_watcher
   ```

2. **创建监控目录**

   ```bash
   mkdir watch-directory
   mkdir logs
   ```

3. **构建并启动服务**

   ```bash
   # 构建应用
   mvn clean package -DskipTests

   # 启动所有服务
   docker-compose up -d
   ```

4. **验证服务状态**

   ```bash
   # 检查服务状态
   docker-compose ps

   # 查看应用日志
   docker-compose logs -f file-watcher
   ```

### 方式二：本地开发环境

1. **环境要求**

   - Java 8+
   - Maven 3.6+
   - MySQL 8.0
   - Redis 7.x

2. **数据库准备**

   ```sql
   CREATE DATABASE file_watcher;
   -- 执行 init.sql 中的脚本
   ```

3. **配置文件**
   修改 `src/main/resources/application.yml` 中的数据库和 Redis 连接信息

4. **启动应用**
   ```bash
   mvn spring-boot:run
   ```

## 部署说明

### 1. 环境要求

- Java 8+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+
- Docker（可选，用于 Doveadm 集成）

### 2. 编译打包

```bash
mvn clean package -DskipTests
```

### 3. 配置文件

修改 `application.yml` 中的配置项：

```yaml
# 数据库配置
spring:
  datasource:
    url: jdbc:mysql://your-mysql-host:3306/file_watcher
    username: your-username
    password: your-password

  # Redis配置
  redis:
    host: your-redis-host
    port: 6379
    password: your-redis-password

# 邮件监控配置
file:
  watcher:
    watch-directories:
      - /path/to/maildir/cur
    webhook-url: "http://your-webhook-url"

# Doveadm配置
mail:
  dovecot:
    container-name: your-dovecot-container
    email-user: user@domain.com
```

### 4. 数据库初始化

创建数据库和表结构：

```sql
CREATE DATABASE file_watcher;
USE file_watcher;

-- 表结构会通过JPA自动创建
```

### 5. 运行应用

#### 方式一：直接运行 JAR 包

```bash
java -jar target/file-watcher-1.0.0.jar
```

#### 方式二：使用 Docker

```bash
# 构建镜像
docker build -t file-watcher .

# 运行容器
docker run -d \
  --name file-watcher \
  -p 8080:8080 \
  -v /path/to/maildir:/maildir \
  -v /path/to/attachments:/app/attachments \
  file-watcher
```

#### 方式三：使用 Maven 运行

```bash
mvn spring-boot:run
```

### 6. 验证部署

访问健康检查接口确认服务正常：

```bash
curl http://localhost:8080/api/file-watcher/health
```

## 配置说明

### 主要配置项

在 `application.yml` 中可以配置以下参数：

```yaml
# 文件监控配置
file:
  watcher:
    # 多目录监控配置（推荐）
    watch-directories:
      - /var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data/xxxxxx/xxxxxxx/Maildir/cur
    # 单目录监控配置（兼容性）
    watch-directory: /path/to/single/directory
    # 检查间隔（秒）
    check-interval: 5
    # Webhook通知地址
    webhook-url: "http://example.com/webhook"
    # 连接超时时间（毫秒）
    connection-timeout: 5000
    # 读取超时时间（毫秒）
    read-timeout: 10000
    # 是否启用多目录监控模式
    multi-directory-mode: true

# 邮件处理配置
mail:
  dovecot:
    # Dovecot容器名称
    container-name: mailcowdockerized-dovecot-mailcow-1
    # 邮件用户
    email-user: user@domain.com
    # 命令执行超时时间（秒）
    command-timeout: 30
    # 重试次数
    retry-count: 3
    # 重试间隔（毫秒）
    retry-interval: 1000

# Redis缓存配置
spring:
  redis:
    host: localhost
    port: 6379
    password: your-password
    database: 0
    # 缓存过期时间（秒）- 30天
    expiration: 2592000
```

### 环境变量

Docker 部署时可以通过环境变量覆盖配置：

- `SPRING_DATASOURCE_URL`: 数据库连接 URL
- `SPRING_DATASOURCE_USERNAME`: 数据库用户名
- `SPRING_DATASOURCE_PASSWORD`: 数据库密码
- `SPRING_REDIS_HOST`: Redis 主机地址
- `SPRING_REDIS_PORT`: Redis 端口
- `FILE_WATCHER_WATCH_DIRECTORY`: 监控目录路径
- `FILE_WATCHER_WEBHOOK_URL`: Webhook 地址

## API 接口

### 1. 获取监控状态

```http
GET /api/file-watcher/status
```

响应示例：

```json
{
  "current_file_count": 15,
  "last_file_count": 12,
  "webhook_url": "http://xxxxxxxxx/api/mailcow/wehook",
  "status": "running",
  "timestamp": 1640995200000,
  "multi_directory_mode": true,
  "monitored_directories": [
    "/var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data/xxxxxxxx/xxxxxxxxx/Maildir/cur"
  ]
}
```

### 2. 手动触发检查

```http
POST /api/file-watcher/check
```

### 3. 处理指定邮件文件

```http
POST /api/file-watcher/process-mail
Content-Type: application/json

{
  "filename": "1640995200.M123456P789.hostname,S=1234,W=5678:2,S",
  "directory": "/path/to/maildir/cur"
}
```

### 4. 获取邮件内容

```http
GET /api/file-watcher/mail-content/{filename}
```

响应示例：

```json
{
  "filename": "mail_file.eml",
  "decoded_content": "[已解码的邮件内容]\n\n邮件正文...",
  "attachments": [
    {
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "downloaded": true,
      "download_path": "./document.pdf"
    }
  ],
  "processing_time": 1234
}
```

### 5. 测试 Webhook 连接

```http
POST /api/file-watcher/test-webhook
```

### 6. 健康检查

```http
GET /api/file-watcher/health
```

### 7. 获取处理统计

```http
GET /api/file-watcher/stats
```

响应示例：

```json
{
  "total_processed": 150,
  "total_attachments_downloaded": 45,
  "cache_hit_rate": 0.85,
  "last_processing_time": 1640995200000
}
```

## Webhook 数据格式

### 1. 新邮件检测通知

当检测到新邮件时，系统会向配置的 Webhook 地址发送 POST 请求：

```json
{
  "event": "new_mail_detected",
  "directory": "/var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data/xxxxxxx/xxxxxxxx/Maildir/cur",
  "filename": "1640995200.M123456P789.hostname,S=1234,W=5678:2,S",
  "mail_info": {
    "uid": "123456",
    "timestamp": 1640995200,
    "size": 1234,
    "hostname": "hostname"
  },
  "processing_status": "success",
  "decoded_content_preview": "邮件内容预览...",
  "attachments_count": 2,
  "timestamp": 1640995200000,
  "service": "file-watcher"
}
```

### 2. 附件下载通知

当成功下载邮件附件时发送的通知：

```json
{
  "event": "attachment_downloaded",
  "mail_filename": "1640995200.M123456P789.hostname,S=1234,W=5678:2,S",
  "attachment": {
    "filename": "document.pdf",
    "content_type": "application/pdf",
    "size": 2048576,
    "download_path": "./document.pdf"
  },
  "timestamp": 1640995200000,
  "service": "file-watcher"
}
```

### 3. 文件数量变化通知（兼容性）

传统的文件数量变化通知：

```json
{
  "event": "file_count_changed",
  "directory": "/path/to/watch",
  "previous_count": 12,
  "current_count": 15,
  "change_type": "INCREASE",
  "timestamp": 1640995200000,
  "service": "file-watcher"
}
```

## 监控和日志

### 应用日志

- 容器内日志路径: `/app/logs/`
- 主机挂载路径: `./logs/`

### 数据库日志

系统会在以下表中记录监控数据：

- `file_monitor_log`: 文件变化记录
- `webhook_log`: Webhook 发送记录
- `system_config`: 系统配置

### 健康检查

- 应用健康检查: `http://localhost:8080/api/file-watcher/health`
- Spring Boot Actuator: `http://localhost:8080/actuator/health`

## 部署建议

### 生产环境部署

1. **资源配置**

   ```yaml
   # docker-compose.yml 中调整资源限制
   deploy:
     resources:
       limits:
         memory: 512M
         cpus: "0.5"
   ```

2. **数据持久化**

   - MySQL 数据: 使用命名卷或绑定挂载
   - Redis 数据: 启用 AOF 持久化
   - 应用日志: 挂载到主机目录

3. **安全配置**
   - 修改默认数据库密码
   - 配置防火墙规则
   - 使用 HTTPS（如果需要）

### 扩展性考虑

- **多目录监控**: 可以部署多个实例监控不同目录
- **负载均衡**: 使用 Nginx 或其他负载均衡器
- **集群部署**: Redis 和 MySQL 可以配置为集群模式

## 开发说明

### 1. 项目结构说明

- `config/`: 配置类，包含 Redis 配置等
- `controller/`: REST API 控制器
- `entity/`: JPA 实体类，对应数据库表
- `mapper/`: MyBatis-Plus 数据访问层
- `service/`: 业务逻辑层，包含文件监控、邮件处理等核心功能
- `util/`: 工具类，包含邮件解码、文件匹配等工具

### 2. 核心组件

- **FileWatcherService**: 文件监控核心服务，支持多目录监控
- **MailContentDecoder**: 邮件内容解码工具，支持 Base64、Quoted-Printable 等编码
- **MailFileMatcherUtil**: 邮件文件匹配工具，用于 Maildir 文件名与邮件内容的匹配
- **DoveadmService**: Doveadm 邮件服务集成，用于获取邮件内容

### 3. 缓存策略

- 使用 Redis 缓存邮件 UID，避免重复处理
- 缓存过期时间：30 天（2592000 秒）
- 支持缓存命中率统计

### 4. 监控模式

- **多目录模式**：支持同时监控多个 Maildir 目录
- **单目录模式**：兼容性模式，监控单个目录
- **定时检查**：可配置检查间隔（默认 5 秒）

## 注意事项

1. **权限配置**

   - 确保应用对监控目录具有读取权限
   - 确保应用对附件下载目录具有写入权限
   - Docker 环境下需要正确配置卷挂载

2. **网络配置**

   - Webhook 地址必须可访问
   - Redis 和 MySQL 服务器必须可连接
   - Docker 容器间网络配置正确

3. **性能优化**

   - 合理配置检查间隔，避免过于频繁的文件系统访问
   - 监控 Redis 内存使用情况
   - 定期清理下载的附件文件

4. **日志管理**

   - 建议在生产环境中配置适当的日志级别
   - 定期检查磁盘空间，避免日志文件过大
   - 可通过 `/logs` 目录查看应用日志

5. **安全考虑**
   - 保护数据库和 Redis 连接密码
   - 限制 API 接口的访问权限
   - 定期更新依赖包版本

## 故障排除

### 常见问题

1. **邮件文件无法读取**

   - 检查文件路径和权限
   - 确认 Maildir 格式正确

2. **Redis 连接失败**

   - 检查 Redis 服务状态
   - 验证连接配置和密码

3. **Doveadm 命令执行失败**

   - 确认 Docker 容器名称正确
   - 检查容器是否运行
   - 验证邮件用户配置

4. **附件下载失败**
   - 检查目录写入权限
   - 确认 Base64 编码格式正确
   - 查看详细错误日志

### 日志查看

```bash
# 查看应用日志
docker-compose logs -f file-watcher

# 查看数据库日志
docker-compose logs -f mysql

# 查看Redis日志
docker-compose logs -f redis
```

## 开发指南

### 本地开发

1. **IDE 配置**

   - 导入 Maven 项目
   - 配置 Java 8 SDK
   - 安装 Lombok 插件

2. **代码规范**

   - 使用统一的代码格式
   - 添加必要的注释
   - 编写单元测试

3. **调试技巧**
   - 使用 IDE 断点调试
   - 查看 Redis 中的缓存数据
   - 监控数据库表变化

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue: [GitHub Issues](https://github.com/your-repo/file-watcher/issues)
- 邮箱: your-email@example.com

---

**注意**: 请根据实际部署环境调整配置参数，确保系统安全和稳定运行。