Posts on 潘达窝

OpenSandbox 源码走读（五·收官）：踩坑合集——3s 轮询、execd 限制与风险清单

Sun, 06 Sep 2026 20:11:17 +0800

OpenSandbox 源码走读（五·收官）：踩坑合集——3s 轮询、execd 限制与风险清单

系列最后一篇，不讲架构，专讲坑。调研和使用 OpenSandbox 过程中踩过、或者差点踩到的坑，按"现象 → 定位 → 根因 → 对策"整理成独立小节，可以直接当 checklist 用。

3s 轮询：任务调度的来龙去脉

这是我在这套代码里最重要的一个发现：批量任务型 sandbox 的整个调度闭环，是被一个写死的 3s 周期推着走的。

先看代码，kubernetes/internal/controller/batchsandbox_controller.go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func (r *BatchSandboxReconciler) reconcileTasks(
 ctx context.Context,
 batchSbx *sandboxv1alpha1.BatchSandbox,
 pods []*corev1.Pod,
) (*taskScheduleResult, error) {
 ...
 // Because tasks are in-memory and there is no event mechanism, periodic reconciliation is required.
 DurationStore.Push(types.NamespacedName{Namespace: batchSbx.Namespace, Name: batchSbx.Name}.String(), 3*time.Second)
 ...
}

注释说得很直白：task 是控制器进程内的纯内存对象，没有任何事件机制，所以只能周期性 reconcile。每 3 秒一轮，干三件事：

1
2
3
4


每 3s 一轮 Schedule():
 1. refreshFreePods() 重建空闲 pod 列表（一个 pod 同时只跑一个 task）
 2. collectTaskStatus() 并发 GET http://<podIP>:5758/getTasks 拉任务状态
 3. scheduleTaskNodes() 分配空闲 pod + POST /setTasks 下发任务 / 释放资源

现象：稳态下没有任何业务变化，控制器依然高频 reconcile。粗算一下，1000 个任务型 sandbox 就是稳态 333 reconcile/s，规模化后 CPU 和 API server 压力线性上涨。

根因：为什么不用事件驱动？我专门推演过改成 push 模式的可行性，结论是当前设计下很难：

约束	说明
归属路由	taskScheduler 在控制器内存里，pod 内的 task-executor 根本不知道该上报给哪个实例（leader 还会切换）
可靠性	上报会丢（控制器重启/网络抖动），需要 ack/重试/补偿；轮询天然幂等
调度动作仍需驱动	新任务下发、释放、删除回收都靠周期性 reconcile 推进状态机，状态上报替代不了

也就是说 pull 不是偷懒，是"task 状态存在 pod 内 HTTP 服务里 + 调度器在内存里"这个结构下的必然选择。3s 是"可感知粒度"的妥协——HTTP 默认超时也是 3s（kubernetes/internal/scheduler/default_scheduler.go 里 defaultTimeout = 3 * time.Second）。

但真正的坑在放大效应。第一处，状态收集是无界全并发，kubernetes/internal/scheduler/status_collector.go：

1
2
3
4
5


func (s *defaultTaskStatusCollector) Collect(ctx context.Context, ipList []string) map[string]*api.Task {
 semaphore := make(chan struct{}, len(ipList)) // ← 容量 = pod 数，等于没有限流
 ...
 s.logger.Info("Collect task status", "result", utils.DumpJSON(ret)) // ← 每轮把全部任务状态序列化打 Info 日志
}

第二处，Pod 事件无过滤，batchsandbox_controller.go 的 Owns(&corev1.Pod{}) 没挂任何 predicate——任意 Pod 状态波动都触发整池 reconcile。第三处，RequeueAfter 走 AddAfter，绕过了 workqueue 的指数退避限流（限流只保护返回 error 的路径）。

对策：

这个 3s 目前改不了，只能缓解：调大 --concurrency=batchsandbox，把状态收集日志降到 Debug；
自己写集成时，任务型 sandbox 的规模要做预估算，别等 reconcile 延迟失控才发现；
如果要改事件驱动，可行路径是 task-executor 在任务终态写回 CR status，控制器 watch 触发 + 低频兜底轮询防丢——但代价正是现在这套设计刻意规避的 API server 写放大。

说实话我一开始以为这是个能顺手修掉的"缺陷"，读完整个调度链才发现它是结构性的：内存态调度器 + pod 内 HTTP 状态源，这两个决定摆在那，轮询就是唯一自洽的方案。要根治得动数据流，不是改个时间常数的事。

execd 目录列表：六个限制一次说清

插件场景（通过 execd 读沙箱内文件系统）最容易在这里翻车，尤其是大目录。

接口是 execd 的 POST /directories/list，契约在 specs/execd-api.yaml，实现全在 components/execd/pkg/web/controller/filesystem.go。六个限制，逐个对应代码：

1. depth 默认 1，depth=0 返回空数组

1
2
3
4
5
6
7
8
9


depth := 1
if rawDepth := c.ctx.Query("depth"); rawDepth != "" {
 parsedDepth, err := strconv.Atoi(rawDepth)
 if err != nil || parsedDepth < 0 {
 c.RespondError(http.StatusBadRequest, ...) // ← 负数/非数字直接 400
 return
 }
 depth = parsedDepth
}

1
2
3
4
5
6
7


func listDirectoryEntries(root string, maxDepth int) ([]model.FileInfo, error) {
 entries := make([]model.FileInfo, 0, 16)
 if maxDepth == 0 {
 return entries, nil // ← depth=0 不是"不限深度"，是空数组
 }
 ...
}

第一眼看 depth=0 很容易理解成"不限制"，实际是返回空。想递归列全树只能一层层调。

2. 符号链接不穿透。root 是 symlink 直接拒绝：

1
2
3
4
5
6
7
8
9


// Use Lstat so a symlink passed as the root is detected and rejected
// rather than silently followed
info, err := os.Lstat(path)
...
if info.Mode()&os.ModeSymlink != 0 {
 c.RespondError(http.StatusBadRequest,
 fmt.Sprintf("path is a symbolic link, refusing to traverse: %s", path))
 return
}

遍历过程中的 symlink 只作为条目列出，不递归展开。/workspace 这类 symlink 路径会直接 400，要传真实路径。

3. 必须是目录：传文件路径 400，路径不存在 404。

4. 没有路径白名单：ExpandAbsPath 会展开 ~ 等，execd 以 root 跑在沙箱内，整个容器文件系统都能列（安全边界只剩容器本身的挂载视图）。

5. 没有数量/大小上限：listDirectoryEntries 递归无任何截断。列 /usr、node_modules 这种目录会返回巨大 JSON，撑爆响应体或客户端内存——这是实际影响最大的一个坑。

6. 只返回元数据：FileInfo（path/name/size/mode/is_dir/modified），不含内容，看内容要再调 read 接口。

对策：列目录前先用 depth=1 探一下规模，再按需深入；定向找文件改用 /files/search（支持 glob，默认 **，同样是 filepath.Walk 全量遍历、无数量上限，适合找文件而不是扫目录）。

第 2 条 symlink 拒绝我觉得设计是对的——Lstat 而不是 Stat，注释里明确写了理由：symlink-as-root 会暴露与调用者请求不同的子树。宁可 400 也不静默穿越，这个取舍值得学。

controller 已知缺陷清单

这一节是我对着源码逐条核过的，每条都标注了代码位置，按"会不会咬人"排序。

Helm 默认资源限额过小（kubernetes/charts/opensandbox-controller/values.yaml）：

1
2
3
4
5
6
7


resources:
 limits:
 cpu: 500m
 memory: 128Mi
 requests:
 cpu: 10m
 memory: 64Mi

控制器是全集群 informer 缓存（数百 MB 量级）+ 每 sandbox 调度器状态 + HTTP 轮询，128Mi 上限在批量创建/回收潮里很容易 OOM。上规模前先调大。

缩容未实现（batchsandbox_controller.go）：

1
2


// TODO var needDeleteIndex []int
// TODO consider supply Pods if Pods is deleted unexpectedly

两行 TODO 挨在一起，覆盖了两个坑：spec.replicas 调小不会删 Pod（只扩不缩）；Pool 模式下分配的 Pod 被外部删掉后，alloc-status 注解里的 Pod 名残留，supplement = replicas - len(allocated) 恒为 0，沙箱永久不可用。节点驱逐、OOM Kill 这种规模化最常见的场景正好命中后者。

恢复失败直接退出进程（kubernetes/internal/controller/allocator.go）：

1
2


// ... is terminated via os.Exit(1) because the allocator cannot operate with an ...
os.Exit(1)

首次 Schedule() 时 Recover 失败（全集群无选择器 List）→ 直接 os.Exit(1) → CrashLoop，且每次重启重试全量 List。RBAC 权限错误、API server 抖动都会触发，恢复逻辑没有降级路径。

pause 只支持单副本（batchsandbox_pause_resume.go）：

1

const supportedPauseReplicas int32 = 1

多副本请求 pause 会 ACK 回原 phase + PauseFailed(UnsupportedReplicas)。和"缩容未实现"组合成死锁：想 pause 多副本 → 得先缩到 1 → 缩不了。

每 pod 串行执行（kubernetes/internal/task-executor/manager/task_manager.go）：

1

maxConcurrentTasks = 1

一个 pod 同时只能跑一个任务，第二个直接报错。并发度完全由 spec.replicas 决定，任务排队只能靠扩容。

分配状态真相源是注解，整表覆盖写。每次分配把 pod 数组 JSON 整表 MergePatch 写 alloc-status 注解，并发分配时以最后一次写入为准，丢更新风险靠"先内存后注解、失败回滚"兜底。绕过内存 store 直接改注解会丢状态——注解是内部契约，别碰。

任务下发走裸 HTTP。调度器对 pod 内 5758 端口直连，无认证无鉴权，安全边界完全依赖 NetworkPolicy。部署时必须配。

这份清单里我最警惕的是缩容那条 TODO——它意味着"多副本"这个看起来很常规的能力，实际是半成品：不能缩、pause 不了、Pod 挂了不补。容量规划只能按只增不减来做。

风险清单：上游 open issues 里躲不掉的坑

调研时我们实际用不到 pause/resume，本来以为禁掉就能绕开一批问题。对着全部 open issues 逐个过完的结论是：绝大多数规模化风险和 pause/resume 无关，禁用也躲不掉。

P0 级，Pool 模式的复合缺陷（截至调研均无修复 PR）：

Issue	现象	要点
#1423	Pod 创建/删除风暴	每分钟创建 ~2250 / 删除 ~2290 个 pool Pod，约一半创建请求失败；重启控制器无效，~15 分钟复发
#954	分配的 Pod 被删后永不重绑	上面缩容 TODO 那条的上游 issue 化，沙箱永久不可用
#1433	`poolRef` 可变更导致 in-use Pod 被杀	CRD 无 `x-kubernetes-validations` 也无 admission webhook，运行中改 poolRef 触发破坏链且状态假报

#1423 有个特别阴的细节：缩容按 CreationTimestamp 升序删 idle Pod，“最旧空闲"在长启动时间下等于"刚启动完的”——正好把可服务的 buffer 删掉，留下 Pending，风暴自我维持。

「挂了自动拉起」不存在。上游明确 resume 只恢复有意的 Paused 状态，Terminated/Failed 不自动重启；重建 = 新 sandbox ID + 内存和未持久化状态全丢。这是集成设计的前提性结论：业务关键状态必须外置，“自动拉起 + 保 ID + 保状态"在当前上游语义下不可实现。

快照作为替代方案也有坑：带 egress sidecar（即启用 network_policy）的沙箱无法 snapshot（#1382，commit Job 对多平台 manifest 单平台化 push 失败）——几乎所有有网络隔离的真实工作负载都中招；快照删除不清理 registry 镜像（#1179），存储泄漏。

运维侧三个必知：

#1386：server 运行约 1 周后 httpx 连接池耗尽（当时并发只有 1-5 也复现），长期运行建议监控连接池并周期性重启；
#1408：server 只导出一个指标，还是 SDK 客户端上报的——不用 SDK 的部署一个指标都没有，约 40 种失败模式零计数，故障在指标层完全不可见；
#1409：egress 的 memory/cpu 指标实际读的是节点 /proc，却按 sandbox_id 打标签，N 个沙箱 = N 条相同的节点级假序列，监控基数爆炸。

对策压缩成五条：不假设任何自动恢复；Pool 模式先验证 #954/#1433 修复是否合入、CR 创建后禁止改 poolRef、小 pool 固定容量；批量释放别用 SDK 串行 releaseAllIdle（500 个空闲沙箱 ≈ 480s，自实现 50 并发可压到 ~150s）；快照方案避开 network_policy 并自行清理镜像；server 自建指标。

proxy 链路的业务事实

我们的业务里所有沙箱流量都走 server proxy，这一节是把 proxy 的行为事实单独拎出来，集成时逐条对过。

连接拓扑：

1
2
3
4
5
6
7


业务 / SDK（use_server_proxy=True）
 │ create / delete / renew-expiration（lifecycle API，直连 server）
 │ exec / 文件 / 健康检查（execd API，经 proxy 转发）
 ▼
OpenSandbox Server
 ├── proxy（/sandboxes/{id}/proxy/{port}/）──► 沙箱 execd（默认 44772）
 └── renew_intent consumer（proxy 访问触发自动续约）

每次 proxy 转发前依次执行（server/opensandbox_server/api/proxy.py）：解析沙箱内部端点 → secure-access token 校验（启用时缺头 401/403）→ 提交自动续约信号（非阻塞）→ 转发。

自动续约的生效条件，四个必须同时满足：服务端 [renew_intent] enabled = true；沙箱创建时 opt-in（extensions["access.renew.extend.seconds"] = 300~86400）；沙箱 Running；有过期时间。语义是 new_expires_at = max(now + extend.seconds, current_expires_at)，单调不减、幂等。

容易踩的边界：

端口必须已暴露：proxy 只对创建沙箱时暴露的端口生效，execd 的 44772 没暴露就是 404/502；
runtime-id 门禁：pod 被重建后旧 id 返回 409 RUNTIME_REPLACED，调用方要按响应里的 runtime_id 切换，这个 409 实际是"环境已重置"的信号；
伪永久沙箱不续约：创建不传 timeout 则 expiresAt=null，永不自动终止，自动续约机制完全跳过；反过来过期了的沙箱想用 renew-expiration 补时间也是 409——TTL 是单向的；
HTTP 的 Upgrade: websocket 会 400，WebSocket 走 proxy 的独立路由；
敏感 header 不转发：authorization/cookie 会被剥掉。

我们的选型结论：池化会话走伪永久 + 上层主动删除，不 opt-in 续约，业务 delete 时由中间层 postStop 兜底回写状态；需要"空闲回收"兜底时才改 TTL + opt-in，让活跃会话经 proxy 自动续命。两条路径都不需要 Redis（proxy-only 模式本地冷却就够）。

proxy 这个设计我比较欣赏的是续约信号的放置位置：挂在每次转发的必经路径上、非阻塞提交，活跃会话自然续命，不活跃自然过期——业务侧完全无感。缺点是多副本部署时可能重复续约（好在幂等，无害）。

结

把全系列五篇的坑浓缩成一张最终 checklist：

1
2
3
4
5
6
7
8
9


[ ] 任务型 sandbox 规模预估算过 3s 轮询的 reconcile 压力了吗
[ ] 列大目录前先 depth=1 探了吗；symlink 路径换成真实路径了吗
[ ] Helm 限额（128Mi/500m）按实际规模调过了吗
[ ] 接受"缩容未实现、Pod 挂了不补"了吗（容量只增不减）
[ ] 业务关键状态外置了吗（自动拉起不存在，重建 = 新 ID + 丢状态）
[ ] Pool 模式验证过 #954/#1433 修复了吗；poolRef 锁死了吗
[ ] NetworkPolicy 配了吗（task 下发是裸 HTTP）
[ ] server 自建指标了吗（自监控约等于零）
[ ] 长期运行的 server 有 httpx 连接池监控吗

五篇走读到这收官。从 controller 的 reconcile 闭环、lease 生命周期与续约、池化的模板/注入/S3 会话同步、出口网络的策略与池化出口，最后落到这篇的坑清单——我对 OpenSandbox 的整体判断没变过：架构思路（池化 + 内存态调度 + 注解契约）足够轻快，但工程完备度和它宣传的生产可用之间还有明显距离，规模化路径上的每一个坑几乎都指向同一个根源：内存态 + 无事件机制 + 无界结构。用它，就得按它的真实边界来设计，而不是按文档承诺来设计。

OpenSandbox 源码走读（四）：出口网络——NetworkPolicy、Egress Sidecar 与池化出口

Sun, 06 Sep 2026 20:10:55 +0800

OpenSandbox 源码走读（四）：出口网络——NetworkPolicy、Egress Sidecar 与池化出口

沙箱平台最尴尬的问题之一：用户在沙箱里跑的代码是不可信的，但它偏偏需要出网——调 LLM API、拉 GitHub、装 pip 包。这一篇讲 OpenSandbox 怎么管住这条出口：先拆 egress sidecar 的内部实现，再对比 K8s 原生 NetworkPolicy 为什么不行，最后是我结合自己 Higress 背景想聊的池化出口 + 网关分层方案。

egress sidecar：共享 netns 的透明拦截器

egress 是按需挂载的 Go sidecar（components/egress/），和沙箱应用容器共享网络命名空间。它的定位很克制：只做 L3/L4 + DNS 层的出口管控，L7 明确不做。

先看它什么时候会被挂进 Pod。server/opensandbox_server/services/k8s/egress_helper.py：

1
2
3


def apply_egress_to_spec(..., network_policy, egress_image, ...):
 if not network_policy or not egress_image:
 return # 两个条件缺一个，egress 根本不会出现

也就是：请求带了 network_policy，且 server 配了 [egress] image，才有 sidecar。不传策略的沙箱出站完全不受限——这是个容易误解的默认行为，管控是 opt-in 的。

安全模型的核心在同一个文件里：

1
2
3
4
5
6


def build_security_context_for_sandbox_container(has_network_policy, ...):
 if not has_network_policy:
 ...
 return {
 "capabilities": {"drop": ["NET_ADMIN"]},
 }

启用网络策略时，server 会把沙箱容器的 NET_ADMIN 摘掉，只有 egress sidecar 保留——沙箱里跑的恶意代码没法自己改 iptables 绕过拦截。这一手比任何规则配置都重要，规则再严，用户能改规则就全白搭。

启动流程在 components/egress/main.go，顺序即依赖：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


initialRules, _, err := policy.LoadInitialPolicyDetailed(...)
if err != nil {
 log.Fatalf("failed to load initial egress policy: %v", err) // fail-closed
}
alwaysDeny, alwaysAllow, err := policy.LoadAlwaysRuleFiles()
...
proxy.Start(ctx) // DNS 代理先起，127.0.0.1:15353
...
if err := iptables.SetupRedirect(15353, exemptDst); err != nil {
 log.Fatalf("failed to install iptables redirect: %v", err)
}
setupNft(...) // dns+nft 模式下加载 nftables 链
...
policySrv, err := startPolicyServer(...) // HTTP API :18080
mitm, err := startMitmproxyTransparentIfEnabled() // 可选，实验特性

值得注意的失败模式：全链路 fail-closed。初始策略解析失败、iptables 装不上、nft 加载失败，一律 log.Fatalf 退出，靠 supervisor 重启——宁可沙箱不可用，不带病放行。早期 OSEP 里"没有 CAP_NET_ADMIN 时降级继续运行"的设计已经废弃了，现在 /healthz 不就绪的 Pod 根本不会被分配流量。

熟悉我的老读者知道我写过 Higress 的 failover 逻辑，所以看到 egress 的 DNS 上游处理时有点亲切感：NXDOMAIN/NOERROR 不重试（这是权威答案），其他 rcode 才 failover 到下一个上游。语义是对的。

两层拦截：DNS 代理 + nftables 动态放行

egress 的核心思路是把"域名白名单"这个 L7 概念拆成两层落地：DNS 层管域名，IP 层管连接。策略模型本身只有 action + target 两个字段。

策略解析在 components/egress/pkg/policy/policy.go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


func normalizePolicy(p *NetworkPolicy) error {
 ...
 if ip, err := netip.ParseAddr(r.Target); err == nil {
 r.targetKind = targetIP // 纯 IP
 r.ip = ip
 continue
 }
 if prefix, err := netip.ParsePrefix(r.Target); err == nil {
 r.targetKind = targetCIDR // CIDR
 r.prefix = prefix
 continue
 }
 // 否则按域名处理

specs/egress-api.yaml 里那句 “IP/CIDR not yet supported in the egress MVP” 是过时注释，实现早就支持了。另外 ParsePolicy 对空策略的处理是 "" / null / {} → DefaultDenyPolicy()——空策略即 deny-all，不会手滑变成全放行。

Layer 1：DNS 代理。iptables 把所有 53 端口流量重定向到本机代理（pkg/iptables/redirect.go）：

1
2
3
4


{"iptables", "-t", "nat", op, "OUTPUT", "-p", "udp", "--dport", "53",
 "-m", "mark", "--mark", constants.MarkHex, "-j", "RETURN"}, // ← 防自递归
{"iptables", "-t", "nat", op, "OUTPUT", "-p", "udp", "--dport", "53",
 "-j", "REDIRECT", "--to-port", targetPort},

代理自己向上游发的查询打上 mark 先 RETURN 跳过，否则会无限套娃。上游地址必须是字面 IP，hostname 会再次命中重定向。IPv4/IPv6 双栈都装，nft 后端装不上 iptables 时还有一套原生 nft redirect 回退（opensandbox_dns_redirect 表）。

被拒域名在 pkg/dnsproxy/proxy.go 的处理：

1
2
3
4
5
6
7
8


if currentPolicy != nil && currentPolicy.Evaluate(domain) == policy.ActionDeny {
 telemetry.RecordDNSDenied()
 p.publishBlocked(domain)
 resp := new(dns.Msg)
 resp.SetRcode(r, dns.RcodeNameError) // 被拒 = NXDOMAIN
 _ = w.WriteMsg(resp)
 return
}

Layer 2：nftables（dns+nft 模式）。pkg/nftables/manager.go 的 buildRuleset 生成的链结构：

1
2
3
4
5
6
7
8
9


ct state established,related accept # 存量连接放行，策略变更不掐断
meta mark <MarkHex> accept # 代理自身流量
oifname "lo" accept # 回环
ip daddr 127.0.0.1 udp/tcp dport 15353 accept
tcp/udp dport 853 drop # DoT 默认阻断，防 DNS 绕过
ip daddr @deny_v4/v6 drop # 静态 deny 集
ip daddr @dyn_allow_v4/v6 accept # 动态 allow 集（DNS 解析产物）
ip daddr @allow_v4/v6 accept # 静态 allow 集
drop # defaultAction: deny 兜底

动态集的 TTL 设计在 pkg/nftables/dynamic.go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const (
 dynSetTimeoutS = 360
 nftTTLSlackSec = 60 // 比 resolver 缓存多活 60s，减少竞态
 minTTLSec = 60
 maxTTLSec = 360 // max DNS TTL (300) + slack
)

func clampTTL(d time.Duration) time.Duration {
 sec := int(d.Seconds()) + nftTTLSlackSec
 sec = min(max(sec, minTTLSec), maxTTLSec)
 return time.Duration(sec) * time.Second
}

放行的域名解析出的 IP 带 TTL 进动态集；连接跟踪器每 30s 扫 /proc 里的活跃 TCP 连接续期（只跟踪 TCP，UDP/QUIC 靠 DNS TTL 自然过期）。还有一个容易忽略的时序细节，proxy.go 的注释写得很明白：

1
2


// maybeNotifyResolved calls onResolved before w.WriteMsg so dynamic nft allows are installed
// before the client receives the answer and may open a connection.

nft 放行在 DNS 响应返回给客户端之前同步完成——否则客户端拿到 A 记录立刻建连，会被还没更新的 nft 规则丢掉，变成玄学超时。

这套设计的弱点也很清楚：IP/CIDR 规则只在 dns+nft 模式生效，纯 dns 模式下 DNS 层直接跳过非域名规则。另外端口维度完全没有——NetworkRule 就没有 port 字段，后面讲 Higress 分层时会回到这个问题。

为什么不用 K8s NetworkPolicy

这是官方 docs/architecture/network-isolation.md 里明确的选择，我在源码层面核了一遍，结论成立：不是 NetworkPolicy 不好，是它的语义模型和沙箱场景不匹配。

维度	K8s NetworkPolicy	egress sidecar
控制点	集群网络层（CNI 数据面）	沙箱 Pod 内部（共享 netns）
控制对象	Pod 集合（namespace + label selector）	单个沙箱（per-sandbox）
域名级控制	原生不支持（需 Cilium `toFQDNs` 扩展）	原生支持 FQDN 白名单
动态调整	静态 YAML，改规则要 apply	运行时 API（`POST/PATCH /policy`）实时生效
平台/用户双层	只有平台级（集群管理员 RBAC）	`deny.always`（平台不可覆盖）+ 用户策略
额外开销	无	每沙箱多一个容器 + `NET_ADMIN` 攻击面
gVisor 兼容	无关（运行时透明）	不兼容（netstack 不实现 iptables nat 表）

三个致命的不匹配：

一，label 不可预测。 沙箱 Pod 的 label 由平台自动注入，不同租户/安全级别的沙箱可能共享同一套 label。NetworkPolicy 靠 label selector 划边界，边界本身不可控，规则写得再细也是空中楼阁。

二，生命周期错位。 沙箱秒级创建销毁，NetworkPolicy 是静态声明。“默认拒绝来自所有其他沙箱的访问"是 per-sandbox 语义，用 Pod 集合语义表达要为每个沙箱单独建规则，且永远覆盖不到下一个创建的沙箱。

三，出站控制天然弱。 NetworkPolicy 的 Ingress 能挡入站，但挡不住沙箱进程主动 curl 另一个沙箱的 Pod IP。要挡出站得 Ingress+Egress 双向配，又绕回前两个问题。而沙箱场景最常用的"允许访问 api.github.com“这种域名规则，原生根本不支持。

再往下挖一层是语义差异。NetworkPolicy 是网络管理员视角——“这个网段允许访问那个网段”；egress 是沙箱视角——“这个沙箱允许访问哪些域名”。多租户场景里用户根本不该知道集群的 Pod/Service CIDR（这本身是敏感信息），egress 让用户只声明域名，CIDR 知识留在平台侧。

一个实际的细节：启用策略时 server 摘掉沙箱容器 NET_ADMIN、只留给 sidecar（前面贴过的 build_security_context_for_sandbox_container），所以沙箱内进程无法绕过。NetworkPolicy 场景下这个前提都不需要，因为策略在集群层，沙箱内根本摸不到。

但 egress 的代价也要列清楚：

缺点	说明
需要 `NET_ADMIN`	只给 sidecar，但镜像/部署复杂度和审计面是实打实增加的
与 gVisor 不兼容	netstack 没有 iptables nat 表，REDIRECT 无效；只能改 Kata 或 CNI 级 FQDN 策略
与透明 mesh 冲突	Istio/Envoy sidecar 同在一个 netns 重写流量，二选一
资源开销	每个受控沙箱多一个容器（内存/CPU/镜像拉取）
只管出站	沙箱间入站隔离仍要靠 `deny.always` 挡 Pod CIDR 间接实现

我的判断：OpenSandbox 选 egress 当主力不是"sidecar 模式先进”，而是沙箱平台的三要素——多租户、动态生命周期、域名级出站白名单——每一个都踩在 NetworkPolicy 的语义盲区上。NetworkPolicy 合理的位置是补充：集群内入站隔离、挡 Pod CIDR，跟 Cilium 这类 CNI 配合做 egress 方案的降级备选（gVisor 场景）。

池化模式：策略必须预置进模板

池化（Pool）是预热沙箱的经典套路——先创建一批 Pod 备着，请求来了直接分配。但这和"创建时注入 sidecar"天然冲突：Pod 已经存在了，生命周期 API 没法往里塞容器。

约束很硬：networkPolicy 与 extensions.poolRef 同时使用会被 server 直接拒绝（HTTP 400）。正确做法是把 egress 容器手动写进 Pool 的 spec.template（完整 corev1.PodTemplateSpec，Schemaless 原样透传）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


- name: egress
 image: opensandbox/egress:v1.1.6
 securityContext:
 capabilities:
 add: ["NET_ADMIN"] # 缺失则 sidecar 启动失败（fail-closed）
 env:
 - name: OPENSANDBOX_EGRESS_MODE
 value: "dns+nft" # IP/CIDR 规则仅此模式生效
 - name: OPENSANDBOX_EGRESS_RULES
 value: '{"defaultAction":"deny","egress":[{"action":"allow","target":"api.github.com"}]}'
 - name: OPENSANDBOX_EGRESS_TOKEN
 value: "<token>" # 不设则 18080 无认证，能连上就能改策略
 readinessProbe:
 httpGet: {path: /healthz, port: 18080}

由此带来几个池化特有的坑：

坑	后果
所有沙箱共享模板策略	每请求独立的 `network_policy` 在 pool 模式不生效，模板级统一管控
`OPENSANDBOX_EGRESS_SANDBOX_ID` 无法注入	egress 审计/deny webhook 的 payload 里 `sandboxId` 为空，无法归因到具体沙箱
模板变更不追溯	已预热的 Pod 继续执行旧策略，要滚动更新 Pool 才生效
运行时 patch 需要预置 token	分配后仍可动态改策略（SDK 走 server 鉴权），但模板必须先带 token

sandbox_id 归因缺失是我认为池化模式目前最实际的短板：一个 Pool 服务多个租户时，deny webhook 只知道"有沙箱撞了黑名单”，不知道是谁。审计闭环断了。

池化出口 + Higress：粗粒度给 sidecar，细粒度给网关

这是我自己方案里最想展开的部分。egress 的能力边界卡在两个地方：没有端口维度、没有 L7。企业内网场景（内部 HTTP API、NodePort 服务）恰好需要这两样。既然集群里已有 Higress 网关，与其改造 egress，不如分层。

先固化平台级基线。/var/egress/rules/deny.always（优先级高于用户策略，每分钟热加载，用户不可覆盖）：

1
2
3
4
5
6
7
8
9


# 平台组件 Service DNS
opensandbox-server.opensandbox.svc.cluster.local
opensandbox-ingress-gateway.opensandbox.svc.cluster.local
# 集群内部 CIDR：平台组件 + 沙箱间互访一刀切
10.244.0.0/16 # Pod CIDR
10.96.0.0/12 # Service CIDR
# 上层业务运行时
10.40.0.0/16
*.admin.corp

用户策略（Pool 模板）只放外部服务和网关：

1
2
3
4
5
6
7
8
9


{
 "defaultAction": "deny",
 "egress": [
 {"action": "allow", "target": "api.openai.com"},
 {"action": "allow", "target": "*.pypi.org"},
 {"action": "allow", "target": "higress-gateway.corp.internal"},
 {"action": "allow", "target": "10.20.0.0/16"}
 ]
}

分层架构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


沙箱应用容器
 │
 ▼
egress sidecar（dns+nft，defaultAction: deny）
 │ 只放行：外部服务域名 + Higress 网关
 ├──────────────► 外部服务（LLM / GitHub / 包源）——域名直连
 │
 ▼
Higress 网关（L7：路径级 allow/deny、认证、限流）
 │
 ▼
内部服务（HTTP API / NodePort 服务）

分工：

层	职责	粒度
egress	默认拒绝 + 白名单；强制内部流量必须走网关；隔离平台组件/业务运行时	域名 / IP / CIDR
Higress	路径/方法级 allow/deny、认证、限流	HTTP 路由

关键机制是egress 把集群内部 CIDR 全 deny，只放行网关——沙箱想访问内部服务，物理上只有 Higress 一条路。这样 L7 管控点天然收口到网关，Higress 上配路由级策略就够，不用关心流量从哪个沙箱来。这个思路对做网关的人来说很自然：L3/L4 收口是防火墙的活，L7 治理是 API 网关的活，别让一个组件干两层的事。

落地时有三个必须踩准的点：

一，内部 Service 要双重放行。 访问集群内 Service，域名（过 DNS 层）和 ClusterIP CIDR（过 nft 层）必须同时 allow。只放域名会出现最迷惑的现象：nslookup 正常，TCP 连接超时——nft 把包丢了，而且动态放行失败在沙箱内看和策略拒绝不可区分。

二，通配符不匹配裸域。 *.pypi.org 匹配不到 pypi.org 本身（domain_index.go 里 exact map 和 wildcard suffix map 是分开的），要两条都加。

三，NodePort 看场景。 专用节点池就 allow 节点网段（如 10.30.1.0/24）；共享节点无法按端口区分，必须让服务走 Higress（网关以 NodePort 暴露，egress 只放网关节点 IP），或者改 ClusterIP + 网关转发。

验证不能只看策略文本，要实测行为：

1
2
3
4


osb egress get <sandbox-id> -o json # 确认 mode=deny_all, enforcementMode=dns+nft
osb command run <sandbox-id> -o raw -- curl -I https://api.github.com # 放行 → 200
osb command run <sandbox-id> -o raw -- curl -I https://blocked.corp # 阻断 → NXDOMAIN
osb command run <sandbox-id> -o raw -- curl -I http://10.244.0.5 # 阻断 → 超时

注意 nft 链放行 established,related，改策略不掐存量连接——验证必须用新连接，不然测的是旧规则。

如果要在生产用这套组合，我会先补三件事：pool 模式的 sandbox_id 归因（比如 egress 支持分配时注入）、egress.nftables.updates.failed_total 指标的告警（动态放行失败是 fail-closed 静默故障，现象和策略拒绝一模一样）、以及一份按实际集群 CIDR 生成的 deny.always 模板——CIDR 写错要么误放行要么误阻断，且都很难从现象反推。

出口网络这条线到这里基本闭环了：组件内部实现 → 与 K8s 原生方案的取舍 → 池化 + 网关分层。整个 OpenSandbox 源码走读系列的下一篇也是收官篇，会把前面几篇没展开的踩坑合集一次性倒出来。

系列索引：（一）CRD Controller 与 Reconcile 循环 · （二）Sandbox Lease 与生命周期管理 · （三）池化设计；下一篇（收官）：踩坑合集。

OpenSandbox 源码走读（三）：池化设计——Template 更新、分配注入与 S3 会话同步

Sun, 06 Sep 2026 20:10:52 +0800

OpenSandbox 源码走读（三）：池化设计——Template 更新、分配注入与 S3 会话同步

前两篇看了 CRD 模型和创建链路，这篇讲我觉得整套系统里工程含金量最高的部分：池化。AI agent 场景下沙箱创建动辄十几秒，用户等不了——所以要把 pod 提前建好捂热，create 时直接分配。但"复用已运行的 pod"这个约束会连锁引出一堆问题：模板更新了怎么办？用户身份怎么在分配时刻注进去？上一个用户的会话数据怎么保证不串到下一个用户？这篇沿着"模板 → 池 → 分配 → 会话同步"把这条线走完。

为什么要池化

非池化路径下，create 一个沙箱意味着：调度 pod → 拉镜像 → 启动容器 → execd 就绪，整个链路秒级起步、镜像大了奔着分钟去。agent 场景里这是不可接受的——用户发一条消息，agent 要在对话内频繁开沙箱跑代码，没人愿意等十几秒的"白屏"。

池化的思路很朴素：用 Pool CRD 预先按模板创建一批 pod 捂着，业务 create 时带 extensions.poolRef，server 不再建 pod，而是从池里挑一个已运行的分给这个 BatchSandbox：

flowchart LR
A[业务 create poolRef] --> B[server 建 BatchSandbox CR]
B --> C[PoolReconciler 分配预热 pod]
C --> D[taskTemplate 下发到 pod 内 task-executor]
D --> E[返回 create 成功]

pod 建好之后所有动作都发生在"已运行的容器"里，这就是池化一切设计的出发点。

Template 更新：sha256 版本号 + 只换空闲 pod

Pool 的模板版本不是手填的，是控制器对 spec.template 做 sha256 算出来的：

1
2
3
4
5
6
7
8
9


// kubernetes/internal/controller/pool_controller.go
func (r *PoolReconciler) calculateRevision(pool *sandboxv1alpha1.Pool) (string, error) {
 template, err := json.Marshal(pool.Spec.Template)
 if err != nil {
 return "", err
 }
 revision := sha256.Sum256(template)
 return hex.EncodeToString(revision[:8]), nil // ← 取前 8 字节做版本号
}

新创建的 pod 会打上 sandbox.opensandbox.io/pool-revision 标签（createPoolPod 里 pod.Labels[LabelPoolRevision] = updateRevision），这样池子里每个 pod 属于哪个版本一目了然。

更新策略有个关键前提：只处理 idle pod。scheduleSandbox 里 idle 的定义是"Ready 且未被分配"：

1
2
3
4
5
6
7
8


// kubernetes/internal/controller/pool_controller.go
latestAllocation, err := r.Allocator.GetPoolAllocation(ctx, pool)
idlePods := make([]string, 0)
for _, pod := range pods {
 if _, ok := latestAllocation[pod.Name]; !ok { // ← 被分配的不算 idle
 idlePods = append(idlePods, pod.Name)
 }
}

recreateUpdateStrategy.Compute（pool_update.go）的签名直接把这一点写在了参数上：

1
2


Compute(ctx context.Context, updateRevision string,
 pods []*corev1.Pod, idlePods []string) *UpdateResult

替换节奏受 UpdateStrategy.MaxUnavailable（默认 25%）预算控制，空闲 pod 分批删旧建新。GenerationChangedPredicate 保证只有 spec 变更才触发 reconcile，status 抖动不会引发无谓轮询。

只换 idle pod 是对的——已分配的 pod 背后有活着的沙箱，删了就是事故。但它带来一个容易被忽略的推论：如果池子里所有 pod 都被分配了，updatePool 算出 SupplyUpdateRevision = 0，一个新 pod 都不会建，整个池子停留在旧版本，而且没有任何告警。升级模板前得先看一眼分配率。

分配：先到先得，不认版本号

分配算法在 algorithm/packed.go，简单到值得整段贴出来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


// kubernetes/internal/controller/algorithm/packed.go
type PackedSchedule struct{}

func (p *PackedSchedule) Schedule(availablePods []string, allRequest []*SandboxRequest) *AllocAction {
 action := &AllocAction{
 ToAllocate: make(map[string][]string),
 ToRelease: make(map[string][]string),
 PodSupplement: int32(0),
 }
 for _, req := range allRequest {
 // ... 收集 release 请求 ...
 need := req.PodSupplement
 if need <= 0 { continue }
 if int32(len(availablePods)) >= need {
 action.ToAllocate[req.SandboxName] = availablePods[:need] // ← 按列表顺序切
 availablePods = availablePods[need:]
 } else if len(availablePods) > 0 {
 action.ToAllocate[req.SandboxName] = availablePods
 action.PodSupplement += need - int32(len(availablePods)) // 不够就补建
 availablePods = nil
 } else {
 action.PodSupplement += need
 }
 }
 return action
}

availablePods 就是上一节的 idle 列表——注意它不区分 revision，新旧版本的 pod 混在一起先到先得。所以模板刚更新完，只要 idle 池里还剩旧 revision 的 pod，新沙箱就可能分到旧 pod。

分配关系的记录方式也值得注意：pod 上没有任何指向 BatchSandbox 的所有权标记。pod 只有 pool-name 和 pool-revision 两个标签，ownerReference 指向的是 Pool；分配关系单向记在 BatchSandbox 的注解上：

1
2
3
4


// kubernetes/internal/controller/apis.go
AnnoAllocStatusKey = "sandbox.opensandbox.io/alloc-status" // {"pods":["pod-a"]}
AnnoAllocReleaseKey = "sandbox.opensandbox.io/alloc-release" // 待释放
AnnoAllocReleasedKey = "sandbox.opensandbox.io/alloc-released" // 已释放

没有 pod → sandbox 的正向索引，查"这个 pod 属于哪个沙箱"只能反向遍历所有 BatchSandbox 的注解。控制器的 InMemoryAllocationStore 也是从注解 Recover 出来的，没有独立持久化——好处是注解即真相、重启可恢复，坏处是规模化之后反向查询会很疼。

分配时刻注入：taskTemplate 就是现成的通道

池化 pod 是预热的，分配时不能改 pod spec——initContainer、ConfigMap 挂载、env 注入这些"创建时生效"的手段全部失效。分配时刻能做的只有往运行中的容器里执行动作。

server 的做法是把注入打包进 taskTemplate。看 batchsandbox_provider.py 的真实代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# server/opensandbox_server/services/k8s/batchsandbox_provider.py
def _build_task_template(self, entrypoint, env, sandbox_id):
 escaped_entrypoint = ' '.join(shlex.quote(arg) for arg in entrypoint)
 if self.execd_run_as_init:
 user_process_cmd = f"exec /opt/opensandbox/bootstrap.sh {escaped_entrypoint}"
 else:
 user_process_cmd = f"/opt/opensandbox/bootstrap.sh {escaped_entrypoint} &"

 wrapped_command = ["/bin/sh", "-c", user_process_cmd]
 env_list = [{"name": k, "value": v} for k, v in env.items()] if env else []
 env_list.append({"name": "OPENSANDBOX_ID", "value": sandbox_id})
 return {"spec": {"process": {"command": wrapped_command, "env": env_list}}}

有个容易踩的坑藏在 _create_workload_from_pool 里：不传 entrypoint/env 时走快路径，直接不生成 taskTemplate：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


needs_task_template = (
 env
 or entrypoint != DEFAULT_ENTRYPOINT
 or self.execd_run_as_init
)
if needs_task_template:
 spec["taskTemplate"] = self._build_task_template(entrypoint, env, batchsandbox_name)
else:
 # Fast path: the pre-created pool pod keeps running its own warm
 # entrypoint, so no per-allocation env can reach execd.

快路径省一次任务下发，但代价是连 OPENSANDBOX_ID 都注入不了，注释里明说了这条路径上 eBPF 审计无法归属 sandbox_id。

“分配后注入"能成立，靠的是 controller 的 3 秒轮询链路：

1
2
3
4


server 创建 BatchSandbox（含 taskTemplate）
 → BatchSandboxReconciler 每 3s reconcile
 → taskTemplate 生成 task specs 下发到 pod 内 task-executor（:5758）
 → task-executor 先跑 preStart 钩子，再跑主命令

这引出一个关键的时序判断：taskTemplate 是 server 每次分配时生成的，create 请求里的动态参数（user_id、token）在生成那一刻就已知，所以可以直接渲染进命令——命令里 cat > file <<'EOF' 写文件、sh file 调脚本，注入和调用一次完成。执行天然发生在分配后，不需要新开 k8s exec 接口。exec 只在需要"分配后才知道的信息”（pod IP、运行时探测）时才值得引入。

token 这类敏感凭证注入时要小心：taskTemplate 的命令会进日志，user_auth_token 千万别拼进命令行，走 env 注入更稳。而且 Pool 模式下 Secret 挂载必须预挂进模板，分配时加不了——所以分配时刻注入 token 实际只有 env 和文件两条路。

S3 会话同步：固定 postStop + 中间层静默 exec

池化还有个更麻烦的问题：pod 是复用的，用户 A 用完回池，用户 B 分到同一个 pod 时绝不能看到 A 的文件。解法是把会话状态放 S3，按前缀隔离：

1

s3://<bucket>/tenants/<tenantId>/users/<userId>/sessions/<sessionId>/

架构上分三层，各管各的：

层	职责	时机
Pool 模板	共享 emptyDir `/shared-workspace`、task-executor 侧 S3 CLI + 凭证（IRSA）	一次配置
BatchSandbox	固定 postStop（与用户无关，所有沙箱一样）	建 CR 时带上
中间层	按用户渲染并注入 sync 脚本、触发 restore	分配后 exec

固定 postStop 长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


lifecycle:
 postStop:
 execMode: Local  # 在 task-executor 侧执行
 timeoutSeconds: 180
 exec:
 command: ["/bin/sh", "-c"]
 args:
 - |
 set -eu
 HOOK=/shared-workspace/.osb-sync-out.sh
 if [ -x "$HOOK" ]; then "$HOOK"; fi # ← 存在才跑，注入的回写脚本
 find /shared-workspace -mindepth 1 -delete # 清盘防串台

中间层的 create 流程对外仍然是一次普通的 create：

1
2
3
4
5
6
7
8


1. 解析身份 → S3_USER_PREFIX
2. 创建 BatchSandbox（poolRef + 固定 postStop 的 taskTemplate）
3. 等待分配的 pod Ready
4. 内部 pods/exec 到 task-executor 容器：
 a. 写入并 chmod +x /shared-workspace/.osb-sync-out.sh
 b. 后台启动 inbound restore（aws s3 sync ... || true），不等 CLI 结束
5. 标记会话已 prepare
6. 返回 create 成功

delete 时（主动删或 expireTime 到期）走同一条路：删 CR → finalizer → StopTask → postStop 跑 .osb-sync-out.sh 回写 S3 + 清盘 → pod 回池。到期删除也能回写，这是把回写放进 postStop 而不是让业务在 delete 前自己 sync 的核心理由。

为什么脚本要靠 exec 注入、而不是让固定钩子去读用户 env？我查了 task-executor 的实现，Local 钩子的环境是这么构造的：

1
2


// kubernetes/internal/task-executor/runtime/process.go
cmd.Env = os.Environ() // ← 只继承 task-executor 进程自身环境

钩子不继承 task 的 process.env，所以"create 时塞个 S3_USER_PREFIX env、固定 sync 脚本去读"这条路在当前实现下走不通——注入脚本把前缀写进文件，就是在绕这个限制。postStop 钩子在任务终态（成功/失败/超时/删除）时必执行，倒是销毁前持久化产物的可靠挂点。

这套设计里我最欣赏的是"动态与静态分离"：用户相关的东西（S3 前缀、脚本内容）由中间层运行时注入，用户无关的骨架（postStop 逻辑、清盘）固化在 CR 模板里。业务 SDK 全程只看到 create → 使用 → delete，pods/exec、S3 命令、脚本路径全都不出中间层。代价是链路变长了：中间层挂了恢复逻辑、postStop 失败是否阻塞回池、restore 还在跑就回池的竞态，这些都是要靠运维约定兜底的模糊地带。

shardTaskPatches：批量创建时的差异化补丁

最后补一个和 taskTemplate 配套的机制。BatchSandbox 支持一次创建 N 个沙箱，shardTaskPatches[i] 按下标对第 i 个副本的任务做覆盖，实现"批量创建、各跑各的"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


spec:
 replicas: 3
 taskTemplate:
 spec:
 process:
 command: ["python", "train.py"]
 args: ["--epochs", "10"]
 shardTaskPatches:
 - spec: { process: { args: ["--epochs", "10", "--lr", "1e-3"] } }
 - spec: { process: { args: ["--epochs", "10", "--lr", "1e-4"] } }
 # 副本 2 无 patch → 用默认 taskTemplate

合并逻辑在 task_scheduling_strategy_default.go，就是标准的 strategic merge patch：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


func (s *DefaultTaskSchedulingStrategy) getTaskSpec(idx int) (*api.Task, error) {
 task := &api.Task{Name: fmt.Sprintf("%s-%d", s.Name, idx)}
 if len(s.Spec.ShardTaskPatches) > 0 && idx < len(s.Spec.ShardTaskPatches) {
 taskTemplate := s.Spec.TaskTemplate.DeepCopy() // ← 在深拷贝上合并，不动原模板
 cloneBytes, _ := json.Marshal(taskTemplate)
 patch := s.Spec.ShardTaskPatches[idx]
 modified, err := strategicpatch.StrategicMergePatch(
 cloneBytes, patch.Raw, &sandboxv1alpha1.TaskTemplateSpec{})
 if err != nil {
 return nil, fmt.Errorf("batchsandbox: failed to merge patch raw %s, idx %d, err %w", patch.Raw, idx, err)
 }
 // ...
 task.Process = convertProcessSpec(newTaskTemplate.Spec.Process,
 s.Spec.TaskTemplate.Spec.TimeoutSeconds) // ← timeout 取基础模板
 } else if s.Spec.TaskTemplate != nil && s.Spec.TaskTemplate.Spec.Process != nil {
 task.Process = convertProcessSpec(s.Spec.TaskTemplate.Spec.Process,
 s.Spec.TaskTemplate.Spec.TimeoutSeconds)
 }
 return task, nil
}

几个容易记错的语义：env 数组按 name merge（同名覆盖、异名保留，patch 删不掉模板里的 env）；timeoutSeconds 永远取基础模板，patch 里改了不算数；patch 数量和 replicas 不匹配时静默兜底，多补丁忽略、少补丁用模板，没有告警。注意 server API 并不暴露 shardTaskPatches，只能直接操作 CR；server 的池化分配路径走的是单任务模板（_build_task_template），没有 shard 能力。 RL 训练/评测这类 “high-throughput agentic-RL” 场景是它的主场：配合 taskResourcePolicyWhenCompleted: Release，任务跑完 pod 立刻回池，批量沙箱用完即焚。

把这条链路串起来看，池化设计的精髓是"把不确定性往后推"：模板预热消灭冷启动，revision 机制管住模板演化，taskTemplate 把分配时刻的动态注入变成一次任务下发，postStop + S3 前缀把有状态会话塞进无状态池。每一环都不复杂，但约束传导得很干净——“复用已建 pod"这一条，决定了注入只能走任务下发、清理只能靠钩子、隔离只能靠外部存储。如果要说短板，我觉得是可观测性：快路径注入不了 ID、旧 revision 无告警、postStop 失败只记注解，这些都得自己补监控。

下一篇走读出口网络：沙箱的 egress 代理、token 鉴权和域名白名单是怎么做的。

OpenSandbox 源码走读（二）：Sandbox Lease 与生命周期管理

Sun, 06 Sep 2026 20:10:30 +0800

OpenSandbox 源码走读（二）：Sandbox Lease 与生命周期管理

沙箱这类"按需创建、用完即弃"的资源，最怕的不是创建慢，而是没人回收——客户端崩了、网络断了，服务端还替它养着一个占 CPU 占内存的容器。这次把 OpenSandbox 的 lease（租约）机制翻了一遍：TTL 怎么算、到期谁去杀、续约有几条路、以及"伪永久"模式的清理边界。代码基于 main 分支（2026-08 核对）。

为什么需要 lease：没有它会出什么事故

先想清楚问题。沙箱不是无状态的 HTTP 请求，它是一个持续占用资源的容器/ Pod。调用方（比如一个 Agent 运行时）创建沙箱后，可能：

进程崩溃，永远不会再发"删除"请求；
网络分区，删除请求丢了；
业务 bug，for 循环里创建了 1000 个沙箱然后忘了。

没有租约机制，这些沙箱就变成孤儿——API 层面查得到，但没人对它们负责。Docker 里一个容器几百 MB 内存，K8s 里一个 Pod 还带 sidecar，泄漏速度远超普通连接池。

OpenSandbox 的解法是经典的 lease 模型：创建时必须声明租期（或者明确声明不设租期），到期由服务端单方面回收。入口在创建请求的 timeout 字段（秒，最小 60），服务端换算成绝对时间戳：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# server/opensandbox_server/services/docker/docker_service.py
def _prepare_creation_context(
 self,
 request: CreateSandboxRequest,
) -> tuple[str, datetime, Optional[datetime]]:
 sandbox_id = self.generate_sandbox_id()
 created_at = datetime.now(timezone.utc)
 expires_at = None
 if request.timeout is not None:
 expires_at = calculate_expiration_or_raise(created_at, request.timeout) # ← createdAt + timeout
 return sandbox_id, created_at, expires_at

注意 timeout is None 这个分支——它不是"忘了传"，而是一个正式模式（后面讲）。租期计算和上限校验都在 services/validators.py：

1
2
3
4
5
6
7
8
9


# server/opensandbox_server/services/validators.py
def ensure_timeout_within_limit(timeout_seconds, max_timeout_seconds) -> None:
 if timeout_seconds is None:
 return # ← 伪永久模式，跳过校验
 calculate_expiration_or_raise(datetime.now(timezone.utc), timeout_seconds)
 if max_timeout_seconds is None:
 return # ← 服务端没配上限 = 不限
 if timeout_seconds > max_timeout_seconds:
 raise HTTPException(status_code=400, ...)

max_sandbox_timeout_seconds 是 [server] 配置里的 TTL 上限（config.py，默认 None 不限）。多租户部署建议配一个，否则调用方传个 timeout=999999999 也能过——虽然 calculate_expiration_or_raise 会把 datetime 溢出转成 400，但"合法地租一年"依然拦不住。

lease 存的是绝对时间戳（expiresAt）而不是剩余秒数，这个选择是对的：服务端重启、时钟回拨、续约覆盖，都以一个不可变的时间点为准，不需要维护递减计数器。

到期执行：Docker 定时器 vs K8s 控制器

expiresAt 算出来了，谁来负责到期杀沙箱？Docker 和 K8s 两条运行时走了完全不同的实现路线。

Docker 路线是进程内 Timer。每个沙箱一个 threading.Timer，续约时直接替换旧 timer：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# server/opensandbox_server/services/docker/docker_service.py
def _schedule_expiration(self, sandbox_id, expires_at, *, update_expiration=True, ...) -> None:
 delay = max(0.0, (expires_at - datetime.now(timezone.utc)).total_seconds())
 timer = Timer(delay, self._expire_sandbox, args=(sandbox_id,), kwargs=expire_kwargs or None)
 timer.daemon = True
 with self._expiration_lock:
 # Replace existing timer (if any) so renew operations take effect immediately
 existing = self._expiration_timers.pop(sandbox_id, None)
 if existing:
 existing.cancel()
 if update_expiration:
 self._sandbox_expirations[sandbox_id] = expires_at
 self._expiration_timers[sandbox_id] = timer
 timer.start()

进程内 Timer 有个致命问题：server 重启，内存里的 timer 全丢。所以启动时有一段 restore 逻辑，遍历所有容器 label 重建 timer，已过期的立即补杀：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# docker_service.py（启动恢复，简化）
expires_at = self._get_tracked_expiration(sandbox_id, labels)
if expires_at is None:
 if self._has_manual_cleanup(labels):
 restored += 1
 continue # ← 伪永久沙箱跳过调度
 ...
if expires_at <= now:
 expired_entries.append((sandbox_id, mount_keys)) # 已过期，pass 2 补杀
 continue
self._schedule_expiration(sandbox_id, expires_at)

_get_tracked_expiration 的查找顺序是内存缓存 → 文件元数据存储 → 容器 label，三层兜底保证重启后也能恢复租约。而 _expire_sandbox 的回调里还有个细节我挺喜欢——杀之前再查一次当前租约，续约竞态时放弃删除：

1
2
3
4
5


# docker_service.py
current_expires = self._get_tracked_expiration(sandbox_id, labels)
if current_expires and current_expires > datetime.now(timezone.utc):
 self._schedule_expiration(sandbox_id, current_expires, update_expiration=False)
 logger.info("Sandbox %s was renewed (expires %s); aborting expiration.", ...)

没有这个检查，就会出现"用户刚续约，过期定时器还是把沙箱杀了"的灵异事件。另外定时器触发时如果暂时查不到容器（瞬时报错），会 30 秒后重试而不是放弃——lease 到期是确定性的，只是延迟，不会丢。

K8s 路线完全没有定时器这回事，靠的是控制器 reconcile。expiresAt 写进 BatchSandbox CR 的 spec.expireTime，控制器每次 reconcile 检查：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// kubernetes/internal/controller/batchsandbox_controller.go
if expireAt := batchSbx.Spec.ExpireTime; expireAt != nil {
 now := time.Now()
 if expireAt.Time.Before(now) {
 if batchSbx.DeletionTimestamp == nil {
 log.Info("batch sandbox expired, delete", "expireAt", expireAt)
 if err := r.Delete(ctx, batchSbx); err != nil { ... } // ← 到期直接删 CR
 }
 } else {
 DurationStore.Push(...) // ← 未到期，把差值塞回去驱动下次 requeue
 }
}

两条路线对"到期后是删是留"还有一个共同的开关：shutdown_policy: Delete|Retain（config.py:700）。设成 Retain 时过期只终止不清理，用于调试或事后取证。

Timer（推）vs reconcile（拉）是分布式系统里到期处理的两种基本形态。Timer 精确但要自己处理重启恢复；reconcile 天然幂等、重启免费，但精度受 requeue 间隔限制。OpenSandbox 两种都用了，各自贴合运行时特性，这个选择没毛病。

手动续约：renew-expiration 的三条约束

租约要能续，否则长任务都得把 timeout 估到最大。续约 API 只有一个端点：

1
2


POST /sandboxes/{id}/renew-expiration
{ "expiresAt": "2026-08-19T12:00:00Z" } // 绝对时间，必填

路由是薄壳，直接委托 service 层（api/lifecycle.py:344-384）。真正有意思的是它背后的三条约束：

约束一：只能延长，不能缩短。 spec 里写死 “Must be in the future and after the current expiresAt time”，服务端校验在 validators.py：

1
2
3
4
5
6
7
8


def ensure_future_expiration(expires_at: datetime) -> datetime:
 if expires_at.tzinfo is None:
 normalized = expires_at.replace(tzinfo=timezone.utc) # naive 时间按 UTC 处理
 else:
 normalized = expires_at.astimezone(timezone.utc)
 if normalized <= datetime.now(timezone.utc):
 raise HTTPException(status_code=400, detail={"code": "INVALID_EXPIRATION", ...})
 return normalized

这意味着你不能通过续约来提前回收一个沙箱，也不能给伪永久沙箱"补"一个过期时间——后者直接 409：

1
2
3
4
5
6
7
8
9


# docker_service.py renew_expiration
if self._has_manual_cleanup(labels):
 raise HTTPException(
 status_code=status.HTTP_409_CONFLICT,
 detail={"code": SandboxErrorCodes.INVALID_EXPIRATION,
 "message": f"Sandbox {sandbox_id} does not have automatic expiration enabled."},
 )
if self._get_tracked_expiration(sandbox_id, labels) is None:
 raise HTTPException(status_code=409, ...) # ← label 丢失也拒绝，宁可不续

约束二：lease 状态要三处同步。 Docker 实现里，续约成功要同时改内存 timer、文件元数据、容器 label 三个地方：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# docker_service.py renew_expiration（注释是原文）
# Persist the new timeout in memory; the file-backed override also keeps renewals correct across restarts
self._schedule_expiration(sandbox_id, new_expiration)
try:
 self._metadata_store.set_expiration(sandbox_id, new_expiration)
except OSError as exc:
 logger.warning("Failed to persist expiration override ...") # ← 失败只记日志
labels[SANDBOX_EXPIRES_AT_LABEL] = new_expiration.isoformat()
try:
 with self._docker_operation("update sandbox labels", sandbox_id):
 self._update_container_labels(container, labels)
except (DockerException, TypeError) as exc:
 logger.warning("Failed to refresh labels ...")

三处里任何一处失败都是 warning 而不是报错——好在查找时有 fallback 链兜底，但严格说这不是事务性的。

约束三：K8s 侧要同步 CR 和 label。 kubernetes_service.py 的 renew_expiration 同时更新 BatchSandbox 的 spec.expireTime 和对应 label，保证 reconcile 逻辑和 kubectl 排障看到的值一致。

409 的设计值得玩味：续约不能作用于伪永久沙箱，这是一个用状态机拒绝而不是静默成功的例子。如果这里静默返回 200，调用方会以为沙箱有了租约，实际永远不会过期——比 409 危险得多。

自动续约（OSEP-0009）：访问即续命

手动续约要求调用方自己记得续，OpenSandbox 在 OSEP-0009 里做了访问驱动的自动续约：反向代理观测到流量，就替沙箱续一次命。

用法上就两步：创建沙箱时在 extensions 里 opt-in，之后所有经 server proxy 的调用（exec/文件/健康检查，转发前有 _schedule_proxy_renew 埋点）自动续期；ingress 模式额外开 Redis。但整条链路有一个唯一的坑，先说在前面——服务端开关。[renew_intent] enabled 默认 False，而创建时对 extension 的校验只查值的格式（300~86400 的字符串十进制整数），不查服务端开关。也就是说客户端全做对了、proxy 调用一切正常，server 没开开关就一个字都不续——proxy_renew.py 第 38 行直接短路返回，无日志无报错，沙箱到点照样被杀。排查"自动续约不生效"，第一个要看的不是客户端配置，是 server config 里这个开关。

opt-in 的合法性在创建时校验的只有这个：

1
2
3


# server/opensandbox_server/extensions/validation.py
ACCESS_RENEW_EXTEND_SECONDS_MIN = 300 # 5 分钟
ACCESS_RENEW_EXTEND_SECONDS_MAX = 86400 # 24 小时

1
2
3
4


{
 "extensions": { "access.renew.extend.seconds": "3600" },
 "timeout": 600
}

注意传的是字符串形式的十进制整数，范围 300~86400，非法值创建即 400。每次访问触发的续约量就是 now + extend.seconds。

触发源有两条路：

flowchart LR
A[客户端流量] -->|经 server proxy| B[ProxyRenewCoordinator
api/proxy.py 埋点]
A -->|经 ingress gateway| C[Go 侧 Publisher
components/ingress/pkg/renewintent]
B --> D[RenewIntentConsumer
统一 asyncio 队列]
C -->|Redis List| E[BRPOP feeder]
E --> D
D --> F{AccessRenewController 门控}
F -->|通过| G[renew_expiration]

所有路径最终汇到 integrations/renew_intent/controller.py 的门控，逻辑很收敛：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


def _try_renew_sync(self, sandbox_id: str, *, source: str) -> bool:
 try:
 sandbox = self._sandbox_service.get_sandbox(sandbox_id)
 except HTTPException:
 return False
 if sandbox.status.state.lower() != "running":
 return False # ← 非 Running 不续
 if sandbox.expires_at is None:
 return False # ← 伪永久沙箱不参与自动续约
 extend = self._extension_service.get_access_renew_extend_seconds(sandbox_id)
 if extend is None:
 return False # ← 未 opt-in 不续
 candidate = now + timedelta(seconds=extend)
 new_expires = max(candidate, current) # ← 单调不减，天然幂等
 ...

max(candidate, current) 这个写法保证了重复消费或乱序消费都不会把租约改小，配合每沙箱 asyncio.Lock 串行化，基本堵死了竞态。

坑都在外围。我对照实现把 OSEP 设计稿和代码过了一遍，这几个点值得记：

Redis 启用时 proxy 路径没有冷却。consumer.py 的 _process_work 里，self._redis is not None 时直接续约，完全跳过 min_interval 节流：

1
2
3
4
5
6
7
8


# consumer.py
async with st.lock:
 if self._redis is not None:
 await self._controller.renew_after_gates(work.sandbox_id, source=work.source)
 return # ← 无 min_interval 检查
 now = time.monotonic()
 if st.last_success_monotonic is not None and (now - st.last_success_monotonic) < self._min_interval:
 return

高 QPS 访问同一个沙箱时，续约 API 调用会非常频繁。续约本身幂等所以不出错，纯属浪费。

没有分布式锁。OSEP 设计了 opensandbox:renew:lock:{sandbox_id}，实现只有进程内 asyncio.Lock。多副本部署 proxy 模式会重复续约——反正 max() 单调不减，影响有限；ingress 模式靠 BRPOP 竞争天然去重。
best-effort 语义。intent 无 ack，消费后进程崩了就丢；超过 INTENT_MAX_AGE_SECONDS=300 的 intent 直接丢弃；ingress 发布队列满（容量 8192）直接 drop。自动续约是"尽力而为"，不能当强保证用。
Redis 不可用静默降级。连接失败降级为 proxy-only 模式，只打日志。ingress 场景下自动续约整个失效，但没有任何告警指标——沙箱会悄悄开始过期。
内存上限。proxy 路径每沙箱状态的 LRU 上限是 PROXY_RENEW_MAX_TRACKED_SANDBOXES = 8192（renew_intent/constants.py），超了驱逐（持锁的除外）。规模再大就要靠 Redis 模式了。

还有一个最容易被忽略的：SDK 默认不走 proxy。Python SDK 的 ConnectionConfig.use_server_proxy 默认 False，工具调用（exec/文件操作）直连沙箱 IP:44772 的 execd 端口——这条路径 server 根本观测不到流量，自动续约完全不生效。业务想要"活跃即续命"，必须显式走 proxy 或 ingress。

自动续约有个隐含的哲学转变：TTL 从"调用方声明的租期"变成了"最后一次访问之后的空闲超时"。这更像 HTTP session 而不是传统 lease。但 best-effort 的投递语义意味着它只能做兜底，关键业务还是应该显式管理租约。

伪永久（manual cleanup）： lease 的另一个极端

创建时不传 timeout，expiresAt 就是 None，schema 里的原文是：“When omitted or null, the sandbox will not auto-terminate and must be deleted explicitly”——不自动终止，必须显式删除。

实现上就是打一个 label / 不设字段，然后让所有过期逻辑绕行：

1
2
3
4
5
6
7
8


# server/opensandbox_server/services/k8s/create_helpers.py
expires_at = None
if request.timeout is not None:
 expires_at = calculate_expiration_or_raise(created_at, request.timeout)

labels: Dict[str, str] = {SANDBOX_ID_LABEL: sandbox_id}
if expires_at is None:
 labels[SANDBOX_MANUAL_CLEANUP_LABEL] = "true" # ← 唯一的区别就是一个 label

K8s 侧 spec.expireTime 不设置，控制器的 expire 分支直接跳过；Docker 侧过期扫描器看到 manual-cleanup=true 就 restore 后 continue（前面启动恢复那段代码里已经有了）。清理完全靠上层业务在会话结束时调 DELETE /sandboxes/{id}。

这个模式是为池化场景准备的：TTL 到期误杀正在使用的会话，比多养几个空闲沙箱的代价大得多。但它把回收责任完全推给了调用方，边界条件都得自己兜：

上层忘删 = 永久泄漏。伪永久沙箱没有任何服务端兜底回收，必须业务侧自建清理（比如定期扫描 expiresAt == null 且长时间无访问的沙箱）。而 SDK 自带的 releaseAllIdle 是严格串行的，实测 500 个空闲沙箱要 ~480 秒（上游 issue #1472），批量清理根本指望不上，得自实现并发 kill。
单向门。创建时没传 timeout，事后不能通过 renew-expiration 补上（409）。伪永久是一个创建时就必须做的决定。
Pool 模式下"删除"本身有坑。这是风险清单里最扎心的部分：#954（分配到的 Pod 被外部删除后 alloc-status 注解残留，supplement 恒为 0，沙箱永久不可用）、#1433（poolRef 可变更导致 in-use Pod 被当孤儿回收 + 新池永不分配）、#1423（Pool 控制器六重缺陷复合成自维持的 Pod 创建/删除风暴，实测约一半创建请求失败）。这三个 issue 截至核对都没有修复 PR。
“挂了自动拉起"不存在。上游明确 resume 只恢复有意的 Paused 状态，Terminated/Failed 不自动重启（#1127/#1328，SDK resume 报 409）。重建 = 新 sandbox ID + 内存和未持久化状态全丢。所以伪永久不是"永久可用”，只是"不会因为 TTL 被服务端杀掉"。

伪永久 + 上层主动删除，本质上是把 lease 的责任从服务端转移到了业务侧。服务端甩掉了误杀风险，但换来的是"业务必须自己靠谱"的前提。如果业务侧的清理兜底写得不靠谱，孤儿沙箱问题会以更隐蔽的方式回来——TTL 模式至少有个确定性的最后期限。

config/env 注入链：一句话版

生命周期之外，把配置注入链也简单记一笔（详细展开值得单独一篇）。核心结论：server 侧固定注入的 env 只有一个——K8s 运行时的 EXECD=/opt/opensandbox/execd（services/k8s/provider_common.py 的 _build_main_container），其余全是 API 请求 env 字段透传。sandbox_id 不走 env，走 label opensandbox.io/id；egress/secure-access 的 token 走 annotation。

有一个和生命周期直接相关的注入条件要注意：创建请求里的 env 和 entrypoint 是通过 taskTemplate 生效的，触发条件是 env 非空或 entrypoint 非默认值，都没传就走快路径——env 注不进去。所以"创建时注入用户 token"这类操作必须确认 taskTemplate 真的被触发了，否则沙箱起来了但没有你要的变量，而且不会报错。

egress 是个例外支线：OPENSANDBOX_EGRESS_* 前缀的 key 会被 split_egress_env 拆出来进 sidecar，不在白名单（ALLOWED_EGRESS_ENV_VARS）直接 ValueError，创建失败——这是少数"配置错误会在创建时 fail-loud"的地方。

边界条件自查清单

把这次走读里值得在集成前确认的边界收拢一下：

边界	行为	出处
timeout 传 0 / 负数	创建 400（最小 60）	`validators.py`
timeout 超服务端上限	创建 400	`ensure_timeout_within_limit`
续约时间早于现在	400	`ensure_future_expiration`
续约时间早于当前 expiresAt	spec 禁止（只能延长）	`sandbox-lifecycle.yml`
伪永久沙箱调续约	409	`docker_service.py:1199`
自动续约对伪永久沙箱	静默跳过（门控 return False）	`controller.py:69`
server 未开 renew_intent.enabled	opt-in 照常创建、proxy 照常转发，但续约零次（开关默认 False）	`config.py` / `proxy_renew.py:38`
lease 状态 label 丢失	拒绝续约（409），但过期调度也可能 skip+warning	`docker_service.py` restore 逻辑
Pod 被外部删除（Pool）	沙箱永久不可用，无自愈	#954
TTL 过期自动删除（K8s）	PVC ownerReferences 可能缺失导致泄漏	#1199
server 长期运行	httpx 连接池疑似泄漏，约 1 周耗尽	#1386

最后一条单独说：#1386 不是沙箱的问题，是 server 自己的。续约、状态查询全走 server，server 挂了所有沙箱的 lease 管理瘫痪——Docker 模式下 timer 停摆但容器还在跑，K8s 模式下 reconcile 停摆 expireTime 形同虚设。server 本身是这个 lease 系统的单点，生产部署要按"它会挂"来设计：监控 httpx 连接池、周期性重启、 lease 到期查询别全压在一个实例上。

走读完整体判断：OpenSandbox 的 lease 设计在"单机/中小规模"上是完整的——绝对时间戳、续约单调性、重启恢复、竞态放弃删除，该有的细节都有。但规模化风险集中在 K8s Pool 一侧（#954/#1433/#1423 三个无 PR 的 P0），伪永久模式的回收责任又全压给业务方。如果要上生产，我会选 TTL + 自动续约组合而不是伪永久：让服务端兜底最后期限，业务侧只负责"保活"，这比"保活 + 回收"两个责任都自担要安全。

下一篇预告：沙箱池化设计——Pool CRD、alloc-status 注解协议、预热与分配路径，以及为什么池化模式在当前上游版本要先踩一遍 #1423 的坑再决定开不开。

OpenSandbox 源码走读（一）：CRD Controller 与 Reconcile 循环

Sun, 06 Sep 2026 20:10:26 +0800

OpenSandbox 源码走读（一）：CRD Controller 与 Reconcile 循环

最近在看 OpenSandbox（阿里的沙箱开源项目）的控制面实现。它把"沙箱"建模成 K8s CRD，用一个 controller-runtime 算子驱动整个生命周期。这篇是我对自己 fork 里 kubernetes/ 目录的走读笔记：从 POST /sandboxes 的参数怎么落进 BatchSandbox spec，到 Reconcile 每一步在干什么，再到失败之后靠什么重试。代码都来自本地 clone（controller-runtime v0.21.0）。

全景：三个 CRD，两条回路

算子一共定义了 3 个 CRD（API 组 sandbox.opensandbox.io/v1alpha1），对应 3 个 Reconciler：

CRD	Reconciler	并发默认	干什么
BatchSandbox（`bsbx`）	BatchSandboxReconciler	32	沙箱本体：建 Pod、跑任务、pause/resume
Pool	PoolReconciler	16	预热 Pod 池：分配/回收/滚动更新/驱逐
SandboxSnapshot（`sbxsnap`）	SandboxSnapshotReconciler	1	rootfs 快照提交（pause/resume 的底层依赖）

整个控制面就两条互相咬合的回路：

1
2
3
4


任务回路：BatchSandbox reconcile → TaskScheduler → HTTP 推任务到 pod 内 task-executor(:5758)
 → 轮询任务状态 → 写回 status
分配回路：Pool reconcile → Allocator → 写 alloc-status 注解 + 内存 store
 → 注解变化经 watch 触发对方 reconcile → 闭环

注意第二条回路的关键设计：分配状态的持久化真相源是 BatchSandbox 上的注解，不是 Pool 的 status。Pool 的内存 store 只是个可重建的缓存。这个设计后面还会反复出现——很多"奇怪"的代码都是在为注解契约服务。

create 请求怎么变成 BatchSandbox

业务侧调 POST /sandboxes，server（Python）把它翻译成一个 BatchSandbox CR。池化模式的核心在 server/opensandbox_server/services/k8s/batchsandbox_provider.py 的 _create_workload_from_pool：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


def _create_workload_from_pool(self, batchsandbox_name, namespace, labels, pool_ref, expires_at, entrypoint, env, ...):
 entrypoint = entrypoint or DEFAULT_ENTRYPOINT
 spec = {
 "replicas": 1,
 "poolRef": pool_ref, # ← 池化模式的开关，指向预热池
 }
 if env or entrypoint != DEFAULT_ENTRYPOINT or self.execd_run_as_init: # needs_task_template
 spec["taskTemplate"] = self._build_task_template(entrypoint, env, batchsandbox_name)
 if expires_at is not None:
 spec["expireTime"] = expires_at.isoformat() # ← timeout 参数的归宿
 # 再包一层 apiVersion/kind/metadata，create_custom_object 直接落一个 BatchSandbox CR

几个 create 参数的映射关系值得记一下：

API 参数	落到 CR 的哪里	备注
`extensions.poolRef`	`spec.poolRef`	特殊值 `*` = 让控制器自动选池
`env` / `entrypoint`	`spec.taskTemplate`	非空即触发 taskTemplate 生成
`timeout`	`spec.expireTime`	不传 = 不自动到期，靠手动 delete
`metadata`	`metadata.labels`	用于 `GET /sandboxes?metadata=...` 过滤
`image` / `resourceLimits`	被忽略	池化 pod 预创建，模板锁死在 Pool 上

env 这条最有意思：server 会把 env 包进一个 shell 包装命令（_build_task_template 里 shlex.quote 转义后拼进 /bin/sh -c "/opt/opensandbox/bootstrap.sh <entrypoint> &"），再把 OPENSANDBOX_ID 追加进 env 列表，最终挂到 taskTemplate.spec.process。

这里有个容易踩的坑：不传 env 也不传 entrypoint 时走"快路径"，不生成 taskTemplate——池 pod 继续跑自己的 warm entrypoint，代价是任何分配时的 env 都注入不进去。所以"为什么我的环境变量没生效"十有八九是这个分支判断没过。

最终生成的 CR 大概长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


kind: BatchSandbox # apiVersion: sandbox.opensandbox.io/v1alpha1
spec:
 replicas: 1
 poolRef: my-pool  # 二选一：poolRef（池化）或 template（直建）
 taskTemplate: # 可选；决定要不要走任务调度
 spec:
 process:
 command: ["/bin/sh", "-c", "/opt/opensandbox/bootstrap.sh python /app/main.py &"]
 env: [{name: OSB_USER_ID, value: user-12345}]
 expireTime: "2026-09-06T12:00:00Z" # timeout 的归宿

注意 spec 里 template 和 poolRef 互斥：直建模式自己带 PodTemplateSpec，池化模式只有 poolRef，Pod 的长相完全由 Pool 的模板决定。server 还会把一批参数（volumes、networkPolicy、snapshotId+poolRef 组合等）直接 400 拒掉，因为池化 pod 是预创建的，事后没法改。

BatchSandbox 的 spec/status 长什么样

apis/sandbox/v1alpha1/batchsandbox_types.go，关键字段摘出来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type BatchSandboxSpec struct {
 Replicas *int32 // 默认 1
 PoolRef string // 与 Template 互斥
 Template *corev1.PodTemplateSpec
 ShardPatches []runtime.RawExtension // 按 index 给每个 pod 打 strategic merge patch
 ExpireTime *metav1.Time // 到了就删，控制器负责执行
 TaskTemplate *TaskTemplateSpec // 非 nil = 需要 TaskScheduler
 Pause *bool // pause/resume 意图，Server 写、Controller 执行
}

// +kubebuilder:validation:Enum=Pending;Succeed;Pausing;Paused;Resuming;Failed
type BatchSandboxPhase string

phase 一共 6 个：Pending / Succeed 是稳态，Pausing / Paused / Resuming 是暂停链路，Failed 是终态。status 侧除了 replicas/ready 计数，还有一组任务计数和两个特殊字段：

1
2
3
4
5
6
7
8


type BatchSandboxStatus struct {
 ObservedGeneration int64
 Replicas, Allocated, Ready int32
 TaskRunning, TaskSucceed, TaskFailed, TaskPending, TaskUnknown int32
 Phase BatchSandboxPhase
 PauseObservedGeneration int64 // pause/resume 幂等闸门：最近一次 ACK 的 generation
 Conditions []BatchSandboxCondition // Ready/Progressing/Paused/PauseFailed/ResumeFailed/PodFailed
}

PauseObservedGeneration 这个设计我第一次看有点绕：spec.pause 只是个布尔意图，Controller 靠"generation 是否前进 + 我 ACK 到哪个 generation 了"来判断这是不是一次新请求。这是把 K8s 原生的 observedGeneration 惯例复用到了 pause/resume 这条命令通道上，避免了额外的 ACK 子资源。

Reconcile 主循环：一轮到底干了什么

核心在 internal/controller/batchsandbox_controller.go 的 Reconcile，按执行顺序拆开：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


func (r *BatchSandboxReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 batchSbx := &sandboxv1alpha1.BatchSandbox{}
 if err := r.Get(ctx, client.ObjectKey{...}, batchSbx); err != nil {
 if errors.IsNotFound(err) {
 return ctrl.Result{}, nil // 对象没了，不用管
 }
 return ctrl.Result{}, err // 其他错误 → 交给退避重试
 }

 // 1. ExpireTime：过期就删，没过期把剩余时间记进 requeue 计划
 if expireAt := batchSbx.Spec.ExpireTime; expireAt != nil {
 if expireAt.Time.Before(now) && batchSbx.DeletionTimestamp == nil {
 r.Delete(ctx, batchSbx)
 } else if !expireAt.Time.Before(now) {
 DurationStore.Push(key, expireAt.Time.Sub(now))
 }
 }

 // 2. poolRef="*"：自动选池，List 全 namespace 的 Pool 挑一个 patch 回 spec.poolRef
 if updated, err := r.assignPool(ctx, batchSbx, profileName); updated {
 return ctrl.Result{}, nil // ← spec 变了，generation 前进，等下一轮
 }

 // 3. finalizer：有 taskTemplate 才挂 task-cleanup，防删除时残留任务
 // 4. pause/resume 分发：优先级最高的命令通道
 if result, handled, err := r.dispatchPauseResume(ctx, batchSbx); handled {
 return result, err
 }

 // 5. 列出 pod（两种模式实现完全不同，见下）
 pods, err := r.listPods(ctx, poolStrategy, batchSbx)
 // 池化模式下分配的 pod 消失了 → failClosedOnMissingAllocatedPods：fail-closed 标 Failed

 // 6. 扩容（池化和 Paused 状态跳过；只有扩没有缩）
 if !poolStrategy.IsPooledMode() && batchSbx.Status.Phase != Paused {
 r.scaleBatchSandbox(ctx, batchSbx, batchSbx.Spec.Template, pods)
 }

 // 7. 从 pod 现状推 phase
 runtimeView := buildRuntimeView(batchSbx, pods)

 // 8. 任务调度（taskTemplate != nil 才进），结果写进 status 任务计数
 if taskStrategy.NeedTaskScheduling() && batchSbx.Status.Phase != Paused {
 ts, err := r.reconcileTasks(ctx, batchSbx, pods)
 ...
 }

 // 9. 落盘：endpoints/runtime-id 注解 + status patch
 requeue, persistErrors := r.persistRuntimeView(ctx, batchSbx, runtimeView)

 // 10. requeue：多来源取最短（Pop 返回各处 Push 的最短值，再与 persist 阶段合并）
 requeueAfter := DurationStore.Pop(req.String())
 return reconcile.Result{RequeueAfter: requeueAfter}, gerrors.Join(aggErrors...)
}

第 6 步的 guard 值得细品：池化模式直接跳过 scale——池化 sandbox 没有 template，pod 的生死由 Pool 的分配/回收决定，控制器自己建删只会打架。Paused 跳过是因为暂停后的沙箱 pod 应该保持不存在，等 resume 重写镜像再拉起来。

listPods 在两种模式下的实现完全不同：直建模式按 ownerRefUID 的 field index 一次 List 拿齐；池化模式先解析 alloc-status 和 alloc-released 两个注解做差集，再对剩下的 pod 逐个 Get——代码里就带着 // TODO maybe performance is problem 的原话注释。池化 sandbox 的 replicas 一大，这每轮 R 次深拷贝 Get 的成本就线性往上叠。

状态机：phase 不是存的，是算的

走读里印象最深的设计：phase 没有独立的状态存储，每轮 reconcile 都从 pod 现状重新推导（batchsandbox_status.go 的 buildRuntimeView）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


func buildRuntimeView(batchSbx, pods) runtimeView {
 newStatus := batchSbx.Status.DeepCopy()
 for _, pod := range pods {
 newStatus.Replicas++
 if utils.IsAssigned(pod) {
 newStatus.Allocated++ // 池化模式下"分配了"的 pod
 }
 if podReady(pod) {
 newStatus.Ready++ // Running + Ready 且未在删除
 }
 }
 switch batchSbx.Status.Phase {
 case Pausing, Paused:
 // 生命周期稳态，不动
 case Resuming:
 applyResumingRuntimePhase(newStatus, pods)
 default:
 applySteadyRuntimePhase(batchSbx, newStatus, pods)
 }
}

func applySteadyRuntimePhase(...) {
 if summary, hasFailures := summarizePodFailures(pods); hasFailures {
 // CrashLoopBackOff / ImagePullBackOff / ErrImagePull / CreateContainerConfigError → Failed
 status.Phase = sandboxv1alpha1.BatchSandboxPhaseFailed
 return
 }
 if status.Ready > 0 {
 status.Phase = sandboxv1alpha1.BatchSandboxPhaseSucceed
 return
 }
 status.Phase = sandboxv1alpha1.BatchSandboxPhasePending
}

状态流转画出来：

stateDiagram-v2
[*] --> Pending: 创建
Pending --> Succeed: ready > 0
Pending --> Failed: pod 进入 BackOff 类状态
Succeed --> Failed: pod 故障
Succeed --> Pausing: spec.pause=true 且 generation 前进
Pausing --> Paused: 内部 Snapshot Succeed，删 Pod、去 finalizer
Pausing --> Failed: Snapshot Failed 且 Pod 丢失
Paused --> Resuming: spec.pause=false 且 generation 前进
Resuming --> Succeed: 快照镜像重建的 pod ready
Resuming --> Failed: resume pod 失败

“状态是推导出来的而不是记录下来的”，这是 K8s 控制器的正统做法（level-triggered），好处是任何状态丢失都能自愈。代价是 Failed 这种"终态"必须靠条件分支保护——代码里到处是 if phase != Failed 的短路判断，不然一个 ready pod 的短暂波动就会把 Failed 翻回去。另外 PauseFailed/ResumeFailed 两个 condition 由 mergeLifecycleConditions 单独保护，不被运行时推导覆盖。

扩容：确定性命名 + 期望机制防重复

scaleBatchSandbox 是直建模式下 pod 的唯一出生点，两个细节都值得学：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


func (r *BatchSandboxReconciler) scaleBatchSandbox(ctx, batchSandbox, podTemplateSpec, pods) error {
 // 1. 对现有 pod 做 ObserveScale，然后查期望是否满足
 if satisfied, unsatisfiedDuration, _ := BatchSandboxScaleExpectations.SatisfiedExpectations(key); !satisfied {
 // 上一轮的 Create 还没被 informer 观察到 → 跳过本轮扩容，防重复建 pod
 DurationStore.Push(key, expectations.ExpectationTimeout-unsatisfiedDuration)
 return nil
 }
 // 2. 算缺哪些 index
 var needCreateIndex []int
 // TODO var needDeleteIndex []int ← 缩容压根没实现，只留了个空注释
 for i := 0; i < int(*batchSandbox.Spec.Replicas); i++ {
 if _, ok := indexedPodMap[i]; !ok {
 needCreateIndex = append(needCreateIndex, i)
 }
 }
 for _, idx := range needCreateIndex {
 pod, _ := utils.GetPodFromTemplate(podTemplateSpec, batchSandbox, controllerRef)
 // 3. 按 index 打 shard patch（每个副本可以不一样）
 podBytes, _ := json.Marshal(pod)
 modifiedPodBytes, _ := strategicpatch.StrategicMergePatch(podBytes, batchSandbox.Spec.ShardPatches[idx].Raw, &corev1.Pod{})
 pod.Name = fmt.Sprintf("%s-%d", batchSandbox.Name, idx) // 4. 确定性命名，天然幂等
 BatchSandboxScaleExpectations.ExpectScale(key, expectations.Create, pod.Name)
 r.Create(ctx, pod) // 失败则 ObserveScale 回滚期望 + 记 Warning Event
 }
}

确定性命名 + ScaleExpectations 是一对组合拳：名字确定让"建了又看不见"（informer 滞后）不会变成重复创建，期望机制让这个等待变得显式。但缩容那句 TODO var needDeleteIndex []int 很扎眼——spec.replicas 调小不会删任何 pod，这可是 ReplicaSet 十年前的基本功。想缩副本只能删整个 sandbox，或者走 Pool 模式。

与 K8s 原生机制的耦合点

这个控制器重度依赖 K8s 原生设施，汇总成一张表：

机制	用法
ownerReference + Owns	Pod/Snapshot 挂 BatchSandbox 为 owner，`Owns(Pod)` watch 级联
Finalizer	`task-cleanup`（停任务）/ `pool-allocation`（等 pod 归还池）/ `cleanup`（清 commit Job）
Annotation	alloc-status / alloc-release / alloc-released / endpoints / runtime-id，五条内部契约
Generation	spec 变更自增，配合 observedGeneration / pauseObservedGeneration 做幂等
Subresource status	`Status().Patch` 单独写状态，与 spec 写路径隔离

注解契约里最容易混淆的是池化三件套，语义上有时序：

1
2
3


alloc-status (Pool 写)："这些 pod 分给这个 sandbox 了" —— 已生效
alloc-release (BatchSandbox 写)："我请求释放这些 pod" —— 释放请求
alloc-released (Pool 写)："确认已回收" —— 释放完成

releasePods 的实现就是把释放请求 MergePatch 到 BatchSandbox 的 alloc-release 注解上（batchsandbox_controller.go），然后靠 Pool 侧的 watch 谓词感知这次变化。Pool 侧的 watch 装配（pool_controller.go 的 SetupWithManager）：

1
2
3
4
5
6
7
8


return ctrl.NewControllerManagedBy(mgr).
 For(&sandboxv1alpha1.Pool{}, builder.WithPredicates(predicate.GenerationChangedPredicate{})).
 Owns(&corev1.Pod{}). // ← 无谓词，任何 pod 事件都全量 reconcile
 Watches(&sandboxv1alpha1.BatchSandbox{}, handler.EnqueueRequestsFromMapFunc(findPoolForBatchSandbox),
 builder.WithPredicates(filterBatchSandbox)). // 只放行 release 注解变化/replicas 变化/进入删除
 Watches(&sandboxv1alpha1.BatchSandbox{}, enqueueOldPoolForDetachedBatchSandbox,
 builder.WithPredicates(filterBatchSandboxDetached)). // poolRef 非空→空：通知旧池重新平衡
 Complete(r)

这个谓词设计其实很精细：普通 alloc-status 变化不会惊动 Pool（不然分配回路就是死循环），只有 release/replicas/删除这三类"需要 Pool 动手"的信号才入队。对比之下 For(BatchSandbox) 连谓词都没有——status 更新会自己触发自己的 reconcile，每笔状态变更约等于两次 reconcile。一边抠得极细，一边完全裸奔，观感有点割裂。

失败怎么重试：三层 requeue 机制

控制器里的重试其实分三层。第一层：返回 error，走 controller-runtime 默认指数退避。 任何 return ctrl.Result{}, err 都进 workqueue 的 rate limiter。最省事但也最不可控——网络抖动和业务逻辑失败在这里没有区别。

第二层：RequeueAfter 定时轮询，多来源取最短。 这是最重的一层，配套了一个小工具 DurationStore：

1
2
3
4
5
6


// internal/utils/requeueduration —— 多个来源都往里 Push，取最短值
func (rd *Duration) Update(newDuration time.Duration) {
 if newDuration > 0 && (rd.duration <= 0 || newDuration < rd.duration) {
 rd.duration = newDuration
 }
}

其中 3s 任务轮询是这个设计的命门：

1
2
3
4
5
6


func (r *BatchSandboxReconciler) reconcileTasks(...) (*taskScheduleResult, error) {
 ...
 // Because tasks are in-memory and there is no event mechanism, periodic reconciliation is required.
 DurationStore.Push(key, 3*time.Second) // ← 注释写得明明白白：没事件机制，只能轮询
 ...
}

第三层：RetryOnConflict，只管写冲突。 Pool 控制器把整个 reconcilePool 包在 retry.RetryOnConflict(retry.DefaultBackoff, ...) 里，冲突就整段重跑。

三层里最要命的是第二层的两个特性叠加：任务型 sandbox 不管有没有变化每 3s 必 reconcile 一次，而 RequeueAfter 走 AddAfter 直接入队，完全绕过 rate limiter（默认指数退避只保护返回 error 的路径）。1000 个任务型 sandbox 就是稳态 333 次 reconcile/s，退避机制对它一筹莫展。任务状态纯内存、task-executor 又没有状态上报事件，这个 3s 是代码注释里自己承认的无奈之举。pause/resume 期间还有一堆 1s 轮询在推进中间态，控制器一过载这些中间态就会集体变慢——轮询式状态机的通病。

整体看下来，这个控制器的骨架是很标准的 controller-runtime 姿势，状态推导、finalizer、期望机制都用得中规中矩；真正让我犹豫的是它把注解当 IPC 用（五个注解键、JSON 整表覆盖式写入、跨控制器 watch 级联）和 3s 无条件轮询这两个选择——单机 demo 没问题，规模上去之后这两处就是最先崩的地方。下一篇拆 Pool 的分配/回收/滚动更新，那里能看到注解契约的完整写路径。（下一篇：Lease 与生命周期）

mmdx：给 AI agent 用的 Mermaid 渲染器怎么设计

Sun, 06 Sep 2026 20:07:23 +0800

mmdx：给 AI agent 用的 Mermaid 渲染器怎么设计

上一篇《Mermaid 主题定制暗坑大全》把 mermaid 主题系统里的坑挨个盘了一遍，这篇讲我把那些教训固化成的东西：mmdx，一个给 AI agent 用的 Mermaid → SVG/PNG 导出 CLI。重点写它的主题系统组织和全覆盖颜色检测——后者是我认为这个项目里最值钱的设计。

痛点：agent 写得动 mermaid，交不出图

LLM 写 mermaid 语法的准确率已经很高了，但"写得出"和"交得出图"之间隔着一条鸿沟。我在 agent 工作流里要一张架构图时，实际发生的事情是：

agent 产出的 ```mermaid 块只能靠渲染器活着——聊天窗口里凑合看，发博客、贴 issue、放幻灯片就露馅
现有工具要么是 VSCode 插件手动导出（默认紫黄 #ECECFF 主题，上一篇吐槽过的那套），要么是 MCP 渲染服务——每个都重造一遍管线基础
agent 在别人的机器上跑，没有 Node、没有字体、主题不可控，渲染结果不可复现

所以 mmdx 的定位很明确：agent 拿着一段 markdown 就能出一个带主题的 SVG/PNG，不装 Node、不下 Chromium（复用系统 Edge/Chrome）、中文字体内置。package.json 里的一句话定位：

1
2
3
4


{
 "name": "mmdx",
 "description": "Mermaid → SVG/PNG exporter with tech-doc themes, bundled CJK font and ELK layout, built for AI agents"
}

“built for AI agents” 不是营销词，它决定了后面一堆设计取舍：CLI 契约要机器可读、输出要确定性、失败要响亮不能挂住。

主链路：五个模块，一条管线

整个 src/ 目录不到 2000 行，模块划分：

1
2
3
4
5


cli.ts 入口：参数解析、围栏块提取、主题叠加、输出契约（462 行）
render.ts 渲染核：单 Chromium + 页面池 + 截图裁切（520 行）
themes.ts 七套主题预设 + deepMerge（667 行）
blocks.ts table/list/card 扩展块转 HTML（193 行）
embed.ts 内嵌资产：mermaid UMD、ELK、字体、svgo（编译期生成）

主链路一句话：提取围栏块 → 主题配置合成 → 页面池渲染 → SVG/PNG 落盘。

flowchart LR
A[md/mmd/stdin] --> B[extractBlocks]
B --> C[主题合成
preset + theme-js + config + css]
C --> D[Renderer 页面池
mermaid.render]
D --> E[SVG 重算 viewBox]
D --> F[PNG 墨迹二次裁切]
E --> G[svgo 压缩]
G --> H[落盘 + --json]
F --> H

块提取是纯正则，FENCE_RE 扫所有围栏语言，认识的才收（src/cli.ts:161）：

1
2
3
4
5
6
7
8


// any fenced block with a recognized language (mermaid / table / list)
const FENCE_RE = /^[ \t]*```([A-Za-z0-9_-]+)[^\n]*\n([\s\S]*?)^[ \t]*```\s*$/gm;

function extractBlocks(input: string, raw: string): Block[] {
 // ... kind = fenceKind(m[1]); kind === 'unknown' 就跳过
 // 记录 line（块在原文的行号，报错时 agent 能定位回源文件）
 blocks.push({ input, base, index: blocks.length + 1, line, code, kind });
}

渲染核 Renderer 是一个类，单浏览器实例 + 页面池。每个页面初始化一次就反复渲染很多图（src/render.ts:145 的 initPage）：注入 mermaid UMD、把 ELK 的 7MB bundle 以 base64 塞进 window.__elkB64 但不解析、注入 Noto Sans SC 子集字体并强制 document.fonts.load：

1
2
3
4
5
6
7
8
9


// src/render.ts:154 — ELK 懒加载的关键
if (this.opts.layout === 'elk' && this.assets.elkJs) {
 // stash the payload; ELK is parsed lazily on the first flowchart render
 // (its 7MB bundle costs ~0.8s of parse per page and only flowchart/
 // graph diagrams ever use it)
 await page.evaluate((b) => {
 (window as any).__elkB64 = b;
 }, b64);
}

真正渲染发生在页面里（src/render.ts:260 的 page.evaluate），几个值得说的点：

1
2
3
4
5
6


mermaid.initialize({
 ...config,
 layoutAlgorithm: wantElk ? 'elk' : 'dagre',
 startOnLoad: false,
 suppressErrorRendering: true, // ← 语法错误必须 throw，不能返回"错误炸弹"SVG
});

suppressErrorRendering: true 是给 agent 的：mermaid 默认把语法错误渲染成一张带错误文字的 SVG 图，agent 拿到文件看不出问题。这里强制它 throw，错误进 --json 的 errors 数组。

SVG 拿到手后 mermaid 给的 viewBox 不能信（上一篇写过：under-measures wrapped CJK labels），所以整棵树重新量一遍。量法有个坐标系陷阱——每个叶子的 getBBox() 在自己的局部坐标系，必须经过 getCTM() 矩阵换算到根 svg 的 user space 再 union（src/render.ts:326 的 toRootRect）：

1
2
3
4


// getCTM maps into VIEWPORT space, which includes the (stale)
// root viewBox scale; divide it out so all leaves land in the
// root's own user space, the space the viewBox is written in.
const m = root.inverse().multiply(mRaw);

PNG 则走两遍截图：第一遍按几何 bounds 截，然后 inkBBox（src/render.ts:72）逐像素找墨迹包围盒，第二遍按墨迹裁——因为几何 bounds 会漏掉箭头 marker 和字形 overshoot。四边留白对称是这么构造出来的，不是靠猜：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// geometric bounds miss marker arrowheads and glyph overshoot; a
// second capture clipped to the actual ink gives pixel-exact,
// symmetric file margins
const ink = inkBBox(first);
if (!ink) return first;
const mx = Math.max(1, padX * sc - 2);
const clip = {
 x: Math.max(0, (ink.x0 - mx) / sc),
 // ... y / width / height 同理
};
return (await page.screenshot({ clip, omitBackground: transparent })) as Buffer;

这个二次截图是我最满意的实现细节之一：留白对称性从"调参调出来的"变成"构造保证的"，测试里断言 L/R 边距差就够了，不用碰玄学。

主题系统：themeVariables 集中 + themeCSS 补刀

七套预设：tech（默认）、openai / openai-dark、minimal、latte / mocha、sketch。每个预设是一个 ThemePreset（src/themes.ts:6）：

1
2
3
4
5
6


export interface ThemePreset {
 config: Record<string, unknown>; // 直接喂 mermaid.initialize
 background: string; // 页面背景，也是 edgeLabelBackground
 dark?: boolean; // 预设是否深色页
 remap?: Record<string, string>; // 渲染后 hex→hex 重着色（mermaid 写死的色）
}

组织原则一：颜色尽量收敛进 themeVariables，走官方派生链。tech 主题的 themeVariables 有 100 多个键，按图型分组注释，核心派生键放最前面（src/themes.ts:167）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


themeVariables: {
 // ---- core derivation chain: every diagram inherits from these.
 // primaryColor in particular must be set — its default (#fff4dd cream)
 // is the "native mermaid" look leaking through every unset corner.
 primaryColor: '#E8F3FF',
 primaryTextColor: '#1D2129',
 primaryBorderColor: '#4098FC',
 // ...
 // ---- pie: AntV G2 default categorical palette
 pie1: '#5B8FF9', pie2: '#5AD8A6', /* ... pie12 */
 // ---- xyChart: plotColorPalette (defaults start with mermaid purple #ECECFF)
 xyChart: { plotColorPalette: '#5B8FF9,#F6BD16,#5AD8A6,...', /* ... */ },
},

组织原则二：themeVariables 覆盖不到的用 themeCSS 补。最典型的是 flowchart 形状分色——mermaid 只给一个 primaryColor，想要"矩形=流程、菱形=判定、圆=状态、圆柱=存储"四色语义，只能 CSS 按形状选择器上色（src/themes.ts:82）：

1
2
3
4
5
6
7


/* shape-coding: mermaid variables only offer a single primaryColor for node
 shapes, so the rect=process / diamond=decision / circle=state / store=purple
 colour roles are painted here */
.node rect { fill: #E8F3FF; stroke: #4098FC; }
.node polygon { fill: #FFF7E6; stroke: #FF9A2E; }
.node circle, .node ellipse { fill: #E8FFEA; stroke: #23C343; }
.node path { fill: #F5E8FF; stroke: #722ED1; }

组织原则三：mermaid 写死在渲染产物的颜色，用渲染后 remap 兜底。sankey 的 tableau10 色板和 journey 的表情底色没有 themeVariables 通道，tech 预设带一张 remap 表，在 SVG 字符串进 DOM 之前做 hex 替换（src/themes.ts:359、src/render.ts:296）：

1
2
3
4


remap: {
 // sankey nodes/links default to the tableau10 set (no theme variables)
 '#4e79a7': '#6E94BB', '#f28e2c': '#D2A36C', /* ... */
},

1

在 render() 里：svg 字符串 → remap 逐条 replace → 才 innerHTML 进 DOM

这样 SVG 和 PNG 拿到的是同一份颜色，不会出现"PNG 对了 SVG 错了"的精神分裂。

三层的覆盖关系在 cli.ts:298 串起来，顺序是固定的：

1
2
3
4


let config = JSON.parse(JSON.stringify(preset.config)); // 1. 预设
if (o.themeJs) config = applyThemeJs(..., config, ...); // 2. --theme-js 整体改写
if (o.config) config = deepMerge(config, JSON.parse(...)); // 3. --config 深合并
if (o.css) config.themeCSS += '\n' + css; // 4. --css 追加

上一篇写过的"assignWithDepth 对数组是追加不是替换"的坑，在这里的对策就是 remap + CSS 钉死（journey actor 圆点的注释直接写在 TECH_CSS 里：config.journey.actorColours is useless — mermaid's assignWithDepth APPENDS arrays）。把踩坑结论固化成代码注释和默认行为，比写博客本身更重要——博客是给人看的，注释是给三个月后的自己看的。

全覆盖检测：像素级颜色普查

主题系统最大的风险不是"某个变量设错了值"，而是"某个角落根本没被任何变量覆盖"。20 种图型 × 100 多个主题变量，人眼看不过来——改一个变量得把 20 张图全渲染一遍肉眼扫，而且人眼对"这个蓝和那个蓝差了 5%“毫无办法。

所以检测必须系统化，分两步。

第一步：全图型渲染筛查（tests/run.ts）。tests/diagrams/ 下每图型一个 fixture——block、c4、class、er、flowchart、gantt、gitgraph、journey、kanban、mindmap、pie、quadrant、radar、requirement、sankey、sequence、state、timeline、treemap、xychart，正好 20 个。全部渲染成 PNG 后做像素分析：

1
2
3
4
5
6


// tests/run.ts:95 — 库级筛查的三个断言
const lr = Math.abs(a.margins.l - a.margins.r); // 左右边距差
const tb = Math.abs(a.margins.t - a.margins.b); // 上下边距差
if (lr > 16) problems.push(`L/R margins ${a.margins.l}/${a.margins.r}`);
if (a.ink < 0.005) problems.push('near-blank'); // 白图检测
if (a.ink > 0.85 && name !== 'treemap') problems.push('overfull');

这一层只筛"结构性坏了”（边距不对称、空白、糊满），颜色对不对它管不了。

第二步：颜色普查（scripts/theme-census.ts），这才是全覆盖的核心。思路：渲染出的 PNG 里每个像素都应该能溯源到主题调色板——溯源不了的就是漏网之鱼。

坏值清单必须有定义来源。检测的"合法色集合"不是手工罗列的，而是从 themes.ts 源码里正则抽出来的全部 hex 字面量（theme-census.ts:16）：

1
2
3
4


// 1. allowed palette = every hex literal in themes.ts + black/white
const themeSrc = fs.readFileSync(path.join(ROOT, 'src', 'themes.ts'), 'utf8');
const allowed = new Set<string>(['#000000', '#FFFFFF']);
for (const m of themeSrc.matchAll(/#([0-9a-fA-F]{6})\b/g)) allowed.add('#' + m[1].toUpperCase());

这一步是整个设计的命门。如果合法集合只写"已知踩过的坑"（比如 #ECECFF），那换个没踩过的默认色漏出来就漏报了。从主题源码抽取，等于声明：凡是主题作者没写进源码的颜色，都是非法的——新增图型用了新默认色、主题改版引入漂移，都会被同一张网捞住。

然后逐像素统计，跳过半透明抗锯齿边缘（theme-census.ts:38）：

1
2
3
4
5
6


for (let i = 0; i < data.length; i += 4) {
 if (data[i + 3] < 250) continue; // AA fringe
 const key = '#' + [data[i], data[i+1], data[i+2]]
 .map((v) => v.toString(16).padStart(2, '0').toUpperCase()).join('');
 counts.set(key, (counts.get(key) ?? 0) + 1);
}

问题来了：抗锯齿和半透明填充会产生调色板色的合成产物——比如 35% 透明度的雷达曲线叠在白底上，逐像素值不在调色板里，但它是合法的。硬把抗锯齿当坏值，工具会误报到没法用。所以有个合成容差判定 isDerived：某颜色 c 合法，当且仅当存在调色板色 P 和 alpha a，使 P*a + 255*(1-a) 在每通道 ±3 内还原出 c（theme-census.ts:48）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const isDerived = (hex: string): boolean => {
 const c = [r, g, b];
 for (const p of pal) {
 // 反解三个通道各自的 alpha，要求自洽（差 < 0.06）且在合理范围
 const alphas = [0, 1, 2].map((i) => (255 - c[i]) / (255 - p[i] || 1));
 const a = alphas[0];
 if (a < 0.08 || a > 1) continue;
 if (alphas.every((x) => Math.abs(x - a) < 0.06) &&
 [0,1,2].every((i) => Math.abs(Math.round(p[i]*a + 255*(1-a)) - c[i]) <= 3)) return true;
 }
 return false;
};

这个反解 alpha 的写法有点取巧：假设合成发生在白底上（255*(1-a)）。页面背景不是白色时（比如 mocha 的 #1E1E2E）它会误判——目前的普查脚本只跑默认 tech 主题所以没事，这是个已知的边界，见文末。

最后一层是刺眼默认色黑名单：有些 mermaid 默认色面积很小（journey 的 actor 圆点、单条错误的连线），按面积阈值会漏掉，但它们恰恰是最扎眼的。黑名单里的颜色任何覆盖率都报（theme-census.ts:61）：

1
2
3
4
5
6
7


// known garish mermaid defaults — flag at ANY coverage (tiny elements
// like journey actor dots fall below the area threshold)
const loud = ['#7CFC00', '#00FFFF', '#8FBC8F', '#ECECFF', '#9370DB',
 '#191970', '#8B008B', '#FF0000', '#00BFFF', '#FF8888'];
const off = [...counts.entries()].filter(([c, n]) =>
 !allowed.has(c) && !isDerived(c) &&
 (n / total > 0.0015 || (loud.includes(c) && n > total * 0.0001)));

注意黑名单的角色和 allowed 集合不同：allowed 是定义合法性（源头是 themes.ts），loud 是提高灵敏度（源头是已知刺眼色的经验清单）。前者漏报新形态，后者只是让小面积的已知坏值更早暴露——两层缺一不可，但只有第一层是完备的。

这套检测的真实战绩：xyChart 的 plotColorPalette 默认以 mermaid 紫 #ECECFF 打头、radar 曲线的 cScale 粉彩在网格线上几乎隐形、treemap 各分区色几乎不可区分——全是普查跑出来的，不是肉眼。另外一个隐蔽案例印证了上一篇"配置嵌套层级"的教训：批量补丁曾把 todayLineColor、quadrant*Fill 等键错误地插进 themeVariables.xyChart 内部，键还在、值也对，就是层级错了导致静默失效——这类错误肉眼 review 配置文件根本看不出来，但普查会直接报"pie 图出现了 off-palette 默认色"，因为变量没生效、默认色就漏出来了。

变量"不生效"的头号症状就是嵌套位置错，而像素普查是唯一能兜住这种静默失效的网——它不检查你写了什么配置，它检查渲染结果长什么样。配置对不对是手段，像素对不对才是目的。

agent 友好性：CLI 契约的取舍

给 agent 用的 CLI 和给人用的差别很大，几个明确的取舍：

1. stdout 只有一份 JSON，进度全走 stderr。 --json 打开时人类可读的进度行全部静默，stdout 是单个 JSON（cli.ts:432）：

1
2
3
4
5
6
7


console.log(JSON.stringify({
 theme: o.theme, layout: o.layout, format: o.format, background,
 blocks: blocks.length, rendered: results.length - failed.length,
 failed: failed.length, files: written,
 errors: failed.map((f) => ({ input: f.input, index: f.index, error: f.error })),
 ...(o.profile ? { profile: profileSummary() } : {}),
}, null, 2));

agent 解析 files 数组核对产物、解析 errors[].input/index/error 定位坏块，不用猜输出格式。

2. 失败隔离 + 确定性退出码。 一个块渲染失败不拖垮整批，--json 里如实记录；退出码三档：0 全成、1 有渲染失败（其余照常出图）、2 用法错误。agent 看到 1 就读 errors 数组，看到 2 就改命令行。

3. 挂死必须响亮。 每次渲染包一层 Promise.race，60 秒必报错（render.ts:505）：

1
2
3
4
5
6
7


// a wedged renderer (bad diagram, crashed tab) must fail loud, never hang
return await Promise.race([
 fn(page),
 new Promise<never>((_, rej) => {
 timer = setTimeout(() => rej(new Error('render timed out after 60s')), 60_000);
 }),
]);

并发下浏览器的瞬时抽风（截图超时之类）则由外层自动重试一次（cli.ts:400）——agent 不该为这类抖动买单，但真正的语法错误重试也没用，两次都失败才进 errors。

4. 确定性输出命名。 同一输入永远产出同名文件：README-m1.svg、README-m2.svg……--index 2 筛选后仍保留 -m2 后缀（cli.ts:292 的注释：keep the -m<n> suffix ... so blocks don't masquerade as the whole file's diagram），agent 引用文件名不会漂移。

5. 观测性。 --profile 输出各阶段耗时（browser-launch / page-init / mermaid-render / screenshot / svgo），典型单图 95ms 渲染 + 90ms 截图。agent 调优 --jobs 或怀疑卡顿时有数据可依。

6. 不下载任何东西。 浏览器按 Edge → Chrome 常见路径探测（render.ts:36 的 detectBrowser），找不到快速报错并列出搜索路径——绝不拉 Chromium。icon 包从 unpkg 拉一次就缓存到临时目录。agent 在别人机器上跑，网络行为必须可预期。

这几条里最费心思的是"响亮失败"和"重试"的边界：重试 absorb 的只该是瞬时故障，语法错误重试是浪费。现在的实现是简单粗暴的无差别重试一次——够用但不精致，理想情况应该按错误类型分流，比如超时重试、语法错误不重试。

结语

回头看，这个项目一半的代码在渲染，另一半在"证明渲染是对的"。主题系统的三层结构（themeVariables 派生链 / themeCSS 形状语义 / remap 兜底）本质上是在跟 mermaid 的历史包袱做分层妥协；而像素普查则是把"主题改完了没漏"从人眼工程变成可回归的断言。

还有几块明显欠账：普查脚本只覆盖默认 tech 主题、没有接进 CI 自动跑、合成容差假设白底、–theme-js 用 new Function 执行用户代码没做任何沙箱。这些都不影响它作为一个 agent 工具完成本职，但离"可以放心让别人依赖的渲染服务"还有距离。

我现在的判断是：给 agent 造工具，最难的不是功能，是让失败的路径和成功的路径一样被设计过——JSON 契约、退出码、超时、坏块隔离这些东西写起来毫无乐趣，但 agent 每天 80% 的时间活在这些路径上。接下来值得想的问题是：像素普查这套思路能不能反哺给 agent 本身——agent 自己产图、自己跑一遍普查、自己修，直到 ALL CLEAN？那才是"built for AI agents"的完全体。

Mermaid 主题定制暗坑大全

Sun, 06 Sep 2026 20:06:28 +0800

Mermaid 主题定制暗坑大全

我给 mmdx（自己的 Mermaid 导出器）做了一套完整主题预设，过程中在 mermaid 的主题机制上反复撞墙：变量改了不生效、CSS 写了被盖、颜色改了换了个地方又冒出来。这篇把踩过的坑整理成 checklist，每条都是"现象 → 为什么 → 怎么绕"，代码全部来自真实仓库。

先立结论：themeVariables 根上的键永远生效

这是整个主题定制的第一原则，反过来用就是最重要的排错手段。

mermaid 的主题计算（Theme.calculate）流程是三步：用户覆盖 → 推导派生色 → 再覆盖。也就是说 themeVariables 根上的键永远赢——不管后面的推导链怎么算，你写在根上的值是最后生效的。所以：

变量"不生效"，九成不是机制问题，而是嵌套位置错——键被插到了某个图型的子配置里，而不是 themeVariables 根上。
例外只有一种：渲染器根本不读这个变量（走了硬编码），那是另一类坑，后面单说。

我真实踩过的版本：用 python 脚本给主题补丁批量插入 pie1~pie12、quadrant1Fill、todayLineColor 十几个键，锚点缩进算错一层，整批键被插进了 themeVariables.xyChart 对象内部：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


themeVariables: {
 primaryColor: '#E8F3FF',
 // ...几十个根级键...
 xyChart: {
 plotColorPalette: '#5B8FF9,#F6BD16,...',
 pie1: '#5B8FF9', // ← 全在这里，静默失效
 pie2: '#5AD8A6', // pie 图根本不读 xyChart 命名空间
 todayLineColor: '#FF9A2E',
 },
},

配置是合法 JSON，渲染不报错，颜色就是不变。排错半天以为是变量名写错或 mermaid 版本问题，最后把配置 dump 出来做括号深度计数才发现层级错了。

“变量不生效 = 先查嵌套位置”，这条现在是我排 mermaid 主题问题的第一反应。批量改配置结构后，写个脚本断言每个键的括号深度，或者干脆整段重写而不是锚点替换——锚点替换省的那几分钟会在排错时十倍还回来。

assignWithDepth：数组是追加不是替换

第二个大坑在 mermaid 合并用户配置的入口函数 assignWithDepth 里。看 mermaid 源码（src/assignWithDepth.ts，dist 产物 chunk-DU6HZSFF.mjs 原样保留）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


var assignWithDepth = (dst, src, { depth = 2 } = {}) => {
 if (Array.isArray(src) && !Array.isArray(dst)) {
 src.forEach((s) => assignWithDepth(dst, s, config2));
 return dst;
 } else if (Array.isArray(src) && Array.isArray(dst)) {
 src.forEach((s) => {
 if (!dst.includes(s)) { // ← 追加，不是替换
 dst.push(s);
 }
 });
 return dst;
 }
 // 对象走递归合并，标量直接覆盖 —— 这部分行为正常

对象合并符合直觉，标量覆盖也正常，唯独数组是 push。dst 里已经有默认值时，你配置的数组元素会追加在默认值后面。

具体受害场景是 journey 图的 actor 圆点。journey 配置里有 actorColours 数组，我配置成：

1
2
3


journey: {
 actorColours: ['#6E94BB', '#7FB08A', '#63A8A4', '#D2A36C', '#8B99A8', '#C48BA6'],
},

结果圆点颜色纹丝不动。原因是 mermaid 默认的 6 个 actor 颜色已经占了 0-5 槽位，我的 6 个颜色被 append 到第 7-12 位——而 journey 只有 6 个 actor，永远读不到追加的段。同理 journey.actorColours 在 themeVariables.cScaleInv 那条路上也有类似问题。

怎么绕？journey 圆点的 fill 是 SVG presentation attribute（fill="cornsilk" 这类），而 presentation attribute 的优先级低于任何 CSS 规则。所以用 themeCSS 直接压：

1
2
3
4
5
6


/* src/themes.ts — journey actor dots: config.journey.actorColours is useless —
 mermaid's assignWithDepth APPENDS arrays, so the hardcoded defaults keep
 slots 0-5. Presentation-attribute fills lose to plain CSS, so pin the dots here. */
.actor-0 { fill: #6E94BB; stroke: #FFFFFF; }
.actor-1 { fill: #7FB08A; stroke: #FFFFFF; }
/* ... .actor-2 到 .actor-5 同理 */

“presentation attribute 输给任何 CSS"是 SVG 规范行为，不是 mermaid 的锅，但它决定了绕法的方向：凡是 fill 写死在元素属性上的地方，别试图找主题变量了，直接 CSS 压，稳赢。

themeCSS 的 #svgId 前缀：svg 根类匹配不到

第三个坑在 themeCSS 本身。mermaid 拿到 themeCSS 后不是原样注入 <style>，而是给每条规则加一个 #svgId 前缀（svg 元素的 id 选择器），把作用域限定在当前图里。

这意味着你的选择器实际生效形式是：

1
2
3
4
5


/* 你写的 */
.erDiagram .entityBox { fill: #E8F3FF; }

/* 实际注入的 */
#svgId .erDiagram .entityBox { fill: #E8F3FF; }

问题来了：.erDiagram 这个类挂在 svg 根元素上，而 #svgId 就是这个根元素。CSS 里"X 的后代 Y"要求 X 是 Y 的祖先——svg 根不可能是自己的后代，所以 #svgId .erDiagram ... 永远匹配不到任何元素。凡是想以 svg 根类做后代选择器中间环节的写法，全部静默失效。

绕法：跳过根类，直接锚定根类内部的结构类：

1
2
3
4
5
6


/* src/themes.ts — ER 实体外壳是 .node path，属性行走 themeVariables */
.node .outer-path path { fill: #E8F3FF; stroke: #4098FC; }
.node .row-rect-odd path { fill: #FFFFFF; stroke: #4098FC; }
.node .row-rect-even path { fill: #F7F8FA; stroke: #4098FC; }
/* class 图的分隔线也会撞上 .node path 规则，单独钉住 */
.divider path { stroke: #4098FC; }

注意上面还有个连锁坑：ER 实体外壳和 class 图的分隔线都是 .node path，会被 flowchart 的通用 .node path 填色规则误伤（我把通用 path 涂成紫色代表"存储”，结果 ER 实体全紫了）。主题 CSS 里每加一条宽泛规则，都要想一遍哪些图型的哪些元素也满足这个选择器。

官方文档完全没提 #svgId 前缀这回事，themeCSS 的行为只能靠 dump 生成的 SVG <style> 反推。我怀疑没几个人成功用过 .erDiagram 开头的 themeCSS 选择器。

内联 style !important：CSS 的尽头是改数据

第四个坑是优先级天花板。C4 图的元素标签文字是硬编码白色内联样式——渲染器里直接 color: fontColor ?? '#FFFFFF' 且带 !important 写进元素的 style 属性。内联样式加 !important，是 CSS 层叠里赢不了的东西：任何外部样式表规则，不管特异性多高，都输给它。

所以我给 C4 换浅色主题的第一次尝试：themeCSS 里写 text { fill: #1D2129 !important } 之类，全部无效。

绕法只有一条：改数据源头。不动文字颜色，把 C4 的填充色调到足够深，让白字可读。官方通道是 config.c4 段（这也是 C4 填充色的正确出处，不在 themeVariables 里）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// src/themes.ts — C4 element palette: official channel is the c4 config section
// NOTE: c4 label text is hardcoded white inline (c4ShapeAdapter: color:
// fontColor ?? '#FFFFFF', applied with !important) — no theme variable
// can change it, so fills must stay dark enough for white text
c4: {
 person_bg_color: '#4A6F94', person_border_color: '#3A5A78',
 external_person_bg_color: '#76828F', external_person_border_color: '#6A7581',
 container_bg_color: '#4A6F94', container_border_color: '#3A5A78',
 // ...
},

这条给了我一个方法论上的提醒：遇到"怎么写 CSS 都不生效"时，先确认目标元素上有没有内联 !important（dump SVG 看 style 属性）。有，就别在 CSS 层纠缠了，往上找数据源——改不了数据源（比如白字是 mermaid 写死的），就把自己的设计往数据源头让步，而不是继续堆选择器。

直接命中 beats 继承：压到实际文字元素上

第五个坑是层叠里最不起眼的一类。我想统一图内文字颜色，在容器层设置：

1

.mindmap-node .label { color: #1D2129 !important; }

.label 是 foreignObject 里的 div，直觉上 color 会继承到内部所有文字。但 mindmap 某些节点的文字元素（span、.text-inner-tspan）上挂着直接命中的规则（比如 root 节点的 tspan 通过 section-root 规则拿到 gitBranchLabel0 的白色），直接命中永远赢过继承——父元素的 color 设得再对，子元素自己有规则就轮不到继承。

绕法：选择器覆盖到实际渲染文字的元素，一层都别省：

1
2
3
4
5
6
7
8


/* src/themes.ts — mindmap 标签是 HTML（foreignObject）——
 颜色必须钉到 span/p/tspan 级别，root 的 text-inner-tspan 否则会
 经 section-root 规则拿到 gitBranchLabel0（白色） */
.mindmap-node .label,
.mindmap-node .label div,
.mindmap-node .label span,
.mindmap-node .label p,
.mindmap-node .text-inner-tspan { color: #1D2129 !important; fill: #1D2129 !important; }

这里 fill 也要一起设——SVG 文字的着色走 fill 而不是 color，混排（HTML 标签 + SVG tspan）的图两种都要覆盖。

层叠顺序"直接命中 beats 继承"是 CSS 基本功，但在 mermaid 里特别容易栽：图型渲染器往内部元素上撒直接规则的习惯比一般网页重得多。div 上设 color “看起来生效了一部分”（普通节点对了，root 节点没对）比全不生效更迷惑人。

同特异性看插入顺序：neo 主题的渐变遮蔽

前面几条都是"我的规则被别人盖"，这一条反过来：mermaid 自己生成的规则会盖掉 themeVariables。

开 look: 'neo' 后（切换到 theme-neo 那套渲染），mermaid 会为 mindmap 每个分区生成带渐变填充的规则，并追加在 themeCSS 之后注入。同特异性时后者赢，结果就是我在 themeVariables.cScale0-5 里精心配的分区色全部被 mainBkg + gradient stroke 的统一渐变盖掉，mindmap 各分支变成同一种颜色。

绕法是在 themeCSS 里显式恢复，并用 !important 对抗插入顺序（规则来源无法控制顺序时，特异性又相同，只能加权重）：

1
2
3
4
5
6
7


/* src/themes.ts — under look:'neo' the generated gradient rule (appended
 later, same specificity) paints EVERY section box mainBkg + gradient
 stroke, masking the cScale section colours; restore per-branch pastels */
.mindmap-node.section--1 rect,
.mindmap-node.section--1 path,
.mindmap-node.section--1 circle { fill: #E8F3FF !important; stroke: #4098FC !important; stroke-width: 2.5px !important; }
.mindmap-node.section-0 rect, /* ...0-5 各分区同理... */

注意根节点是 section--1（双横线），分区是 section-0 到 section-N——这个命名也是 dump SVG 才能确认的。

mermaid 的规则注入顺序是"基础 themeCSS → 图型生成规则 → neo 渐变"，我方永远在下游被动挨打。能用 themeVariables 根键解决的绝不用 CSS，因为 CSS 要跟生成规则抢位置；根键走的是 Theme.calculate 的覆盖链，不受注入顺序影响。

验证方法论：dump + 反查，不靠记忆猜

以上每个坑的定位过程都指向同一套验证手段，值得单独总结。主题排错不要对着记忆猜优先级，两步拿到事实：

dump SVG 的 <style> 全部规则：把渲染产物 SVG 存下来，看 <style> 里到底注入了什么、顺序如何、有没有 #svgId 前缀、目标元素上挂着哪些规则。内联样式直接看元素的 style 属性。
getComputedStyle 反查：在浏览器 console 里对目标元素跑 getComputedStyle(el)，看 fill/color 的最终值，再沿匹配规则定位来源。

在 mmdx 里我把这个思路固化成了全覆盖检测脚本（scripts/theme-census.ts）：渲染全部图型，像素级统计颜色，凡是落在主题调色板和合成容差之外的都报警，外加一张"mermaid 原生刺眼默认色"黑名单按任意覆盖率标记（小元素如 journey 圆点面积太小，覆盖率阈值会漏报，只能靠黑名单兜）：

1
2
3


// scripts/theme-census.ts — allowed palette = themes.ts 里每个 hex 字面量 + 黑白
for (const m of themeSrc.matchAll(/#([0-9a-fA-F]{6})\b/g)) allowed.add('#' + m[1].toUpperCase());
// ...渲染后逐像素计数，接受"调色板色以某 alpha 合成到白底"的结果（抗锯齿/半透明填充）

关键设计：黑名单必须有定义来源（主题调色板全集），只列已知坏值（比如 #ECECFF 这个 mermaid 紫）会漏掉"自家主题色被误用"这类新形态——这也是我从教训里烧出来的：第一版检测脚本只黑名单了 #ECECFF，结果自己的 Arco 色被另一条规则覆盖了照样漏。

手工排错靠 dump + 反查，批量验收靠像素普查。两者缺一不可：前者定位单点，后者保证"改 A 没顺手弄坏 B"——主题这种全联动的东西，没有全覆盖检测就是在打地鼠。

颜色散落地图

最后一个 checklist 是"哪里能改哪个颜色"。mermaid 的颜色配置入口散落在至少四个地方，找对入口能省掉前五节大半的斗争：

图型/元素	颜色入口	备注
全局派生链	`themeVariables` 根（primaryColor 等）	根键永远生效，配这里优先
C4 元素填充	`config.c4.*`	不在 themeVariables；白字硬编码，填充必须够深
journey 分段	`themeVariables.fillType0-7`	圆点例外，见 assignWithDepth 一节
xyChart 调色板	`themeVariables.xyChart.plotColorPalette`	逗号分隔字符串，不是数组；默认头一个就是 `#ECECFF` 紫
radar 曲线	`themeVariables.cScale` + `config.radar`	cScale 粉彩在刻度网上不可读，我用 CSS 覆盖成 AntV 色
mindmap 根节点	`themeVariables.git0` / `gitBranchLabel0`	是的，mindmap 借用 gitgraph 的变量名
treemap	`cScale`（类目）+ `cScalePeer`	相邻分区色差太小，CSS 单独配
sankey	无主题变量	走 tableau10 硬编码，mmdx 里用渲染后 hex→hex remap 补救
neo look 渐变	`themeVariables.gradientStart/Stop`	注意 genGradient 遮蔽 mindmap 分区色

look: 'neo' 这个开关单独提醒：它不只是加圆角，是整套渲染走 theme-neo 的新代码路径，渐变生成、阴影、mindmap 分区行为都变了。我最后是 neo + 显式 CSS 恢复分区色的组合。

sankey 那行值得多说一句：连主题变量都没有的图型，唯一出路是渲染后处理。mmdx 的 ThemePreset.remap 就是为此存在的——PNG 出来前对 SVG 里的硬编码 hex 做一次映射表替换。丑，但比魔改 mermaid 源码可持续。

最后是工程坑：批量补丁怎么不翻车

上面的坑里有两类（补 themeVariables 大批键、补 themeCSS 大段规则）都涉及"往配置文件里批量插入大块内容"，这里踩的坑不在 mermaid 而在工具链：

坑一：超长 heredoc 截断。 用 bash heredoc 往文件里写整段 CSS/配置模板，内容一长（几百行）会被静默截断，文件尾部缺失。绕法：大块内容用 Write 工具（或编辑器）写成独立文件，再用小脚本拼接进去，heredoc 只留给几行的东西。

坑二：python 补丁必须带断言和回滚。 批量插入用锚点替换时，锚点选错（缩进差一层）就是我第一节那个 pie1-12 插错层的事故。防线两条：

1
2
3
4


# 每个 replace 前断言锚点恰好出现一次
assert src.count(anchor) == 1, f"anchor not unique: {anchor[:40]}"
src = src.replace(anchor, patched)
# 任何一步失败，整体回滚，不许半成品落盘

插入后立刻做层级断言：括号深度计数，断言新键在预期嵌套层级上。锚点替换赌的是"锚点文本唯一且位置如我所想"，断言是把这个赌注变成显式检查。

这两条是纯工程纪律，但和 mermaid 的坑叠加起来杀伤力最大：插错层是静默失效，heredoc 截断也是静默截断——两个静默叠在一起，你还以为自己的主题配置"试过了没用"。所有静默失败的工具链环节，都值得配一道显式断言。

总结成一句话：mermaid 主题定制的所有坑，本质是"三层优先级体系 + 散落的配置入口"——themeVariables 根键 > CSS（受 #svgId 前缀、注入顺序、内联 !important 制约）> presentation attribute，而 C4 白字、sankey 配色这类硬编码点只能改数据或后处理。排错永远从 dump SVG 开始，不要猜。下一篇写 mmdx 本身的设计，以及那套全覆盖像素检测是怎么建的。

给 MCP 服务器做减法（二）：从 MCP 退到 CLI 的 fail-loud 改造

Sun, 06 Sep 2026 20:05:43 +0800

给 MCP 服务器做减法（二）：从 MCP 退到 CLI 的 fail-loud 改造

上一篇讲的是 token 账——cbm 和 codegraph 两件套的定义层税有 ~8,600 tokens/会话。这一篇讲更彻底的一刀：把 cbm（codebase-memory-mcp）整个从 MCP 进程形态退到 CLI 形态，以及退的过程中撞出来的 fail-loud 教训。数据都是本机实测（Windows 11，cbm v0.10.8，codegraph v1.6.0）。

MCP 形态的固定成本：不只是 token

先看进程结构。MCP 形态下，cbm 是三层：

flowchart LR
A[MCP 客户端] -- stdio, 每会话一个 --> B[stdio server]
B -- IPC --> C[中心 daemon]
C -- fork --> D[index worker 池]

这个结构意味着三笔固定成本，而且没有一笔能省掉：

每会话拉起一个 stdio server。只要有 N 个客户端连着，就有 N 份进程开销。上游 #1764 报的就是这个：空闲 MCP 客户端每个烧 ~0.7 核，N 会话 = N 核。
daemon 冷启。CLI 侧实测冷启一次 daemon 约 5 秒；MCP 侧更糟，上游 #1955 报新客户端要等 15-30s 才能连上健康 daemon。
worker 的资源上限形同虚设。我实测索引本仓库（~1900 文件的 C 项目）时 worker 吃到 2.7GB 内存（预算 2.8GB 几乎打满）、242s CPU；282MB 的单个 exe；stdio server 在空闲时段还平均烧 ~30% 单核。预算是 advisory 的（#1973），宁可 OOM 也不降级（#1997 报 14k 文件 monorepo 全量索引分配 ~11.5GB，无视配置）。

然后才是 token 账。cbm 的 MCP 定义层（tools/list + initialize.instructions + prompts）实测 ~5,850 tok，15 个工具 22.4KB；跟 codegraph 合计 ~8,600 tok/会话。而且 cbm 的结果还是双份返回——tree 文本 + structuredContent JSON，同一份数据塞两遍进上下文。

单看哪个数字都不致命，叠起来就是"我明明没怎么用它，它却一直在烧"的体感。最后那根稻草是 watcher，先看 2026-09-04 那次实测的完整账单：

指标	实测值	备注
index worker 内存	2.7GB（预算 2.8GB 几乎打满）	PID 1172，索引本仓库
index worker CPU	242s / 运行约 2 分钟	~21% 单核
MCP stdio server CPU	330+ CPU 秒 / 17 分钟	空闲时段平均 ~30% 单核
二进制体积	282MB 单个 exe	cbm.zip 才 37MB
watcher 行为	`strategy=git` 每 3~5 秒一轮 + 每轮 reap 一个 worker	自触发重索引循环，#1953
同仓库 codegraph 对照	磁盘 1.1GB（db 160MB + WAL 882MB）	checkpoint 饥饿，与 cbm #1083 同款病

worker 触发链当时是实锤的：会话工具在仓库内写 .codegraph/、graphify-out/（未 gitignore、untracked）→ git-strategy watcher 判定 changed → daemon 反复 fork worker。这不是低概率 bug，是默认配置的必然后果——watcher 默认开、git 策略对 untracked 敏感、而工具产物恰恰就是 untracked 文件。上游四连发可以佐证这不是孤例：#1953 watcher 自触发、#2015 worker 失败无退避（有人 4h43m 里 fork 了 2233 个 worker）、#1083 WAL 无上限（有人跑出 115GB）、#1991 每请求 ~12ms 固定地板。

为什么裁剪在 MCP 侧做不干净

第一反应是裁工具面。cbm 支持 --tool-profile=scout，实测能从 argv 解析、立即生效，定义层 ~8.6K → ~5.8K tok。但往下走就发现问题了：

1
2
3


档位 1 scout 配置 → 省 32%，零改动，但 15 个工具里只留一小撮
档位 2 自编译加 arch 档 → 要改 src/mcp/mcp.c 的 mcp_tool_allowed()，约 20 行
档位 3 退出 MCP 走 CLI → 省 68%，15 个工具全部可用

档位 2 的尴尬在于：我想要的"arch 档"（get_architecture、query_graph、detect_changes、index_status、check_index_coverage、list_projects 这 6 个 codegraph 没有的工具）上游没有，得自己打补丁。而 cbm 0.10.x 几乎周更，上游自己的 profile 裁剪 PR（#1649 思路的 DACL 补丁）已经在冲突边缘——大补丁 rebase 会痛，这是结构性问题，不是手艺问题。

更隐蔽的是配置漂移。MCP 形态下 cbm 的行为散落在好几处：_config.db（藏在 cache 目录里，#1744 报升级会丢设置）、config.json、argv、daemon 启动时机。两个具体的坑：

1
2


watcher_enabled → 只在 daemon 启动时读，改完必须 daemon stop 再起
daemon 环境变量 → 被首个会话固化，后续会话无法按需调整

也就是说，就算工具面裁干净了，运行时行为还是被"谁先启动谁说了算"的 daemon 固化——每会话一个 stdio server + 中心 daemon 的三层结构里，daemon 环境被第一个连上来的会话定型，后面的人只能接受。

这是我最终选档位 3 的真正原因：不是 token 省 68% 有多诱人，而是 MCP 形态下"裁剪"永远是在别人的进程模型里打补丁。CLI 形态下，进程模型是我的，每次调用都是干净的一次性子进程，没有固化、没有漂移。

退到 CLI：全量 15 个工具，选择权交给 skill

形态变化一句话：cbm 不再注册为 MCP server，改用

1

codebase-memory-mcp cli --json <tool> [args...]

按需子进程调用。它有个很方便的性质：每个 MCP 工具都有 CLI 等价物，所以"裁剪"这个概念直接消失了——15 个工具全量可调，一个不少，也就不存在"profile 裁不干净"的问题。工具面不再占据每个会话的上下文，调用时才产生成本。

定义层的账当场就变了：

组合（定义层）	≈ tokens/会话	相对两件套
cbm MCP + codegraph MCP（现状）	~8,600	—
cbm scout 档 + codegraph	~5,840	省 32%
cbm arch 补丁档 + codegraph	~4,550	省 47%
cbm 退 CLI，仅 codegraph 进 MCP	~2,750	省 68%

而且 bytes/4 是乐观估算——schema 是标点密集的 JSON，真实分词约 bytes/3~3.5，两件套体感可能到 ~10-11K tokens。CLI 形态下这笔税直接归零。

代价是模型看不到工具列表了，“什么时候用哪个命令"得有人管。我的方案是用 skill 规约约束，而且刻意收得很窄——只保留三个实测有效的场景，其余一律禁用：

场景	命令	为什么留给 cbm
架构概览	`cbm cli get_architecture`（aspects=clusters/cycles/hotspots）	cbm 独有，codegraph 无架构视图
图查询	`cbm cli query_graph`（Cypher、复杂度门槛）	cbm 独有
commit 影响半径	`cbm cli detect_changes`（git diff → 传递影响集）	diff 基，codegraph 的 impact 是符号基

规约里还给三类典型工作流定了调用法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


开源调研 clone 后 codegraph init + index（一次全量，之后增量自动）；
 cbm 只在确定要做架构级分析时 index_repository mode=full（语义边只有 full/moderate 有），
 用完 daemon stop；大仓（>1 万文件）用 mode=fast 先垫底。
 引用代码前必跑 check_index_coverage——parse_partial 区域的图结果不可信。

二次开发 日常 impact/callers 走 codegraph；提交前跑一次 cbm detect_changes 当"影响面自检"，
 配合 query_graph 查改动的传递调用深度。
 cbm watcher 关掉（#1953），索引新鲜度靠提交前手动 index。

自研项目 仓库 < 几千文件时 codegraph 一个就够；cbm 只做里程碑体检
 （get_architecture aspects=cycles,hotspots 查循环依赖和上帝节点）。

配套的索引分层原则也写进了规约：

1
2


codegraph = 活层（always-on，保存 ~0.3s 增量，喂日常符号工作）
cbm = 深层（milestone / 按需全量，喂架构分析与影响面，用完 daemon stop）

会话开始时 hook 自动 init/sync，我不手动管索引；cbm 只在确定要做架构级分析时 index_repository 一次，用完 daemon stop。产物目录（.codegraph/、.codebase-memory/）一律 gitignore，防 watcher 互喂。

这里有个反直觉的取舍：CLI 化之后单次冷启 daemon 要 ~5 秒，比 MCP 常驻"慢"了。但对一个每会话只按需调两三次的深层工具，5 秒 × 2 次 < 常驻进程烧掉的一切——包括那个 watcher 死循环和 2.7GB worker。低频工具的合理形态就是一次性子进程，不是常驻服务。

fail-loud：静默空结果比报错更危险

CLI 化过程中最值钱的教训是这个：工具返回"空结果"有两种可能——真的没有，或者工具坏了。MCP 形态下这两者都表现为一个正常的响应，模型根本分不清。三个实锤案例（记载在我的环境备忘里，均为实测）：

案例一：upstream #1682。 CALLS 边丢失时，trace_path 返回 callers_total: 0——和"这个函数真的没有调用方"在响应格式上完全不可区分。我一开始信了图谱的"没有调用方”，后来 grep 复核才发现调用方明明存在。

案例二：detect_changes 对非法 direction 静默返回空。 传错参数不报错，返回一个空的影响集。影响面自检场景里，“空"意味着"这次改动无风险”——把工具错误翻译成了错误的安全结论。

案例三：since 参数拒收 ^ 后缀。 传 v1.0^ 直接被拒。这算好的，好歹是个显式失败——但如果不看退出码，管道里它同样表现为"空"。

1
2
3
4
5


危险的共同模式：
 输入非法 / 内部状态损坏
 → 静默返回空集
 → 模型把"空"读成"事实上的不存在"
 → 下游结论全错，且无任何报错痕迹

防御手段我总结成三条，全部写进了 skill 规约：

否定性结论必须 grep 复核。“没有调用方/没有引用"这类结论，图谱零结果不可信——静默漏报与真实无调用不可区分，先 grep 原文再下结论。
批量修改必须带断言。用脚本补丁改配置时 assert count == 1，失败即整体回滚。我实际靠这个救回过两次——python 补丁锚点缩进错误，把一批配置键插进了错误的嵌套层级（比如插到 themeVariables.xyChart 内部），键"存在"但静默失效。批量改配置结构后还要用括号深度计数脚本断言键的层级，或者干脆整段重写而不是锚点替换。
黑名单 + 全量审计代替打地鼠。检测的"坏值清单"必须有定义来源（比如主题调色板全集），只列已知坏值会漏掉"自家配置被误用"这类新形态。正确姿势是先渲染全部形态 → 像素级/结构级普查 → 对照定义来源全集，一次扫完，而不是发现一个修一个。

把这三条合在一起，就是 skill 规约里给所有图谱类工具定的防呆前置：

1
2
3


调图谱工具前： index_status 确认索引新鲜度（索引落后时 detect_changes 结果失真）
调完拿结论前： 结论是"空/没有/零" → 强制 grep 复核，禁止直接采信
写脚本改配置： assert count==1 + 层级断言，失败即整体回滚

这三条没有一条是 cbm 特有的——任何"返回结构化结果"的工具都适用。图谱只是把问题放大了，因为它看起来太可信了：返回带行号、带符号名的精确结果，模型（和我）都倾向于直接信。

有意思的是，这个原则直接催生了 fork 补丁计划里的 #4：给 cbm 加配置化工具禁用清单（tools_disabled，双侧生效），要求禁用必须 fail-loud——调用被禁的工具要显式报错而不是静默失败，且 --help 输出与实际工具面一致。禁用一个工具后它还能被调用、或者 help 里还列着，都是配置漂移的静默形态。

fail-loud 说白了就一句话：宁可让错误炸在这一层，也不要让它变成一层之下的"空结果”。静默空结果最阴险的地方在于它消耗的是信任而不是报错——你不会去排查一个"正常"的空响应。

Windows 的 DACL 仪式

CLI 化没解决的一个问题：cbm 在 Windows 上对 daemon endpoint 做强制 ACL 检查（上游 #1624/#1856/#2023 的 ACL 设计），撞上时直接报 secure daemon endpoint could not be created。

我踩过的绕法，按代价排序：

1
2
3
4
5
6


# 1. 搬运行时目录（官方思路，但只能搬家不能豁免检查本身）
CBM_RUNTIME_DIR=D:\data\codebase-memory-mcp\runtime

# 2. 临时绕过：收紧目标目录 ACL 让检查通过（D:\data 这么干过，事后要 icacls /reset 恢复）

# 3. fork 补丁计划 #2：加 CBM_SKIP_DACL_HARDENING 开关

#2 的关键是：CLI 形态同样受 DACL 检查拖累——退到 CLI 躲开了 MCP 的进程结构税，但躲不开单机安全检查对本地回环通信的开销。CBM_RUNTIME_DIR 只是把战场挪走，检查本身还在跑。所以补丁计划里专门立了 #2：一个显式的跳过开关，本地单人场景没必要每次都做安全仪式。

这类问题在 Linux 上根本不存在，纯 Windows 单机税。但代价结构很典型：设计给多用户/低信任场景的防御，在单用户高信任环境里变成每个请求都要交的过路费。和 MCP 工具面裁剪是同构的——都是"默认配置为我不存在的场景付费"。

fork 补丁计划：把教训变成 issue

最后整理一下 fork 仓库的 issue 清单。写出来是因为每一条背后都是上面某一节的一个教训：

#	内容	状态
#1	CLI 方案取代 profile 裁剪	已关闭——直接退 CLI，profile 档位没了存在必要
#2	`CBM_SKIP_DACL_HARDENING` 开关	待做——CLI 侧同样受检查拖累
#3	默认值反转	待做——已补 CLI 侧证据：daemon 冷启 ~5s/次、detect_changes 非法 direction 静默空、since 拒收 `^`
#4	配置化工具禁用清单（tools_disabled 双侧生效 + fail-loud + `--help` 一致性）	待做——挡住实测判负的 5 个工具被误用

补丁纪律沿用之前定下的：机械、小、可重放。上游几乎周更，#1649 已经在冲突边缘，任何超出"加一组名字/加一个开关"粒度的补丁都是给未来的自己挖坑。

值得单独说的是 #1 被关闭这个信号：最初计划里"给 MCP 加更好的 profile 档位"是正经理方案，做着做着发现 CLI 形态让整个问题消失了。最好的裁剪是不需要裁剪——工具面从来不进上下文，就无所谓留哪 6 个砍哪 9 个。

这套退法在整体方案里的位置

退 CLI 不是孤立动作，它是一个分层方案的地基。完整规划是三步：

1
2
3
4


P0 只包 codegraph 进 MCP（4 个短工具：search / source / relations / impact）
P1 CBM 保持 CLI 按需调用——本文讲的退法就是这一步的落地
P2 仅当"出会话跑 CLI"摩擦大到不可接受，才在门面里延迟拉起 CBM 三个工具
 （第一次调用才 spawn cbm cli，空闲超时 daemon stop）

配套的验收清单里，几条硬指标直接针对 MCP 形态的老病：

1
2
3
4


- 会话 tools/list 工具数 ≤ 8，描述合计 ≤ 4KB（对 ~22.4KB 的 cbm 全量）
- 日常 search/source/relations/impact 不启动 cbm.exe / cbm daemon
- 结果无双份 JSON（cbm 的 tree + structuredContent 双份是重点封杀对象）
- 需要架构分析时有文档化的 CLI 一步（含 daemon stop）

同样重要的是"明确不做"清单：不给 cbm 关 LSP、拆 daemon、硬内存上限——那是敌对 fork，和周更上游打架。改不动的地方绕过去（CLI、CBM_RUNTIME_DIR），绕不过去的立 issue（#2/#3/#4），这就是补丁计划全部是"开关级"改动的原因。

复盘下来，“从 MCP 退到 CLI"与其说是性能优化，不如说是一次责任边界的回收：进程模型、调用时机、失败语义，全部收回到我自己的 skill 规约里。代价是我要自己维护规约、自己复核否定性结论。但考虑到静默空结果曾经让我把"图谱说没有调用方"当成事实写进结论——这笔交易不亏。

给 MCP 服务器做减法（一）：实测判负的工具与裁剪依据

Sun, 06 Sep 2026 20:04:24 +0800

给 MCP 服务器做减法（一）：实测判负的工具与裁剪依据

我深度用了两周 codebase-memory-mcp（下称 cbm），一个把代码库索引成知识图谱的 MCP 服务器，15 个工具。结论是：15 个里只有 3 个场景真正立住了，其余全部判负——要么被 codegraph 同类工具碾压，要么 CLI 里一行命令就有等价物，不值得在每轮对话里交定义层税。这篇记录判负的证据和方法，不记录情绪。

先算账：15 个工具的定义层税单

判负之前先量化"养着这些工具要花多少钱"。MCP 的成本模型里有个容易被忽略的项：工具定义不是调用时才付费，而是每个会话每轮对话都常驻在上下文里。

cbm 是 stdio server，我就以 MCP 客户端身份把它拉起来，抓 tools/list 的真实载荷。探针是个几十行的 Node 脚本（简化版）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// mcp_probe.cjs：拉起 stdio server，抓 initialize + tools/list 全量载荷
const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "inherit"] });

send({ jsonrpc: "2.0", id: 1, method: "initialize",
 params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "probe" } } });
send({ jsonrpc: "2.0", method: "notifications/initialized" });
send({ jsonrpc: "2.0", id: 2, method: "tools/list" });

child.stdout.on("data", buf => {
 // 按 Content-Length 拆帧，落盘每个响应的原始字节数
 frames.push({ id: msg.id, bytes: buf.length, payload: msg });
});

初版只量了 tools/list，后来发现漏了两项：MCP initialize 响应里的 instructions 字段（规范客户端会注入系统提示词）和 prompts 列表。补齐后的完整账单：

定义层	codegraph	cbm 全量
tools/list（描述+schema）	6,762B ≈ 1,691 tok	22,441B ≈ 5,610 tok（15 个工具）
instructions 字段	4,226B ≈ 1,057 tok	808B ≈ 202 tok
prompts 列表	无	2 个 ≈ 37 tok
定义层小计	≈ 2,748 tok	≈ 5,850 tok

payload 字节数到手后换算 token。这里有个容易自欺的地方：用 bytes/4 估是乐观值，对 schema 这种标点密集的 JSON，真实分词更接近 bytes/3~3.5：

1
2
3


// 估算口径：两档一起报，给区间不给单点
const tokensOptimistic = bytes / 4; // 乐观下界
const tokensRealistic = bytes / 3.5; // 标点密集 JSON 的经验档

两个 server 一起挂着，定义层合计 ≈ 8,600 tokens/会话，乐观估算下真实体感可能到 10-11K。

最扎眼的是 codegraph 那行 4.2KB 的 instructions：一整套行为指令（“直接回答别委派子 agent"“先于 Read/Grep 调用”）。这是把工具用法写死进系统提示词，替模型做工作方式决策。cbm 反过来，instructions 很短，但用 15 个工具的长描述把复杂性全堆在 tools/list 里。两种路线，交的税一样。

调用时的开销另算，而且更隐蔽：cbm 每个结果是双份返回——tree 文本和 structuredContent JSON 是同一份数据给两遍，结果侧直接 ×2。codegraph 单份但载荷密，官方自己承认常驻上下文 +80%。

结果侧的浪费也顺手写进了探针：同一个结果，content 里是 tree 文本，structuredContent 里是同数据的 JSON 序列化。对模型来说信息为零增益，token 直接翻倍。

判负的标准：三条硬证据

“我感觉没用"不是裁剪依据，MCP 工具面的每一次删减都要能回答：删了之后工作流会不会退化？

我的判负标准是三条，全部可复测：

真实调用率：回看若干个真实会话的调用记录，哪些工具被 agent 主动调过；
结果质量：调了之后，是否真的省掉了后续的 grep/Read 次数，还是拿到结果还得回原始文件验证；
CLI 等价性：这个工具在 cbm cli 里有没有一行等价命令——有的话，退出 MCP 只损失"agent 自主发现"这一点，能力不丢。

第 1 条有个陷阱要说明：agent 不调 ≠ 工具差。可能是 schema 写得糊、描述太长模型没读进去。但对裁剪来说结论一样成立——一个 agent 不会主动调的工具，挂在工具面里就是纯税。

这三条里第 3 条最关键，它把"裁剪"从减法变成了搬家：MCP 定义层省下的 token 是确定的，能力通过 CLI 随时可取回。没有等价物的工具才需要真正纠结去留。

还有一个反向的佐证：实测里 agent 对工具的误用集中出现在少数几个工具上——schema 越长、描述越糊，模型越容易拿错误的参数组合去撞。工具面越长这个问题越严重，15 个工具互相干扰，单个工具的描述再精准也救不回来。

逐个判负：砍掉的、留下的、可惜的

15 个工具过一遍筛子。判负名单按"被谁替代"分组，证据都来自实测记录和上游 issue。

flowchart LR
A[cbm 15 个工具] --> B{三条硬证据筛}
B -->|被 codegraph 碾压| C[判负组 1：符号级查询]
B -->|CLI 有等价物| D[判负组 2：管理面]
B -->|真实会话零调用| E[判负组 3：list_projects]
B -->|三场景对照实验立住| F[保留：3 个场景工具]

判负组 1：符号级查询，被 codegraph 碾压。 这是最大的一组。符号搜索、取源码、调用链——这些是 codegraph 的基本盘，而且强得多：

能力	cbm 工具	codegraph 对应	判负理由
符号搜索	search_graph	search	codegraph 一次返回限定元数据，够用且轻
取源码	get_code_snippet	node / explore	explore 一次拉一组符号的完整源码，cbm 做不到
调用链	trace_path	callers / callees / trace	cbm 有 #1991：每请求固定 ~12ms 地板（0.9.0 时代是亚毫秒），codegraph 无此税

trace_path 的判负最干脆：调用链分析 codegraph 的 callers/callees/trace 全覆盖，cbm 这边还背着 12ms/请求的进程间协调地板。同一次查询，没有理由选慢的那个。

判负组 2：管理面，全走 CLI。 索引、同步、daemon 控制（index_repository、daemon stop、config 类）占了好几个工具位，但它们的调用者是人，不是 agent——我从来没需要让模型自主决定"什么时候重建索引”。这类工具留在 MCP 工具面里，等于让每轮对话为低频管理操作付常驻税。

判负组 3：list_projects。 T1-T3 对照实验里，三个真实场景（架构概览、图查询、变更影响）它一次都没进过调用路径，而 CLI 里一行就有。典型的"挂在那显得功能全"的工具。

唯一可惜的舍弃：semantic_query。 概念级查找（“找处理重试的逻辑"这类不精确匹配符号名的需求）是符号搜索真覆盖不了的。但它依赖向量语义边——而语义边恰恰是素材里判定"贬值最快"的那类增值插件。如果哪天真需要，方案是把它做成搜索工具的可选参数挂 vector 索引，不单开工具。

留下的：3 个场景。 对照实验里立住的三个，恰好都是 codegraph 没有的能力：

1
2
3
4
5
6
7


get_architecture # 架构概览：Leiden 社区划分、复杂度热点、循环依赖
query_graph # 图查询：写 Cypher 做"谁调了 X"、跨模块模式确认
detect_changes # 变更影响：git diff → 受影响符号的传递集（提交前自检）

# 另有两个排查辅助留在 CLI 侧，不进 MCP：
index_status # 索引新鲜度——结果失真前先看这个
check_index_coverage # 覆盖度审计——parse_partial 区域的图结果不可信

这 3 个能立住不是偶然：get_architecture 的 Leiden 社区和 detect_changes 的传递影响集是图算法，tree-sitter 解析完之后的加工增值；而符号级查询本质是"更贵的 grep”，模型演进越快这类工具越容易被原生搜索追平。不贬值的是图算法、覆盖度审计、跨会话索引资产——裁剪就是留下不贬值的。

中间档：scout 和 arch，为什么不选

裁剪不是只有"全留"和"全退"两个选项。cbm 官方有 tool-profile，自编译还能加自定义档，我在这两档之间停留过，最后还是走了 CLI。

scout 档是零改动方案，一行配置：

1
2
3
4
5
6
7
8


{
 "mcpServers": {
 "codebase-memory-mcp": {
 "command": "codebase-memory-mcp",
 "args": ["--tool-profile=scout"]
 }
 }
}

arch 档官方没给，要自己编译——在 src/mcp/mcp.c 的 mcp_tool_allowed() 里加一组工具名，约 20 行：

1
2
3
4
5


// 思路示意：在白名单函数里加一个档位判断
if (strcmp(profile, "arch") == 0) {
 return tool_in(tool, "get_architecture", "query_graph", "detect_changes",
 "index_status", "check_index_coverage", "list_projects", NULL);
}

三档的省幅：

档位	动作	定义层 token	相对现状
现状两件套	—	~8,600	—
scout 档	一行配置	~5,840	省 ~32%
arch 档	自编译补丁	~4,550	省 ~48%
退出 MCP	CLI + skill	~2,750	省 68%

scout/arch 档对"还想留在 MCP 里"的人是合理阶梯。但它们有个共同问题：判负的工具只是被藏起来了，定义层的判断负担还在——我要持续维护"哪些该露出来"的清单，而 CLI 路线把这个维护成本一次性归零。既然判负证据已经够了，中间档只是延迟同一个结论，我没有停在那。

保留集的工作流：CLI + skill 配方

退出 MCP 之后，cbm 的形态从"server 常驻"变成"按需起进程”。三个场景各自有固定配方：

1
2
3
4
5
6
7
8


# 场景 1：架构概览——大仓库第一刀，先看事实上的模块切分
cbm cli get_architecture --aspects clusters

# 场景 2：跨模块确认——Cypher 直查
cbm cli query_graph --query "..."

# 场景 3：commit 影响半径——提交前跑一次当自检
cbm cli detect_changes --since HEAD~1

和 CLI 配套的是把配方烧进一个 skill：skill 里写死"什么信号出现时调哪个 CLI 命令、结果为空怎么排查"。这相当于把"MCP 工具描述"的引导职能从定义层搬到了 skill 文本——区别是 skill 文本只在需要时加载，不占每轮对话。

说白了这是一笔交换：放弃 agent 的自主发现（模型自己看到工具描述决定调用），换成确定性调度（skill 规则触发）。实测下来 agent 自主发现 15 个工具的成功率并不高——schema 太长，描述互相干扰，误用和空转不少。确定性调度反而准。

两个 server 的分工随之定型，索引也分成两层：

1
2


codegraph = 活层（always-on，保存后 ~0.3s 增量，喂日常符号工作）
cbm = 深层（milestone/按需全量，喂架构分析与影响面，用完 daemon stop）

裁剪后的定义层税单：8,600 → 只剩 codegraph ≈ 2,750 tok，省 68%，且 cbm 的结果侧双份开销也一并消失。

反向参照：如果只留 8 个工具，理想长什么样

判负做完，我把两个 server 的能力摊在桌面上重新排列了一次：假如从零设计一个最小工具面，它应该是什么形状。这张表也是裁剪依据的一部分——它划出了"该留的"和"增值插件"的边界。

六个能力层、8 个工具，管理面全部走 CLI 不占 MCP 定义层：

层	工具	接口要点	对应物
L1 定位	search	名称/正则/BM25，返回限定元数据	codegraph search
L2 读取	source	符号 → 源码+签名+紧邻调用	codegraph node / explore
L3 关系	relations	方向(in/out/path)+边类型，游标分页	codegraph callers/callees/trace
L4 变更	impact / diff_impact	符号级影响；git diff → 传递影响集	codegraph impact / cbm detect_changes
L5 导览	architecture	modules(社区)/cycles/hotspots	cbm get_architecture（独有）
L6 信任	coverage	逐文件解析覆盖+索引新鲜度	cbm check_index_coverage（独有）

按短描述+精简 schema 算，8 工具的定义层预算约 3-4KB ≈ 900 tok。对比现状 8,600，省幅在 70% 以上。

同样重要的是明确排除的清单——这些是调研里判定"贬值最快"的增值插件：

1
2


向量语义边、相似度边、跨仓 intelligence、运行时轨迹注入、
ADR 存图、graph UI、常驻 daemon/协调层

这张表给我的最大启发是"成本前置 vs 成本后置"的分野：cbm 是成本前置 + 捆绑销售（耐用品和易耗品强制一起买），codegraph 是成本后置 + 行为导演。模型演进越快，为弱模型设计的补偿性智能贬值越快——L1 到 L3 那几层本质是"更贵的 grep"，而 L5/L6 依赖的图算法和覆盖度审计不会贬值。裁剪清单和这张表是同一个判断的两个投影。

代价核对：判负清单之外的理由

工具面裁剪解决 token，但 cbm 的账不止这一页。记录性能侧的实测，作为"为什么不留着试试"的补充证据。

2026-09-04 的一次普通会话里抓到的数字（本机 Windows 11，~1900 文件的 C 项目）：

指标	实测值	对应上游 issue
index worker 内存	2.7GB（预算 2.8GB 几乎打满）	#1973：预算是 advisory，宁可 OOM 不降级
MCP stdio server	空闲时段 ~30% 单核	#1764：每个空闲客户端烧 ~0.7 核
二进制体积	282MB 单个 exe	—
watcher	每 3~5 秒一轮自触发重索引	#1953：git 策略对 untracked 文件敏感，工具产物喂它死循环
失败 worker	无退避无限重 fork	#2015：4h43m 内 2233 个 worker

触发链已经实锤：会话工具在仓库里写 .codegraph/ 这类产物目录 → git-strategy watcher 判定 changed → daemon 反复 fork worker。解法之一是把产物目录 gitignore，但更根本的是——一个"高性能"卖点著称的索引服务，默认配置下会和客户端工具互相喂出死循环，这本身就是工具面之外的设计债。

cbm 的深度（LSP 类型解析 + 语义边）是用内存和常驻进程换的，codegraph 的增量快是用磁盘和 WAL 换的，没有免费午餐。但"深度"大部分在判负清单里已经卖不出去了——剩下 3 个场景恰恰不依赖常驻 daemon，按需起进程跑完就停，反而是对它资源模型最友好的用法。

裁剪的尽头是一个朴素的判断：MCP 工具面应该只放"agent 每轮都可能自主用到"的东西，低频能力、管理面、被更强工具覆盖的能力，都该退到 CLI。15 个工具筛完剩 3 个场景，token 省 68%，误用率归零（没有可误用的了）——这个比例让我怀疑大部分 MCP 服务器都超配了一倍以上。下一篇写从 MCP 退到 CLI 的过程中暴露的另一类问题：CLI 静默失败——空结果和真失败不可区分，agent 拿着空输出继续推理，比误用工具更危险。所以下一步是给 CLI 做 fail-loud 改造：非法参数报错、空结果带原因、退出码讲真话。

Higress 端点级断路器（二）：全拉黑放行——最反直觉的设计决策

Sun, 06 Sep 2026 20:03:25 +0800

Higress 端点级断路器（二）：全拉黑放行——最反直觉的设计决策

系列第二篇。上一篇写了慢故障的统计口径——5s 去重间隔、70s 慢阈值 × 2~~3 次确认拉黑、TTL 30~~60s 惰性恢复，这一篇只讲一个分支：当所有端点都被拉黑时，插件选择放行、不做屏蔽，让请求继续打到所有节点上。第一次推演到这个 case 时，我的直觉答案是"该 503"；把时间轴往下多推一步，就改了主意。

从一次"差点全拉黑"的推演讲起

先把这个最坏场景摆出来。假设网关后面挂着一个 provider 的三个端点，上游网络抖动 30 秒：

1
2
3
4
5
6


t=0s 抖动开始，请求陆续变慢/超时
t=8s 端点 A 慢样本确认满 2~3 次，拉黑 → 流量集中到 B、C
t=15s B 被集中流量压垮，拉黑 → 流量全压 C
t=22s C 独木难支，也拉黑
t=23s 候选集为空 —— 此刻屏蔽过滤要不要生效？
t=35s 上游抖动结束，实际已恢复

前三步都是正常的断路器行为，问题出在 t=23s。候选集为空时最自然的写法是返回 503，但注意时间轴上还有 t=35s：抖动结束了，上游恢复了，然后呢？

黑名单的解除靠什么？靠 TTL 到期的惰性恢复——端点在 blockUntil 过期后自动回池。503 方案的问题不是永久锁死（TTL 终究会到期），而是恢复时刻被 TTL 绑架：t=35s 上游已经恢复，可每个端点要等各自的 blockUntil 过期才回池，这段时间网关在主动 503，白瞎已经恢复的容量。TTL 是按"最坏故障时长"配的，通常远长于一次真实抖动——为了防误判把 TTL 配长，结果真故障短了也要多陪等一整段。而放行的代价只是请求继续打到（可能已恢复的）节点上：打成功就是赚的，打失败也只是维持本来的坏状态。上游明明恢复了，网关却握着屏蔽名单不放，故障没扩散，是屏蔽逻辑替它完成了最后一击。

推演到这一步我才意识到，“全拉黑"根本不是一个正常的状态转换，而是一个危险信号：它要么说明故障大面积爆发，要么说明统计在误判。两种情况的处理方式殊途同归，下面分开说。

放行的分支设计

先交代状态结构，这段来自我的 failover 设计文档（Go filter 方案那一层；统计形态在不同落地载体上有差异——wasm 里是 SharedData 分片，Go filter 里是进程内全局——这里按设计文档的形态讲），端点级统计就挂在这个全局结构上：

1
2
3
4
5
6


var healthState = struct {
 sync.Mutex
 failures map[string]*slidingWindow // 每 provider 失败滑动窗口（被动健康）
 probes map[string]*probeResult // 主动探测结果（goroutine ticker 维护）
 quota map[string]*tokenBucket // 配额余量（rate_limiting 降级）
}{}

屏蔽过滤发生在选端点阶段，分支逻辑用伪代码表达（实现细节从略）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 候选端点过滤：拉黑名单的放行分支
func filterEndpoints(eps []Endpoint) []Endpoint {
 healthy := make([]Endpoint, 0, len(eps))
 for _, ep := range eps {
 if !blacklisted(ep) { // 黑名单来自慢阈值判定（70s × 2~3 次确认，5s 去重间隔）
 healthy = append(healthy, ep)
 }
 }
 if len(healthy) == 0 {
 return eps // ← 全拉黑：放弃过滤，全量放行
 }
 return healthy
}

用流程图看这个分支在整体调度里的位置：

flowchart TD
A[请求进入] --> B{黑名单过滤}
B -->|部分端点被拉黑| C[返回健康候选集]
B -->|无端点被拉黑| C
B -->|全部被拉黑| D[放弃过滤
全量放行]
C --> E[priority → weight 轮询选端点]
D --> E
E --> F{请求结果}
F -->|成功| G[请求成功
端点按各自 TTL 到期回池]
F -->|失败| H[失败样本继续入账
回池后重新判定是否再拉黑]

注意 t=23s 之后发生了什么：放行意味着请求继续打到这些端点上，上游一恢复请求就直接成功；屏蔽名单里的端点则在各自 TTL 到期后惰性回池——恢复路径上没有任何额外的状态转换。而 503 方案里，恢复时刻被 blockUntil 绑死，TTL 配多长就白等多久。放行不是妥协，是让"上游恢复"这个事实能立刻传导到流量上。

有一个容易混淆的边界要划清。我的设计文档初稿里，provider 级选择循环的兜底是这样写的：

1
2


p := pickProvider(providers) // priority → weight 轮询 → 健康/配额过滤
if p == nil { SendLocalReply(503, "all providers failed"); return }

这行 503 我保留，而且认为它是对的——因为它的前提是每个 provider 都真实尝试过且失败。端点级拉黑放行针对的是另一种情况：请求还没发出去，就被统计先验判死了。两者的区别一句话：试出来的全失败可以 503，统计出来的全失败必须放行。

这个设计不是我拍脑袋拍出来的。APISIX 的 ai-proxy-multi 在实例健康过滤上做了完全相同的选择：所有实例均无健康节点时返回 {all_unhealthy=true}，回退为"全量可用”，不直接 503。它的设计取舍表里写得很直白，理由是"避免误判把实例永久打死；宁可试错"。机制有差异——APISIX 的 fail-open 建立在 active health check 判死之上，我的拉黑来自被动耗时统计（5s 去重间隔 + 70s × 2~3 次确认）——但兜底语义一致，说明这是这一类系统共同交过学费换来的结论。

误判从哪来

放行的合理性取决于一个概率判断：全拉黑里有多少是真故障、多少是误判。把误判来源列全：

误判来源	机制	为什么会被当成端点故障
网络抖动	网关到 provider 的链路瞬断/丢包	多端点往往共享同一条出口链路，抖动会"同时"打挂所有端点的统计——这恰恰说明故障在链路不在端点，逐端点拉黑是错误归因
provider GC 停顿 / 冷启动	服务端扩容、发布、JVM GC 导致延迟飙升触发超时	超时被计入失败样本，但停顿结束即恢复，端点本身没坏
样本量小	低峰期单端点分钟级请求个位数	两三个失败就能把失败率顶过阈值，统计噪声被放大成"故障"
5s 去重间隔的局限	间隔内同端点慢样本去重计数，防单次抖动被放大	但间隔一过同一场故障重新起算——30 秒的抖动能贡献约 6 个样本，足够攒满 2~3 次确认，去重防的是重复计数，防不了跨间隔的持续误判

两个分支分别看：

真的大面积故障：屏蔽已经无意义。屏蔽的价值是"把流量从坏节点挪到好节点"，前提是还有健康节点可分流量。全坏时无处可挪，打了也白打——但不打更糟，不打就是主动放弃恢复窗口。
统计误判：放行是唯一的自愈通道，理由上面已经推演过，不重复。

有意思的是第二个观察：全端点同时"故障"，大概率意味着问题不在端点层。真正每端点独立坏掉且坏的时间完全同步，本身就是小概率事件；同步失败更常见的解释是共享层出问题——出口链路、账号配额、provider 整体。这时候逐端点拉黑不但无用，还在用屏蔽逻辑制造第二层故障。

和经典断路器的 half-open 对照

经典 circuit breaker 是三态机：closed → open（熔断）→ 冷却后进入 half-open → 放少量探测请求 → 成功则回到 closed。对照下来会发现，全拉黑放行相当于跳过 half-open，直接退化成"无熔断直通"：

	经典 half-open	全拉黑放行
探测流量	限量（如每周期 1 个请求）	全量，所有请求都是探测
恢复判定	探测成功 N 次才闭合	TTL 到期惰性解封，真实流量重新判定
额外状态	需要 per-endpoint 状态机 + 冷却计时器	零，复用已有的滑动窗口
上游真死时的代价	只有探测请求打到死节点	所有请求都打到死节点，错误率/延迟全暴露

第三行是我选后者的现实原因：滑动窗口里已经有一份跨请求的失败统计了，再为 half-open 维护一套状态机和计时器是重复建设。但更本质的是前两行——half-open 解决的问题是"探测风暴打死正在恢复的上游"，而 LLM 网关的场景里探测流量就是正常流量本身，不存在额外风暴；反过来，“探测不足导致恢复延迟"才是主要矛盾。

还有一个领域差异值得记下：LLM 上游的故障很少是"瞬间全好或全坏”，更多是逐渐恢复、部分恢复（限流解除一部分、扩容落了一半实例）。half-open 的"限量探测 + N 次成功闭合"假设恢复是离散事件，跟这种渐变恢复对不上；全量放行 + 持续统计天然形成软探测，每一分钟都在试探上游，恢复到什么程度，流量就自然分过去多少。

所以这里的结论是：不是 half-open 不好，是它的适用前提（探测流量需要被限制、恢复是离散事件）在这个场景不成立。设计模式照搬之前先核对前提，这个 case 给我上了一课。

反思：宁可慢、不可全断

全拉黑放行是有代价的，我不打算把它说得像免费午餐：全拉黑期间客户端会真实感受到高延迟和错误率，因为请求确实在打坏节点。但这个代价是有界的——上游一恢复，放行路径上的请求直接成功；拉黑的端点按各自 TTL 到期回池，最坏也只多等一个 TTL 周期。而 503 的代价是无界的——恢复时刻被 blockUntil 绑死，TTL 配多长就白瞎多久，还可能伴随客户端的 503 重试风暴。

为网关类组件做设计时，我现在的判断标准就一条：宁可慢，不可全断。慢是上游的病传导过来，断是网关自己在病上加了病。屏蔽、熔断、拉黑这些手段全都只有一个合法目标——在还有健康容量时保护性地挪流量；一旦健康容量归零，它们的使命就结束了，继续执行只会从保护变成伤害。

还有一条线值得单独展开：流式（SSE）请求的取舍——响应头之前可以换端点重试，流中失败只能截断，APISIX 和我的方案在这做了相同的让步。这篇先不展开。

一个还没想清楚的问题留在这里：放行分支要不要加一个"全拉黑持续时间"的告警钩子？放行是运行时自愈，但如果全拉黑状态持续几分钟不解除，多半说明真故障或者统计参数需要调了——这个信号现在只落在日志里，值不值得升格成独立指标，我还在犹豫。

Higress 端点级断路器（一）：本地 Provider 的端点屏蔽与 TTL 控制

Sun, 06 Sep 2026 19:59:22 +0800

Higress 端点级断路器（一）：本地 Provider 的端点屏蔽与 TTL 控制

上游换成私有化部署的 LLM 端点之后，故障形态变了：不报 429、不吐 5xx，就是慢——请求挂在网关上几分钟才吐结果，用户早走了。这篇记录我基于 ai-load-balancer 做的一层端点级断路器：响应耗时持续突破阈值（2~~3 次确认）就把端点拉黑，TTL 30~~60s 到期自动放回负载均衡池。整套设计里我最满意的是统计层的 5s 去重间隔——同一端点短时间内只计一次，既防高频请求重复统计，也配合确认次数把一次抖动挡在误判之外。

动机：慢节点拖尾是私有化部署的特有痛点

之前写过一篇处理 Higress 网关的端点故障屏蔽，针对的故障是"显式"的：429 限流、配额耗尽、5xx——响应码摆在那，数数就能判定。这次场景换成本地/私有化部署的 provider，玩法完全不同。

私有化 LLM 端点的典型故障是"慢"：

长上下文推理本身就可能跑几十秒，正常和异常的边界很模糊；
某台机器显存碎片、批处理排队、GPU 降频，服务还活着，就是越来越慢；
这些端点经 McpBridge 注册成 Envoy cluster（命名形如 outbound|443||provider.dns），连接层完全正常。

麻烦在于平台现有的健康机制全都够不着这类故障。Envoy 原生的 active health check 和 outlier detection 是设计文档里定义的 Level 1 容错，它的局限写得很清楚：只在"节点全挂/被驱逐"时起作用，429 配额耗尽、单 provider 部分降级触发不了。慢节点比这更隐蔽——consecutive_5xx 数不出来，因为根本没有 5xx，只有漫长的等待。

一台慢节点拖着不做处理，代价是拖尾：每个打到它的请求都白占一个网关连接槽位，挂到客户端超时为止。网关的连接池、下游的并发额度，都在替一台病机器买单。

端点粒度 vs 路由粒度：为什么不上现成的 failover

第一反应是找现成能力。盘点下来三层，粒度从粗到细：

层	机制	粒度	为什么不够
平台层	Envoy outlier detection / health check	节点	只认连接错误和 5xx，慢故障不可见
路由层	ai-proxy 的 providers failover（failoverOnStatus）	provider 整机	切换粒度是整个 provider，且 failover 重发请求有 body 丢失的老 bug（issue #3531）
选端层	★ 本设计的端点断路器	单个端点	—

路由层整机 failover 不适用的根本原因是场景：私有化部署里一个 provider 后面挂的是自己机房的多台推理机，没有"备用 provider"可切。慢一台就把整个 provider 判死，等于自断服务。正确的粒度是把坏的那台端点摘出去，其余继续扛流量。

选端层做这件事有个天然优势：判定发生在建立上游连接之前。ai-load-balancer 的三种 LB 策略都走同一条路——先拿候选端点集合，再指定 host 转发：

1
2
3


GetUpstreamHosts() // fork 扩展：读 cluster 的端点与健康状态
 → 过滤屏蔽名单 // ← 断路器插在这里
 → SetUpstreamOverrideHost(host) // 指定端点转发

坏端点在选端阶段就被跳过，故障代价从"一次 70s 超时"降到"一次内存查询"。

但选端层也有自己的代价，两条 wasm 侧的硬约束：

GetUpstreamHosts / SetUpstreamOverrideHost 是 higress fork SDK 的扩展能力，不在标准 proxy-wasm ABI 里；
SetUpstreamOverrideHost 指定端点时必须返回 HeaderStopIteration，否则 override 不生效——这是 ai-load-balancer 三种 LB 策略验证过的统一姿势。

粒度选择本质上是"谁能看见故障"的问题。平台层只看得见连接，路由层只看得见 provider，只有选端层同时看得见端点和业务耗时。看得见，才管得了。

统计层：5s 去重窗口是整个设计的核心

断路器需要统计每个端点的响应表现。最朴素的实现是每次上游响应都计入统计，但这里有个私有化场景特有的陷阱：慢端点会同时拖住一批在途请求。

推理请求耗时本来就长，网关上同一个端点常态挂着几十个在途请求。一旦它开始变慢，这批请求会在相近的时间窗内相继超时。不去重的话：

一次慢抖动被记成 N 份"失败证据"，统计被同一事件重复灌水；
屏蔽状态走 SharedData（CAS 写），计数爆炸直接放大写竞争；
观测指标失真——看起来"失败了 40 次"，其实是一个慢节点拖住的一批受害者。

所以统计层加了去重间隔：短时间内（5s）同一端点只计算一次。设计推演如下（伪代码，非最终实现）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// 伪代码：响应统计 + 去重 + 拉黑判定
const (
 dedupWindowMs = 5000 // 5s 去重间隔
 slowThreshold = 70000 // 慢阈值 70s
 confirmCount = 2 // 确认次数阈值，2~3 次按场景调
 blockTtlMs = 45000 // 拉黑 TTL，30~60s 区间内取值
)

func onUpstreamResponse(ep string, costMs int64) {
 now := nowMs()
 st := stats[ep]
 if now-st.lastCountedAt < dedupWindowMs {
 return // ← 间隔内已计过，这个响应不重复入账
 }
 st.lastCountedAt = now
 if costMs >= slowThreshold {
 st.count++
 if st.count >= confirmCount {
 block(ep, now+blockTtlMs) // 慢样本攒够确认次数，拉黑
 }
 }
}

去重带来的第二个收益是防抖动放大误判。没有窗口时，一次网络抖动产生的整批慢响应会被当成多次独立证据，叠加起来很容易越过判定边界；有窗口后，统计的时间分辨率被限制在 5s，抖动只能贡献一个样本，持续性的慢才会持续入账。顺带它还保证了确认次数之间的最小采样间隔——2~~3 次确认至少跨过 5~~10s 的观察期，“一次抖动"和"持续变慢"在这个尺度上被区分开。

多 worker 的一致性问题也要面对。wasm 插件每个 Envoy worker 线程一个 VM，跨 worker 状态不互通——统计视角天然分片，这反而可以接受（每个 worker 是一个独立采样点）；但屏蔽名单必须全局一致，否则 A worker 拉黑了、B worker 还往坏端点上发请求。跨 VM 的写要走 Get/SetSharedData（CAS），SDK 的语义是并发写同一 key 返回 ErrorStatusCasMismatch，计数器/状态必须做 Get+Set 重试循环，不能假设一次成功。

我考虑过把去重窗口也放 SharedData 做全局一致，后来放弃了：窗口状态是高频热路径，每次响应都 CAS 一轮，写竞争的代价超过收益。5s 窗口本身对精度不敏感，per-worker 各自维护，采样视角还更分散——这算是我为数不多主动选择"不一致"的地方。

阈值与 TTL：70s 慢阈值 × 23 次确认，3060s 拉黑

判定逻辑压成一句话：耗时突破 70s 的慢样本，按 5s 去重间隔计数，攒够 2~3 次确认就拉黑；拉黑不是永久的，TTL 到期自动恢复参与负载均衡。

70s 这个数的来源是私有化场景的两头挤压：下限要高于正常推理的长尾——长上下文请求跑三四十秒是常态，阈值太低会把慢请求误判成慢节点；上限受交互式体验约束——LLM 场景用户对首字延迟的容忍就是几十秒的量级，一个响应要 70s 的端点，对用户来说和挂了没有区别。

确认次数定在 2~~3 是第三个旋钮：只确认一次，一次长尾抖动（provider GC、瞬时批处理排队）就会误杀健康端点；要求太多次，慢节点又会在池里白吃好几分钟流量。2~~3 次配合 5s 去重间隔，等效于要求"慢状态持续 10~~15s 以上"才动手——误杀率和反应速度都被框在了可接受区间。TTL 取 30~~60s，则是在"别把暂时过载的节点锁太久"和"别让真坏节点频繁回来试"之间取的平衡。

时间线长这样：

1
2
3
4
5
6
7


T+0s 请求 A → 端点 E，开始推理
T+70s A 耗时突破 70s → E 记第 1 次慢失败（5s 间隔内首次，入账）
T+71s+ 在途请求 B/C/D 相继超时 → 间隔内全部去重，不计数
T+75s+ 后续请求依旧超时 → 跨过间隔，记第 2 次
 → 慢样本攒到确认次数（2~3），E 拉黑，blockUntil = now + TTL(30~60s)
TTL 内 选端时过滤屏蔽名单，E 被跳过
TTL 到期 E 惰性恢复，自动回到候选池

恢复机制我选了惰性恢复：不设定时器，选端时检查 blockUntil，过期即视为恢复。这个思路和 Envoy outlier detection 的 base_ejection_time 同构，但实现更轻——恢复完全被请求驱动，零后台开销。

1
2
3
4
5
6
7


// 伪代码：选端过滤
candidates := filterHealthy(getUpstreamHosts())
candidates = rejectBlocked(candidates, nowMs()) // blockUntil 已过期的直接放回
if len(candidates) == 0 {
 // 不覆盖端点，交给 Envoy 默认选端 —— 下一篇的主题
}
setUpstreamOverrideHost(pick(candidates))

TTL 恢复是个乐观假设：到期不等于健康。端点如果还在慢，打过去的请求重新开始攒慢样本，再花 2~3 次确认拉黑一轮——相当于用真实流量做探测，代价是每个 TTL 周期有一段糟糕的用户体验。要不要配主动健康检查（用最小模型探活提前解封），我还在权衡，至少当前流量规模下不值当。

实现要点：贴着 wasm 的约束走

骨架就是标准的 wasm-go 插件回调链：

1
2
3
4
5
6
7


func init() {
 wrapper.SetCtx("endpoint-breaker",
 wrapper.ParseConfig(parseConfig), // fail-fast：非法配置直接 error
 wrapper.ProcessRequestHeaders(onReqHeaders), // 读屏蔽名单 + 选端 override
 wrapper.ProcessResponseHeaders(onRespHeaders), // 耗时统计的计时锚点
 )
}

几个关键实现决策，每条背后都是 wasm 执行模型的一条硬约束：

回调里不做任何阻塞动作。 wasm 回调跑在 Envoy worker 线程上，同步做耗时操作会卡住该 worker 的所有请求；wasm 目标没有真线程，goroutine 不可用。好在断路器的判定全是内存操作——读名单、比对时间戳、CAS 写回，没有一处需要异步。

屏蔽写回走 CAS 重试。 SDK 的 SharedData 语义决定了并发写必须循环重试：

1
2
3
4
5
6
7
8
9


// 伪代码：SharedData CAS 写回（SDK 语义：冲突返回 ErrorStatusCasMismatch）
for i := 0; i < maxRetry; i++ {
 data, cas := proxywasm.GetSharedData(key)
 updated := mergeBlock(data, ep, blockUntil)
 if _, err := proxywasm.SetSharedData(key, updated, cas); err == nil {
 break
 }
 // cas mismatch → 别的 worker 先写了，重读重算再试
}

fail-open 兜底。 wasm 框架对插件 panic 的兜底语义是 fail-open：wrapper 的 recoverFunc 捕获 panic 后，回调以零值 ActionContinue 返回，请求继续正常处理。这对断路器是理想行为——屏蔽逻辑自身崩溃，最坏结果是"不屏蔽”，绝不会挡流量。推论是故障完全静默，必须靠日志关键词告警兜住，调试期可以用 WASM_DISABLE_PANIC_RECOVERY=true 关掉兜底看原始栈。

共存纪律。 SetUpstreamOverrideHost 一个请求只允许一个策略，断路器和其他 LB 类插件不能同挂；SharedData key 加插件前缀，防互踩。

参考实现可以直接看仓库里两个现成插件：ai-load-balancer 的 global_least_request/lb_policy.go（端点健康读取 + 指定 host 转发的完整姿势）、ai-proxy 的 provider/failover.go（SharedData 健康状态机 + 探测恢复）。我的屏蔽名单状态机基本是后者换了判定信号。

反思：这套设计粗糙但够用的边界在哪

坦率说，这是一个"单实例自洽、多副本将就"的设计，边界我列清楚：

阈值是刀切的。 70s 对长上下文模型可能太严（正常推理就被拉黑），对轻量模型可能太松（慢节点拖 60s 依然在池里）。按 model 维度配差异化阈值是第一优先级的改进，配置结构上 _rules_ 路由级覆盖直接可用。
SharedData 只覆盖单实例。 多副本网关部署时，每个副本的屏蔽状态是割裂的，全局一致要走 Redis（key 加插件前缀、{cluster} hash tag 防 CROSSSLOT）。当前单副本部署下这不是问题，扩副本前必须补。
耗时统计的口径很粗。 只看单次响应耗时，没有分位数、没有趋势。更精细的做法是滑动窗口内记录 P95，但那会引入事件序列存储——上一篇的设计里已经有窗口上限 20 条的先例，代价是 CAS 竞争显著加剧，我不确定值得。

下一篇写拉黑策略的补丁：全拉黑放行——候选集被屏蔽名单清空时，屏蔽逻辑主动退位，把控制权还给 Envoy 默认选端。宁可疑似的端点接到流量，也不主动拒绝请求，这个取舍值得单独一篇展开。

断路器做到最后，我体会到的核心不是"怎么拦"，而是"什么时候不拦"——屏蔽判定越激进，兜底路径就越重要。一个只在候选集非空时才起作用的断路器，看起来功能打折，实际上是所有流量的安全带。

wiki CLI 工具设计

Sun, 23 Aug 2026 14:47:30 +0800

wiki CLI 工具设计

一个基于 agent hook 设计的命令行工具：会话结束 hook 自动跑同步，把项目 wiki 知识、Obsidian 校对、Hugo 博客发布串成一条自动化流水线。核心思想：hook 驱动自动化，数据面与控制流分离。源码：daidaiJ/my-wiki-repo

动机：笔记散落十几个仓库

让 agent 做源码调研和方案分析，产出物（调研 wiki、issue 分析、踩坑记录）散落在十几个仓库的角落里，格式不一、无人索引、想找的时候不知道在哪。为每个项目 fork 一个 wiki 仓库又太重。

my-wiki 的做法是正文进知识库、项目留窗口：agent 仍往 项目/wiki/ 里写笔记（路径不变，不必知道知识库在哪），收工 hook 把正文反转进 WIKI_ROOT/projects/——git 可同步的真文件，项目侧原位换成一条窗口链接；本地注册表登记每个项目的位置和介绍。任何时刻 wiki grep 跨项目检索，而你的个人知识配置永远不会出现在项目 remote 里。

这个布局不是一开始就想清楚的。第一版走的是"正向聚合"：笔记留在各项目里（单一事实源），知识库用符号链接聚合过来。用下来发现两个硬伤——git 只能提交链接本身，笔记永远进不了版本控制；换一台机器，链接全部悬空。于是把方向反过来：正文当真文件收进知识库（git 可同步、Obsidian 直读），项目侧才用链接。旧布局遇到时 init / sync --fix 会自动迁移，不再作为选项。存储位置之争的裁判是 git 和换机场景，不是"哪个更像单一事实源"——链接聚合格局好看，但 git 提交不了链接指向的内容。

核心思想：hook 驱动，自动化优先

wiki 的定位不是"又一个笔记工具"，而是 agent 工作流里的自动同步器。设计围绕唯一一个 hook 展开：会话退出时跑一次 wiki check——幂等、静默、非阻塞。已注册项目做窗口维护和正文反转迁移；没注册过的项目只要已经有了知识目录（说明 agent 写过东西），就自动接入——agent 写入后才触发，不预建空目录。人不需要记得"接入"这件事，agent 也不需要。

早期版本还有 register 子命令、会话开始的 prepare hook 等一串入口，后来发现它们的所有场景都被这一个 check 覆盖了，索性全部砍掉：register 删除，prepare 降级为换机后手动重建窗口的修复工具。能被一个 hook 覆盖的维护逻辑，就不该让用户配置第二个 hook。

hook 驱动的前提是架构分层，wiki 把整个系统切成两层：

数据面：知识数据本身。知识正文是 WIKI_ROOT/projects/ 下的真文件（git 可同步），注册表、发布记录、配置同在 wiki 根下——这个目录同时就是 Obsidian 仓库
控制流：工具逻辑与 agent 工作流。命令契约、钩子、规约注入——这部分可以开源、可以复制、可以升级，和数据互不污染

分离的直接体现是 wiki 根解析：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// config.go（简化）
func WikiRoot() string {
 if env := os.Getenv("WIKI_ROOT"); env != "" {
 return env
 }
 // 依次探测可执行文件目录、当前目录是否含 index.md 标记
 for _, dir := range []string{exeDir, cwd} {
 if _, err := os.Stat(filepath.Join(dir, "index.md")); err == nil {
 return dir
 }
 }
 return exeDir // 兜底
}

工具仓库可以开源（代码 + 规约），个人数据在 WIKI_ROOT 指向的目录，两者互不污染。换机器只要 clone 知识库数据目录，wiki prepare 重建一次窗口即可。

数据面还有一个更重要的原则：项目仓库零足迹。接入信息只存在 wiki 根的本地注册表，不会随项目 commit/push 泄漏到远程——你的个人知识配置永远不会出现在公开仓库里。

数据面实现：注册表 + 反转存储

注册表持久化为 index.md 顶部的隐藏 JSON 块，其余是渲染视图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// registry.go
func saveRegistry(root string, reg *Registry) error {
 var b strings.Builder
 b.WriteString("<!-- wiki-registry\n")
 b.Write(data) // ← JSON 数据块（机器读）
 b.WriteString("\n-->\n\n")
 b.WriteString("# 项目索引\n\n") // ← 以下是 Markdown 渲染视图（人读）
 for _, p := range reg.Projects {
 fmt.Fprintf(&b, "| %s | %s | %s |\n", p.Name, p.Root, p.Intro)
 }
 return os.WriteFile(registryPath(root), []byte(b.String()), 0o644)
}

一个文件同时是数据源和视图，agent 和人都能读。JSON 藏在 HTML 注释里，Markdown 渲染器不会显示它，wiki grep 也不会被它干扰。

链接层（窗口）：项目侧的 wiki/ 是一条指向知识库正本的 symlink，Windows 无权限时自动降级 junction：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func makeLink(target, link string) error {
 if err := os.Symlink(target, link); err == nil {
 return nil
 } else if runtime.GOOS == "windows" {
 out, jerr := exec.Command("cmd", "/c", "mklink", "/J", link, target).CombinedOutput()
 if jerr == nil {
 return nil // ← junction 降级成功
 }
 return fmt.Errorf("symlink 失败: %v；junction 降级也失败: %v: %s", err, jerr, out)
 }
 return err
}

整体关系（注意方向：链接从项目侧指向知识库，与正向聚合相反）：

flowchart LR
A["agent 写 项目A/wiki/"] -->|"会话退出 check：反转"| P
subgraph WR["wiki 根（WIKI_ROOT）"]
P["projects/项目A/wiki（真文件，git 可同步）"]
R["注册表 index.md"]
end
subgraph 项目仓库["项目仓库"]
W["项目A/wiki（窗口链接）"]
end
W -- "symlink / junction" --> P
P --> R

项目侧怎么看见正文：link 还是 copy

反转存储里还剩一个二选一：项目侧用窗口链接（link，缺省）还是真目录（copy）。这是同一布局的两种形态，不是两套设计，接入时 --mode 选择，wiki list 可见每个项目的模式。

copy 模式下正文归项目 git 管，收工 hook 只做项目 → 知识库的增量合并拷贝——mtime 新者胜（rsync -u 语义）、永不删文件。永不删是有意设计：Obsidian 侧的校对修改不会被项目侧覆盖，代价是两侧各有一份拷贝、项目侧删掉的文件会残留在知识库。另外拷贝模式下遇到残留的链接布局会拒绝动手——防错误覆盖搬迁比自动化更重要。

怎么选：项目仓是自己的、希望知识随仓库走、或环境不便建符号链接 → copy；想避免两份拷贝、知识只归知识库管 → link（缺省）。已注册项目保留原模式，换模式需 unlink 后重新 init。

控制流实现：为 hook 而生

控制流要回答一个问题：hook 和 agent 怎么和这个工具协作？两个设计贯穿始终。

幂等 check，为钩子而生。 wiki check 被设计为对任何钩子机制都安全：

stdout 恒为空（部分工具会把 stdout 当 JSON 严格校验）
日志全部走 stderr，内部错误不改变退出码
不修改当前项目仓库的任何文件

1
2
3
4
5
6
7
8


// EnsureRegistered 幂等地把项目接入知识库，init/check 共用
func EnsureRegistered(root, abs string, decl *WikiSyncDecl) (*EnsureResult, error) {
 // 1. 跳过健康链接（EvalSymlinks 比对目标）
 // 2. 修复失效链接
 // 3. 清理声明收缩后的孤儿链接（只删链接，绝不碰真实目录）
 // 4. upsert 注册表——无变化则不写盘
 ...
}

关键细节：注册表无变化则不写盘。否则每轮会话结束都触发一次文件写入，既制造噪音，也让 git 工作区永远不干净。

check 的生效范围也是可配置的（hookMode）：forbiddenList（缺省）全目录生效、按禁止名单排除；whitelist 只在白名单子孙目录生效（名单支持 ~ 前缀，跳过时 stderr 说明原因）。生效范围和静默契约是两件事：前者给"上游项目仓库、公司代码目录不想被收编"的环境差异留口子，后者保 hook 安全——范围可以宽松配置，stdout 契约一步不让。

还有一个不显眼但救命的设计：中断迁移的恢复。反转迁移是"项目侧真目录 ↔ 知识库真目录"两侧都是真文件的场面，做到一半被杀（Windows rename 锁、进程中断）会留下半迁移状态。恢复逻辑的原则是永不覆盖 vault 侧文件——多余的合并进知识库、冲突的逐子项搬运兜底。迁移类工具的第一守则：任何情况下不能弄丢用户数据，宁可留下待清理的残留。

宽容 flag 解析。 agent 调用 CLI 时经常把位置参数放在旗标前（init <目录> --paths wiki），标准库 flag 不接受这种顺序。ParseWithPositionals 内部重排为「旗标在前、位置参数在后」再交给标准 FlagSet：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


func ParseWithPositionals(fs *flag.FlagSet, args []string) error {
 var flags, pos []string
 for i := 0; i < len(args); i++ {
 a := args[i]
 if strings.HasPrefix(a, "-") && a != "-" {
 flags = append(flags, a)
 if f := fs.Lookup(strings.TrimLeft(a, "-")); f != nil {
 if bv, ok := f.Value.(interface{ IsBoolFlag() bool }); !ok || !bv.IsBoolFlag() {
 if i+1 < len(args) { // 非 bool 旗标吞掉下一个 token
 i++
 flags = append(flags, args[i])
 }
 }
 }
 } else {
 pos = append(pos, a)
 }
 }
 return fs.Parse(append(flags, pos...))
}

这个函数是 agent 友好设计的缩影：CLI 的调用方是 LLM，不是人。LLM 生成命令时不会严格遵守「旗标在前」的约定，宽容解析能显著减少失败重试。

打通 Obsidian 和 Hugo 博客仓库

知识库有两个出口：Obsidian 仓库（人阅读校对）和 Hugo 博客仓库（对外发布）。Obsidian 仓库根就是 wiki 根（pandawiki），projects/ 聚合各项目的知识正文（反转存储后的真文件），人在里面阅读校对；校对通过的笔记才进博客流水线。调研笔记（wiki/issues）→ 知识库检索 → Obsidian 校对 → 沉淀成博客，一条链路：

flowchart LR
A["agent 调研产出笔记"] --> B["wiki init 接入知识库"]
B --> C["wiki grep 跨项目检索"]
C --> D["Obsidian 查看校对"]
D --> E["wiki blog new 创建文章"]
E --> F["wiki blog publish 发布"]
F --> G["GitHub Actions 自动部署"]

blog new 的完整流程：

flowchart TD
A["wiki blog new"] --> B["查重：slug / 文件名"]
B --> C["hugo new 按主题 archetype 生成模板"]
C --> D["填 title/slug/categories/tags 四字段"]
D --> E["追加正文"]
E --> F["wiki blog publish"]
F --> G["git add + commit + push"]
G --> H["GitHub Actions 自动构建部署"]

几个关键设计：

apply 时查重：slug 罕见重复 + 文件名存在性，先于 hugo new 报错，避免生成一半才发现冲突
push 失败不重试：原始错误透传，文章已本地提交，用户手动补一次 git push 即可
blog.json 懒维护：发布成功后才更新四字段记录，blog list 据此统计分类复用频次

1
2
3
4
5
6


// blogPublish 提交并推送；push 失败不重试
if out, _, err := run("push", "push"); err != nil {
 return fmt.Errorf("git push 失败（不重试，原始输出透传如下）:\n%s%v\n\n"+
 "GitHub 网络问题请用户手动处理：稍后在 %s 执行 git push 即可，文章已本地提交。",
 out, err, repo)
}

不重试是刻意的：push 失败几乎都是网络问题，自动重试只会放大 GitHub 的限流压力。把决定权交给人，比假装智能地重试更可靠。

知识管理对博客的反哺也在这里：blog list 统计已有分类的使用频次，新文章优先复用——分类不会碎片化，知识库的元数据直接指导博客的写作决策。

工作流设计：从调研到发布

工具解决"怎么管"，工作流解决"怎么用"。整条链路三段：agent 驱动总结 → Obsidian 查看校对 → Hugo 发布 / git 同步。每段有明确的产出物和交接点，中间夹一道人工关卡。

flowchart LR
A["① Agent 驱动总结"] --> B["② Obsidian 查看校对（人工关卡）"]
B --> C["③ Hugo 发布 / git 同步"]
C --> D["GitHub Actions 部署"]

Agent 驱动总结

agent 调研/实践后把结论沉淀成笔记，写入项目自己的 wiki/ 目录——路径不变，agent 不必知道知识库在哪。文风由 tech-blog skill 规范，产出物直接可读。接入零足迹：wiki init 只写本地注册表 + 建窗口；Stop hook 每轮会话结束跑 wiki check——已注册项目反转迁移正文，没注册但已有知识目录的项目自动接入，新笔记自动进知识库，不需要任何手动步骤。

Obsidian 查看校对

知识库最终要给人看。Obsidian 仓库根 = wiki 根（pandawiki），projects/ 下是各项目的知识正文（反转存储后的真文件），人在 Obsidian 里阅读校对：链接通不通、结论站不站得住、有没有遗漏。这是整条链路唯一的人工关卡——agent 产出再快，发布前必须过一遍人眼。

反转存储之后这个环节反而变简单了：正本是真文件，不再依赖符号链接可见性。VSCode 侧也照顾到了——接入操作幂等补齐 projects/.vscode/ 配置（*.md 默认打开内置 Markdown 预览 + 扩展推荐清单，仅缺失时写入、不覆盖用户改动），点开 .md 直接是渲染视图。校对通过，笔记才进入发布。

Hugo 发布 / git 同步

发布走 wiki blog new → wiki blog publish（细节见上一节），push 成功即触发 GitHub Actions 的 hugo 构建部署。失败处理是刻意的：

flowchart TD
E["wiki blog publish"] --> F{"git push 成功?"}
F -- 是 --> G["GitHub Actions 构建部署"]
F -- 否 --> H["本地已提交，手动补 push"]

push 失败不重试——几乎都是网络/代理问题，自动重试只会放大限流。git 同步管理是兜底：先查代理（本地代理没启动时 push 必挂），再手动补 push。

三段产出物：笔记（知识库 projects/ 正本）→ 校对结论（人脑）→ 已发布文章（博客仓库）。交接点清晰，每段可独立重跑：agent 反复改笔记、人在 Obsidian 反复看、发布随时重来。人工关卡放在发布前而不是发布后，是这条流水线最重要的设计决定。

同题对照：ai-memory 的另一种切法

开源这个工具两周后，我看到 akitaonrails/ai-memory——Rust 写的 AI coding agent 长期记忆系统，核心链路和我殊途同归：lifecycle hooks 静默采集 → 会话结束 consolidate 成 markdown wiki 页 → 下一个会话检索续接。两个独立演化的方案最终在"markdown 正本 + hook 收工沉淀"上汇合，这件事本身比任何一方的设计都更有说服力。

	my-wiki	ai-memory
记忆载体	`projects/` 下的普通 .md（反转存储）	git-backed wiki 的普通 .md，数据库只是可重建的派生索引
写入方式	agent 直写 `项目/wiki/`，收工 hook 反转进知识库	lifecycle hooks 全程静默采集，会话结束整理成页
检索	`wiki grep` 全文检索，零索引	全文/实体/链接/(可选)向量融合排序，默认零 LLM 调用
跨 agent	规约注入（`wiki inject`）+ 单 hook，命令契约对 LLM 友好	20+ harness 第一方接入，handoff 是显式协议（typed、owned、claimed exactly once）
部署形态	单二进制 CLI，本地优先	自托管 server，跨机器、团队共享、审计日志

两边最有共识的一点：记忆的正本必须是普通 markdown 文件。ai-memory 的原话是 “No vector store to babysit, nothing held hostage in a binary blob”，我的版本是"任何时刻 grep 一下就能跨项目检索"。agent memory 赛道都在卷向量库，但真正高频的知识检索场景全文搜索就够——文件本身是最好的数据库，grep 是最低的维护成本。

分歧在共享边界：ai-memory 把"跨 agent、跨机器、跨人"当第一性需求，为此上了 server 和多用户认证；我把知识库锚在本地 git + Obsidian，团队共享是明确不支持的取舍。这是个人工具和团队基建的分野——我选择先保证单人链路足够顺滑，共享需求真出现了再说。另外它的 handoff 协议（交接物是 typed、owned、只能认领一次）值得借鉴，我的"交接"目前只靠知识库正文本身，没有显式的进行时状态。

演进复盘：两周里被改掉的三次

文章开头的设计是最终形态，但它是被提交史一路撞出来的。把 8 月 23 日开源到 9 月 6 日的演进拉出来看，比描述最终状态更有信息量：

时间	演进	内容
08-23	开源收尾	标准分包、MIT/CI/tag 发布；`blog new` 改由 hugo archetype 生成模板
09-03	反转存储落地	正文进 `projects/`，项目侧换窗口链接；`bundle` 归档出口
09-03	copy 模式	增量合并拷贝（mtime 新者胜、永不删文件）；`injectFile` 可配置适配不同 agent 工具
09-04	崩溃恢复	中断迁移的恢复：永不覆盖 vault 侧文件，宁可留残留
09-05	单 hook 重构	hookMode 生效范围 + 自动反转挪到会话退出；`register` 删除（Closes #2）
09-06	VSCode 预览	init/check 幂等补齐 `projects/.vscode` 预览配置

三条反思：

正向聚合败给物理约束，不是败给逻辑。 第一版"笔记留项目、知识库链接聚合"在逻辑层完全自洽——单一事实源、项目零足迹，每一条都站得住。但它过不了两道物理约束：git 提交不了链接指向的内容，换机即断。教训是设计评审该先问"这个方案在 git / 换机 / 崩溃恢复这些物理现实下还成立吗"，自洽的方案太多了，能过物理约束的没几个。

功能的寿命取决于它有没有独占场景。 register、会话开始的 prepare hook 都曾有自己的存在理由；自动反转挪到会话退出后，check 一个入口覆盖了全部场景，于是 register 删除、prepare 降级为手动修复工具。没有独占场景的入口是负债——文档、心智、测试三份维护成本，换不来任何不可替代性。

自动化等信号，不抢跑。 自动反转的触发条件是"未注册项目已经有了知识目录"——agent 写入之后才收编，绝不预建空目录。提前建好的自动化是猜，等信号的自动化是响应；猜错的自动化会产生一堆要清理的空壳。

一些取舍

注册表是单机本地的，没有多用户同步——团队共享知识库不适合
刻意本地优先：要跨机器同步就用 git remote 管理数据目录，工具从不自动 push
项目侧近零足迹：link 模式下项目仓只多一条窗口链接和一个 .gitignore 条目（projectGitignore 可关），个人配置不进 remote；想要知识随项目仓公开走，copy 模式让正文随项目提交——可选项，不是默认
Windows 支持：symlink 失败自动降级 junction，无需管理员权限

坦率说，这个工具离"通用知识管理"还有距离，但它解决了我自己的核心痛点：跨项目检索 + 博客发布自动化。工具的价值不在于功能多，而在于和 agent 工作流的契合度——每个命令都是为 LLM 调用方设计的。

实践：Obsidian 仓库接入 SOP

知识库最终要给人看。Obsidian 是现成的阅读器，把 wiki 根接进去当仓库有两条路：先建仓库再配 wiki CLI（推荐），或者顺序反了之后迁移。殊途同归：Obsidian 仓库根 = wiki 根，一个目录两用。

路线一：先建仓库，再配置 wiki CLI

正确顺序是先有仓库，再让 wiki CLI 的持久化目录落进仓库：

建一个空的 Obsidian 仓库，目录名避开 wiki——和 knowledgeDirs 的类型名重合，自动发现时可能把仓库目录自己误认成项目知识目录
把 wiki CLI 持久化目录配置到仓库：setx WIKI_ROOT "D:\wiki\pandawiki"（用户级环境变量，新终端生效）
wiki init <项目> 接入项目——注册表 index.md、config.json、projects/ 链接全部落在仓库目录里，Obsidian 里立即可见
验证：wiki ls 项目在册，obsidian vault=pandawiki folders 索引完整

路线二：顺序反了，迁移现有持久化目录

wiki CLI 数据已经存在（比如在 D:\wiki），迁移进 Obsidian 仓库分四步：

迁数据：index.md（注册表）、config.json、blog.json、projects/ 整个目录移进仓库
显式指定 WIKI_ROOT：wiki 根靠 index.md 标记解析（环境变量 > exe 目录 > 当前目录），只搬文件不设环境变量，hook 会静默失效、wiki check 空转：

1

setx WIKI_ROOT "D:\wiki\pandawiki" # 用户级环境变量

hook 不依赖终端环境，内联设置：

1

cmd /c "set WIKI_ROOT=D:\wiki\pandawiki&& D:/CODE/ai/my-wiki/wiki.exe check"

注册仓库：UI 里 Open folder as vault，或直接改注册表：

1
2


// %APPDATA%\obsidian\obsidian.json
{"vaults":{"c3d4bd2d547a9675":{"path":"D:\\wiki\\pandawiki","ts":1787470151204,"open":true}},"cli":true}

obsidian://open?path= 只能解析已注册仓库里的文件，不能注册新仓库——别在这上面浪费时间。

验证清单：

wiki ls：项目全部在册
obsidian vault=pandawiki folders/files：知识正文全部索引（projects/ 下是真文件，不依赖符号链接可见性）
最终结构：

1
2
3
4
5
6
7
8
9


D:\wiki\pandawiki\ ← Obsidian 仓库根 = wiki 根
├── .obsidian/
├── index.md ← 注册表（标记）
├── config.json / blog.json
├── 欢迎.md
└── projects/ ← 知识正文（真文件，git 可同步）
 ├── agentscope/wiki/
 ├── higress/wiki/
 └── ...

两条路线殊途同归：Obsidian 仓库根 = wiki 根，一个目录两用。推荐路线一，但路线二也不复杂——迁数据、设 WIKI_ROOT、注册、验证四步，十分钟收工。

Higress 网关 LLM 端点故障临时屏蔽（Endpoint Failover）

Sat, 01 Aug 2026 23:44:36 +0800

Higress 网关 LLM 端点故障临时屏蔽（Endpoint Failover）

给 LLM 网关做选端的时候碰到一个绕不开的问题：供应商端点的故障大多是"业务性"的——429 限流、配额耗尽、5xx，连接层完全正常，Envoy Outlier Detection 这种平台健康检查根本发现不了。所以在 ai-load-balancer 选端前加了一层黑名单过滤器：失败端点暂时打入冷宫，惩罚期过了再放回候选池。整个设计最核心的理念是软屏蔽——被屏蔽不等于不可用，只是低优先级。

需求拆解

LLM 端点故障和普通微服务不一样：故障持续时间从几十秒到几分钟，期间所有请求都挂在超时上；同一个集群里 A 挂了，B、C 还活着，需要快速改道；429 限流是常态而不是异常，但连续 429 说明端点已经过载。

需求拆出来五条规则：

R1 只有上游真实响应才算失败（网关自己拦的不算）；
R2 连续失败 ≥ 阈值进屏蔽名单，窗口内不参与选端；
R3 过滤后候选集为空 → 不覆盖端点，走 Envoy 默认选端；
R4 候选集非空时按负载策略从候选集选最优；
R5 TTL到期惰性恢复，可选健康检查加速。

R3 是这个设计最反直觉的地方。多数熔断在"全被屏蔽"时会直接吐 503，这里把控制权还给 Envoy 默认路由。我认同这个取舍：网关的职责是转发，不是裁决。宁可流量打到可能已恢复的端点，也不主动拒绝。

核心流程

一条请求走四个阶段：请求头阶段 DisableReroute() 锁死路由，保留选端控制权；请求体阶段拿到 GetUpstreamHosts() 的健康端点，过滤屏蔽名单；响应头阶段判定成败；流结束阶段兜底。

1
2
3
4
5
6
7
8


请求头 DisableReroute() 锁死路由，保留选端控制权
请求体 GetUpstreamHosts() → 过滤健康端点
 → 读屏蔽名单（本地缓存 1s TTL，过期才拉 SharedData）
 → candidates = healthy − blocked
 → 空？不覆盖走默认（R3） ｜ 非空？按策略选最优并覆盖
响应头 IsResponseFromUpstream() 且命中失败码 → 计数 +1
 → 连续失败 ≥ 阈值 → 写屏蔽名单（blockUntil = now + 60s ± 抖动）
流结束 正常结束清零计数；异常断流按失败处理

选端放在请求体阶段是关键：在建立上游连接之前就把坏端点过滤掉，故障的代价从"超时级"降到"选端级"。失败判定放在响应头阶段，此时请求已结束，不增加时延。

状态机：端点怎么被"打入冷宫"

以 consecutive 模式（阈值 3、屏蔽 60s）为例：

1
2
3
4
5
6


T0 正常，FailCount=0
T1 503 → FailCount=1
T2 503 → FailCount=2
T3 503 → FailCount=3 → 触发！BlockUntil = now + 60s + 随机±6s，计数清零
T4~T63 选端时在屏蔽名单里，跳过
T63+ 到期，惰性恢复，回到候选池

触发判定核心就几行：

1
2
3
4


if b.FailCount >= failureThreshold {
 b.BlockUntil = now + blockDurationMs + jitter() // ← 抖动防同步解封
 b.FailCount = 0 // 恢复后从零重新计数
}

触发后清零 FailCount，这个细节我琢磨了一下：不清零的话，历史失败会一直累积，端点永远达不到新阈值，等于屏蔽一次就永久拉黑。但清零也带来盲区——间歇性抖动（偶发 429 后连续成功）永远不会触发，所以设计里还有 window 触发模式（60s 内失败 ≥ 5 次）和 rate 模式（窗口失败率 ≥ 50%）补这个洞。

两个实现细节值得展开：

CAS 并发安全。wasm 每个 worker 一个 VM，多个 VM 可能同时判定"该屏蔽 A"。屏蔽状态必须走 GetSharedData → 修改 → SetSharedData(cas) 原子循环，冲突重试上限 10 次，超限降级为本地计数。这套模式在 ai-proxy 的 apiToken failover 里已经跑过一遍，代码直接复用。

本地缓存 + TTL。热路径上每请求读一次 SharedData 撑不住，每个 VM 缓存屏蔽名单快照（默认 1s TTL），选端时直接用内存副本。代价是屏蔽生效有最多 1s 延迟——性能和生效速度的权衡，对企业场景是合理折中。

软屏蔽：全被屏蔽时不覆盖

选端逻辑压成一行公式：

1
2


candidates = GetUpstreamHosts().healthy − blocked
selected = LoadBalancer.Select(candidates)

候选集非空 → 按 least_busy / global_least_request / prefix_cache 从候选集里选最优；候选集为空 → 不调 SetUpstreamOverrideHost，Envoy 默认路由接管，流量仍可能打到被屏蔽端点。

软屏蔽带来三个收益：全死锁时至少还有流量能过去；刚恢复的端点能立即承载流量；屏蔽判定有误时，流量不会被完全阻断。思路和 Envoy Outlier Detection 的硬剔除（全剔除时也回退）一致，但 wasm 层能叠加业务规则——比如按 model 维度屏蔽：端点 A 的 qwen-max 稳定但 gpt-4 超配额，只屏蔽 gpt-4。

一个没想通的地方：候选集为空时流量均匀撒向所有端点（包括坏的），失败率保持高位，直到某个端点恢复。设计没有做"全屏蔽时按最近成功率挑一个最可能活的"这类优化。可能因为收益不确定，不值得为极端场景加复杂度。

失败判定：网关的拦截不算数

R1 是最容易踩坑的地方：

1
2
3


if !wrapper.IsResponseFromUpstream() { // 网关自己拦的不算
 return types.ActionContinue
}

waf 拦截的 403、限流返回的 429、管理接口的响应，都是网关自身行为，不是上游真实反应。把这些计入失败，健康端点会被误判成故障。

设计文档点出一个更隐蔽的问题：插件执行顺序会让 IsResponseFromUpstream() 不可靠。限流插件如果在 failover 之后执行，限流 429 从 failover 视角看就是"来自上游"。对策是让限流插件注入 X-Rate-Limited: true 头做二级判定；健康检查子请求也要打标记跳过判定，否则探活请求的 503 会不断延长屏蔽时间，端点永远无法恢复。

判定污染在插件体系里很常见：每个插件只看到自己阶段的响应，不知道响应是别人伪造的。用响应头标记做显式契约，比赌执行顺序可靠。

恢复机制：不引发二次故障

恢复期最容易出事——所有端点同时解封 → 瞬时过载 → 再屏蔽，形成同步震荡。设计里堆了几层防护：blockUntil 加随机抖动（±10%）打散解封时刻；健康检查需连续成功 ≥ successThreshold 次防振荡；租约选主只让一个 VM 发探活，最小模型降成本；可选指数退避，连续多次屏蔽时窗口倍增 60s→120s→240s。

恢复有两条路径：惰性恢复零成本但最慢，等 60s 自然到期；主动健康检查用最小模型发探活请求，连续成功就提前解封，代价是额外计算资源。

惰性恢复的实现是"选端时发现过期即清除"，不需要任何定时器，恢复完全被请求驱动。这个设计我喜欢，零开销。

观测设计

需求明确要求"完整支持失败次数与时间点的可观测性"，四路输出：Prometheus 指标（Counter 累计失败/屏蔽/恢复，Gauge 实时状态/剩余时间，Histogram 屏蔽时长）、访问日志（endpoint_selected、endpoint_blocked、endpoint_fail_count）、链路 span 标签、admin 查询接口（/_internal/_higress/endpoint-failover/status 返回 JSON）。

数据模型上，每个端点维护：连续失败数、累计失败数、滑动窗口失败事件序列（上限 20 条），外加最近失败/成功/进入屏蔽/到期/恢复五个时间点。剩余屏蔽时间、失败率这类派生指标不存储，查询时现算。

观测后端可配置。Prometheus 方案是 VM 本地指标，跨实例靠采集端聚合；Redis 方案复用限流插件已有的 RedisClient，ZSet 存事件流（score=时间戳），跨 VM 跨实例天然一致，管理接口直接读 JSON，不用 PromQL。

Redis 方案能覆盖 Prometheus 的全部观测语义，差别只在"谁来看"——Prometheus 由采集端拉取，Redis 由查询接口消费。对没有 Prometheus 基础设施的企业，Redis 反而是更省事的选项。

与现有能力的分层

这个设计不是孤岛，和企业网关已有的能力叠成五层：

1
2
3
4
5


第 1 层：连接/传输健康 Envoy Outlier Detection（平台级，硬剔除） —— 管"连不上"
第 2 层：业务健康判定 ★ 端点软屏蔽（本设计） —— 管"业务异常/限流"
第 3 层：请求重试 ai-proxy retryOnFailure（换 token 重试） —— 管"单请求偶发失败"
第 4 层：认证可用性 ai-proxy apiToken failover（token 隔离） —— 管"key 失效"
第 5 层：容量保护 ai-token-ratelimit / ai-quota —— 管"超卖"

本设计管"换端点"（这个后端坏了换那个），ai-proxy 的 failover 管"换 token"（这个 key 没额度了换那个），两层正交可叠加。端点全挂时，ai-proxy 的重试自然兜底。

分层的关键是别重复实现平台已有的能力。连接级健康判定交给 Envoy，这里专注 LLM 业务语义——429、配额耗尽、业务错误码，这些平台健康检查永远管不到。

边界情况：踩过的坑提前排雷

设计文档列了十几个 Bad Case，挑几个有代表性的：

Bad Case	根因	预防
限流 429 误判为上游故障	`IsResponseFromUpstream()` 受插件执行顺序影响	限流插件注入 `X-Rate-Limited` 头
健康检查自身触发熔断	探活请求的 503 进入失败判定，屏蔽无限延长	健康检查请求打标记，跳过判定
单端点集群死锁	唯一端点被屏蔽后请求全打它，失败又延长屏蔽	单端点时不延长 BlockUntil
熔断误伤无法恢复	误配 `failoverOnStatus` 导致全端点被屏蔽	Admin 接口 `unblock` / `unblock-all`
Redis 分区后本地不一致	各 VM 独立判定，屏蔽状态分裂	本地模式降阈值 + 短屏蔽时间

贯穿始终还有两条原则：一是 fail-open，GetUpstreamHosts / SetSharedData 任一出错就记日志走默认路由，熔断自身故障不能阻断流量；二是可回滚，enabled: false 热更新即全量直通，failoverOnStatus: [] 让失败判定永不触发，已有屏蔽自然到期。

总结

把"换端点"做成可观测、可回滚、fail-open 的特性，而不是在 ai-load-balancer 里硬编码一个熔断。但离开箱即用还有距离：本地缓存一致性窗口、CAS 写放大、Redis 故障降级，这些参数需要在自己环境中靠压测和灰度慢慢调。

如果要上生产，需要多关注三个点：多副本网关下 SharedData 只覆盖单实例，所以靠不住，屏蔽状态全局一致得靠 Redis；window 触发模式的失败事件序列存 SharedData 做 CAS 更新，跨 VM 竞争比单纯计数激烈得多，也许把窗口判定直接交给 Redis 的 ZCount 才是正解；上线前对 failureThreshold / blockDurationMs 做灰度验证，误配 failoverOnStatus 的代价是全端点被拉黑。甚至可以考虑在上述设计逻辑中为特殊的上游端点配置白名单，可以是从缓存里面拿去，或者是从按配置的正则来匹配

Semantic_router

Tue, 30 Jun 2026 13:04:01 +0800

vLLM Semantic Router：不只是路由，是 AI 请求全生命周期治理

背景

最近在研究 vLLM 项目组推出的 Semantic Router 项目，结合源码分析和官方博客的几篇文章，整理下这个项目的核心设计和一些思考。

参考文章：

一、项目定位

vLLM Semantic Router (VSR) 是一个信号驱动（Signal-Driven）的系统级智能路由器，面向 Mixture-of-Models (MoM) 架构。

它不是传统 API 网关，而是一个请求理解 + 内容治理 + 智能分发的中间层。

部署方式是 Envoy ext_proc sidecar：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


Client ──► Envoy (port 8801)
 │
 │ gRPC ext_proc (127.0.0.1:50051)
 ▼
 ┌─────────────────────────────────┐
 │ vLLM Semantic Router (Go 进程) │
 │ │
 │ ┌─ extproc gRPC server │
 │ ├─ Signal Engine (18路并发) │
 │ ├─ Decision Engine │
 │ └─ Selection Engine │
 │ │ │
 │ CGO (Rust 动态库) │
 │ ▼ │
 │ ┌─ candle-binding (GPU) │
 │ ├─ onnx-binding │
 │ ├─ openvino-binding │
 │ └─ ml-binding (KNN/KMeans/SVM) │
 └─────────────────────────────────┘

注意：所有 ML 推理通过 CGO 调用 Rust 动态库完成，项目中的 WASM 组件仅用于 Dashboard 前端的 DSL 编译器，不参与运行时推理。

二、Signal → Decision → Selection 三层流水线

信号提取层

系统并行提取 18 种信号，全部以 goroutine 并发执行：

分类	信号	说明
基础	keyword, embedding, domain	关键词/向量/领域
路由	complexity, modality, language, context, structure	复杂度/多模态/语言/上下文长度
安全	jailbreak, PII, fact-check, authz	越狱检测、隐私检测、事实核查、授权
对话	conversation, reask, preference, user-feedback, kb, event	上下文/重复提问/偏好/知识库

决策引擎

基于声明式 YAML 配置的 Decision 结构，支持布尔规则树（AND/OR/NOT 组合）：

1
2
3
4
5
6
7
8


type Decision struct {
 Name string
 Rules RuleCombination // 递归布尔表达式树
 ModelRefs []ModelRef // 候选模型列表
 Algorithm *AlgorithmConfig // 选择算法配置
 Plugins []DecisionPlugin // 安全/缓存/RAG 等插件
 Emits []EmitDirective // 声明式副作用指令
}

模型选择层

实现 10+ 种选择算法：

算法	来源	机制
Elo	RouteLLM	Bradley-Terry 加权评分
RouterDC	arXiv:2409.19886	双重对比学习 query-to-model
AutoMix	arXiv:2310.12963	POMDP 级联 + 自验证
KNN/KMeans/SVM/MLP	FusionFactory	传统 ML + 神经网络
RLDriven	Router-R1	强化学习（Thompson Sampling）
MultiFactor	—	质量 + 时延 + 成本 + 负载加权
SessionAware	—	会话级路由一致性

三、ext_proc 智能路由工程实现

路由决策在 RequestBody 阶段完成，信号采集跨越整个请求生命周期，response 阶段反哺下一次决策：

1
2
3


Request → Headers → Body → [上游推理] → Resp Headers → Resp Body → Client
 │ │ │ │
 安全门控 信号+决策+选模型 记录 TTFT TPOT/成本/缓存

负载感知

全局状态 map[model] → {map[token] → entry{start_time}}，Begin(model) → token / End(model, token)。超过 10min 的 entry 自动淘汰（自愈机制，防 panic/断连导致计数泄漏）。

时延感知

EMA 平滑（α=0.3）+ 滑动窗口（max=1000）+ 百分位查询（默认 p95），采集两个核心指标：

TPOT（Time Per Output Token）：ResponseBody 阶段 completionLatency / completionTokens
TTFT（Time To First Token）：streaming 首个 chunk

成本感知

静态配置价格 + 运行时计量：

1
2
3
4
5


models:
 - name: gpt-4o
 pricing:
 prompt_per_1m: 2.50
 completion_per_1m: 10.00

运行时：cost = prompt_tokens * prompt_rate + completion_tokens * completion_rate

MultiFactor 评分

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


候选模型列表
 │
 ▼
1. SLO 硬过滤（MaxTPOTMs / MaxTTFTMs / MaxCostPer1M / MaxInflight）
 │
 ▼
2. 信号采集（quality 静态配置 / latency p95 / cost 配置 / load 并发数）
 │
 ▼
3. Min-Max 归一化到 [0,1]
 │
 ▼
4. score = wQ*quality + wL*latency + wC*cost + wLoad*load
 权重自动归一化 sum=1，默认等权 0.25

四、路由的真正含义

“选模型"只是 RequestBody 阶段的一个子步骤。整个系统在请求全生命周期做远不止路由的事：

请求进入时：安全门控

能力	行为
Jailbreak 检测	越狱攻击 → 直接返回 403
PII 检测	隐私信息 → 按策略拒绝/脱敏
速率限制	超限 → 返回 429

转发前：请求改写

能力	说明
RAG 注入	从向量库检索相关文档，注入 messages
Memory 注入	注入用户历史对话记忆
Prompt 压缩	评估文本过长时压缩，减少 token
System Prompt 注入	按 decision 分支注入不同 system prompt
工具选择	按 decision 配置选择暴露哪些 tools

响应返回时：后处理

能力	说明
语义缓存	embedding 相似度匹配 → 直接返回缓存
幻觉检测	NLI 模型检测 → 注入警告或拦截
格式转换	OpenAI ↔ Anthropic 协议互转
记忆存储	将对话存入记忆系统供未来使用

“Semantic” 在哪？ 不在"路由到哪个 cluster"这一步，而在"决定怎么处理这个请求"这一步。它理解请求的语义，然后决定：要不要发（安全门控）、发给谁（模型选择）、怎么发（请求改写）、发完怎么处理（响应后处理）。

五、路由决策 → Envoy 分发链路

路由器不直接选 Pod。它选模型，通过 header mutation 告诉 Envoy 去哪个 cluster，Pod 选择由 Envoy 的 LB 完成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


第一步：决策引擎选模型
 Signal → Decision → Selection → selectedModel = "deepseek-r1"

第二步：模型 → Backend 解析
 PreferredEndpoints = ["ep-vllm-rack2"]
 ExternalModelIDs["vllm"] → "deepseek-ai/DeepSeek-R1"

第三步：构建 Header Mutation
 x-selected-model: "deepseek-r1" ← Envoy 路由匹配 key
 Authorization: "Bearer sk-xxx" ← 下游凭证

第四步：Body Mutation
 {"model": "auto"} → {"model": "deepseek-ai/DeepSeek-R1"}

第五步：Envoy 根据 header 选择 cluster + Pod
 x-selected-model prefix "claude-" → anthropic_api_cluster
 x-selected-model regex /^(gpt-|o1-)/ → openai_api_cluster
 else → vllm_backend_cluster
 （Pod 级负载均衡由 Envoy ROUND_ROBIN 完成）

六、四大核心机制

6.1 语义缓存

不是精确匹配 query 文本，而是 embedding 向量相似度匹配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


请求 "如何用 Python 排序"
 │
 ▼
1. 提取 query
2. 检查跳过：含 RAG/Memory 的决策跳过缓存（防泄露用户数据）
3. 生成 embedding
4. HNSW 向量搜索 (M=16, efConstruction=200, efSearch=50)
5. similarity >= threshold ?
 YES → 命中！返回缓存
 NO → 请求发往模型，响应返回后写入缓存

缓存后端：内存 + HNSW 索引 / Milvus / Redis，支持按 decision 独立配置 similarity_threshold 和 TTL。

6.2 幻觉检测

两层检测，通过 CGO 调用 Rust Candle binding 的 NLI 模型：

基础版：DetectHallucination(context, question, answer) → {detected, confidence, unsupported_spans}
NLI 增强版：DetectHallucinationWithNLI(...) → span 级标注 {text, start, end, nli_label, severity, explanation}

检测后按 action 处理：header 设置警告 header / body 在响应前插入警告 / none 仅记录 metrics。

6.3 循环检测

Reask 检测：计算当前 turn 与历史 turns 的 embedding cosine 相似度，倒序检查连续超过阈值的 streak：

1
2


规则: { threshold: 0.85, lookback_turns: 3 }
streak >= lookback ? 触发 : 不触发

Conversation 检测：检测工具调用循环（lastMessage == tool_result / assistantToolCallCount > toolResultCount）。

6.4 记忆存储与召回

三种记忆类型：

Type	含义	例子
semantic	事实/偏好/知识	“用户的夏威夷预算是 $10K”
procedural	操作步骤/指令	“部署 payment-service: npm build → docker push”
episodic	会话摘要/事件	“2024-12-29 用户规划了夏威夷旅行”

生命周期：

存储：Response 阶段异步 goroutine，提取 userMessage + assistantResponse + history → MemoryExtractor.ProcessResponseWithHistory(...)
检索：Request 阶段，自适应阈值（找最大 score 断层，只返回强相关记忆），hybridSearch
注入：格式 "以下是用户之前对话的相关上下文：\n- {memory.content}"，位置在 system message 之后、第一条 user message 之前

安全设计：检索按 UserID 隔离，含 RAG/Memory 的 decision 跳过语义缓存，jailbreak 拦截的响应不存入记忆。

七、v0.3 Themis Release 要点

2026 年 6 月 5 日发布的 v0.3 是一个里程碑版本，350+ commits，核心变化：

配置稳定：YAML 配置契约固化，生产可用
协议兼容：新增 Anthropic 协议支持，OpenAI ↔ Anthropic 格式互转
推理后端扩展：Intel OpenVINO 支持（x86 也能跑推理）
性能验证：RouterArena 排名 #1（75.4 分）
生态接入：Kubernetes Operator、Helm Chart、Grafana Dashboard

八、SAAR：会话感知的 Agentic 路由

Session-Aware Agentic Routing 解决的核心问题：在 Agent 场景下，路由切换模型会导致会话状态丢失。

SAAR 的设计：

会话记忆由路由器管理，不是推理引擎
硬锁定（Hard Lock）：Agent 工作流期间锁定当前模型，不切换
重置边界（Reset Boundaries）：明确哪些操作可以重置会话状态
切换经济学（Switch Economics）：量化切换成本（上下文重建、延迟、缓存失效），只有收益 > 成本才切换
Replay Traces：切换模型时，将之前的对话历史 replay 给新模型

九、Micro-Agent：多模型协作

Micro-Agent 的核心理念：前沿模型不再单独工作，而是在 API 服务层实现多模型协作。

六大协作机制：

机制	说明
Confidence	模型输出置信度评分
Ratings	多模型对同一输出打分
ReMoM	Mixture-of-Models 的路由+混合
Fusion	多模型输出融合
Workflows	预定义的多模型工作流
Auto Recipes	自动发现最优模型组合

十、AI 网关演进方向

推理引擎正在变成"无状态执行单元”

1
2
3
4
5
6
7
8
9


传统 API 网关:
 Client ──► [鉴权/限流] ──► Backend ──► Response

AI 网关（新范式）:
 Client ──► [理解层] ──► [增强层] ──► [治理层] ──► Inference ──► [审计层] ──► Response
 │ │ │ │
 信号提取 RAG/记忆注入 选模型/改参数 幻觉检测
 意图分类 prompt压缩 限流/缓存 格式转换
 安全检测 工具选择 凭证注入 成本计量

维度	以前（推理引擎为中心）	未来（网关为中心）
Prompt 管理	应用层拼 prompt	网关层动态组装
上下文	应用层管理对话历史	网关层记忆系统自动注入
安全	模型内置 / 外挂审核服务	网关层内联（零延迟）
模型选择	应用层硬编码	网关层信号驱动自动决策
缓存	应用层 Redis	网关层语义缓存

稳定前缀 vs 动态注入

当前设计的结构性问题：每次请求的注入内容独立检索，模型看到的"世界"每轮都在变。

建议的分层架构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


┌───────────────────────────────┐
│ Session Layer（稳定） │ 创建时确定，session 内不变
│ system prompt │
│ user profile snapshot │
│ turn history (append-only) │
├───────────────────────────────┤
│ Request Layer（动态） │ 每轮独立
│ real-time RAG │
│ safety detection │
│ model selection │
├───────────────────────────────┤
│ Response Layer（后处理） │ 响应后执行
│ hallucination check │
│ memory extraction │
│ session history append │
└───────────────────────────────┘

这与 OpenAI Responses API 的 previous_response_id 设计方向一致 — 服务端维护完整上下文链，上下文是追加式的，不是每次重建的。

待解决问题

个性化 vs 缓存矛盾：含 RAG/Memory 的请求跳过缓存，最有价值的请求享受不到缓存收益
延迟叠加：信号 ~10ms + RAG ~50ms + 记忆 ~30ms + 幻觉 ~100ms ≈ 190ms 额外延迟
网关可用性瓶颈：解法是 failure_mode_allow: true，网关故障时直通后端

总结

vLLM Semantic Router 的核心价值不在"路由"而在"治理"。它把传统 API 网关的鉴权/限流能力，扩展到了 AI 语义理解的维度：理解请求意图、安全门控、智能选模型、请求改写、响应后处理、记忆管理。

从 v0.3 Themis 到 SAAR 到 Micro-Agent，这个项目在快速演进。方向很明确：推理引擎变成无状态执行单元，智能向网关层迁移。但动态注入 vs 上下文一致性、个性化 vs 缓存的矛盾，仍然是需要解决的核心问题。

AI 编程助手的上下文压缩：only-cc-lite 设计与 98 个真实会话的压测分析

Sun, 07 Jun 2026 13:12:44 +0800

为什么需要上下文压缩

AI 编程助手（Claude Code、Qwen Code、Cursor 等）的工作模式是累积式的：每次用户发一条消息，客户端会把从会话开始到当前的所有消息一起发送给 LLM API。

这意味着一个 30 轮的会话，第 30 次请求包含了前 29 轮的全部历史。如果中间执行了 cargo build、npm run build、grep 搜索等工具调用，大量构建日志、搜索结果会被反复发送。

实际使用中，一个中等复杂度的调试会话，单次请求的 input tokens 轻松突破 10 万。累积下来，一个会话消耗几百万 tokens 很常见。

问题的核心：大部分历史内容是重复的，但不能直接丢弃。LLM 需要上下文来理解代码变更的背景，而 LLM 提供商的前缀缓存（prompt cache）机制要求历史消息的字节序列保持不变。

only-cc-lite 就是为解决这个问题而生的。

设计原则

从 Headroom 提取，但做了关键简化：

特性	headroom-core	only-cc-lite
内容类型检测	Magika ONNX + 正则	纯正则
Token 计数	tiktoken-rs + HuggingFace	字符密度估算
语义相关性评分	fastembed ONNX	BM25 纯关键词
二进制膨胀	~50-80MB (ONNX)	<5MB
传递依赖	4182	~80

三个核心设计原则：

零 ML 依赖 — 不引入 ONNX Runtime、fastembed、HuggingFace tokenizers，纯 Rust 实现
增量压缩 — 只压缩 user 侧的增量内容，assistant 消息原样保留
前缀缓存安全 — 压缩后的请求，历史部分的字节序列与原始请求完全一致

增量压缩模型

传统做法是压缩整个请求体。但这会破坏 LLM 提供商的前缀缓存——提供商通过 SHA-256 哈希请求的前 N 个字节来判断是否命中缓存，任何字节变化都会导致缓存失效。

only-cc-lite 的做法是只压缩最新 user 消息中的可压缩内容块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


请求消息结构：
┌─────────────────────────────────────┐
│ user msg #0 (frozen) │ ← 不动
│ assistant msg #0 (frozen) │ ← 不动
│ user msg #1 (frozen) │ ← 不动
│ assistant msg #1 (frozen) │ ← 不动
│ ... │
│ user msg #N ← LIVE ZONE │ ← 只压缩这里
│ ├─ text block "请帮我修复..." │ ← 不压缩（短文本）
│ ├─ tool_result: 构建日志 8000 tok │ ← 压缩！(log_compressor)
│ ├─ tool_result: grep 结果 2000 tok│ ← 压缩！(search_compressor)
│ └─ tool_result: git diff 1500 tok │ ← 压缩！(diff_compressor)
│ assistant msg #N (cache hot zone) │ ← 不动
└─────────────────────────────────────┘

对应的 Rust 实现入口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


use only_cc_lite::{compress_request, Provider};

let outcome = compress_request(
 &body,
 Provider::Anthropic,
 "claude-sonnet-4-5-20250929",
 None, // ccr_store，可选
)?;

match &outcome.body {
 Some(compressed) => {
 // 转发压缩后的 body 到上游 API
 forward_to_upstream(compressed);
 }
 None => {
 // 无可压缩内容，转发原始 body
 forward_to_upstream(&body);
 }
}

这个模型的核心洞察：编程助手会话中，assistant 消息（代码、解释）占比大但不适合压缩（格式敏感），而 user 消息中的工具结果（日志、搜索结果）是最理想的压缩目标——结构化、冗余高、可安全截断。

四种压缩策略

压缩器通过正则检测内容类型，自动选择最合适的策略：

LogCompressor — 构建/运行日志

识别 ERROR、WARN、Traceback、panic、failed 等模式，提取关键错误信息，丢弃重复的编译输出。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


输入 (8000 tokens):
 Compiling foo v0.1.0
 warning: unused variable `x` --> src/main.rs:42:9
 error[E0308]: mismatched types --> src/lib.rs:100:5
 ... (几百行编译输出)

输出 (1200 tokens):
 [ERROR] src/lib.rs:100:5 - mismatched types
 [WARN] src/main.rs:42:9 - unused variable `x`
 ... (只保留错误和警告)

SearchCompressor — 代码搜索结果

匹配 file:line:content 格式的搜索结果，保留匹配行，丢弃上下文。

DiffCompressor — Git Diff

解析 unified diff 格式，保留变更摘要（文件名、变更类型），压缩具体 diff 内容。

SmartCrusher — JSON 数组

解析 JSON 数组，保留首尾元素，中间用统计摘要替代。

1
2
3
4
5


// 输入: 100 个元素的数组
[{"id":1,"name":"a"},{"id":2,"name":"b"},...,{"id":100,"name":"zz"}]

// 输出: 首尾 + 摘要
[{"id":1,"name":"a"}, "... 98 more items ...",{"id":100,"name":"zz"}]

SmartCrusher 的压缩效果最好，单轮可达 60-90%。但在真实编程助手中，触发频率最低——大部分工具调用返回的是日志和搜索结果，不是纯 JSON 数组。

前缀缓存保护机制

这是 only-cc-lite 最关键的设计。三层保护确保压缩不会破坏 LLM 提供商的前缀缓存：

第一层：Frozen Zone

历史消息（所有 assistant 消息 + 之前的 user 消息）完全不动。通过 frozen_message_count 参数确定冻结边界。

第二层：Live Zone 限制

只在最新 user 消息内寻找可压缩的 content blocks。Assistant 消息即使包含大段内容也不压缩。

第三层：Byte-range Surgery

这是最精妙的部分。apply_replacements() 函数做字节级精确替换：

1

out = body[..block_start] || replacement || body[block_end..]

被替换的 block 通过 serde_json::value::RawValue 的借用切片定位其在原始 buffer 中的偏移量。替换前后，block 外部的字节逐字节复制，不做任何重新序列化。

这意味着：

1
2
3
4


原始请求: [prefix bytes...] [block A] [suffix bytes...]
压缩后: [prefix bytes...] [block A'] [suffix bytes...]
 ↑
 只有这里变了

前缀的 SHA-256 在压缩前后完全一致，LLM 提供商的 prompt cache 命中率不受影响。

实际上，这也是为什么压缩器只压缩最后一条 user 消息——更早的消息即使是 user 消息，修改它们也会破坏前缀缓存。

真实会话压测

为了验证压缩效果，基于真实的 AI 编程助手会话日志做了评估。

测试数据

维度	数值
压测会话数	98 个（Claude Code 2 个 + Qwen Code 96 个）
对话轮次	4,210
总 input tokens	3.28 亿
涉及模型	mimo-v2.5-pro、minimax-m2.7、kimi-k2.6、glm-5、glm-4.7-flash、deepseek-v4-flash、qwen3.6-plus 等

会话来源通过环境变量自动定位（$USERPROFILE 或 $HOME），不依赖任何硬编码路径。会话文件格式包括 Anthropic Messages API（Claude Code）和 OpenAI Chat Completions（Qwen Code）两种。

总体指标

指标	数值
User 内容（可压缩）	10.3 MB
Assistant 内容（保留不动）	3.3 MB
Tokens 节省	103,256
Bytes 节省	452,770
整体 User 压缩率	4.4%

4.4% 看起来不高？这恰恰反映了编程助手的真实使用特征。

场景收益分析

收益明显的场景——user 消息中包含大块结构化内容：

场景	策略	单轮压缩率	触发条件
构建失败日志	log_compressor	50-100%	`cargo build`、`npm run build` 输出大量错误
运行时错误堆栈	log_compressor	70-100%	Python traceback、Node.js rejection
代码搜索结果	search_compressor	50-80%	grep/ripgrep 返回大量匹配
Git diff	diff_compressor	40-60%	多文件变更的 diff 输出
JSON 数据	smart_crusher	60-90%	API 响应、配置文件

典型案例：一个 28 轮会话中，第 1 轮就压缩了 14,790 tokens（构建日志），单轮压缩率 100%。

几乎无收益的场景——占绝大多数轮次：

场景	占比	原因
短指令对话	~60% 轮次	“fix this bug”、“add a test” < 500 bytes
纯文本粘贴	~15% 轮次	错误描述、需求说明等非结构化文本
小文件内容	~10% 轮次	单个函数/配置片段 < 5KB
对话式交互	~10% 轮次	追问、确认、解释

98 个会话中 73 个（74%）未产生任何压缩——整个会话没有出现大块结构化内容。

1
2
3
4
5
6


会话压缩收益分布（98 个会话）：

无压缩 ████████████████████████████████████████ 73 个 (74%)
< 1% █████ 7 个 (7%)
1-5% ████████ 12 个 (12%)
5-15% ██████ 6 个 (6%)

收益高度集中：Top 5 会话贡献了 52% 的总 tokens 节省。

策略命中统计

策略	命中轮次	贡献占比
log_compressor	57 turns	~85%
diff_compressor	8 turns	~8%
search_compressor	2 turns	~5%
smart_crusher	1 turn	~2%

log_compressor 是绝对主力。这也符合直觉——编程助手中最常见的"重内容"就是构建和运行日志。

与会话长度的关系

会话轮次	压缩情况
短会话 (< 10 轮)	通常无压缩，除非首轮就有大日志
中等会话 (10-50 轮)	部分有压缩，取决于是否触发构建/搜索
长会话 (50+ 轮)	更可能遇到构建失败，但平均压缩率不一定更高

结论：压缩收益与会话长度无关，与是否触发"重内容"工具调用强相关。一个 338 轮的长会话可能压缩率很低（如果都是短指令），而一个 5 轮的调试会话可能单轮压缩 90%。

运行自己的压测

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 克隆仓库
git clone https://github.com/daidaiJ/only-cc-lite.git
cd only-cc-lite

# 运行评估（自动发现本地会话文件）
cargo bench --bench eval_runner

# 查看报告
cat target/eval-report.txt # 人类可读
cat target/eval-report.json # 程序消费

支持的 Agent CLI：

Agent CLI	会话目录	日志格式
Claude Code	`~/.claude/projects//.jsonl`	Anthropic Messages API
Qwen Code	`~/.qwen/projects//chats/.jsonl`	OpenAI Chat Completions

总结

only-cc-lite 的核心价值不在于压缩率有多高，而在于压缩的安全性：

零侵入 — 只压缩最后一条 user 消息，不动历史，不破坏前缀缓存
零依赖 — 纯 Rust，无 ONNX/tokenizer，<5MB 二进制
零风险 — 压缩失败自动降级为 passthrough，不影响正常请求

在真实编程助手场景下，整体压缩率 4.4%，但"重内容"场景下单轮可达 50-100%。对于重度使用构建/调试/搜索的开发者，长期累积的 tokens 节省可观。对于以对话为主的轻量使用，压缩收益有限但也不会引入额外开销。

本质上这是一个"有则赚，无则不亏"的设计——压缩器只在有明确收益时才出手，其他时候完全透明。

项目地址: github.com/daidaiJ/only-cc-lite

许可证: Apache-2.0

Google ax + substrate：智能体运行时调度架构分析

Sun, 07 Jun 2026 09:53:32 +0800

Google ax + substrate：智能体运行时调度架构分析

Google 开源了两套用于运行长时间智能体（Agent）的组件：ax 和 substrate。ax 负责业务编排和会话管理，substrate 负责沙箱实例的生命周期调度。两者组合解决了 LLM 智能体运行时的核心问题：一个有状态的 Agent 进程，在空闲时如何保存全部状态并释放计算资源，新请求来了怎么快速恢复。

架构总览：两层设计

graph TB
subgraph ax["ax (编排层)"]
Controller["Controller
调谐循环"]
EventLog["EventLog
事件溯源"]
Harness["Harness
执行抽象"]
end
subgraph substrate["substrate (基础设施层)"]
ControlAPI["ControlAPI
状态机+锁"]
WorkerPool["WorkerPool
K8s Pod 池"]
Atelet["Atelet
快照 Agent"]
Redis["Redis
Actor 状态"]
end
Controller -->|gRPC| ControlAPI
Harness -->|gRPC| ControlAPI
ControlAPI --> Redis
ControlAPI --> WorkerPool
ControlAPI --> Atelet

两层的职责边界很清晰：ax 知道"做什么"（业务逻辑），substrate 知道"怎么跑"（沙箱调度）。ax 通过 gRPC 调用 substrate 的 ControlAPI 来管理 Actor 的创建、恢复和挂起。

核心概念：Actor 模型

每个 Agent 会话对应一个 Actor，这是整个系统的核心抽象。Actor 不是一个 Go 对象，而是一个分布式状态机，状态存在 Redis 里，实际的沙箱进程跑在 K8s Worker Pod 上。

Actor 状态流转：

stateDiagram-v2
[*] --> SUSPENDED: CreateActor
SUSPENDED --> RESUMING: ResumeActor
RESUMING --> RUNNING: 成功
RESUMING --> SUSPENDED: 失败(回退)
RUNNING --> SUSPENDING: SuspendActor
SUSPENDING --> SUSPENDED: 成功
SUSPENDING --> RUNNING: 失败(回退)

每个状态转换都是幂等的，失败时回退到前一个稳定状态。状态字段定义在 Redis 里，用 version 字段做乐观并发控制（WATCH 事务）。

Actor 核心字段（Redis 存储）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// substrate/pkg/proto/ateapipb/ateapi.proto
message Actor {
 string id = 1;
 ActorStatus status = 2; // UNSPECIFIED/RESUMING/RUNNING/SUSPENDING/SUSPENDED
 int64 version = 3; // 乐观并发版本号
 string last_snapshot = 4; // 最近完成的快照路径（GCS）
 string in_progress_snapshot = 5; // 正在写入的快照路径
 string ateom_pod_name = 6; // 绑定的 K8s Pod
 string ateom_pod_ip = 7; // Pod IP
 string ateom_pod_node = 8; // Pod 所在 Node
}

这里的关键设计是：Actor 状态和 Worker 节点是解耦的。Redis 里只存"这个 Actor 应该在哪"，实际的沙箱进程可以漂移到任何有空闲资源的 Worker 上。

WorkerPool：K8s 原生的 Worker 管理

substrate 用 K8s CRD 来管理 Worker 节点池，而不是自建调度器。这样可以复用 K8s 的 HPA、PDB 等能力。

1
2
3
4
5


// substrate/pkg/api/v1alpha1/workerpool_types.go
type WorkerPoolSpec struct {
 Replicas int32 `json:"replicas"` // Worker Pod 数量
 AteomImage string `json:"ateomImage"` // gVisor 沙箱镜像
}

WorkerPoolSyncer 是一个 K8s Controller，监听 ate.dev/worker-pool 标签的 Pod：

1
2
3
4
5
6
7
8
9


// substrate/cmd/ateapi/internal/controlapi/syncer.go
// 核心逻辑：watch Pod 变更，同步到 Redis Worker 集合
func (s *WorkerPoolSyncer) syncPods(ctx context.Context) error {
 pods, _ := s.kubeClient.CoreV1().Pods(s.namespace).List(ctx, metav1.ListOptions{
 LabelSelector: "ate.dev/worker-pool=" + s.poolName,
 })
 // 用 Redis SET 维护活跃 Worker 列表
 // Pod 删除时，尝试释放该节点上的 Actor（best-effort）
}

有一个值得注意的点：Pod 意外死亡时，releaseActorOnDeadWorker 是 best-effort 的。如果此时恰好有并发操作导致乐观锁冲突，Actor 可能卡在 RUNNING 状态——这是一个已知问题。

挂起与恢复：4 步幂等工作流

这是整个系统最精妙的部分。挂起和恢复都不是单次操作，而是拆成 4 个幂等步骤的工作流，每一步都可以安全重试。

通用工作流引擎：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// substrate/cmd/ateapi/internal/controlapi/workflow.go
func RunWorkflow[Params, Context any](
 ctx context.Context,
 params Params,
 steps []WorkflowStep[Params, Context],
) error {
 for _, step := range steps {
 // 1. 先检查这步是否已经完成（幂等快进）
 done, _ := step.IsComplete(ctx, params, context)
 if done {
 continue // 已完成，跳过
 }
 // 2. 执行步骤，带指数退避重试
 retry.Retry(step.Action, retry.WithBackoff(retry.NewExponentialBackoff()))
 }
}

每一步先调 IsComplete 检查是否已完成——这就是幂等的核心。如果系统在步骤 3 崩溃了，重启后从步骤 1 开始，步骤 1 和 2 的 IsComplete 会返回 true，直接跳到步骤 3 继续。

挂起工作流（4 步）：

1
2
3
4
5
6
7


// substrate/cmd/ateapi/internal/controlapi/workflow_suspend.go
steps := []WorkflowStep[SuspendActorParams, SuspendActorContext]{
 {Name: "LoadActorForSuspend", Action: loadActorForSuspend},
 {Name: "MarkSuspending", Action: markSuspending}, // RUNNING→SUSPENDING, 生成快照路径
 {Name: "CallAteletSuspend", Action: callAteletSuspend}, // gRPC 调用 Atelet 做 checkpoint
 {Name: "FinalizeSuspended", Action: finalizeSuspended}, // 释放 Worker, 更新 LastSnapshot
}

快照路径生成用时间戳+随机数避免冲突：

1
2
3
4
5


func markSuspending(ctx context.Context, params SuspendActorParams, sCtx *SuspendActorContext) error {
 snapshotPath := fmt.Sprintf("gs://bucket/actors/%s/snapshots/%d-%s",
 params.ActorID, time.Now().UnixNano(), rand.String(8))
 // Redis: status SUSPENDED→SUSPENDING, in_progress_snapshot = snapshotPath
}

恢复工作流（4 步）：

1
2
3
4
5
6
7


// substrate/cmd/ateapi/internal/controlapi/workflow_resume.go
steps := []WorkflowStep[ResumeActorParams, ResumeActorContext]{
 {Name: "LoadActorForResume", Action: loadActorForResume},
 {Name: "AssignWorker", Action: assignWorker}, // 从 WorkerPool 选空闲 Pod
 {Name: "CallAteletRestore", Action: callAteletRestore}, // 3条路径: 快照恢复/黄金快照/冷启动
 {Name: "FinalizeRunning", Action: finalizeRunning}, // SUSPENDING→RUNNING
}

assignWorker 的逻辑是：shuffle 所有 Worker，找到第一个没有绑定 Actor 的 Pod。如果所有 Pod 都满了，直接失败——WorkerPool 不会自动扩容，需要外部 HPA 或手动调整 replicas。

恢复时有 3 条路径：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func callAteletRestore(ctx context.Context, params ResumeActorParams, rCtx *ResumeActorContext) error {
 switch {
 case rCtx.Actor.LastSnapshot != "":
 // 路径1: 有个人快照，从 GCS 下载 + runsc restore
 case rCtx.Template != nil && rCtx.Template.Snapshot != "":
 // 路径2: 黄金快照（ActorTemplate 预制），快速冷启动
 default:
 // 路径3: 纯冷启动，无状态恢复
 }
}

快照机制：gVisor checkpoint/restore

这是整个系统的"魔法"所在。gVisor 的 checkpoint/restore 能把整个沙箱进程的内存状态序列化到文件，恢复时从文件加载回内存，实现毫秒级的状态恢复。

Atelet（DaemonSet，每节点一个）负责实际的快照操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// substrate/cmd/ateom-gvisor/runsc.go
// checkpoint: 把容器进程的全部内存页 + sentry 状态写到磁盘
func (r *Runsc) Checkpoint(ctx context.Context, containerID, imagePath string) error {
 args := []string{"checkpoint", "--image-path", imagePath, containerID}
 // 注意：没有 --parent 参数，不支持增量快照
 return r.runsc.Run(ctx, args...)
}

// restore: 从磁盘加载内存页，重建容器进程
func (r *Runsc) Restore(ctx context.Context, containerID, imagePath, bundlePath string) error {
 args := []string{"restore", "--image-path", imagePath,
 "--background", "--direct", "--detach", "--bundle", bundlePath, containerID}
 return r.runsc.Run(ctx, args...)
}

快照上传/下载用 zstd 压缩：

1
2
3
4
5
6
7
8
9


// substrate/cmd/atelet/internal/ategcs/objects.go
func (s *ObjectStorage) SendLocalFileToGCSWithZstd(ctx, bucket, object, localPath) error {
 // 本地文件 → zstd 压缩 → GCS PUT
 // 没有合并、没有增量、没有去重
}

func (s *ObjectStorage) FetchLocalFileFromGCSWithZstd(ctx, bucket, object, localPath) error {
 // GCS GET → zstd 解压 → 写本地文件
}

一个很大的设计局限：每次挂起都是全量快照。gVisor 的 runsc checkpoint 支持 --parent 增量模式，但 substrate 没有用。这意味着一个 2GB 内存的 Agent，每次挂起都会写 2GB（压缩后可能 500MB）。没有快照合并、没有增量、没有去重。

ax 编排层：事件溯源与调谐循环

ax 的设计哲学是 event-sourcing：所有状态变更都记录为事件，系统状态可以从事件日志完全重建。

双事件日志：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// ax/internal/controller/executor/sqlite.go
// 两张表：
// conversation_log: 客户端消息（通过 lastSeq 实现增量同步）
// execution_log: 执行记录（用于崩溃恢复时重放）

type EventLog interface {
 Append(ctx, conversationID string, event *ConversationEvent) (int64, error) // 追加会话事件
 AppendExec(ctx, conversationID string, event *ExecutionEvent) error // 追加执行事件
 Events(ctx, conversationID string, afterSeq int64) ([]*ConversationEvent, error) // 读取会话事件
 ExecEvents(ctx, conversationID string) ([]*ExecutionEvent, error) // 读取执行事件
}

v1 Controller 的调谐循环：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// ax/internal/controller/controller.go
func (c *Controller) tryResuming(ctx, req) error {
 events := c.eventLog.Events(req.ConversationID)
 lastSeq := req.LastSeq

 // 1. 快进：跳过客户端已知的事件
 for _, ev := range events {
 if ev.Seq <= lastSeq { continue }
 // 客户端需要这些事件，先推送给它
 }

 // 2. 查找未完成的执行（崩溃恢复）
 pending := findPendingExecutions(events)
 if len(pending) > 0 {
 // 重放历史，恢复执行
 replayHistory(pending)
 }

 // 3. 驱动新的执行
 executor.Execute(ctx, req)
}

这里的 lastSeq 机制很巧妙：客户端告诉服务端"我已知到第 N 条事件"，服务端只推送 N 之后的事件。这样即使中间服务端重启了，客户端也不会丢消息。

Harness 抽象（v2 重构）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// ax/internal/harness/harness.go
type Harness interface {
 Start(ctx context.Context, conversationID string) (Execution, error)
}

type Execution interface {
 Run(ctx, input) error
 Queue(ctx, input) error
 ID() string
 Close(ctx) error
}

v1 直接用 agent.Agent 接口，v2 引入 Harness 抽象，SubstrateHarness 桥接到 substrate：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// ax/internal/harness/substrate.go
func (h *SubstrateHarness) Start(ctx, conversationID) (Execution, error) {
 // 1. CreateActor（幂等）
 h.client.CreateActor(ctx, &CreateActorRequest{Id: conversationID})
 // 2. ResumeActor
 h.client.ResumeActor(ctx, &ResumeActorRequest{Id: conversationID})
 // 3. gRPC 连接到 Worker Pod
 actor := h.client.GetActor(ctx, &GetActorRequest{Id: conversationID})
 conn, _ := grpc.Dial(actor.AteomPodIp + ":50051")
 // 4. 开始执行
 return &substrateExecution{conn: conn, actor: actor}, nil
}

func (e *substrateExecution) Close(ctx) error {
 // 5. 关闭 gRPC 连接
 e.conn.Close()
 // 6. Fire-and-forget 挂起！
 go suspendActor(e.actor.Id) // ⚠️ 结果没人检查
 return nil
}

针对 Agent 业务的特殊设计

通用的容器编排（K8s）解决不了智能体的需求，因为 Agent 进程的内存状态就是业务状态本身。下面这些设计都是为这个特点服务的。

1. 进程级快照而非应用级序列化

传统微服务用数据库/Redis 持久化状态，重启后从存储加载。但 LLM Agent 的状态太复杂：

LLM 对话历史（可能几 MB）
Python/Node 运行时的完整堆栈
工具调用的中间状态
向量数据库的内存索引

gVisor checkpoint 直接序列化整个进程的内存页，不需要应用层做任何适配。代价是快照体积大、无法增量。

2. 黄金快照（Golden Snapshot）

1
2
3
4
5
6
7
8
9


// ActorTemplate Controller 预制一个初始快照
// 比如：已安装依赖、已加载模型权重、已初始化运行时
// 新 Actor 恢复时如果有黄金快照，跳过冷启动
type ActorTemplate struct {
 Spec ActorTemplateSpec
 Status struct {
 Snapshot string // 预制快照的 GCS 路径
 }
}

这个设计很聪明。Agent 运行时（比如 Python + langchain + 向量库）冷启动可能要 30s+，但如果有黄金快照，恢复只需要几秒。

3. 分布式锁保证单点写入

1
2
3
4
5
6


// Redis SETNX + TTL = 30 秒
func acquireActorLock(ctx, actorID string) (bool, error) {
 key := "actor:lock:" + actorID
 acquired, _ := rdb.SetNX(ctx, key, "1", 30*time.Second).Result()
 return acquired, nil
}

一个 Actor 同一时刻只能有一个挂起/恢复操作。锁的 TTL 是 30 秒——如果操作超过 30 秒没完成，锁自动释放，其他操作可以介入。这比 K8s 的 resourceVersion 乐观锁更适合长时间操作。

存在的问题

坦率说，这两个项目还在早期阶段（v1alpha1），有不少明显的架构缺陷。

1. 没有空闲检测和冷却期

最严重的问题。当前逻辑是每次请求结束就立刻挂起：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// ax/internal/server/server_ate.go
func (s *Server) Execute(ctx, req) {
 s.inFlight[req.ConversationId] = struct{}{}
 defer delete(s.inFlight, req.ConversationId)

 exec, _ := s.harness.Start(ctx, req.ConversationId)
 defer exec.Close(ctx) // ← 立刻触发挂起

 exec.Run(ctx, req) // ← 执行完就挂起
}
// 挂起只有 50ms 的延迟：
func suspendActor(conversationID string) {
 time.Sleep(50 * time.Millisecond) // ⚠️ 几乎等于立刻挂起
 client.SuspendActor(...)
}

后果： 高频请求的 Agent 会疯狂抖动——每次请求都触发一次全量 checkpoint + restore。一个 1GB 内存的 Agent，每秒 1 次请求 = 每秒写 1GB 快照到 GCS。

缺少的机制：

没有 idle timeout（空闲 N 秒后才挂起）
没有 cooldown（挂起后 N 秒内不允许再挂起）
没有活跃度判断（看最近 N 分钟的请求频率）

2. 挂起是 Fire-and-Forget

1
2


// ax/internal/server/server_ate.go
go suspendActor(req.ConversationId) // 结果没人检查

1
2
3
4
5
6
7
8


func suspendActor(conversationID string) {
 ctx := context.Background()
 client := getATEClient()
 _, err := client.SuspendActor(ctx, &pb.SuspendActorRequest{Id: conversationID})
 if err != nil {
 log.Error(err) // 只记日志，不重试，不回退
 }
}

挂起失败了怎么办？Actor 卡在 RUNNING 状态，Worker Pod 不会被释放，资源一直占用。没有重试、没有告警、没有补偿。而且 SuspendActor 的 gRPC 超时只有 30 秒，如果 checkpoint 大一点（比如 2GB），可能超时失败。

3. 没有快照 GC

1
2
3
4
5


// substrate 只跟踪最近一个快照
type Actor struct {
 LastSnapshot string // 最近完成的快照
 InProgressSnapshot string // 正在写的快照
}

每次挂起都往 GCS 写一个新快照，但从不删除旧快照。一个月下来，一个 Actor 可能积累上百个快照文件。没有 GC 策略、没有 TTL、没有存储配额。

4. 没有自动扩缩容

WorkerPool 是静态的 Replicas，Actor 绑定满了就拒绝新请求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func assignWorker(ctx, params, rCtx) error {
 workers := shuffle(allWorkers)
 for _, w := range workers {
 if !isOccupied(w) {
 // 分配成功
 return nil
 }
 }
 return errors.New("no available worker") // ← 所有 Worker 都满了
}

没有 HPA 集成、没有 pending 队列、没有抢占机制。生产环境需要自己搭扩缩容逻辑。

5. Worker 死亡时的状态恢复有竞态

1
2
3
4
5
6
7
8


// substrate/cmd/ateapi/internal/controlapi/syncer.go
func releaseActorOnDeadWorker(ctx, podName string) {
 actor := findActorByPod(podName)
 if actor == nil { return }
 // best-effort：用乐观锁重置状态
 // 但如果有并发操作（比如正在 Resume），可能冲突
 // 冲突后 Actor 卡在 RUNNING，Pod 已死 → 资源泄漏
}

这个问题在 GitHub issue #23 有讨论。核心矛盾是：K8s 的 Pod 删除是异步的，substrate 的 Actor 状态更新也是异步的，两个异步事件之间没有原子性保证。

6. v2 Controller 缺少执行恢复

1
2
3
4
5


// ax/internal/controller2/controller.go
func (c *Controller) reconcile(ctx, req) {
 // TODO: tryResuming 没有实现
 // 崩溃后的执行恢复靠谁做？不清楚。
}

7. 没有增量快照

gVisor 的 runsc checkpoint 原生支持 --parent 增量模式（只写和上次快照相比变化的内存页），但 substrate 没用。每次都是全量写。对于内存较大的 Agent 进程（比如加载了大模型的推理服务），这是一个很大的存储和性能瓶颈。

总结

ax + substrate 的设计思路是对的：用 gVisor 的进程级快照解决 Agent 状态持久化，用 K8s CRD 管理 Worker 池，用幂等工作流保证挂起/恢复的可靠性。但作为一个还在 v1alpha1 阶段的项目，它离生产可用还有不少距离——最核心的短板是没有空闲检测（每次请求结束就挂起）、没有快照 GC、挂起失败不重试。

如果要在生产中用这套架构，需要自己补的东西：

suspendScheduler：带 debounce 的挂起调度器，空闲 N 秒后才触发挂起，活跃期间不挂起
Substrate 层 cooldown：Redis 里记录 last_suspend_time，挂起后 M 秒内拒绝再次挂起
快照 GC：只保留最近 K 个快照，用 GCS lifecycle policy 或自定义 controller 清理
LRU 淘汰：Worker 满时，淘汰最久未使用的 Actor，为新请求腾位置
挂起结果确认：从 fire-and-forget 改为同步等待 + 重试 + 告警
增量快照：启用 gVisor 的 --parent 参数，减少快照体积

作为一个学习对象，这套架构的幂等工作流设计（RunWorkflow + IsComplete 快进）、双层事件日志（Conversation + Execution）、分布式锁 + 乐观并发控制，都值得借鉴。但直接用到生产环境还需要大量的工程补齐。

AI编程工具TokenPlan横评

Tue, 26 May 2026 15:00:00 +0800

AI 编程工具 Token 计划横评

用同一份月度用量，算算 DeepSeek V4 Pro API 直调、opencode Go、Mimo Token Plan 这三种方案到底差多少钱。

TLDR 省流

以个人本月预估用量 538M 为基准：

方案	月费	折算月成本	相对 DS API 倍率	额度覆盖	备注
DeepSeek V4 Pro API	按量	`¥100.34`	1.0x	—	缓存 `¥0.025`/M
opencode Go	`$10`	`$10` / `¥72`	0.72x	✅ `$60` 额度（6 倍杠杆）	⚠️ DS 折扣未同步，同步后等效 token +300%
Mimo API 直调（新价）	按量	`¥100.34`	1.0x	—	🆕 已降至和 DeepSeek 同价
Mimo Token Plan Standard	`¥99`	`¥99`	0.99x	✅ 110 亿积分，用量占 91%	🆕 99 折包月预付
Mimo Token Plan Pro	`¥329`	`¥329`	3.3x	❌ 380 亿积分，用量仅占 26%	用量不足，单价反升
Mimo Token Plan Max	`¥659`	`¥659`	6.6x	❌ 820 亿积分，用量仅占 12%	用量严重不足

结论

Mimo API 和 Token Plan 同时降价，API 降到和 DeepSeek 同价，Token Plan 三档套餐（Standard ¥99 / Pro ¥329 / Max ¥659）
月度用量 538M 换算约 100.34 亿积分，Standard 档 110 亿刚好覆盖（91%），成本从旧 Max ¥659 降到 ¥99，降了 85%
Token Plan ¥99 vs API ¥100.34 = 0.99x（99 折），本质上就是 API 的包月预付版
Pro/Max 满额单价更低（8.7 折/8 折），但当前用量下额度严重过剩，单价反而更高，适合重度用户
opencode Go 仍是最低价选项（¥72），但差距从原来的数量级缩小到了 ¥27

下面是详细计算过程。

用量基准

以下数据来自 20 天的实际使用。由于前期用量偏低，20 天实际用量约占月度的 60%，按比例换算完整月度用量（÷60% ≈ ×1.67）：

类别	20 天实际	折算月用量	占比
缓存命中	307.887 M	513.145 M	95.4%
未命中（输入）	12.323 M	20.539 M	3.8%
输出	2.590 M	4.316 M	0.8%
合计	322.800 M	538.000 M	100%

缓存命中率 96.2%，编程助手场景的常态——项目文件、system prompt 每轮对话都在重复。

定价对比

DeepSeek V4 Pro（25% 永久降价后）

类别	当前单价（¥/M）	降价前
缓存命中	`¥0.025`	`¥0.1`
输入（未命中）	`¥3.00`	`¥12.00`
输出	`¥6.00`	`¥24.00`

缓存价格只有输入价格的 0.83%，命中率从 80% 拉到 96%，输入成本砍一大半。

Mimo v2.5 Pro（🆕 已降价，和 DeepSeek 同价）

类别	当前单价（¥/M）	降价前
缓存命中	`¥0.025`	`¥1.40`
输入（未命中）	`¥3.00`	`¥7.00`
输出	`¥6.00`	`¥21.00`

Mimo API 现在和 DeepSeek 完全同价——缓存、输入、输出三项全部对齐。降价前缓存价差 56 倍，现在是 1:1。

Mimo Token Plan 积分制（🆕 新计费规则）

Token Plan 改用积分制计费，三档套餐：

档位	月费	含积分	满额单价	折扣
Standard	`¥99`	110 亿	`¥0.90`/亿	9 折
Pro	`¥329`	380 亿	`¥0.87`/亿	8.7 折
Max	`¥659`	820 亿	`¥0.80`/亿	8 折

计费规则（每种 token 类型消耗积分不同）：

类别	积分/MTok
缓存命中	2.5 积分
输入（未命中）	300 积分
输出	600 积分

换算月度用量积分：

类别	月用量	× 积分费率	积分
缓存命中	513.145 M	× 2.5	12.83 亿
输入	20.539 M	× 300	61.62 亿
输出	4.316 M	× 600	25.90 亿
合计	538.000 M		100.34 亿

月度用量 100.34 亿积分，Standard 档 110 亿刚好覆盖（用量占 91%）。

验证：加权平均 1 token ≈ 1.867 积分，110 亿 ÷ 1.867 ≈ 589M token，月度 538M 在范围内。✅

折扣计算（以当前用量 100.34 亿积分为基准，API 等价 ¥10/亿积分 = ¥1003.40）：

档位	月费	用量占比	实际单价	相对 API 折扣
Standard	`¥99`	91.2%	`¥0.99`/亿	99 折
Pro	`¥329`	26.4%	`¥3.28`/亿	3.3 折
Max	`¥659`	12.2%	`¥6.57`/亿	6.6 折

当前用量下只有 Standard 划算——Pro/Max 额度过剩，单价反而更高。Pro 适合月用量 200~300 亿、Max 适合 500 亿以上的重度用户。

三个方案分别是什么

DeepSeek V4 Pro 直调 API 最直接的方式，官方或兼容接口调用，按 token 计费，用多少算多少。

opencode Go opencode Go 是个订阅计划，月费 $10（首月 $5），核心玩法是花 $10 买最多 $60 的 API 使用额度，额度按节奏释放：

限制维度	额度
每 5 小时	`$12`
每周	`$30`
每月	`$60`

5 小时最多花 $12，一周最多 $30，连续高强度写代码偶尔会碰到 5 小时上限。模型挺全的：DeepSeek V4 Pro/Flash、MiMo V2.5 Pro、Kimi K2.5/K2.6、GLM-5、Qwen3.5/3.6 Plus 等等，十几个模型随便切。额度用完还能用免费模型续命。

但要注意它的计费倍率：opencode 对 DeepSeek 的计价大约是官方价的 4 倍（零售标价 6x，订阅折后约 4x）。$60 额度 ÷ 4x = 约 $15 的 DeepSeek 官方 API 价值，相对 $10 订阅费是 1.5 倍。当前唯一的问题是 DeepSeek 的 25% 永久折扣还没同步，同步后同样 $60 额度能多用 300% 的 token。issue #28846 里发现的计费差异就是未同步导致的。

如果 opencode 后续同步了 DeepSeek 的 25% 永久折扣，4x 倍率不变但基数变小，同样的 $60 额度能多用 300% 的 token。同步前 $10 ≈ $15 官方 API，同步后 $10 ≈ $60 官方 API，越等越值。

Mimo Token Plan Standard（🆕） Mimo 平台的入门套餐，¥99/月，含 110 亿积分。新的积分制计费规则下，缓存命中只要 2.5 积分/MTok，编程场景 96% 缓存命中率下非常划算。之前这个用量需要 Max 档（¥659，820 亿积分），用量仅占 12%，严重浪费；现在 Standard 档（¥99，110 亿积分）用量占 91%，刚好匹配。

算钱（折算月用量）

以下均按折算月用量 538M 计算。

DeepSeek V4 Pro API / Mimo API（🆕 同价）

类别	计算	花费
缓存命中	513.145M × `¥0.025`	`¥12.83`
输入	20.539M × `¥3.00`	`¥61.62`
输出	4.316M × `¥6.00`	`¥25.90`
合计		`¥100.34`（≈`$13.93`）

Mimo API 降价后和 DeepSeek 完全同价，结果一模一样。

opencode Go

opencode Go $10 月费，$60 月额度，6 倍杠杆。按 4x DeepSeek 官方价计费，$60 额度折合约 $15 的 DeepSeek API 价值。折算月用量 DeepSeek 官方价 $13.93，在 $15 范围内，月费就是 $10（¥72），不会超。

唯一问题是 DeepSeek 25% 折扣还没同步，用的是旧价基数。同步后同样 $60 额度，等效 token +300%（$15 → $60 官方 API 价值）。

Mimo Token Plan Standard（`¥99`）

月度用量换算积分 100.34 亿，Standard 档含 110 亿积分，用量占 91%，有 10% 余量。

对比	Token Plan Standard	API 直调（同价）
月费	`¥99`（固定）	`¥100.34`（按量）
相对 DS API 倍率	0.99x	1.0x
额度覆盖	✅ 110 亿，用量占 91%	—

在当前 96% 缓存命中率下：

Token Plan（¥99）≈ API（¥100.34），倍率 0.99x，几乎持平
Token Plan 是固定月费，API 按量浮动。如果某月缓存命中率下降（比如换了新项目、大量新代码），API 成本会上涨，Token Plan 则锁死 ¥99

本质上 Token Plan 就是 API 的 99 折包月预付版——积分费率完全对齐 DeepSeek 定价（¥10/亿积分），100.34 亿积分值 ¥1003.40，Standard 档卖 ¥99（110 亿积分），按实际用量算刚好 99 折。真正的价值不在折扣，在于固定月费不怕用量波动。

三档套餐怎么选

适合用量范围	推荐档位	月费	按用量单价
~100 亿/月	Standard	`¥99`	99 折
200~300 亿/月	Pro	`¥329`	~1.3 折
500 亿以上/月	Max	`¥659`	~1.3 折

当前用量 100.34 亿/月，Standard 是唯一合理选择。Pro/Max 额度过剩，单价反而更高。

套餐对比（新 vs 旧）

维度	旧方案	新方案	变化
适用套餐	Max（`¥659`，820 亿积分）	Standard（`¥99`，110 亿积分）	降 85%
用量覆盖	12%（严重浪费）	91%（刚好）	精准匹配
vs DS API 倍率	6.6x	0.99x	从 6.6 倍降到持平
折扣	8 折（但用量不足）	99 折（用量刚好）	实际更省

总结

Mimo 降价是最大变化：API 和 DeepSeek 同价，Token Plan 三档套餐，当前用量选 Standard（¥99）比旧 Max（¥659）省 85%
Token Plan 就是 API 的 99 折包月预付版：积分费率完全对齐 DeepSeek 定价（¥10/亿积分），Standard 档 110 亿积分卖 ¥99，按实际用量 100.34 亿算刚好 99 折
三档套餐看用量选：Standard（110 亿）适合 ~~100 亿/月，Pro（380 亿）适合 200~~300 亿/月，Max（820 亿）适合 500 亿以上。额度过剩反而单价更高
按量弹性首选：DeepSeek V4 Pro API 直调，¥100/月，缓存红利吃满
性价比订阅：opencode Go，$10 月费、$60 月额度、6 倍杠杆，折算月用量完全覆盖，倍率仅 0.72x。唯一变数是 DeepSeek 25% 折扣同步进度
Token Plan 的优势在于锁定成本：固定 ¥99/月，不怕缓存命中率波动。如果某月命中率下降，API 按量会涨，Token Plan 不变
缓存是核心变量：命中率 96% 时 Token Plan ≈ API（0.99x），命中率越低 Token Plan 越划算

统计大模型流式响应的token usage

Wed, 15 Apr 2026 15:33:03 +0800

LLM 流式响应的 usage 怎么统计？

以Openai api 为例

现在大模型流式输出应用很广泛了，很多webui 上附加的打字机效果，视觉体验确实好。但是这种场景下咋统计大模型的token 用量

这里简单分享一下个人的拙作。

SSE 响应格式的特点

Server-Sent Events（SSE）是一种基于 HTTP 的轻量级单向实时通信协议。在 OpenAI API 中，流式响应以 SSE 格式传输，每个分块的结构如下：

1

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"...","choices":[{"index":0,"delta":{"content":"某"},"finish_reason":null}]}

关键特点：

每个分块是一行以 data: 开头的文本
最后一个分块固定为 data: [DONE]，标志流结束
分块之间可能穿插空行
响应头中 content-type: text/event-stream，transfer-encoding: chunked

usage 怎么获取

大多数 LLM API（OpenAI、以及各种兼容 API）在开启流式响应时，不会在第一个分块里就把 usage 返回。而是会在流快结束、发送 [DONE] 之前，插一个特殊的分块。这个分块大概长这样：

1

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":11,"completion_tokens":27,"total_tokens":38,"prompt_tokens_details":{"cached_tokens":0}}}

可以看到：

delta 是空的 {}，不是 null
finish_reason 变成了 "stop"
整块的 usage 信息就在这儿

这就是核心：usage 信息不是元数据单独发过来的，而是塞在流结束前的上个分块里。 。

滚动更新缓存

参考： openai chat completes api 文档
既然 usage 必然出现在 [DONE] 之前，只要在收到 [DONE] 时，解析缓存的最后一个分块就行了。

思路：

收到正常分块 → 放进队列，队列满了就踢掉最老的
收到 [DONE] → 队列里的一定有 usage，直接取出来解析

用队列（maxsize=2）来实现，代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


import httpx
import json
import queue


def stream_chat_completion(base_url: str, sk: str, model: str, messages: list):
 """
 流式请求 OpenAI /v1/chat/completions 接口，
 用大小为 2 的队列缓存 SSE 分块，解析 usage。

 Args:
 base_url: API 基础地址
 sk: 模型密钥sk
 model: 模型名称
 messages: 对话消息列表
 """
 url = f"{base_url.rstrip('/')}/v1/chat/completions"

 payload = {
 "model": model,
 "messages": messages,
 "stream": True
 }

 headers = {
 "Content-Type": "application/json",
 "Authorization": f"Bearer {sk}",
 }

 print(f"请求地址: {url}")
 print(f"请求体: {json.dumps(payload, ensure_ascii=False, indent=2)}")
 print("-" * 50)
 print("开始接收 SSE 流:")
 print("-" * 50)

 with httpx.stream(
 "POST",
 url,
 json=payload,
 headers=headers,
 timeout=60.0
 ) as response:
 print(f"状态码: {response.status_code}")
 print(f"响应头: {dict(response.headers)}")
 print("-" * 50)

 # 关键：用队列只保留最近 2 个分块
 records: queue.Queue[str] = queue.Queue(maxsize=2)

 for line in response.iter_lines():
 if line:
 if line.startswith("data:"):
 data = line[5:].strip()
 if data == "[DONE]":
 print("得到 [SSE] 流结束信号: [DONE]")
 try:
 item = records.get()
 parsed = json.loads(item)
 usage = parsed.get("usage", {})
 if usage:
 output_token = usage.get("completion_tokens", 0)
 input_token = usage.get("prompt_tokens", 0)
 cached_token = usage.get("cached_tokens")
 prompt_tokens_details = usage.get(
 "prompt_tokens_details", {}
 ).get("cached_tokens")
 if not cached_token and prompt_tokens_details:
 cached_token = prompt_tokens_details
 print(
 f"[解析后] output_token={output_token}, "
 f"input_token={input_token}, cached_token={cached_token}"
 )
 while not records.empty():
 s = records.get_nowait()
 print(s)
 except json.JSONDecodeError:
 print(f"[解析失败] 无法解析 JSON: {data}")
 else:
 # 队列满了就丢弃旧数据，只保留最新的
 if not records.empty():
 records.get(block=False)
 records.put(data)
 else:
 print(f"[其他] {line}")


if __name__ == "__main__":
 BASE_URL = "https://api.example.com"
 MODEL = "gpt-3.5-turbo"
 MESSAGES = [{"role": "user", "content": "用一句话介绍 Python 3.11"}]
 SK = "your-api-key"

 stream_chat_completion(BASE_URL, SK, MODEL, MESSAGES)

跑一下，大概是这种输出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


请求地址: https://api.example.com/v1/chat/completions
请求体: {
 "model": "gpt-3.5-turbo",
 "messages": [{"role": "user", "content": "用一句话介绍Python 3.11"}],
 "stream": true
}
--------------------------------------------------
开始接收 SSE 流:
--------------------------------------------------
状态码: 200
响应头: {'server': 'openresty', 'content-type': 'text/event-stream', 'transfer-encoding': 'chunked'}
--------------------------------------------------
得到 [SSE] 流结束信号: [DONE]
[解析后] output_token=27, input_token=11, cached_token=0

这样就拿到usage和主要的输入/缓存/输出token 量了，其实还可以顺带统计下api 请求次数，现在很多coding plan 是基于api 调用次数计量的。

其实一个变量就够了

回过头来看，队列大小设成 2 有点多余。

usage 分块是 [DONE] 之前唯一一个 delta 为空的块，而且它和 [DONE] 之间不会再有其他有效数据了。所以我们只需要记住最近收到的那个 data: 行就行，不需要队列。

单变量版：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


last_chunk = None
for line in response.iter_lines():
 if line and line.startswith("data:"):
 data = line[5:].strip()
 if data == "[DONE]":
 if last_chunk:
 usage = json.loads(last_chunk).get("usage", {})
 print(f"input={usage.get('prompt_tokens')}, output={usage.get('completion_tokens')}")
 else:
 last_chunk = data

逻辑是一样的，只是把"最多两个"换成了"就一个"——反正够用。空间复杂度直接从 O(2) 变成 O(1)，虽然实际差别微乎其微，但写出来更干净。

适用场景

想了一下，大概是这么几类场景：

API 代理或网关。转发流的时候想顺便记个 token 用量，没必要把整个响应缓存下来再处理，拿到 usage 直接记了就行。

轻量级 SDK。不想维护一个大的缓冲区，特别是并发量大的时候，内存省一点是一点。

成本统计/监控。实时统计每个请求的消耗，而不是事后去日志里翻。

调试工具。快速跑一个请求，看看某个模型实际消耗了多少 token，做个对比什么的。

基本上，只要你需要在流式响应的同时拿到 usage，而又不打算存完整的流，这个思路都能用。

其实核心就一句话：usage 信息是在 [DONE] 的上个分块里一起过来的。理解这个要点，用一个变量（或两个元素的队列）就能拿到，完全不需要缓存整个流。当然实际开发中怎么用，看你心情。追求简洁就一个变量，想留点冗余空间方便以后加日志就队列，两种写法都行，理解原理最重要。

Claude_mem_prompt

Sat, 28 Feb 2026 13:41:14 +0800

claude mem 提示词总结笔记

年后回来比较忙，今天才有一点时间总结一下假期对claude mem 的上下文管理研究

claude mem 对上下文的管理主要是分成两部分：

总结 summary 让llm 自身对上下文做提炼，获取一个精炼的内容摘要
渐进式检索，通过summary 和会话的id 顺序，获得前后关联内容

summary 部分

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


PROGRESS SUMMARY CHECKPOINT
===========================
Write progress notes of what was done, what was learned, and what's next. This is a checkpoint to capture progress so far. The session is ongoing - you may receive more requests and tool executions after this summary. Write \"next_steps\" as the current trajectory of work (what's actively being worked on or coming up next), not as post-session future work. Always write at least a minimal summary explaining current progress, even if work is still in early stages, so that users see a summary output tied to each request.

Claude's Full Response to User:
${lastAssistantMessage}

Respond in this XML format:
<summary>
 <request>[捕捉用户请求和讨论/完成内容实质的简短标题]</request>
 <investigated>[到目前为止探索了什么？检查了什么？]</investigated>
 <learned>[你了解到了什么工作原理？]</learned>
 <completed>[到目前为止完成了什么工作？发布或更改了什么？]</completed>
 <next_steps>[在此会话中，你正在积极处理或计划接下来处理什么？]</next_steps>
 <notes>[关于当前进度的其他见解或观察]</notes>
</summary>

IMPORTANT! DO NOT do any work right now other than generating this next PROGRESS SUMMARY - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.
Never reference yourself or your own actions. Do not output anything other than the summary content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful summary content.
Thank you, this summary will be very useful for keeping track of our progress!
LANGUAGE REQUIREMENTS: Please write ALL summary content (request, investigated, learned, completed, next_steps, notes) in 中文

可以看到整个提示次的结构可以分成四部分：

意图，也就是目标
待处理内容
输出示例
输出形式约束

上下文管理的相关思考

claude mem 的三级结构

索引，可以理解为字段检索，根据持久化上下文中的元信息
上下文也就是摘要相关的内容
全量的原始会话

目前claude 通过记录和压缩历史上下文，能够让长期项目在会话启动时收益，避免预先加载大量上下文，算是一种瘦身，另外尚有一种在测试的endless 模式，通过拦截替换工具调用的上下文，整理历史会话，避免多轮对话+ 多次工具调用带来的上下文膨胀问题，节省token。

另外可以通过减少工具/tool search/skill 渐进式加载等方式在工程上缓解这个问题，其实子智能体subAgent 通过隔离上下文，可以和上述的技术结合起来改善上下文问题

TODO

学习研究pageindex 的递归树式上下文管理，思考如何在seekdb 这类至少可以支持BM25+向量混合检索的数据库上实现这类模式

Volcano调度器执行分布式任务记录

Mon, 09 Feb 2026 15:30:00 +0800

使用Volcano调度器执行分布式任务记录实践记录

记录下如何使用Volcano调度器运行Ray分布式计算任务，以及使用Kubeflow Training Operator v1（老版本，限制v2 重构了）进行PyTorch模型训练的完整实践。

Ray on Volcano 分布式计算示例

环境准备

在使用Ray on Volcano之前，需要确保：

已安装Volcano调度器的Kubernetes集群
启用Ray插件和svc插件

Volcano Job配置

以下是一个完整的Ray集群部署配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


apiVersion: batch.volcano.sh/v1alpha1
kind: Job
metadata:
 name: ray-distributed-compute
spec:
 minAvailable: 3
 schedulerName: volcano
 plugins:
 ray: [] # 启用Ray插件
 svc: [] # 启用Service插件
 policies:
 - event: PodEvicted
 action: RestartJob
 queue: default
 tasks:
 - replicas: 1
 name: head
 template:
 spec:
 containers:
 - name: head
 image: rayproject/ray:2.9.0-py311-cpu
 command: ["bash", "-c"]
 args:
 - |
 ray start --head --port=6379 && \
 python3 /workspace/distributed_compute.py
 resources:
 requests:
 memory: "4Gi"
 cpu: "2"
 limits:
 memory: "8Gi"
 cpu: "4"
 restartPolicy: OnFailure
 - replicas: 2
 name: worker
 template:
 spec:
 containers:
 - name: worker
 image: rayproject/ray:2.9.0-py311-cpu
 command: ["bash", "-c"]
 args:
 - |
 ray start --address=${RAY_HEAD_IP}:6379
 env:
 - name: RAY_HEAD_IP
 value: "ray-distributed-compute-head-svc"
 resources:
 requests:
 memory: "4Gi"
 cpu: "2"
 limits:
 memory: "8Gi"
 cpu: "4"
 restartPolicy: OnFailure

Ray分布式计算脚本

创建一个简单的分布式计算任务脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


import ray
import time
import numpy as np

# 初始化Ray连接
ray.init(address="auto")

@ray.remote
def compute_task(data_chunk):
 """模拟计算密集型任务"""
 # 模拟一些计算
 result = np.sum(data_chunk ** 2)
 time.sleep(1) # 模拟计算时间
 return result

def distributed_compute():
 """分布式计算示例"""
 print(f"Ray集群资源: {ray.cluster_resources()}")

 # 创建测试数据
 data_size = 1000000
 chunk_size = data_size // 4
 data_chunks = [np.random.random(chunk_size) for _ in range(4)]

 # 并行执行计算任务
 start_time = time.time()

 # 提交任务到Ray集群
 futures = [compute_task.remote(chunk) for chunk in data_chunks]

 # 获取结果
 results = ray.get(futures)

 total_result = sum(results)
 end_time = time.time()

 print(f"计算结果: {total_result}")
 print(f"总耗时: {end_time - start_time:.2f}秒")

 return total_result

if __name__ == "__main__":
 result = distributed_compute()
 print(f"分布式计算完成，结果: {result}")

部署和运行

下述操作可以通过业务代码来自动完成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 应用Volcano Job配置
kubectl apply -f ray-distributed-compute.yaml

# 查看Pod状态
kubectl get pods

# 端口转发访问Ray Dashboard
kubectl port-forward service/ray-distributed-compute-head-svc 8265:8265

# 查看分布式计算日志
kubectl logs -f ray-distributed-compute-head-0

Kubeflow Training Operator v1 PyTorch训练示例

环境准备

确保已安装Kubeflow Training Operator v1，并配置好GPU资源。

ResNet训练脚本

一个简单的ResNet模型训练脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89


import torch
import torch.nn as nn
import torch.optim as optim
import torch.distributed as dist
import torch.multiprocessing as mp
from torch.nn.parallel import DistributedDataParallel as DDP
from torchvision import models, transforms
from torch.utils.data import DataLoader, TensorDataset
import os

def setup(rank, world_size):
 """初始化分布式训练环境"""
 os.environ['MASTER_ADDR'] = 'localhost'
 os.environ['MASTER_PORT'] = '12355'

 # 初始化进程组
 dist.init_process_group("nccl", rank=rank, world_size=world_size)

def cleanup():
 """清理分布式训练环境"""
 dist.destroy_process_group()

def create_dummy_dataset(size=1000):
 """创建虚拟数据集用于演示"""
 # 模拟ImageNet数据 (224x224 RGB图像)
 images = torch.randn(size, 3, 224, 224)
 labels = torch.randint(0, 1000, (size,))
 return TensorDataset(images, labels)

def train(rank, world_size, epochs=5):
 """训练函数"""
 print(f"Running DDP on rank {rank}.")
 setup(rank, world_size)

 # 设置设备
 torch.cuda.set_device(rank)
 device = torch.device(f"cuda:{rank}")

 # 创建模型
 model = models.resnet18(pretrained=False)
 model = model.to(device)
 ddp_model = DDP(model, device_ids=[rank])

 # 创建优化器和损失函数
 optimizer = optim.SGD(ddp_model.parameters(), lr=0.001, momentum=0.9)
 criterion = nn.CrossEntropyLoss()

 # 创建数据加载器
 dataset = create_dummy_dataset()
 sampler = torch.utils.data.distributed.DistributedSampler(
 dataset, num_replicas=world_size, rank=rank
 )
 dataloader = DataLoader(dataset, batch_size=32, sampler=sampler)

 # 训练循环
 ddp_model.train()
 for epoch in range(epochs):
 sampler.set_epoch(epoch)
 epoch_loss = 0.0

 for batch_idx, (data, target) in enumerate(dataloader):
 data, target = data.to(device), target.to(device)

 optimizer.zero_grad()
 output = ddp_model(data)
 loss = criterion(output, target)
 loss.backward()
 optimizer.step()

 epoch_loss += loss.item()

 if batch_idx % 10 == 0 and rank == 0:
 print(f"Epoch {epoch}, Batch {batch_idx}, Loss: {loss.item():.4f}")

 if rank == 0:
 avg_loss = epoch_loss / len(dataloader)
 print(f"Epoch {epoch} 完成，平均损失: {avg_loss:.4f}")

 cleanup()

def main():
 """主函数"""
 world_size = torch.cuda.device_count()
 print(f"使用 {world_size} 个GPU进行训练")

 mp.spawn(train, args=(world_size,), nprocs=world_size, join=True)

if __name__ == "__main__":
 main()

PyTorchJob配置

创建Kubeflow PyTorchJob CR配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


apiVersion: kubeflow.org/v1
kind: PyTorchJob
metadata:
 name: resnet-training
 namespace: kubeflow
 annotations:
 sidecar.istio.io/inject: "false"
spec:
 cleanPodPolicy: None
 pytorchReplicaSpecs:
 Master:
 replicas: 1
 restartPolicy: OnFailure
 template:
 spec:
 containers:
 - name: pytorch
 image: pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime
 command:
 - "python"
 - "/workspace/resnet_train.py"
 volumeMounts:
 - name: workspace
 mountPath: /workspace
 resources:
 requests:
 memory: "16Gi"
 cpu: "4"
 nvidia.com/gpu: 1
 limits:
 memory: "32Gi"
 cpu: "8"
 nvidia.com/gpu: 1
 ports:
 - containerPort: 23456
 name: pytorchjob-port
 Worker:
 replicas: 2
 restartPolicy: OnFailure
 template:
 spec:
 containers:
 - name: pytorch
 image: pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime
 command:
 - "python"
 - "/workspace/resnet_train.py"
 volumeMounts:
 - name: workspace
 mountPath: /workspace
 resources:
 requests:
 memory: "16Gi"
 cpu: "4"
 nvidia.com/gpu: 1
 limits:
 memory: "32Gi"
 cpu: "8"
 nvidia.com/gpu: 1
 ports:
 - containerPort: 23456
 name: pytorchjob-port
 volumes:
 - name: workspace
 emptyDir: {}

部署和监控

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 创建PyTorchJob
kubectl create -f resnet-training.yaml

# 查看Job状态
kubectl get pytorchjobs resnet-training -n kubeflow

# 查看创建的Pod
kubectl get pods -l training.kubeflow.org/job-name=resnet-training -n kubeflow

# 查看训练日志（Master节点）
PODNAME=$(kubectl get pods -l training.kubeflow.org/job-name=resnet-training,training.kubeflow.org/replica-type=master,training.kubeflow.org/replica-index=0 -o name -n kubeflow)
kubectl logs -f ${PODNAME} -n kubeflow

总结

总结一下volcano 和分布式计算运行时其实在业务中和常规k8s job定义的区别还是较少的，这上面两种常见的运行时的计算任务，其实很好转化为业务代码，通过api server 提交业务请求对应的cr 来触发volcano 调度器去创建分布式运行时对应的job

Ray on Volcano：适合通用分布式计算任务，提供了灵活的编程模型和自动扩缩容能力
Kubeflow Training Operator：专为机器学习训练优化，提供了完整的训练作业管理功能

两种方案都可以充分利用Volcano的gang调度能力，确保作业的资源需求得到满足。在实际应用中，可以根据具体需求选择合适的方案。

Vllm deploy

Mon, 09 Feb 2026 10:40:46 +0800

vLLM 部署大模型手册

以Qwen2.5-32B-Instruct 为例子
基本命令：
python3 -m vllm.entrypoints.openai.api_server --trust-remote-code --enable-prefix-caching --disable-log-requests --model /data --gpu-memory-utilization 0.90 -tp 8 --port 8000 --served-model-name Qwen2.5-32B-Instruct --max-model-len 32768

vLLM常见参数配置说明

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


--model 挂载模型目录（与【挂载地址】保持一致）
-tp 卡数（部署模型需要几张卡就写几张）
--port 端口（默认8000即可）
--max-model-len 最大上下文长度
--served-model-name 模型名称
--gpu-memory-utilization 0.90
--max_num_seqs batch 里面的最大输入序列个数
--enforce_eager 禁用图捕获优化参数，能节省一些显存
--pipeline_parallel_size 一般是多节点部署时，按照这个参数去拆分模型层，多个节点构成流水线，但是会增加延迟
--max_num_batched_tokens = batch_size * max_model_len， 是一个batch 中总的token 数
--enable_expert_parallel 对部分MOE 专家模型，启用专家并行
--kv-transfer-config '{"kv_connector":"MooncakeConnector","kv_role":"kv_consumer"}' 安装mooncake-transfer-engine 可以通过多级缓存和RDMA 来加速kv cache 传输，优化推理
-dcp 这个计算公式是 tp数/（kv 头数*节点数） ，可以保持同个节点上不会重复载入
注：预估 tp 的值（卡数），简单预算公式（单位GB）：模型文件总大小 * 1.2 <= GPU显存大小

多节点部署

mp 运行时

1
2
3
4
5
6


# master 节点
python3 -m vllm.entrypoints.openai.api_server --trust-remote-code --enable-prefix-caching --disable-log-requests --model /data --gpu-memory-utilization 0.90 -tp 2 --port 8000 --served-model-name Qwen2.5-32B-Instruct # 注意下面这几行 
--nnodes 2 \
--node-rank 0 \ # 不同节点这个就这个rank 数不同，master 用0 
--master-addr 192.168.0.101 \
--distributed-executor-backend mp

ray 计算后端

1
2
3
4
5
6
7
8


# 首先，先在master 节点
ray start --head --port=6379
# 然后其他worker 节点
ray start --address=${master_ip}:6379
# 这时候ray 集群通信就建立起来了
python3 -m vllm.entrypoints.openai.api_server --trust-remote-code --enable-prefix-caching --disable-log-requests --model /data --gpu-memory-utilization 0.90 --port 8000 -tp 8 --pipeline-parallel-size 2 --served-model-name Qwen2.5-32B-Instruct \ 
# 注意下面这个
--distributed-executor-backend ray

使用vllm 的示例脚本简化上述过程

1
2
3
4
5


# master
bash /vllm-workspace/examples/online_serving/multi-node-serving.sh leader --ray_cluster_size=2
python3 -m vllm.entrypoints.openai.api_server --trust-remote-code --enable-prefix-caching --disable-log-requests --model /data --gpu-memory-utilization 0.90 --port 8000 -tp 8 --pipeline-parallel-size 2 --served-model-name Qwen2.5-32B-Instruct
# worker
bash /vllm-workspace/examples/online_serving/multi-node-serving.sh worker --ray_cluster_size=2

Volcano 分布式任务编排

其实Volcano 本质上是对不同分布式任务运行时的编排调度管理工具，所以按照上面两种分布式运行时后端，创建job 时适配command 命令就行，volcano 会按照工作组做资源分配管理
参照 Volcano Kthena 在 Kubernetes 上部署多节点LLM推理

HAMI 虚拟化原理与资源超卖机制

Thu, 29 Jan 2026 11:00:00 +0800

HAMI 虚拟化原理与资源超卖机制

HAMI（HAMi）是一个开源的 vGPU 方案，本文从调度器原理、资源超卖两个方面做个总结。

一、调度器原理

1.1 架构概述

Hami-scheduler 采用 Scheduler Extender 机制实现，而非直接扩展 default-scheduler：

使用默认 kube-scheduler 镜像启动服务，通过配置将调度器名称指定为 hami-scheduler
为该调度器配置 Extender，Extender 服务由同一 Pod 中的另一个 Container 启动的 HTTP 服务提供

1.2 部署架构

1
2
3
4
5


Deployment (kube-system/vgpu-hami-scheduler)
├── Container 1: kube-scheduler（原生调度器）
│ └── 使用 KubeSchedulerConfiguration 配置 Extender
└── Container 2: vgpu-scheduler-extender（HAMi 调度逻辑）
 └── 提供 /filter 和 /bind HTTP 接口

1.3 关键配置

KubeSchedulerConfiguration 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


profiles:
- schedulerName: hami-scheduler
extenders:
- urlPrefix: "https://127.0.0.1:443"
 filterVerb: filter  # 对应 /filter 接口
 bindVerb: bind  # 对应 /bind 接口
 nodeCacheCapable: true
 weight: 1
 httpTimeout: 30s
 enableHTTPS: true
 tlsConfig:
 insecure: true
 managedResources:
 - name: nvidia.com/vgpu
 ignoredByScheduler: true
 # ... 其他 vGPU 相关资源

managedResources 作用：

指定 HAMi 管理的资源类型（nvidia.com/vgpu、nvidia.com/gpumem 等）
ignoredByScheduler: true 表示原生调度器忽略这些资源，完全由 Extender 处理
只有 Pod 申请了这些资源时，调度器才会请求 Extender

1.4 资源感知机制

1.4.1 感知节点上的 GPU 资源信息

HAMi 通过 Node Annotations 获取 GPU 信息：

1
2


# Node Annotation 示例
hami.io/node-nvidia-register: 'GPU-03f69c50-207a-2038-9b45-23cac89cb67d,10,46068,100,NVIDIA-NVIDIA A40,0,true:...'

格式解析：GPU-ID,索引,显存(MB),核心数,厂商型号,NUMA节点,健康状态

数据来源：

DevicePlugin 中的后台 Goroutine 定时上报并写入 Node Annotations
Scheduler 通过 RegisterFromNodeAnnotations() 方法定时（每 15 秒）从 Annotations 解析 GPU 信息

1.4.2 感知节点上 GPU 使用情况

通过 Informer 机制 Watch Pod 和 Node 变化：

1
2
3
4
5
6


// Pod 事件处理
informer.AddEventHandler(cache.ResourceEventHandlerFuncs{
 AddFunc: s.onAddPod,
 UpdateFunc: s.onUpdatePod,
 DeleteFunc: s.onDelPod,
})

从 Pod Annotations 解析 GPU 使用情况：

1
2


# Pod Annotation 示例
hami.io/vgpu-devices-allocated: 'GPU-03f69c50-207a-2038-9b45-23cac89cb67d,NVIDIA,3000,30:;'

格式解析：GPU-UUID,设备类型,已用显存(MB),已用核心百分比

1.5 调度核心算法

1.5.1 Filter 接口（节点过滤与打分）

流程：

1
2
3
4


1. 检查 Pod 是否申请 vGPU 资源 → 未申请则返回全部节点
2. 获取所有节点的 GPU 使用情况 (getNodesUsage)
3. 计算每个节点的得分 (calcScore)
4. 选择得分最高的节点进行调度

得分计算算法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// pkg/scheduler/policy/node_policy.go
func (ns *NodeScore) ComputeScore(devices DeviceUsageList) {
 // 统计已使用资源
 used, usedCore, usedMem := int32(0), int32(0), int32(0)
 for _, device := range devices.DeviceLists {
 used += device.Device.Used
 usedCore += device.Device.Usedcores
 usedMem += device.Device.Usedmem
 }

 // 统计总资源
 total, totalCore, totalMem := int32(0), int32(0), int32(0)
 for _, deviceLists := range devices.DeviceLists {
 total += deviceLists.Device.Count
 totalCore += deviceLists.Device.Totalcore
 totalMem += deviceLists.Device.Totalmem
 }

 // 计算得分：资源使用率越高，得分越高
 useScore := float32(used) / float32(total)
 coreScore := float32(usedCore) / float32(totalCore)
 memScore := float32(usedMem) / float32(totalMem)

 ns.Score = float32(Weight) * (useScore + coreScore + memScore)
}

核心逻辑： 节点上 GPU Core 和 GPU Memory 资源剩余越少，得分越高（Binpack 策略）。

1.5.2 Bind 接口（完成调度）

核心逻辑： 调用 Kubernetes API 创建 Binding 对象将 Pod 绑定到目标节点

1
2
3
4
5


binding := &corev1.Binding{
 ObjectMeta: metav1.ObjectMeta{Name: args.PodName, UID: args.PodUID},
 Target: corev1.ObjectReference{Kind: "Node", Name: args.Node},
}
err = s.kubeClient.CoreV1().Pods(args.PodNamespace).Bind(context.Background(), binding, ...)

1.6 内存数据结构

1
2
3
4
5


type Scheduler struct {
 nodes map[string]*util.NodeInfo // 节点 GPU 信息缓存
 cachedstatus map[string]*NodeUsage // 节点资源使用情况
 overviewstatus map[string]*NodeUsage // 全局节点概览
}

二、资源超卖机制

2.1 超卖配置参数

参数	默认值	超卖场景
`device-memory-scaling`	1.0	显存超卖（如设为 1.5 表示 100GB 可虚拟出 150GB）
`device-cores-scaling`	1.0	核心超卖（如设为 1.5 表示 100% 核心可虚拟出 150%）

2.2 资源充足情况

场景： 节点有足够的物理 GPU 资源满足 Pod 需求

处理方式：

正常计算节点得分
根据 Binpack 策略选择得分最高（资源利用率最高）的节点
Pod 分配到目标节点后，Device Plugin 进行资源绑定

调度流程：

1

Pod 申请资源 → Filter 阶段计算得分 → 选择得分最高节点 → Bind 阶段绑定 → Device Plugin 分配

2.3 资源不足情况

场景： 节点剩余资源无法完全满足 Pod 需求

处理方式：

场景	处理方式
资源充足	正常计算得分，选择得分最高（资源利用率最高）的节点
资源不足	`fitInDevices()` 判断节点剩余资源是否满足 Pod 需求，不满足则忽略该节点
所有节点都不满足	返回错误：“no available node, all node scores do not meet”

核心判断逻辑（伪代码）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


func fitInDevices(node *NodeUsage, request ResourceRequest) bool {
 // 检查显存是否满足
 if node.AvailableMem < request.Memory {
 return false
 }
 // 检查核心是否满足
 if node.AvailableCores < request.Cores {
 return false
 }
 // 检查设备数量是否满足
 if node.AvailableDevices < request.DeviceCount {
 return false
 }
 return true
}

2.4 显存超卖原理

当 device-memory-scaling > 1.0 时启用显存超卖：

注册阶段：将物理显存按比例放大写入 Node Annotations

1
2


实际显存: 46068 MB
缩放后显存: 46068 * 1.5 = 69102 MB

调度阶段：按虚拟显存进行调度，允许调度总量超过物理显存
运行时限制：通过 libvgpu.so 拦截 CUDA 内存分配请求
- 环境变量 CUDA_DEVICE_MEMORY_LIMIT_* 设置显存上限
- 超额部分通过共享缓存文件（CUDA_DEVICE_MEMORY_SHARED_CACHE）模拟

2.4.1 运行时显存分配失败处理机制

当 Pod 在 limit 配额内申请更多显存，但整个 GPU 已经没有余下可用显存时，HAMi-core 通过以下机制处理，类似应用接收到显存分配失败异常，而不是被OOM Kill：

1. 内存分配拦截与检查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// libvgpu/cuda_memory.c - cuMemAlloc_v2_hook
CUresult cuMemAlloc_v2_hook(CUdeviceptr *dptr, size_t bytesize)
{
 log_debug("Intercepted cuMemAlloc_v2: size=%zu", bytesize);

 // 检查内存限制
 if (check_memory_limit(bytesize) != 0) {
 log_error("Memory allocation exceeds limit: %zu bytes", bytesize);
 return CUDA_ERROR_OUT_OF_MEMORY;
 }

 // 调用真实的 cuMemAlloc
 CUresult result = cuMemAlloc_v2_real(dptr, bytesize);

 if (result == CUDA_SUCCESS) {
 // 更新内存使用统计
 update_memory_usage(bytesize);
 // 记录分配信息
 record_allocation(*dptr, bytesize);
 }

 return result;
}

2. 共享内存协调机制

HAMi-core 使用共享内存实现多进程间的内存使用统计和协调：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// libvgpu/cuda_shm.c - 共享内存结构
struct shm_info {
 size_t memory_limit; // 内存限制（来自环境变量）
 size_t used_memory; // 当前已使用内存
 int process_count; // 进程计数
 pid_t process_pids[MAX_PROCESSES]; // 进程PID数组
 size_t process_memory[MAX_PROCESSES]; // 每个进程的内存使用
};

// 检查内存限制
int check_memory_limit(size_t size)
{
 struct shm_info info;

 // 从共享内存获取当前内存使用情况
 if (get_shm_info(&info) != 0) {
 return -1;
 }

 // 检查是否超过限制
 if (info.used_memory + size > info.memory_limit) {
 log_error("Memory limit exceeded: %zu + %zu > %zu",
 info.used_memory, size, info.memory_limit);
 return -1;
 }

 return 0;
}

3. 处理流程总结

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


┌─────────────────────────────────────────────────────────────────┐
│ 显存分配失败处理流程 │
├─────────────────────────────────────────────────────────────────┤
│ 1. CUDA 应用调用 cudaMalloc() │
│ └── 被 libvgpu.so 拦截 │
│ │
│ 2. 检查内存限制 (check_memory_limit) │
│ ├── 从共享内存读取当前使用量 │
│ ├── 检查是否超过 CUDA_DEVICE_MEMORY_LIMIT_* │
│ └── 如果超过，返回 CUDA_ERROR_OUT_OF_MEMORY │
│ │
│ 3. 如果未超过限制，调用真实 cuMemAlloc() │
│ ├── 成功 → 更新共享内存使用统计 │
│ └── 失败 → 返回 CUDA_ERROR_OUT_OF_MEMORY │
│ │
│ 4. CUDA 错误处理 │
│ ├── 记录错误日志（当前使用量、限制值） │
│ ├── 触发 OOM 处理函数 │
│ └── 尝试清理缓存（如果有） │
│ │
│ 5. 应用程序收到 CUDA_ERROR_OUT_OF_MEMORY │
│ └── 应用程序自行处理 OOM（如释放内存、降低 batch size 等） │
└─────────────────────────────────────────────────────────────────┘

2.5 核心超卖原理

当 device-cores-scaling > 1.0 时启用核心超卖：

配置方式：设置 CUDA_DEVICE_SM_LIMIT 环境变量限制 SM 使用比例
1 2

物理核心: 100% 缩放后虚拟核心: 150%
实现原理：通过 libvgpu.so 周期性采样和限制
- 采样周期内如果 SM 利用率超过限制，则触发限流
- recentKernel 和 lastKernelTime 用于平滑超卖场景下的资源分配

2.6 调度策略配置

节点选择策略（通过 Annotations 配置）：

hami.io/node-scheduler-policy: 节点级调度策略（binpack / spread）
hami.io/gpu-scheduler-policy: GPU 级调度策略（binpack / spread）

策略	说明
binpack	优先将 Pod 调度到资源使用率高的节点，减少碎片
spread	优先将 Pod 调度到资源使用率低的节点，提高容错

三、调度流程总结

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


┌─────────────────────────────────────────────────────────────────────┐
│ HAMI 调度器工作流程 │
├─────────────────────────────────────────────────────────────────────┤
│ 1. 用户创建 Pod 并申请 vGPU 资源 │
│ │
│ 2. Webhook 修改 SchedulerName 为 hami-scheduler │
│ │
│ 3. hami-scheduler 接收调度请求 │
│ ├── 获取 Node Annotations → 解析 GPU 资源总量 │
│ ├── 获取 Pod Annotations → 解析 GPU 使用量 │
│ └── 计算各节点剩余可用资源 │
│ │
│ 4. Filter 阶段： │
│ ├── fitInDevices() 检查资源是否满足 │
│ ├── 根据资源使用率计算得分（Binpack/Spread） │
│ └── 选择得分最高的节点 │
│ │
│ 5. Bind 阶段：将 Pod 绑定到目标节点 │
│ │
│ 6. Kubelet 启动 Pod，Device Plugin 进行资源绑定 │
│ ├── 设置 NVIDIA_VISIBLE_DEVICES（原生逻辑） │
│ ├── 挂载 libvgpu.so，设置资源限制环境变量（HAMi 逻辑） │
│ └── libvgpu.so 运行时拦截 CUDA API 实现资源隔离 │
└─────────────────────────────────────────────────────────────────────┘

四、关键环境变量汇总

环境变量	作用
`NVIDIA_VISIBLE_DEVICES`	指定容器可见的 GPU 设备
`CUDA_DEVICE_MEMORY_LIMIT_*`	限制对应 GPU 的显存使用量
`CUDA_DEVICE_SM_LIMIT`	限制 GPU 核心（SM）使用比例
`CUDA_DEVICE_MEMORY_SHARED_CACHE`	共享内存缓存文件路径
`CUDA_OVERSUBSCRIBE`	启用显存超额订阅
`CUDA_DISABLE_CONTROL`	禁用 libvgpu.so 控制（跳过 ld.so.preload 替换）
`CoreLimitSwitch`	是否关闭算力限制

五、总结

HAMI vGPU 方案的核心设计要点：

调度器层：采用 Extender 机制实现调度逻辑，根据节点资源使用率进行打分和选择
资源超卖：通过 device-memory-scaling 和 device-cores-scaling 参数启用，配合 libvgpu.so 实现运行时隔离
核心隔离：依赖 libvgpu.so 拦截 CUDA API，通过环境变量控制显存和核心使用上限

Docker push unauthorized

Wed, 14 Jan 2026 13:29:25 +0800

记录一次harbor 镜像报错失败的定位流程

问题背景:
在通过docker client 库向harbor 仓库推送一个28G 左右的镜像时，会遇到推送到100% 左右出现unauthorized: unauthorized to access repository: project_name/repo_name 的报错，导致整个job 失败，然后出现重试，导致业务层面看到push 进度从100%–> 0% 的奇怪现象

搜索与llm

llm 提示要检查nginx 转发配置和认证的token 配置的有效时间；
搜索到的绝大多数解决方法都是 login 一下

这两者中：

比较符合项目上出现的情况，因为是有成功过的推送过程的，近似于超时
离得比较远了，而且确认过鉴权正常

翻找harbor issue

Can’t push large image if the process takes more then 30 min - unauthorized to access repository
harbor push 30min超时，出现unauthorized: unauthorized to access repository
这是原issue 连接，有相应的解决方法如下

这里对应我们业务的影响其实是会话有效时间，貌似harbor 需要在一个鉴权后的会话中完成镜像的推送流程

结论

在harbor web 管理页中修改了系统配置的会话有效时间解决了这个问题

HAMI vgpu monitor 解析：（二）

Fri, 09 Jan 2026 18:14:42 +0800

从HAMi vGPU Monitor 排错开始

近期项目中hami vgpu monitor 的vgpu 利用率一直获取为0，但是节点上的物理卡nvidia-smi 利用率为100% 附近，两者显然是冲突的，下面是排查的过程，包括一些工具脚本的开发

解析cache 文件

从上一篇指定vgpu monitor 获取的数据源是一个mmap 创建的内存映射cache文件，我们从hami pkg monitor 中截取一部分代码，用来作为一个hami cache 文件解析的工具，代码主要如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102


//go:build linux
// +build linux

package main

import (
 "flag"
 "fmt"
 v1 "hami_tool/v1"
 "os"
 "syscall"
)

type UsageInfo v1.Spec

type ContainerUsage struct {
 PodUID string
 ContainerName string
 data []byte
 Info v1.Spec
}

func readCacheFile(cacheFile string) (*ContainerUsage, error) {
 // 1. 打开文件（只读模式）
 f, err := os.OpenFile(cacheFile, os.O_RDONLY, 0666)
 if err != nil {
 return nil, fmt.Errorf("打开缓存文件失败: %w", err)
 }
 defer func() {
 _ = f.Close()
 fmt.Printf("已关闭文件：%s\n", cacheFile)
 }()

 // 2. 获取文件信息（大小）
 info, err := f.Stat()
 if err != nil {
 return nil, fmt.Errorf("获取文件信息失败: %w", err)
 }
 fileSize := info.Size()
 if fileSize == 0 {
 return nil, fmt.Errorf("缓存文件为空：%s", cacheFile)
 }
 fmt.Printf("缓存文件大小：%d 字节\n", fileSize)

 // 3. mmap映射文件（仅读取）
 mmapData, err := syscall.Mmap(
 int(f.Fd()),
 0,
 int(fileSize),
 syscall.PROT_READ,
 syscall.MAP_SHARED,
 )
 if err != nil {
 return nil, fmt.Errorf("mmap映射文件失败: %w", err)
 }
 // 确保mmap内存最终会释放（无论解析是否成功）
 defer func() {
 if err := syscall.Munmap(mmapData); err != nil {
 fmt.Printf("释放mmap内存失败: %v\n", err)
 } else {
 fmt.Printf("已释放mmap内存，长度：%d\n", len(mmapData))
 }
 }()

 // 4. 深拷贝mmap数据到新的字节切片（核心修改）
 dataCopy := make([]byte, len(mmapData))
 copy(dataCopy, mmapData) // 将mmap内存的数据复制到新内存

 // 5. 用拷贝后的数据解析（此时解析结果不再依赖mmap内存）
 fmt.Printf("casting......v1\n")
 usage := &ContainerUsage{}
 usage.Info = v1.CastSpec(dataCopy)

 // 6. 返回解析结果（仅保留Info，mmap内存会在defer中释放）
 return usage, nil
}

func main() {
 // 1. 解析命令行参数
 var cacheFile string
 flag.StringVar(&cacheFile, "f", "", "缓存文件路径（必填）")
 flag.Parse()

 // 2. 校验参数
 if cacheFile == "" {
 fmt.Printf("必须通过 -f 参数指定缓存文件路径")
 flag.Usage() // 打印用法
 os.Exit(1)
 }

 // 3. 核心逻辑：一次性读取并解析mmap文件
 usage, err := readCacheFile(cacheFile)
 if err != nil {
 fmt.Printf("处理缓存文件失败: %v", err)
 os.Exit(1)
 }
 for i, proc := range usage.Info.GetProcs() {
 fmt.Printf(" %d proc hostpid [%d] pid [%d] util [%d] mem [%d]", i, proc.GetHostPid(), proc.GetPid(), proc.GetUtil(), proc.GetMemUtil())

 }

}

v1 的核心定义如下，基本上是nvidia v1 里面spec 定义稍微修改了点

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112



package v1

import "unsafe"

const maxDevices = 16

type deviceMemory struct {
 contextSize uint64
 moduleSize uint64
 bufferSize uint64
 offset uint64
 total uint64
 unused [3]uint64
}

type deviceUtilization struct {
 decUtil uint64
 encUtil uint64
 smUtil uint64
 unused [3]uint64
}

type ShrregProcSlotT struct {
 pid int32
 hostpid int32
 used [16]deviceMemory
 monitorused [16]uint64
 deviceUtil [16]deviceUtilization
 status int32
 unused [3]uint64
}

func (s ShrregProcSlotT) GetHostPid() int32 {
 return s.hostpid
}

func (s ShrregProcSlotT) GetPid() int32 {
 return s.pid
}

func (s ShrregProcSlotT) GetMemUtil() uint64 {
 for _, val := range s.monitorused {
 if val > 0 {
 return val
 }
 }
 return 0
}

func (s ShrregProcSlotT) GetUtil() uint64 {
 for _, device := range s.deviceUtil {
 if device.smUtil > 0 {
 return device.smUtil
 }
 }
 return 0
}

type uuid struct {
 uuid [96]byte
}

type semT struct {
 sem [32]byte
}

type SharedRegionT struct {
 initializedFlag int32
 majorVersion int32
 minorVersion int32
 smInitFlag int32
 ownerPid uint32
 sem semT
 num uint64
 uuids [16]uuid

 limit [16]uint64
 smLimit [16]uint64
 procs [1024]ShrregProcSlotT

 procnum int32
 utilizationSwitch int32
 recentKernel int32
 priority int32
 lastKernelTime int64
 unused [4]uint64
}

type Spec struct {
 sr *SharedRegionT
}



func CastSpec(data []byte) Spec {
 return Spec{
 sr: (*SharedRegionT)(unsafe.Pointer(&data[0])),
 }
}


func (s Spec) GetProcs() []ShrregProcSlotT {
 ret := []ShrregProcSlotT{}
 for _, proc := range s.sr.procs {
 if proc.hostpid != 0 && proc.pid != 0 {
 ret = append(ret, proc)
 }

 }
 return ret
}

这里我是手动确认了项目中cache 格式是符合v1 格式的，于是只做了v1 格式的解析工具使用如下 ./hami_cache -f e38008ef-62e3-4400-8d87-dab22aaff197.cache 后者就是从环境中拷贝出来的cache 文件

目前可以确认cache 拿到的就是util 0 ，这时观察到hostpid 和pid 相等，怀疑是hostpid 到pid 映射失败，Hami core 只拿到容器内pid 的接下来，需要在Hami 管理的容器中去尝试通过相同逻辑获取使用率，确认最终问题

容器内获取util demo

这里用的是nvidia-ml-py 这个nvml 的python 绑定，hami core 通过libvgpu.so 注入劫持了nvml 的直接调用，所以通过nvml 的python binding库搭配脚本，可以避开编译调试的复杂性，测试如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56



from contextlib import contextmanager
import time
import pynvml

@contextmanager
def _nvml():
 try:
 pynvml.nvmlInit()
 yield
 finally:
 pynvml.nvmlShutdown()

def gettimeofday_microsec():
 """
 纯Python实现：获取当前Unix微秒时间戳（向前偏移1秒）
 功能等价于原C代码+ctypes封装的逻辑，无任何C依赖
 """
 # 获取当前时间的秒数和微秒数（等价于C的gettimeofday）
 # time.time() 返回浮点数，单位为秒，精度到微秒级
 current_time = time.time()

 # 拆分出秒数和微秒数
 tv_sec = int(current_time) # 整数部分：秒数
 tv_usec = int((current_time - tv_sec) * 1000000) # 小数部分转微秒

 # 核心逻辑：向前偏移1秒（和原代码一致，避免秒数为0时出现负数）
 sec = tv_sec - 1 if tv_sec > 0 else 0

 # 计算最终的微秒级时间戳
 microsec = sec * 1000 * 1000 + tv_usec
 return microsec



@_nvml()
def debug():
 gpu_num:int=pynvml.nvmlDeviceGetCount()
 for i in range(gpu_num):
 handle = pynvml.nvmlDeviceGetHandleByIndex(i)
 procs = pynvml.nvmlDeviceGetComputeRunningProcesses(handle)
 for proc in procs:
 name = pynvml.nvmlSystemGetProcessName(proc.pid)
 memory = proc.usedGpuMemory // (1024**2)
 util = pynvml.nvmlDeviceGetUtilizationRates(handle)
 microsec = gettimeofday_microsec()
 hami_sm_utils = pynvml.nvmlDeviceGetProcessUtilization(handle,microsec)
 print(f"pid {proc.pid} name {name} mem {memory} util {util.gpu}")
 for hami_util in hami_sm_utils:
 sm_util = hami_util.sm_util
 print(f"hami pid {hami_util.pid} {sm_util}")



if __name__ == "__main__":
 debug()

这里主要是观察hami 通过pynvml.nvmlDeviceGetProcessUtilization 拿到的设备sm util 的过程来模拟其源码中定时获取监控数据的更新逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 // Get SM util for container
 int processes_num=0;
 nvmlDevice_t device;
 // 获取一秒间隔中的利用率采样数据
 gettimeofday(&cur,NULL);
 microsec = (cur.tv_sec - 1) * 1000UL * 1000UL + cur.tv_usec;
 nvmlProcessUtilizationSample_t processes_sample[SHARED_REGION_MAX_PROCESS_NUM];
 unsigned int processes_num = SHARED_REGION_MAX_PROCESS_NUM;
 res = nvmlDeviceGetProcessUtilization(device,processes_sample,&processes_num,microsec);
 if (res == NVML_SUCCESS) {
 for (i=0; i<processes_num; i++){
 proc = find_proc_by_hostpid(processes_sample[i].pid);
 if (proc != NULL){
 sum += processes_sample[i].smUtil;
 proc->device_util[cudadev].sm_util = processes_sample[i].smUtil;
 }
 }
 }

运行结果如下

可以看到这中间的冲突是hostpid 在节点上是36103 和上一步拿到写在cache 中的hostpid 1082 完全不等，那这个猜想合理么？

hami core 映射proc 和hostpid 的源码

1
2
3
4
5
6
7
8


shrreg_proc_slot_t *find_proc_by_hostpid(int hostpid) {
 int i;
 for (i=0;i<region_info.shared_region->proc_num;i++) {
 if (region_info.shared_region->procs[i].hostpid == hostpid)
 return &region_info.shared_region->procs[i];
 }
 return NULL;
}

可以看到就是凭借一个hostpid 相等来定位的，但是按照cache 中解析的那样，容器中hami core 错误将hostpid 和pid 弄成一个数了，目前还没想到好办法来解决，因为节点上会存在多卡情况，一个proc 可能存在多个卡上，用nvmlDeviceGetUtilizationRates 不能完全满足需求

HAMI vgpu monitor 解析：（一）

Thu, 08 Jan 2026 11:23:12 +0800

HAMI vGPU Monitor 原理解析笔记

hami 目前是一个很火的云原生基金会的开源项目，最早是第四范式推出的，通过动态库劫持来实现显存和核心切分

监控整体架构

hami 的监控分成两个部分，一个是vgpu monitor ，通过在节点上按固定间隔从mmap cache 文件来跨进程获取device plugin 设备插件提供的监控数据，整个mmap 映射区域是按照自定义的二进制序列化协议来存取的，相当高效，在vgpu monitor 这边是提供了一个metrics 端点，可以从节点上直接curl 查看实时的metrics 数据，所以这部分逻辑还是相当简单的，主要是从设备插件那边获取动态的vgpu 使用率和显存使用量，所以重点还是分析设备插件这块

nvidia-device-plugins 项目 https://github.com/Project-HAMi/HAMi-core.git

核心数据结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


// CUDA_DEVICE_MAX_COUNT 表示一个节点上最多的卡数 16

// 使用率
typedef struct {
 uint64_t dec_util;
 uint64_t enc_util;
 uint64_t sm_util; // sm 核心使用率
 uint64_t unused[3];
} device_util_t;

// pod 监控信息结构
typedef struct {
 int32_t pid;
 int32_t hostpid;
 device_memory_t used[CUDA_DEVICE_MAX_COUNT]; // 显存分配信息，对监控没啥用，但是是实现共享显存的基础
 uint64_t monitorused[CUDA_DEVICE_MAX_COUNT]; // 显存用量字节
 device_util_t device_util[CUDA_DEVICE_MAX_COUNT]; // 存储sm 核心使用率
 int32_t status; // GPU 状态
 uint64_t unused[3];
} shrreg_proc_slot_t;


typedef struct {
 int32_t initialized_flag;
 uint32_t major_version;
 uint32_t minor_version;
 int32_t sm_init_flag;
 size_t owner_pid;
 sem_t sem;
 uint64_t device_num;
 uuid uuids[CUDA_DEVICE_MAX_COUNT];
 uint64_t limit[CUDA_DEVICE_MAX_COUNT];
 uint64_t sm_limit[CUDA_DEVICE_MAX_COUNT];
 shrreg_proc_slot_t procs[SHARED_REGION_MAX_PROCESS_NUM]; //一个节点上最多支持的vgpu 负载1024个
 int proc_num;
 int utilization_switch;
 int recent_kernel;
 int priority;
 uint64_t last_kernel_time;
 uint64_t unused[4];
} shared_region_t;

初始化逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 // 跨进程共享的mmap 文件路径
 char* shr_reg_file = getenv(MULTIPROCESS_SHARED_REGION_CACHE_ENV);
 if (shr_reg_file == NULL) {
 shr_reg_file = MULTIPROCESS_SHARED_REGION_CACHE_DEFAULT;
 }

 int fd = open(shr_reg_file, O_RDWR | O_CREAT, 0666);
 if (fd == -1) {
 LOG_ERROR("Fail to open shrreg %s: errno=%d", shr_reg_file, errno);
 }
 region_info.fd = fd;
 // .. 做一些操作尝试写入，确保对象可写

 region_info.shared_region = (shared_region_t*) mmap(
 NULL, SHARED_REGION_SIZE_MAGIC,
 PROT_WRITE | PROT_READ, MAP_SHARED, fd, 0);

这里的 SHARED_REGION_SIZE_MAGIC 其实就是预定义的shared_region_t 字节数核心结构是shrreg_proc_slot_t ，申请共享内存时，一个节点上最多16张卡，最多1024 个任务负载，这些负载需要记录节点上的多卡vgpu 监控数据所以需要有16 个device_util 和monitorused ，另一个device_memory_t 是在不同卡上的显存分配信息

核心获取逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


int get_used_gpu_utilization(int *userutil,int *sysprocnum) {
 struct timeval cur;
 size_t microsec;

 int i;
 unsigned int infcount;
 nvmlProcessInfo_v1_t infos[SHARED_REGION_MAX_PROCESS_NUM];

 unsigned int nvmlCounts;
 CHECK_NVML_API(nvmlDeviceGetCount(&nvmlCounts));
 lock_shrreg();

 int devi,cudadev;
 for (devi=0;devi<nvmlCounts;devi++){
 uint64_t sum=0;
 infcount = SHARED_REGION_MAX_PROCESS_NUM;
 shrreg_proc_slot_t *proc;
 cudadev = nvml_to_cuda_map((unsigned int)(devi));
 if (cudadev<0)
 continue;
 userutil[cudadev] = 0;
 nvmlDevice_t device;
 CHECK_NVML_API(nvmlDeviceGetHandleByIndex(cudadev, &device));

 //Get Memory for container
 nvmlReturn_t res = nvmlDeviceGetComputeRunningProcesses(device,&infcount,infos);
 if (res == NVML_SUCCESS) {
 for (i=0; i<infcount; i++){
 proc = find_proc_by_hostpid(infos[i].pid);
 if (proc != NULL){
 // 这里是显存用量
 proc->monitorused[cudadev] = infos[i].usedGpuMemory;
 }
 }
 }
 // Get SM util for container
 gettimeofday(&cur,NULL);
 microsec = (cur.tv_sec - 1) * 1000UL * 1000UL + cur.tv_usec;
 nvmlProcessUtilizationSample_t processes_sample[SHARED_REGION_MAX_PROCESS_NUM];
 unsigned int processes_num = SHARED_REGION_MAX_PROCESS_NUM;
 res = nvmlDeviceGetProcessUtilization(device,processes_sample,&processes_num,microsec);
 if (res == NVML_SUCCESS) {
 for (i=0; i<processes_num; i++){
 proc = find_proc_by_hostpid(processes_sample[i].pid);
 if (proc != NULL){
 sum += processes_sample[i].smUtil;
 // 这里是sm 使用率
 proc->device_util[cudadev].sm_util = processes_sample[i].smUtil;
 }
 }
 }
 if (sum < 0)
 sum = 0;
 userutil[cudadev] = sum;
 }
 unlock_shrreg();
 return 0;
}

这里获取的时候也是直接按节点上的deviceidx 设备索引号来获取有负载的卡上的不同任务负载的显存用量和利用率数据

Sqlmodel 官方文档之外的操作

Tue, 23 Dec 2025 18:10:06 +0800

SqlModel 教程之外的实用操作

sqlmodel 官方的一些教程基本上都是偏向python 查询到model 实例再操作的循环流程，对于一些可能有大批量数据的场景来说不是很友好，毕竟cython 比数据操作会更慢。下面就是近期遇到并发掘的一些实用操作

同异步会话创建

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70


from contextlib import asynccontextmanager,contextmanager
from typing import AsyncIterator, Iterator
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
from sqlalchemy import AsyncAdaptedQueuePool, create_engine
from sqlalchemy.orm import sessionmaker
from sqlmodel import Session
from sqlmodel.ext.asyncio.session import AsyncSession


async_engine = create_async_engine(
 async_url, # 异步dsn postgresql+asyncpg://
 echo=app.settings.ECHO,
 future=True,
 pool_size=2,
 max_overflow=30,
 pool_recycle=3600,
 pool_pre_ping=True,
 poolclass=AsyncAdaptedQueuePool,
)

AsyncSessionLocal = async_sessionmaker(
 bind=async_engine,
 class_=AsyncSession,
 expire_on_commit=False, # 避免commit后属性过期
)


@asynccontextmanager
async def get_async_session() -> AsyncIterator[AsyncSession]:
 """ """

 async with AsyncSessionLocal() as session:
 yield session
 await session.commit()

sync_engine = create_engine(
 sync_url, # postgresql+psycopg2://
 echo=app.settings.ECHO,
 pool_size=2,
 max_overflow=30,
 pool_recycle=3600,
 pool_pre_ping=True,
)

SyncSessionLocal = sessionmaker(
 bind=sync_engine,
 class_=Session,
 expire_on_commit=False, # 避免commit后属性过期
)

@contextmanager
def get_sync_session()->Iterator[Session]:
 with SyncSessionLocal() as session:
 yield session
 session.commit()


def session_scope(func):
 """会话管理装饰器（自动开启、提交、回滚、关闭会话）"""
 @wraps(func)
 def wrapper(*args, **kwargs):
 with SyncSessionLocal() as session:
 try:
 result = func(*args, session_=session, **kwargs)
 session.commit()
 return result
 except Exception as e:
 session.rollback()
 raise e
 return wrapper

通过上下文管理器装饰器来支持with 和 async with 自动commit 提交更改

count 数据计数

1
2
3
4
5


 with get_session() as session:
 stmt = select(func.count()).where(col(TestData.status)==StatusEnums.ACTIVE)
 count = session.exec(stmt)
 if cnt:=count.first():
 print(f"get cnt {cnt}") # get cnt xx

其实本质上就是用sqlmodel.func 底下的 count 函数做了 count(*) 操作

批量更新及删除

 1
 2
 3
 4
 5
 6
 7
 8
 9
10



 with get_session() as session:
 # 更新 status 为inactive 的变成 banned 状态
 stmt_update =update(TestData).where(col(TestData.status)==StatusEnums.INACTIVE).values(status=StatusEnums.BANNED)
 session.exec(stmt_update)
 session.commit()
 # 删除所有 banned 状态的数据，慎重
 stmt_delete =delete(TestData).where(col(TestData.status)==StatusEnums.BANNED)
 session.exec(stmt_delete)
 session.commit()

session.exec(stmt_delete) 在传入非select 语句的时候低版本会被pylance 报错，重载不支持，其实可以执行,忽视类型检查就行

这里用的是sqlmodel 的update 和delete 表达式

pg 方言冲突时更新

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


from sqlmodel import Session, select,insert
from sqlalchemy.dialects.postgresql import insert as pg_insert ,Insert
from .models.creation_template import CreationTemplate

def update_creation_template(session:Session,uuid:list[str],creation_type:Optional[str],template_id:Optional[str],commit:bool=False):
 if len(uuid)==0 or creation_type is None : # 兼容旧传参
 return
 data = [{"res_uuid": x,"creation_type":creation_type,"template_id":template_id } for x in uuid]
 stmt:Insert = pg_insert(CreationTemplate).values(data)
 # 这里一定要 重新赋值
 stmt = stmt.on_conflict_do_update(index_elements=[CreationTemplate.res_uuid],set_={CreationTemplate.creation_type:creation_type,CreationTemplate.template_id:template_id})
 session.execute(stmt)
 if commit:
 session.commit()

stmt = stmt.on_conflict_do_update(index_elements=[CreationTemplate.res_uuid],set_={CreationTemplate.creation_type:creation_type,CreationTemplate.template_id:template_id}) 这行一定要重新赋值，因为on_conflict_do_update 不是原地替换inpalce，是传统的链式调用的模式，这样有相同主键的就会更新字段内容其实更简单的是 session.merge(instance) 会先查再更新或者创建，但是性能上会差一些，也不适合批量更新工具类

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37



class PGConflictBase:
 @session_scope # 装饰器注入session
 def conflict_or_do_nothing(self,session_: Session):
 """
 仅创建一次
 """
 stmt:Insert = pg_insert(self.__class__).values(self.model_dump(exclude_unset=True, exclude_none=False))
 pk = self.__class__.get_pk_fields()
 stmt = stmt.on_conflict_do_nothing(index_elements=pk)
 session_.exec(stmt)
 session_.commit()

 @session_scope # 装饰器注入session
 def conflict_or_do_update(self,session_: Session,exclude_fields: Optional[List[str]] = None):
 """
 仅创建一次
 """
 pk = self.__class__.get_pk_fields()
 exclude_fields = exclude_fields.extend(pk)
 instance_data = self.model_dump(exclude_unset=True，exclude_none=False)
 stmt:Insert = pg_insert(self.__class__).values(instance_data)
 update_values = {
 field: getattr(self, field) # 直观获取当前实例的字段值，可读性极强
 for field in instance_data.keys()
 if field not in exclude_fields
 }
 stmt = stmt.on_conflict_do_update(index_elements=pk,set_=update_values)
 session_.exec(stmt)
 session_.commit()

 @classmethod
 def get_pk_fields(cls):
 # 检查模型并获取mapper对象
 mapper = inspect(cls)
 # 提取主键字段名
 return [col.key for col in mapper.primary_key]

排序时处理null 值

1
2
3
4


class obj:
 rank_no:Optional[int]=Field(default=None,description="排序数，可以为空")
# 
order = col(obj.rank_no).asc().nulls_last() # 默认的情况下会将null 值排前面，使用nulls_last() 可以置后

Gpu test python script

Mon, 15 Dec 2025 18:30:17 +0800

gpu 测试脚本

因为项目背景需求，经常测试k8s pod 或者job 监控的gpu 显存，使用率相关指标，下面是一个工具脚本

脚本内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77



import argparse
import time
import random
import sys
import torch


def main():
 parser = argparse.ArgumentParser(description="gpu 负载测试脚本")
 parser.add_argument("--mem-gb", type=float, required=True, help="目标显存占用(GB)")
 # 为duration添加默认值60秒，不再强制必填
 parser.add_argument(
 "--duration", type=int, default=300, help="持续时间(秒)，默认300秒"
 )
 args = parser.parse_args()

 # 基础检查
 if not torch.cuda.is_available():
 raise RuntimeError("未检测到CUDA GPU")
 torch.cuda.empty_cache()
 device = torch.device("cuda")

 # 1. 精准计算张量形状（按字节级控制显存）
 dtype = torch.float32 # 固定float32，每元素4字节，简化逻辑
 elem_bytes = 4
 target_bytes = int(args.mem_gb * 1024 * 1024 * 1024) # 目标显存转字节
 total_elems = target_bytes // elem_bytes
 # 生成2D张量形状（保证总元素数匹配目标显存）
 dim = int(total_elems**0.5)
 shape = (dim, dim)
 actual_mem_gb = (dim * dim * elem_bytes) / (1024**3)

 # 2. 分配张量（禁用梯度，无计算图，仅占显存）
 tensor = torch.randn(shape, dtype=dtype, device=device, requires_grad=False)
 # 校验显存占用
 allocated_mem_gb = torch.cuda.memory_allocated(device) / (1024**3)
 print(f"=== 初始化 ===")
 print(f"目标显存: {args.mem_gb}GB | 实际占用: {allocated_mem_gb:.4f}GB")
 print(f"张量形状: {shape} | 持续计算: {args.duration}秒\n")

 # 3. 核心：原地计算消耗GPU算力（无额外显存占用）
 start_time = time.time()
 try:
 while time.time() - start_time < args.duration:
 # 原地运算（所有操作均在原张量执行，不新增显存）
 tensor.add_(random.uniform(0.01, 0.1)) # 原地加
 tensor.mul_(random.uniform(0.9, 1.1)) # 原地乘
 tensor.sin_() # 原地正弦
 tensor.cos_() # 原地余弦
 torch.cuda.synchronize() # 确保计算完成

 # 打印状态（覆盖式输出）
 elapsed = int(time.time() - start_time)
 remaining = max(0, args.duration - elapsed)
 print(
 f"剩余时间: {remaining:3d}秒 | 显存占用: {allocated_mem_gb:.4f}GB",
 end="\r",
 )
 time.sleep(0.001) # 微调算力强度（越小算力越高）

 except KeyboardInterrupt:
 print("\n\n⚠️ 手动终止")
 finally:
 # ========== 核心：仅在退出时强制flush所有输出 ==========
 print("\n", flush=True)
 sys.stdout.flush()
 # 清理显存
 del tensor
 torch.cuda.empty_cache()
 final_mem = torch.cuda.memory_allocated(device) / (1024**3)
 print(f"\n=== 结束 ===")
 print(f"释放后显存: {final_mem:.4f}GB")


if __name__ == "__main__":
 main()

使用方式就是容器有pytorch 依赖，调用时如下:
python3 gpu_test.py --mem-gb 1 来构造一个1GB 默认5分钟的gpu 计算任务

使用pg 对资源用时进行统计

Fri, 05 Dec 2025 17:00:24 +0800

使用pg统计资源用时

近期项目上有个相关资源用时统计的需求，我个人想了一个简单的统计demo

大致需求

有个资源有唯一id ，需要根据开机时间，关机时间统计按当天（近似实时），天，周，月，年的维度计算用时数据拆解下来最基本的计算逻辑时天和当天这两种，下文会简单说下其他的几个维度咋统计或者查询
计算当天和昨天的需求可以被抽象成一个逻辑：
查找开始时间到截止（当下或者昨天最后一秒）的资源用时。
先给个简单的创建表结构语句示例：

1
2
3
4
5
6


CREATE TABLE machine_runtime (
 id SERIAL PRIMARY KEY,
 machine_id VARCHAR(50) NOT NULL, -- 机器ID
 start_time TIMESTAMP NOT NULL, -- 开机时间
 end_time TIMESTAMP -- 关机时间（可为空）
);

这里开机时创建一个记录，有开机时间，但是关机时间为空，可以将主键记录在资源实体记录中，或者关机时查机器id 相关记录中关机时间为空的那个补上这个关机时间，于是这个开关机记录有两种：

有开机时间没关机，说明是还在运行中的，就将查询时间当成统计截止时间来计算用时
用关机时间，需要比较这个开机时间是否比筛选的开始范围更晚

1
2


 select round(sum( extract (epoch from ( least(COALESCE(end_time,'2025-12-04T23:59:59'),'2025-12-04T23:59:59')-GREATEST(start_time,'2025-12-04T00:00:00')) ) )
/3600,0) as cost_hour from machine_runtime where machine_id='1;

上述是查询语句示例：在12-05 结算前一天的特定机器的用时，如果是计算当天的只需要改动下起止时间点，于是根据pg 的函数定义方式得出了下面的函数创建语句

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


CREATE OR REPLACE FUNCTION calculate_machine_hour_batch(p_machine_id VARCHAR(50),p_start_time TIMESTAMP,p_end_time TIMESTAMP)
RETURNS TABLE (cost_hour NUMERIC) AS
$$
BEGIN
 RETURN QUERY
 SELECT
 ROUND(
 SUM(EXTRACT(EPOCH FROM (
 LEAST(COALESCE(m.end_time, p_end_time), p_end_time) - GREATEST(m.start_time, p_start_time)
 ))) / 3600, 0
 ) AS cost_hour
 FROM machine_runtime m
 WHERE m.machine_id = p_machine_id AND (( m.start_time>p_start_time) or m.end_time is null);
END;
$$
LANGUAGE plpgsql;

整个过程被封装成查询某个id 的起止时间内多段开关机记录的用时总和，用法如下：

1
2
3
4
5


 select calculate_machine_hour_batch('1','2025-12-04T00:00:00','2025_12-04T23:59:59') as cost_time;
 cost_time
-----------
 15
(1 row)

看起来还是很简单的

python 怎么查询

在python 中可以通过sqlmodel 执行原生sql 的方式简化查询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


def get_machine_runtime_hour(
 machine_id: str,
 start_time: str, # 格式如 "2025-12-04T00:00:00"
 end_time: str # 格式如 "2025-12-04T23:59:59"
) -> Optional[int]:
 """
 调用PostgreSQL的calculate_machine_hour函数，获取机器用时（小时，取整）
 """
 # 函数调用的SQL语句（注意PostgreSQL函数调用的语法）
 sql = """
 SELECT calculate_machine_hour(
 %s::varchar,
 %s::timestamp,
 %s::timestamp
 ) AS cost_hour;
 """

 with Session(engine) as session:
 # 执行原生SQL，传入参数（避免SQL注入）
 result = session.exec(
 sql,
 params=[machine_id, start_time, end_time]
 ).first() # 获取单行结果

 # 结果解析：返回整数小时数（无数据则返回None）
 return int(result) if result is not None else 0

周，月，年怎么处理

上面其实已经论述了怎么计算前一天的用时数据，那其他维度的过去用量其实都是可以按照天来定时更新，按照id ，时间维度的开始日期或者就是时间，来确定一个周，月，年的资源统计记录，然后把这个增量数据（天）加上去。
这个就是除去当天之前的其他维度数据的计算，通过存放到多个表里来以查代算，只用每天定时更新前一天的就可以把计算的维度缩小到一天之中，控制聚合的记录数量，剩下就是重复走当天用量的计算逻辑。这里看下来通过创建这三个字段的聚合索引可以完成初步优化

1
2
3


CREATE INDEX idx_machine_runtime_covering ON machine_runtime (
 machine_id, start_time
) INCLUDE (end_time);

结合lora和离线学习的llm蒸馏策略

Fri, 05 Dec 2025 16:29:45 +0800

大模型的lora 想法

大模型本身在推理部署的场景下对模型显存的占用量就是很夸张的，导致训练大模型成本很高，基于lora 在领域语料上继续学习垂直知识是一个低成本的最佳实践，最近组里也在测试蒸馏学习的最佳实践，便有了如下的想法，估计很多人都已经付诸于实践了，我这点东西只是记录下碎片化的idea。

简单的模型蒸馏

在前几年bert刷分的时代，bert 蒸馏技术在印象中可以简单归纳为两种:

logit 层感知学习，对照教师模型和学生模型在最后一个logit 层的张量损失，作为学生模型的学习损失
hidden 层感知学习，这个是将中间多层transformers 块的输出也考虑进来，逐个对照输出分布差异，将各层损失求和

这两种方法在资源紧张的情况下，可以通过保存张量，和输入预料关联制作成离线的蒸馏学习数据集：好处是：

蒸馏学习时可以省去一个教师大模型占据的显存资源，成本低；
同时这部分数据可以多次复用，用时间去换空间；

lora 微调 llm

现在基于peft 的lora 微调流程其实已经很成熟了，lora 微调可以使得llm在领域预料上的finetune 时占用显存更小，便于持续学习这种模式训练llm，同时没有改变 logit 层的输出维度，使用lora 的同时还可以开量化，半精度训练来感知量化，减少因为精度损失带来的性能退化。

结合起来

先用教师大模型提取数据集的离线张量数据
学生模型用lora 开量化在相同数据上同时计算任务损失和教师模型的学习损失最终学生模型会获得一个在单纯量化上利用蒸馏张量和训练恢复性能的lora 模块，这个流程标准化后蒸馏和微调小模型的成本会继续下降

使用python 实现一个分布式Singleflight

Fri, 24 Oct 2025 16:34:08 +0800

使用Python 实现的分布式Singleflight

在golang 项目中Singleflight 是个常见的优化工具，但是在python 中好像没有标准库模块，用第三方的引入依赖也挺讨厌的，越来越重的依赖，所以这里仿照go 的机制，做了两个工具类，适合在fastapi 框架中使用，需要有redis 组件

同步版本多缓存实现

先看核心的类定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118



class DistributedSingleFlight:
 def __init__(self, redis: redis.Redis, local_cache: TTLCache):
 self.redis = redis
 self.local_cache = local_cache
 self.lock_prefix = "singleflight:lock:"
 self.result_prefix = "singleflight:result:"

 @contextmanager
 def _lock(self, key: str, timeout: int = 10):
 """分布式锁实现"""
 lock_key = f"{self.lock_prefix}{key}"
 identifier = str(uuid.uuid4())

 # 尝试获取锁
 acquired = self.redis.set(
 lock_key,
 identifier,
 nx=True,
 ex=timeout # 防止死锁，自动过期
 )

 try:
 yield acquired, identifier
 finally:
 # 只有持有锁的进程才能释放锁
 if acquired:
 current = self.redis.get(lock_key)
 if current == identifier:
 self.redis.delete(lock_key)

 def _get_result(self, key: str) -> Optional[Any]:
 """获取已缓存的结果"""
 result_key = f"{self.result_prefix}{key}"
 data = self.redis.get(result_key)
 if data:
 return json.loads(data)
 return None

 def _set_result(self, key: str, result: Any, ttl: int = 60):
 """缓存执行结果"""
 result_key = f"{self.result_prefix}{key}"
 self.redis.set(result_key, json.dumps(result), ex=ttl)
 # 同时更新本地缓存
 self.local_cache[key] = result

 def do(
 self,
 key: str,
 func: Callable,
 *args,
 result_ttl: int = 60,
 lock_timeout: int = 10,
 retry_interval: float = 0.1,
 **kwargs
 ) -> Any:
 """
 执行函数，跨进程确保同一 key 只有一个实例执行
 :param key: 任务标识
 :param func: 执行函数
 :param result_ttl: 结果缓存时间（秒）
 :param lock_timeout: 分布式锁超时时间（秒）
 :param retry_interval: 等待锁的重试间隔（秒）
 """
 # 先查本地缓存，减少 Redis 访问
 if key in self.local_cache:
 return self.local_cache[key]

 # 查 Redis 缓存
 cached_result = self._get_result(key)
 if cached_result is not None:
 self.local_cache[key] = cached_result
 return cached_result

 # 尝试获取分布式锁
 with self._lock(key, lock_timeout) as (acquired, identifier):
 if acquired:
 # 成功获取锁，执行实际任务
 try:
 result = func(*args, **kwargs)
 self._set_result(key, result, result_ttl)
 return result
 except Exception as e:
 # 可以选择缓存异常或直接抛出
 raise e
 else:
 # 未获取到锁，等待结果
 while True:
 result = self._get_result(key)
 if result is not None:
 self.local_cache[key] = result
 return result
 time.sleep(retry_interval)

 def wrap(
 self,
 key_func: Optional[Callable] = None,
 result_ttl: int = 60,
 lock_timeout: int = 10
 ) -> Callable:
 """装饰器版本"""
 def decorator(func: Callable) -> Callable:
 @wraps(func)
 def wrapper(*args, **kwargs) -> Any:
 # 生成 key
 if key_func:
 key = key_func(*args, **kwargs)
 else:
 key = f"{func.__module__}:{func.__name__}"
 return self.do(
 key=key,
 func=func,
 *args,
 result_ttl=result_ttl,
 lock_timeout=lock_timeout,** kwargs
 )
 return wrapper
 return decorator

这里是测试用的主代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


import time
import uuid
import json
from functools import wraps
from typing import Callable, Optional, Dict, Any
from contextlib import contextmanager

import redis
from cachetools import TTLCache
from fastapi import FastAPI
from singleflight import DistributedSingleFlight
# 初始化 Redis 连接（根据实际配置调整）
redis_client = redis.Redis(
 host="localhost",
 port=6379,
 db=0,
 decode_responses=True
)

# 进程内本地缓存（避免重复处理同一 key）
local_cache = TTLCache(maxsize=1024, ttl=60) # 缓存 60 秒

app = FastAPI()




# 初始化单飞实例
sf = DistributedSingleFlight(redis_client, local_cache)

# FastAPI 示例接口
@app.get("/fetch")
@sf.wrap(
 key_func=lambda url: f"fetch:{url}", # 用 url 作为 key
 result_ttl=30, # 结果缓存 30 秒
 lock_timeout=5 # 锁超时 5 秒
)
async def fetch_resource(url: str):
 """模拟获取远程资源的接口"""
 print(f"实际执行请求: {url} (进程: {id(os.getpid())})")
 # 模拟耗时操作（如数据库查询、网络请求）
 await asyncio.sleep(2)
 return {"url": url, "data": f"content of {url}"}


if __name__ == "__main__":
 import uvicorn
 # 多进程启动（模拟生产环境，workers>1）
 uvicorn.run(
 "main:app",
 host="0.0.0.0",
 port=8000,
 workers=4, # 4个进程
 reload=False
 )

这里可以看到其实同步版本就是利用多级缓存中是否有key(TTL时效控制)，有的话直接返回，没的话上升到分布式锁，能拿到唯一分布式锁的执行者会将结果缓存到redis 中，其他未拿到锁的跟随者，通过轮询sleep 的方式来等待结果缓存产生，这里相比循环拿锁的串行流程，是在第一个执行者完成后，剩余的并发会在短时间内复用改结果，而不是继续串行执行：
假设有n 个执行者，每个执行的时间近似为t。这样在使用Singleflight机制的情况下，预期的执行耗时是t，如果单纯使用分布式锁争抢就是n*t。

使用异步来进一步优化

直接专注于Singleflight 的核心类定义就行

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128



class AsyncDistributedSingleFlight:
 def __init__(self, redis: Redis, local_cache: TTLCache):
 self.redis = redis
 self.local_cache = local_cache
 self.lock_prefix = "singleflight:lock:"
 self.result_prefix = "singleflight:result:"
 # 进程内的异步锁（防止同一进程内的协程竞争）
 self._local_locks: Dict[str, asyncio.Lock] = {}

 async def _get_local_lock(self, key: str) -> asyncio.Lock:
 """获取进程内的本地锁（每个 key 一个）"""
 if key not in self._local_locks:
 self._local_locks[key] = asyncio.Lock()
 return self._local_locks[key]

 @asynccontextmanager
 async def _distributed_lock(self, key: str, timeout: int = 10):
 """异步分布式锁（基于 Redis）"""
 lock_key = f"{self.lock_prefix}{key}"
 identifier = str(uuid.uuid4())

 # 尝试获取锁：SET NX（不存在则设置），并设置过期时间防止死锁
 acquired = await self.redis.set(
 lock_key, identifier, nx=True, ex=timeout
 )

 try:
 yield acquired, identifier
 finally:
 # 只有持有锁的进程才能释放锁
 if acquired:
 current = await self.redis.get(lock_key)
 if current == identifier:
 await self.redis.delete(lock_key)

 async def _get_result(self, key: str) -> Optional[Any]:
 """从 Redis 获取缓存结果"""
 result_key = f"{self.result_prefix}{key}"
 data = await self.redis.get(result_key)
 return json.loads(data) if data else None

 async def _set_result(self, key: str, result: Any, ttl: int = 60):
 """将结果存入 Redis 和本地缓存"""
 result_key = f"{self.result_prefix}{key}"
 await self.redis.set(result_key, json.dumps(result), ex=ttl)
 self.local_cache[key] = result # 同步更新本地缓存

 async def do(
 self,
 key: str,
 func: Callable,
 *args,
 result_ttl: int = 60,
 lock_timeout: int = 10,
 retry_interval: float = 0.1,
 **kwargs
 ) -> Any:
 """
 异步执行函数，确保同一 key 在多进程/多协程下只有一个实例执行
 :param key: 任务标识
 :param func: 异步函数（需用 async def 定义）
 :param result_ttl: 结果缓存时间（秒）
 :param lock_timeout: 分布式锁超时时间（秒）
 :param retry_interval: 等待结果的重试间隔（秒）
 """
 # 1. 先查本地缓存（最快，避免跨进程交互）
 if key in self.local_cache:
 return self.local_cache[key]

 # 2. 获取进程内本地锁（防止同一进程内的多个协程同时竞争分布式锁）
 local_lock = await self._get_local_lock(key)
 async with local_lock:
 # 双重检查本地缓存（防止本地锁等待期间已缓存结果）
 if key in self.local_cache:
 return self.local_cache[key]

 # 3. 查 Redis 缓存（跨进程共享的结果）
 cached_result = await self._get_result(key)
 if cached_result is not None:
 self.local_cache[key] = cached_result
 return cached_result

 # 4. 竞争分布式锁，执行任务
 async with self._distributed_lock(key, lock_timeout) as (acquired, _):
 if acquired:
 # 成功获取锁，执行实际任务（确保是异步函数）
 try:
 result = await func(*args, **kwargs) # 异步执行
 await self._set_result(key, result, result_ttl)
 return result
 except Exception as e:
 # 异常不缓存，直接抛出（可根据需求修改）
 raise e
 else:
 # 未获取到锁，循环等待结果（非阻塞等待）
 while True:
 result = await self._get_result(key)
 if result is not None:
 self.local_cache[key] = result
 return result
 # 异步睡眠，不阻塞事件循环
 await asyncio.sleep(retry_interval)

 def wrap(
 self,
 key_func: Optional[Callable] = None,
 result_ttl: int = 60,
 lock_timeout: int = 10
 ) -> Callable:
 """装饰器版本，用于异步函数"""
 def decorator(func: Callable) -> Callable:
 @wraps(func)
 async def wrapper(*args, **kwargs) -> Any:
 # 生成 key（默认用函数路径+参数生成）
 if key_func:
 key = key_func(*args, **kwargs)
 else:
 key = f"{func.__module__}:{func.__name__}:{args}:{tuple(kwargs.items())}"
 return await self.do(
 key=key,
 func=func,
 *args,
 result_ttl=result_ttl,
 lock_timeout=lock_timeout,** kwargs
 )
 return wrapper
 return decorator

这样能进一步优化一下接口io,不同key 的通过异步能承载更多请求

pydantic V2 迁移遇到的json 类型兼容问题

Fri, 17 Oct 2025 13:38:40 +0800

pydantic v2 的json 兼容性问题

背景介绍：项目里面有很多v1 时代的写法，例如：envs: List[EnvModel] = Field([], sa_column=Column(JSON), description="环境变量列表"), 在v1 时代pydantic 会自动帮你做泛型转换在 Pydantic v1 中，可能通过隐式逻辑将 List[T] 与 JSON 类型关联，但 v2 移除了这种隐式关联，导致直接使用 sa_column=Column(JSON) 时，SQLAlchemy 无法将 List[EnvModel] 与 JSON 类型正确绑定，从而会引发报错 <class 'list'> has no matching SQLAlchemy type。本质原因是SQLAlchemy 对字段类型的推断依赖于明确的 Python 类型与数据库类型的映射（如 str → VARCHAR，int → INTEGER）。但对于泛型容器类型（如 List[EnvModel]），SQLAlchemy 本身无法直接识别为某个数据库类型（如 JSON），必须显式指定类型（如 Column(JSON)）。

现在介绍三种解决方法：

方案1 手动添加方法进行转换

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


class EnvModel(SQLModel):
 name: str = Field(..., nullable=False)
 value: str = Field(..., nullable=False)

env_list_adapter = TypeAdapter(list[EnvModel])

class APP(SQLModel, table=True):
 __tablename__ = "apps"

 id: int | None = Field(default=None, primary_key=True)
 name: str = Field("应用名称", nullable=False, description="应用名称")
 envs_json: str = Field("",sa_column=Column(JSON),alias="envs")
 def __init__(self,**data:Any):
 envs_ = data.pop("envs",None)
 super().__init__(**data)
 if isinstance(envs_,list):
 self.envs = envs_

 @property
 def envs(self)->list[EnvModel]:
 if isinstance(self.envs_json,str) and self.envs_json:
 try:
 return env_list_adapter.validate_json(self.envs_json)
 except Exception:
 return []
 return env_list_adapter.validate_python(self.envs_json)

 @envs.setter
 def envs(self,val:list[EnvModel]):
 self.envs_json = env_list_adapter.dump_json(val).decode()

优点：简单易懂，简单类转换一下也不会出啥问题
缺点：改动较多，一个字段最少得多两个方法和一个TypeAdapter，在大量使用这种复合类型字段的情况下，这种改动太多了

方案2 减少对类的改动，通过外部转换

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


class EnvModel(SQLModel):
 name: str = Field(..., nullable=False)
 value: str = Field(..., nullable=False)
 class Config:
 orm_mode = True

class APP(SQLModel, table=True):
 __tablename__ = "apps"

 id: int | None = Field(default=None, primary_key=True)
 name: str = Field("应用名称", nullable=False, description="应用名称")
 # 这里用list[dict] 字典列表来做类型注解，自动转换为常见的array json类型
 envs: list[dict] = Field( sa_column=Column(ARRAY(JSON)),alias="envs")

优点：对类几乎无改动，用的也是基本类型字典
缺点：如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


async with async_session() as session:
 try:
 test = APP(
 name="测试服务",
 envs=[
 # 赋值需要转成dict 
 EnvModel(name="PATH", value="/usr/local/bin").model_dump(),
 EnvModel(name="PYTHONPATH", value="/app").model_dump(),
 EnvModel(name="DEBUG", value="true").model_dump()
 ]
 )

 session.add(test)
 await session.commit()
 await session.refresh(test)

 logger.info(f"创建的服务 ID: {test.id}")
 logger.info(f"环境变量数量: {len(test.envs)}")

 result = await session.execute(select(APP).where(APP.id == test.id))
 db_app = result.first()

 logger.info(f"查询到的服务名称: {db_app.name}")
 logger.info("环境变量:")
 for env in db_app.envs:
 # 获取时需要用EnvModel 来检验类型，并转换成对应实例
 env = EnvModel(**env)
 logger.info(f" {env.name}: {env.value}")

方案3 自定义类型适配器，推荐

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


T = TypeVar('T', bound=SQLModel)


class SQLModelListType(TypeDecorator, Generic[T]):
 """
 自定义SQLAlchemy类型，自动处理：
 - 写入：list[SQLModel] -> list[dict]（存储为JSON数组）
 - 读取：list[dict] -> list[SQLModel]
 """
 # 基础类型：PostgreSQL的ARRAY(JSON)或纯JSON
 impl = JSON # 若用纯JSON则改为JSON

 def __init__(self, model_cls: Optional[Type[T]]=None, *args, **kwargs):
 super().__init__(*args, **kwargs)
 if model_cls:
 self.model_cls: Type[T] = model_cls # 明确标注类型

 def process_bind_param(self, value: List[T], dialect) -> List[dict]:
 """写入数据库时：将模型列表转为字典列表"""
 if not value:
 return []
 return [item.model_dump() for item in value]

 def process_result_value(self, value: List[dict], dialect) -> List[T]:
 """从数据库读取时：将字典列表转为模型列表"""
 if not value:
 return []
 return [self.model_cls(** item) for item in value]


class EnvModel(SQLModel):
 name: str = Field(..., nullable=False)
 value: str = Field(..., nullable=False)



class APP(SQLModel, table=True):
 __tablename__ = "apps"

 id: int | None = Field(default=None, primary_key=True)
 name: str = Field("应用名称", nullable=False, description="应用名称")
 # 核心改动：使用自定义类型，指定模型类型为EnvModel
 envs: list[EnvModel] = Field(
 default_factory=list,
 sa_column=Column(SQLModelListType(EnvModel)) # 绑定自定义类型
 )

优点：能复用这个类型装饰器，实现v2 的类型迁移，几乎无感，改动也仅限于对应字段的那行，完全可以接受这个工作量
缺点：自定义sqlalchemy 类型装饰器的场景比较少见，用来做sa_column 可能没之前那么直白，理解难度会高一些

sqlalchemy 的类型装饰器

SQLAlchemy 的 TypeDecorator 是用于自定义数据库类型的核心工具，它通过封装底层数据库类型并覆盖特定方法，实现 Python 类型与数据库类型的双向转换。其核心方法如下：

impl：指定底层数据库类型（必须定义）
impl 是 TypeDecorator 的核心类属性，用于指定当前自定义类型基于哪个 SQLAlchemy 原生类型（如 Integer、String、JSON 等）。所有数据库交互最终会委托给这个底层类型。
示例：
1 2 3 4

from sqlalchemy import TypeDecorator, JSON class MyJsonType(TypeDecorator): impl = JSON # 基于原生 JSON 类型扩展
process_bind_param(self, value, dialect)：Python → 数据库（写入时）
作用：将 Python 中的值（如自定义对象、复杂类型）转换为底层数据库类型可接受的格式（如 JSON 类型接受字典 / 列表，String 接受字符串）。
参数:
- value：Python 中要写入数据库的值（可能为 None）。
- dialect：当前数据库方言（如 postgresql、mysql），可用于适配不同数据库的差异。
- 返回值：转换后的值（需符合 impl 类型的要求）。
示例：
1 2 3 4 5

def process_bind_param(self, value, dialect): if value is None: return [] # 将自定义模型列表转为字典列表（适配 JSON 类型） return [item.dict() for item in value]
process_result_value(self, value, dialect)：数据库 → Python（读取时）
作用：将从数据库读取的值（如 JSON 解析后的字典）转换为 Python 中需要的类型（如自定义模型、复杂对象）。
参数：

value：从数据库读取的值（可能为 None，格式由 impl 类型决定）。
dialect：当前数据库方言。

返回值：转换后的 Python 对象（如自定义模型实例）。
示例：

1
2
3
4
5
6



def process_result_value(self, value, dialect):
 if not value:
 return []
 # 将字典列表转为自定义模型列表
 return [MyModel(** item) for item in value]

process_literal_param(self, value, dialect)：处理 SQL 字面量（可选）
作用：当值以字面量形式嵌入 SQL 语句（如 INSERT VALUES (?) 中的 ?）时，将其转换为符合 SQL 语法的字符串。
默认行为：若未实现，会使用 impl 类型的 process_literal_param 方法。通常用于自定义类型需要特殊 SQL 字面量格式的场景（如日期格式化）。
示例：
1 2 3 4 5

def process_literal_param(self, value, dialect): if value is None: return 'NULL' # 对字符串类型值添加单引号，避免 SQL 注入风险 return f"'{value}'"

纯go 调用dll 实现一些动态装载

Mon, 29 Sep 2025 10:51:48 +0800

golang 调用dll 实践

众所周知，go 支持通过cgo 方式直接嵌入c/cpp 代码，但是有时候涉及到ffi 的部分仅仅是一小部分的业务功能，没有必要开混编。

这里记录下近期发掘到的一种通过封装的dll 来动态调用c库的方法。个人觉得这种方式提升了灵活性，有利于实现部分功能的热更新，对于目前ai 应用的混编部署也是一种简约的模式，函数调用优于网络调用。

dll 部分

c 和cpp 里面宽窄字符串一直是比较恶心的一点，这里就用它做示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


#include<iostream>
#include <string>
#include <locale>
#include <windows.h> // 引入Windows API
using std::cout;
using std::endl;

// 将宽字符串转换为UTF-8字符串（使用Windows API）
std::string wstring_to_utf8(const std::wstring& wstr) {
 if (wstr.empty()) return "";

 // 计算需要的缓冲区大小
 int buffer_size = WideCharToMultiByte(
 CP_UTF8, // 目标编码为UTF-8
 0, // 转换标志
 wstr.c_str(), // 源宽字符串
 -1, // 自动计算长度
 nullptr, // 目标缓冲区（先不提供）
 0, // 目标缓冲区大小（先计算）
 nullptr, // 无效字符替换（使用默认）
 nullptr // 是否使用了替换字符
 );

 if (buffer_size <= 0) return "";

 // 分配缓冲区并进行转换
 std::string result(buffer_size, 0);
 WideCharToMultiByte(
 CP_UTF8,
 0,
 wstr.c_str(),
 -1,
 &result[0],
 buffer_size,
 nullptr,
 nullptr
 );

 // 移除结尾的空字符
 if (!result.empty() && result[result.size() - 1] == '\0') {
 result.pop_back();
 }

 return result;
}

extern "C" __declspec(dllexport) void sayHello(const char * s){
 cout<<"hello"<<s<<endl;
}

extern "C" __declspec(dllexport) void sayHelloW(const wchar_t* s) {
 if (s == nullptr) return; // 空指针保护
 try {
 // 将宽字符转换为UTF-8再输出，避免直接使用wcout的问题
 std::wstring wstr(s);
 std::string utf8_str = wstring_to_utf8(wstr);
 cout << "Hello, " << utf8_str << endl;
 } catch (...) {
 cout << "Error processing string" << endl;
 }
}

这里给了两个函数，分别用于处理简单的ascii字符串和带中文的通过命令行

1

 g++ -shared -o mylib.dll hello.cc

将其处理为 dll 文件

go 部分

这里是展示两种加载和字符串处理方式： - lazy 加载，调用到对应函数时才会第一次加载，有助于优化启动速度，实现热更新要用系统调用释放这部分，再加载 - loaddll 调用这个方法时加载，需要手动释放，实现热更新时，释放再加载就行

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74


import (
 "fmt"
 "syscall"
 "unsafe"

 "golang.org/x/sys/windows"
)

// 将Go字符串转换为C兼容的UTF-8字符串
func cString(s string) *byte {
 b := make([]byte, len(s)+1)
 copy(b, s)
 return &b[0]
}

func lazydllW() {
 // 加载动态库
 lib := windows.NewLazyDLL("mylib.dll")

 if err := lib.Load(); err != nil {
 fmt.Println("加载动态库失败:", err)
 return
 }

 // defer lib.Release()
 // 获取函数地址
 funcAddr := lib.NewProc("sayHelloW")

 // 调用函数
 exampleFunction := funcAddr.Addr()
 str, err := syscall.UTF16PtrFromString("潘达") // 使用宽字符串
 if err != nil {
 fmt.Println("Error converting string:", err)
 return
 }
 _, _, err = syscall.SyscallN(exampleFunction, uintptr(unsafe.Pointer(str)))
 if err != syscall.Errno(0) {
 fmt.Println("Error calling Add:", err)
 return
 }
 fmt.Println("函数执行成功")
}

func loadWithASCII(){
 // 加载动态库
 lib, err := syscall.LoadDLL("mylib.dll")

 if err != nil {
 fmt.Println("加载动态库失败:", err)
 return
 }

 defer lib.Release() // 非lazy模式记得手动释放
 // 获取函数地址
 funcAddr, err := lib.FindProc("sayHello")
 if err != nil {
 fmt.Println("函数查找失败:", err)
 return
 }
 // 调用函数
 exampleFunction := funcAddr.Addr()
 str := "panda"
 cStr := unsafe.Pointer(cString(str)) // 注意这里，需要转成c 兼容的字符串，类型转成Pointer
 if err != nil {
 fmt.Println("Error converting string:", err)
 return
 }
 _, _, err = syscall.SyscallN(exampleFunction, uintptr(cStr))
 if err != syscall.Errno(0) {
 fmt.Println("Error calling Add:", err)
 return
 }
 fmt.Println("函数执行成功")
}

lumberjack 日志库组件权限陷阱

Sun, 20 Jul 2025 15:09:23 +0800

lumberjack 日志库组件权限陷阱

之前一直使用go zero 的logx 组件来创建一个滚动日志，对filebeat 日志收集容器兼容性很好；近期在换成zero log+ lumberjack 的这套方案时用，和filebeat 的边车模式产生了冲突；

现象

filebeat 服务告警，指向的日志文件权限不可访问；使用webssh 上去查看时发现ls -al 看到的权限是"0600"，也就是说不支持其他用户组的服务去访问，于是检查代码，发现并未手动创建日志，赋予0600文件权限，所以问题是lumberjack组件内部的默认文件权限是0600。
那到底是哪部分导致的？源码
通过翻看上述部分源码，确认是默认给的权限就是0600，搜索issue 发现自定义文件权限里面提到：

Lumberjack will copy the permissions of the existing file when it creates the new file. See here: https://github.com/natefinch/lumberjack/blob/v3/lumberjack.go#L267
So if you want different file permissions, the easiest thing to do is create the file with the permissions you want, first.
另外附加源头pr 链接：https://github.com/natefinch/lumberjack/pull/112, 这里做出这个变更的原因据称是为了审计要求，收紧默认权限。十分甚至一百分的不优雅，加个Options 让使用者自己选不是比默认0600好很多？

所以处理策略就是在使用前，先创建一个644权限的日志文件，然后关闭,再将该文件名交给lumberjack 组件。这样lumberjack会复制原始文件的权限，创建新的日志文件，避免边车容器因为用户组不同导致600无法访问文件的事情；

处理

简单的加三行代码

1
2
3


if fp, err := os.OpenFile(fileName, os.O_WRONLY|os.O_APPEND|os.O_CREATE, 0644); err == nil {
 fp.Close()
}

总结

使用不熟悉的库遇到问题的时候，光翻找官方教程和在线博客可能是不够的，需要结合源码和issue 去排查。

Videocutter

Mon, 14 Jul 2025 16:01:50 +0800

视频流切片服务设计

这里记录下终端录制视频流切片并上传的流程设计与优化过程： 1. ffmpeg -i rtmp://xxxxx:1935/yyyy/zzzz/vision -c:v h264 -flags +cgop -g 0 -hls_flags program_date_time -hls_list_size 0 -hls_time 10 /app/data/record.m3u8 -y
2. ffmpeg -hide_banner -f concat -safe 0 -i files.txt -ss 00:00:18 -t 00:00:40 -c copy -hls_list_size 0 ./output.m3u8

这里是实现最原始切片方案的核心逻辑，下面会解释流程，然后列出自己的优化过程。

最简原型

录制逻辑

ffmpeg -i rtmp://xxxxx:1935/yyyy/zzzz/vision -c:v h264 -flags +cgop -g 0 -hls_flags program_date_time -hls_list_size 0 -hls_time 10 /app/data/record.m3u8 -y

这里从rtmp://xxxxx:1935/yyyy/zzzz/vision 视频流获取然后添加：

-hls_flags program_date_time 使用#EXT-X-PROGRAM-DATE-TIME时间扩展 ,在m3u8 文件中记录每个切片的开始时间，重要
-hls_list_size 0 配置 m3u8 为记录所有ts 文件
-c:v h264 确保格式为h264

切片逻辑

切片最重要的是解析m3u8 文件，判断请求的时间是否在文件记录的范围内，是的话将其加入到concat 文件中，然后更新ss 也就是切片开始时间，最后执行下述切片指令; ffmpeg -hide_banner -f concat -safe 0 -i files.txt -ss 00:00:18 -t 00:00:40 -c copy -hls_list_size 0 ./output.m3u8

-i files.txt 输入concat 文件，这里是切片的核心逻辑
-ss 00:00:18 -t 00:00:40 切片起始时间和持续时间
-c copy 不做编码，直接复制
-hls_list_size 0 配置 m3u8 为记录所有ts 文件

上传逻辑

使用tar 对目标目录下所有非tar 后缀文件进行归档；
创建分片上传请求，拿到上传id
使用上传id 去分片上传大文件，设置有效时间
确认上传成功后主动清理目标目录

优化

上述实现流程中存在以下问题:

切片太慢，多个视角有放大效应
录制太占用资源，观察到最极端场景 113% cpu 占用 top

录制逻辑优化

首先在测试需要录制的视频流格式，获得以下信息：

Metadata:
|RtmpSampleAccess: true
fileSize : 0
title : Streamed by ZLMediaKit(git hash:f3026f5/2025-01-12T10:16:45+08:00,branch:master,build time:2025-01-12T02:24:04)
Duration: 00:00:00.00, start: 2196.413000, bitrate: N/A
Stream #0:0: Data: none
Stream #0:1: Video: h264 (Constrained Baseline), yuv420p(progressive), 768x432, 10 fps, 10 tbr, 1k tbn
Stream #0:2: Audio: aac (LC), 8000 Hz, mono, fltp

可以看到视频编码格式是 H264 ，和切片的编码相同，使用 -c copy 直接复制即可。
上下分别是修改前后的资源占用情况 TOP
最低也节省了40%*4 的cpu 资源这里还可以利用hls_warp 来实现滚动录制，但是得需要手动拷贝到目标目录然后重建m3u8,长期录制需要去做这个，另外这里的优化为后面的切片逻辑让出了余裕。

切片逻辑优化

切片主要是有以下几个问题：

会随着 -ss 开始切片的值，导致切片耗时增长
多个视角使用串行一次完成录制

针对问题1，可以检索到ffmpeg 命令行文档中记录

-ss position (input/output)
When used as an input option (before -i), seeks in this input file to position. Note that in most formats it is not possible to seek exactly, so ffmpeg will seek to the closest seek point before position. 当使用-ss 时，会先seek 到指定位置，（如果可能的话），然后开始解码

应对策略，在需要切片的视频只命中了一个M3U8文件，去掉合并逻辑，直接从m3u8 切片，使用-ss 优化切片耗时：

~~在-i 之前使用 -ss 可以利用seek 操作，快速定位，提升切片效率，测试后观察切片时间平均减半~~，更正优化策略，通过跟踪观察对HLS类型的录制，直接使用-ss 无法实现预先中的seek 定位，需要手动从原始M3U8 中切出子播放列表，是的可以用 -ss 0 来从子切片的位置开头的位置处直接提取，优化效果1分钟的切片可以在秒级完成，可以满足合规要求

1
2


2025-07-16T14:45:18+08:00 | INFO | command.go:15 > ExecCMD: ffmpeg -y -hide_banner -ss 00:00:00 -t 00:01:32 -i /app/data/temp/back_bd650cb7-15f3-467b-99d4-fb4c90c5093e.m3u8 -c copy -hls_list_size 0 /app/data/upload/bd650cb7-15f3-467b-99d4-fb4c90c5093e/back.m3u8 |
2025-07-16T14:45:20+08:00 | INFO | transform.go:76 > spend 00:00:02 time |

针对问题2，决定使用多协程并发处理：

使用视角+uuid 方式分离-i参数给的合并输入文件命名，分离多协程之间的干扰；
利用sync.WaitGroup 和 context.Context 来协同父子进程，在子进程完成多个视角切片后，解除阻塞，继续后面的流程tar-> 分片上传；

结果

ffmpeg -i rtmp://xxxxx:1935/yyyy/zzzz/vision -c:v copy -flags +cgop -g 0 -hls_flags program_date_time -hls_list_size 0 -hls_time 10 /app/data/record.m3u8 -y 大幅减少cpu 资源消耗
ffmpeg -y -hide_banner -ss 00:00:18 -t 00:00:40 -i xxx.m3u8 -c copy -hls_list_size 0 ./output.m3u8 seek 快速定位，避免读取开头的切片，并发协同

Memory_fence

Sun, 06 Jul 2025 15:19:34 +0800

cpp 内存序

cpp 的内存序在以往开发的经历中很少有相关的需求，因此也一直没去学，近期在交流群里面谈到这方面技术后，对相关的知识做一个串联，整理成此篇笔记；

内存屏障

说到cpp 的内存序，先不去罗列有几种内存序，首先内存屏障在cpp11 和c11 版本中就已经正式发布，其声明为 extern "C" void atomic_thread_fence( std::memory_order order ) noexcept; 下面是其三种内存屏障:

在 x86（包括 x86-64）上，atomic_thread_fence 函数不发出 CPU 指令，仅影响编译时代码移动，但 std::atomic_thread_fence(std::memory_order_seq_cst) 除外。 atomic_thread_fence 施加的同步约束比具有相同 std::memory_order 的原子存储操作更强。虽然原子存储-释放操作阻止所有先前的读取和写入移动到存储-释放之后，但具有 std::memory_order_release 排序的 atomic_thread_fence 阻止所有先前的读取和写入移动到所有后续存储之后。

可以发现这三种内存屏障是约束编译时内存操作的顺序，然后解释释放和获取两种屏障，先具体到一个线程内，线程内的操作在插入释放屏障时，语义上应该在插入点之前执行的操作都应该在之前生效，不可被放到屏障之后去执行；获取屏障则是相反，是约束插入屏障后的操作不可以被提前执行，这个约束不是使用在单线程中的，因为单线程中使用最宽松的Relaxed 内存序，也就是能保证最终原子数据值的一致性就行。
在多线程并发的场景中，如果使用原子量作为条件来约束多个线程之前的多个操作的条件，就需要注意这点，以免因为重排序，使得单个线程中语义上被原子量保证的内存操作，在跨线程的场景中被提前读到，或者延后写入。

内存序

现在回到内存序上来，其表现上就是原子读前写后插入（release/acquire）两种相应的内存屏障，来保证跨线程的内存操作数据，是一种轻量级的同步机制，其中对应的开销更重的互斥锁的加解锁操作，内部本身就携带了内存屏障，内存序主要是用于多线程并发场景中的无锁并发数据结构，或者在高性能场景中避免直接加锁带来的性能瓶颈。

下面给出一个伪代码解释的两组内存序的使用场景，来帮助理解这个知识点：

memory_order_acquire/memory_order_release 读写内存序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// 生产者线程（事务提交）
std::atomic<bool> transaction_complete(false);
void commit_transaction() {
 // 1. 写入事务数据到数据库
 write_data_to_database(...);
 // 2. 使用Release语义标记事务完成
 transaction_complete.store(true, std::memory_order_release);
}

// 消费者线程（读取事务结果）
void read_transaction() {
 // 1. 使用Acquire语义检查事务状态
 while (!transaction_complete.load(std::memory_order_acquire));
 // 2. 确保能看到事务提交前的所有写入
 read_data_from_database(...);
}

memory_order_acq_rel 读写同步内存序，这个会禁用读前写后的重排序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


std::atomic<int> connection_count(0);
std::mutex pool_mutex;

Connection* acquire_connection() {
 // 1. 使用AcqRel语义原子地增加连接计数
 int count = connection_count.fetch_add(1, std::memory_order_acq_rel);
 if (count < MAX_CONNECTIONS) {
 // 有可用连接，无需加锁
 return get_connection_from_pool();
 }
 // 无可用连接，加锁等待
 std::lock_guard<std::mutex> lock(pool_mutex);
 // ...
}

void release_connection(Connection* conn) {
 // 1. 使用AcqRel语义原子地减少连接计数
 connection_count.fetch_sub(1, std::memory_order_acq_rel);
 // 2. 将连接放回池中
 return_connection_to_pool(conn);
}

Gmtls

Thu, 03 Jul 2025 15:27:35 +0800

双向认证

最近的一个项目合规要求使用国密算法实现双向认证，这里就将国密和常见的X509 RSA 的双向认证的实现都分享一下

RSA 双向认证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


import (
 "crypto/tls"
 "crypto/x509"
 "io/ioutil"
 "net"
)
func UseX509TLS(carootpath,certpath,keypath string)(*tls.Config,error){
 certPool := x509.NewCertPool()
 cacert, err := ioutil.ReadFile(carootpath)
 if err != nil {
 return nil, err
 }
 certPool.AppendCertsFromPEM(cacert)
 authKeypair, err := tls.LoadX509KeyPair(certpath, keypath)
 if err != nil {
 return nil, err
 }
 return &tls.Config{
 MaxVersion: tls.VersionTLS12,
 RootCAs: certPool,
 Certificates: []tls.Certificate{authKeypair},
 InsecureSkipVerify: false,
 }, nil
}

func ClientConn(addr string)(*net.Conn,error){
 // 三个分别是 ca证书路径，客户端证书路径，客户端私钥路径
 cfg,err := UseX509TLS("ca.crt","client.crt","client.key")
 //
 conn,err := tls.Dial("tcp", addr, cfg)
 if err!= nil{
 return nil, err
 }
 return &conn, nil
}

这里的客户端证书和密钥是给服务端用于认证客户端的身份，同时使用指定的ca 根证书这里用在mqtt 上就很简单了，甚至不用写连接创建的函数opts.SetTLSConfig(tlsConfig) 里面将tls 配置进去，mqtt 库会自动完成

国密双向认证

这里就比较复杂一些了，因为目前go 的标准库的暂不支持国密认证，需要使用github.com/tjfoc/gmsm 这个仓库，来建立国密认证连接，仅配置tls 是不行的，需要

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46



func GMTLSDialer(broker string, ca, key, cert string) (net.Conn, error) {
 cfg, err := BothAuthConfig(ca, key, cert)
 if err != nil {
 return nil, err
 }
 addr := broker
 if strings.HasPrefix(broker, "mqtt://") {
 addr = broker[7:]
 }
 fmt.Printf("addr: %s\n", addr)
 conn, err := gmtls.Dial("tcp", addr, cfg)
 if err != nil {
 return nil, err
 }
 return conn, nil
}

func BothAuthConfig(ca, key, cert string) (*gmtls.Config, error) {
 // 信任的根证书
 certPool := x509.NewCertPool()
 cacert, err := os.ReadFile(ca)
 if err != nil {
 return nil, err
 }
 certPool.AppendCertsFromPEM(cacert)
 authKeypair, err := gmtls.LoadX509KeyPair(cert, key)
 if err != nil {
 return nil, err
 }
 return &gmtls.Config{
 GMSupport: &gmtls.GMSupport{},
 RootCAs: certPool,
 Certificates: []gmtls.Certificate{authKeypair},
 InsecureSkipVerify: false,
 }, nil

}

func MqttOpenConnectionFn(uri *url.URL, options mqtt.ClientOptions) (net.Conn, error) {
 return cert.GMTLSDialer(cfg.Mqtt.Addr,
 "ca.crt",
 "client.crt",
 "client.key"，
 )
}

最后如何在mqtt 中使用呢opts.SetCustomOpenConnectionFn(MqttOpenConnectionFn) 这样就行

Rustmod

Mon, 19 May 2025 17:09:22 +0800

rust 项目组织

项目结构

1
2
3
4
5
6
7
8


.
├── Cargo.toml
└── src
 ├── deno
 │ ├── data.rs
 │ └── hello.rs
 ├── deno.rs
 └── main.rs

主代码示例

首先声明mod deno; 表明从 src/deno.rs 中导入mod 定义

1
2
3
4
5
6
7


mod deno;
use deno::hello;
use deno::get_data;
fn main() {
 hello("panda");
 print!("data: {}",get_data());
}

模块示例

这里先声明 src/deno 目录下的两个子模块，通过pub use 从当前模块中导出定义的两个函数 deno.rs

1
2
3
4


mod data;
mod hello;
pub use self::hello::hello;
pub use self::data::get_data;

data.rs

1
2
3


pub fn get_data()->&'static str{
 return "data";
}

hello.rs

1
2
3


pub fn hello(name:&str){
 println!("Hello ,{}",name);
}

备注

这里是一个最简单的mod 组织示例，用于快速回忆rust 的代码组织概念

sse

Fri, 18 Apr 2025 12:33:29 +0800

sse gin 的花式推送

众所周知ai llm 这些东西让SSE 这个技术传遍"石河子"东西南北

其实按照推送技术来说还是有不少的：

chunk 分块这个其实是SSE 的基础
sse 服务端推送事件
websocket 这个可以支持双向的，但是无法兼容h2

代码示例

下面给一下处了 websocket 以外的推送示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72


func ChunkDemo(c *gin.Context) {
 w := c.Writer
 header := w.Header()
 header.Set("Transfer-Encoding", "chunked")
 header.Set("Content-Type", "text/html")
 w.WriteHeader(http.StatusOK)
 w.Write([]byte(`
 <html>
 <body>
 `))
 w.(http.Flusher).Flush()
 for i := 0; i < 10; i++ {
 w.Write([]byte(fmt.Sprintf(`
 <h1>%d</h1>
 `, i)))
 w.(http.Flusher).Flush()
 time.Sleep(time.Duration(1) * time.Second)
 }
 w.Write([]byte(`

 </body>
 </html>
 `))
 w.(http.Flusher).Flush()
 })
// h1 sse
func sseHandlerHTTP1(c *gin.Context) {
 // 设置响应头
 c.Writer.Header().Set("Content-Type", "text/event-stream")
 c.Writer.Header().Set("Cache-Control", "no-cache")
 c.Writer.Header().Set("Connection", "keep-alive")
 c.Writer.Header().Set("Access-Control-Allow-Origin", "*")

 // 确保响应头被立即发送
 c.Writer.(http.Flusher).Flush()

 ticker := time.NewTicker(2 * time.Second)
 defer ticker.Stop()

 for {
 select {
 case <-c.Request.Context().Done():
 return
 case t := <-ticker.C:
 // 发送SSE消息
 c.Writer.Write([]byte("data: " + t.Format(time.RFC3339) + "\n\n"))
 c.Writer.(http.Flusher).Flush()
 }
 }
}
func sseHandlerHTTP2(c *gin.Context) {
 // 设置响应头
 c.Writer.Header().Set("Content-Type", "text/event-stream")
 c.Writer.Header().Set("Access-Control-Allow-Origin", "*")

 // 确保响应头被立即发送
 c.Writer.(http.Flusher).Flush()

 ticker := time.NewTicker(2 * time.Second)
 defer ticker.Stop()

 for {
 select {
 case <-c.Request.Context().Done():
 return
 case t := <-ticker.C:
 // 发送SSE消息
 c.Writer.Write([]byte("data: " + t.Format(time.RFC3339) + "\n\n"))
 c.Writer.(http.Flusher).Flush()
 }
 }
}

上面的区别其实是 h2 不用设置客户端缓存控制这个响应头, 比较统一的是推送开始和结束都需要Flush 刷写一下

otle

Fri, 18 Apr 2025 12:33:17 +0800

链路追踪示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90


package main

import (
 "context"
 "log"
 "net/http"

 "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
 "go.opentelemetry.io/otel"
 "go.opentelemetry.io/otel/attribute"
 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
 "go.opentelemetry.io/otel/propagation"
 "go.opentelemetry.io/otel/sdk/resource"
 tracesdk "go.opentelemetry.io/otel/sdk/trace"
 semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
)

// initTracer 初始化 OpenTelemetry 追踪器
func initTracer() (*tracesdk.TracerProvider, error) {
 ctx := context.Background()

 // 创建一个 OTLP HTTP 导出器
 exp, err := otlptracehttp.New(ctx,
 otlptracehttp.WithInsecure(),
 otlptracehttp.WithEndpoint("localhost:4318"),
 )
 if err != nil {
 return nil, err
 }

 // 创建资源，指定服务名称
 r, err := resource.Merge(
 resource.Default(),
 resource.NewWithAttributes(
 semconv.SchemaURL,
 semconv.ServiceName("my-http-service"),
 ),
 )
 if err != nil {
 return nil, err
 }

 // 创建追踪器提供程序
 tp := tracesdk.NewTracerProvider(
 tracesdk.WithBatcher(exp),
 tracesdk.WithResource(r),
 )

 // 设置全局传播器
 otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{}))
 // 设置全局追踪器提供程序
 otel.SetTracerProvider(tp)

 return tp, nil
}

func main() {
 // 初始化追踪器
 tp, err := initTracer()
 if err != nil {
 log.Fatalf("Failed to initialize tracer: %v", err)
 }
 defer func() {
 if err := tp.Shutdown(context.Background()); err != nil {
 log.Printf("Error shutting down tracer provider: %v", err)
 }
 }()

 // 定义一个简单的 HTTP 处理函数
 http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
 // 创建一个新的 span
 ctx, span := otel.Tracer("example-tracer").Start(r.Context(), "handle-root")
 defer span.End()

 // 添加一些属性到 span
 span.SetAttributes(attribute.String("http.method", r.Method))

 // 模拟一些工作
 w.WriteHeader(http.StatusOK)
 w.Write([]byte("Hello, World!"))
 })

 // 使用 otelhttp 包装 HTTP 处理程序
 http.Handle("/", otelhttp.NewHandler(http.DefaultServeMux, "my-http-service"))

 log.Println("Starting server on :8080")
 if err := http.ListenAndServe(":8080", nil); err != nil {
 log.Fatalf("Failed to start server: %v", err)
 }
}

示例代码很明确了，另外就是使用 otle 作为exporter 时可以通过环境变量来配置endpoint 端点 OTEL_EXPORTER_OTLP_ENDPOINT 这样可以不用Option 显式配置更加灵活

记一次helm部署重构实践

Thu, 10 Apr 2025 16:05:57 +0800

记一次helm 部署重构实践

背景: 项目上会通过一个自研的部署管理平台来向设备上推送服务部署，随着时间和合作项目的增多，我负责业务的服务也多起来了，为了简化项目管理，将同业务的项目的部署整合的需求被发下来了：

需要支持多项目组合，通过values.yaml 来选择不同的项目部署方案

要兼容现有部署平台，避免额外的修改

依赖和子Charts

我们内部用的部署方案是 helm chart ，基于这一点最简单的组合策略就是通过依赖和condtion 的组合来控制不同依赖的子chart 是否被启用。要实现这一方案有以下的几点需要注意：

condition 所引用的key 如果在values 中访问不到，默认会是启用，所以需要在values 中显式禁用未使用的服务
使用依赖去实现多应用组合部署需要，增加一个更新或者构建helm 依赖的流程：
- helm dependency update
- helm dependency build
构建时通过 –set 传入的变量，只能通过 global 来传递给子Chart ，因为values 中显式覆盖子Chart 的变量才会在子Chart 中生效

上述 1. 2两点是迫使我放弃子Chart 方案的主要原因

使用条件模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


{{ if and ( hasKey .Values "service_xxx") .Values.service_xxx.enabled }}
{{ $projectScopeValue := .Values.service_xxx }}
{{ $projectName := "your-project-name" }}
apiVersion: v1
kind: ConfigMap
metadata:
 namespace: yourNamespace
 name: {{ printf "%-configmap" $projectName }}
data:
{{ (.Files.Glob (printf "%s/etc/*" $projectName)).AsConfig | indent 2 }}
-----
{{- $customValues := tpl (.Files.Get (printf "%s/%s" $projectName (default "values.yaml" $projectScopeValue.valuesFile) )) . | fromYaml -}}
apiVersion: apps/v1
kind: Deployment
metadata:
 namespace: yourNamespace
 name: {{ $projectName }}
.....
spec:
 selector:
 matchLabels:
 ....
 replicas: 1
 strategy:
 type: RollingUpdate
 template:
 metadata:
 labels:
 .....
 spec:
 containers:
 - name: yourImageName
 image: "yourImage:{{ $customValues.imageVersion }}"
 imagePullPolicy: IfNotPresent
 tty: true
 securityContext:
 privileged: true
 env:
 - name: TZ
 value: 'Asia/Shanghai'

{{ end }}

上述模板文件中通过最外围的 service_xxx.enabled 的values 变量来控制使用启用服务，同时不显式声明为true 的情况下，服务默认不会启用
可以通过.Values.xxx 来传递一些和部署环境有关的控制信息
将原始存储镜像版本号和指定运行时配置的数据通过嵌套子目录给复用上了，同时在自动构建过程中各个服务的镜像版本号更新也可以通过子目录隔离来减小风险

如下values模板 示例说明了如何灵活配置组合不同服务和配置文件

1
2
3
4
5
6
7


# 修改 配置项，对应 chart 配置文件目录名
service_a:
 enabled: true
 config_file: config.test # 可以用来指定非子目录下的 etc 中使用的配置文件 
service_b:
 enabled: true # 是否启用此服务，默认关闭
 valuesFile: values.yaml  # 可以用来指定非子目录的 values 文件中的镜像版本号

目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


--project-a/
--.--etc/
---.--test.yaml
---.--default.yaml # 不同values 配置
--project-b/
--templates/
--.--a.deploy.yaml
--.--b.deploy.yaml
--Chart.yaml
--values-a.yaml
--values-b.yaml

简单的restful http client 包实现

Thu, 03 Apr 2025 18:13:44 +0800

一个restful http client 实现

主要是基于日常开发中遇到的常见http 请求需求，做了简单的封装，不做过度设计, 特点是：

链式调用

响应处理

原始响应缓存

易于复用

代码实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160


package httpx

import (
 "bytes"
 "encoding/json"
 "io"
 "net/http"

 "github.com/rs/zerolog/log"
)

type HttpClientX struct {
 header http.Header
 query map[string]string
 tmpBody *bytes.Buffer
 tmpResp *bytes.Buffer
 respStautCode int
 respErr error
}

func NewHttpClientX() *HttpClientX {
 return &HttpClientX{
 header: make(http.Header),
 query: make(map[string]string),
 tmpBody: bytes.NewBuffer(nil),
 tmpResp: bytes.NewBuffer(nil),
 }
}

func (h *HttpClientX) SetHeader(k, v string) *HttpClientX {
 h.header.Set(k, v)
 return h
}

func (h *HttpClientX) ClearHeader() *HttpClientX {
 h.header = make(http.Header)
 return h
}
func (h *HttpClientX) SetContentType(v string) *HttpClientX {
 h.header.Set("Content-Type", v)
 return h
}
func (h *HttpClientX) AddHeader(k, v string) *HttpClientX {
 h.header.Add(k, v)
 return h
}
func (h *HttpClientX) SetAuthorization(v string) *HttpClientX {
 h.header.Set("Authorization", v)
 return h
}

func (h *HttpClientX) SetQuery(k, v string) *HttpClientX {
 h.query[k] = v
 return h
}

func (h *HttpClientX) ClearQuery() *HttpClientX {
 h.query = make(map[string]string)
 return h
}

func (h *HttpClientX) Post(url string, obj any) *HttpClientX {
 return h.request("Post", url, obj)
}

func (h *HttpClientX) Get(url string) *HttpClientX {
 return h.request("Get", url, nil)
}

func (h *HttpClientX) Put(url string, obj any) *HttpClientX {
 return h.request("Put", url, obj)
}

func (h *HttpClientX) Delete(url string, obj any) *HttpClientX {
 return h.request("Delete", url, obj)
}

func (h *HttpClientX) request(method, url string, obj any) *HttpClientX {
 var body io.Reader
 if obj != nil {
 h.tmpBody.Reset()
 buf, err := json.Marshal(obj)
 if err != nil {
 log.Error().Err(err).Msg("SetBody")
 return h
 }
 h.tmpBody.Write(buf)
 body = h.tmpBody
 }

 req, err := http.NewRequest(method, url, body)
 if err != nil {
 log.Error().Err(err).Msg(method)
 h.respErr = err
 return h
 }

 if h.header["Content-Type"] == nil {
 req.Header.Set("Content-Type", "application/json")
 }
 for k, v := range h.header {
 if len(v) == 1 {
 req.Header.Set(k, v[0])
 }
 }
 if len(h.query) > 0 {
 q := req.URL.Query()
 for k, v := range h.query {
 q.Set(k, v)
 }
 req.URL.RawQuery = q.Encode()
 }
 resp, err := http.DefaultClient.Do(req)
 if err != nil {
 log.Error().Err(err).Msg(method)
 h.respErr = err
 return h
 }
 defer resp.Body.Close()
 h.respStautCode = resp.StatusCode
 h.tmpResp.Reset()
 _, err = io.Copy(h.tmpResp, resp.Body)
 if err != nil {
 log.Error().Err(err).Msg(method)
 h.tmpResp.Reset()
 h.respErr = err
 return h
 }
 return h
}

// 应该是用指针对象
func (h *HttpClientX) Then(obj any) *HttpClientX {
 if h.respErr != nil {
 return h
 }
 if len(h.tmpResp.Bytes()) == 0 {
 return h
 }
 if err := json.Unmarshal(h.tmpResp.Bytes(), obj); err != nil {
 log.Error().Err(err).Msg("Then")
 h.respErr = err
 }
 return h
}

func (h *HttpClientX) Catch(errHandle func(error)) *HttpClientX {
 if h.respErr != nil {
 errHandle(h.respErr)
 }
 return h
}

func (h *HttpClientX) GetRawResp() string {
 return h.tmpResp.String()
}

func (h *HttpClientX) GetStatusCode() int {
 return h.respStautCode
}

使用注意

先设置 header 和 query
可以设置 Content-Typ
然后通过 POST/PUT/GET/DELETE 发起实际请求
通过 Then 和 Catch 来解析响应类型，这里只是简单的做了Json 解析，可以自行扩展
可以通过GetRawResp和GetStatusCode 获取原始响应和响应状态码，避免json 解析错误后丢失原始内容

Webrtc_go Turn 服务器相关

Fri, 27 Dec 2024 14:10:10 +0800

Turn 服务

在常用的 Webrtc 教程中通常会为ICE 引入Stun 或者Turn 服务，一般可以用谷歌或者Cloudflare 提供的 stun 服务，也有用开源项目自行搭建的，这里主要是介绍Pion Turn 库的使用方法。

Credentials 长期凭证

1
2
3
4


 u, p, _ := turn.GenerateLongTermCredentials(*authSecret, time.Minute)
 if _, err := os.Stdout.WriteString(fmt.Sprintf("%s=%s", u, p)); err != nil { // For use with xargs
 log.Panicf("Failed to write to stdout: %s", err)
 }

核心就是根据鉴权secret 生成长期凭证

简单的STUN

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


package main

import (
 "flag"
 "log"
 "net"
 "os"
 "os/signal"
 "strconv"
 "syscall"

 "github.com/pion/turn/v4"
)

func main() {
 publicIP := flag.String("public-ip", "", "IP Address that STUN can be contacted by.")
 port := flag.Int("port", 3478, "Listening port.")
 flag.Parse()

 if len(*publicIP) == 0 {
 log.Fatalf("'public-ip' is required")
 }

 // Create a UDP listener to pass into pion/turn
 // pion/turn itself doesn't allocate any UDP sockets, but lets the user pass them in
 // this allows us to add logging, storage or modify inbound/outbound traffic
 udpListener, err := net.ListenPacket("udp4", "0.0.0.0:"+strconv.Itoa(*port))
 if err != nil {
 log.Panicf("Failed to create STUN server listener: %s", err)
 }

 s, err := turn.NewServer(turn.ServerConfig{
 // PacketConnConfigs is a list of UDP Listeners and the configuration around them
 PacketConnConfigs: []turn.PacketConnConfig{
 {
 PacketConn: udpListener,
 // RelayAddressGenerator: &turn.RelayAddressGeneratorPortRange{
 // RelayAddress: net.ParseIP(*publicIP),
 // Address: "0.0.0.0", // But actually be listening on every interface
 // MinPort: 50000,
 // MaxPort: 55000,
 // },
 },
 },
 })
 if err != nil {
 log.Panic(err)
 }

 // Block until user sends SIGINT or SIGTERM
 sigs := make(chan os.Signal, 1)
 signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
 <-sigs

 if err = s.Close(); err != nil {
 log.Panic(err)
 }
}

这里需要的公网IP 应该用于做中继的，通过RelayAddressGenerator 系列函数来实现一个动态负载均衡？上述turn.NewServer 函数的参数中，可以添加鉴权hanlder

鉴权机制

1
2
3
4
5
6


AuthHandler: func(username string, realm string, srcAddr net.Addr) ([]byte, bool) { // nolint: revive
 if key, ok := usersMap[username]; ok {
 return key, true
 }
 return nil, false
 },

这个可以和内置的两种LongTermTURNRESTAuthHandler处理时间:用户名对应的验证对应GenerateLongTermTURNRESTCredentials; NewLongTermAuthHandler 处理长期凭证的验证,对应GenerateLongTermCredentials 可以先过滤对应鉴权的用户是否存在，再进行下一步的验证中间注释的RelayAddressGenerator 中继地址生成器的配置，可以用于控制中继端口的分配范围，配合防火墙来使用

传输层

Turn 支持udp、tcp、tls，配置起来也很简单，直接在turn.NewServer 函数中添加ListenerConfigs.Listener,例如使用TLS 的tcp 协议

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// 这里两个 File 参数指向的是文件路径
cer, err := tls.LoadX509KeyPair(*certFile, *keyFile)
 if err != nil {
 log.Println(err)
 return
 }

 // Create a TLS listener to pass into pion/turn
 // pion/turn itself doesn't allocate any TLS listeners, but lets the user pass them in
 // this allows us to add logging, storage or modify inbound/outbound traffic
 tlsListener, err := tls.Listen("tcp4", "0.0.0.0:"+strconv.Itoa(*port), &tls.Config{
 MinVersion: tls.VersionTLS12,
 Certificates: []tls.Certificate{cer},
 })
 if err != nil {
 log.Println(err)
 return
 }
s, err := turn.NewServer(turn.ServerConfig{
 Realm: *realm,
 // Set AuthHandler callback
 // This is called every time a user tries to authenticate with the TURN server
 // Return the key for that user, or false when no user is found
 AuthHandler: func(username string, realm string, srcAddr net.Addr) ([]byte, bool) { // nolint: revive
 if key, ok := usersMap[username]; ok {
 return key, true
 }
 return nil, false
 },
 // ListenerConfig is a list of Listeners and the configuration around them
 ListenerConfigs: []turn.ListenerConfig{
 {
 Listener: tlsListener,
 RelayAddressGenerator: &turn.RelayAddressGeneratorStatic{
 RelayAddress: net.ParseIP(*publicIP),
 Address: "0.0.0.0",
 MinPort: 50000,
 MaxPort: 55000,
 },
 },
 },
 })

实现黑名单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


 var permissions turn.PermissionHandler = func(clientAddr net.Addr, peerIP net.IP) bool {
 for _, cidr := range conf.TurnDenyPeersParsed {
 if cidr.Contains(peerIP) {
 return false
 }
 }

 return true
 }
 _, err = turn.NewServer(turn.ServerConfig{
 Realm: Realm,
 AuthHandler: svr.authenticate,
 // TCP 连接
 ListenerConfigs: []turn.ListenerConfig{
 {Listener: tcpListener, RelayAddressGenerator: gen, PermissionHandler: permissions},
 },
 // UDP 连接
 PacketConnConfigs: []turn.PacketConnConfig{
 {PacketConn: udpListener, RelayAddressGenerator: gen, PermissionHandler: permissions},
 },
 })

使用多线程

使用多线程，看着更像是多个监听线程，所以会有端口重用的需要

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


 addr, err := net.ResolveUDPAddr("udp", "0.0.0.0:"+strconv.Itoa(*port))
 // Create `numThreads` UDP listeners to pass into pion/turn
 // pion/turn itself doesn't allocate any UDP sockets, but lets the user pass them in
 // this allows us to add logging, storage or modify inbound/outbound traffic
 // UDP listeners share the same local address:port with setting SO_REUSEPORT and the kernel
 // will load-balance received packets per the IP 5-tuple
 listenerConfig := &net.ListenConfig{
 Control: func(network, address string, conn syscall.RawConn) error { // nolint: revive
 var operr error
 if err = conn.Control(func(fd uintptr) {
 // 将socket 关联的fd 描述符配置成 通用套接字配置 地址和端口重用
 operr = syscall.SetsockoptInt(int(fd), syscall.SOL_SOCKET, unix.SO_REUSEPORT, 1)
 }); err != nil {
 return err
 }

 return operr
 },
 }

 relayAddressGenerator := &turn.RelayAddressGeneratorStatic{
 RelayAddress: net.ParseIP(*publicIP), // Claim that we are listening on IP passed by user
 Address: "0.0.0.0", // But actually be listening on every interface
 }

 packetConnConfigs := make([]turn.PacketConnConfig, *threadNum)
 for i := 0; i < *threadNum; i++ {
 // 创建一个可以用的本地UDP 监听器
 // 要用net.Listen
 conn, listErr := listenerConfig.ListenPacket(context.Background(), addr.Network(), addr.String())
 if listErr != nil {
 log.Fatalf("Failed to allocate UDP listener at %s:%s", addr.Network(), addr.String())
 }

 packetConnConfigs[i] = turn.PacketConnConfig{
 PacketConn: conn,
 RelayAddressGenerator: relayAddressGenerator,
 }

 log.Printf("Server %d listening on %s\n", i, conn.LocalAddr().String())
 }

总体来说Pione/turn 还是挺简单易用的；

Kafka_go

Fri, 27 Dec 2024 11:43:59 +0800

Kafka_go

主要是记录下 sarama 库的部署和使用，异步生产者的实现注意

docker compose 部署

首先注意下 kafka 数据包所有者

1

chown 1001:1001 ./data

下面是 docker-compose.yaml 文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


 name: "kafka"
 services:
 kafka:
 image: 'bitnami/kafka:3.6.2'
 container_name: kafka
 restart: always
 ulimits:
 nofile:
 soft: 65536
 hard: 65536
 environment:
 - TZ=Asia/Shanghai
 - KAFKA_CFG_NODE_ID=0
 - KAFKA_CFG_PROCESS_ROLES=controller,broker
 - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=0@kafka:9093
 - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093,EXTERNAL://:9094
 - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092,EXTERNAL://127.0.0.1:9094
 - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,EXTERNAL:PLAINTEXT
 - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
 networks:
 - app-tier
 ports:
 - '9092:9092'
 - '9094:9094'
 volumes:
 - ./data:/bitnami/kafka
 networks:
 app-tier:
 name: app-tier
 driver: bridge

注意这里仅仅是非集群模式的部署

代码与结果

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136


package main

import (
 "context"
 "errors"
 "fmt"
 "os"
 "os/signal"
 "sync"
 "syscall"
 "time"

 "github.com/IBM/sarama"
)

var version = sarama.DefaultVersion
var eps = []string{"127.0.0.1:9094"}
var wg sync.WaitGroup

func Producer(topic string, ctx context.Context) {
 defer wg.Done()
 config := sarama.NewConfig()
 config.Version = version
 config.Producer.RequiredAcks = sarama.NoResponse
 config.Producer.Compression = sarama.CompressionSnappy
 config.Producer.Return.Successes = true
 producer, err := sarama.NewAsyncProducer(eps, config)
 if err != nil {
 panic(err)
 }
 defer producer.Close()
 // 注意这里一定要让这些等结果的协程先行退出
 iwg := &sync.WaitGroup{}
 iwg.Add(1)
 go func(ctx context.Context, p sarama.AsyncProducer) {
 iwg.Done()
 for {
 select {
 case <-ctx.Done():
 return
 case err := <-p.Errors():
 fmt.Println(err)
 case <-p.Successes():
 }
 }
 }(ctx, producer)
 cnt := 1
 for {
 msg := &sarama.ProducerMessage{
 Topic: topic,
 Value: sarama.StringEncoder(fmt.Sprintf("hello %d", cnt)),
 }
 select {
 case <-ctx.Done():
 // 等待子协程退出
 iwg.Wait()
 return
 case producer.Input() <- msg:
 cnt++
 }
 time.Sleep(1 * time.Second)
 }

}

type TestKafkaGroup struct {
 ctx context.Context
}

func (t *TestKafkaGroup) Setup(session sarama.ConsumerGroupSession) error {
 fmt.Println("setup")
 return nil
}
func (t *TestKafkaGroup) Cleanup(session sarama.ConsumerGroupSession) error {
 fmt.Println("cleanup")
 return nil
}

func (t *TestKafkaGroup) ConsumeClaim(session sarama.ConsumerGroupSession, claim sarama.ConsumerGroupClaim) error {
 for {
 select {
 case message, ok := <-claim.Messages():
 if !ok {
 fmt.Printf("message channel was closed")
 return nil
 }
 fmt.Printf("Message claimed: value = %s, partid %d timestamp = %v\n", string(message.Value), message.Partition, message.Timestamp)
 session.MarkMessage(message, "")
 // Should return when `session.Context()` is done.
 // If not, will raise `ErrRebalanceInProgress` or `read tcp <ip>:<port>: i/o timeout` when kafka rebalance. see:
 // https://github.com/IBM/sarama/issues/1192
 case <-session.Context().Done():
 return nil
 case <-t.ctx.Done():
 return nil
 }
 }
}
func Consumer(topic string, ctx context.Context) {
 defer wg.Done()
 config := sarama.NewConfig()
 config.Version = version
 config.Consumer.Return.Errors = true
 consumer, err := sarama.NewConsumerGroup(eps, topic, config)
 if err != nil {
 fmt.Println(err)
 return
 }
 defer consumer.Close()
 tc := &TestKafkaGroup{ctx: ctx}
 for {
 if err := consumer.Consume(ctx, []string{topic}, tc); err != nil {
 fmt.Println(err)
 if errors.Is(err, sarama.ErrClosedConsumerGroup) {
 return
 }
 }
 if ctx.Err() != nil {
 return
 }

 }
}

func main() {
 ctx, cancel := context.WithCancel(context.Background())
 defer cancel()
 quit := make(chan os.Signal, 1)
 signal.Notify(quit, os.Interrupt,syscall.SIGINT, syscall.SIGTERM)
 wg.Add(1)
 go Producer("test", ctx)
 go Consumer("test", ctx)
 <-quit
 cancel()
 wg.Wait()
}

输出结果如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


setup
Message claimed: value = hello 11, partid 0 timestamp = 2024-12-27 11:29:27.321 +0800 CST
Message claimed: value = hello 1, partid 0 timestamp = 2024-12-27 11:38:33.201 +0800 CST
Message claimed: value = hello 2, partid 0 timestamp = 2024-12-27 11:38:34.201 +0800 CST
Message claimed: value = hello 3, partid 0 timestamp = 2024-12-27 11:38:35.202 +0800 CST
Message claimed: value = hello 4, partid 0 timestamp = 2024-12-27 11:38:36.202 +0800 CST
Message claimed: value = hello 5, partid 0 timestamp = 2024-12-27 11:38:37.203 +0800 CST
Message claimed: value = hello 6, partid 0 timestamp = 2024-12-27 11:38:38.203 +0800 CST
Message claimed: value = hello 7, partid 0 timestamp = 2024-12-27 11:38:39.203 +0800 CST
Message claimed: value = hello 8, partid 0 timestamp = 2024-12-27 11:38:40.203 +0800 CST
Message claimed: value = hello 9, partid 0 timestamp = 2024-12-27 11:38:41.204 +0800 CST
Message claimed: value = hello 10, partid 0 timestamp = 2024-12-27 11:38:42.206 +0800 CST
Message claimed: value = hello 11, partid 0 timestamp = 2024-12-27 11:38:43.206 +0800 CST
Message claimed: value = hello 12, partid 0 timestamp = 2024-12-27 11:38:44.206 +0800 CST
Message claimed: value = hello 13, partid 0 timestamp = 2024-12-27 11:38:45.207 +0800 CST
Message claimed: value = hello 14, partid 0 timestamp = 2024-12-27 11:38:46.208 +0800 CST
Message claimed: value = hello 15, partid 0 timestamp = 2024-12-27 11:38:47.208 +0800 CST
Message claimed: value = hello 16, partid 0 timestamp = 2024-12-27 11:38:48.209 +0800 CST
Message claimed: value = hello 17, partid 0 timestamp = 2024-12-27 11:38:49.209 +0800 CST
Message claimed: value = hello 18, partid 0 timestamp = 2024-12-27 11:38:50.21 +0800 CST
Message claimed: value = hello 19, partid 0 timestamp = 2024-12-27 11:38:51.211 +0800 CST
Message claimed: value = hello 20, partid 0 timestamp = 2024-12-27 11:38:52.211 +0800 CST
^C
cleanup

使用wails 构建桌面程序实操

Thu, 12 Dec 2024 11:47:28 +0800

Wails 构建桌面程序实操

Wails 是一个用于构建桌面应用程序的 Go 框架。官网如下 wails

简单前端项目封装

首先在 go install github.com/wailsapp/wails/v2/cmd/wails@latest 安装完wails 后用 wails doctor 来检查下依赖环境

用 wails init -n name -t -t vanilla[-ts]
- 带-ts 会从js 切换到ts
- 可以将 t 参数后面的模板换成其他例如 vue react svelte
将前端项目迁移到frontend 目录下
将项目根目录下的wails.json 和 frontend 目录下的package.json 里面的构建命令对应起来
将builid/appicon.png 替换成你想要的图标图片，最好是无背景1024*1024 大小的
下载upx 放到 path 变量所在的路径
wails build -upx -upxflags –lzma -platform windows/amd64
- 构建过程中加 -nsis 会生成安装程序（需要另外安装），
- 加-devtools 可以在软件右键开发者模式查看
- 加-webview2 指定webview 依赖处理方式
  - Download（下载）
  - Embed（内嵌）
  - Browser（浏览器）
  - Error（报错）
wails json 里面有个 info 可以给执行文件的信息里面添加你的版权信息，而且不可以被别人修改

1
2
3
4
5
6
7


"Info": {
 "companyName": "My Company Name",
 "productName": "Wails Vite",
 "productVersion": "1.0.0",
 "copyright": "Copyright©2024TigerJuice",
 "comments": "Built using Wails (https://wails.io)"
 },

顺便推广下我用wails 封装的PokeRogue 桌面程序 PokeRogueWinDesk

涉及到后端的一些数据交互

用本地网络套接字去传输，纯web 这套逻辑
使用wails 的go 函数bind，可以通过运行时js 库导入到js 当中
使用wails 提供的运行时管道，应用起来，示例如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


 func (a *App) syncWriter(str string) {
 var tmp string
 if strings.HasSuffix(str, "\n") {
 tmp = fmt.Sprintf("%s: %s", time.Now().Local().Format(time.RFC3339), str)
 } else {

 tmp = fmt.Sprintf("%s: %s\n", time.Now().Local().Format(time.RFC3339), str)
 }
 fmt.Fprintf(a.fw, tmp)
 runtime.EventsEmit(a.ctx, "sse", tmp)
}

上面这个是一个函数用来将日志消息通过管道同步到前端，前端订阅如下，

1
2
3


 EventsOn("sse", (data) => {
 printlog(data);
 });

其实整套逻辑就是pub sub 的一种实现，这个反过来前端js 去推送，后端去订阅也是一样的

项目组织结构

1
2
3
4
5
6
7
8


-project
--/build
--/frontend
--/pkg
--/wailsjs
--app.go
--main.go
--wails.json

可以通过增加 /pkg 目录来管理go 的后端逻辑，要是已经有一个后端的代码包，也可以提升到和project 同级目录下，然后通过 go mod 里面用 replace pkg v0.0.0=> ../pkg 来关联

elasticsearch learing note

Wed, 11 Dec 2024 17:02:52 +0800

elasticsearch 菜鸟查询手册

正如你所知道的那样，本人由于不擅长elk 组件，出于学习的目的对用途更加广泛的 elasticsearch 这个核心技术栈的检索api 做了初步的了解和学习

索引 & 文档

es 的文档和索引的结构如下： /<索引:_index>/<文档类型:_type>/<ID:_id>

基本操作

新增文档可以通过 PUT 方法去自动创建索引，在请求体body 中通过携带多组键值形式的字段，单个文档的提交就是这样简单查询对应文档就是对同一个路由调用 GET 方法，在响应的json 中 _source._key 的json 路径来获取键对应的字段删除对应文档也是调用同路由的DELETE 方法，指定执行删除操作的主分区可能会不可用，可以通过 timeout 参数来控制这个不可用的时间范围，删除时可以通过if_seq_no和 if_primary_term ，另外删除的时候如果路由分片指定错误，删除操作不会发生根据查询删除匹配的文档，POST /_index/_delete_by_query 更新文档也是一个套路，

1
2
3
4
5
6
7
8
9


{
 "script" : {
 "source": "ctx._source.counter += params.count",
 "lang": "painless",
 "params" : {
 "count" : 4
 }
 }
}

可以看到是通过 script 中对应 source 字段中对的简单表达式和 params 中的参数来更新数据的

Linux 工具集合

Fri, 06 Dec 2024 15:32:49 +0800

Linux 工具集合

cli类

bat 替代cat
yazi 文件浏览器
lsd 替代ls
fastfetch
SCC 代码统计
starship shell prompt
lnav 日志查看器
ripgrep 反向搜索

软件类

kitty 高性能终端模拟器
hugo 静态博客生成器
obsidian markdown 编辑器
Tiling Assiant gnome 平铺管理器
vscode
火焰截图
雾凇拼音
copyQ

语言类

uv 替代pip 和 conda 高效
ruff python lint
protoc protobuf 编译器
meson 轻量级编译构建工具
ninja 构建工具
docker 和 docker-compose 以及 dpanel

alias

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


alias hgrep="history | grep "
alias cat="bat"
alias gm="git commit -m"
alias ls="lsd -a"
alias ll="lsd -al"
alias sudo="sudo"
alias reposhow='git remote show'
alias repoadd='git remote add'
alias fy="trans :en"
alias ff="fastfetch"

Kitty

1
2
3
4
5
6
7
8
9


 include ./theme.conf
 font_family Hack Nerd Font Mono
 font_size 14.0
 window_padding_width 10
 tab_bar_min_tabs 1
 tab_bar_edge bottom
 tab_bar_style powerline
 tab_powerline_style slanted
 tab_title_template {title}{' :{}:'.format(num_windows) if num_windows > 1 else ''}

Luascript

Thu, 05 Dec 2024 14:42:14 +0800

redis Lua 实用脚本

计数器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


local key = "daily_data:".. tostring(ARGV[1])
local increment = tonumber(ARGV[2])
local currentValue = redis.call('GET', key)
if currentValue == false then
 redis.call('SET', key, increment)
 return increment
else
 local newValue = tonumber(currentValue) + increment
 redis.call('SET', key, newValue) -- redis.call('SETEX', key,86400 ,newValue)
 return newValue
end

对应的复用操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


import redis
import hashlib
r = redis.Redis() # 定义 Lua 脚本 
lua_script = """
local key = "daily_data:".. tostring(ARGV[1])
local increment = tonumber(ARGV[2])
local currentValue = redis.call('GET', key)
if currentValue == false then
 redis.call('SET', key, increment)
 return increment
else
 local newValue = tonumber(currentValue) + increment
 redis.call('SET', key, newValue)
 return newValue
end
""" # 加载脚本并获取 SHA1 校验和 
sha = r.script_load(lua_script)
# 使用已加载的脚本执行操作 
date = '20241106'
increment_value = 10
new_value = r.evalsha(sha, 2, date, increment_value)
print(f"更新后的单日累加数据：{new_value}")
# 再次使用已加载的脚本执行操作 
new_value = r.evalsha(sha, 2, date, increment_value)
print(f"再次更新后的单日累加数据：{new_value}")

对应的go 代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


const luaScript := `
local key = KEYS[1]
local change = ARGV[1]

local value = redis.call("GET", key)
if not value then
 value = 0
end

value = value + change
redis.call("SET", key, value)

return value
`
const DefaultPrefix = "Default"
func getToDayKey() string {
 return fmt.Sprintf("%s:%s", DefaultPrefix, time.Now().Local().Format(time.DateOnly))
}


func Init(){
 cmd := redis.ScriptLoad(luaScript)
 if err:= cmd.Err();err!=nil{
 log.Debug().Msgf("转载lua 脚本错误 %v",err)
 }
}


func Update(delta int)(int,err){

 var incrBy = redis.NewScript(luaScript)
 keys := getToDayKey()
 values := delta
 return incrBy.Run(ctx, rdb, keys, values...).Int()
}

分布式集群限流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15



local key = KEYS[1]
# 这里能进一步将 limit 和 window 写成常量来避免传值
local limit = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local now = tonumber(redis.call('TIME')[1])
local countKey = key.. ':'.. math.floor(now / window)
local count = tonumber(redis.call('GET', countKey) or 0)
if count < limit then
 redis.call('INCR', countKey)
 redis.call('EXPIRE', countKey, window)
 return 1
else
 return 0
end

分布式锁

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


local key = KEYS[1]
local value = ARGV[1]
local ttl = tonumber(ARGV[2])
local existingValue = redis.call('GET', key)
if existingValue == false then
 redis.call('SET', key, value, 'PX', ttl)
 return true
elseif existingValue == value then
 redis.call('PEXPIRE', key, ttl)
 return true
else
 return false
end

ebpf postgresql慢查询日志服务

Mon, 02 Dec 2024 22:36:03 +0800

ebpf postgresql慢查询日志服务

因为需要使用用户控件探针来做绑定，需要可执行文件有符号信息，所以需要在编译pg 时启用 –enable-debug

用户态程序

这里主要是实现一个日志，可以通过systemd 来管理这个慢查询日志，目前没给这个程序做配置文件管理的部分，但是实现起来也是很简单的

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164


//go:build amd64

package main

import (
 "bytes"
 "encoding/binary"
 "errors"
 "flag"
 "fmt"
 "log"
 "os"
 "os/signal"
 "path/filepath"
 "syscall"

 "github.com/cilium/ebpf/link"
 "github.com/cilium/ebpf/perf"
 "github.com/cilium/ebpf/rlimit"
 "golang.org/x/sys/unix"
)
// 这个是bpf2go 的生成代码
//go:generate go run github.com/cilium/ebpf/cmd/bpf2go -cc clang -target amd64 -type event bpf dbstats.c -- -I../headers

const (
 symbol = "exec_simple_query"
)

var binPath string
var logPath string
var logFile *os.File
var pid int
var slow int

func init() {
 flag.StringVar(&binPath, "P", "", "the path of postgres")
 flag.IntVar(&pid, "p", 0, "pid")
 flag.IntVar(&slow, "t", 200, "the threshold of slow query")
 flag.StringVar(&logPath, "l", "", "the log output file path")
}
func Config() bool {
 flag.Parse()
 if binPath == "" && pid == 0 {
 fmt.Printf("invalid argument path [%s] pid %d", binPath, pid)
 return true
 }
 if binPath == "" {
 if path, err := filepath.EvalSymlinks(fmt.Sprintf("/proc/%d/exe", pid)); err != nil {
 fmt.Printf("pid %d err %v", pid, err)
 return true
 } else {
 binPath = path
 }
 }
 if logPath != "" {
 path, err := filepath.Abs(logPath)
 if err != nil {
 fmt.Printf("get abs path failed %v\n", path)
 }
 if file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666); err != nil {
 fmt.Printf("open log file failed %v\n", err)
 } else {
 logFile = file
 log.SetOutput(file)
 }
 }
 if slow < 0 || slow > 2000 {
 return true
 }
 return false
}
func main() {
 shouldReturn := Config()
 if shouldReturn {
 return
 }
 defer func(file *os.File) {
 if file != nil {
 file.Close()
 }
 }(logFile)
 stopper := make(chan os.Signal, 1)
 signal.Notify(stopper, os.Interrupt, syscall.SIGTERM)

 // Allow the current process to lock memory for eBPF resources.
 if err := rlimit.RemoveMemlock(); err != nil {
 log.Fatal(err)
 }

 // Load pre-compiled programs and maps into the kernel.

 objs := bpfObjects{}
 if err := loadBpfObjects(&objs, nil); err != nil {
 log.Fatalf("loading objects: [%v]", err)
 }
 defer objs.Close()
 // 200ms 是慢查询上限
 objs.SlowMap.Put(0, slow)
 // Open an ELF binary and read its symbols.
 ex, err := link.OpenExecutable(binPath)
 if err != nil {
 log.Fatalf("opening executable: %s", err)
 }

 // Open a Uretprobe at the exit point of the symbol and attach
 // the pre-compiled eBPF program to it.

 up, err := ex.Uretprobe(symbol, objs.UretprobeExecSimpleQuery, nil)
 if err != nil {
 log.Fatalf("creating uretprobe: %s", err)
 }
 defer up.Close()
 do, err := ex.Uprobe(symbol, objs.UprobeExecSimpleQuery, nil)
 if err != nil {
 log.Fatalf("creating uprobe: %s", err)
 }
 defer do.Close()
 // Open a perf event reader from userspace on the PERF_EVENT_ARRAY map
 // described in the eBPF C program.
 rd, err := perf.NewReader(objs.Events, os.Getpagesize())
 if err != nil {
 log.Fatalf("creating perf event reader: %s", err)
 }
 defer rd.Close()

 go func() {
 // Wait for a signal and close the perf reader,
 // which will interrupt rd.Read() and make the program exit.
 <-stopper
 log.Println("Received signal, exiting program..")

 if err := rd.Close(); err != nil {
 log.Fatalf("closing perf event reader: %s", err)
 }
 }()

 log.Printf("Listening for events..")

 // bpfEvent is generated by bpf2go.
 var event bpfEvent
 for {
 record, err := rd.Read()
 if err != nil {
 if errors.Is(err, perf.ErrClosed) {
 return
 }
 log.Printf("reading from perf event reader: %s", err)
 continue
 }

 if record.LostSamples != 0 {
 log.Printf("perf event ring buffer full, dropped %d samples", record.LostSamples)
 continue
 }

 // Parse the perf event entry into a bpfEvent structure.
 if err := binary.Read(bytes.NewBuffer(record.RawSample), binary.LittleEndian, &event); err != nil {
 log.Printf("parsing perf event: %s", err)
 continue
 }

 log.Printf("%s:%f/ms\n", unix.ByteSliceToString(event.Cmd[:]), float64(event.Timestamp)/1000000.0)
 }
}

ebpf uprobe

这部分代码主要是对命令的拷贝和exec_simple_query函数执行的计时

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76


//go:build ignore

#include "common.h"

#include "bpf_tracing.h"

char __license[] SEC("license") = "Dual MIT/GPL";
#define MAX_DATA_LEN 256
u32 slowThreshold=0;
const u32 timebase = 1000000;
struct event {
 u64 pid;
 u64 timestamp;
 u8 cmd[MAX_DATA_LEN];

};
struct bpf_map_def SEC("maps") slow_map = {
 .type = BPF_MAP_TYPE_ARRAY,
 .key_size = sizeof(u32),
 .value_size = sizeof(u32),
 .max_entries = 1,
};

struct bpf_map_def SEC("maps") kprobe_map = {
 .type = BPF_MAP_TYPE_HASH,
 .key_size = sizeof(u64),
 .value_size = sizeof(struct event),
 .max_entries = 256,
};

struct {
 __uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY);
} events SEC(".maps");


// Force emitting struct event into the ELF.
const struct event *unused __attribute__((unused));

SEC("uretprobe/exec_simple_query")
int uretprobe_exec_simple_query(struct pt_regs *ctx) {

 u64 pid = bpf_get_current_pid_tgid()>>32;
 struct event * valp = bpf_map_lookup_elem(&kprobe_map, &pid);
 if (valp) {

 valp->timestamp = bpf_ktime_get_ns()- (valp->timestamp);
 if(slowThreshold>0||valp->timestamp>slowThreshold){

 bpf_perf_event_output(ctx, &events, BPF_F_CURRENT_CPU, valp, sizeof(struct event));
 }
 bpf_map_delete_elem(&kprobe_map, &pid);
 return 0;
 }

 return 0;
}

SEC("uprobe/exec_simple_query")
int uprobe_exec_simple_query(struct pt_regs *ctx) {
 if(slowThreshold==0){
 int key =0;
 u32 * ret = (u32*)bpf_map_lookup_elem(&slow_map, &key);
 if(ret) slowThreshold = *ret*timebase;

 }
 struct event event;

 u64 pid = bpf_get_current_pid_tgid()>>32;
 u64 ts = bpf_ktime_get_ns();
 event.pid = pid;
 event.timestamp = ts;
 char * sql_string = (char*)PT_REGS_PARM1(ctx);
 bpf_probe_read(&event.cmd,sizeof(event.cmd),sql_string);
 bpf_map_update_elem(&kprobe_map,&pid,&event,BPF_ANY);
 return 0;
}

这里因为ebp-go 没有从go 程序处修改ebpf 中全局变量的接口，这里是通过一个map array 来间接传递这个慢查询阈值，最大支持2s 的慢查询上限，要是觉得这个上限比较低，可以将数据类型改成 u64，这里理论上只会在初次触发时进行全局变量的赋值，后续使用全局变量做快速路径

etcd go 手册

Mon, 02 Dec 2024 22:36:03 +0800

ETCD 手册

KV 操作

WithIgnoreLease() 使用租约时可以用这个，当key 不存在时会返回错误 WithPrevKV() 可以返回更新前的KV值 WithIgnoreValue() 普通put 使用这个key不存在时会返回错误 WithSort(clientv3.SortByKey, clientv3.SortDescend) 可以让在查询的时候使用特定的排序方式 WithPrefix() 这可以可以按照key，查找前缀是key字符串的所有值； Get() 使用的WithRev(presp.Header.Revision) ，中的版本号可以时某次put操作返回的版本号，我觉得get的其实也是可以的；

看了下源码 ResponseHeader 这东西里面塞了： ClusterId 和这个消息交互的集群的id
MemberId 节点id Revision 消息版本 RaftTerm 选举的周期

1
2
3
4
5
6


 // 这里获取版本后，该版本之前的历史数据存储开始进行合并压缩
 // 这里会生成快照吗？ 按照文档上说这个操作应该是要定时进行的
 compRev := resp.Header.Revision // specify compact revision of your choice

 ctx, cancel = context.WithTimeout(context.Background(), requestTimeout)
 _, err = cli.Compact(ctx, compRev)

func (Maintenance).Status(ctx Context, endpoint string) 可以获取集群的状态 func (Maintenance).Defragment(ctx Context, endpoint string) 这可以开启etcd 的碎片整理

授权管理

先是简单的通过用户名密码来验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


// 这部分可以手动来进行的
// etcdctl --user root role add r
 if _, err = cli.RoleAdd(context.TODO(), "r"); err != nil {
 log.Fatal(err)
 }
// etcdctl --user root role grant-permission r foo zoo
// 使用 -prefix=true 可以仅指定开头前缀
 if _, err = cli.RoleGrantPermission(context.TODO(),"r", "foo", "zoo", clientv3.PermissionType(clientv3.PermReadWrite),); err != nil {
 log.Fatal(err)
 }
// etcdctl --user root user add u --new-user-password 123
 if _, err = cli.UserAdd(context.TODO(), "u", "123"); err != nil {
 log.Fatal(err)
 }
// etcdctl --user root user grant-role u r
 if _, err = cli.UserGrantRole(context.TODO(), "u", "r"); err != nil {
 log.Fatal(err)
 }
// etcdctl auth enable
 if _, err = cli.AuthEnable(context.TODO()); err != nil {
 log.Fatal(err)
 }

 // 这里使用 root 角色的用户来登录
 rootCli, err := clientv3.New(clientv3.Config{
 Endpoints: exampleEndpoints(),
 DialTimeout: dialTimeout,
 Username: "root",
 Password: "123",
 })
 if err != nil {
 log.Fatal(err)
 }
 defer rootCli.Close()
 // root 用户可以获取别的 用户或者角色的数据 etcdctl --user root role get r
 resp, err := rootCli.RoleGet(context.TODO(), "r")
 if err != nil {
 log.Fatal(err)
 }
 // 可以获得 角色权限的信息
 fmt.Printf("user u permission: key %q, range end %q\n", resp.Perm[0].Key, resp.Perm[0].RangeEnd)
 // 这里关闭身份校验 etcdctl auth disable
 if _, err = rootCli.AuthDisable(context.TODO()); err != nil {
 log.Fatal(err)
 }

建立客户端连接时使用的证书

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


 tlsInfo := transport.TLSInfo{
 CertFile: "/tmp/test-certs/test-name-1.pem",
 KeyFile: "/tmp/test-certs/test-name-1-key.pem",
 TrustedCAFile: "/tmp/test-certs/trusted-ca.pem",
 }
 tlsConfig, err := tlsInfo.ClientConfig()
 if err != nil {
 log.Fatal(err)
 }
 cli, err := clientv3.New(clientv3.Config{
 Endpoints: exampleEndpoints(),
 DialTimeout: dialTimeout,
 TLS: tlsConfig,
 })

事务

STM is an interface for software transactional memory. 事务使用 MVCC多版本控制，在事务执行的函数类使用 STM 来读写键值

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


// Txn 这个简单的事务接口，还是基于客户端连接来的
 kvc := clientv3.NewKV(cli)

 _, err = kvc.Put(context.TODO(), "key", "xyz")
 if err != nil {
 log.Fatal(err)
 }

 ctx, cancel := context.WithTimeout(context.Background(), requestTimeout)
 // if 条件成立 会执行 then 分支的修改，否则会执行else 分支的操作
 _, err = kvc.Txn(ctx).
 // txn value comparisons are lexical
 If(clientv3.Compare(clientv3.Value("key"), ">", "abc")).
 // the "Then" runs, since "xyz" > "abc"
 Then(clientv3.OpPut("key", "XYZ")).
 // the "Else" does not run
 Else(clientv3.OpPut("key", "ABC")).
 Commit()
//
 exchange := func(stm concurrency.STM) {
 from, to := rand.Intn(totalAccounts), rand.Intn(totalAccounts)
 if from == to {
 // nothing to do
 return
 }
 // read values
 fromK, toK := fmt.Sprintf("accts/%d", from), fmt.Sprintf("accts/%d", to)
 fromV, toV := stm.Get(fromK), stm.Get(toK)
 fromInt, toInt := 0, 0
 fmt.Sscanf(fromV, "%d", &fromInt)
 fmt.Sscanf(toV, "%d", &toInt)

 // transfer amount
 xfer := fromInt / 2
 fromInt, toInt = fromInt-xfer, toInt+xfer

 // write back
 stm.Put(fromK, fmt.Sprintf("%d", fromInt))
 stm.Put(toK, fmt.Sprintf("%d", toInt))
 return
 }

 // concurrently exchange values between accounts
 var wg sync.WaitGroup
 wg.Add(10)
 for i := 0; i < 10; i++ {
 go func() {
 defer wg.Done()
 if _, serr := concurrency.NewSTM(cli, func(stm concurrency.STM) error {
 exchange(stm)
 return nil
 }); serr != nil {
 log.Fatal(serr)
 }
 }()
 }
 wg.Wait()

普通的 kv api 其实也有一个Txn ,但是同一个key 只能修改一次

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


 orderingKv := ordering.NewKV(cli.KV,
 func(op clientv3.Op, resp clientv3.OpResponse, prevRev int64) error {
 return errOrderViolation
 })
 orderingTxn := orderingKv.Txn(ctx)
 _, err = orderingTxn.If(
 clientv3.Compare(clientv3.Value("b"), ">", "a"),
 ).Then(
 clientv3.OpGet("foo"),
 ).Commit()
 if err != nil {
 t.Fatal(err)
 }

租约

租约有点像 go 里面的上下文，租约过期时会撤销掉这期间的更改；同时在func (Lease).Revoke(ctx Context, id LeaseID) 释放租约的时候，之前修改会被视作失效了；func (Lease).KeepAliveOnce(ctx Context, id LeaseID) 可以手动续约，避免租约超期被取消了；

key 和 Lease 是多对一的关系。一个 key 最多只能挂绑定一个 Lease ，但是一个 Lease 上能挂多个 key 。租约在申请下来后，关联的操作，我觉得全是修改，会被关联到这个租约的 map 里面，这段事件应该是独占这些个 key 的所有权，所以加进来的key修改，在租约失效的时候，反向调用Txn 来删除这些key，就能把之前的版本恢复

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 lease, err := cli.Grant(context.Background(), 100)
 if err != nil {
 t.Fatal(err)
 }
 // 每个会话会有一个唯一的ID 和TTL 存活时间
 s, err := concurrency.NewSession(cli, concurrency.WithLease(lease.ID))
 if err != nil {
 t.Fatal(err)
 }
 defer s.Close()
 assert.Equal(t, s.Lease(), lease.ID)

 go s.Orphan()
 select {
 case <-s.Done():
 case <-time.After(time.Millisecond * 100):
 t.Fatal("session did not get orphaned as expected")
 }

使用租约来控制的会话会比租约更早结束，以免出现并发控制的问题？这个和上面的互斥锁连用就可以实现租约时长来控制的互斥锁，超时会退出，并撤销操作？另外可以给租约设置 TTL 也就是生存时间

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


 s, err := concurrency.NewSession(cli, concurrency.WithTTL(setTTL))
 if err != nil {
 t.Fatal(err)
 }
 defer s.Close()

 leaseID := s.Lease()
 // TTL retrieved should be less than the set TTL, but not equal to default:60 or exprired:-1
 resp, err := cli.Lease.TimeToLive(context.Background(), leaseID)
 if err != nil {
 t.Log(err)
 }
 if resp.TTL == -1 {
 t.Errorf("client lease should not be expired: %d", resp.TTL)

 }
 if resp.TTL == 60 {
 t.Errorf("default TTL value is used in the session, instead of set TTL: %d", setTTL)
 }
 if resp.TTL >= int64(setTTL) || resp.TTL < int64(setTTL)-20 {
 t.Errorf("Session TTL from lease should be less, but close to set TTL %d, have: %d", setTTL, resp.TTL)
 }

这里可以看到租约的实际时间是比设置的要短的

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 lease, err := cli.Grant(context.Background(), 100)
 if err != nil {
 t.Fatal(err)
 }
 s, err := concurrency.NewSession(cli, concurrency.WithLease(lease.ID))
 if err != nil {
 t.Fatal(err)
 }
 defer s.Close()
 assert.Equal(t, s.Lease(), lease.ID)
 // 主要是通过 会话的上下文的Done 来控制会话内操作的退出
 childCtx, cancel := context.WithCancel(s.Ctx())
 defer cancel()

 go s.Orphan()
 select {
 case <-childCtx.Done():
 case <-time.After(time.Millisecond * 100):
 t.Fatal("child context of session context is not canceled")
 }

会话和 go 原生的上下文的使用；总结一下：

租约加会话加互斥锁可以实现分布式锁
租约加会话加上下文，可以取消会话内协程的执行

分布式锁

etcd 3有个并发api ，调用这个api 可以实现分布式锁，锁会持有到主动解锁或者租期到了

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


 // 新建会话是一个标准流程表，因为下面申请锁需要通过一个会话来进行
 s1, err := concurrency.NewSession(cli)
 if err != nil {
 t.Fatal(err)
 }
 defer s1.Close()
 m1 := concurrency.NewMutex(s1, "/my-lock/")
 if err = m1.Lock(context.TODO()); err != nil {
 t.Fatal(err)
 }
 // 这之间就是s1 获得锁的临界区
 if err := m1.Unlock(context.TODO()); err != nil {
 t.Fatal(err)
 }

如果先调用解锁，会得到ErrLockReleased 也就是锁已经被释放了，或者没有获得锁，总而言之就是当前没有持有锁

服务发现和注册

实际是etcd根据mainID去磁盘查数据，磁盘中数据以revision.main+revision.sub为key(bbolt 数据库中的key)，所以就会依次遍历出所有的版本数据。同时判断遍历到的value中的key(etcd中的key)是不是用户watch的，是则推送给用户。

这里每次都会遍历数据库性能可能会很差，实际使用时一般用户只会关注最新的revision，不会去关注旧数据。

采用了MVCC，以一种优雅的方式解决了锁带来的问题。执行写操作或删除操作时不会再原数据上修改而是创建一个新版本。这样并发的读取操作仍然可以读取老版本的数据，写操作也可以同时进行。这个模式的好处在于读操作不再阻塞，事实上根本就不需要锁。客户端读key的时候指定一个版本号，服务端保证返回比这个版本号更新的数据，但不保证返回最新的数据。 MVCC能最大化地实现高效地读写并发，尤其是高效地读，非常适合读多写少的场景。

客户端使用watch 来获取服务端地址

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


 var serviceTarget = "Hello"
 type remoteService struct {
 name string
 nodes map[string]string
 mutex sync.Mutex
 }
 service = &remoteService {
 name: serviceTarget
 }
 kv := clientv3.NewKV(etcdClient)
 rangeResp, err := kv.Get(context.TODO(), service.name, clientv3.WithPrefix())
 if err != nil {
 panic(err)
 }

 service.mutex.Lock()
 for _, kv := range rangeResp.Kvs {
 service.nodes[string(kv.Key)] = string(kv.Value)
 }
 service.mutex.Unlock()

 go watchServiceUpdate(etcdClient, service)


// 监控服务目录下的事件
func watchServiceUpdate(etcdClient clientv3.Client, service *remoteService) {
 watcher := clientv3.NewWatcher(client)
 // Watch 服务目录下的更新
 watchChan := watcher.Watch(context.TODO(), service.name, clientv3.WithPrefix())
 for watchResp := range watchChan {
 // 这里对增删时间的响应，会使用互斥锁来解决并发的数据修改问题
 for _, event := range watchResp.Events {
 service.mutex.Lock()
 switch (event.Type) {
 case mvccpb.PUT://PUT事件，目录下有了新key
 service.nodes[string(event.Kv.Key)] = string(event.Kv.Value)
 case mvccpb.DELETE://DELETE事件，目录中有key被删掉(Lease过期，key 也会被删掉)
 delete(service.nodes, string(event.Kv.Key))
 }
 service.mutex.Unlock()
 }
 }
}

服务端主要是注意租约的维护

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


// 将服务注册到etcd上
func RegisterServiceToETCD(ServiceTarget string, value string) {
 dir = strings.TrimRight(ServiceTarget, "/") + "/"

 client, err := clientv3.New(clientv3.Config{
 Endpoints: []string{"localhost:2379"},
 DialTimeout: 5 * time.Second,
 })
 if err != nil {
 panic(err)
 }

 kv := clientv3.NewKV(client)
 lease := clientv3.NewLease(client)
 var curLeaseId clientv3.LeaseID = 0

 for {
 if curLeaseId == 0 {
 leaseResp, err := lease.Grant(context.TODO(), 10)
 if err != nil {
 panic(err)
 }

 key := ServiceTarget + fmt.Sprintf("%d", leaseResp.ID)
 if _, err := kv.Put(context.TODO(), key, value, clientv3.WithLease(leaseResp.ID)); err != nil {
 panic(err)
 }
 curLeaseId = leaseResp.ID
 } else {
 // 续约租约，如果租约已经过期将curLeaseId复位到0重新走创建租约的逻辑
 if _, err := lease.KeepAliveOnce(context.TODO(), curLeaseId); err == rpctypes.ErrLeaseNotFound {
 curLeaseId = 0
 continue
 }
 }
 time.Sleep(time.Duration(1) * time.Second)
 }
}

使用 watch 监视的时候 clientv3.WithRev(1) 可以指定从哪个版本开始获取，clientv3.WithFragment() 会允许服务端将事件分页发送过来

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


select {
 case ws := <-wch:
 // 没启用分页的时候，因为对应的 key 的值太大了，旧没接收到
 if !fragment && exceedRecvLimit {
 if len(ws.Events) != 0 {
 t.Fatalf("expected 0 events with watch fragmentation, got %d", len(ws.Events))
 }
 exp := "code = ResourceExhausted desc = grpc: received message larger than max ("
 if !strings.Contains(ws.Err().Error(), exp) {
 t.Fatalf("expected 'ResourceExhausted' error, got %v", ws.Err())
 }
 return
 }

 // 启用分页将每次发送的数据分成限制内大小后，拿到的分页数，这个事件本身是键值对的一个切片，里面的元素是类似CPP 的 pair 这种键值二元组
 if len(ws.Events) != 10 {
 t.Fatalf("expected 10 events with watch fragmentation, got %d", len(ws.Events))
 }
 if ws.Err() != nil {
 t.Fatalf("unexpected error %v", ws.Err())
 }

 case <-time.After(testutil.RequestTimeout):
 t.Fatalf("took too long to receive events")
 }

使用 cfg.ClientMaxCallRecvMsgSize = 1.5 * 1024 * 1024 修改集群配置时，会限制集群给客户端发送消息大小

观测

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


import(
 grpcprom "github.com/grpc-ecosystem/go-grpc-prometheus"
 "github.com/prometheus/client_golang/prometheus/promhttp"
)
 // 这样在客户端的 grpc 连接里面塞两个Prometheus的中间件进去
 cli, err := clientv3.New(clientv3.Config{
 Endpoints: exampleEndpoints(),
 DialOptions: []grpc.DialOption{
 grpc.WithUnaryInterceptor(grpcprom.UnaryClientInterceptor),
 grpc.WithStreamInterceptor(grpcprom.StreamClientInterceptor),
 },
 })
 if err!=nil{
 log.Fatal(err)
 }
 defer cli.close()
 // 开个 http 服务端
 ln, err := net.Listen("tcp", ":0")
 if err != nil {
 log.Fatal(err)
 }
 defer ln.close()
 http.Serve(ln, promhttp.Handler()) // 现在就可以被监听到了

调优

io优先级

1

sudo ionice -c2 -n0 -p `pgrep etcd`

快照触发数量

1

etcd --snapshot-count=5000

心跳和选举时间

1

 etcd --heartbeat-interval=100 --election-timeout=500

cpu

1

echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

一些维护操作

1
2
3
4
5
6
7
8
9


etcdctl member list -w table # 可以查看节点信息
etcdctl move-leader XXID --endpoints 127.0.0.1:2379
etcdctl member remove xxxID
# 重新将一个节点添加到集群里面来
etcdctl member add etcd01 --peer-urls="https://xxxxxxx:2380"
# 对某个节点存储快照
etcdctl --endpoints=https://10.184.4.240:2380 snapshot save snapshot.db
# 从节点快照恢复数据
etcdctl snapshot restore snapshot.db --name etcd01 --initial-cluster etcd01=https://10.184.4.238:2379,etcd02=https://10.184.4.239:2379,etcd03=https://10.184.4.240:2379 --initial-cluster-token etcd-cluster --initial-advertise-peer-urls https://10.184.4.238:2380

使用客户端api 也是可以实现上面的操作的

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// 添加一个 节点进来 2380 一般是这个端口，用来做集群间通信的，那个2379的是用监听客户端的
 mresp, err := cli.MemberAdd(context.Background(), []string{"http://localhost:32380"})
 if err != nil {
 log.Fatal(err)
 }
 fmt.Println("added member.PeerURLs:", mresp.Member.PeerURLs)
 fmt.Println("members count:", len(mresp.Members))

 // Restore original cluster state
 _, err = cli.MemberRemove(context.Background(), mresp.Member.ID)
 if err != nil {
 log.Fatal(err)
 }
 // 这个添加进来做从节点？
 mresp, err := cli.MemberAddAsLearner(context.Background(), []string{"http://localhost:32381"})
 if err != nil {
 log.Fatal(err)
 }
 // 这里用来获取集群的节点列表
 resp, err := cli.MemberList(context.Background())
 if err != nil {
 log.Fatal(err)
 }
 // 修改节点的内部通信地址
 peerURLs := []string{"http://localhost:12380"}
 _, err = cli.MemberUpdate(context.Background(), resp.Members[0].ID, peerURLs)
 if err != nil {
 log.Fatal(err)
 }

快照

etcd 的快照和虚拟机的快照比较类似，是摸一个时间点etcd 节点的所有数据；快照是一个checkpoint，避免因为wal 数据被无限制写入，导致体量超大，通过checkpoint做一个记录，后续的wal可以做增量，checkpoint生成的快照充当的应该是快照前的数据，发生修改后的数据会在wal上，(也不能这么说，因为wal记录本来就是修改记录)。

faketcp 原理介绍

Mon, 02 Dec 2024 22:36:03 +0800

faketcp 原理简介

背景

通过udp 实现多路传输时，可能会被运营商通过qos策略给丢掉；通过rawsocket 机制在udp报文上增加tcp 头来伪装成tcp包，通过增加一部封拆包头的代价来换取udp通信的可用性

代码实现

这里没有做具体的udp包体封装的例子，但是字节流数据传输可见是完整的，将一个udp报文转成[]byte切片来使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175



package main

import (
 "encoding/binary"
 "fmt"
 "log"
 "net"
 "sync"
 // "github.com/xitongsys/ethernet-go/header"
)

type TCP struct {
 SrcPort uint16
 DstPort uint16
 Seq uint32
 Ack uint32
 Offset uint8
 Flags uint8
 Win uint16
 Checksum uint16
 UrgPointer uint16
 Opt uint32
}

type IPv4Pseudo struct {
 Src uint32
 Dst uint32
 Reserved uint8
 Protocol uint8
 Len uint16
}

func (h *IPv4Pseudo) Marshal() []byte {
 headerLen := int(12)
 res := make([]byte, headerLen)
 binary.BigEndian.PutUint32(res[0:], h.Src)
 binary.BigEndian.PutUint32(res[4:], h.Dst)
 res[8] = byte(h.Reserved)
 res[9] = byte(h.Protocol)
 binary.BigEndian.PutUint16(res[10:], h.Len)
 return res
}

func (h *TCP) Marshal() []byte {
 res := make([]byte, 20)
 binary.BigEndian.PutUint16(res, h.SrcPort)
 binary.BigEndian.PutUint16(res[2:], h.DstPort)
 binary.BigEndian.PutUint32(res[4:], h.Seq)
 binary.BigEndian.PutUint32(res[8:], h.Ack)
 res[12] = byte(h.Offset)
 res[13] = byte(h.Flags)
 binary.BigEndian.PutUint16(res[14:], h.Win)
 binary.BigEndian.PutUint16(res[16:], h.Checksum)
 binary.BigEndian.PutUint16(res[18:], h.UrgPointer)
 return res
}

func ReCalTcpCheckSum(bs []byte, src, dst uint32) error {
 if len(bs) < 20 {
 return fmt.Errorf("too short")
 }
 ipps := IPv4Pseudo{}
 ipps.Src = src
 ipps.Dst = dst
 ipps.Reserved = 0
 ipps.Protocol = 6
 ipps.Len = uint16(len(bs))

 ippsbs := ipps.Marshal()
 tcpbs := bs
 tcpbs[16] = 0
 tcpbs[17] = 0

 if len(tcpbs)%2 == 1 {
 tcpbs = append(tcpbs, byte(0))
 }

 s := uint32(0)
 for i := 0; i < len(ippsbs); i += 2 {
 s += uint32(binary.BigEndian.Uint16(ippsbs[i : i+2]))
 }
 for i := 0; i < len(tcpbs); i += 2 {
 s += uint32(binary.BigEndian.Uint16(tcpbs[i : i+2]))
 }

 for (s >> 16) > 0 {
 s = (s >> 16) + (s & 0xffff)
 }
 binary.BigEndian.PutUint16(tcpbs[16:], ^uint16(s))
 return nil
}

// https://sourcegraph.com/github.com/xitongsys/ethernet-go@master/-/blob/header/tcp.go
func server(ch chan<- struct{}, wg *sync.WaitGroup) {
 ipaddr, _ := net.ResolveIPAddr("ip4", "127.0.0.2")
 con, err := net.ListenIP("ip4:6", ipaddr)
 if err != nil {
 log.Fatalf("tcp listening failed %+v\n", err)
 }
 buf := make([]byte, 1024)
 fmt.Printf("开始接收%v\n", con.LocalAddr())
 ch <- struct{}{}
 for range 3 {
 {
 n, from, _ := con.ReadFromIP(buf)
 if n > 20 {
 fmt.Printf("[%s] for [%s]\n", string(buf[20:n]), from.String())
 } else {
 fmt.Printf("too short %d\n", n)
 }
 }
 }
 close(ch)
 con.Close()
 wg.Done()
}

const (
 FIN = 0x01
 SYN = 0x02
 RST = 0x04
 PSH = 0x08
 ACK = 0x10
 URG = 0x20
 ECE = 0x40
 CWR = 0x80
)

func BuildTcpHeader(src, dst uint32, sport, dport uint16, flag uint8, data []byte) []byte {
 tcpheader := &TCP{
 SrcPort: sport,
 DstPort: dport,
 Seq: 1,
 Ack: 1,
 Offset: 0x50,
 Flags: flag,
 Win: ^uint16(0),
 Checksum: 0,
 UrgPointer: 0,
 }
 result := make([]byte, len(data)+20)
 copy(result, tcpheader.Marshal())
 copy(result[20:], data)
 ReCalTcpCheckSum(result, src, dst)
 return result
}

func client(ch <-chan struct{}) {
 laddr, _ := net.ResolveIPAddr("ip4", "127.0.0.3")
 raddr, _ := net.ResolveIPAddr("ip4", "127.0.0.2")
 con, err := net.DialIP("ip4:6", laddr, raddr)
 if err != nil {
 log.Fatalf("ip conn create failed %+v\n", err)
 }
 <-ch
 for i := range 3 {
 buf := BuildTcpHeader(binary.BigEndian.Uint32(laddr.IP.To4()), binary.BigEndian.Uint32(raddr.IP.To4()), 7742, 7743, SYN, []byte(fmt.Sprintf("test data packet%d", i)))
 con.Write(buf)
 }
 <-ch
 fmt.Println("has write")
 con.Close()
}

func main() {
 var wg sync.WaitGroup
 ch := make(chan struct{})
 wg.Add(1)
 go server(ch, &wg)
 fmt.Println("server start")
 client(ch)
 fmt.Println("client close")
 wg.Wait()
}

后期会补一些原理图上去

gRPC 使用手册

Mon, 02 Dec 2024 22:36:03 +0800

gRPC 使用手册

环境准备

grpc 是使用protobuf 协议的需要安装对应的编译器

1
2


 go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
 go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2

定义好 .proto 文件之后可以使用 protoc 编译器来生成对应语言的代码

1
2


protoc --go_out=./proto/ --go_opt=paths=source_relative
 --go-grpc_out=./proto/ --go-grpc_opt=paths=source_relative ./proto/your.proto

基础的流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


// 单次调用
 ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 defer cancel()
 resp, err := client.UnaryEcho(ctx, &ecpb.EchoRequest{Message: message})
 if err != nil {
 log.Fatalf("client.UnaryEcho(_) = _, %v: ", err)
 }

// 流接收
func recvMessage(stream pb.Echo_BidirectionalStreamingEchoClient, wantErrCode codes.Code) {
 res, err := stream.Recv()
 if status.Code(err) != wantErrCode {
 log.Fatalf("stream.Recv() = %v, %v; want _, status.Code(err)=%v", res, err, wantErrCode)
 }
 if err != nil {
 fmt.Printf("stream.Recv() returned expected error %v\n", err)
 return
 }
 fmt.Printf("received message %q\n", res.GetMessage())
}

// 在接受流的时候要验证 err 是不是EOF
for {
 in, err := stream.Recv()
 if err != nil {
 fmt.Printf("server: error receiving from stream: %v\n", err)
 if err == io.EOF {
 return nil
 }
 return err
 }
 fmt.Printf("echoing message %q\n", in.Message)
 stream.Send(&pb.EchoResponse{Message: in.Message})
 }

OAuth token 验证

因为有两种rpc 调用一种是单次调用一种是流式调用；在客户端 client 建立连接时使用的opts 中使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// fetchToken 表示获取token 的动作,使用 tokensource 获取带时效时间的 token
 perRPC := oauth.TokenSource{TokenSource: oauth2.StaticTokenSource(fetchToken())}
 creds, err := credentials.NewClientTLSFromFile(data.Path("x509/ca_cert.pem"), "x.test.example.com")
 if err != nil {
 log.Fatalf("failed to load credentials: %v", err)
 }
 opts := []grpc.DialOption{
 // In addition to the following grpc.DialOption, callers may also use
 // the grpc.CallOption grpc.PerRPCCredentials with the RPC invocation
 // itself.
 // See: https://godoc.org/google.golang.org/grpc#PerRPCCredentials
 grpc.WithPerRPCCredentials(perRPC),
 // oauth.TokenSource requires the configuration of transport
 // credentials.
 grpc.WithTransportCredentials(creds),
 }

在服务端则是要通过拦截器来分别处理两种 rpc 调用的验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// 流式的 验证
func ensureValidToken(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
 md, ok := metadata.FromIncomingContext(ctx)
 if !ok {
 return nil, errMissingMetadata
 }
 // 下面这个是将客户端传的token 和服务器端的校验逻辑来比较
 if !valid(md["authorization"]) {
 return nil, errInvalidToken
 }
 // Continue execution of handler after ensuring a valid token.
 return handler(ctx, req)
}
 cert, err := tls.LoadX509KeyPair(data.Path("x509/server_cert.pem"), data.Path("x509/server_key.pem"))
 if err != nil {
 log.Fatalf("failed to load key pair: %s", err)
 }
 opts := []grpc.ServerOption{
 grpc.UnaryInterceptor(ensureValidToken),
 // Enable TLS for all incoming connections.
 grpc.Creds(credentials.NewServerTLSFromCert(&cert)),
 }

这里也是可以用 go-grpc-middleware 提供的auth 中间件来实现验证函数的包装

取消调用

取消调用里面要在用grpc 调用时传入上下文作为第一个参数来控制rpc 调用过程；

1
2
3
4
5
6
7


 ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 stream, err := c.BidirectionalStreamingEcho(ctx)
 if err != nil {
 log.Fatalf("error creating stream: %v", err)
 }
 cancel()
 // 此时已经取消任务了，

压缩请求

1
2
3


// 旧版本在 NewClient() 的时候传一个 grpc.WithCompressor(grpc.NewGZIPCompressor())
// 新版本需要在调用的时候传入
grpc.UseCompressor(gzip.Name)

grpc限流

用go-grpc-middleware实现一个接口来在grpc 中间件里做限流，限流中间件必须排在后面，避免令牌被浪费了，使用原生的方式可以基于服务来做特定任务的限流；在示例中用定时器触发模拟限流机制产生，当服务端调用阻塞的时候，退出后续的批量任务，

请求失败重试策略配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18



 var retryPolicy = `{
 "methodConfig": [{
 "name": [{"service": "grpc.examples.echo.Echo"}], //应用的服务
 "waitForReady": true, // 是否等待
 "retryPolicy": {
 "MaxAttempts": 4,
 "InitialBackoff": ".01s",
 "MaxBackoff": ".01s",
 "BackoffMultiplier": 1.0,
 "RetryableStatusCodes": [ "UNAVAILABLE" ]
 }
 }]}`

// use grpc.WithDefaultServiceConfig() to set service config
func retryDial() (*grpc.ClientConn, error) {
 return grpc.NewClient(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithDefaultServiceConfig(retryPolicy))
}

等待对端恢复

1
2


// 在需要等待对端恢复服务的时候可以加入这个option
grpc.WaitForReady(true)

携带元数据

这个元数据有点像 http 里面的 header 的作用，携带一些用于配置的的内容客户端这边需要用

1
2
3
4
5
6


 metadata.Pairs("timestamp", time.Now().Format(timestampFormat)) // 来添加组装键值对，两个字符串作为一组，转换成一个KV对，键值对的键可以有重复的
 ctx := metadata.NewOutgoingContext(context.Background(), md)
 // 然后 封装成一个上下文通过 grpc 调用传过去
 var header, trailer metadata.MD
 r, err := c.UnaryEcho(ctx, &pb.EchoRequest{Message: message}, grpc.Header(&header), grpc.Trailer(&trailer))
 // 这个 header 和 trailer 是

服务端对这个元数据做交互

1
2
3
4
5
6
7


md, ok := metadata.FromIncomingContext(ctx)
 header := metadata.New(map[string]string{"location": "MTV", "timestamp": time.Now().Format(timestampFormat)})
 grpc.SendHeader(ctx, header)
 // 执行grpc 服务
 // 下面逻辑要在defer 函数里面执行
 trailer := metadata.Pairs("timestamp", time.Now().Format(timestampFormat))
 grpc.SetTrailer(ctx, trailer)

感觉可以用来做rpc 调用的时延监控，或者调用前后状态的跟踪点

grpc 长连接保活

1
2
3
4
5
6
7


var kacp = keepalive.ClientParameters{
 Time: 10 * time.Second, // send pings every 10 seconds if there is no activity
 Timeout: time.Second, // wait 1 second for ping ack before considering the connection dead
 PermitWithoutStream: true, // send pings even without active streams
}
// 新建客户端时带上这个 grpc.DialOption
conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithKeepaliveParams(kacp))

负载平衡

默认的连接构建策略是使用首个配置构建两件，如果需要使用负载平衡机制

1
2
3
4
5
6


// 使用轮转策略
roundrobinConn, err := grpc.NewClient(
 fmt.Sprintf("%s:///%s", exampleScheme, exampleServiceName),
 grpc.WithDefaultServiceConfig(`{"loadBalancingConfig": [{"round_robin":{}}]}`), // This sets the initial balancing policy.
 grpc.WithTransportCredentials(insecure.NewCredentials()),
 )

llm 知识抽取管线

Mon, 02 Dec 2024 22:36:03 +0800

llm 知识抽取管线

利用prompt模板，从文档中抽取出知识，并控制输出格式，完成知识抽取管线

prompt模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


KE_PROMPT= """你现在是一个用于抽取结构化信息的知识抽取模型，请按照遵守下面的步骤提取结构化的实体关系:
- 步骤 -
1. 识别所有在实体类型列表:{node_lists}中给出类型的实体，提取以下信息，同时保持实体一致性：
 - name 实体名称，尽量简单明确，不要包含多余信息；
 - type 实体类型，必须是实体类型列表中给出的类型；
 - desc 实体描述，可以实体属性和相关活动的描述；
 将每个实体输出为json格式，其格式如下，键值内容不要包含单双引号，格式如下：
 {{"name":"<实体名称>","type":"<实体类型>","desc":"<实体描述>"}}；
2. 针对步骤1中获取的实体，识别所有在关系类型列表:{relation_lists}中给出类型的关系，提取以下信息：
 - src 源实体的名称，即步骤1中标识的name
 - dst 目标实体的名称，即步骤1中标识
 - rel 关系类型，必须是关系类型列表中给出的类型；
 - rel_desc 说明源实体和目的实体存在实体关系的原因
 将每个关系输出转化成以下的json格式:格式如下:
 {{"src":"<源实体名称>","dst":"<目标实体名称>","rel":"<关系类型>","rel_desc":"<关系描述>""}}
3. 请保证按照上述规则输出，不要输出其他内容。
- 真实数据 -
#############
{text}
#############
输出:"""

def main():
 node_lists = ["人物", "地点", "组织","事件"]
 relation_lists = ["位于", "就职于","发生了","谈论"]
 test = "昨天实验室的牛师兄带着常师哥去面馆吃了八十八碗面，然后谈论面上项目的一些筹划，准备结合从所在的大数据实验室的重点方向挖掘项目创新点"
 print(KE_PROMPT.format(node_lists=node_lists,relation_lists=relation_lists,text=test))

if __name__ == '__main__':
 main()

openai 或者gpt 大模型http 非流式调用

这部分可以参照之前的那个chatgpt 桌面版调用不同厂商的sdk 接口，用来组装成流水线

Prometheus exporter pprof 优化

Mon, 02 Dec 2024 22:36:03 +0800

Prometheus exporter pprof 优化

这个工程是基于 Prometheus client-go 的库来开发的，这个库的主要流程是将 collector 的数据用http server的形式通过metrics 路由交出去，背景状况是现在这个收集器的收集间隔很长基本上是6个小时更新一次，但是负责抓取这些指标数据的服务leader 又不同意改成6小时的大跨度，所以之前的措施是把硬件采集的数据缓存起来，但是更新后的版本cpu占用率和响应时间都没太大优化，需要定位这个问题

怎么采集后台运行进程性能数据

使用ps -ef | grep xxx 来获取进程号pid
1. pidstat -u -p pid 15 4 来采集进程的cpu 占用率
top 按t 和m 来切换 cpu 和内存排序
go 使用 _ “net/http/pprof” 然后非http 网络服务就再增加一个拉起http 服务的几行代码
1. 使用curl -o cpupgo.out http://your_address:your_port/debug/pprof/profile?seconds=60 来采样一分钟的运行数据
2. go tool pprof -http=:9000 cpupgo.out 使用 pprof 工具开启一个网络服务在web网页上查看性能采样
使用 perf 工具来采样基本上会用到 record 和 report 这些，然后转成火山图来分析

问题追踪

问题1. 缓存为什么没有生效(降低延迟减少耗时操作) 通过go 的pprof 对后台运行的服务采样后发现大部分cpu 时间在生成Metric 相关的结构体上，同时缓存的数据格式是json，取json 数据会用到仿射，这使得组装Metric 的过程中充斥着大量的耗时操作，于是选择将json 数据缓存改成 Metric 数据缓冲，和时效时间戳一起封装成一个抽象的容器，在未过期时会将，slice 里面所有的Metric 通过管道发送出去，过期时会将slice 长度重置，发送Metric 的同时将其append 到slice 里面缓存，总结来说，缓存生效了，但是又没完全覆盖到所有耗时操作上。

改进后的缓存实现，在应用中遇到了新的问题，缓存应用后没被触发？

问题2. 缓存为什么没被触发？复盘对比了两种缓存机制和Collect 方法被调用的过程时发现，Collect 中声明的对象在每次调用时重新创建的，之前json 缓存是用的全局变量，所以创建前后用的都是一个缓存；这里将新的缓存实现也没大改，给新建的这些对象实例也做个全局缓存，没过期失效前这些实例就不会被重新创建，减少了一些再分配构建的过程，通过预留的 cache stat handler 可以看到缓存除了初次和过期时未命中外，其余时刻缓存全命中，符合预期

新的全局缓冲实现生效了，将cpu 占用率降低到原先的30%，同时内存占用差别不大，但剩下的30%还能不能继续优化呢？

终极优化方案

通过对 Prometheus client go 的源码阅读，确定了相应http 响应的整个构造流程，脑中浮现了一个比较极端的想法，缓冲响应；

这个适合用来缓存响应内容在一段时间内不会发生改动的 http handler 接口对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92


/* get resp cache code start */
type respCacheWriter struct {
 header http.Header
 expireat time.Time
 statuscode int
 buf []byte
 update bool
}
func newRespCacheWriter() *respCacheWriter {
 return &respCacheWriter{
 header: make(http.Header, 3),
 buf: make([]byte, 0, 1024*4),
 }
}
func (r *respCacheWriter) NotExpire() bool {
 return time.Now().Before(r.expireat)&&!r.update
}
func (r *respCacheWriter) Update(interval time.Duration) {
 r.expireat = time.Now().Add(interval)
 r.update = false
}
func (r *respCacheWriter) Header() http.Header {
 return r.header
}
func (r *respCacheWriter) SetUpdate() http.Header {
 return r.update = true
}

func (r *respCacheWriter) WriteHeader(statusCode int) {
 r.statuscode = statusCode
}

func (r *respCacheWriter) Write(p []byte) (int, error) {
 if p == nil {
 return 0, fmt.Errorf("Write []byte length should not be zero")
 }
 r.buf = append(r.buf, p...)
 return len(r.buf), nil
}

type GetRespCache struct {

 interval time.Duration
 cache map[string]*respCacheWriter
 next http.Handler
}

func NewGetRespCache(i time.Duration,next http.Handler)GetRespCache{
 return GetRespCache{
 interval: i,
 cache: make(map[string]*respCacheWriter,1),
 next: next,
 }
}

// 这个方法其实也可以 转成私有的，但是不会修改cache 状态所以无所谓

func (g *GetRespCache)UpdateCache()bool{
 key := fmt.Sprintf("key%v", r.URL.Query())
 if c,ok:=g.cache[key];key&&c!=nil{
 c.SetUpdate()
 }
}

func (g *GetRespCache) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 key := fmt.Sprintf("key%v", r.URL.Query())
 if val, ok := g.cache[key]; ok && val != nil&&val.NotExpire() {
 g.generateResp(val, w)
 } else {
 // 调用 write 方法时 缓存响应的 header
 resp := newRespCacheWriter()
 g.next.ServeHTTP(resp, r)
 g.generateResp(resp, w)
 g.update(key, resp)

 }
}
func (g *GetRespCache) update(key string, resp *respCacheWriter) {
 // 这里会更新过期时间和下一个响应状态
 resp.Update(g.interval)
 g.cache[key] = resp
}
func (*GetRespCache) generateResp(val *respCacheWriter, w http.ResponseWriter) {
 for k, s := range val.header {
 for _, v := range s {
 w.Header().Set(k, v)
 }
 }
 w.WriteHeader(val.statuscode)
 w.Write(val.buf)
}
/* get resp cache code end */

可以看到其实就是通过中间的代理接口，将被代理的handler 函数的修改缓存起来，根据get 请求的query值来做hash 返回响应的；过期的时效间隔这里倒是比较粗，用的是同一个过期间隔；

这个get 缓存方案是我最看好的:

第一点基本上是即插即用，迁移性好兼容性好，
第二点是性能更好，缓存占用少，还剩去了内部handler 处理的时间

这个之所以能用在这个场景上，其实是需求造成的，抓取端不改动，数据供应端又允许缓存；所以这个getcache 的方案理论上有奇效，但是最终还是没应用上这个，确定是按照问题2解决后的实现方案来。

TailReader 一个反向迭代器

Mon, 02 Dec 2024 22:36:03 +0800

TailReader 一个反向迭代器

面对大文本获取最后的消息，向前遍历go 目前没有现成的接口

设计思路

seek 反向移动offset ，然后bytes 判断不同系统上的换行符在哪里？
将一次分割后的字节数组，缓存起来，留待下次取分行字节
在多次未能查看到换行符的时候，默认是3KB 就提前终止提交失败，避免因为错误遍历大二进制文件
有缓存机制，大小文件效率都不差，适合做类似 tail -n 3 这种文本获取行为
目前支持的 empty 行跳过行为比较简单，其实更接近于剔除前缀换行符, 如果需要跳过空行，可以嵌套个if 判断len(temp)>0
面对极小文件可以直接用ReadFile 来切split，避免带来额外的复杂度

实现细节

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147



type TailReader struct {
 rc *os.File
 buf []byte // 用来缓存剩余字节
 temp []byte // 提供给 Read
 sep []byte // 兼容不同系统架构分隔符
 offset int64 // 记录offset
 size int64 // 文件大小
 skipempty bool // 控制是否跳过空行行为
 atEnd bool // 记录offset 是否被移动到文件开始位置了
}

var (
 Sep_win = []byte("\r\n")
 Sep_linux = []byte("\n")
)

func NewTailReader(fname string, sep []byte, skip bool) (*TailReader, error) {
 file, err := os.Open(fname)
 if err != nil {
 return nil, err
 }
 stat, _ := file.Stat()
 size := stat.Size()
 var offset int64 = 1024
 if size < offset {
 offset = size
 }

 _, errs := file.Seek(int64(-offset), 2)
 if errs != nil {
 return nil, errs
 }
 offset2, _ := file.Seek(0, io.SeekCurrent)
 fmt.Printf("seek to offset %d, file size is %d\n", offset2, size)
 atEnd := false
 if offset == size {
 atEnd = true
 }
 return &TailReader{rc: file, buf: make([]byte, 0, 1024), temp: make([]byte, 1024), sep: sep, skipempty: skip, offset: int64(offset), size: size, atEnd: atEnd}, nil
}

func (t *TailReader) Close() {
 t.rc.Close()
}

func (t *TailReader) ReadBytes() ([]byte, error) {
 // 如果上次缓存没清完，检查是否有换行符
 sepsize := 0
 if t.skipempty {
 sepsize = len(t.sep)
 }
 // 处理上次遗留的缓存
 if len(t.buf) > 0 {
 if idx := bytes.LastIndex(t.buf, t.sep); idx != -1 {
 temp := append([]byte{}, t.buf[idx+sepsize:]...)
 t.buf = t.buf[:idx]
 return temp, nil
 }
 if t.atEnd {
 p := slices.Clone(t.buf[:len(t.buf)])
 t.buf = t.buf[:0]
 return p, nil
 }
 }

 if t.size < t.offset {
 return nil, io.EOF
 }
 // 拷贝重置缓存
 var p []byte
 // 先将这部分尾巴给卸除出去
 if len(t.buf) > 0 {
 p = append([]byte{}, t.buf...)
 }
 n, err := t.rc.Read(t.temp)
 if err == nil && n > 0 {
 idx := bytes.LastIndex(t.temp[:n], t.sep)

 if idx != -1 {

 temp := append([]byte{}, t.temp[idx+sepsize:n]...)
 temp = append(temp, p...)
 t.buf = t.buf[:0]
 t.buf = append(t.buf, t.temp[:idx]...)
 if err := t.move(n); err != nil {
 return nil, err
 }
 return temp, nil
 }

 var cur, next []byte

 cur = slices.Concat(t.temp[:n], p)
 if err := t.move(n); err != nil {
 return nil, err
 }
 // 用来预防二进制大文件，堆爆slice
 for i := 0; i < 3 && idx == -1; i++ {
 n, err = t.rc.ReadAt(t.buf, 0)
 if err != nil {
 return nil, err
 }
 if err := t.move(n); err != nil {
 return nil, err
 }
 idx = bytes.LastIndex(t.buf[:n], t.sep)
 if idx != -1 {
 next = slices.Concat(t.temp[idx:n], cur)
 // 尽量复用
 t.buf = t.buf[:0]
 t.buf = append(t.buf, t.temp[:idx]...)
 break
 }
 next = slices.Concat(t.temp[:n], cur)
 }

 if idx != -1 {
 return nil, errors.New("cant found sep in many times try")
 }

 return next, nil
 }
 return nil, err
}

func (t *TailReader) move(delta int) error {
 t.offset += int64(delta)
 if t.offset > t.size {
 t.offset = t.size
 }
 // 避免重复移动
 if t.offset <= t.size && !t.atEnd {

 _, err := t.rc.Seek(-t.offset, 2)
 if err != nil {
 return err
 }
 if t.offset == t.size {
 t.atEnd = true
 }
 }
 if len(t.buf) > 0 {
 return nil
 }
 return io.EOF
}

简单使用示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


 f, err := NewTailReader(`test.txt`, utils.Sep_win, true)
 if err != nil {
 fmt.Printf("error %s", err.Error())
 }
 defer f.Close()
 for {

 b, e := f.ReadBytes()
 // 一般是 io.EOF
 if e != nil {
 break
 }
 fmt.Printf("%s\t%v\n", string(b), e)
 }

一般用来读取尾部行，不太适合对日志这种增长文件去重复读取

TLS 和 H2 配置

Mon, 02 Dec 2024 22:36:03 +0800

TLS 和 H2 配置

TLS 证书签发流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 下面是 v3.ext 的内容
# authorityKeyIdentifier=keyid,issuer
# basicConstraints=CA:FALSE
# keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
# extendedKeyUsage = serverAuth
# subjectAltName = @alt_names

# [alt_names]
# DNS.1=localhost
# DNS.2=10.110.8.36
openssl genrsa > serve.key
openssl req -new -key serve.key -out serve.csr -subj "/C=GB/L=China/O=hx/CN=localhost" -days 365 -addext "subjectAltName = DNS:localhost"
# 个人感觉 这边加个 -addext "subjectAltName = DNS:localhost" 也可以替代 extfile
openssl x509 -req -sha512 -days 365 -extfile v3.ext -signkey serve.key -in serve.csr -out serve.crt

三个文件：

serve.key 私钥
serve.csr 公钥
serve.crt 给客户端用来验证服务的签名证书

代码实现TLS 和H2

服务端这边

1
2
3
4
5
6
7


 http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
 io.WriteString(w, "hello, world!\n")
 })
 // 这里要指向两个文件的路径
 if e := http.ListenAndServeTLS(":443", "serve.crt", "serve.key", nil); e != nil {
 log.Fatal("ListenAndServe: ", e)
 }

客户端这边

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


package main

import (
 "crypto/tls"
 "crypto/x509"
 "fmt"
 "io"
 "log"
 "net/http"
 "os"

 "golang.org/x/net/http2"
)

func loadCA(caFile string) *x509.CertPool {
 pool := x509.NewCertPool()

 if ca, e := os.ReadFile(caFile); e != nil {
 log.Fatal("ReadFile: ", e)
 } else {
 pool.AppendCertsFromPEM(ca)
 }
 return pool
}

func main() {
 c := &http.Client{
 // 这个会拿到 h2的协议
 Transport: &http2.Transport{
 TLSClientConfig: &tls.Config{RootCAs: loadCA("../serve.crt")},
 AllowHTTP: true,
 },
 // 启用下面这个注释的就是 https 的协议
 // Transport: &http.Transport{
 // TLSClientConfig: &tls.Config{RootCAs: loadCA("../serve.crt")},
 // },
 }

 if resp, e := c.Get("https://localhost:443/"); e != nil {
 log.Fatal("http.Client.Get: ", e)
 } else {
 defer resp.Body.Close()
 io.Copy(os.Stdout, resp.Body)
 fmt.Printf("Got response %d: %s \n", resp.StatusCode, resp.Proto)
 }
}

分布式一致性hash golang 实现

Mon, 02 Dec 2024 22:36:03 +0800

分布式一致性哈希 Golang 实现

哈希环定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


import "hash/crc32"
type Hash func(data []byte) uint32
// 用crc32
var defaultHashFn = crc32.ChecksumIEEE
// 哈希环
// 注意，非线程安全，业务需要自行加锁
type HashRing struct {
 hash Hash
 // 每个真实节点的虚拟节点数量
 replicas int
 // 哈希环，按照节点哈希值排序
 ring []int
 // 用来在新增节点时去重的
 keys []string
 // 节点哈希值到真实节点字符串，哈希映射的逆过程
 nodes map[int]string
}

func NewHashRing(r int,fn Hash)*HashRing(){
 if fn==nil{
 fn = defaultHashFn
 }
 return &HashRing{
 replicas: r,
 hash: fn,
 ring: make([]int,0,8*r),
 keys: make([]string,0,8),
 nodes: make(map[int]string,8),
 }

}

方法实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


import (
 "slices"
 "sort"
 "strconv"
)

func (h *HashRing) Add(nodes ...string) {
 for _, k := range nodes {

 exist := false
 for _, val := range h.keys {
 if val == k {
 exist = true
 }
 }
 if !exist {
 h.keys = append(h.keys, k)
 for i := 0; i < h.replicas; i++ {
 hash := int(h.hash([]byte(strconv.Itoa(i) + k)))
 h.ring = append(h.ring, hash)
 h.nodes[hash] = k
 }
 }
 }
 slices.Sort(h.ring)
}
func (h *HashRing) Len() int {
 return len(h.keys)
}

func (h *HashRing) Get(key string) string {
 if h.Len() == 0 {
 return ""
 }

 hash := int(h.hash([]byte(key)))

 // Binary search for appropriate replica.
 idx := sort.Search(len(h.ring), func(i int) bool { return h.ring[i] >= hash })

 // Means we have cycled back to the first replica.
 if idx == len(h.ring) {
 idx = 0
 }

 return h.nodes[h.ring[idx]]
}
func (h *HashRing)Rest(){
 h.ring = h.ring[:0]
 h.keys = h.keys[:0]
 clear(h.nodes)
}

Add() 方法是用来创建节点环的,在一些节点退出后，可能需要reset 哈希环来再次重构哈希环
Reset() 是用来重置hash环信息的
Get() 就是用来获取一致性哈希映射到的节点的字符串上

矢量化扩展

Mon, 02 Dec 2024 22:36:03 +0800

矢量化扩展

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66


#include <array>
#include <chrono>
#include <iostream>
#include <string>
#include <vector>
#include "boost/core/noncopyable.hpp"

using std::chrono::duration_cast;
using std::chrono::high_resolution_clock;
class BenchTimer : boost::noncopyable {
 high_resolution_clock::time_point tp;
 std::string name;
 std::vector<std::string> rd;
 std::vector<double> dt;

 public:
 inline void st(const std::string &name) {
 this->name = name;
 tp = high_resolution_clock::now();
 }
 inline void end() {
 dt.emplace_back(duration_cast<std::chrono::nanoseconds>(high_resolution_clock::now() - tp).count());
 rd.emplace_back(this->name);
 }
 void showBenchTest() {
 for (int i = 0, size = static_cast<int>(rd.size()); i < size; i++) {
 std::cout << rd[i] << ":" << dt[i] / 1000 << "\n";
 }
 }
};

int main() {
 std::vector<int> arr_a(256, 0);
 std::vector<int> arr_b(256, 100);
 typedef int int256 __attribute__((vector_size(256 * sizeof(int))));
 int256 a;
 int256 b;

 for (int i = 0; i < 256; i++) {
 arr_a[i] = i;
 a[i] = i;
 arr_b[i] = 256 - i;
 b[i] = 256 - i;
 }
 int t = 10000;
 auto bench = BenchTimer();
 #pragma clang optimize off
 bench.st("foreach");
 while (t > 0) {
 for (auto i = 0; i < 256; i++) {
 arr_a[i] = 2 * arr_b[i];
 }
 t--;
 }
 bench.end();
 t = 10000;
 bench.st("vec");
 while (t > 0) {
 a = 2 * b;
 t--;
 }
 bench.end();
 #pragma clang optimize on
 bench.showBenchTest();
 std::cout << "2*b[0]==" << a[0] << std::endl;
}

bench测试结果

foreach:673.4 vec:4.8
2*b[0]==512

按照600/5 也有120倍的加速差距了，据我观察这种大轮次的外部循环可能对vec 的缓存hit更友好点，总之是有优化效果的

文件多格式压缩工具rust实现

Mon, 02 Dec 2024 22:36:03 +0800

https://

文件多格式压缩

使用了一个压缩集合库来实现的这部分功能 compress

代码实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135


package kit

import (
 "fmt"
 "io"
 "os"
 "path/filepath"
 "strings"
 "syscall"

 gzip "github.com/klauspost/compress/gzip"
 snappy "github.com/klauspost/compress/s2"
 zip "github.com/klauspost/compress/zip"
 zstd "github.com/klauspost/compress/zstd"
)

/* compress file func start */
// go build:+ linux
var osChown = os.Chown

type (
 CompressType int
 ZWriter interface {
 io.WriteCloser
 Flush() error
 }
)

const (
 GZIP_TYEP CompressType = iota
 ZSTD_TYPE
 SNAPPY_TYPE
 ZIP_TYPE
)

var suffixs = [4]string{".gz", ".zst", ".snappy", ".zip"}

func chown(name string, info os.FileInfo) error {
 f, err := os.OpenFile(name, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, info.Mode())
 if err != nil {
 return err
 }
 f.Close()
 stat := info.Sys().(*syscall.Stat_t)
 return osChown(name, int(stat.Uid), int(stat.Gid))
}

func CompressLogFile(src, dst string, ct CompressType, rm bool) (err error) {
 f, err := os.Open(src)
 if err != nil {
 return fmt.Errorf("failed to open log file: %v", err)
 }
 defer f.Close()
 if dst == src {
 dst += "out"
 }
 fi, err := os.Stat(src)
 if err != nil {
 return fmt.Errorf("failed to stat log file: %v", err)
 }

 if !strings.HasSuffix(dst, suffixs[ct]) {
 dst += suffixs[ct]
 }
 if err := chown(dst, fi); err != nil {
 return fmt.Errorf("failed to chown compressed log file: %v", err)
 }

 // If this file already exists, we presume it was created by
 // a previous attempt to compress the log file.
 zf, err := os.OpenFile(dst, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, fi.Mode())
 if err != nil {
 return fmt.Errorf("failed to open compressed log file: %v", err)
 }
 defer zf.Close()
 if ct == ZIP_TYPE {
 w := zip.NewWriter(zf)

 _, filename := filepath.Split(src)
 temp, err := w.Create(filename)
 if err != nil {
 return err
 }
 if _, err := io.Copy(temp, f); err != nil {
 w.Close()
 return err
 }
 if err := w.Close(); err != nil {
 return err
 }
 } else {

 var zwriter ZWriter
 switch ct {
 case GZIP_TYEP:
 zwriter = gzip.NewWriter(zf)
 case SNAPPY_TYPE:
 zwriter = snappy.NewWriter(zf, snappy.WriterSnappyCompat())
 case ZSTD_TYPE:
 zwriter, _ = zstd.NewWriter(zf)
 }

 defer func() {
 if err != nil {
 os.Remove(dst)
 err = fmt.Errorf("failed to compress log file: %v", err)
 }
 }()

 if n, err := io.Copy(zwriter, f); err != nil {
 zwriter.Close()
 return err
 } else {
 fmt.Printf("debug %d byets has beed write to dst path %s", n, dst)
 }
 zwriter.Flush()
 if err := zwriter.Close(); err != nil {
 return err
 }
 }
 if err := zf.Close(); err != nil {
 return err
 }

 if err := f.Close(); err != nil {
 return err
 }
 if rm {
 if err := os.Remove(src); err != nil {
 return err
 }
 }

 return nil
}

这部分主要是通过枚举加分支逻辑来处理不同压缩格式的处理，通过io.Copy 来做数据管道

消息订阅实现

Mon, 02 Dec 2024 22:36:03 +0800

消息订阅实现

原理

go 的消息管道可以看成一个并发安全的队列，每个订阅者将字节的收信队列添加到SubHub 里面，按照订阅的topic 和 channel 的关系用一个 map[string]chan 来实现关联，当Hub 接受到对应topic 的消息推送的时候，会给slice 里面的收信队列发事件消息

实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


import (
 "sync"
 "time"
)

type HEvent struct {
 Data interface{}
 Topic string
}

type HEventData chan HEvent
type HEventDataArray []HEventData //一个topic 可以有多个消费者

type HEventBus struct {
 sub map[string]HEventDataArray
 rm sync.RWMutex
}


func HEventSrv() *HEventBus {
 return h
}

func (h *HEventBus) Sub(topic string, ch HEventData) {
 h.rm.Lock()
 if chanEvent, ok := h.sub[topic]; ok {
 h.sub[topic] = append(chanEvent, ch)
 } else {
 h.sub[topic] = append([]HEventData{}, ch)
 }
 defer h.rm.Unlock()
}

func (h *HEventBus) Push(topic string, data interface{}) {
 h.rm.RLock()
 defer h.rm.RUnlock()
 if chanEvent, ok := h.sub[topic]; ok {
 for _, ch := range chanEvent {
 ch <- HEvent{
 Data: data,
 Topic: topic,
 }
 }
 }
}

func (h *HEventBus) PushFullDrop(topic string, data interface{}) {
 h.rm.RLock()
 defer h.rm.RUnlock()
 if chanEvent, ok := h.sub[topic]; ok {
 for _, ch := range chanEvent {
 select {
 case ch <- HEvent{
 Data: data,
 Topic: topic,
 }:
 case <-time.After(time.Second):
 }
 }
 }
}

雪花算法实现

Mon, 02 Dec 2024 22:36:03 +0800

雪花算法实现

雪花算法

0 - 0000000000 0000000000 0000000000 0000000000 0 - 0000000000 - 000000000000

符号位时间戳机器码序列号

41位毫秒级时间戳，10位机器id 12位序列号这个起始时间sEpoch其实不太重要，因为一般业务不会超过10年，这个69-(10~20)总还有50年的余量的，比较重要的一点就是如果一个毫秒内生产的序列id 过多就得等待到下一个毫秒窗口内

代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69


package utils

// https://sourcegraph.com/github.com/sohaha/zlsgo/-/blob/zstring/snowflake.go
// 学习 zlsgo的总结
import (
 "fmt"
 "sync"
 "time"
)

const (
 sEpoch = 1474802888000 // 这个可以是业务上线的时间
 TimeBase = int64(1000000)
 MaxWorkID = 1<<5 - 1
 MaxDataID = MaxWorkID
 MaxSeqID = 1<<12 - 1
 MaskWorkID = 1<<10 - 1
 MaskSeqID = 1<<12 - 1
)

type SnowFlakeBuilder struct {
 start int64
 workid int64
 seqid int64
 lock sync.Mutex
}

func NewBuilder(st time.Time, data int, worker int) *SnowFlakeBuilder {
 if data < 0 || data > MaxDataID || worker < 0 || worker > MaxWorkID || st.After(time.Now()) {
 panic("invaild argument error")
 }
 return &SnowFlakeBuilder{
 start: st.UnixNano() / TimeBase,
 workid: int64(data<<5|worker) & MaskWorkID,
 }
}

// 类似自旋锁的逻辑，持续试图获取下一毫秒的时间资源
func (s *SnowFlakeBuilder) waitToNextMS(last int64) int64 {
 ts := time.Now().UnixNano() / TimeBase
 for {
 if ts <= last {
 ts = time.Now().UnixNano() / TimeBase
 } else {
 break
 }
 }
 return ts
}

func (s *SnowFlakeBuilder) GetID() (int64, error) {
 s.lock.Lock()
 defer s.lock.Unlock()
 ts := time.Now().UnixNano() / TimeBase
 if ts == s.start {
 s.seqid = (s.seqid + 1) & MaskSeqID
 if s.seqid == 0 {
 ts = s.waitToNextMS(ts)
 }
 } else {
 s.seqid = 0
 }
 if ts < s.start {
 return 0, fmt.Errorf("clock moved backwards, refuse gen id")
 }
 s.start = ts
 ts = (ts-sEpoch)<<22 | s.workid<<12 | s.seqid
 return ts, nil
}

一个gptapi 桌面套件

Mon, 02 Dec 2024 22:36:03 +0800

一个gptapi 桌面套件

使用了pyside6 和qfluentwidget 做的界面，qfluent 主要是用了侧边导航栏，后期考虑去掉这个依赖进一步减少编译后执行文件大小。 chatdesk 桌面套件连接

功能

markdown 自动导出
国产api {千问，豆包，混元，千帆，DeepSeek，Kimi}
支持多轮对话，但是暂时没做单轮多轮的动态切换
支持api 厂商动态切换，左下角label 显示当前使用的api后端
work线程实现异步读取响应流，但是考虑到防误触重发的问题，读取完成前，发送按钮不能再次点击
支持静态模型切换，目前配置文件存于工作目录，比使用环境变量更安全些
实验特性，多api 同时响应回答，目前没对多轮会话做支持；

主页面动态增长对话框

这边没有完全考虑仿照qq 那种一左一右的对话布局，因为比较麻烦；主要是在Scrollarea可滚动区域里面，添加重写的文本框；文本框在内容更新和变动时会自动适应内容大小，固定宽度；文本框超出滚动区域可视高度时会调整整个滚动区域的最小高度，避免压缩文本框；

TODO：因为会根据滚动区域里面文本框的累积高度来调整滚动区域最小高度，避免压缩文本框，会在特定情况下发生侧边滚动条调变，后期可能考虑优化；给模型切换设计更加灵活的触发方式；支持历史记忆管理，增强多轮会话的关联性；支持一些链模式，或者说对内容做多轮归纳增强；

会话窗口

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227



# 一个单线程的异步执行者
class MyThead(QThread):
 def __init__(self,parent):
 super().__init__(parent)
 self.queue =Queue(10)
 self.exist = False
 def addtask(self,fn):
 self.queue.put(fn)
 def stop(self):
 self.exist =True
 self.queue.put(lambda: logging.debug("线程shutdown") )
 def run(self):
 while not self.exist:
 try:
 fn =self.queue.get(timeout=1)
 if fn is None:
 break
 if self.exist:
 break
 try:
 fn()
 except Exception as e:
 logging.debug(f"线程内部执行错误{e=}")
 break
 except Empty:
 if self.exist:
 break
 continue
# 简单的 对话界面窗口
class Flow(QWidget):
 def __init__(self):
 super().__init__()
 self.layout_ = QVBoxLayout(self)
 self.layout_.setAlignment(Qt.AlignmentFlag.AlignTop)
 self.setLayout(self.layout_)
 def addWidget(self,w:QWidget):
 self.layout_.addWidget(w)


class TextArea(QTextEdit):
 def __init__(self,parent):
 super().__init__()
 self.setReadOnly(True)
 self.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
 self.m_txtDefaultHeight = 50
 self.setMaximumHeight(50)
 self.setMinimumHeight(50)
 self.top,self.bottom = self.contentsMargins().top(), self.contentsMargins().bottom()
 self.ctx = ""
 self.pa = parent
 # 隐藏时间戳，后续可能会用到类似的注释
 self.ud = f"<!-- TS:{datetime.now().strftime('%Y-%m-%d %H:%M:%S')} -->"
 self.ds = f"{datetime.now().strftime('%Y_%m_%d')}"
 self.saved = False
 self.callback :Callable[[float],int]
 self.lastH = -1.0
 def insertMarkdown(self,s:str):
 self.ctx +=s
 self.setMarkdown(self.ctx)
 self.checkResize()
 def regist(self,callback:Callable[[float],int] ):
 self.callback = callback
 # 适应窗口变动
 @Slot()
 def checkResize(self):
 # print("更新变动")
 h = self.document().size().height()
 outer =-1
 if h>max(self.lastH,outer):
 self.lastH = h
 outer =self.callback(h+self.top+self.bottom)
 if h>self.m_txtDefaultHeight:
 self.m_txtDefaultHeight = math.floor(h)

 self.setMaximumHeight(math.floor(h))
 self.setMinimumHeight(math.floor(h))
 rect = self.geometry()
 self.setGeometry(rect.x(),rect.y(),rect.width(),math.floor(h)+self.top+self.bottom)
 # 导出md 文件
 @Slot()
 def export2File(self):

 if self.saved:
 return
 with open(f"./chart_{self.ds}.md",mode="a+",encoding="utf8") as fw:
 size = self.ctx.split("-----",maxsplit=1)
 if len(size) >1 and len(size[1])>0:
 fw.write(self.ctx)
 fw.write(f"\n{self.ud}\n")
 self.saved =True

 def wheelEvent(self,e :QWheelEvent):
 self.pa.wheelEvent(e)
 def resizeEvent(self, e: QResizeEvent) -> None:
 self.document().setTextWidth(self.viewport().width())
 margins = self.contentsMargins()
 height = int(self.document().size().height() + margins.top() + margins.bottom())
 self.setMaximumHeight(height)
 self.setMinimumHeight(height)

class MyApp(QWidget):
 sig = Signal(str)
 def __init__(self, *args,**kwargs) -> None:
 super().__init__(*args,**kwargs)
 self.setWindowTitle("PYSIDE6 demo")
 self.id =0
 self.gid =0
 self.resize(800,450)
 self.m_end =0
 self.set_ui()
 self.ctx =""
 # 这部分还可以整理一下
 def set_ui(self):
 self.scrollarea = SingleDirectionScrollArea()
 self.scrollarea.setWidgetResizable(True)
 self.scrollbar = self.scrollarea.verticalScrollBar()
 self.flow = Flow()
 self.create_txt()
 self.flow.addWidget(self.txt)
 self.flow.setMinimumHeight(self.scrollarea.size().height())
 self.scrollarea.setWidget(self.flow)
 self.button = PrimaryPushButton("发送")
 self.inputtext = LineEdit()
 self.inputtext.setPlaceholderText("请输入你的想法")
 self.laout = QGridLayout(self)
 # self.appendWS([self.text,self.button,self.inputtext])
 self.laout.addWidget(self.scrollarea,0,0,3,4)
 self.laout.addWidget(self.inputtext,4,0,1,3)
 self.laout.addWidget(self.button,4,3,1,1)
 self.button.clicked.connect(self.magic)
 self.agent = None
 self.worker = MyThead(self)
 self.setStyleSheet("QPushButton{border-width:1px;border-radius:5px;background-color: #3366FF ;}\
 QLabel{border:3px solid black ;border-radius:5px;color:black}")
 # 动态切换api 后端
 def changeAgent(self,s):
 if s in Agents:
 if s==da:
 return

 self.agent = Agents[s]
 # 根据内容更新滚动条高度
 def changeScrollBar(self, f:float):
 nexth =-1
 if self.m_end +f >= self.flow.minimumHeight():
 nexth = int(self.m_end+f)+50
 self.flow.setMinimumHeight(nexth)
 self.scrollbar.setValue(self.scrollbar.maximum())
 return nexth
 def create_txt(self):
 if self.gid>1:
 self.m_end =self.txt.geometry().y()+self.txt.geometry().height()+self.txt.top+self.txt.bottom
 self.sig.disconnect(self.txt.insertMarkdown)
 self.txt = TextArea(self)
 self.scrollbar.setValue(self.scrollbar.maximum())
 self.txt.regist(self.changeScrollBar)
 self.flow.addWidget(self.txt)
 self.sig.connect(self.txt.insertMarkdown)

 def appendWS(self,l:list[QWidget]):
 for it in l:
 self.layout.addWidget(it)
 # 异步任务
 def loopread(self,s:str):
 # 多api 响应，目前没做多轮兼容
 if useALL:
 for k,a in Agents.items():
 try:
 self.append(f"\n\n`{k}`: \n\n")
 a.StreamCall(s,self.append)
 except Exception as e:
 logging.debug(f"多轮提问错误{e=}")
 else:
 self.agent.StreamCall(s,self.append) # type: ignore
 self.button.setEnabled(True)
 if saveHistory:
 self.txt.export2File()

 def append(self,s):
 self.sig.emit(s)
 def showMessage(self,ty:str,s:str):
 TeachingTip.create(
 target=self.button, # type: ignore
 icon=InfoBarIcon.ERROR,
 title=ty,
 content=s,
 isClosable=True,
 tailPosition=TeachingTipTailPosition.BOTTOM_RIGHT,
 duration=2000,
 parent=self
 )
 logging.debug(f"type={ty},{s}")

 @Slot()
 def magic(self):
 if self.agent is None:
 # 延迟代理配置，使用户可以先通过界面生成配置文件后再重启后使用
 if len(Agents)==0 or da == "":
 self.showMessage("Error:","请先在设置页面配置一个chatgpt api的接口设置")
 else:
 self.agent = Agents[da]
 self.gid +=1
 if self.gid>1:
 self.create_txt()
 if self.inputtext.text()!="":
 self.button.setDisabled(True)
 self.txt.insertMarkdown(f"#### Q: {self.inputtext.text()}\n-----\n**A:** \n")
 # 延迟启动异步线程
 if not self.worker.isRunning():
 self.worker.start()

 self.worker.addtask(lambda : self.loopread(self.inputtext.text()))
 # 用来处理线程关闭问题 
 def close(self) -> bool:
 self.worker.stop()
 self.worker.wait()
 self.worker.quit()
 self.worker.terminate()
 return super().close()
 def closeEvent(self, event) -> None:
 self.worker.stop()
 self.worker.wait()
 self.worker.quit()
 self.worker.terminate()
 event.accept()
 return super().closeEvent(event)

api 后端

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141


# 千问，Kimi,deepseek
# 一直有ssl 验证的ca调用后面会排查一下怎么跳过
class openai:
 def __init__(self,a:auth) -> None:
 self.key =a.sk
 self.url =urlMap[a.type]
 self.client = OpenAI(api_key=self.key,base_url=self.url)
 self.history = [{'role': 'system', 'content': 'You are a helpful assistant.'}]
 self.model = ModelMap[a.type][0]
 self.isMulti = False
 def setModel(self,s:str):
 self.model = s


 def StreamCall(self,s:str,fn:Callable[[str],None]):
 if not self.isMulti:
 self.history = []
 self.history.append({'role': 'user', 'content': f'{s}'})
 cmp = self.client.chat.completions.create(
 model=self.model,
 messages=self.history, # type: ignore
 stream=True
 )
 temp = ""
 for chunk in cmp:
 ctx = chunk.choices[0].delta.content
 try:
 if ctx and len(ctx)>0:
 fn(ctx)
 except Exception as e:
 logging.debug(f"streamcall {e=}")
 if ctx:
 temp +=ctx
 if self.isMulti:
 self.history.append({'role': 'system', 'content': f'{temp}'})

# 百度千帆
class qf:
 def __init__(self,sk=None,ak=None) -> None:
 if sk==None or ak==None:
 raise ValueError(f"{sk=},{ak=} is invalid")
 self.client = qianfan.ChatCompletion(ak=ak,sk=sk)
 self.model = ModelMap["千帆"][0]
 self.history = []
 self.isMulti =False
 def setModel(self,s:str):
 self.model = s
 def StreamCall(self,s:str,fn:Callable[[str],None]):
 temp = ""
 if not self.isMulti:
 self.history = []
 self.history.append({"role":"user","content":f"{s}"})
 resp = self.client.do(model=self.model,messages=self.history,stream=True)
 for chunk in resp:
 ctx = chunk["body"]["result"]
 try:
 if len(ctx)>0:
 fn(ctx)
 except Exception as e:
 showMessage("错误",f"{e=}",None,None)
 temp +=ctx
 if self.isMulti:
 self.history.append({'role': 'system', 'content': f'{temp}'})

import json
# 混元
from tencentcloud.common.common_client import CommonClient
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile



class hy:
 def __init__(self,sk=None,ak=None) -> None:
 if sk==None or ak==None:
 raise ValueError(f"{sk=},{ak=} is invalid")
 self.model = ModelMap["混元"][0]
 self.message = {"Messages":[],"Stream":True,"Model":self.model}
 self.history =self.message["Messages"]
 self.isMulti =False
 cred = credential.Credential(ak, sk)

 httpProfile = HttpProfile()
 httpProfile.endpoint = "hunyuan.tencentcloudapi.com"
 clientProfile = ClientProfile()
 clientProfile.httpProfile = httpProfile

 params = "{}";
 self.client = CommonClient("hunyuan", "2023-09-01", cred, "", profile=clientProfile)
 def setModel(self,s:str):
 self.model = s
 self.message["Model"] = self.model
 def StreamCall(self,s:str,fn:Callable[[str],None]):
 temp = ""
 if not self.isMulti:
 self.message["Messages"] = []
 self.message["Messages"].append({"Role":"user","Content":f"{s}"})
 resp = self.client.call_sse("ChatCompletions", self.message)
 for chunk in resp:
 ctx = json.loads(chunk["data"])["Choices"][0]["Delta"]["Content"]
 # ctx = chunk["body"]["result"] 
 try:
 if len(ctx)>0:
 fn(ctx)
 except Exception as e:
 showMessage("错误",f"{e=}",None,None)
 temp +=ctx
 if self.isMulti:
 self.history.append({'role': 'system', 'content': f'{temp}'})

# 豆包的这个是比较恶心的，在ak，sk，上还要一个modelid 形式的key
from volcenginesdkarkruntime import Ark
class db:
 def __init__(self,sk=None,ak=None,model=None) -> None:
 if sk==None or ak==None or model==None:
 raise ValueError(f"{sk=},{ak=} is invalid")
 self.client = Ark(ak=ak,sk=sk,base_url="https://ark.cn-beijing.volces.com/api/v3")
 self.model = model
 self.history = []
 self.isMulti =False
 def setModel(self,s:str):
 self.model = s
 def StreamCall(self,s:str,fn:Callable[[str],None]):
 temp = ""
 if not self.isMulti:
 self.history = []
 self.history.append({"role":"user","content":f"{s}"})
 resp: Stream[ChatCompletionChunk] = self.client.chat.completions.create(model=self.model,messages=self.history,stream=True) # type: ignore
 for chunk in resp:
 if not chunk.choices:
 continue
 ctx: str = chunk.choices[0].delta.content # type: ignore
 try:
 if len(ctx)>0:
 fn(ctx)
 except Exception as e:
 showMessage("错误",f"{e=}",None,None)
 temp +=ctx
 if self.isMulti:
 self.history.append({'role': 'system', 'content': f'{temp}'})

实现这个异步响应就是通过调用agent 接口的 streamcall ，通过传入的s 表示请求消息，fn表示每轮执行的回调函数，这里的ctx 之类的返回需要增加一个if ctx检查防止某些情况下拿到的对象是None 出现错误

一个range 风格的范围迭代器封装实现

Mon, 02 Dec 2024 22:36:03 +0800

一个range 风格的范围迭代器封装实现

go 里面有个range 的表达式可以遍历很多容器，最近应该是1.21支持range int,这看起来很像 python的 range 了，很舒服，想着很久没用cpp 写东西了就准备按照迭代器整一个，做小点，也不用什么模板；

第一种宏定义

这种其实类似哪些OIer 常用的 for_each 宏

1

 #define rangeI(_I, _end) for (i = 0; i < (_end); i++)

其实就是一个包装常见的 for 表达式头的一个宏，限制挺多，优点是几乎零开销；

迭代器类封装实现

这个东西实现上并未考虑太多性能,应该会需要创建两个对象，这个有点像cpp 20里面增加的，ranges::itoa_views()；但是这个功能更单一，仅用于整型范围迭代，而且接口也是更使用，提供，start，end，step，支持for range双向遍历

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63




class RangeIter {
 private:
 int step;
 int cur_val;

 public:
 RangeIter(int step, int val) : step(step), cur_val(val) {}

 // these three methods form the basis of an iterator for use with a rangeIter-based for loop
 bool operator!=(const RangeIter &other) const {
 if (step < 0) {
 return cur_val != other.cur_val && cur_val > other.cur_val;
 }
 return cur_val != other.cur_val && cur_val < other.cur_val;
 }

 // this method must be defined after the definition of IntVector since it needs to use it
 int operator*() const { return cur_val; }
 const RangeIter &operator++() {
 cur_val += step;
 return *this;
 }
};
class Range {
 private:
 int _st, _end, _step;
 bool args_check() const {
 if (_step == 0) {
 return false;
 }
 if (_step < 0 && _st <= _end) {
 return false;
 }
 return _step <= 0 || _st < _end;
 }

 public:
 Range(int start, int end, int step) : _st(start), _end(end), _step(step) {}
 Range(int start, int end) : _st(start), _end(end), _step(1) {}
 explicit Range(int end) : _st(0), _end(end), _step(1) {}
 RangeIter iter() { return RangeIter{_step, _st}; }
 RangeIter cbegin() const {
 if (!args_check()) {
 throw std::invalid_argument("step should match the exper start+n*step>end");
 }
 return RangeIter{_step, _st};
 }
 RangeIter cend() const {
 // if (!args_check()){
 // throw std::invalid_argument("step should match the exper start+n*step>end");
 // }
 return RangeIter{_step, _end};
 }
 RangeIter begin() {
 if (!args_check()) {
 throw std::invalid_argument("step should match the exper start+n*step>end");
 }
 return RangeIter{_step, _st};
 }
 RangeIter end() { return RangeIter{_step, _end}; }
};

这里对 begin 做了参数检查，避免意外的错误情况，导致无限循环之类的情况，其实正常情况应该是把RangeIter 这个迭代器实现给塞到 private 域里面去，避免他人骚操作；但这里只是一个简单的演示demo就不用考虑太多；

调用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


int main() {
 std::vector<int> val{1, 2, 3};
 int i = 0;
 rangeI(i, val.size()) { std::cout << val[i] << std::endl; }
 // 1
 // 2
 // 3
 try {
 for (auto i : Range(static_cast<int>(val.size()), 0, -1)) {
 std::cout << i << ";\n";
 }
 } catch (std::logic_error &e) {
 std::cout << "error" << e.what() << std::endl;
 }
 // 3;
 // 2;
 // 1;
 std::cout << std::endl;
}

总之复习了for range和迭代器实现

异步日志写实现

Mon, 02 Dec 2024 22:36:03 +0800

异步日志写实现

设计逻辑

内置 sync.pool 获取缓存，将 p 写入 bytes.Buffer，写入成功就将 buff 入队，然后使用轮询函数在循环中一直取队列里面的 buffer，使用刷写将缓存内容落盘，同时将缓存返回池中。在进程做优雅退出的时候，关联到异步写者，让其 for range 剩余的缓存，连续落盘；落盘写函数逻辑：

要写入的字节流长度是否大于缓存剩下的部分？
1. 是将当前写缓存内容刷写落盘，
2. 否直接追加到写缓存后面异步轮询的 poller 函数会从队列里面取出 next writer，如果不是空的就直接执行缓存操作，这部分用 select 来做个定时操作，如果较长时间没有新的日志进来，就先把缓存里面有的数据落盘

go 代码实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125



type FixSizeLargeBuff struct {
 buf []byte
}

const Megabit = 1024 * 1024

func NewFixSizeLargeBuff() *FixSizeLargeBuff {
 return &FixSizeLargeBuff{buf: make([]byte, 0, Megabit)}
}
func (f *FixSizeLargeBuff) Avail() int {
 return Megabit - len(f.buf)
}
func (f *FixSizeLargeBuff) Reset() {
 f.buf = f.buf[:0]
}
func (f *FixSizeLargeBuff) Append(p []byte) (int, error) {
 if f.Avail() < len(p) {
 return 0, fmt.Errorf("no avail free bytes")
 }
 f.buf = append(f.buf, p...)
 return len(p), nil
}

type SimpleAsyncWriter struct {
 data chan *FixSizeLargeBuff
 curbuff *FixSizeLargeBuff
 buffpool sync.Pool
 wt io.Writer
 lock sync.Mutex
 wg sync.WaitGroup
 ct *time.Ticker
 last time.Time
 active chan struct{}
}

func NewSimpleAsyncWriter(w io.Writer, limit int) *SimpleAsyncWriter {
 ret := &SimpleAsyncWriter{
 data: make(chan *FixSizeLargeBuff, limit),
 buffpool: sync.Pool{New: func() any {
 return NewFixSizeLargeBuff()
 }},
 wt: w,
 lock: sync.Mutex{},
 active: make(chan struct{}),
 ct: time.NewTicker(1 * time.Second),
 }
 ret.addCount()
 go ret.poller()
 return ret
}
func (s *SimpleAsyncWriter) addCount() {
 s.wg.Add(1)
}
func (s *SimpleAsyncWriter) Write(p []byte) (int, error) {
 select {
 case <-s.active:
 return 0, ErrorWriteAsyncerIsClosed
 default:
 }

 s.last = time.Now()
 s.lock.Lock()
 defer s.lock.Unlock()
 select {
 case <-s.active:
 return 0, ErrorWriteAsyncerIsClosed
 case <-s.ct.C:
 if s.curbuff.Avail() > 0 && time.Since(s.last) > 5*time.Second {
 s.data <- s.curbuff
 s.curbuff = s.buffpool.Get().(*FixSizeLargeBuff)
 }
 default:

 if s.curbuff == nil {
 s.curbuff = s.buffpool.Get().(*FixSizeLargeBuff)
 }
 if len(p) > s.curbuff.Avail() {
 s.data <- s.curbuff
 s.curbuff = s.buffpool.Get().(*FixSizeLargeBuff)

 }
 }

 if n, err := s.curbuff.Append(p); err != nil {
 return n, err
 }
 return len(p), nil

}

func (s *SimpleAsyncWriter) poller() {

 defer func() {

 for i := len(s.data); i > 0; i-- {
 d := <-s.data
 s.wt.Write(d.buf)
 }
 if s.curbuff.Avail() > 0 {
 s.wt.Write(s.curbuff.buf)
 }
 close(s.data)
 s.data = nil
 s.ct.Stop()
 s.wg.Done()
 }()

 for {
 select {
 case <-s.active:
 goto outer
 case d := <-s.data:
 s.wt.Write(d.buf)
 d.Reset()
 s.buffpool.Put(d)
 }
 }
outer:
}

func (s *SimpleAsyncWriter) Stop() {
 s.active <- struct{}{}
 s.wg.Wait()
}

基准测试

使用 law 的 benckmark 测试并给 BlackHoleWriter 类的 Writer 增加了时延模拟真实的落盘耗时，使用随机预先生成的字节数组队列来模拟真实负载填充，下面是 benckmark 测试的耗时

第一列是测试项-cpu 数，第二列是每秒钟执行的次数，第三列是耗时，第四列是每个操作分配的字节数(这个可能是我预生成的随机字节数组拷贝时产生的)，第五列是每个操作的分配次数

可以看到在 write 写操作平均耗时和平均分配的字节数来看，都有比较明显的优化，同时因为利用 defer 和 wait 机制联动，可以保证在调用 stop 是已经写入缓存的内容可以安全落盘，可以优雅推出，同步机制使用原生 channel 管道

特点

轻量级，代码简洁封装少，使用原生操作实现
多缓冲，使用sync.Pool 实现多级缓冲
安全并发，虽然使用了互斥锁，但是仅用在write 方法上，对性能影响足够小