Skip to content

v1.5.0

Choose a tag to compare

@zy84338719 zy84338719 released this 17 Oct 13:49
· 13 commits to main since this release

v1.5.0 —— 工程规范对齐 oekit:健康端点、API 业务错误码、离线探测限流

一次工程规范与可观测性版本:把面板的热路径、容器探针、错误契约三处长期靠约定
撑着的地方改成有代码守着的,并补上 10 个新文件(8 个回归测试共 1313 行 + 2 个源文件 135 行)。数据库无迁移,
升级即换二进制。

本版的判定口径:没有引入新的破坏性契约。API 的 JSON 形状、状态码、CSV BOM、
Cookie、405/404 语义、零断点重启逐项保持不变;新增的错误码是加字段,旧脚本
继续可用。

1. 健康端点:探针不再打面板首页(web / deploy)

原来 k8s 的 startup / readiness / liveness 三条探针全部打 GET /。而 / 是面板
首页
——要渲染模板、查设备表、算统计:库忙时探针就超时,k8s 误判并把好端端的容器
重启掉;面板开了鉴权时它还会 401,让「服务是不是活着」这件事本身依赖了登录态。

新增三个专用端点(ACS 与面板两个端口都有,所以单端口/双端口都不用改探针端口号):

端点 用途 语义
/pingz liveness 只答 pong,不碰任何依赖,故障时不重启容器
/healthz readiness 真 ping 一次 SQLite,通不过就临时摘流量
/buildVersion 版本 出问题时把这行贴过来最省事

liveness 刻意不用 /healthz:库短暂不可用(比如磁盘抖动)时若据此重启,
就掉进「越重启越起不来」的死循环。liveness 只回答「进程还在不在」。

Dockerfile 的 HEALTHCHECK 与 deploy/k8s/statefulset.yaml 三条探针同步换过去。
换之前那个 wget / 是靠「未登录时 303 跳登录页、2xx/3xx 都算健康」这种巧合判断的,
语义不对;打 CWMP 路径更不行——协议只收 POST,GET 一律 405,容器会被永远判 unhealthy。

这组路由是 Hertz 原生静态路径注册,优先于 /*any 兜底;health_test.go 里
TestHealthEndpoints_BeatCatchAll 专门钉住「不能掉进面板兜底」。

2. API 业务错误码:8xxx 段,与设备侧 9xxx 隔离(web / biz)

以前 API 只给 HTTP 状态码 + 可本地化的 error 文案。问题是:脚本轮询 /api 时,
500 可能是「库写不进去」也可能是「这台设备正在被改」;400 可能是「ID 格式错」也
可能是「body 不是 JSON」。状态码只能表达大类,抓取方没法据此分支,只能去 match
错误文案——而文案会改、会本地化,拿来当接口契约必然烂掉。

新增稳定的 code 字段:

code 含义
8000 内部错误(未归类;含库写不进去等)
8001 请求不合法:设备 ID 格式错、body 不是 JSON、必填参数为空
8003 缺少或无效的凭据
8004 目标不存在(设备 / 端点不存在)
8005 该能力当前不可用(如未接入控制接口)

编号约定:8xxx 是 ACS 自己产生的,9xxx 留给 CPE→ACS 方向(设备报上来的
错误码),两边不共用号段——看一个码就知道是谁说的。

api_code_test.go 钉住这套映射。旧的只读状态码不变,脚本可渐进迁移。

3. 离线探测限流:1000 台设备同时掉线不再等于 1000 个并发连接(cwmp)

一批设备同时掉线时,每台待探设备都要独立等满 ConnReqTimeout(默认 10 秒)。
不设上限的话,1000 台设备同时掉线 = 1000 个并发 ConnectionRequest:轻则本机 fd 与
ephemeral port 被吃光、SQLite 写入排队,重则把 CGNAT 后面的设备和运营商侧一起顶住。

现在用闸(buffered channel)做硬上限,不靠「起个池子大概限制一下」:

  • -probe-concurrency / ACS_PROBE_CONCURRENCY,默认 20,<= 0 回落默认值;
  • 另加扫描互斥(sweepMu / sweeping):探测被限流后一轮可能跑很久,
    不能让下一次 tick 叠上来。

lifecycle_test.go 覆盖会话生命周期与探测并发闸。

4. 后台任务收编:统一 gopool / async.GoSafe,关库前排空(cwmp / store / alert)

原先散落各处的裸 go func 与临时池子改成 oekit/concurrency 的 gopool /
async.GoSafe(panic 被 recover 并汇报)。进程级 gopool 在关库前排空,
避免后台任务写到已关闭的 SQLite 上——那正是「偶发 database is closed」的来源。

库内调用方不必接线:bg == nil 时退回 async.GoSafe。
close_test.go 钉住关停顺序。

5. 面板静态资源走 Hertz 原生路由(web)

/static/(style.css + app.js)是面板每次开页必取的热路径,却没有动态逻辑。
以前整棵 http.ServeMux 经 adaptor.HertzHandler 挂在 /*any 兜底上,每个请求
都多走一跳 net/http.Request ⇄ hertz.RequestContext 转换,外加 http.FileServer
的一整套目录/重定向/Range 处理。

现在注册成 Hertz 原生路由(/static/*filepath,GET + HEAD),直接读 embed.FS
写 Hertz 响应。实测每请求服务端 CPU 省约 9%(42.6µs → 38.6µs,分配次数少 32%)。

附带纠一个流传的说法:oekit/hertz 的 adaptor.StaticFSHandler 并不绕开
adaptor
——它内部最后一行仍是 adaptor.HertzHandler。实测其每请求 CPU 与改动前
持平。已在 oekit/hertz#8 反馈,上游已
接受并补了 NativeStaticFSHandler(等发版后可替换本地实现)。

行为差异(均有意,且已钉测试):404 不带 Cache-Control(与改前一致,
net/http 的 serveError 会摘掉错误响应上的缓存头);不再发 Accept-Ranges
(没实现 Range 就不宣称);GET /static/ 目录本身回 404,不再列文件。

6. 依赖升级:14 个 oekit 模块全部到最新版

pkg v0.9.0→v0.11.0、concurrency v0.4.0→v0.5.4、core v0.3.3→v0.6.0、
hertz v0.5.2→v0.5.10、logx v0.2.0→v0.5.0、tracing v0.2.0→v0.2.1、
gormx v0.5.2→v0.5.4、middleware v0.5.1→v0.6.2、bootstrap v0.5.2→v0.5.3、
kitx v0.1.0→v0.1.1、nns v0.3.4→v0.3.5。零代码改动,逐模块升、逐模块全量
测试验证。go mod tidy 顺带修正了 core / hertz 被误标 // indirect 的问题,
并移除了 lumberjack.v2。

7. 回归测试(8 个新测试文件 / 1313 行)

本版新功能此前一条测试都没有,下次重构悄悄改回去不会有人发现:

  • web/health_test.go(156):探针语义 + 「不能掉进面板兜底」;
  • web/api_code_test.go(172):8xxx 错误码映射;
  • web/static_test.go(263):原生静态路由直出、逐字节比对、目录穿越拒绝、
    以及反向验证(不注册原生路由时请求必须落到兜底);
  • cwmp/lifecycle_test.go(249):会话生命周期 + 探测并发闸;
  • cmd/lightcat/shutdown_test.go(146):关停与零断点重启;
  • ontweb/jsonrepair_test.go(105)、store/close_test.go(86)、
    web/enqueue_notice_test.go(136)。

验收:go build / go vet / gofmt 全干净,全仓库测试通过,
web 与 cmd/lightcat 的 -race 通过,GenieACS 官方模拟器互通性验证 8/8
(换一个独立实现来打,才能证明真的互通,而不是两边犯了同样的错)。

8. 文档

  • docs/requirements.md 补 §13/§14:工程规范对齐 oekit 的三轮审计记录,
    含有意不采纳的项及理由(复核后维持),以及为什么不整包切 logx 门面;
  • CONTRIBUTING.md 补工程规范对齐的相关约定;
  • docs/notes/loadtest.md 补静态路由性能实测(测法、数字与为什么 QPS 不可信)。

升级提示

换二进制即可,无需迁移、无需改配置。新增的 -probe-concurrency /
ACS_PROBE_CONCURRENCY 有合理默认值,不配也能跑。