2025年12月29日

内容截止日: 2026年01月04日

本周工作计划与执行完成进度

中心服务平台 - 功能完善

• 进度: 🔘 未开始 -> 🟡 进行中 -> ⚠️ 部分完成 -> ✅ 已完成 -> 📌 已自测
  • 以往已完成的工作不再重复，详情请查看上周及上月报告
  • 〔工作量〕es-center-server-services 35 次 · 代码 +1.7k/-0.6k ｜ es-center-server-web-app 6 次 ｜ es-center-server-install-app 26 次 · 代码 +0.8k/-0.6k ｜ es-ext-doc-website 5 次 ｜ es-center-server-build 4 次
  • 〔方法论〕Nacos 帐号密钥集中化管理 ｜ EMQX API Key 安装程序自动生成 ｜ 启动主动检测设备在线替代停用的状态记录服务 ｜ 敏感凭据服务端注入避免客户端泄露
  • 12-29 ~ 01-04: 重启后的设备在线状态
    • ✅ 补齐设备服务重启后的在线状态，定时清理旧缓存 〔es-center-server-services〕
      • 设计 此前比较两种方案：MQTT 是设备与服务器交换消息的通道，可向所有设备发 ping，根据响应判断在线；它复用现有通道、免额外认证、兼容性强，部署维护成本低，原方案优先采用。EMQX 负责管理设备的 MQTT 消息连接。另一方案是调用 EMQX REST API 查询连接状态，需要预配 API 权限、生成密钥并同步到中心服务器，部署运维更复杂。要解决的是状态记录服务一度停用时，device-service 升级、宕机或重启漏收下线通知的问题。
      • 实施 本周落地的是 EMQX API 方案：服务启动时查询实时在线客户端列表，并在每日凌晨 2 点再次执行同步。先清空 Redis 中原有 MQTT 在线状态缓存，再写入查询结果，降低缓存存储压力，维护设备在线状态。
      • 重构 调整取数、清空与写入的顺序，在清空后重新查询再写入。清理缓存改用分批扫描，避免一次遍历大量键阻塞 Redis；同步整理构造注入、常量、引用、注释和空行。
    • ✅ 安装和升级时自动生成 EMQX API 凭据 〔es-center-server-install-app〕
      • 实施 生成随机的 EMQX API Key 账号与密码，写入 .env，并生成对应的 EMQX API KEY 配置文件。随后统一凭据名称为 API Key/API Secret，同步环境模板、命令行参数与配置生成逻辑。
      • 重构 将 TLS 与 API 凭据变量放回各自的配置区，删除重复、位置错误的 SSL 配置块。
    • ✅ 设备服务读取环境凭据，准备调用 EMQX 查询接口 〔es-center-server-services〕
      • 实施 device-service 从 .env 读取认证凭据，配置 EMQX 专用 HTTP 客户端，并保存接口响应样本和调试命令，用于核对在线状态字段。
      • 重构 为主服务和设备服务配置统一的 HTTP 客户端，采用虚拟线程处理请求；搜索服务 Meilisearch 的地址和密钥命名一并整理，移除其重复客户端配置。
  • 12-29 ~ 01-04: 本地 Nacos 与多服务器部署
    • ✅ 为印度客户准备本地 Nacos 部署，安装与升级程序接入该服务 〔es-center-server-install-app〕
      • 设计 Nacos 用来集中保存配置。印度客户这样的独立部署版本默认连接本地服务器，安装与升级包预先设置连接参数。这是轻量化跨境分布式第二阶段改造的部署安排；公司非主节点若需连接主节点 Nacos，可修改 .env 的 NACOS 参数，区分运行环境。
      • 实施 将 Nacos 服务纳入首次安装、更新和升级流程，补齐容器配置、启动步骤、镜像、端口、持久化目录和管理员参数，并让环境变量驱动这些配置。
      • 实施 安装时只生成一次随机 Nacos 密码，同时写入管理员和服务访问配置，避免两套凭据不一致。
      • 实施 将 Nacos 地址及访问凭据传给主服务和设备服务容器，并修正示例云节点内网地址。安装与升级程序具备自动安装和升级 Nacos 的能力。
      • 重构 缩短基础服务的启动等待时间，保留主服务较长的启动窗口；移除主服务、设备服务和 ActiveMQ 的固定容器内存上限与预留，主服务和设备服务改用 JVM 百分比参数结合宿主环境约束内存。
    • ✅ 调整服务端 Nacos 默认地址，补充开发环境配置入口 〔es-center-server-services〕
      • 实施 主服务与设备服务的默认 Nacos 地址改用容器服务名；新增 .dev.env 并接入编辑器启动配置，集中保存开发环境的 Nacos、Meilisearch 与 EMQX 地址和凭据。
      • 重构 默认配置改读环境变量，移除两服务开发配置里的重复覆盖和失效注释，清理环境文件末尾空行。
    • ✅ 持续更新多服务器的部署脚本与发布包引用 〔es-center-server-install-app〕
      • 实施 迭代 zxs、zxs-hs、zxs-cs、zxs-ca 的部署脚本、Docker Compose 与环境变量；同步主服务、设备服务和 Web 镜像，以及安装包、上传入口和运维说明。
      • 实施 在发布辅助流程中加入 rnacos 镜像复制，随新组件一起交付；补充 tmux 升级入口，让较长的升级过程可以脱离终端继续运行。
      • 实施 1 月 4 日调整发布组合：保留两个 GE 上传目标、停用两个 CN 目标，随后改选 CA 并停用 HS；升级基础镜像、切回 CN 产物后，自动上传目标再由 CA 改为 CS 测试环境。相应部署与上传引用同步更新。
      • 设计 创建版本分支 2.0.0-cn-1-20260104，并与服务端、Web 前端同步。
  • 12-30: App 帐号注销
    • ✅ 注销帐号时清理个人空间及关联数据 〔es-center-server-services〕
      • 实施 新增用户注销接口和消息处理流程，查询用户全部租户并筛选个人空间，在事务中清理自身绑定的设备、分享给其他用户的设备及源设备、其他用户分享给该用户的设备、第三方帐号、手机号绑定、邮箱绑定、用户与租户绑定、用户专属租户和用户账户。
      • 重构 补齐分享源设备的清理，统一注销接口与队列命名；将用户控制器从通用层迁至零售层，并整理相关控制器的命名与请求入口。同步删除未用引用、修正注释错字。
  • 12-31: 设备列表通知
    • ✅ 通知用户刷新设备列表时，优先使用手机号或邮箱识别账号 〔es-center-server-services〕
      • 实施 在原有解绑和强制绑定通知上调整用户标识：查询用户名与手机号、邮箱的绑定关系，手机号优先、邮箱次之，两者都没有时保留原账号；随后整理通知处理的格式。
  • 12-31: 2.0.0 用户手册
    • ✅ 新建并多轮改写 2.0.0 用户手册，补充版本变更日志 〔es-ext-doc-website〕
      • 设计 首版列出后端服务系统的核心服务模块、业务模块和通用组件，以及 Web 应用的 UI 组件系统与框架技术；完整清单还覆盖 Agent、WASM 加密、安装部署和整体架构。
      • 设计 将技术清单改写为面向用户的 13 类产品能力：账号体系与认证授权、实时视频、设备管理、设备列表管理、远程控制、报表、基础数据管理、配置管理、运维管理、系统管理、安全与权限、API 与集成、前端技术特性。
      • 设计 随后再次改写手册，按 16 个领域展开：账号体系与认证授权、直播、远程控制、设备管理、报表管理、配置管理、运维管理、历史数据管理、订单管理、基础数据管理、消息与事件处理、系统基础设施、前端架构、安装部署、版本控制与协作、统计数据。多轮优化结构、表述与功能描述，同步补充代码规模和技术栈统计；手册标题统一为 2.0.0。
      • 设计 扩充 2.0.0 变更日志，记录功能优化和问题修复。2.0.0-20251231 发布记录涵盖启动与定时在线同步、随机 EMQX API Key、App 注销、重复设备校验、绑定通知、SSL、协议页面及直播兼容修复。
  • 12-30 ~ 01-04: 工程规则与依赖整理
    • ✅ 整理后端工程规则及过程材料，升级基础依赖 〔es-center-server-services〕
      • 设计 清理已经落地或失效的设备号校验、Nacos 集成、Spring Boot 升级评估和 wiki 过程材料；生成用户注销与设备在线同步的仓库说明，修订 Qoder 代码风格规则。
      • 实施 Spring Boot 从 3.5.8 升至 3.5.9，HTTP 客户端配置适配新版本接口；commons-io 从 2.18.0 升至 2.21.0、dynamic-datasource 从 4.3.1 升至 4.5.0、jasypt 从 3.0.5 升至 4.0.3，并同步工程指引。
      • 设计 GIT-MANAGE.md 记录统一的 Git 管理流程；分支操作记录先更新为 2.0.0-cn-1-20260106，随后校正为实际的 2.0.0-cn-1-20260104。
      • 重构 统一基础数据 Mapper 接口缩进。
    • ✅ 补充前端项目指引并整理组件与开发环境 〔es-center-server-web-app〕
      • 设计 Qoder 生成仓库 wiki，说明 API 集成、UI 组件、设备、远程控制、运维、报表、配置管理、路由与状态管理；新增 AGENTS.md 介绍技术栈，同步 GIT-MANAGE.md 中的 2.0.0-cn-1-20260104 分支及管理记录。
      • 实施 开发环境由 Cs 切回 bodycamera，停用本地 MAIN_SERVICE 配置；升级 @react-three/fiber 9.5、plyr-react 6.0、react-day-picker 9.13、recharts 3.6 与 three 依赖，并调整构建配置。
      • 实施 为按钮的样式和尺寸补默认值及数据属性，调整对话框、选择组件，并补充编辑器批量格式化扩展。
  • 01-04: 构建与镜像分发
    • ✅ 统一构建基座与发布路径，清理未使用的 Docker 资源 〔es-center-server-build〕
      • 实施 将发布物从 12-19 推进到 01-05，同步构建入口、各目标上传路径、远端加载和二次转发命令；将一个目标的上传组合从主服务与设备服务双镜像收窄为仅设备服务镜像。
      • 实施 固定 Temurin JDK/JRE 21.0.9_10，升级 Nginx 1.29.4 与 rnacos 0.7.10，同步构建、初始化拉取与导出；在开发发布辅助末尾增加 Docker 未使用资源清理命令。
    • ✅ 补充跨服务器传输操作说明并更新基础镜像 〔es-center-server-install-app〕
      • 设计 记录远端构建机与目标服务器之间的传输、SSH 操作及 Nacos 验证命令，说明一次发布中需要人工接力的步骤。
      • 实施 将 Nginx 和 rnacos 的镜像版本与本轮构建同步。
  • 下列回顾保留原页已并入的早期工作。对应 Git 工作发生在本周窗口之前，目标周页在本批范围外，因此仍留原位；回顾中的日期表示本页原有的汇总段，不计为本周新完成，提交工作量只统计 12 月 29 日至 1 月 4 日。
  • 12-29 ~ 12-30: 跨境 App MQTT 帐号回顾
    • ✅ 公共 App 帐号池统一管理，配置同步到各服务器 〔es-center-server-services〕
      • 设计 帐号密码池容量上限 6 组，既有方案记载每周新增一组、每月最多新增一组。池满 6 组时，将第 6 组旧帐号移至首位并更新密码；尽量避免修改已有帐号密码，防止运行中的 App 认证失败、无法连接 EMQX。
      • 实施 此前已通过 Nacos 实现所有服务器共用的 App MQTT 帐号与密码池管理；各节点取最新配置，同步写入 EMQX 使用的 Redis，包含帐号、密码与权限。新增或变更后各节点及时更新，保持服务一致。
      • 实施 手机或邮箱登录后的 /logind 接口返回池中第一组有效凭证，避免在客户端硬编码固定帐号密码。对应帐号同步及登录返回的 Git 工作在 12 月 24 日完成。
  • 12-29 ~ 12-31: 绑定与接口安全回顾
    • ✅ 设备绑定加入授权码校验 〔es-center-server-services〕
      • 设计 由设备生成授权码，用户用手机 App 采集并提交，服务端按内部加密逻辑校验；失败返回错误信息。
      • 实施 校验成功后按三分支处理：无历史绑定记录直接绑定；存在相同授权码时，用户名一致返回“重复绑定”，不一致返回“设备已绑定至用户: xxx”；存在不同授权码时，用户名一致更新授权码，不一致则更新授权码、解绑原用户并绑定新用户。
    • ✅ API 操作留日志，Janus 管理密钥由服务端注入 〔es-center-server-services〕
      • 实施 为手机 App 调用服务端的关键 API 记录日志，让重要操作可追溯、责任可追究。
      • 实施 Janus 是处理实时音视频的服务。调用 Janus Admin API 的 admin_secret 由服务器转发请求时动态添加，再发送至对应分布式节点，避免敏感信息硬编码到客户端；Web 前端与设备端查询房间人数时使用该接口。
    • ✅ 解绑和强制绑定通知相关用户刷新设备列表 〔es-center-server-services〕
      • 实施 按 App 自定义协议通知所有相关用户刷新设备列表，及时移除已解绑设备；本周继续调整通知账号的识别方式，见上面的设备列表通知段。
  • 12-29 ~ 12-31: 8883 证书与重复设备校验回顾
    • ✅ EMQX 8883 端口绑定证书 〔es-center-server-install-app〕
      • 实施 为 EMQX 服务 8883 端口配置证书绑定，优先考虑 Let’s Encrypt 免费证书方案；本周只继续整理 TLS 配置变量，见上面的 API 凭据段。
    • ✅ 跨租户限制重复设备、采集服务器与采集盒 〔es-center-server-services〕
      • 实施 新增、修改或通过 Excel 导入设备、采集服务器与采集盒时，禁止添加其他租户已存在的重复项。
  • 12-29 ~ 12-31: Web 省电省流与直播回顾
    • ✅ Web 完成省电省流改造并验证 〔es-center-server-web-app〕
      • 实施 梳理并完成设备与手机端省电省流方案需要的 Web 前端修改。
      • 测试 部署至 zxs、zxs-hs、zxs-cs、zxs-ca 四台服务器，测试通过。
    • ✅ Web ping 减少冗余判断并调整发送频率 〔es-center-server-web-app〕
      • 协作 与孙工讨论 Web 端 ping 机制，也就是定时探测连接是否仍然可用。
      • 实施 优化冗余判断、调整发送频率，提升稳定性与响应效率。
      • 测试 部署四台服务器测试通过，服务器仍为 zxs、zxs-hs、zxs-cs、zxs-ca。
    • ✅ SFU 通知设备更快推送关键帧 〔es-center-server-web-app〕
      • 实施 SFU 是服务器转发音视频的模式。调整通知设备快速推送关键帧的代码逻辑，让小幅画面更快出图。
  • 12-23 ~ 12-24: 巴西客户嵌入式 Web 回顾
    • 🟡 在 802.1X 修复中整理交接代码，继续理解需求 〔es-bodycam-web-ui-1〕
      • 设计 深入理解 802.1X 需求；它用于连接需要认证的网络。龚工交接的代码可读性较差，大量写法不符合 React 规范，维护成本较高。
      • 重构 在修复 BUG 时整理代码结构，提升可维护性，方便后续修改与排查。相关 Git 改动发生在 12 月 23 日至 24 日，保留为此前进展，状态仍为进行中。

其它工作

• 目标: 记录日常耗时的杂项工作、协作事项，以及必要的沟通、讨论等隐性事务。
• 进度: 🔘 未开始 -> 🟡 进行中 -> ⚠️ 部分完成 -> ✅ 已完成 -> 📌 已自测
  • 29 日
    • ✅ 用户协议及隐私协议的 Markdown 排版格式改进
    • ✅ 制作最新的安装及升级程序，部署到 zxs-cs 及 zxs-ca 服务器，验证 EMQX 配置 API KEY 的正确性
  • 30 日
    • ✅ 优化设备在线状态同步逻辑，减少性能消耗
    • ✅ 制作最新的安装与升级程序，部署至 zxs-cs 和 zxs-ca 服务器；针对”假在线”问题进行多轮测试——手动停止 device-service 服务后再断开设备连接，随后重启服务，验证此前因服务中断而离线的设备能否被准确自动维护为离线状态，确保设备上下线状态同步无误
    • ✅ 手机 App 帐号注销接口需清理的数据（账号注销时均需按流程逐一清除，确保信息彻底解绑并删除）:
      • 自身绑定的设备
      • 已分享给其他用户的设备
      • 其他用户分享给该用户的设备
      • 手机号与用户之间的绑定关系
      • 邮箱与用户之间的绑定关系
      • 用户与租户之间的绑定关系
      • 用户专属租户
      • 用户账户本身
    • ✅ 制作最新的安装与升级程序，部署至 zxs 服务器，提供给 App 联调使用
  • 31 日
    • ✅ 验证从家中带到公司的花生棒是否可用: 该设备为十年前购买，若已损坏则需重新购置；因需开发对接苹果回调的接口，必须通过公网访问穿透连通内网中的开发电脑
    • ✅ 使用 zxs-cs 和 zxs-ca 服务器对集成了 Nacos 的安装程序及升级程序进行测试
  • 01 日
    • ✅ 使用 zxs 和 zxs-hs 服务器更新为最新版本