Repository navigation
v1.3.0
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)
- bash 3.2 会把紧跟
$VAR的全角标点首字节并进变量名(echo "$PORT,"→ unbound variable),
脚本统一改${VAR}写法; - 项目更名 acs → lightcat 后
verify_s1.py仍找旧名:第 26 节凭据断言必失败,
浏览器 DOM / 双端口 / 自动刷新 / 离线判定四节被静默跳过(skip 不计失败所以一直没暴露); - 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-permsinitContainer 兜底。
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.sh415 / 0(含新增 42~45 标签 / 收光榜 / CSV / 面板一致性四节;
另 3 项浏览器用例在无 headless Chrome 的机器上合规跳过)scripts/verify-interop.sh8 / 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 语义、重启时机),首次真机升级仍建议
先用一台可接受变砖风险的测试猫验证