Go 大批量日志写入怎么从单文件迁移到分片队列：吞吐、顺序与重放

审计日志量一上来，最先暴露问题的往往不是磁盘容量，而是接口延迟：每个请求都在同一个 audit.log 上调用 WriteString，文件锁和同步刷盘把业务协程排成了一条长队。更稳妥的改法是把“接收日志”和“落盘”拆开，用租户哈希把事件分到固定队列，再由每个分片批量写入文件；这样既保留单租户内顺序，也给失败重放留下明确的位置。

单文件写入为什么会把请求拖慢

先做一个小实验：接口收到事件后，直接给 audit.log 加互斥锁，写入一行 JSON，再调用 Sync。低流量时它运行得很顺畅，但并发升到 300 个请求后，P95 延迟会跟着磁盘抖动波动。这里别急着把锁换成更快的锁，问题根源在于业务请求仍然直接承担了落盘责任。

func appendAudit(f *os.File, mu *sync.Mutex, line []byte) error {
    mu.Lock()
    defer mu.Unlock()
    if _, err := f.Write(append(line, '\n')); err != nil {
        return err
    }
    return f.Sync()
}

这段代码有三个很明显的代价：所有租户共享一把锁；每条事件都触发一次写入；Sync 出现在 HTTP 请求的关键路径。即使文件系统最终把数据缓存在页缓存里，请求也会被最慢的那一轮 I/O 拖慢节奏。

把日志入口改成固定分片队列

迁移时我保留了一个简单约束：同一个 tenantID 的事件必须进入同一个分片。分片数量在进程启动时确定，比如 8 个；不要根据当前队列长度动态扩缩，否则重启或扩容后很难解释同一租户的事件顺序。

type Event struct {
    TenantID string
    Seq      uint64
    Body     []byte
}

type Shard struct {
    Queue chan Event
    File  *os.File
}

func pickShard(tenant string, count int) int {
    h := fnv.New32a()
    _, _ = h.Write([]byte(tenant))
    return int(h.Sum32() % uint32(count))
}

HTTP 层只负责复制一份必要数据、分配序号并把事件送进队列。队列满时要有明确策略：审计日志通常不能静默丢弃，我更建议返回“稍后重试”并记录拒绝计数；如果业务允许降级，也要把丢弃原因写进监控，而不是只打印一条模糊的 warning 日志。

批量落盘怎样兼顾吞吐和分片内顺序

每个分片只启动一个写入 worker，按入队顺序取事件，累计到 256 条或等待 50 毫秒就刷一次。批次先写入临时文件，成功关闭后再改名为 batch-000042.ok；写失败则保留 batch-000042.retry，这样重放工具能识别“已经取出但尚未确认”的事件范围。

func flushBatch(s *Shard, batch []Event, id uint64) error {
    name := fmt.Sprintf("batch-%06d.tmp", id)
    tmp, err := os.OpenFile(name, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0640)
    if err != nil { return err }
    for _, e := range batch {
        if _, err = tmp.Write(append(e.Body, '\n')); err != nil {
            _ = tmp.Close()
            return err
        }
    }
    if err = tmp.Sync(); err != nil { _ = tmp.Close(); return err }
    if err = tmp.Close(); err != nil { return err }
    return os.Rename(name, strings.TrimSuffix(name, ".tmp")+".ok")
}

这里的 Seq 仍然要写进每行事件，文件名只能代表批次，不代表业务顺序。重放时按分片文件夹中的批次编号和行内序号读取，遇到已经入库的序号就跳过。这个幂等边界比“相信文件名连续”可靠得多。

扩容时最容易丢掉的不是性能而是顺序

固定 8 分片在单实例内很好理解，但进程扩容后，简单的本地哈希会让同一租户被不同实例接收。若日志必须全局有序，需要把分片放到共享队列或在入口按租户路由；如果只要求单实例内有序，则应在文档和字段名里明确写成“分片内顺序”，不要给调用方错误承诺。

实战里可以先把分片编号、实例 ID、批次 ID 和最后确认序号打进指标与日志。扩容前观察每个分片的队列长度、刷盘耗时、失败批次数；扩容后重点检查同一个租户是否出现两个实例同时写入的情况。

停机和重放要有一条可执行的路径

收到 SIGTERM 后，先让 HTTP 服务停止接收新事件，再关闭所有分片队列的写入口。worker 继续排空，直到队列长度为 0 或达到停机预算；未完成的批次移动到 retry 目录，启动时再由重放程序按序处理。最后才关闭文件句柄。

关闭入口 -> 关闭队列 -> 等待 worker -> 标记 retry -> 关闭文件

停机预算不要写成无限等待。比如给 20 秒，最后 2 秒只做状态记录和文件关闭，并把未排空数量写入 shutdown_pending。下一次启动先处理 retry，再接收新流量，避免新旧批次交错到让人无法复盘。

常见问题

分片数量应该一开始就设得很大吗？

不建议。分片越多，占用的文件、worker 和监控维度就越多。先根据写入峰值和单 worker 的批量吞吐压测，留出约 30% 的余量，再用稳定的编号规划后续扩容。

队列满了能不能直接丢弃日志？

只有业务明确允许时才丢弃，而且必须记录丢弃计数和原因。审计、计费、权限变更类事件通常应拒绝请求或转入更可靠的外部队列。

批次文件已经改成 ok 了，还需要写数据库吗？

如果文件只是中间缓冲，数据库或下游系统仍应保存最后确认的分片序号。文件名用于恢复，确认序号用于幂等，两者承担的职责不同。

落地前的检查清单

• 确认同一业务键的顺序要求是分片内还是跨实例全局。
• 压测队列满、磁盘变慢、批次写失败和进程被终止四种场景。
• 检查每个事件都有可追踪的 tenant_id、seq 和 batch_id。
• 演练 retry 文件夹重放，确认重复事件不会再次产生业务副作用。

把同步单文件写入改成分片队列，真正的收益不只是吞吐数字变大，而是把顺序、失败和停机边界明确写进了系统。先用固定分片跑通指标和重放，再考虑共享队列或跨实例路由，迁移过程会更容易收敛。