filepulse 0.1.0

文件监控与归档同步工具 — 轮询检测文件变化并自动同步，支持 zip 归档自动解压处理

filepulse — 文件监控与归档同步工具

轮询检测源文件变化并自动同步到目标位置，支持 zip 归档自动解压处理。

功能特性

• 📁 监控文件变化（时间戳、大小、哈希），自动同步到目标位置
• 📦 监控压缩包（zip），自动解压并分发到多个目标目录
• 🔀 支持扁平化复制（丢弃子目录，文件直达目标）
• 🪝 前后置钩子脚本（sync/archive 处理前后执行自定义逻辑）
• 💾 自动备份功能
• 🔄 可配置的检查间隔
• 📊 运行状态统计
• 🎯 支持简单和复杂映射配置

系统要求

• Python ≥ 3.10
• pip install 自动安装依赖 (tomli, tomli-w, click)

快速开始

1. 安装

pip install filepulse

2. 初始化

filepulse init    # 创建 config.toml, 日志和备份目录

3. 配置监控文件

编辑 config.toml：

[monitor]
interval = 2.0

[files]
"source/path/file.txt" = "target/path/file.txt"

4. 启动监控

# 文件同步
filepulse sync run config.toml              # 前台持续监控
filepulse sync run --daemon config.toml     # 后台运行
filepulse sync once config.toml             # 一次性同步

# 归档处理
filepulse archive run config.toml           # 前台持续扫描
filepulse archive run --daemon config.toml  # 后台运行
filepulse archive once config.toml          # 一次性处理
filepulse archive check config.toml         # 干跑：列出待处理 zip

# 守护进程管理
filepulse daemon status                      # 查看状态
filepulse daemon stop                        # 停止
filepulse daemon logs 50                     # 查看日志
filepulse daemon reload                      # 重载配置

命令参考

文件同步 (filepulse sync)

命令	说明
sync run <config>	前台持续监控
sync run --daemon <config>	后台持续监控
sync once <config>	一次性同步所有变更文件
sync check <FILE> <config>	检查单个文件状态
sync stats <config>	列出配置的文件映射

归档处理 (filepulse archive)

命令	说明
archive run <config>	前台持续扫描 zip
archive run --daemon <config>	后台持续扫描
archive once <config>	一次性处理待处理 zip
archive check <config>	干跑：列出待处理 zip

守护进程 (filepulse daemon)

命令	说明
daemon status	查看所有后台进程
daemon stop	停止所有后台进程
daemon logs [N]	查看最近 N 行日志
daemon reload	停止后重新启动

工具

filepulse clean               # 清理旧日志和备份
filepulse treasury-run        # 运行司库日报流程
filepulse --version           # 版本信息

Just 别名（可选）

如果安装了 Just，可使用快捷别名：

just daemon         # → filepulse sync run --daemon config.toml
just foreground     # → filepulse sync run config.toml
just status         # → filepulse daemon status
just stop           # → filepulse daemon stop
just logs           # → filepulse daemon logs 50

配置说明

文件同步配置

简单格式：

[files]
"源文件路径" = "目标文件路径"

详细格式（带钩子）：

[files.my_entry]
source = "/path/to/source.xlsx"
target = "/path/to/target.xlsx"
on_before_sync = ""   # 前置钩子脚本
on_after_sync = ""    # 后置钩子脚本

监控选项 ([monitor])：

• interval: 检查间隔（秒，默认 2.0）
• check_size: 检查文件大小变化（默认 true）
• check_mtime: 检查修改时间变化（默认 true）
• check_hash: 检查文件哈希变化（默认 false）
• create_backup: 同步前创建备份（默认 true）
• backup_dir: 备份文件目录（默认 "backup"）

归档处理配置

[archive_monitor]
interval = 10.0                    # 检查间隔（秒）
extract_temp = "/tmp/sync_extract" # 解压临时目录
base_dir = "/path/to/base"         # 源文件扫描根目录

[[archives]]
name = "任务名"
source_pattern = "inbox/通道-*/data-*.zip"  # glob 模式（相对于 base_dir）
target_dirs = ["/path/to/output1", "/path/to/output2"]  # 多目标（推荐）
flatten_targets = ["/path/to/output2"]  # 扁平化目标（丢弃子目录）
rename_to = ""                     # 解压后重命名顶层目录
archive_dir = "/path/to/processed" # 已处理 zip 归档位置
on_before_process = ""             # 前置钩子脚本
on_after_process = ""              # 后置钩子脚本

钩子环境变量

变量	文件同步	归档处理
MONITOR_TYPE	file_sync	archive
MONITOR_EVENT	before_sync / after_sync	before_process / after_process
MONITOR_SOURCE	源文件路径	zip 文件路径
MONITOR_TARGET	目标文件路径	目标目录
MONITOR_TASK	file_id	任务名
MONITOR_EXTRACTED	—	目标目录（仅后置钩子）

状态文件与路径

filepulse 遵循 XDG 规范存储运行时数据：

• 状态文件: ~/.local/share/filepulse/ (或 $XDG_DATA_HOME/filepulse/)
• 日志文件: ~/.cache/filepulse/ (或 $XDG_CACHE_HOME/filepulse/)
• PID 文件: ~/.local/share/filepulse/

可通过环境变量覆盖：FILEPULSE_DATA_DIR, FILEPULSE_CACHE_DIR

迁移指南

从旧 monitor.py 迁移：

旧	新
python monitor.py config.toml --foreground	filepulse sync run config.toml
python monitor.py config.toml --daemon	filepulse sync run --daemon config.toml
python monitor.py config.toml --sync-all	filepulse sync once config.toml
python monitor.py config.toml --check <F>	filepulse sync check <F> config.toml
python monitor.py config.toml --stats	filepulse sync stats config.toml
python monitor.py config.toml --archive-foreground	filepulse archive run config.toml
python monitor.py config.toml --archive-daemon	filepulse archive run --daemon config.toml
python monitor.py config.toml --archive-sync	filepulse archive once config.toml
python monitor.py config.toml --archive-check	filepulse archive check config.toml

配置文件 100% 向后兼容。

故障排除

• 导入错误 → pip install filepulse 会自动安装依赖
• 文件未同步 → filepulse daemon logs 50 查看日志
• 归档 zip 未处理 → filepulse archive check config.toml 干跑
• 前台调试 → filepulse archive run config.toml 前台运行查看实时输出