colibri：低内存单二进制常驻任务调度与搬运服务

colibri 这个词，西班牙语里是蜂鸟。第一次看到有人拿它当项目名，我脑子里立刻浮现出那个画面——体重不到两克，翅膀每秒拍七八十下，能悬停、能倒飞、能在花丛里精准定位，而且能耗低到可以整夜不吃东西。把这样一个生物的名字贴到工程产物上，多半不是随便取的，它暗含了一整套设计约束：体积要小、响应要快、能耗要低、动作要准。我这次要聊的 colibri，就是沿着这条思路做出来的东西——一个常驻在本机或边缘设备上的轻量级任务搬运与调度服务。

先说清楚它能干什么。日常开发和运维里，总有一堆零碎的活儿需要一个“永远在线的小管家”：定时把某个目录的新文件搬到另一个地方、每隔几分钟抓一次本地接口的状态写进时序库、把散落在各处的日志做一次归并和过滤、在设备断网时把数据先缓冲在本地、等链路恢复再补发。这些活儿用 crontab 写会散得到处都是，用 Celery、Airflow 这类框架又太重，光依赖就够喝一壶。colibri 瞄准的就是这个夹缝：单个二进制、一份配置文件、常驻内存控制在几十兆以内、冷启动两百毫秒内就绪。

这篇文章适合谁看？如果你手上有一台树莓派、一台老旧的迷你主机、一台工控机，或者只是想让自己的笔记本在后台安静地跑点小任务，那你就是目标读者。如果你已经写过几个常驻服务，但总在内存缓慢上涨、优雅退出卡死、配置改了不生效这些地方翻车，那这篇更值得往下读。标题只给了一个词，所以下面的技术选型和参数都是按这类项目最典型的路子展开的，你可以直接套，也可以按自己的场景替换掉其中几块。

1. 项目定位与整体架构设计

1.1 把“蜂鸟”这三个字翻译成可验收的工程指标

名字好听没用，得能落到数字上。我给 colibri 定的第一版验收线是这样的：常驻内存 RSS 不超过 40MB，空闲状态下 CPU 占用低于 0.5%，从进程启动到开始接活的时间不超过 200 毫秒，单实例同时挂载的任务数不少于 200 个，进程被杀掉之后 3 秒内能被系统重新拉起来并恢复调度，最终交付物是一个二进制加一份配置文件。这几条看着朴素，但每一条都会倒逼出后面的技术决策，比如“单二进制”直接排除了需要解释器或运行时依赖的方案，“200 毫秒就绪”排除了启动时要连一大堆外部组件的设计，“40MB 内存”则决定了队列缓冲不能随便开大。

为什么要把指标写死而不是“尽量小”？因为常驻服务最怕的就是边界模糊。你心里想着“轻量”，结果队列开了十万条，日志缓存给了 64MB，插件各自再起几个协程，上线一个月后一看 RSS 已经三百多兆，在一台 1GB 内存的小机器上就开始跟别的进程抢资源。把数字写下来，后面每一个参数选择才有参照系，讨论“要不要把它调大一点”的时候也有依据，而不是凭感觉。

这套约束带来的直接结果是：优先考虑静态编译、自带运行时的语言；优先考虑事件驱动而不是线程池；优先考虑内存里有界队列而不是无界队列。下面几节就沿着这个逻辑往下拆。

1.2 语言与运行时选型的横向对比

这一步值得花时间，因为改语言等于重写。我把几个常见方案拉平了放在一起比较，数据是空载常驻进程的典型量级，实际会有浮动，但相对关系是稳的。

我最终选了 Go，理由挺实在：静态编译出一条命令就能跑，交叉编译到 ARM 平台只要改两个环境变量，goroutine 的栈是动态增长的，起几百个也就几兆，标准库把 HTTP、JSON、日志、信号处理全包了，不需要为了一个小服务拉一堆第三方依赖。Rust 的资源表现更好，但开发速度会慢一截，对这个体量的项目来说性价比不高。Python 写起来最舒服，可是空载就吃掉一半内存预算，还得处理虚拟环境和版本问题，在小设备上不划算。

注意：这里说的内存量级是空载常驻进程的观测值，不同版本、不同编译参数、不同操作系统上会有差异。做技术选型时建议自己在目标设备上跑一个最小 Demo 实测一遍，别直接抄表格。

1.3 架构骨架：一个进程、三类协程、四条队列

colibri 的内部结构不复杂，就是一条流水线。源头是任务装载器，它读配置、读插件清单，把任务定义注册进调度器。调度器负责算出每个任务下一次该在什么时候跑，到点了就把任务投进就绪队列。执行池从就绪队列里取任务，真正去调用处理函数，成功就记录结果，失败就按策略丢进重试队列或死信队列。整个过程跑在一个进程里，靠 channel 串起来。

三类协程分别是：调度协程，通常只有一个，负责维护时间结构、推进时钟；执行协程，数量固定，从队列里取活干；辅助协程，包括信号监听、指标采集、日志刷盘、配置监听，每个都是长跑的小循环。四条队列分别是就绪队列、延迟队列、重试队列、死信队列，全部设容量上限，满了就有明确行为，要么阻塞生产者，要么按策略丢弃并打点。

为什么全都用有界队列？因为无界队列是内存泄漏的温床。上游一快、下游一慢，队列就像吹气球一样膨胀，直到把内存吃干净才报 OOM，那时候你连现场都抓不到。有界队列的坏处是可能丢数据，但丢数据这件事只要被记录、被计数、被告警，就是可控的；反过来，内存被慢慢吃光，是不可控的。

1.4 为什么不用现成的调度框架

我认真评估过 Airflow、Celery、Kubernetes CronJob 和系统自带的 systemd timer，最后都排除了。

Airflow 解决的是数据管道的依赖编排问题，带 Web UI、元数据库、执行器，最小部署也要跑好几个进程，内存占用直接就是 colibri 的十几倍，而且它依赖数据库，在没有稳定数据库的现场环境里根本起不来。Celery 需要消息中间件，RabbitMQ 或 Redis 又是一套要维护的东西，多一个组件就多一个半夜被叫醒的理由。Kubernetes CronJob 在小规模场景下是杀鸡用牛刀，为了跑几个定时脚本搭一个集群，运维成本完全不成比例。

systemd timer 是个例外，它其实很轻，也足够可靠。但它有两个短板：一是任务逻辑只能用脚本表达，脚本一多就散得到处都是，版本管理和依赖管理很痛苦；二是任务之间的状态共享、重试策略、背压控制都得自己在脚本里实现，等于把复杂度外包给了 shell。colibri 的定位是补上中间这一层——比 cron 有结构，比框架轻得多。

2. 关键参数怎么算，才不会上线就崩

2.1 内存账本：把 40MB 拆成六份

拍脑袋定个“不超过 40MB”，心里没底。我习惯做一张内存账本，把预算拆开，这样每加一个功能就知道从哪儿扣钱。colibri 的账本大致是这样：

• 二进制与只读段：约 6-8MB，取决于编译时是否带调试符号，去掉符号表能省下不少。
• 运行时基础开销：约 4-6MB，包括运行时自己的结构、GC 元数据、初始堆。
• 协程栈：每个 goroutine 栈初始很小，按需增长。200 个协程、平均 8KB 估算，约 1.6MB。
• 队列缓冲：这块是大头，取决于队列长度和单条消息大小。
• 日志缓冲与指标缓冲：预留 2-4MB。
• 插件与业务对象：预留给具体任务逻辑，给 10MB 左右的空间。

真正需要算的是队列缓冲。假设就绪队列长度设为 10000，单条任务描述结构体序列化后平均 256 字节，那 10000 × 256 字节 ≈ 2.5MB，加上 Go 里结构体本身有对齐和指针开销，实际按 1.5 到 2 倍估，差不多 5MB。四条队列不能都按最大长度算，重试队列和死信队列平时基本是空的，可以开小一点，比如各自 2000 条。

把这些加起来，稳态占用落在 25-35MB 区间，留了 15% 左右的余量应对突发。这个算法不精确，但足以让你在配置里填数字时心里有谱，而不是随手写个 1000000 然后等着看内存曲线。

2.2 队列深度：用利特尔法则算，不要凭感觉

队列该开多长，本质是算“上游比下游快多少，以及你愿意为此缓冲多久”。经典公式是利特尔法则：队列平均长度 = 到达速率 × 平均等待时间。放到我们的场景里，如果任务到达速率是每秒 2000 条，消费速率是每秒 1500 条，那积压速度就是每秒 500 条。你希望系统能扛住 30 秒的短时过载而不丢任务，那队列深度至少要 500 × 30 = 15000。

这个数字直接决定了内存开销，也决定了背压触发的时机。反过来说，如果队列开得比这个大很多，比如开了 100000，那意味着你可以容忍 200 秒的积压，但代价是接近 25MB 的内存，而且是随时可能被占满的。所以在配置里我会把队列深度写成“积压速率 × 容忍时间”，并在注释里写清楚这两个数是怎么来的，方便以后调整时有据可查。

注意：容忍时间不要拍脑袋定。要先问自己一个问题——任务积压 30 秒和积压 5 分钟，业务后果有什么不同？如果只是延迟出报表，那可以放宽；如果涉及设备状态上报的时效性，那必须收紧，同时把背压触发这件事做成可观测的指标。

2.3 并发度：IO 密集和 CPU 密集要用两套算法

执行池开多少个协程，是最容易被随手写成一个固定数字的地方。常见的错误是写个 8 或者 16，然后不管机器是 1 核还是 16 核，不管任务是纯计算还是在等网络。

正确的做法是先判断任务类型。如果一个任务的大部分时间在等外部响应，那它属于 IO 密集，并发度可以远高于核数；如果任务大部分时间在算，那并发度接近核数就够了，开多了只会增加上下文切换成本。常用的估算公式是：最优并发数 ≈ 核数 × (1 + 等待时间 / 计算时间)。

举个具体的例子。假设任务是读一个本地接口、解析 JSON、写入本地数据库，整个过程中等待占了 80 毫秒，真正的计算占 20 毫秒，机器是 4 核。套公式：4 × (1 + 80/20) = 4 × 5 = 20。所以执行池开 20 个协程是合理的。如果任务变成纯文件拷贝，等待时间占比更高，可以进一步上调；如果是压缩计算，等待占比很低，那就要往核数靠拢，甚至更低。

我一般会在配置里把执行池大小和机器核数脱钩，写成一个显式的配置项，然后在上线后观察两个指标：队列积压深度和执行协程的忙碌比例。如果队列一直在涨、协程几乎都在忙，说明开少了；如果协程大部分时间在等锁或者 CPU 利用率已经打满，说明开多了或者任务本身有问题。

2.4 超时与退避：把抖动加上，别让重试形成尖峰

重试策略里最常见的坑是固定间隔重试。假设一个下游服务挂了，colibri 这边有 500 个任务同时在重试，如果都按“每 5 秒重试一次”来，那下游会在每个 5 秒的整数倍时刻同时收到 500 个请求，本来只是慢，现在直接被压垮。

解决办法是两件事叠加：指数退避加随机抖动。退避让重试间隔随失败次数增长，抖动让每个任务的重试时刻错开。常用的公式是：延迟 = 基础间隔 × 2^(重试次数) × (0.5 + 随机数)，随机数取 0 到 1 之间。这样一来，第 1 次重试在 0.5 到 1.5 倍基础间隔之间，第 2 次在 1 到 3 倍之间，第 5 次就拉开到 16 到 48 倍。

抖动的效果是肉眼可见的，它把一个尖峰摊成了一段平缓的曲线。另外，重试次数必须设上限，我一般设 5 到 8 次，超过就进死信队列，并且死信队列的深度变化要报警——它是系统里最诚实的信号之一。

3. 从零动手：把 colibri 跑起来

3.1 环境准备与目录规划

环境要求很朴素：Go 的较新版本、Git、以及目标平台的编译能力。如果要在 ARM 的小设备上跑，交叉编译前记得把 CGO 关掉，这样出来的才是纯静态二进制，拷过去就能执行，不用管目标机上装了什么库。

目录结构我习惯这么分：入口放在根目录下的 cmd 子目录里，核心逻辑放在 internal 下并继续细分，配置示例放在 configs 里，部署脚本和单元文件放在 deploy 里。internal 这个目录名有讲究，它是 Go 的约定，放在里面的包不允许被外部项目导入，等于给模块边界上了一道锁，避免以后有人图省事直接从外面引内部实现。

# 1. 初始化项目 mkdir colibri && cd colibri go mod init github.com/yourname/colibri # 2. 建目录骨架 mkdir -p cmd/colibri internal/config internal/scheduler \ internal/worker internal/metrics internal/logging \ configs deploy scripts # 3. 交叉编译到 ARM64（注意关掉 CGO） CGO_ENABLED=0 GOOS=linux GOARCH=arm64 \ go build -trimpath -ldflags="-s -w" \ -o build/colibri-linux-arm64 ./cmd/colibri

-trimpath去掉构建时的本地路径信息，-s -w去掉符号表和调试信息，这两个一起用，二进制体积通常能缩掉三成左右。别小看这几十兆里省下的几兆，在存储紧张的设备上，以及在做版本分发的时候，差别是实打实的。

3.2 配置结构与热加载：用原子指针替换，别加锁读

配置这块我踩过坑，所以设计得比较谨慎。核心思路是：配置本身是一个不可变对象，改动时整体替换，读的时候用原子操作拿指针。这样读路径完全无锁，性能好，也不会出现“读到一半配置被改了”的中间态。

配置文件用 YAML，结构上分成三块：服务级配置、队列与执行池配置、任务列表。任务列表里每一项包含名字、处理函数、调度表达式、超时时间、重试策略。处理函数用注册表的方式管理，插件在初始化时把名字和实现注册进去，配置里只写名字，这样配置和代码解耦。

package config import ( "os" "sync/atomic" "gopkg.in/yaml.v3" ) type Task struct { Name string `yaml:"name"` Handler string `yaml:"handler"` Schedule string `yaml:"schedule"` Timeout int `yaml:"timeout_seconds"` MaxRetry int `yaml:"max_retry"` } type Config struct { Version string `yaml:"version"` QueueSize int `yaml:"queue_size"` Workers int `yaml:"workers"` LogLevel string `yaml:"log_level"` Tasks []Task `yaml:"tasks"` } var current atomic.Value // 存 *Config func Load(path string) (*Config, error) { raw, err := os.ReadFile(path) if err != nil { return nil, err } var c Config if err := yaml.Unmarshal(raw, &c); err != nil { return nil, err } // 简易校验，宁可拒绝加载也不要带着坏配置跑 if c.QueueSize <= 0 || c.Workers <= 0 { return nil, errInvalidConfig } return &c, nil } func Store(c *Config) { current.Store(c) } func Get() *Config { v := current.Load() if v == nil { return &Config{QueueSize: 1000, Workers: 4} } return v.(*Config) }

热加载的触发方式是给进程发一个信号，捕获之后重新读文件、校验、替换指针。这里有个关键细节：校验必须做全，包括任务名有没有重复、处理函数名在注册表里存不存在、调度表达式能不能解析、超时值是不是正数。校验失败就保留旧配置并打一条错误日志，绝对不能“部分生效”——半新旧的状态比完全没生效更难排查。

注意：热加载只替换配置，不会自动重建执行池和队列。队列深度这类影响内存结构的参数改了之后需要重启才能生效，这一点必须在日志里明确提示，否则用了半天还以为改了没起作用。

3.3 调度器：为什么我最后用了最小堆而不是时间轮

一提调度，很多人第一反应是时间轮。它的插入和删除都是常数级别，理论性能很好，在高频短定时场景下确实香。但在这个项目里我放弃了它，原因有三条。第一，colibri 的任务数量在几百到几万之间，这个量级下最小堆的对数复杂度（log n 大概在 10 到 15 之间）完全不构成瓶颈，省下的那点时间根本没有收益。第二，时间轮的槽位数量和时间精度是耦合的，精度要 1 秒、最长要 24 小时，槽位就得开 86400 个，内存一下就上去了，而 colibri 的内存预算本来就不富裕。第三，时间轮的任务删除要额外维护索引，环形回绕的处理也容易出边界错误，代码复杂度上去了，出 bug 的概率也跟着上去。

用标准库的 container/heap 就够了。每个任务记录下一次触发时间，堆顶永远是最早要跑的那个。调度协程的主循环是这样：从堆顶取出任务，算出距离现在还有多久，如果大于零就等待这段时间；如果系统时间被调整过，等待时间算出来是负的，那就直接触发，并把堆重新梳理一遍。

package scheduler import ( "container/heap" "context" "time" ) type item struct { taskName string next time.Time interval time.Duration index int } type pq []*item func (p pq) Len() int { return len(p) } func (p pq) Less(i, j int) bool { return p[i].next.Before(p[j].next) } func (p pq) Swap(i, j int) { p[i], p[j] = p[j], p[i]; p[i].index = i; p[j].index = j } func (p *pq) Push(x interface{}) { n := len(*p); it := x.(*item); it.index = n; *p = append(*p, it) } func (p *pq) Pop() interface{} { old := *p n := len(old) it := old[n-1] old[n-1] = nil it.index = -1 *p = old[:n-1] return it } type Scheduler struct { queue chan<- string items pq mu chan struct{} // 用容量为 1 的 channel 当互斥锁，方便配合 select } func (s *Scheduler) Run(ctx context.Context) { timer := time.NewTimer(0) defer timer.Stop() for { s.mu <- struct{}{} if s.items.Len() == 0 { <-s.mu select { case <-ctx.Done(): return case <-time.After(time.Second): continue } } top := s.items[0] now := time.Now() wait := top.next.Sub(now) if wait <= 0 { // 到点了，出堆并投递 heap.Pop(&s.items) name := top.taskName it := *top it.next = now.Add(it.interval) if it.interval > 0 { heap.Push(&s.items, &it) } <-s.mu select { case s.queue <- name: case <-ctx.Done(): return } continue } <-s.mu timer.Reset(wait) select { case <-ctx.Done(): return case <-timer.C: } } }

这段代码里有个细节值得说：等到期的方式要么用 timer 等，要么用固定间隔轮询。如果任务数量很少、间隔又很长，纯等 timer 就行。但如果有任务被动态添加进来，而当前正在等一个很久之后才到期的任务，新任务就会被拖延。实际实现里我会在配置热加载或任务增删时往一个通知 channel 里发个信号，让调度循环提前醒来重算，避免新加的任务要等下一个周期才生效。

3.4 执行池与优雅退出：别让进程被强杀

执行池就是固定数量的协程，从就绪队列里取任务名，查注册表拿到处理函数，在带超时的 context 里执行。超时用 context.WithTimeout 控制，处理函数必须接受 context 参数并在里面响应取消，否则超时就是摆设。

优雅退出是这个项目里我认为最值得认真写的部分。目标很明确：收到终止信号后，不再接受新任务，把队列里已经在跑的任务放完，然后退出。实现上是一个 context 取消加一个 WaitGroup。

package worker import ( "context" "log/slog" "sync" "time" ) type Handler func(ctx context.Context) error type Pool struct { queue <-chan string registry map[string]Handler timeout time.Duration wg sync.WaitGroup } func (p *Pool) Start(ctx context.Context, n int) { for i := 0; i < n; i++ { p.wg.Add(1) go func(id int) { defer p.wg.Done() for { select { case <-ctx.Done(): slog.Info("worker exiting", "id", id) return case name, ok := <-p.queue: if !ok { return } p.run(ctx, name) } } }(i) } } func (p *Pool) run(ctx context.Context, name string) { h, ok := p.registry[name] if !ok { slog.Error("handler not found", "task", name) return } c, cancel := context.WithTimeout(ctx, p.timeout) defer cancel() start := time.Now() if err := h(c); err != nil { slog.Warn("task failed", "task", name, "err", err, "cost_ms", time.Since(start).Milliseconds()) return } slog.Info("task done", "task", name, "cost_ms", time.Since(start).Milliseconds()) } func (p *Pool) Stop(grace time.Duration) { done := make(chan struct{}) go func() { p.wg.Wait() close(done) }() select { case <-done: slog.Info("all workers drained") case <-time.After(grace): slog.Warn("grace period exceeded, forcing exit") } }

这里有个我反复强调的点：优雅退出的宽限时间不能设得太长。我曾经把它设成 120 秒，结果部署时每次重启都要等两分钟，运维同事以为服务卡死了。后来改成 15 秒，配合任务级超时（大多数任务在 10 秒内结束），实际体验好很多。宽限时间的逻辑关系是：任务超时时间 < 优雅退出宽限时间 < 系统强杀时间。三层必须形成阶梯，否则要么任务被中途砍断，要么进程被强杀留下脏状态。

3.5 部署：单元文件里那几个必须改的字段

打包好之后，用一个系统服务来托管它，崩了自动拉起，开机自动启动。单元文件里默认的几个行为对常驻服务不友好，需要调整。

[Unit] Description=colibri lightweight task runner After=network-online.target Wants=network-online.target [Service] Type=simple User=colibri Group=colibri WorkingDirectory=/opt/colibri ExecStart=/opt/colibri/colibri -config /etc/colibri/config.yaml ExecReload=/bin/kill -HUP $MAINPID Restart=always RestartSec=2 LimitNOFILE=65536 KillMode=mixed KillSignal=SIGTERM TimeoutStopSec=20 MemoryMax=256M LogRateLimitIntervalSec=0 [Install] WantedBy=multi-user.target

KillMode=mixed这一项经常被忽略。默认值是 control-group，意思是停止服务时先把主进程干掉，再干掉整个控制组里的所有进程。如果 colibri 会拉起子进程执行外部命令，主进程收到信号还没走完优雅退出流程，子进程就已经被清理掉了，容易出现“父进程在等一个永远等不到的子进程”的情况。mixed 模式是先给主进程发信号，等宽限时间过了再清理整个组，配合 TimeoutStopSec 使用，行为和预期更一致。

LimitNOFILE也得调。小设备上的默认文件句柄上限常常只有 1024，colibri 如果同时操作大量文件或连接，很容易撞到这个天花板，报出来的错误是“too many open files”，但如果你没有提前设置，排查时会往内存和逻辑方向找，绕一大圈。

ExecReload发 HUP 信号，对应前面实现的配置热加载，改完配置执行 reload 命令就能生效，不用重启进程，任务不中断。

3.6 观测：指标不用多，够查就行

常驻服务最怕黑盒。我在 colibri 里内置了一个 HTTP 端点，暴露纯文本格式的指标，任何成熟的采集器都能直接抓。指标不求多，这几类必须有：任务执行总数（按任务名和结果分类）、平均与最大执行耗时、队列当前深度、队列拒绝次数、重试次数、死信队列深度、当前活跃协程数、进程运行时长。

计数用原子操作维护，避免用锁把热路径拖慢。日志输出结构化格式，每条都带时间、级别、任务名、耗时、结果，这样在日志系统里可以直接按任务名聚合做趋势分析。

package metrics import ( "fmt" "net/http" "sync/atomic" ) var ( taskTotal int64 taskFailed int64 queueDepth int64 queueReject int64 retryTotal int64 deadLetter int64 activeWork int64 ) func IncTaskTotal() { atomic.AddInt64(&taskTotal, 1) } func IncTaskFailed() { atomic.AddInt64(&taskFailed, 1) } func IncQueueReject() { atomic.AddInt64(&queueReject, 1) } func AddActiveWork(d int64) { atomic.AddInt64(&activeWork, d) } func Handler(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "text/plain; version=0.0.4") fmt.Fprintf(w, "colibri_task_total %d\n", atomic.LoadInt64(&taskTotal)) fmt.Fprintf(w, "colibri_task_failed_total %d\n", atomic.LoadInt64(&taskFailed)) fmt.Fprintf(w, "colibri_queue_depth %d\n", atomic.LoadInt64(&queueDepth)) fmt.Fprintf(w, "colibri_queue_rejected_total %d\n", atomic.LoadInt64(&queueReject)) fmt.Fprintf(w, "colibri_retry_total %d\n", atomic.LoadInt64(&retryTotal)) fmt.Fprintf(w, "colibri_dead_letter_depth %d\n", atomic.LoadInt64(&deadLetter)) fmt.Fprintf(w, "colibri_active_workers %d\n", atomic.LoadInt64(&activeWork)) }

绑定地址要注意，指标端点默认只监听本地回环，不要直接暴露出去，需要外部采集就用反向代理转发，或者加一层认证。

4. 线上踩坑与排查实录

4.1 高频故障速查表

跑了小半年，攒下来一张排查表，基本都是我或者同事真遇到过的。

4.2 几个让我熬夜的坑

第一个坑是配置热加载的悬垂引用。我一开始的实现是替换配置指针，但正在执行的任务在启动时已经把旧配置里的参数拷了出来，理论上没问题。问题出在一个缓存对象上——它是按任务名缓存的，配置替换后缓存没清，新配置里的任务超时改了，实际跑的还是旧的超时，看起来就是“改了没用”。后来我在替换配置的同时加了一个版本号，缓存键里带上版本号，配置一变缓存自然失效，问题就没了。

第二个坑是调度器里的定时器重置。我最初用固定的 tick 间隔驱动调度循环，比如每 100 毫秒醒一次检查有没有任务到期。这在任务少的时候很浪费，任务多的时候又不够精确。更重要的是，如果某个任务的执行时间超过了 tick 间隔，下一轮检查时它已经被投递过了，就会出现重复投递。改成基于堆顶时间动态设置等待时长之后，浪费和重复都没了。

第三个坑是日志刷盘。为了性能，我把日志写到一个带缓冲的通道里，由单独的协程落盘。这个设计本身没问题，问题在于程序退出时没有等日志协程把缓冲刷完，最后几条关键日志（尤其是报错）就丢了，导致排查时最关键的信息缺失。修复方式是在退出流程里显式关闭日志通道并等待其排空，同时给日志协程设一个刷盘超时，避免磁盘慢的时候把整个退出流程拖住。

第四个坑是循环里的延迟调用累积。有个处理函数在循环里给每个子项都写了延迟关闭，循环几千次下来，几千个待执行调用堆在栈上，直到函数返回才一次性释放，内存曲线出现明显的锯齿。改成在循环内显式调用关闭，或者把循环体抽成独立函数，问题就消失了。这个坑在很多语言里都有对应版本，属于通用陷阱。

4.3 调优的一些经验值

跑了一段时间后，我整理出一些在小型设备上比较稳的默认值，你可以在自己的环境里作为起点再微调：执行池大小从核数的 2 倍起步，观察队列深度再上调；就绪队列深度按积压速率乘以 30 秒来定，多数场景落在 5000 到 20000 之间；重试队列和死信队列各开 2000 就够，它们的作用是留证据不是存数据；任务级超时按 P99 耗时的 2 到 3 倍设置，不要一刀切；优雅退出宽限时间设成任务最大超时再加 5 秒；日志按天轮转，保留 7 到 14 天，单文件不超过 50MB。

还有一条经验是关于指标告警阈值的。我一开始把死信队列深度大于 0 就告警，结果收到一堆噪音，因为偶尔一两条失败任务进了死信队列是完全正常的。后来改成“5 分钟内新增超过 10 条”才告警，误报率大幅下降，真正的故障也不会漏。队列深度告警同理，用持续超过容量 50% 一段时间作为条件，比瞬时值可靠得多。

最后再分享一个小技巧：如果你不确定某个参数该设多少，先把它做成可以通过环境变量覆盖的，上线后用保守值跑一周，把观测数据拉出来看分布，再定最终值。这比在办公室拍脑袋强得多，也比一上线就用激进参数稳得多。colibri 这类常驻小服务，真正的难点从来不在写代码，而在长期运行中保持资源占用和行为的可预期，把观测做足，把边界设清楚，剩下的就是让时间去验证了。