gtunesdev/fspulse

fsPulse

镜像概述和主要用途

fsPulse是一款全面的文件系统监控与完整性工具，为关键目录提供完整可见性。它能跟踪数据随时间的增长和变化，检测意外修改，并在数据腐败（如位衰减）演变成灾难前及时发现。通过自动扫描、历史趋势分析和专门的完整性视图，fsPulse提供持续的数据状态感知。

文件系统不断演变——文件被添加、修改和删除，存储不断增长。但表面下隐藏着"无形问题"：位衰减悄无声息地损坏数据，勒索软件在保留时间戳的同时修改文件，目录膨胀而用户未察觉。fsPulse让用户同时感知可见和不可见的变化。

核心功能和特性

监控变化与增长

• 跟踪目录大小及随时间的增长趋势
• 可视化文件的添加、修改和删除
• 了解所有扫描中的变更内容和时间

检测完整性问题

• 内容哈希（SHA2）：即使元数据不变，也能捕获文件内容变化——这是位衰减或篡改的特征
• 格式验证：读取并验证文件结构，检测FLAC、JPEG、PNG、PDF等格式的腐败

关键能力

• 健康概览：立即查看所有受监控目录的状态：完整性问题、上次扫描时间和整体健康状况
• 持续监控：安排定期扫描（每日、每周、每月或自定义间隔）自动跟踪文件系统
• 时间版本控制：跟踪每个项目随时间的状态；可浏览过去任何扫描时的文件系统状态
• 大小与增长跟踪：监控目录大小并通过双格式单位可视化存储趋势
• 变更检测：通过版本历史跟踪所有文件的添加、修改和删除
• 完整性管理：专门的"完整性"页面显示可疑哈希和验证失败，并带有审核跟踪
• 历史趋势：交互式趋势图表展示数据演变：大小、数量、变更和完整性指标
• 强大查询语言：类SQL语法，用于跨四个数据域的过滤、排序和分析
• Web优先设计：优雅的Web UI支持所有操作，包括扫描、浏览、查询和配置

使用场景和适用范围

• 存储容量管理：监控目录大小和增长趋势，避免存储空间意外耗尽
• 项目变更跟踪：跟踪文件添加、修改和删除，了解项目随时间的演变
• 数据完整性保障：检测位衰减、文件腐败和潜在篡改，确保关键数据可靠性
• 系统审计：记录文件系统变更历史，满足合规性和审计需求
• 个人数据保护：监控重要文档、媒体文件等个人数据的完整性和变更

详细的使用方法和配置说明

Docker快速启动

sh
docker run -d \
  --name fspulse \
  -p 8080:8080 \
  -v fspulse-data:/data \
  -v ~/Documents:/roots/documents:ro \
  gtunesdev/fspulse:latest

访问Web UI：http://localhost:8080

参数说明

• -p 8080:8080：映射Web UI端口
• -v fspulse-data:/data：持久化存储fsPulse数据库、配置和日志
• -v ~/Documents:/roots/documents:ro：以只读方式挂载要监控的目录（:ro确保fsPulse无法修改源文件）

Docker Compose配置示例

yaml
version: '3'
services:
  fspulse:
    image: gtunesdev/fspulse:latest
    container_name: fspulse
    ports:
      - "8080:8080"
    volumes:
      - fspulse-data:/data
      - /path/to/important/docs:/roots/docs:ro
      - /path/to/media/files:/roots/media:ro
    restart: unless-stopped
    environment:
      - FSPULSE_SERVER_PORT=8080
      - FSPULSE_LOGGING_FSPULSE=info

volumes:
  fspulse-data:

配置选项

fsPulse可通过环境变量或配置文件进行配置：

示例：修改端口和启用调试日志

sh
docker run -d \
  --name fspulse \
  -p 9090:9090 \
  -v fspulse-data:/data \
  -e FSPULSE_SERVER_PORT=9090 \
  -e FSPULSE_LOGGING_FSPULSE=debug \
  gtunesdev/fspulse:latest

运行fsPulse

启动fsPulse服务器：

sh
fspulse

或显式启动：

sh
fspulse serve

在浏览器中打开**[***] UI操作：

• 健康概览，显示根目录状态和完整性摘要
• 配置和管理扫描根目录及计划
• 实时监控任务进度
• 通过树形、文件夹和搜索视图浏览文件系统
• 按完整性状态过滤：哈希状态、验证状态和变更类型
• 在"完整性"页面审核可疑哈希和验证失败
• 查看时间点快照并跨扫描比较
• 跨四个数据域查询和探索数据

界面亮点

界面分为两个导航组——日常使用的主要页面和配置及高级分析的工具页面：

主要页面

• 首页：健康概览，显示根目录状态、活动任务、最近活动及完整性摘要
• 浏览：通过树形、文件夹和搜索视图导航文件系统，提供完整性过滤、内联详情面板和跨扫描/根目录的并排比较
• 完整性：审核可疑哈希和验证失败，可按问题类型、文件类型和审核状态过滤
• 趋势：交互式图表跟踪文件大小、数量、变更活动和完整性指标随时间的变化

工具页面

• 历史：完整的扫描和任务活动日志，支持过滤
• 根目录：添加、删除和扫描受监控目录
• 计划：创建和管理自动扫描计划
• 数据资源管理器：可视化查询构建器和跨四个数据域的自由格式查询界面
• 设置：编辑配置，查看数据库统计信息和系统信息

重要保障

• 只读保证：fsPulse从不修改文件。仅需要对配置为扫描的目录的读访问权限。写访问仅用于fsPulse自己的数据库、配置文件和日志——绝不会用于用户数据。
• 本地运行保证：fsPulse不进行出站网络请求。所有功能完全在本地系统运行，无外部依赖或遥测。

安装选项

除Docker外，fsPulse还可通过以下方式安装：

Cargo (crates.io)

sh
cargo install fspulse

需在系统上安装Rust工具链。

预编译二进制

从https://github.com/gtunes-dev/fspulse/releases%E4%B8%8B%E8%BD%BD%E7%89%B9%E5%AE%9A%E5%B9%B3%E5%8F%B0%E7%9A%84%E4%BA%8C%E8%BF%9B%E5%88%B6%E6%96%87%E4%BB%B6%EF%BC%8C%E6%94%AF%E6%8C%81Linux%E3%80%81macOS%E5%92%8CWindows%E3%80%82macOS%E6%9E%84%E5%BB%BA%E5%8C%85%E5%90%ABIntel%EF%BC%88x86_64%EF%BC%89%E5%92%8CApple Silicon（ARM64）二进制文件。

从源码构建

sh
git clone https://github.com/gtunes-dev/fspulse.git
cd fspulse
./scripts/build.sh
./target/release/fspulse --help

前提条件：需安装Node.js（带npm）和Rust（通过rustup）。

注意事项

• 实验性MCP支持：fsPulse现在包含内置的Model Context Protocol服务器，允许Claude Desktop和Claude Code等AI助手查询文件系统数据、探索扫描历史并通过自然对话调查完整性问题。
• 早期开发通知：fsPulse正在积极开发中，尚未功能完整。核心功能稳定，但预计会持续演进并偶尔出现破坏性变更。欢迎反馈和问题报告，以帮助我们推进1.0版本发布。

获取帮助

• 报告问题：https://github.com/gtunes-dev/fspulse/issues
• 文档：https://gtunes-dev.github.io/fspulse/
• Docker Hub：https://hub.docker.com/r/gtunesdev/fspulse

许可证

采用MIT许可证发布。详情参见LICENSE。