Skip to content

v1.4.0

Choose a tag to compare

@github-actions github-actions released this 11 Oct 18:15
· 25 commits to main since this release

v1.4.0 —— 后端 HTTP 引擎换 CloudWeGo Hertz,API 层按 hz/IDL 架构模式重组

一次引擎与架构层的重构,不是功能版本:对外行为契约(JSON 形状、状态码、CSV BOM、
Cookie、405/404 语义、零断点重启)逐项保持不变,415 项端到端断言原样复验全绿。
数据库无迁移,升级无感。

1. HTTP 引擎:net/http → Hertz

  • 单端口 / 双端口两个监听都跑在 Hertz(netpoll 内核)上;TLS(-tls-cert/-tls-key)、
    优雅退出(SIGTERM → 5 秒收敛)一并换用 Hertz 语义(WithTLS / WithExitWaitTime);
  • 零断点重启的 listener 交接保留:面板「立即重启服务」把活着的 net.Listener 交给
    新进程,Hertz 用 WithListener 收养现成句柄 —— 这条能力是换引擎最大的风险点,
    e2e 的重启章节(含双端口、句柄交接、新端口起不来回滚)原样通过;
  • 方法语义:WithHandleMethodNotAllowed(true) + POST-only 路由的 GET 孪生照旧显式回 405;
    面板陌生 GET 落样式化 404、/api 与 /metrics 落 JSON 404 的分流口径不变。

2. API 层:hz + IDL 的 biz 三层

  • 契约写在 idl/lightcat_api.proto(hz v0.9.7 + protoc 生成):biz/router(路由注册与
    guard 中间件挂载点)、biz/handler/api(解析请求 → 调服务层 → 写回)、biz/model(IDL 模型);
  • /api/* 生产流量走 hz 原生路由;guard 做成 /api 组中间件(面板会话 cookie 或
    Bearer token 二者其一,401 回 JSON),与旧 apiGuard 同一口径;
  • 逻辑单一出处:internal/web/service.go 的服务方法(返回 payload + 带状态码的
    APIError)。net/http 壳(单元测试直接打它)与 hz 壳(生产流量)都是薄包装,
    任何一边都不许私改 JSON 形状 —— 415 项 e2e 是这条纪律的执法者;
  • CSV 导出改成「先取数、后写头」两阶段:404/500 能在响应头落定前改走 JSON 错误,
    BOM 与编码由 WriteCSV 统一,两个壳口径单一。

3. 没动的部分(刻意)

  • internal/cwmp 协议内核零改写:会话状态机 / SOAP 编解码 / HTTP Digest 仍是
    http.Handler 形态,经 adaptor.HertzHandler 挂载。它是 415 项 e2e 与 GenieACS
    互通验证过的部分,为换引擎重写它只有风险没有收益;
  • 面板 HTML 处理器暂留 net/http 壳(经 adaptor 挂在 Hertz 上):服务端渲染 +
    415 项断言覆盖的展示契约,原生化的边际收益低于回归风险;边界与后续评估记在实现笔记;
  • 存储层、ontweb、alert、presets、files 等业务包零改动。

4. 依赖

  • 新增 github.com/cloudwego/hertz v0.10.6(含 netpoll);bytedance/sonic 升到 v1.15.4
    消除 go1.27/arm64 上的 fallback 告警(JSON 编解码在不受支持平台自动回落 encoding/json,
    行为不变);
  • 核心协议层(internal/cwmp)依旧零第三方依赖 —— 引擎与协议的分层让「协议稳定性」
    和「引擎演进」互不绑架(requirements §8 的依赖控制口径相应修订)。

5. 面板产品化(四轮界面改造)

引擎换对了不等于界面能用。这一节是发版前用真机数据(华为 V271-20,
399 参数 / 64 终端 / FTTR 子设备 3 台)逐页实地看下来、逐项收掉的粗糙感。

表格排版(最刺眼的一类)

  • 表头不折行:中文列名不再被压成「备/注」「参数/数」两行。
  • 全站 15 张表(最宽的 inventory 有 15 列)统一套滚动容器,窄屏横向滚动;
    标识符 / 时间 / 数值列一律 nowrap —— MAC 地址「6c:71:d2:1e:36:63」逐字符
    竖排、型号「V271-20」被拆成 V2/71-/20 这类问题由此消失。
  • 斑马纹改为按需启用:三行小表上色只是噪音。

信息层次

  • 设备详情页原来「状态 / 参数 / 任务 / 操作」四卡挤在一排,按钮竖排把卡撑高、
    状态卡却只有一个徽章,四张参差不齐。拆成一排等高指标卡 + 独立操作条,
    读操作在左、破坏性操作(重启 / 删除)在右。
  • 概览统计卡网格上限收到 260px:一个数字占满整卡、右侧大片留白,正是
    「内部工具」的观感来源。

交互细节

  • 空状态全部结构化(图标 + 标题 + 说明 + 下一步动作),并说明接下来会看到
    什么
    ,而不只是「现在没有」;设备清单的空态直接给出「查看接入步骤」入口。
  • 自动刷新前铺骨架灰条 + 顶栏进度条,消除每 5 秒一次的空白闪烁。

产品完整度

  • 版本号常驻顶栏(web.Version)——此前代码里根本没有版本定义,任何页面截图
    都不带版本号,报障时无法核对。
  • 新增 /help:这是什么 / 首次接入四步(ACS URL 怎么填、别填 127.0.0.1)/
    各页面职责 / 常见问题 / 版本与升级。第一次部署的运维不必去翻 README。
  • 英文词条 393 条全覆盖(此前每加一个功能就漏一批)。

顺带修掉的真 bug

  • 跨行拼接的 {{T "前半" "后半" }} 会被 Go 拼成一个 key:扫描正则只抓前半段
    (造成「已翻译」的假象),渲染时查不到,页面露出 %!(EXTRA string=…),中文版
    同样中招。已全部合并为单行,并加两条断言挡住(扫渲染结果的 fmt 残留、
    扫模板源码的跨行拼接)。
  • settingsView 缺 Version 字段(struct 不走 mergeCommon),导致设置页顶栏
    渲染直接失败。
  • 清理 1330 行无人 import 的 protoc 生成物(biz/model),移出版本库并进
    .gitignore;IDL 字段标记由 form 改为 raw_body(如实反映 handler 读 JSON body)。
  • ontweb 内建轮询补 panic 兜底:真机抓取遇到厂商网页改版不该拖垮整个服务。

6. 发版前的代码审查:修掉的三个实质问题

引擎与界面都收口之后,另做了一轮以「找缺陷」为目标的审查(重点在 cwmp 协议
内核、store 存储层、web 鉴权面、进程装配)。下面三条都有代码证据、都已修复,
其中第一条和第二条都会造成数据错误或信息泄露。

会话指纹撞车会把设备数据写错设备(cwmp)

无 cookie 时 sessionKeyOf 的兜底指纹是 (源IP, User-Agent, BasicAuth用户),
而开启 CPE 认证后 user 这一维对所有设备是同一个常量,指纹实际退化成
(源IP, User-Agent) —— 同一 NAT/CGNAT 出口、同型号同固件的两台设备会撞进
同一个会话。原 bindDevice 无条件执行 s.DeviceID = deviceID,于是 A 设备
的回执会按 sess.DeviceID 写进 B 设备名下:参数入库、设备信息合并、任务下发
全都取这个字段。

现在 bindDevice 发现会话已属于别的设备就丢弃该会话并返回 false,
调用方回一个 Fault 让 CPE 重开会话,而不是继续用一个 DeviceID 指向别人的会话。
(本次 Inform 的参数落库用的是解析出来的局部 deviceID,所以即便会话被丢弃,
本次上报也不会写错设备。)

配了 API Token 但没开面板账号密码时,Token 完全失效(web,信息泄露)

两条鉴权路径都被 opt.Auth.Enabled() 门控,而面板账号未启用时
APIAuthOK 首行直接 return true —— 于是「配了 Token」看起来有防护,
实际 /api/devices(含序列号、来源 IP、全部参数)、/api/files、/metrics
对全网可读,而设置页仍在提示 Token 已生效。

现在:配了 Token 就必须校验(登录态或 Bearer 二者其一),不因面板账号
未启用而放行;没配 Token 时才按「面板未开鉴权 = 本来就公开」的既有语义处理。
同时在启动日志里对「配了 Token 但未启用面板账号」打显式 WARN,说清楚面板页面
本身仍然对能访问该端口的人公开。

修这个洞时顺带暴露了 Hertz 侧与 net/http 侧的口径分叉:/metrics 走 mux,
/api/* 走 Hertz 原生路由,两边逻辑不同时只有生产流量才会炸(排查时表现为
「metrics 200 而 api 401」)。两处现已统一,并加了 9 种鉴权组合的断言钉住。

光功率历史的「读最近一条 → 决定合并还是插新行」不是原子的(store)

SetMaxOpenConns(1) 只保证单条语句串行,不保证这对读-改原子。TR-069 分批回执
与 ontweb 轮询撞进同一个窗口时,两路都会判定「需插新行」,趋势图上就多出一个
重叠点 —— 正是这个函数本来要消除的东西。现在把两步放进一个事务(事务内只用
txs、不回调 s.db,否则单连接下会自锁)。

依赖

  • cloudwego/base64x 0.1.6 → 0.1.7、cloudwego/gopkg 0.2.0 → 0.2.1、
    dustin/go-humanize 1.0.1 → 1.1.0(均为补丁版本,无 API 变更)。

7. 验收

  • go test ./... 全绿、-race 全绿、gofmt/vet 干净;
  • verify-s1.sh 415 / 0(含重启交接、405 契约、样式化 404、登录/登出、浏览器 DOM 各节);
  • verify-interop.sh 8 / 0(GenieACS 官方模拟器打 Hertz 引擎);
  • TLS 双监听实测(HTTPS 面板 200、CWMP 口 GET 405);容器冒烟(镜像重建、compose 起、
    cpesim 打容器纳管、Bearer/401/CSV 全查);
  • 2026-10-11 终验复跑:go build / go vet / gofmt 干净,go test ./... 与
    -race 全绿;verify-s1.sh 415 / 0(演示实例占着默认端口,用
    ACS_TEST_PORT=17548 复跑 —— 「起实例前先探端口」的防呆就是为这种情况写的)、
    verify-interop.sh 8 / 0。终验后开发/演示数据已全部清理(演示实例、模拟器设备、
    测试固件件,清单见实现笔记)。
  • 2026-10-12 界面改造后复跑:四轮改造后 build / vet / gofmt 仍干净,
    go test ./... 与 -race 全绿,verify-s1.sh 415 / 0、
    verify-interop.sh 8 / 0(改造过程中断过一条断言 —— FTTR 实例号按
    <td class="mono"> 精确匹配,模板加 nowrap 后失配,已同步放宽为
    mono[^\"]*,功能未变)。
  • 2026-10-12 审查修复后复跑:verify-s1.sh 415 / 0、
    verify-interop.sh 8 / 0、go test ./... 与 -race 全绿。鉴权改动用真实
    实例双端口实测:面板页 200、/api/* 与 /metrics 带登录态 200、无凭据 401。
  • 真机复核:华为 V271-20 经 ontweb 通道纳管(399 参数 / 64 终端 / 发光 -1.2 dBm),
    内建轮询连跑两轮稳定;/metrics 带 token 200、无 token 与错 token 均 401,
    Grafana 看板与实际暴露的 10 个指标双向全对齐。

升级

无数据库迁移;update.sh 照常。二进制体积与启动时间量级不变(Hertz 静态链接进单二进制)。