Repository navigation
v1.4.0
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/base64x0.1.6 → 0.1.7、cloudwego/gopkg0.2.0 → 0.2.1、
dustin/go-humanize1.0.1 → 1.1.0(均为补丁版本,无 API 变更)。
7. 验收
go test ./...全绿、-race全绿、gofmt/vet 干净;verify-s1.sh415 / 0(含重启交接、405 契约、样式化 404、登录/登出、浏览器 DOM 各节);verify-interop.sh8 / 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.sh415 / 0(演示实例占着默认端口,用
ACS_TEST_PORT=17548复跑 —— 「起实例前先探端口」的防呆就是为这种情况写的)、
verify-interop.sh8 / 0。终验后开发/演示数据已全部清理(演示实例、模拟器设备、
测试固件件,清单见实现笔记)。 - 2026-10-12 界面改造后复跑:四轮改造后 build / vet / gofmt 仍干净,
go test ./...与-race全绿,verify-s1.sh415 / 0、
verify-interop.sh8 / 0(改造过程中断过一条断言 —— FTTR 实例号按
<td class="mono">精确匹配,模板加 nowrap 后失配,已同步放宽为
mono[^\"]*,功能未变)。 - 2026-10-12 审查修复后复跑:
verify-s1.sh415 / 0、
verify-interop.sh8 / 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 静态链接进单二进制)。