物联网平台二次开发实战指南：从选型到协议扩展与维护

最近几个月“二开”这个词在我朋友圈里出现的频率明显高了不少。从建站CMS二开到商城系统二开再到机器狗控制、视觉软件二开本质上大家都在做同一件事找一个成熟底座把省下来的时间和成本花在自己的业务逻辑上。放到物联网领域这句话就变成了——找一个适合二开的物联网平台。我先后帮几个团队做过物联网平台选型和落地也基于开源平台做过私有协议适配、多租户改造、可视化大屏二开。这些年最大的体会是很多项目不是死在需求复杂而是死在底座选错了。选了一个封闭的、不好改的、改完没法升级的平台后期全是痛苦。这篇就把我踩过的坑和攒下来的方法论摊开讲一讲从判断标准到平台盘点再到一条实战二开路径以及最容易翻车的几个环节希望对你选型和动手有实际帮助。1. 先想清楚你是哪种“二开”这决定了平台选型我见过太多人一上来就问“哪个平台适合二开”但其实“二开”这个词的粒度差得很远。有人说的二开是配配菜单、改改Logo有人说的二开是要接入一个很偏门的私有协议还有人说的二开是打算把规则引擎、数据存储、前端展示全都换一遍。这三种需求对平台的要求完全不同。1.1 三种二开深度对应三种选型思路我把物联网平台的二开粗略分成三个层级大家可以自己对号入座二开深度典型工作内容对平台的要求配置级创建产品、配置物模型、搭仪表板、设置告警规则文档齐全、操作界面友好、内置协议够用模块级新增一种通信协议、定制规则处理、扩展OpenAPI、改造前端页面模块解耦清晰、有扩展点和插件机制、社区有参考案例内核级改消息总线、换时序数据库、重新设计多租户权限、深度定制设备管理流程开源协议宽松、架构文档完整、核心技术栈自己团队能驾驭如果你只是配置级二开那商业SaaS平台甚至直接用阿里云物联网平台这类托管服务就够了买了就能用不用自己养一套系统。但如果你做到模块级尤其是要接入私有协议、要做私有化部署、要对接客户自己的业务中台那就必须选一个“真能改得动”的开源底座。至于内核级说实话那已经不是选型问题了是研发能力问题——选什么平台都得评估一下团队能不能把源码吃透。我自己经手的项目大多数落在模块级。所以这篇文章的重心也会放在“模块级二开”上平台本身能跑但你需要往里添东西、改东西。1.2 五个硬指标帮你筛掉90%的“伪二开平台”判断一个物联网平台适不适合二开我建议用五个指标去打分不要只看Star数或者宣传文档。第一个是开源许可证。这点最容易忽略也最致命。Apache License 2.0、MIT这类宽松协议商用、私有化、改代码再闭源交付基本没有问题只要保留版权声明。但遇到GPL、AGPL要格外小心AGPL对网络服务都有传染性你基于它做的二开可能也被要求开源集成商接了这类项目会非常被动。很多平台主仓库写着“开源”但license文件里藏着猫腻一定要自己去翻源码仓库里的LICENSE文件确认。第二个是模块边界是否清晰。适合二开的平台源码结构一般非常干净设备接入、协议解析、消息路由、规则处理、数据存储、API层是分开的。你加一个协议包不需要动消息总线你改一条规则不需要碰设备接入模块。反过来如果源码一堆模块互相耦合改一个地方跳动一片那不是你技术不行是平台就不该这么搞。第三个是扩展点是否暴露出来。好的平台不会让你“哪个文件都能改”而是让你“在指定位置插进去”。比如协议层有独立的接口、规则引擎支持自定义节点、API层可以挂载过滤器。扩展点是平台自己设计出来的“合法破坏口”用它们做二开后期升级才不会被源码冲突绊死。第四个是技术栈是否匹配团队。Java技术栈的平台Java团队改起来顺手Go平台对部署运维友好C#平台则适合.NET背景的团队。道理都懂但真到二开阶段面对的是一个几万甚至几十万行的项目不是网上抄一段代码就能解决的。团队里至少得有人能读懂核心模块源码否则所谓二开就是改改配置文件。第五个是社区活跃度和文档。注意这里说的文档不是官方API参考而是有没有人写过“二次开发教程”“自定义协议示例”“踩坑记录”。社区活跃度能通过GitHub的Issue讨论、博文数量、Release频率看出来。选平台时我会特意去搜一下“某某平台 二开教程”搜不到东西的心里就得打个问号。另外还有一个看不见但极其重要的点升级路径。你是打算把二开结果长期维护下去还是交付完就撒手如果长期维护就要考虑平台官方发新版时你的二开代码怎么跟上去。模块化做得好的平台二开只集中在某几个扩展点升级时合并成本很低而那种被删改得乱七八糟的源码树一次升级就是一次灾难。这个问题后面有专门一节讲这里先记住结论选平台时要像买房子一样看“承重墙”和“隔断墙”——承重墙不能动隔断墙随便拆。平台设计得好它自己就会告诉你哪些是承重墙。2. 五款主流平台实测感受JetLinks、ThingsBoard、ThingsPanel、IoTSharp与Node-RED前面讲了一堆标准现在落到具体平台上。我实际跑过、改过的开源物联网平台里以下这几个在不同场景下都算“适合二开”但适合的方向各有不同。2.1 JetLinksJava技术栈下的协议扩展要点最清晰JetLinks是我个人用得比较多的一款印象最深的是它的解耦设计。它把设备接入拆成网络组件、协议支持、物模型、规则引擎几层一个自定义设备协议在平台里被当作一个“协议支持包”注入进去而不是把代码散落到消息处理的各种角落。也就是说你想接入一款走私有TCP封包格式的设备不用去翻设备管理的核心代码只需要实现好协议解析和编码平台就能通过这个协议包把设备数据变成统一的物模型数据。这一点对二开太重要了。我在给一个工厂做设备数据采集项目时要接几十台老旧PLC设备协议是非标的二进制封包数据还要带CRC校验。当时就是给JetLinks写了一个自定义协议支持包开发、联调、上线全程没动平台核心源码。后来官方升级版本我这边合代码基本没有冲突。JetLinks的技术栈是Java为主Spring Boot 2.x WebFlux Reactor PostgreSQL Redis ElasticSearch前端是Vue。这套组合对Java团队很友好但对没接触过响应式编程的人来说上手有门槛——WebFlux和传统的Spring MVC写法差别不小刚上手时很容易在背压、异步链路这些概念里绕晕。别怕核心二开场景首先用同步跑通再逐步深入。2.2 ThingsBoard规则引擎强大但协议接入门槛偏高ThingsBoard在国际上很知名GitHub Star数很高社区也非常活跃。它的强项是规则引擎和可视化仪表板。规则引擎用事件驱动的方式处理设备上报的数据过滤器、变换器、动作节点可以在界面上拖出来串成一条规则链。比如说“设备温度大于80度且连续三次上报就发邮件告警”这类联动逻辑用ThingsBoard的规则引擎改起来比直接写代码要快得多。但ThingsBoard的设备协议接入层是另一个画风。它有一套Transport层的机制支持MQTT、CoAP、LwM2M、HTTP等但如果你要自定义一个私有协议需要自己实现对应Transport端处理器这部分的抽象层级较深源码看起来比JetLinks要费劲一些。所以我的感受是如果项目重点是设备接入、私有协议、国产化适配ThingsBoard不一定是最佳起点如果项目重点是数据链路复杂、页面展示要求高、需要做SaaS级多租户那ThingsBoard值得重点考虑。还有一点ThingsBoard的部署相对偏重它依赖Kafka、Cassandra或者PostgreSQL、Redis这些组件生产环境建议用微服务架构或者至少拆开部署。它对硬件资源的要求也比轻量平台高一个量级小项目用起来会觉得有点“大炮打蚊子”。2.3 ThingsPanel与IoTSharp轻量级二开的两个备选ThingsPanel是国内团队维护的物联网平台后端Go、前端Vue主打轻量化和插件化。它对TDengine时序数据库做了深度集成设备接入走MQTT为主支持多租户。Go技术栈的特点是部署简单、资源占用低一台2核4G的云主机就能跑起来适合边缘服务器、本地化机房的场景。插件机制也做得比较灵活协议接入、数据解析可以通过插件扩展。但它的生态和社区规模比JetLinks、ThingsBoard小一些遇到冷门问题不一定能搜到现成答案。IoTSharp则是.NET/C#技术栈的平台如果你团队是微软系出身更愿意用C#写后端IoTSharp会是比较顺手的底座。它支持MQTT、CoAP等多种协议时序存储可以对接InfluxDB、TimescaleDB等架构上也是前后端分离。老实说它在迭代节奏和社区活跃度上不如前两者但对于特定团队来说“自己读得懂”比什么都重要。技术栈不匹配的平台再强你也改不动。2.4 Node-RED不是平台但几乎是二开标配的边缘层很多人把Node-RED也归到物联网平台里严格说它更像个流编排引擎但它确实是二开场景里非常常见的组件。我很多项目里Node-RED被放在边缘网关这一层设备数据先到Node-RED在里面做协议转换、数据清洗、本地联动控制再转发到JetLinks这样的主平台。这样做的好处是边缘侧的业务逻辑可以快速调整不一定要经过平台完整的发布流程。Node-RED基于Node.js界面是拖拽连线的业务人员也能看懂一部分。它最大的价值是“快”客户说“温度超过阈值就本地关一下阀门”在Node-RED里拖几根线就实现不用改平台。但它的问题也很明显节点一多流程一复杂整张图画得跟蜘蛛网一样维护起来头疼。所以我的习惯是Node-RED只放轻量逻辑重逻辑还是放到主平台规则引擎里去。2.5 厂商云平台与开源平台怎么选这一节要专门回应很多人搜“阿里云物联网平台Android SDK二开”这类需求。厂商云平台确实很好用设备接入、物模型、规则引擎、数据流转都是现成的还配套了各端的SDK比如Android、iOS、嵌入式都有端侧二开很方便。我见过不少团队用阿里云物联网平台做车联网、做智能家居App开发速度是真的快。但厂商云平台的“二开边界”非常清楚你只能在平台给的物模型、规则、API范围里玩平台核心是黑盒。你要私有协议栈人家不一定支持你要把数据导到自己指定的机房里人家不一定放行你要做私有化交付给某个对数据安全极其敏感的客户基本谈不了。所以我的判断很简单业务主要是云端快速上线、不涉及强定制用厂商云平台性价比最高业务需要私有化部署、跨云/本地化、接入特殊协议、深度集成客户业务系统就选开源平台做二开。两条路不是对立关系有些团队甚至会做混合架构边缘侧用开源平台二开核心数据用厂商云平台的流式计算托管服务。关键是别在选型阶段把后路堵死。3. 实战基于JetLinks扩展一个自定义设备协议完成二开闭环前面聊了选型现在动手看一条完整路径。我用JetLinks做例子不是因为别的平台不行而是它的模块边界对二开最友好适合拿来做演示。核心思路是一样的换到ThingsBoard或其他平台也只是API不同。3.1 先把开发环境和源码结构跑明白第一步是从官网或GitHub把代码拉下来。JetLinks包含后端geek-bin和前端jetlinks-ui-antd两个主要仓库另外还有单独的协议代码仓库。本地开发时我习惯用Docker Compose把依赖跑起来PostgreSQL存业务数据Redis做缓存和实时状态ElasticSearch做日志和检索。启动依赖后我强烈建议先把Demo跑通再把代码导进IDE。不用着急改任何东西先用默认配置启动后端用管理端创建一个产品、添加一个设备然后用MQTT客户端模拟这个设备上报一次属性。看到数据能在设备列表和仪表板上正常显示说明环境链路是通的后面二开才有了可靠的参照物。源码结构上有几个目录值得重点关注一个是网络组件相关模块处理TCP/MQTT等网络监听一个是协议支持相关模块负责把设备原始报文转成统一的设备消息再一个是规则引擎模块处理数据转发和联动逻辑。二开时绝大多数时候你只需要跟这三个区域打交道。3.2 一条设备数据从上线到展示要经过哪些环节在做协议扩展之前心里一定要有一条完整的数据流链路。我习惯这样跟团队成员讲设备通过网络组件接入平台建立连接比如MQTT连接到平台的1883端口。网络组件把收到的字节流交给协议支持模块。协议支持模块按照你写的协议规则解析报文区分这是登录认证、属性上报、事件上报还是设备回复。解析完成后数据被转换成统一的设备消息结构发到平台内部消息总线。规则引擎监听消息总线根据规则决定把数据写入时序数据库、触发告警、调用Webhook还是下发指令。前端通过API查询这些数据渲染成列表、图表和大屏。大多数二开工作发生在这条链路的第2和第3步。第4步以后平台已经把所有数据变成标准结构了你基本不需要关心。3.3 自定义协议支持包最简实现思路假设我要接入一款设备它走MQTT但topic和载荷格式都是自定义的。官方MQTT协议包处理不了就得写一个自定义协议支持包。思路是这样新建一个模块或代码目录实现协议解析的核心接口里面重点是两部分——上行解析和下行编码。上行解析是把设备发来的字节数组转成平台能识别的设备属性、事件结构下行编码是把平台要下发的一个指令比如开关命令转成设备能听懂的报文。下面是一段思路示意代码具体的方法签名会根据你clone的版本略有差异但它表达的结构是一致的// 伪代码示意实际以项目版本为准 public class CustomMqttProtocolSupport implements ProtocolSupport { Override public DeviceMessage decode(MessagePayload payload) { // 1. 从payload取出原始字节 byte[] data payload.getBytes(); // 2. 按私有协议解析例如前4字节是设备ID5-8字节是温度值 String deviceId parseDeviceId(data); double temperature parseTemperature(data); // 3. 转换成平台统一属性上报消息 ReportPropertyMessage message new ReportPropertyMessage(); message.setDeviceId(deviceId); message.addProperty(temperature, temperature); return message; } Override public MessagePayload encode(DeviceMessage message) { // 把平台下发的指令编码成设备能识别的字节流 // 例如根据message中的command类型组装一个JSON或者二进制包 } }写完协议支持包后在平台上把这个协议注册进去然后在网络组件里配置一个MQTT监听端口并绑定该协议最后在产品里配置好物模型——包括属性标识符、数据类型、是否只读等。此时设备连上来平台就能像处理官方协议一样处理它了。第一次做这一步时容易在“设备标识”这个环节卡住。很多自定义协议里设备ID不是简单的MQTT clientId而是藏在payload字节里或者需要从某个注册表反查。这就要在解码前多写一个“设备认证”步骤先解析出设备编号再到设备列表中校验这个设备是否存在、是否启用。当年我在接GPS终端时设备ID在登录报文里但属性上报报文里只有短编号同一台设备在不同报文里的标识还不一样当时为这个适配逻辑调了很久。3.4 规则引擎与应用层二开协议包做完设备的数据已经能进平台了。接下来是业务侧的二开通常分几条路走第一种是规则引擎。JetLinks界面里可以配置规则实例当设备上报数据满足某条件时触发指定的动作。比如设备上报的温度大于阈值就通过HTTP请求把告警推到客户的钉钉群或者企业微信。规则引擎是可视化界面业务人员也能调不需要为每个客户单独写代码。第二种是开放API。平台自带的OpenAPI已经覆盖设备管理、数据查询、指令下发等基础能力但客户的业务系统往往需要一些聚合接口比如“查一个项目下所有设备的汇总状态”。这种接口在平台源码里没有现成的需要你在后端新增一个Controller直接调用平台的设备管理服务。好在JetLinks的模块边界清楚新加接口不会影响原有功能。第三种是前端。前端二开最常见的是做一个定制的可视化大屏或者把平台的设备列表页面改成客户需要的布局。jetlinks-ui-antd是Vue技术栈熟悉Vue的团队改起来不费劲但要注意别把前端业务逻辑写得太重很多状态应该从后端的API直接拿而不是在前端硬算。3.5 为什么这样设计二开成本更低这一步很关键我要专门讲讲“为什么这样设计”。曾经有客户问我你们写协议解析的时候为什么不直接在设备消息处理代码里加一个if判断判断是某品牌设备就走某个解析逻辑那样不是更快吗确实是更快写一个if判断五分钟搞定。但问题在于平台的设备接入是一个持续演进的过程今天接一个GPS终端明天接一个温湿度传感器后天接一个门禁控制器。如果每次都往核心消息处理里加if代码很快就变成了没人敢动的意大利面条。协议包模式的好处是每个协议是独立的、插件化的新增协议不需要改动已有代码删掉协议也不影响平台主流程。平台官方在新版本里改进了消息处理逻辑也不影响你已经写好的协议包。做二开的人一定要有这个意识你的目标是长期维护这个系统不是做一次性交付。选择“稍微多花一点时间、但是架构上更干净”的方式后面会省下数倍的时间。4. 二开最容易翻车的五个环节与完整排查链路写过几年物联网平台二开之后我发现翻车的地方其实非常集中来来去去就那么几个问题。这里把排查链路完整写出来遇到问题别慌按步骤来。4.1 设备一直不在线从网关到协议栈逐层排查这是二开时遇到最多的问题设备明明连上来了平台设备列表里还是显示离线。我的排查顺序固定是先看网络组件——TCP端口通不通、MQTT连接是否建立成功再看协议日志——设备有没有上报数据报文有没有被解析出来最后看设备影子——平台记录的设备状态和最新时间戳有没有更新。实践经验里“设备不在线”最常见的根因有两个。一个是物模型的属性标识符和设备上报的字段名对不上解析出来的数据无处存放被平台丢弃另一个是设备只上报了数据但没上报心跳或者没走完登录认证流程平台认为设备未激活。排查时直接在协议支持代码里打日志把decode前后的原始报文和解析结果都打印出来基本五分钟就能定位到问题层。4.2 数据上报有延迟或丢包先查队列再查存储数据量一上来很多人会发现设备上报正常但平台页面上的数据刷新有延迟甚至少数据。排查第一步是看消息中间件有没有积压。很多平台架构里设备消息先投到消息队列然后由消费者写入存储。如果消费者处理不过来队列里积压得越来越多延迟就会出现。这一步通过监控中间件中的队列长度就能看出来。如果队列没有积压再查存储写入的批量大小和索引策略。时序数据库、ElasticSearch这类存储批量写入的性能远高于单条写入。JetLinks这类平台默认会有批量处理机制但二开时如果自己写了一版数据落地逻辑很容易忽略批量写入一条一条写库数据量一大必炸。另外一个隐蔽的点是有些二开在过滤环节误删了事件类数据导致页面正常但统计报表缺数据。建议在做任何过滤之前先保存一份全量原始数据到对象存储或者日志系统方便事后对账。4.3 多租户数据串号多半是二开时丢了租户上下文做SaaS化项目多租户隔离是底线要求。很多开源平台自带租户体系你在原有界面里操作数据天然是隔离的。但二开时你新增了一个接口或者写了一个定时任务往往会把“当前用户是谁”这个上下文丢掉结果数据就串了。我排查过的一个真实案例是二开团队写了一个定时任务每天凌晨把所有项目下的设备统计数据汇总后写入一张报表表。任务本身没有带租户ID结果所有租户打开报表看到的是同一份汇总数据。这个问题的恐怖之处在于它不报错、不告警数据还是好看的只是根子上错了。排查方法进数据库直接查这条数据是由哪个任务产生的追踪任务代码里是否存取了租户上下文如果是平台内新增的接口则检查接口是否在事务边界上正确传递了租户ID。建议在二开代码审查清单里加一条所有新增的数据写入逻辑必须明确写明租户ID的获取方式。无法获取租户ID的逻辑宁可不让它跑。4.4 前端表单和物模型对不上统一数据字典前端二开时最头大的是字段乱。平台里设备属性明明叫temperature前端图表里写的是temp物模型里单位是℃前端下拉框里变成“温度”。看着是小事但一旦数据对不上页面空白或者图表显示为0排查起来特别费劲。根本原因是前后端没有共用同一份数据字典。物模型是平台里的核心概念每个属性的标识符、名称、数据类型、单位都在物模型里定义好了。前端二开时应该直接读取物模型的元数据来动态生成表单和图表配置而不是在前端再硬编码一份字典。我现在的做法是后端提供一个通用的元数据接口前端框架从接口把所有设备的物模型拉下来页面动态渲染。这样新增一个设备类型前端什么代码都不用改物模型里有的字段页面上自动就有。改起来也安全。4.5 上游发版直接合并冲突用分支与模块隔离这个问题几乎每个二开团队都会遇到。项目做了一年平台官方发布了两个大版本你想升级拿新功能和Bug修复结果二开代码和上游代码冲突得面目全非。合并一次冲突耗掉三天还不一定保证没改坏原有逻辑。原因很简单二开时直接改了源头码树里的核心文件而核心文件恰恰是发版时改动最频繁的地方。我现在的工程规范是这样二开代码尽量独立成模块放在平台扩展机制支持的目录或独立仓库里确实需要修改核心源码的会做一个专门的二开分支每次官方发版时先拉取官方新版本作为主干再把二开分支里只包含修改文件的部分cherry-pick或merge上去。为了保证可追踪所有对核心源码的修改都用统一的代码注释标注例如“// CUSTOM-BEGIN: 客户X需求”和“// CUSTOM-END”之间的代码才是我们加的升级时只看这些标记范围就能评估冲突影响。5. 二开之后的工程化升级、测试、部署与团队组织二开不是把功能写出来就算完。交付之后这个系统要长期运行要升级、要维护、要交到别的团队手里。这一节聊聊代码之外的事情这些东西决定二开项目能走多远。5.1 团队配置至少要有一个能读懂源码的人很多企业做二开是从“找一个外包团队”开始的。外包团队做完功能、交了源码自己团队的人看着陌生的平台代码傻眼。任何二开项目内部至少要有一名能读懂平台核心模块源码的开发者他不需要自己把所有代码写完但他要能判断外包做的改动是否合理、是否符合平台的扩展机制、有没有埋雷。这个人选谁合适呢我建议找那种“业务理解能力强、愿意啃文档”的后端工程师而不是纯前端。物联网平台的复杂度主要集中在设备接入、消息处理、存储架构这些后端领域前端二开相对容易补课后端一旦听不懂整个项目就会失控。5.2 能不改核心源码就绝对不改这是二开圈子里最朴素的真理但遵守的人不多。每个二开需求出现时先问三句话平台原生的配置项能不能覆盖官方的扩展点能不能实现能不能用规则引擎或OpenAPI组合出来三个答案都是否才考虑动核心源码。为什么这么严格我见过太多案例二开团队为了图省事直接改核心源码改完后跑起来没问题但后续每一次升级都变成一场灾难。而且平台官方不可能帮你测试“被魔改过的版本”所有兼容性问题只能二开团队自己吞。如果你有“这个改动应该让平台官方来做”的感觉那就去搜搜官方仓库的Issue和Roadmap没准官方已经计划支持甚至新版已经实现你不升级还在自己造轮子。5.3 测试与压测设备模拟器必须提前进场二开项目的测试比普通Web项目复杂因为硬件环境很难在测试环境完整复现。我的做法是开发阶段就写一个设备模拟器能模拟成千上万台设备同时连接平台、上报数据、接收指令。设备模拟器在二开中的价值非常大。一是回归测试每次二开改完跑一遍模拟器确认设备接入、数据流转、规则触发都还正常二是容量摸底模拟器把并发数往上加就能看到平台的CPU、内存、消息队列积压情况提前发现瓶颈三是验收演示给客户演示时不能现场找真设备模拟器跑起来效果一样还稳定。压测的参考指标我一般这样定先按项目预估的设备总数再乘以一定冗余系数确定并发接入数然后观察平台在稳态负载下的响应延迟和资源占用。如果压到预估值的2倍时平台还能稳定运行这个二开版本才会被放行进入发布流程。5.4 容器化部署与线上监控大会小会我都建议二开交付用容器化部署。Docker Compose适合中小项目一台主机一台机器搞定规模大了再上Kubernetes。容器化交付的好处是环境一致性客户那边拉起来就能跑不用对着安装文档折腾半天。线上监控一定要做三件事日志集中采集、资源监控和告警通知。日志只留在服务器本地出问题排查太慢了统一收集到日志系统里按traceId去查整条链路资源监控至少覆盖CPU、内存、磁盘、中间件队列深度告警通知要能推到钉钉、企微这类工具。对于二开团队来说监控系统是你和客户之间最重要的“保险”很多隐蔽Bug都是通过监控曲线提前暴露出来的而不是等客户打电话投诉才发现。5.5 文档和交接别让二开成为一次性人肉工程二开项目的文档通常是个短板。功能是外包写的客户领导不太关心但后期维护的人太关心了。接手一个二开系统最痛苦的就是不知道哪些地方被改过、为什么改、上游新版本该怎么合。至少要有四类文档二开改动清单改了哪些模块、新增了哪些接口、部署手册依赖组件、版本号、环境要求、运维手册日志位置、常见故障排查办法、备份恢复步骤、架构说明二开的模块和原平台核心模块的关系以及升级时需要注意的冲突点。写文档这件事我吃过亏也占了便宜。早年一个项目交付时没有留改动记录半年后客户要求升级版本我方接手的人看代码看了整整一周才敢动手。后来另一个项目从第一天就坚持把二开改动记录在案同样的升级任务三天完成。区别不在于技术能力而在于有没有把“改动痕迹”当作资产来管理。最后再分享一个我自己的习惯。每次启动一个新二开项目我会花半天时间专门读一遍平台官方仓库的CHANGELOG和升级指南搞清楚我当前用的版本和上游最新版本差多少。很多二开团队只盯着“我要的功能”对上游版本演进毫无概念结果做到一半发现官方新版本里已经做了他们想做的功能或者已经改变了某个模块的API——那场面真的非常尴尬。项目选型、二开发开、长期维护所有的环节都要有一种“跟着上游走”的心态不是一次定死而是持续对齐。这也算是我做了这么多年二开项目最想提醒后来者的一句话。