平台技术架构与改造路线图（技术版）

日期：2026-04-05

1. 文档目的

本文档面向研发、实施和架构讨论，目标是统一三件事：

  1. 当前系统的真实技术结构
  2. 核心模块之间的职责和关系
  3. 下一阶段的技术改造优先级与执行路线

2. 系统总体判断

当前仓库是一个以 Go 后端为核心、双 Vue 前端承载后台与前台能力的单仓平台。

它的中心不是单一协议，而是围绕以下业务对象构建：

  • 宽带账号
  • 套餐
  • 订单
  • 在线会话
  • 设备
  • 区域
  • 网关/NAS
  • 微码

TR069、RADIUS、iKuai、VPN、微码前台都在为这个业务闭环服务，而不是各自独立存在。

3. 当前仓库的主结构

3.1 后端

后端目录：

  • gf-server/

后端入口：

  • gf-server/main.go
  • gf-server/internal/cmd/cmd.go
  • gf-server/internal/router/router.go

启动后实际挂载的核心能力包括：

  • HTTP API
  • 定时任务
  • TR069 运行配置检查
  • TR069 维护任务
  • TR069 调度器
  • TR069 自动回读 / 自愈
  • RADIUS 认证服务
  • RADIUS 计费服务

这说明当前后端是一个集中式业务核心，而不是松散组件集合。

3.2 管理端前端

管理端目录：

  • vue-admin/

当前技术栈：

  • Vue 3
  • TypeScript
  • Vite
  • Pinia
  • Element Plus
  • Vitest

管理端主要承担：

  • 宽带账号管理
  • 套餐与订单管理
  • NAS / iKuai 管理
  • TR069 设备与任务管理
  • 区域和运营视角管理

3.3 轻前台

前台目录：

  • vue-front/

当前技术栈：

  • Vue 3
  • Vite
  • html5-qrcode
  • qrcode
  • tesseract.js

前台主要承担：

  • 微码扫码识别
  • 装维绑定设备
  • 状态查询
  • 套餐支付
  • 续费结果查询

4. 当前核心架构分层

4.1 逻辑分层

后端当前基本遵循 GoFrame 的典型结构：

  • API：定义请求与响应结构
  • Controller：承接路由入口
  • Service：定义服务接口
  • Logic：承接业务实现
  • DAO / Model：数据访问与对象模型
  • Utility：承接协议、调度、辅助能力

这套结构整体是可维护的，问题不在于层次混乱，而在于某些高复杂度域已经开始跨层扩散。

4.2 主要业务域

A. 计费认证域

关键职责：

  • 用户认证
  • 计费会话建立与更新
  • 配额扣减
  • 在线会话管理
  • 强制下线

关键对象：

  • sys_net_user
  • sys_product
  • sys_order_data
  • sys_session_data
  • sys_user_online

这一域已经具备正式业务系统底座特征。

B. NAS / iKuai 运维域

关键职责：

  • NAS 设备信息维护
  • iKuai 参数和接口管理
  • PPP 会话查询与踢线
  • VPN 边界接入

这一域与现场网络控制直接相关，是实际交付的重要抓手。

C. TR069 设备纳管域

关键职责：

  • CWMP Inform 接收
  • 设备入库与更新
  • 参数快照与事件记录
  • 任务调度与执行
  • 写后回读与状态校验
  • 自动回读、自愈与闭环追踪

这是当前复杂度最高、价值最高的模块。

D. 微码与轻前台域

关键职责：

  • 扫码识别设备/微码
  • 装维绑定流程
  • 轻量状态查询
  • 用户续费与支付

这是连接设备交付与用户消费行为的入口。

5. 当前真实数据流

5.1 业务主线

平台当前真正的主业务链可以概括为：

  1. 建立区域、公寓、套餐、账号
  2. 用户通过认证与计费进入在线状态
  3. 设备通过 TR069 或装维绑定纳入平台
  4. 平台对设备执行初始化、业务下发与回读校验
  5. 用户在前台查询、支付、续费
  6. 平台根据套餐、状态、设备与会话做持续运维控制

5.2 TR069 主链路

当前 TR069 至少存在四条核心子链路：

  1. Inform 入库链路
  2. 模板任务下发链路
  3. 运行态回读校验链路
  4. 自动回读 / 自愈链路

目前这四条链路基本都已经成型，但仍在持续收口统一语义。

5.3 前台绑定与续费链路

前台链路可以概括为：

  1. 扫码获取微码信息
  2. 判断是否已绑定
  3. 未绑定则进入装维绑定页
  4. 已绑定则进入信息页
  5. 如有需要进入套餐购买与支付流程

这条链路已经具备真实业务含义，而不是单纯的展示页面。

6. 当前架构的优点

6.1 主业务方向清晰

当前架构不是为了展示技术能力而堆功能，主轴始终围绕公寓宽带业务。

6.2 后端集中式核心适合当前阶段

对当前项目阶段而言，集中式单体后端比过早拆分微服务更合适。当前问题主要不是“服务太大”，而是“高复杂度模块要继续做清晰边界收口”。

6.3 TR069 的方向基本正确

当前 TR069 已经从简单模板下发转向：

  • 能力识别
  • 参数映射
  • 写后回读
  • 多品牌兼容
  • 闭环诊断

这条路线方向是对的。

6.4 前后端已经形成一定的共享语义意识

从 TR069 相关 shared helper 和测试痕迹看，前端已经开始减少页面内散乱分支，转向统一语义定义。这是后续稳定化的正方向。

7. 当前主要技术问题

7.1 TR069 域复杂度高且跨层影响大

当前 TR069 相关逻辑横跨：

  • Service
  • Utility
  • Vendor Client
  • 调度器
  • MySQL updater
  • 前端设备页 / 任务页
  • 报告与 SOP 文档

这会带来一个典型风险：

一个状态语义改动，可能同时影响后端调度、落库、前端展示和运维判断。

7.2 统一正式执行链路仍需继续收口

当前已经明显在向统一执行框架推进，但仍不能认为已经完全收口。尤其在以下方面仍应坚持继续统一：

  • VendorConfig 解析
  • 任务执行分类
  • timeout / retry / recovery 语义
  • 读任务、写任务、browse、refresh、factory reset 的统一边界

7.3 业务对象虽全，但主流程尚未完全产品化

当前账号、套餐、订单、设备对象都在，但从架构上看，真正的一体化业务编排还没有完全成为第一公民。

还需要进一步明确：

  • 新装流程入口
  • 欠费策略入口
  • 恢复策略入口
  • 客服/装维/后台三类角色的主操作流

7.4 安全与环境治理明显落后

当前开发推进很快，但安全与运维治理还没同步到位，主要体现在：

  • 配置脱敏不足
  • 多环境分层不足
  • 发布规范不足
  • 运行态监控不足

这部分如果不尽快补，后面会成为系统性隐患。

8. 测试与质量现状判断

从仓库内容可以确认，当前已经存在比较多的测试覆盖，尤其集中在两块：

  • RADIUS 认证与计费处理
  • TR069 渲染、执行、兼容、状态分类与集成链路

这说明：

  • 项目并不是完全靠手工试出来的
  • 核心高风险域已经开始有回归保护意识

但仍要看到两个现实：

  1. 高复杂度域越复杂，测试维护成本也越高
  2. 业务闭环与环境治理部分的自动化保障仍偏弱

因此当前质量状态可定义为：

高风险核心链路已有一定测试保护，但整个平台还没形成完整的工程质量体系。

9. 建议的目标架构原则

下一阶段不建议做“大重构”，建议坚持增量式重构与收口，遵循以下原则：

原则 1：继续保持单体主架构

当前阶段不建议拆微服务。先把边界清楚、状态统一、治理能力补齐，比拆服务更重要。

原则 2：TR069 继续围绕“兼容层 + 业务语义层 + 执行层”收口

目标不是继续在业务代码里堆厂商 if/else，而是把差异更多沉淀到：

  • 兼容指纹
  • 参数映射
  • 能力探测
  • 写后校验
  • 模板版本管理

原则 3：把业务编排提升为平台一等公民

下一阶段应减少“功能点分散存在”，转而明确业务主流程对象与状态机。

原则 4：尽快补运行态治理能力

配置、监控、告警、发布、备份恢复必须尽快进入体系化建设。

10. 分阶段改造路线图

P0：TR069 工程化加固

目标：把 TR069 从“已可用”继续推进为“可稳定规模使用”。

重点事项：

  1. 继续统一真实执行链路
  2. 严格清理历史过渡语义和分散 fallback
  3. 强化任务重试、恢复、长任务续租与超时治理
  4. 统一事件、错误分类、回写与前端展示语义
  5. 持续把多品牌差异下沉到兼容层与映射层

完成标志：

  • 同类任务在不同执行链路上的状态解释一致
  • 设备页、任务页、日志页口径一致
  • 新品牌接入不再依赖堆业务特判

P1：业务闭环产品化

目标：把平台从“强技术系统”推进为“强业务产品”。

重点事项：

  1. 新装自动绑定与自动初始化收口
  2. 欠费限制与恢复策略落地
  3. 账号、套餐、订单、设备的一致性编排
  4. 客服与装维主操作流设计

完成标志：

  • 新装、欠费、续费、恢复形成清晰主流程
  • 客服和装维操作不再需要跨多个模块拼流程

P1：安全与运维治理

目标：让系统适合长期线上运行。

重点事项：

  1. 配置与密钥治理
  2. 多环境配置隔离
  3. 发布与回滚规范
  4. 监控、告警与日志汇总
  5. 备份恢复标准

完成标志：

  • 生产环境部署、回滚、排障有标准流程
  • 关键故障可以被及时发现并快速定位

P2：交付复制标准化

目标：把成功经验沉淀成标准做法。

重点事项：

  1. 品牌接入 SOP
  2. 网络诊断清单
  3. 交付检查单
  4. 验收标准文档

完成标志：

  • 不依赖个别熟悉系统的人也能完成标准交付

11. 推荐的研发组织视角

如果从研发协作角度看，建议后续工作按四条线并行但分优先级推进：

  1. 平台核心线：RADIUS、账号、套餐、订单、会话
  2. 设备纳管线：TR069、兼容、模板、校验、自愈
  3. 运营交付线：iKuai、VPN、现场诊断、交付 SOP
  4. 产品闭环线：微码、绑定、支付、续费、恢复

这样可以避免所有问题都堆在单一模块里讨论。

12. 最终技术结论

当前系统的技术底座总体是成立的。

最重要的结论不是“要不要推翻重做”，而是：

  • 不需要推翻
  • 也不应无节制继续堆功能
  • 最需要的是围绕现有主能力做边界收口、语义统一和工程治理

对研发团队来说，下一阶段的关键不是证明系统能做什么，而是把它打磨成：

  • 可稳定维护
  • 可一致解释
  • 可扩展兼容
  • 可支持业务规模增长

如果路线保持现在这个方向，平台是有条件从“复杂但可用的系统”继续演进成“稳定可复制的平台型产品”的。

作者：wuge  创建时间：2026-04-05 16:32
最后编辑：wuge  更新时间：2026-04-05 16:32