inklog 0.3.0-rc.4

中文 | English

企业级 Rust 日志基础设施

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

⚡ 结构化日志，安全内建

一条日志从采集、脱敏、加密到多端落盘，全链路可控：

📋 目录

• ✨ 功能特性
• 🚀 快速开始
• 🎨 特性标志
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

✨ 功能特性

inklog 是面向生产环境的日志基础设施：应用代码继续使用 log / tracing 标准宏，由 inklog 接管订阅、脱敏、分发与落盘。下表为主要能力，全部与仓库代码和 docs/ 文档对应。

• Sink 家族（src/support/io/sink/）：console、file（轮转/压缩/加密）、database（批量/分区/断路器）、ring_buffered_file（通道缓冲高吞吐）、net（TCP 可 TLS + UDP）、otlp、middleware、sampling、rate_limit
• 处理层（src/support/processing/）：template 模板引擎、masking 脱敏引擎与规则注册表、object_pool LogRecord/字符串对象池
• 可观测性（src/support/observability/）：Metrics、HealthStatus、SinkHealthMonitor、回退状态
• 校验（src/validation/）：PathValidator 路径穿越防护、LogSanitizer 日志内容净化
• 归档防篡改（src/support/audit_chain.rs）：归档 HMAC-SHA256 链，防删除、重排与伪造
• 集成适配（src/integrations/）：OxCacheAdapter、InklogConfigAdapter、DbNexusAdapter、trait-kit InklogModule、dbnexus 审计桥、confers 配置与 watch
• CLI（src/cli/）：decrypt、generate、validate、query 四个子命令

🚀 快速开始

环境要求

安装

cargo add inklog

或在 Cargo.toml 中显式声明（default = []，默认仅启用核心能力）：

[dependencies]
inklog = "0.3.0-rc.3"

最小可运行示例

出自 examples/src/bin/core/basic.rs：

use inklog::LoggerManager;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 默认配置初始化并安装全局 subscriber（Console Sink，级别 info）
    let logger = LoggerManager::new().await?;

    tracing::info!("Hello, inklog!");
    tracing::info!(user_id = 42, action = "login", "结构化字段示例");

    // 退出前排空通道并关闭全部 Sink
    logger.shutdown()?;
    std::mem::forget(logger); // 已显式关闭，阻止 Drop 重复关闭
    Ok(())
}

核心概念

1. 初始化：LoggerManager 负责安装全局 tracing subscriber 与 log crate 前端，进程内单例语义（init_inklog_logger() 提供便捷入口）。
2. 记录：业务代码使用 tracing::info! 等标准宏，无侵入。
3. Sink：输出目标抽象（LogSink / AsyncSink trait），console / file / database / net / otlp 内置实现，可自定义。
4. 配置：InklogConfig 支持 TOML 文件与 INKLOG_* 环境变量覆盖，优先级为环境变量 > 配置文件 > 默认值。
5. 关闭：应用退出前调用 shutdown()，等待通道中剩余日志全部写入。

🎨 特性标志

default = []：默认组合只包含核心能力，下列 feature 全部按需显式启用（依据 Cargo.toml [features] 定义）。

⚠️ 数据库后端互斥：sqlite / postgres / mysql / duckdb 互斥（经 dbnexus 强制，embedded 与 server-side 驱动不得混用），不适用 --all-features，请按后端分组启用。

📚 文档

💻 示例

examples/ 是 workspace 内的独立 crate（inklog-examples），按目录分为 7 类共 39 个示例。在仓库根目录运行：

cargo run --package inklog-examples --example <名称>

配置（config）

核心（core）

Sink 与输出（sinks）

数据库（database）

基础设施（infra）

网络（network）

安全（security）

📂 浏览全部示例 →

🏗️ 架构

inklog 采用分层异步架构：domain（管理器、Subscriber 与工作线程）经 support::processing 完成模板渲染与脱敏后进入 Crossbeam 有界通道，由专用线程分发给 support::io::sink 各 Sink；integrations 以 trait 适配 oxcache / confers / dbnexus / trait-kit，support::observability 经 http feature 暴露健康与指标端点。分层架构图、分层职责表与模块树对照见 docs/ARCHITECTURE.md「分层架构」。

🔀 核心执行链路

一条日志从 tracing 标准宏记录、脱敏、非阻塞进入有界通道（满时背压）到文件 / 数据库 Sink 落盘并回写指标的完整时序图，以及关键要点（默认通道容量 10000、3 个工作线程，可经 PerformanceConfig 调整；加密、压缩与轮转按轮转文件触发，不占用单条记录写入热路径），见 docs/ARCHITECTURE.md「核心执行链路」。

🧯 故障降级与自愈

Sink 写入失败经断路器（默认失败阈值 5 次、冷却 30 秒）重试或触发 DB → File → Console 三级降级，健康检查线程每 10 秒巡检并自动重建不健康 Sink、重置断路器。完整流程图见 docs/ARCHITECTURE.md「故障降级与自愈」。

🧪 测试

测试策略

测试规模（截至 v0.3.0-rc.3，按 #[test] / #[tokio::test] 统计）：src/ 内联 1,255 个 + tests/ 目录 528 个，共 1,783 个测试函数；另有 criterion 基准函数 18 个（benches/inklog_bench.rs 15 个、benches/rc4_pipeline_bench.rs 3 个）。

运行命令（与 CI 一致）

# CI 测试门禁（数据库后端互斥，不适用 --all-features）
cargo test --workspace --features "sqlite http cli kit compression gzip parquet fast-masking test-utils"

# Docker 数据库集成测试
docker compose -f docker/docker-compose.test.yml up -d

# 覆盖率门禁（CI 要求 ≥80% 行覆盖）
cargo llvm-cov --features "sqlite http cli kit compression gzip parquet fast-masking" --lib --fail-under-lines 80

# 基准测试
cargo bench --bench rc4_pipeline_bench
cargo bench --bench inklog_bench

本地化提示：错误消息经 ICU/Fluent 按系统 locale 渲染。若测试断言英文消息文本，请设置 INKLOG_LOCALE=en（如 CI 或非英文系统环境）以固定输出语言。

代码质量门禁

cargo fmt --all -- --check                    # 格式检查
cargo clippy --all-targets --features "sqlite http cli kit compression gzip parquet fast-masking" -- -D warnings  # 零告警
cargo deny check                              # 依赖漏洞 / 许可证 / 重复依赖
cargo audit                                   # 安全公告（lefthook pre-push）

📊 性能

基线数字

首份正式基线（2026-09-11，criterion 中位数，覆盖写入 / 序列化 / 加密三条路径）的完整数字、环境口径与「复现」步骤见 docs/PERFORMANCE.md。

设计要点

复现方式见 docs/PERFORMANCE.md「复现」章节。

🔒 安全

漏洞报告

发现安全漏洞请不要公开披露，按 docs/SECURITY.md 流程负责任上报：

• 首选：邮件 security@inklog.dev
• 备选：GitHub Security Advisories
• 响应时限与协调披露流程：见 docs/SECURITY.md「漏洞报告流程」。

安全设计

静态加密（AES-256-GCM）、密钥派生与内存清零、路径与内容防护、SQL 注入防护、HTTP 访问控制、归档防篡改链，以及对 GDPR / HIPAA / PCI-DSS 的合规映射，逐项说明见 docs/SECURITY.md「安全设计概览」。

供应链安全

仓库维护 deny.toml；cargo deny check（漏洞 / 许可证 / 重复依赖）、cargo audit（RustSec 公告）与 pre-commit 私钥扫描的运行位置与口径见 docs/SECURITY.md「安全设计概览」。

🗺️ 开发路线图

以下为既有发布安排整理的阶段性目标（节奏随工作区整体发布计划调整）：

🤝 参与贡献

欢迎贡献！完整流程见 docs/CONTRIBUTING.md。

开发环境

git clone https://github.com/Kirky-X/inklog.git
cd inklog
bash scripts/install-pre-commit.sh

# 运行测试（与 CI 相同的 feature 组合）
cargo test --workspace --features "sqlite http cli kit compression gzip parquet fast-masking test-utils"

提交约定

• Conventional Commits：feat: ... / fix: ... / docs: ... 等，commit-msg 钩子强制校验；
• pre-commit 钩子：rustfmt、clippy（-D warnings 零告警）、cargo deny check、私钥扫描；
• pre-push 钩子：cargo audit 与覆盖率 ≥80% 门禁。

Pull Request 流程

1. Fork 仓库并创建功能分支（git checkout -b feature/your-feature）；
2. 进行修改，为公共 API 补充文档注释；
3. 运行测试、clippy 与 cargo fmt --all，确保全部通过；
4. 以 Conventional Commits 风格提交并推送；
5. 打开 Pull Request 并通过 CI 全部质量门禁。

📋 更新日志

完整版本记录见 docs/CHANGELOG.md（Keep a Changelog 格式，语义化版本）。

最近版本

• 0.3.0-rc.3（2026-09-10）：新增 init_inklog_logger 单例初始化、运行时级别热调（set_level）、动态 Sink 注册（LoggerBuilder::add_sink）、trace_id/span_id 追踪关联、inklog-cli query 日志检索、网络转发 Sink（TCP/UDP）、OTLP 导出 MVP、归档防篡改链与 docs/PERFORMANCE.md 首份性能基线；
• 0.3.0-rc.2（2026-09-03）：集成 trait-kit 0.5.0-rc.2 与 i18n 重构并升级版本号；默认公共 API 移除三个 Mock（BREAKING，外部测试消费者需启用 test-utils）；
• 0.2.0（2026-08-05）：新增 compression / parquet / fast-masking feature 与 i18n 核心模块；新增 ChannelBufferedFileSink、断路器保护与环形缓冲文件 Sink；edition 2024、MSRV 1.94。

📄 许可证

本项目基于 MIT License 发布，附加 Commons Clause 条件：未经单独授权，不得销售本软件。版权所有 (c) 2026 Kirky.X。

🙏 致谢

inklog 的实现依赖这些优秀的开源项目：

• tokio：异步运行时
• tracing：结构化日志与 Subscriber 生态
• crossbeam-channel：高性能有界通道
• axum：HTTP 健康与指标端点
• serde：序列化框架
• RustCrypto（aes-gcm / sha2 / pbkdf2 / zeroize）：密码学原语
• Project Fluent 与 ICU：国际化消息格式
• criterion：统计严谨的基准测试框架

数据库、缓存、配置与生命周期集成分别由同工作区项目 dbnexus、oxcache、confers、trait-kit 提供。

📞 联系与支持

⭐ Star 历史

💝 支持本项目

如果您觉得这个项目有用，请考虑给它一个 ⭐️！

由 ❤️ Inklog 团队构建

© 2026 Inklog Project. 版权所有。

⬆ 返回顶部