Skip to content

Releases

v1.5.4

Choose a tag to compare

@github-actions github-actions released this 17 Oct 16:18

v1.5.4 —— 已恢复的离线告警不再和正在发生的故障同色显示

补丁版本。无迁移、无配置变更,升级即换二进制。

问题

告警是留痕的:设备后来又报上了,那条「设备判定离线」记录不会自动消失。
而告警页原来给所有 offline 类记录都打红徽章,不看设备当前状态 —— 于是用户扫一眼
告警页会以为设备现在还离线着。看着像故障,其实早已恢复。

现网就有一条实证:10-16 判过离线,之后设备一直正常(ontweb 每 10 分钟采一次、
last_inform_at 持续刷新、online=1),但告警页上那个红「离线」徽章一直在。

做法

alertRows 多接一个「设备当前在线状态」的映射,给离线类告警算一个 Resolved
标志;模板据此把「已恢复」渲染成绿色徽章(沿用仓库既有的 .badge.on,与
「已推送」同一套样式),而不是红色 failed。

三个边界:

情况 处理 为什么
设备仍离线 不标恢复 该红还是红
设备已从库里删掉 标恢复 map 取不存在的键返回零值 false,分不出「仍离线」和「已删除」;用两值查找,人不在了就不该显示成还离线
收光过低 / 光口异常 不参与该语义 这两类没有「恢复」这层含义

顺带澄清一件一度怀疑错的事

「Web 通道纳管的设备会不会被误判离线」—— 不会。ontweb 每次采集都走
UpsertDevice,last_inform_at 与 online=1 都会刷新,而离线判定读的正是
last_inform_at。

(排查时我查的是 devices.last_seen —— 那一列根本不存在,真实列名是
last_inform_at。是查错了列名,不是它有 bug。记一笔:对着不存在的列名查出来的
None 什么都不能证明。)

验收

新增 1 个用例,钉住上面四种组合。全仓库测试通过、全量 -race 通过、
GenieACS 官方模拟器互通性 8/8。

v1.5.3

Choose a tag to compare

@github-actions github-actions released this 17 Oct 15:47

v1.5.3 —— 修正 v1.5.2 别名迁移的大小写去重失效

补丁版本:v1.5.2 的迁移 #19 有 bug,本版修正并清理。有两条迁移
(#19 改写、#20 新增),升级即换二进制。

问题

v1.5.2 的迁移 #19 补齐 ontweb 光口参数别名时,把 match_contains 写成小写
'x_hw_lanopticinterface'(少了 Config),而表上已有的(现网手工补过的、
也是 #19 该沿用的)写法是 'X_HW_LANOpticInterfaceConfig'。

param_aliases 的 UNIQUE(field, match_contains, match_suffix) 对大小写敏感,
所以 INSERT OR IGNORE 根本没去重成 —— 现网老库上每个字段多插了一行,
别名总数 14 → 18。

行为是无害的:Matches() 两边都 strings.ToLower,两条规则匹配结果一致,
读数不变。但同一个字段存两份来源不同的规则,以后排查「这条规则哪来的」会说不清。

更要紧的是:v1.5.2 的提交说明与发版说明里都写了「老库不会重复插入」——
那句话当时是错的,需要更正。

修正

  1. 迁移 #19 改用规范写法 'X_HW_LANOpticInterfaceConfig'(与真机参数路径
    …X_HW_LANOpticInterfaceConfig.1.… 一致)。新库不会再插重复行。
  2. 新增迁移 #20:清掉老库里已经插进去的重复行。

迁移 #20 的第一版也写错过(记一下)

#20 的 DELETE 第一版写成
lower(match_contains) = 'x_hw_lanopticinterfaceconfig' —— 找的是带 Config 的,
而实际要删的重复行是不带 Config 的小写值。又一次等值匹配漏掉了,
等于一条都删不掉。

现在改成:

DELETE FROM param_aliases
 WHERE lower(match_contains) LIKE '%lanopticinterface%'
   AND match_contains <> 'X_HW_LANOpticInterfaceConfig'

这一族里凡不是规范写法的一律清掉,比逐个形态列举更不容易再漏 ——
这次的教训就是「形态比想象的多」(大小写、缺后缀,两处都中招了)。

测试

新增 TestOntwebAliasNoCaseDuplicate:按现网真实状态复现 —— 跑完 #19 后人为插入
那 4 条重复行、把 user_version 退回 19(模拟「跑过 #19、还没跑 #20」),
重开后 #20 必须清干净,且一条正常的都不能误删。

这个测试是必要的:v1.5.2 里那条 TestOntwebAliasMigrationIdempotent
只验「重开不再加」,对一个从来没去重成功过的迁移当然是通过的 ——
它测的是「迁移不会重复应用」,不是「迁移不会插出重复行」,两回事。

另修两处:TestSeedCoversOntwebOpticParams 的断言大小写跟着 #19 走;
TestSeedDoesNotFakeRxPower 改成大小写不敏感比较。

验收

全仓库测试通过、全量 -race 通过、GenieACS 官方模拟器互通性 8/8。

升级提示

换二进制即可,无需改配置。迁移自动执行:

  • 新装机器:#19 直接插规范写法的 4 条,#20 无事可做;
  • 已升到 v1.5.2 的机器:#20 清掉多出来的 4 条重复行。

无论哪种,最终别名表都是「该族 4 条、全是规范写法」。

v1.5.2

Choose a tag to compare

@github-actions github-actions released this 17 Oct 15:39

v1.5.2 —— 补上 ontweb 光口参数种子,收光盲区不再静默

两处一起修,因为它们是同一个盲区的两半。有一条迁移(补 4 条别名规则),
升级即换二进制,无需改配置。

1. 种子缺了 ontweb 通道那一族参数 —— 只影响新装机器

别名种子(迁移 #6)是照 TR-069 通道在真机上对出来的:

  • X_CU_WANEdgeONTPONInterfaceConfig.OpticalTransceiver.*(光模块寄存器原始值)
  • X_GponInterafceConfig.*(同一台设备的整数近似值)

而 ontweb 通道(光猫 Web 普通账号)把光口信息页的读数写成 TR-098 形状的
InternetGatewayDevice.LANDevice.1.X_HW_LANOpticInterfaceConfig.1.* ——
那一族一条规则都没有。

后果:新装的机器纳管华为 V271-20 走 Web 通道时,收/发光/温度/电压/偏流在
参数驱动的视图(概览页、清单页)里全认不出来,只剩 optical_history 兜底。

现网那台机器的 14 条别名里有 4 条是手工补的 —— 所以只有新装机器受影响,
这类问题天然难被发现(现网是好的,新装的是坏的)。

新增迁移 #19 补齐这 4 条,换算已在现网逐条核对:

参数 原始值 decode 换算
TransceiverPower 7499 dbm_01uw −1.24997 dBm
SupplyVoltage 31450 mv01 3.145 V
TransceiverTemperature 13056 div256 51.0 ℃
BiasCurrent 9500 ua2 19.0 mA

用 INSERT OR IGNORE + 表上的 UNIQUE(field, match_contains, match_suffix) 去重,
老库(已手工补过)不会插出重复行——迁移幂等,有测试钉住。

刻意不加 rx_power 规则:华为 V271-20 的 UserOpticInfo 只给 TX/电压/温度/
偏流四个原始值,固件不提供上行收光。加一条永远命不中的规则,只会让人以为
「配了就能读到」——这正是下面第 2 条要根治的毛病。

2. 收光读不到时不再「静默」

原来「读不到收光」和「收光正常」在界面上长得一样:概览页/清单页一个裸 -,
详情页整块趋势图悄悄消失。人只会读成「收光正常」。

而收光过低告警(rx_low)在这种情况下永远不会触发,却没有任何提示 ——
典型的静默盲区:功能看起来在工作,实际是瞎的。

现在把三件事分开:

情况 界面
收光有值 正常显示
认得出 TX、认不到任何 Rx 参数,历史里从未出现过收光 显式显示「本采集通道不提供收光功率读数」,并说明收光过低告警不会触发
两个方向都没有 仍是 -(那才是「这轮没采到」)

判据落在 HostOptical.RxUnavailable(),概览页、清单页、详情页三处统一。

这个盲区能不能消掉:这台光猫做不到。收光要靠 TR-069 纳管读 RXPower,
而普通账号拿不到(这也是为什么默认走 ontweb 通道)。想要收光告警,得让设备
接受 CWMP 纳管(需要运营商超管权限配 ACS URL)。现在至少它是可见的,
而不是看起来一切正常。

验收

新增 6 个用例:判据三态、历史里出现过收光就不算能力缺失、种子覆盖、不加假
rx_power 规则、迁移幂等、以及一条端到端(详情页必须出现那句说明)。

全仓库测试通过、全量 -race 通过、GenieACS 官方模拟器互通性 8/8。

升级提示

换二进制即可,无需改配置。迁移 #19 自动执行,对已手工补过规则的老库无副作用。

v1.5.1

Choose a tag to compare

@github-actions github-actions released this 17 Oct 15:12

v1.5.1 —— 可靠性补丁:janitor panic 静默停摆、trace_id 日志洪水、webhook 重试与串联

v1.5.0 的收尾修复。数据库有一条迁移(informs 表加 trace_id 列),
升级即换二进制,无需改配置。

判定口径:不引入任何破坏性契约。API 的 JSON 形状、状态码、Cookie、
405/404 语义、零断点重启全部保持;新增的错误码与 trace 字段都是加的。

1. 周期循环一轮 panic 会静默停摆(cwmp / cmd)—— 本版最要紧的一条

三处周期循环(离线巡检 / 会话清理 / ontweb 采集)原先都是「整个 for-select 塞进
一个 `goBg` 任务」:

```go
s.goBg(func() {
t := time.NewTicker(interval)
for {
select {
case <-ctx.Done(): return
case <-t.C: doSomething() // ← 这一轮 panic 会带走整个循环
}
}
})
```

一轮 panic 虽然被 `async.GoSafe` recover 了、进程不崩,但那会同时带走循环协程:
离线巡检停摆 → 设备离线永远不会被判出来;会话清理停摆 → 超时会话永不释放,
`byID` 一直涨;ontweb 停摆 → 光功率趋势不再更新。

而且没有任何告警 —— recover 把 panic 吃干净了,表现为「功能慢慢不工作了但
日志里什么都看不到」,是最难查的那类问题。

现在三处都交给 `oekit/concurrency/loop`,它把四个易漂移的语义一次钉死:单轮 panic
收编、停机排水、忙时丢 tick、首跑延迟可被打断。其中停机排水直接续上 v1.5.0
的关停契约(关库时正在写库的巡检不会被拦腰砍断)。

先写测试复现再改:手写版本第 3 轮 panic 后 120 ms 内只跑了 3 轮(`---\nFAIL`),
换成 loop.Run 后同场景通过。

2. trace_id 被客户端灌爆日志(web)—— 安全修复

新增 trace_id 时手搓的中间件有个漏洞:客户端传入的 `X-Trace-Id` 被原样采信,
逐字写进该请求的每一条日志行。实测一个带 2000 字节 `X-Trace-Id` 的请求:该值的
前缀出现在 11 行日志里,日志最长行 2196 字节。单个请求就能灌爆日志,
配上可换行的值还能伪造日志条目。

换成 `oekit/middleware/hmw` 的中间件后同一个请求:污染行 0,最长日志行
262 字节,落库的是合法 12 位十六进制。hmw 还多做了三处注入的一致性
(响应头 / RequestContext / 标准 ctx)与客户端 ID 的白名单校验。

3. 告警 webhook 改有界重试(alert)

原来失败只记日志、不重试。理由「重试风暴对家庭网络没好处」前半句对(所以不该无限
重试),但「完全不重试」对幂等接收端(Grafana / Alertmanager / 自建转发器)偏保守:
一次网络抖动导致的推送是白白丢的,而接收端根本不知道你来过。

四个上界缺一不可:次数 3、单次退避 8s、抖动 500ms、单条总时长 30s。只对可重试错误
重试(连接失败 / 超时 / 429 / 5xx);其余 4xx 是接收端明确拒收,重试毫无意义。

关停契约上有个坑值得记:issue 里只提了「退避等待要能被 ctx 打断」,但 `hc.Timeout`
是 10s、比关停窗口(5s)还长,接收端根本不回时会卡在 `hc.Do` 里整整 10s,把库写入
排空的时间挤掉。所以请求本身也绑了进程 ctx,两种卡法都补了测试。

4. 设备上报 trace_id 串联(cwmp / web)

一次设备 Inform 会打出「收到 Inform」「已入队:取设备基本信息」「入队采集光功率」
等十几条日志,散在 cwmp / web 两层,用户报障贴一段日志出来,我们没法回答
「这十几条是不是同一次上报」。

现在一次 Inform 触发的全部日志共用一个 trace_id。落库到 `informs` 表(迁移 #18),
面板「上报记录」多一列、点一下复制 —— 用户报障时贴这一个值,我们就能在日志里捞出
整条链。

配套改法记一笔:trace_id 挂在 ctx 上,而 `slog.Logger.Info`(无 Context 变体)
根本拿不到 ctx,靠调用点加属性等于 111 个日志点都要记得传。所以做成
`internal/trace.SlogHandler` 包一层 `slog.Handler`。用户可见的日志格式不变,
末尾多一个 `trace_id=`。

5. 两条被实测否决的「优化」(store / web)

v1.5.0 的压测文档里挂着两条写入优化待办,这次按「先测再动」的原则验了,两条都是
反向的
,已从文档改成实测结论,免得后人对着一份看起来很有道理的待办去优化一遍。

批量多行 INSERT:慢 1.7 倍。 一批 200 条参数:

写法 ns/op allocs/op
逐行 Exec(现状) 418,194 2813
多行单语句 chunk=50(最优点) 717,827 1095

分配少一半却慢 1.7 倍,chunk 从 5 到 200 全扫过没有一档能赢,缓存 SQL 文本
(按行数缓存预编译语句)也救不回来(830 µs)。原因不是解析:逐行版本来就只
Prepare 一次,多行版把 200 行塞进一条反而让 SQLite 的 upsert 走不了逐行快路径。

复用 prepared statement:只占 4.6%。 Prepare 单独量 20 µs,整批 418 µs。
且 `MaxOpenConns(1)` 下事务已占住唯一连接,要复用必须在 `Begin` 之前备好
(事务内再 `db.Prepare` 会死锁,实测踩过)。

另外 v1.5.0 关闭的 OEK-6(settings 缓存)基线也补测了:`GetSetting` 3.8 µs,
是面板本来就在做的那些查询里最便宜的,占 P95 预算 0.008%,不做。

依赖

oekit 全量到最新版(pkg v0.11.0 / concurrency v0.5.4 / core v0.6.0 /
hertz v0.5.10 / logx v0.5.0 / middleware v0.6.2 等),零代码改动。向 oekit 反馈了两条
并已被接受:logx#12(缺给裸
`slog.Handler` 注入 trace_id 的包装)、concurrency#15
(retry 缺 HTTP 可重试性判定)。

验收

全仓库测试通过、全量 `-race` 通过、GenieACS 官方模拟器互通性 8/8、
新增 14 个回归测试用例。

升级提示

换二进制即可。有一条迁移(`informs` 表加 `trace_id` 列),首次启动自动执行。

v1.5.0

Choose a tag to compare

@zy84338719 zy84338719 released this 17 Oct 13:49

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 有合理默认值,不配也能跑。

v1.4.1

Choose a tag to compare

@github-actions github-actions released this 11 Oct 19:08

v1.4.1 —— 补丁:会话归属残留、设置页英文译文与文档校正

v1.4.0 换引擎后的收尾修复。无数据库迁移、无配置变更、无破坏性改动,升级即换二进制。

1. 会话被丢弃后仍带着旧设备 ID(cwmp)

v1.4.0 加了「会话指纹撞车就丢弃该会话」的保护(同一 NAT/CGNAT 出口、同型号同固件的
两台设备会撞进同一个会话,bindDevice 无条件覆盖 DeviceID 会让 A 设备的回执写进
B 设备名下)。但 dropLocked 只从 byID/byKey/byDevice 三个 map 删了索引,
没清会话对象自身的 DeviceID。

那个 *Session 可能还被别处持有(inflight 的 HTTP 请求、Cookie 重放)。带着旧
DeviceID 的它一旦被继续使用,回执还是会落到那台设备名下 —— 正是那次修复要防的事。
现在 dropLocked 会把 s.DeviceID 置 0;置 0 也让 bindDevice 的「已属于别的设备」
判断重新成立(0 = 未绑定)。

这条是补回归测试时被断言查出来的(修复 bindDevice 时只顾着清 map,漏了对象字段)。

2. 三处修复的回归测试

v1.4.0 的三个修复原本一条测试都没有,下次重构把它们悄悄改回去不会有人发现。
本次补上,并把「测试守得住」验证过(把事务改回去,同窗口立刻插出 9 条而不是 1 条):

  • cwmp/session_bind_test.go:撞车拒绝改绑 + byDevice 不得残留(残留会让
    hasSession 恒真,任务再也不排队)、同设备顶掉旧会话、同设备反复重绑幂等;
  • store/optical_history_test.go:8 路并发写同一窗口,-race 下仍只合并成 1 条;
  • web/settings_listen_test.go:normalizeListen 此前零测试 —— 它是唯一挡住
    「面板被绑到意外地址」的一道关(设成 0.0.0.0 的后果是静默的),7 个合法 +
    6 个非法输入。

3. 设置页提示语的英文译文(web)

英文界面下改端口 / 改密码 / 设 token 全会露出中文 —— 而这几个恰是管理员最常做的动作。
补 9 条(含「已保存」「密码至少 6 位」「两次输入的密码不一样」与三条 token 校验)。

附带一条经验:带动态尾巴的("保存失败:" + err)必须写成带 %s 占位符的词条,
否则 TSmart 的整串匹配查不到(catalog 里没有那个完整串),会静默回落成中文 ——
光看词条表「有没有这条」查不出问题,得实跑。

4. 文档校正

  • README 徽章不再裂图:GitHub 会把所有 README 图片经 Camo 代理回源,而 shields.io
    在这条路径上稳定超时(直连 200 / 0.4s,经代理 504 / 4.6s)。CI 与 Release 徽章改用
    GitHub 官方的 actions/workflows/<file>/badge.svg,Go 与 License 徽章改为仓库内自带的
    SVG(docs/images/badges/),从此不依赖任何外部图床。
  • 鉴权语义写对:README / DOCKER.md 原文是「开了面板鉴权时,/api 与 /metrics 认两种
    凭据」—— 这个限定在 v1.4.0 已不成立。现在写清:配了 token 就一定校验,与面板账号是否
    启用无关;不配则跟随面板自身鉴权。
  • 补上 v1.4.0 漏记的功能:/inventory 资产盘点页、/help 使用帮助、设置页一键下载
    Prometheus 抓取配置与 Grafana 看板;目录结构补 idl/ 与 biz/。
  • 验收项数:CONTRIBUTING 写的「当前 373 项」实为 415 项,已更正。
  • 部署文档:K8s 镜像示例跟随版本;DOCKER.md 补 compose 层的 LIGHTCAT_* 变量表
    (含 LIGHTCAT_PASS 的 :? 校验对所有子命令生效这条易踩的规则)。

已知边角

TSmart 对嵌套括号拼出来的句子翻不干净(如 无线组网(信号 75%(3/4 格)):外层翻了、
里头的「/4 格」留着)。根因是非贪婪捕获加后续字面量锚定在嵌套括号处提前闭合,而译文里
又保留着中文括号;加兜底会被同一条词条的宽松正则再匹配回去形成死循环。属于该匹配策略的
固有局限,修它需要换成按括号配平切段,是独立一件事,本次不扩大改动面。

验收

  • go build / go vet / gofmt 干净,go test ./... 与 -race 全绿;
  • verify-s1.sh 415 / 0、verify-interop.sh 8 / 0。

升级

无数据库迁移;update.sh 照常。二进制体积与启动时间量级不变。

v1.4.0

Choose a tag to compare

@github-actions github-actions released this 11 Oct 18:15

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 静态链接进单二进制)。

v1.3.0

Choose a tag to compare

@github-actions github-actions released this 11 Oct 02:04

v1.3.0 —— 监控与运维能力大批量落地:趋势 / 告警 / 预设 / 固件升级 / HTTPS / 指标

按「监控工具为主轴」的演进规划做的一轮:光功率趋势补全、阈值告警、预设(Preset)、
固件远程升级、HTTPS、Prometheus 指标与 API token
。数据库有结构变化(迁移 #9~#15),
升级用 update.sh 照常走,迁移自动执行、不丢数据。

1. 光功率趋势:补收光列 + TR-069 通道接入

  • optical_history 表新增 rx_dbm(迁移 #9):Web 适配通道的普通账号读不到上行收光(存 NULL),
    TR-069 通道能读到 —— 两条通道共用同一张历史表,详情页有数据的线才画(收光绿 / 发光蓝 / 温度黄)。
  • TR-069 设备也有趋势了:cwmp 加了 OnParamsStored 钩子,GetParameterValues 回执入库后,
    用与面板同一套口径(映射表 + 兜底启发式)认出光模块读数记进历史;一个读数都认不出的
    采集批次不留空行。同一次采集被拆成十几批回执(真机单批上限 256 个参数名),5 分钟窗口内
    合并成一个趋势点,图上不会全是重复点。
  • 历史保留期成为配置:-optical-history-days(默认 30,0 = 不限),写入时顺带裁剪
    (裁剪按 ts 走索引,迁移 #15 —— 几百台 × 每 10 分钟一条 × 30 天也不会退化成全表扫)。

2. 阈值告警(新表 alerts,迁移 #10/#11)

收光过低(默认 < -27 dBm)、光模块过温(默认 > 70 ℃)、光口状态异常(Web 通道的 Down/LOS)、
设备判定离线 —— 自动记录进库:

  • 顶栏新增「告警」页(带条数徽标),设备详情页有「最近告警」块;
  • -alert-webhook 配一个地址就 POST JSON(kind/message/value/threshold/序列号/时间),
    10 秒超时、失败不重试只记日志 —— 告警主体永远在库里,推送是尽力而为的旁路;
  • 同设备同类告警有冷却窗口(-alert-cooldown,默认 6h),持续越限不轰炸;
  • 读数缺失的项不评估:没读到不告警,与面板「宁缺毋编」同一口径。

3. 预设 Preset(新表 presets/preset_fires,迁移 #12/#13,需求 FR-10)

「什么事件 / 什么条件下,自动对设备做哪串操作」——全是数据,面板「预设」页增删启停:

  • 触发:Inform 事件码(0 BOOTSTRAP / 1 BOOT / 2 PERIODIC…)或「首次纳管」,可叠加参数条件
    (名字后缀匹配 + eq / ne / contains / exists);
  • 动作:每行一个,SET 参数名=值|类型、GET 参数名;相邻同类行合并成一条 RPC;
  • 命中后在同一次会话里按序下发(纳管即配好,不等下一轮周期上报);
  • 默认每台设备只触发一次;编辑预设会清掉触发记录(改过的预设重新生效一次);
  • 预设数据写坏(未知动作类型)只跳过并留痕,不炸会话。

4. 固件远程升级(新表 files,迁移 #14,需求 FR-11 / 里程碑 M4)

面板「固件」页跑通全链路:上传(落盘 -files-dir,磁盘名 = 服务端随机十六进制,
用户文件名只做展示;SHA-256/大小自动入库)→ 下发(选设备 + DelaySeconds 错峰,
入队 Download 任务)→ 设备收到指令后自己来拉 /files/<随机名>(内置文件服务;
双端口部署时挂在 CWMP 侧,设备只连 ACS 端口也能取件)→ 设备发 TransferComplete(CommandKey)
回报成败,任务历史可见;接受后 2 小时未回报由巡检判失败。

安全口径:取件端点不做面板鉴权(设备没有登录态),靠 128 位随机名 + 只放行库内登记 +
精确匹配(无目录列表);上传的原始文件名永远不参与拼路径(展示名也过 filepath.Base)。
文件 URL 基地址优先 -acs-url(设备视角可达地址);没配就按面板访问地址兜底并明确提示核实。

5. HTTPS(FR-1 的 TLS 项)

-tls-cert + -tls-key(成对,PEM)后 ACS 与面板两个监听一起切 TLS ——
运营商固件要求 ACS URL 走 https 的场景不用再套反代。证书读不了启动即报错(不留到第一个请求);
只配一半视为笔误直接拒绝启动。零断点重启的句柄交接对 TLS 同样有效。

6. /metrics 与 API token(FR-13 / FR-14)

  • GET /metrics:Prometheus 文本格式(0.0.4),零第三方依赖。设备/在线/探测中、参数行、
    任务(pending/running/failed)、上报与告警存量、光功率历史行数 —— 全部来自一条 Stats() 查询,
    抓取再频繁也扫不疼库。流水表按保留上限裁剪过,如实按 gauge 暴露存量、不冒充 counter。
  • -api-token:/api/* 与 /metrics 支持 Authorization: Bearer <token>(常量时间比较),
    脚本与 Prometheus 不用面板登录态;没配 token 行为与从前完全一致。机器端点未认证一律回
    401 JSON(不再 303 跳登录页 —— 抓取器不该拿着一坨 HTML 当指标解析)。

7. ontweb:机型配方(profile)抽象 + 不静默失败

  • 页面路径、登录握手、JS 构造器正则、AJAX 参数域全部收进 internal/ontweb/profile.go 的
    配方结构;支持一台新机型 = 照抄一份配方改数据,采集流程与入库口径不动。
    抓到设备信息后按自报型号/固件自动重选配方。
  • 解析失败不再静默:某页认不出内容会进 Snapshot.Warnings(CLI 打印、内建轮询打 WARN 日志),
    硬失败的错误信息带上检测到的型号/固件与适配入口。
  • 命令行 -from-dir 离线模式同样输出软诊断。

8. 验收脚本修复(在 macOS 上真跑才暴露的三个历史 bug)

  1. bash 3.2 会把紧跟 $VAR 的全角标点首字节并进变量名(echo "$PORT," → unbound variable),
    脚本统一改 ${VAR} 写法;
  2. 项目更名 acs → lightcat 后 verify_s1.py 仍找旧名:第 26 节凭据断言必失败,
    浏览器 DOM / 双端口 / 自动刷新 / 离线判定四节被静默跳过(skip 不计失败所以一直没暴露);
  3. 37e 的 skip() 调用引号混用,走到跳过分支直接 TypeError 崩掉整个验收。

顺带把验收脚本自己的边界钉死:所有 HTTP 走唯一出口(只允许回环地址 + 强制不走系统代理 ——
macOS 系统代理不豁免 127.0.0.1,开着代理时验收会随机 502)、所有日志读写不得越出 $WORK。

9. 模拟器与端到端验收扩容

test/cpesim 补上了 Download 的真实实现:收到指令后真的去拉文件(校验 URL 可达、
字节数与 FileSize 一致),按协议另起一次会话发 Inform(7 TRANSFER COMPLETE) +
TransferComplete(CommandKey),成功/失败码都如实回报。验收脚本相应新增三节:

  • 39 固件下发全链路:面板 multipart 上传 → SHA256/大小自动算对 → 取件端点匿名可取且
    内容原样 → 下发入队 → 模拟器自拉 → TransferComplete 结案(任务 done)→ 结案后允许再次下发;
  • 40 预设全链路:面板建预设 → 新设备 0 BOOTSTRAP → SET/GET 在同一次会话内生效
    (参数入库可查)→ 第二轮 BOOTSTRAP 不重复下发(每台一次)→ 停用接口可用;
  • 41 阈值告警全链路:收光 -15.95 dBm 低于验收实例的 -10 阈值 → 告警自动记录
    (带读数/阈值/设备关联)→ 冷却窗口内只记一条 → 告警页与设备详情页可见。
  • 42~44 标签 / 收光榜 / CSV(本版 §12 的端到端):保存→去重→详情页/概览页渲染→
    ?tag= 与 /api/devices?tag= 筛选→清空;收光最弱榜出现且读数正确;两个 CSV 端点
    的 BOM/表头/数据行/limit/404 全查。

10. 发布链更名收尾(acs → lightcat 的遗留断点)

更名提交(4e1e8e3)只改了一半,发布链实际上是断的:build-release.sh 找
deploy/lightcat.service(文件还叫 acs.service,打包直接失败);就算打出来,
install.sh 找包内 acs 二进制(打包产物叫 lightcat,安装必失败)。这版修齐:

  • 单元模板改名 deploy/lightcat.service;ExecStart 不再硬编码 -db,数据库路径由
    EnvironmentFile 的 ACS_DB 决定(命令行 flag 优先级高于环境变量,旧模板会把 env
    里的自定义路径顶掉);
  • 发布包名 lightcat-<版本>-linux-<架构>.tar.gz(与 README 一致);包内二进制
    lightcat + acs 兼容硬链接(同一 inode);同时产出 acs-* 兼容包名副本并一起
    进 SHA256SUMS —— ≤v1.2.x 存量安装的 update.sh 按 acs-* 资产名下载、按 -name acs
    找二进制,两个兼容点保证它们的 sudo ./update.sh 不断;
  • install.sh:二进制装到 /usr/local/bin/lightcat(systemd 服务名仍是 acs,单元装成
    acs.service,systemctl 习惯不变);老落点自动接管 —— /var/lib/acs 有库而新位置
    没有时沿用老目录与老配置(/etc/default/acs),老库文件名 acs.db 也沿用,
    重装不会把旧数据晾在一边;
  • update.sh:换二进制写单元 ExecStart 实际引用的路径(老布局 /usr/local/bin/acs、
    新布局 /usr/local/bin/lightcat 都升得动,不按名字猜);下载资产先试 lightcat-*
    再回退 acs-*(指定老 tag 升级也能用);本地 --file 两种包名都认;备份/健康检查
    同样接管老落点;
  • uninstall.sh:两种二进制名都清;--purge 找得到老落点的数据与配置。

发布 v1.3.0 时请把 lightcat-* 与 acs-* 两组 tar.gz 都传上 release 资产。

11. 容器部署(Docker / Kubernetes)与发布流水线

  • Dockerfile(仓库根):多阶段构建;构建段固定在 runner 架构(--platform=$BUILDPLATFORM)
    用 Go 交叉编译,不需要 qemu 就能出 amd64/arm64 双架构;运行段 alpine(带
    ca-certificates 与 tzdata),非 root(uid/gid 10001),数据只有 /data 一个目录。
    镜像内置 HEALTHCHECK;双端口部署时健康检查必须打面板端口(LIGHTCAT_HEALTH_PORT)——
    CWMP 专用端口对 GET 一律 405(协议只收 POST),探活会误报。
  • docker-compose.yml:双端口(7547 设备侧 / 8080 面板)+ ./data 落盘;面板密码用
    ${LIGHTCAT_PASS:?} 强制显式提供,防止误把无鉴权面板开进局域网。
  • deploy/k8s/:StatefulSet(replicas 恒为 1 —— SQLite 单写者是硬约束,单副本滚动
    更新 = 先停旧再起新,不双实例抢 RWO 卷)+ PVC 模板 + 双 Service(CWMP LoadBalancer /
    面板 ClusterIP)+ 三探针打面板端口 + 非 root / 只读根文件系统 / drop ALL capabilities;
    local-path 这类不支持 fsGroup 的存储由 fix-data-perms initContainer 兜底。
    kustomize 一键部署,文档在 deploy/k8s/K8S.md。
  • CI 扩容:ci.yml 新增 manifests 校验(kubeconform -strict)与镜像可构建性
    (buildx 只建不推 + GHA 缓存);新增 release.yml(tag 触发):多架构镜像推 ghcr.io +
    build-release.sh 产物传 GitHub Release(发布说明取 docs/releases/<tag>.md)。
  • 文档:deploy/DOCKER.md(含国内网络镜像源配置、以及「系统代理在 VPN-only 网段时
    Docker VM 路由不到」的坑位说明)、deploy/k8s/K8S.md、README 中英新增「容器部署」章节。

12. 面板运维增强:设备标签 / 收光最弱榜 / CSV 导出

  • 设备标签(device_tags 表,迁移 #16/#17):详情页「标签」块,逗号分隔、最多 16 个、
    单个最长 24 字符(超长截断、自动去重)。一标签一行的建模让筛选与计数都走索引,联合主键
    天然去重,设备删除随外键级联清掉。纯面板侧数据,不下发设备。
  • 按标签筛选:概览页标签 chips 条(带每标签设备数),URL 可分享(/?tag=,与搜索、
    在线状态筛选可叠加);设备行里的标签徽章可点即筛;/api/devices?tag= 同款过滤,
    CSV 导出跟随当前筛选。空筛选结果有专门空态。
  • 收光最弱榜:概览页新增区块,按「每台设备最近一次收光读数」从低到高取前 5。
    取最近一条用相关子查询走 (device_id, id) 索引;没有收光数据的设备不参与
    (Web 通道读不到上行收光,不拿 NULL 冒充垫底)。统计卡片维持两张的既定口径不动。
  • CSV 导出:GET /api/devices.csv(设备清单 + 最近光功率读数 + 标签 + 备注)与
    GET /api/devices/{id}/optical.csv(光功率历史,?limit= 默认 1000 / 上限 10000)。
    UTF-8 带 BOM(Excel 双击不乱码);鉴权与 /api/* 一致(面板登录态或 Bearer token);
    空读数如实留空列,不编数。面板入口:概览页搜索栏「导出 CSV」、详情页趋势图下「导出历史 CSV」。

13. 面板一致性打磨:统一顶栏 / 样式化 404 / 动作反馈归一

此前每个页面各手抄一份顶栏,已经抄漂了:设置页缺「预设 / 固件」入口、设备详情页只剩
「设置」、无线编辑页连「退出」都没有、告警徽标只有概览页有。这轮把观感与反馈收敛成同一套契约:

  • 共享顶栏 partial(templates/layout.html 的 topnav):品牌(可点回首页)+ 五个栏目
    链接(设备列表 / 告警 / 预设 / 固件 / 设置,当前栏目高亮)+ 告警徽标(所有页面统一
    显示,计数挪进 pageCommon)+ 自动刷新(只出现在概览页与设备详情页这类数据页;表单编辑页
    一律不给,免得把没提交的表单刷没)+ 主题 / 语言 / 退出。页面用 .Section / .CanRefresh
    两个数据位声明自己是谁,其余由 pageCommon 兜底(settingsView 是 struct,字段显式带上)。
  • 样式化 404:面板里的未知地址、过期的设备/频段链接统一渲染 notfound.html(带顶栏、
    一键回设备列表),不再吐裸文本;/api、/metrics 机器端点仍回 JSON 404;405 语义保留
    —— POST-only 路由显式注册 GET 孪生回 405(「重启接口只认 POST」的既有契约原样通过)。
    兜底按全方法注册 "/" 并先探测:共用端口且 -path=/ 时 CWMP 已占了 "/",自动让位不重复注册
    (注册期冲突曾把服务直接炸掉 —— e2e 抓到,新增两条注册测试钉死)。
  • 动作反馈统一:备注 / 标签保存后带提示条回详情页(?msg=…[&err=1],与删除设备、
    无线保存同一模式),不再静默跳转或裸 http.Error 文本页。
  • 空态与引语统一:告警 / 预设 / 固件页的空态从 hint+手写 margin 换成与概览页同款的
    .empty 卡片;区块引语统一 .page-intro;预设 / 固件表格补「共 %d 条」计数行(对齐告警页)。
  • 破坏性操作确认统一:预设 / 固件页的内联 onsubmit=confirm(...) 改成 data-confirm
    (与设备重启 / 删除同一机制:文案由模板负责转义,设备名带引号也不会把脚本弄坏)。
  • 重启过渡页补品牌条(原来是一张裸页)。
  • 验收脚本的静默隐患修复:verify-s1.sh 的端口被占用时,自起实例 bind 失败、就绪探测却
    被占用者应答,整套验收会静默打到别的服务器上(本轮被登录断言当场抓住:占用者是没开
    鉴权的演示实例,408 项里 407 项「绿」得毫无意义)。现在启动前先查端口,占用即报错退出
    并提示 ACS_TEST_PORT=<别的端口>。

升级

tar xzf lightcat-1.3.0-linux-amd64.tar.gz && cd lightcat-1.3.0-linux-amd64
sudo ./update.sh    # 迁移 #9~#14 自动执行;配置不动,新参数都有默认值

≤v1.2.x 的存量安装直接 sudo ./update.sh 即可(老脚本走 acs-* 兼容资产;数据目录、
服务名、数据库文件名都保持老落点不变,不搬数据)。

新参数速查:-optical-history-days -alert-webhook -alert-rx-low -alert-temp-high
-alert-offline -alert-cooldown -files-dir -tls-cert -tls-key -api-token(详见 README)。

验收

  • go test ./... 全绿(新增 alert / presets / files / download / metrics / firmware /
    optical_history / profile 等约 35 个测试);go test -race ./... 同样全绿
  • scripts/verify-s1.sh 415 / 0(含新增 42~45 标签 / 收光榜 / CSV / 面板一致性四节;
    另 3 项浏览器用例在无 headless Chrome 的机器上合规跳过)
  • scripts/verify-interop.sh 8 / 0:GenieACS 官方 JS 模拟器(独立实现)完整纳管,
    厂商 / 型号 / OUI / 软件版本 / 数据模型根 / 参数条数 / 在线全对
  • scripts/build-release.sh v1.3.0 实跑通过:两个架构 × 两个包名 + SHA256SUMS;
    install.sh / update.sh / uninstall.sh 三个脚本 --dry-run 冒烟通过
  • 容器链:本机 docker build 实跑通过 + 容器端到端冒烟(cpesim 打容器纳管、面板/API 正常);
    K8s manifests 过 kustomize 渲染与字段自查(kubeconform -strict 在 CI 常驻)
  • 已知边界:固件升级链路已由模拟器端到端验证(含设备自拉文件与 TransferComplete 结案),
    但真机固件的 Download 行为各家有差异(Status 语义、重启时机),首次真机升级仍建议
    先用一台可接受变砖风险的测试猫验证