Go syscall.Flock 怎样实现单实例文件锁

我做过一个只允许单进程运行的本地任务：程序启动时要读同一份缓存，重复启动反而会互相覆盖。最初只判断“锁文件是否存在”，结果进程异常退出后留下的文件会把下一次启动永远挡住。更可靠的做法是让文件存在与否退居二线，把真正的互斥交给打开后的文件描述符：用 syscall.Flock 请求排他锁，再把这个描述符一直持有到服务结束。

官方文档：https://pkg.go.dev/syscall#Flock

这套写法适合 Linux、macOS 等 Unix 类环境中的单机任务、桌面后台进程和本地定时器。它解决的是“同一锁文件对应的多个进程不要同时进入”，不是跨主机的分布式锁。

先把锁文件、文件描述符和互斥语义分开

锁文件路径只是大家约定的坐标，例如 /var/run/my-worker.lock 或用户可写目录里的 my-worker.lock。真正参与 Flock 调用的是 os.OpenFile 返回的文件描述符。只要另一个进程打开同一文件并请求冲突的排他锁，内核就能让它进入“已占用”分支。

因此不要把“锁文件还在不在”当作锁状态，也不要在启动前无条件删除它。进程崩溃后，内核会随着文件描述符关闭释放锁；文件名留下并不代表互斥状态还在。

用非阻塞排他锁拒绝重复启动

单实例程序通常不希望第二个进程一直卡在启动阶段，所以组合 LOCK_EX 与 LOCK_NB：前者表示排他锁，后者表示拿不到锁时立即返回。下面的示例把打开、加锁和错误分类放在一起，方便把“已有实例”与“路径不可用”区分开。

package main

import (
    "errors"
    "fmt"
    "os"
    "syscall"
)

// acquireSingleInstance 打开固定锁文件，并尝试立即取得排他锁。
func acquireSingleInstance(path string) (*os.File, error) {
    // 锁文件只需要作为稳定坐标，不把业务数据写进去。
    file, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600)
    if err != nil {
        return nil, fmt.Errorf("打开锁文件失败: %w", err)
    }

    // LOCK_NB 让重复启动快速失败，不让第二个进程永久等待。
    err = syscall.Flock(int(file.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
    if err != nil {
        _ = file.Close() // 加锁失败时立即归还已经打开的描述符。
        if errors.Is(err, syscall.EWOULDBLOCK) || errors.Is(err, syscall.EAGAIN) {
            return nil, fmt.Errorf("已有实例持有锁: %w", err)
        }
        return nil, fmt.Errorf("获取文件锁失败: %w", err)
    }
    return file, nil
}

func main() {
    lockFile, err := acquireSingleInstance("/tmp/example-worker.lock")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer func() {
        // 先显式解锁，再关闭描述符，释放责任更清楚。
        _ = syscall.Flock(int(lockFile.Fd()), syscall.LOCK_UN)
        _ = lockFile.Close()
    }()

    // 真实服务应在这里进入自己的主循环，并一直持有 lockFile。
    fmt.Println("单实例锁已取得")
}

这里的关键不是锁文件内容，而是 file.Fd() 对应的打开对象。第二个进程拿不到冲突锁时，常见结果是 EWOULDBLOCK 或与它等价的 EAGAIN；这表示“已有实例”，不应被误报成目录权限错误。

失败处理和生命周期要一起设计

我更愿意把锁获取当成自动化任务的入口门禁：入口失败要能告诉调用方“已有实例”，入口成功则必须把锁句柄交给整个服务生命周期。只在一个短函数里加锁、函数返回后马上关闭文件，等于把门禁提前撤掉。

正常退出路径上用 defer 释放；加锁失败路径上关闭已经打开但未持锁的文件；异常终止时，操作系统会回收进程持有的文件描述符。锁文件本身可以保留，避免用删除文件制造“路径变化但旧描述符仍有效”的额外复杂度。

这把锁能管什么，不能管什么

另外，文件锁只约束“遵守同一锁协议”的进程。某个进程直接写业务文件却不调用 Flock，锁不会替它拦截所有 I/O；这也是为什么锁路径、受保护资源和启动入口要在项目约定里写清楚。

我的结论：把它当单机入口门禁

如果目标是让一台机器上的 worker、备份程序或本地调度器只运行一份，OpenFile + LOCK_EX|LOCK_NB + 持有描述符 + defer 释放 是一条直观路线。最容易出错的地方有三个：把文件存在当成锁状态、忽略非阻塞锁的占用错误、以及拿到锁后过早关闭文件。

如果目标已经变成多机抢占、租约续期或故障转移，就应该换成明确支持这些语义的协调方案，而不是给 syscall.Flock 再包一层名字。

相关问题

锁文件需要在程序退出时删除吗？通常不需要。文件名是稳定坐标，锁的有效性来自文件描述符和内核锁状态。

为什么第二个进程不能一直等待？单实例入口更适合用 LOCK_NB 立即返回，让调度器或用户知道已有实例，而不是无提示地卡住。

syscall.Flock 能替代分布式锁吗？不能直接替代。它的边界是能共享同一文件锁语义的 Unix 文件系统环境。