logViewer/README-zh.md

logViewer

English

用 Rust 构建的高性能终端日志查看器，专为处理超大日志文件（GB 级别）而设计，内存占用极低。

基于 mmap 内存映射、稀疏行索引和后台渐进式加载，打开文件几乎瞬时完成——即使是 5GB 以上的日志文件，也能在索引完成前就开始滚动浏览。

特性

• 瞬时打开 — mmap 读取 + 后台渐进式索引，索引未完成即可开始浏览
• 超大文件支持 — 稀疏行索引（每 256 行采样一次），5GB 文件仅占用约 8MB 内存
• 实时文件追踪 — 通过 notify 监控文件追加、截断和日志轮转
• JSON 日志解析 — 支持 NDJSON 格式，自动处理 BOM、检测重复键，可切换格式化显示
• Unicode 感知的换行 — 正确处理中文、emoji 和制表符的行宽计算
• 持久化索引缓存 — 行索引保存到磁盘，使用 xxh3 哈希校验内容变更，再次打开几乎无需等待
• Vim 风格快捷键 — 终端用户无学习成本
• 可自定义配色 — 每个日志级别独立配色，通过 TOML 配置文件管理，TUI 内直接调整

快速开始

# 直接编译运行
cargo run -p log-viewer-tui -- path/to/logfile.log

# 或先编译再运行
cargo build --release -p log-viewer-tui
./target/release/log-viewer-tui path/to/logfile.log

需要 Rust 1.92 及以上版本（见 rust-toolchain.toml）。

快捷键

按键	操作
j / ↓	向下滚动一行
k / ↑	向上滚动一行
Ctrl+d	向下滚动半页
Ctrl+u	向上滚动半页
Ctrl+f / PgDn	向下滚动一页
Ctrl+b / PgUp	向上滚动一页
G / End	跳转到文件末尾
gg / Home	跳转到文件开头
Tab	切换 JSON 格式化显示
S	打开配色设置
q / Esc	退出

设置面板：j/k 选择日志级别，←/→ 切换颜色，Enter 保存，Esc 取消。

项目结构

crates/core  — 核心库：I/O、解析、数据类型、配置、文件监控
crates/tui   — 终端界面（ratatui + crossterm）
crates/gui   — 图形界面（egui + eframe）— 占位模块，尚未实现
crates/bench — mmap 与 pread 性能对比基准测试

开发

# 检查、测试、代码规范
cargo check --workspace
cargo test --workspace
cargo fmt --check --all
cargo clippy --workspace -- -D warnings

# 运行基准测试（首次运行会生成约 5GB 测试文件）
cargo run -p log-viewer-bench
cargo run -p log-viewer-bench -- --quick --suites startup,render --output results.md

# 单独测试某个 crate
cargo test -p log-viewer-core
cargo test -p log-viewer-tui

CI

CI 在 ubuntu-latest 和 windows-latest 上运行以下检查：

1. cargo fmt --check --all
2. cargo check --workspace
3. cargo test --workspace
4. cargo clippy --workspace -- -D warnings

无自定义 rustfmt 或 clippy 配置——使用工具链默认值。

架构

核心库 log-viewer-core 负责所有 I/O、解析和数据类型。关键设计决策：

• 稀疏行索引 — 每 256 行采样一次，使用 memchr SIMD 加速。100 万行的文件仅产生约 32KB 的索引，而非 8MB。
• 渐进式加载 — ProgressiveFileReader 先读取文件头尾进行快速行数估算，再通过 crossbeam-channel 在后台线程构建完整索引。
• mmap 与 TOCTOU 防护 — mmap 映射后进行 stat 校验以检测文件变更。read_cache 模块为未来基于 pread 的实现预留，可彻底消除 SIGBUS 风险。
• 持久化缓存 — 行索引序列化到磁盘，使用 xxh3 内容哈希进行失效校验，通过临时文件实现原子写入。
• 视觉高度索引 — 基于换行后行高的前缀和数组，支持 O(log n) 的滚动定位，适用于长行换行场景。

计划中但尚未实现的功能：过滤、书签、会话管理、搜索引擎（stub 模块已创建）。

基准测试

自研基准测试框架，对比 mmap 与 pread 两种后端在 7 个测试场景（启动、渲染、跳转、内存、增长、轮转、并发）下的表现。使用挂钟计时和 /proc/self/ 的 RSS 及页错误指标。结果以 Markdown 表格形式输出到 benchmark-report.md。

基准测试二进制包含约 75 个单元测试，覆盖读取器后端和指标采集逻辑。