Skip to content

v1.3.0

Choose a tag to compare

@github-actions github-actions released this 11 Oct 02:04
· 31 commits to main since this release

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 语义、重启时机),首次真机升级仍建议
    先用一台可接受变砖风险的测试猫验证