filerotate

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 28, 2026 License: MIT Imports: 12 Imported by: 0

README

filerotate

Go Reference

多进程安全的文件轮转库,提供统一的 Writer 结构和两种工作模式:

  • New() – 根据 NotifierFactory 自动选择模式:
    • NotifierFactory 为 nil(默认)→ 单机模式,内置文件轮询 + 文件锁,开箱即用。
    • NotifierFactory 非 nil → 标准模式,通过 Leader 选举与可插拔的进程间通知机制实现精确协调。
  • NewLocal() – New() 的便捷封装,强制单机模式,忽略 NotifierFactory/LockerFactory 配置。

特性

两种模式共有
  • 多进程安全 – 轮转时通过分布式锁(文件锁、Valkey Redlock)保证唯一执行者。
  • 按大小轮转 – 文件达到设定大小后自动重命名为带纳秒级时间戳的备份文件。
  • 自动清理 – 可配置备份文件保留天数,过期自动删除。
  • 零日志丢失 – 轮转期间其他进程的写入会完整保留在备份文件中,下次写入自动重开文件。
  • Write() 无锁 – 热路径不加锁,依赖 O_APPEND 内核级原子追加,高并发下完全并行写入。
  • Windows 支持 – 使用 FILE_SHARE_DELETE 打开文件,允许其他进程在持有句柄时执行重命名。
标准模式额外优势
  • 全自动进程发现 – 无需手动配置进程数,Leader 锁自动协调所有进程。
  • Leader 死亡自动恢复 – 原 Leader 崩溃后其他进程自动重新选举。
  • 可插拔通知与锁 – 提供 Notifier 和 Locker 接口,内置多种实现。
单机模式特点
  • 无进程间通信 – 每个进程通过内置 polling goroutine 独立检测文件大小和 inode 变化。
  • 统一阈值 – 所有进程共享同一 MaxSizeMB 阈值,无需预估每进程写入量。
  • 信号去重 – 轮转失败时不会重复发送信号,直到当前处理完成后才允许下一轮检测。

平台支持

模式 Linux macOS Windows 说明
单机模式 (NewLocal()) ✅ ✅ ✅ 默认,基于文件轮询 + 文件锁,无 Leader 选举
标准模式 (自定义通知器) ✅ ✅ ✅ 设置 NotifierFactory 后启用 Leader 选举 + 跨进程通知

快速开始

安装
go get github.com/piyongcai-liucai/filerotate
单机模式(默认,无进程间通信)
// 方式一:New() 自动选择(NotifierFactory 为 nil → 单机模式)
writer, err := filerotate.New(filerotate.Config{
    FilePath:   "./app.log",
    MaxSizeMB:  100,
    MaxAgeDays: 7,
})
// 方式二:NewLocal 便捷函数(强制单机模式,忽略 LockerFactory/NotifierFactory)
writer, err := filerotate.NewLocal(filerotate.Config{
    FilePath:   "./app.log",
    MaxSizeMB:  100,
    MaxAgeDays: 7,
})
if err != nil {
    log.Fatal(err)
}
defer writer.Close()

log.SetOutput(writer)
使用 Valkey 通知器和锁(跨主机 NFS)
client, _ := valkey.NewClient(valkey.ClientOption{
    InitAddress: []string{"localhost:6379"},
})

locker, _ := filerotate.NewValkeyLocker(
    valkeylock.LockerOption{
        ClientOption: valkey.ClientOption{InitAddress: []string{"localhost:6379"}},
        KeyMajority:  1,
        KeyValidity:  30 * time.Second,
    },
    "filerotate-lock",
)

writer, _ := filerotate.New(filerotate.Config{
    FilePath:  "/nfs/logs/app.log",
    MaxSizeMB: 10,
    LockerFactory: func(lockPath string) (filerotate.Locker, error) {
        return locker, nil
    },
    NotifierFactory: func(errorHandler func(error)) (filerotate.Notifier, error) {
        return filerotate.NewValkeyNotifier(client, "filerotate:rotate", errorHandler), nil
    },
})

配置说明

NotifierFactory 与模式选择
type Config struct {
    FilePath        string                                          // 文件路径,所有进程必须相同
    MaxSizeMB       int                                             // 触发轮转的文件大小(MB),0 表示永不轮转
    MaxAgeDays      int                                             // 备份保留天数,0 为永久
    CheckInterval   time.Duration                                   // 检查间隔:默认 5s(标准),1s(单机)
    LockerFactory   func(lockPath string) (Locker, error)           // 自定义锁工厂,标准模式必填,单机模式忽略
    NotifierFactory func(errorHandler func(error)) (Notifier, error) // nil=单机模式,非nil=标准模式 + Leader选举
    ErrorHandler    func(error)                                     // 内部 goroutine 错误回调,默认打印 stderr
}

内置组件

通知器(Notifier)
实现 构造函数 适用场景
单机轮询 内置默认 基于文件轮询(inode + 大小检测),单机默认
NATS 核心 NewNATSNotifier(conn, subject, errorHandler) Pub/Sub,需要 NATS 服务
JetStream NewJetStreamNotifier(js, subject, errorHandler) 临时消费者,Stream 外部创建,消息持久化
Valkey NewValkeyNotifier(client, channel, errorHandler) Pub/Sub,需要 Valkey/Redis
分布式锁(Locker)
实现 构造函数 说明
单机文件锁 内置 默认,基于 gofrs/flock,单机模式自动使用
Valkey 锁 NewValkeyLocker(option, key) Redlock 算法,自动续期,适合跨主机

如果你只在单台机器上运行多个进程,默认的文件锁就是最简单、最快速的方案。Locker 接口仅作为可选扩展提供。

选型指南

场景 模式 通知器 锁
单机极简模式 单机模式 内置单机轮询 内置单机文件锁
网络文件系统 标准模式 NATS / JetStream / Valkey ValkeyLocker

项目结构

filerotate/
├── writer.go                # Writer 结构 + 标准模式 Config/New
├── writer_local.go           # 单机模式便捷构造函数和自轮转循环
├── leader.go                # Leader 选举、文件监控、轮转触发
├── rotate.go                # 文件重命名、备份清理、时间戳解析
├── open_file_unix.go        # Unix: O_CREATE|O_APPEND|O_WRONLY
├── open_file_windows.go     # Windows: CreateFile + FILE_SHARE_DELETE
├── locker.go                # Locker 接口 + 工厂函数
├── notifier.go              # Notifier 接口 + 工厂函数
├── integration_test.go      # 多进程集成测试
├── internal/
│   ├── locker/
│   │   ├── local.go         # 单机文件锁(flock)
│   │   └── valkey.go        # Valkey 锁(Redlock)
│   └── notifier/
│       ├── local.go         # 单机轮询通知器(基于文件大小和 inode)
│       ├── nats.go          # NATS Pub/Sub 通知器
│       ├── jetstream.go     # JetStream 临时消费者通知器
│       └── valkey.go        # Valkey Pub/Sub 通知器
└── example/
    ├── local/               # 单机模式多进程示例
    ├── nats/                # NATS 通知器示例
    ├── jetstream/           # JetStream 通知器示例
    └── valkey/              # Valkey 通知器 + 锁示例

工作原理

标准模式
进程启动 → New()(NotifierFactory + LockerFactory 均非 nil)
  → 尝试获取 Leader 锁
  ├── 成功 → runLeader()
  │          ├── 启动 Notifier.Serve()(监听连接)
  │          ├── Connect() 自己,接收自己广播的命令
  │          └── 定时检查文件大小 → 超阈值 → doRotation() → Broadcast("ROTATE")
  └── 失败 → connectToLeader()
             ├── Connect() 连接到 Leader
             ├── handleCommands() 监听 ROTATE 命令
             └── 收到 ROTATE → 发送信号到 rotateCh → Write() 中 reopenFile()
单机模式
进程启动 → New() / NewLocal()
  ├── 创建 LocalNotifier(polling goroutine,定期 stat 文件)
  ├── 启动 runLocalLoop goroutine 监听轮转信号
  └── Write() 热路径:
       ├── select rotateCh(非阻塞检查)
       │   └── 有信号 → reopenFile()
       └── f.Write(p)(直接写入,无锁)

LocalNotifier 检测到 size 超阈值或 inode 变化 → 发送 ROTATE
  → runLocalLoop 收到 ROTATE → tryRotate()
      ├── TryLock()(非阻塞抢锁)
      ├── 抢到锁 → 二次确认文件大小 → doRotation()
      └── 没抢到(别人已轮转)→ 仅 reopenFile()

轮转文件命名

备份文件使用纳秒级精度时间戳,避免高频轮转时文件名冲突:

app.log.20240501_143025.123456789

旧格式(秒级精度)的备份文件同样支持识别和清理:

app.log.20240501_143025

Documentation

Overview

Package filerotate 提供多进程安全的文件轮转功能。

本文件实现 Leader 选举后的主循环逻辑:监控文件大小、触发轮转。

Package filerotate 提供多进程安全的文件轮转功能。

本文件定义 Locker 接口及工厂函数,用于创建分布式锁。 所有锁实现(文件锁、Valkey 锁)均通过此接口对外暴露, 具体实现位于 internal/locker 包中,外部不可见。

Package filerotate 提供多进程安全的文件轮转功能。

本文件定义 Notifier 接口及工厂函数,用于进程间轮转通知。 所有通知器实现(文件轮询、NATS、JetStream、Valkey)均通过此接口对外暴露, 具体实现位于 internal/notifier 包中,外部不可见。

Package filerotate 提供多进程安全的文件轮转功能。

本文件实现 Unix 平台的文件打开。

Package filerotate 提供多进程安全的文件轮转功能。

本文件包含文件轮转的核心操作:重命名、创建新文件、清理过期备份。

Package filerotate 提供多进程安全的文件轮转功能。

本文件实现 Writer 核心逻辑:Write、Close、doRotation 及标准模式(Leader 选举 + 通知器)。

Package filerotate 提供多进程安全的文件轮转功能。

本文件实现单机(Local)模式的自轮转循环和便捷构造函数, 使用内置轮询通知器 + 文件锁协调多进程。

Index

Constants

View Source
const (
	// CmdRotate 是 Leader 通知客户端执行文件重开的命令。
	CmdRotate = "ROTATE"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// FilePath 文件路径。所有并发进程必须使用相同的路径。
	FilePath string

	// MaxSizeMB 触发轮转的总文件大小(MB)。Leader 定期检查文件实际大小。
	MaxSizeMB int

	// MaxAgeDays 备份文件保留天数。0 表示永不删除。轮转时自动清理过期备份。
	MaxAgeDays int

	// CheckInterval 检查文件大小的间隔。默认值取决于模式:单机 1s,标准 5s。
	CheckInterval time.Duration

	// LockerFactory 自定义锁工厂函数。标准模式必须设置,单机模式忽略(始终用 LocalLocker)。
	LockerFactory func(lockPath string) (Locker, error)

	// NotifierFactory 自定义通知器工厂函数。若为 nil,使用基于文件轮询的默认通知器。
	// 跨主机场景(NFS + 跨进程通知)时可注入 NATS / JetStream / Valkey 等通知器。
	NotifierFactory func(errorHandler func(error)) (Notifier, error)

	// ErrorHandler 当内部 goroutine 发生错误时调用。如果为 nil,错误将打印到 stderr。
	ErrorHandler func(error)
}

Config Writer 配置,同时用于单机模式和标准模式。

type Locker

type Locker interface {
	// TryLock 非阻塞尝试获取锁,返回是否成功。
	// 成功获取锁后,调用者应确保在操作完成后调用 Unlock。
	TryLock() (bool, error)

	// Unlock 释放锁。
	Unlock() error
}

Locker 分布式锁接口,用于保护轮转操作。 单机模式内置文件锁,无需关心此接口。 仅在跨主机场景下才需要提供自定义实现(如 NewValkeyLocker)。

func NewValkeyLocker

func NewValkeyLocker(option valkeylock.LockerOption, key string) (Locker, error)

NewValkeyLocker 创建一个基于 Valkey 的分布式锁。

使用 valkeylock 包的 Redlock 算法,支持多节点多数派共识、锁自动续期和客户端缓存失效通知。 用户可以通过 option 完全控制锁的行为,例如设置客户端配置、多数派数量、锁有效期等。

参数:

  • option: valkeylock.LockerOption 配置,用于底层锁的创建。
  • key: 锁键名称,所有竞争同一资源的进程必须使用相同的 key。

示例:

locker, err := filerotate.NewValkeyLocker(
    valkeylock.LockerOption{
        ClientOption: valkey.ClientOption{InitAddress: []string{"localhost:6379"}},
        KeyMajority:  1,
        KeyValidity:   30 * time.Second,
    },
    "my-lock-key",
)

type Notifier

type Notifier interface {
	// Serve 在 Leader 端启动服务,等待客户端连接。
	// 对于无需服务端初始化的实现(如 NATS),可直接返回 nil。
	Serve() error

	// Connect 客户端连接到 Leader,返回一个接收命令的字符串通道。
	// 通道中会收到 CmdRotate 等命令,当连接断开时通道关闭。
	Connect() (<-chan string, error)

	// Broadcast 向所有已连接的客户端发送命令。
	// 应确保所有当前在线的客户端都能收到该命令。
	Broadcast(cmd string) error

	// Close 关闭通知器,释放资源。
	Close() error
}

Notifier 定义进程间轮转通知的通信接口。 Leader 通过此接口向所有客户端广播轮转命令(CmdRotate)。 所有进程(包括 Leader 自己)都需要通过 Connect() 订阅命令, 以便在收到 ROTATE 命令时执行文件重开操作。

func NewJetStreamNotifier

func NewJetStreamNotifier(js nats.JetStreamContext, subject string, errorHandler func(error)) Notifier

NewJetStreamNotifier 创建一个基于 NATS JetStream 的通知器。 使用临时消费者(Ephemeral Consumer),进程退出后自动清理,只接收新消息。 errorHandler 为错误处理回调,若为 nil 则默认打印到 stderr。

func NewNATSNotifier

func NewNATSNotifier(conn *nats.Conn, subject string, errorHandler func(error)) Notifier

NewNATSNotifier 创建一个基于 NATS 核心 Pub/Sub 的通知器。 conn 为已建立的 NATS 连接,subject 为通信主题,所有进程必须使用相同的主题。 errorHandler 为错误处理回调,若为 nil 则默认打印到 stderr。

func NewValkeyNotifier

func NewValkeyNotifier(client valkey.Client, channel string, errorHandler func(error)) Notifier

NewValkeyNotifier 创建一个基于 Valkey Pub/Sub 的通知器。 client 为已连接的 Valkey 客户端,channel 为频道名称,所有进程必须使用相同的频道。 errorHandler 为错误处理回调,若为 nil 则默认打印到 stderr。

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer 是多进程安全的文件写入器。

标准模式:通过 Leader 选举和进程间通知协调所有进程。 所有进程平等竞争 Leader,Leader 负责监控文件大小并广播轮转命令。

单机(Local)模式:无 Leader 选举,无进程间通信。每个进程通过内置的 polling goroutine 独立检查文件状态,通过分布式锁协调轮转操作。

Writer 实现了 io.WriteCloser,可直接与 log.Logger、fmt.Fprint 等配合使用。

func New

func New(cfg Config) (*Writer, error)

New 创建一个 Writer。

根据 NotifierFactory 自动选择模式:

  • NotifierFactory == nil:单机模式,使用内置 LocalNotifier 轮询 + 分布式锁协调多进程。 所有进程平等,无 Leader 选举。
  • NotifierFactory != nil:标准模式,使用自定义 跨进程通知器 + Leader 选举协调多进程。

func NewLocal

func NewLocal(cfg Config) (*Writer, error)

NewLocal 创建一个单机模式 Writer。

与 New() 不同,NewLocal 强制使用内置 LocalNotifier(文件轮询)+ LocalLocker(文件锁), 忽略 Config 中的 LockerFactory 和 NotifierFactory。

单机模式下每个进程自给自足:

  • 独立轮询文件状态(大小 + inode)
  • 检测到超阈值时通过文件锁竞争轮转权
  • 检测到 inode 变化(其他进程已完成轮转)时自动重开文件

func (*Writer) Close

func (w *Writer) Close() error

Close 释放资源,关闭文件、通知器和锁。

func (*Writer) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write 实现 io.Writer。写入前检查是否有轮转信号,若有则先处理轮转。 Write 本身不加锁(依赖 O_APPEND 内核级原子写入),轮转时 doRotation 加 mu 锁。 若本轮写入期间发生轮转,数据进入备份文件而非新文件,但数据不会丢失, 下次写入时自动重开文件。

Directories

Path Synopsis
example
common
Package common 提供示例程序共享的辅助函数。
Package common 提供示例程序共享的辅助函数。
jetstream command
JetStream 示例:使用 NATS JetStream 临时消费者进行进程间通信,模拟 3 个进程并发写入。
JetStream 示例:使用 NATS JetStream 临时消费者进行进程间通信,模拟 3 个进程并发写入。
local command
Local 版示例:模拟 3 个进程并发写入,无进程间通信,通过内置轮询和分布式锁协调轮转。
Local 版示例:模拟 3 个进程并发写入,无进程间通信,通过内置轮询和分布式锁协调轮转。
nats command
NATS 示例:使用 NATS 核心 Pub/Sub 进行进程间通信,模拟 3 个进程并发写入。
NATS 示例:使用 NATS 核心 Pub/Sub 进行进程间通信,模拟 3 个进程并发写入。
valkey command
Valkey 示例:同时使用 Valkey Pub/Sub 通知器和 Valkey 分布式锁, 模拟 3 个进程并发写入,适用于跨主机 NFS 共享存储场景。
Valkey 示例:同时使用 Valkey Pub/Sub 通知器和 Valkey 分布式锁, 模拟 3 个进程并发写入,适用于跨主机 NFS 共享存储场景。
internal
locker
Package locker 提供分布式锁的内部实现。
Package locker 提供分布式锁的内部实现。
notifier
Package notifier 提供进程间通知的内部实现。
Package notifier 提供进程间通知的内部实现。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL