8 月产品月报我先直接说结果蝉翊官网改版正式上线协议库第一批 20 个协议也完成了首批收录。这个月团队的核心精力几乎都压在了这两件事上从需求整理、方案设计到上线验证节奏比平常紧了不少。写这篇东西有两个原因一是给自己团队留一份完整复盘二是把我们在改版和协议库落地过程中踩过的坑、验证过的做法整理出来给同样在做官网重构或打算搭协议库的同行一个参考。如果你正好在负责产品官网、技术文档体系或者通信协议对接相关的工作这篇应该能帮你省一点时间。1. 项目立项为什么官网改版和协议库要放在同一个月1.1 旧官网的三宗罪信息结构、内容更新和技术债这次改版不是拍脑袋决定的旧官网的问题其实积累了大半年。第一是信息结构混乱。首页堆了很多荣誉资质、公司介绍、活动照片但用户真正关心的产品文档、协议说明、接口参数反而藏得很深。我们拉过页面点击数据从首页到达协议文档平均要 5 次点击移动端有时7次都点不到这在一个技术产品官网里是很致命的。第二是内容更新成本太高。旧官网用的是老 CMS 加自定义模板发布一篇文章要登录后台、改模板、传图片、手动生成静态页流程琐碎。技术团队写好的更新交给市场同学发布经常要等两三天等发布完内容又过时了。产品文档和协议说明长期不更新客户看到的第一印象就是项目不活跃。第三是技术债。旧站没有响应式设计手机端体验很差没有缓存策略首屏加载在弱网环境要 6 秒以上也没有清晰的 SEO 结构很多页面抓取不到。这些问题凑在一起就不是“换个皮肤”能解决的必须把整个站点重新搭一遍。所以立项时我们就定了调子改版等于重建不是美化核心目标是让官网变成一个能持续更新、能被搜索到、移动端好用的产品入口。1.2 协议库要解决的痛点测试、对接与学习成本协议库这件事的起因更直接。我们是做物联网设备、工业数据采集这类产品的日常要面对大量通信协议。客户设备可能走 Modbus、MQTT、CAN也可能用自定义 TCP 协议开发同学每接一个新设备就要翻一遍厂商手册重新写一次解析代码测试同学还要手工构造报文验证功能。同一个协议不同厂商的字段定义还不完全一致沟通成本非常高。我们想要的是一个“协议库”产品它不是简单放几篇协议科普文章而是把协议整理成结构化的条目包含帧格式、字段含义、时序过程、校验算法、典型报文示例和常见坑点。研发可以拿它当开发参考测试可以拿它造模拟报文技术支持可以直接把它发给客户当对接说明。第一批收录 20 个协议就是要先覆盖我们业务里最高频的那批协议把重复劳动压下去。立项的时候还有个小讨论要不要直接买现成的协议库方案。后来一致决定自建因为外部的协议百科偏理论很少从“开发/测试核对”的角度写我们要的是每个协议都对应一份可校验、可复现的报文细节这东西只有自己最懂。1.3 这个月定下的成功指标任何项目没有指标就会失控所以我们在一开始就定了几个可量化的目标。官网方面首页 LCP 小于 2.5 秒移动端 Lighthouse 综合评分到 95 以上产品文档从首页到达的点击次数不超过 2 次旧 URL 全部做好重定向不出现批量 404。协议库方面首批正式收录 20 个以上协议每个协议都包含报文示例和校验方式上线后日检索量能反映用户确实在用团队内部做一次“新协议对接模拟测试”研发和测试按协议库条目能独立完成解析开发。这些指标不复杂但好处是边界清楚。后面所有决策比如哪些内容砍掉、哪些功能先不做都是拿这些指标过滤的。指标之外的事哪怕再好看也排到后面版本再说。2. 官网改版实操信息架构、技术选型与性能优化2.1 信息架构重组把用户最关心的内容提前旧官网最大的问题不是页面丑而是用户找不到东西。所以重构信息架构时我们放弃了传统的“公司介绍优先”结构改成“产品与文档优先”。整个导航只保留 5 个主入口产品方案、协议库、技术文档、关于我们、联系我们。协议库和文档直接提到一级导航这在公司官网里其实少见但对我们这种技术型产品是合理的因为来官网的人大多是想查资料、看协议、找对接方式。首页的内容优先级也重排了第一屏放产品核心价值和一句话说明第二屏放典型应用场景第三屏放协议库入口和最新技术文档公司介绍和新闻动态压缩到非常靠后的位置。改之前我们也犹豫过怕首页太“技术”不够“企业”。后来看数据旧站访问最多的就是文档页和协议相关文章访客来源大头是技术搜索说明使用官网的人要的就是技术信息这个方向没问题。每个产品页我们也做了模板化处理统一了模块结构产品概述、适用场景、技术参数、典型部署、关联文档、常见问题。这样市场同学以后新增产品只要填模板不用从零排版内容更新的门槛一下子降下来了。2.2 技术选型从老 CMS 切到静态站点生成器技术选型时对比了几条路线继续用传统 CMS、上无头 CMS、还是直接用静态站点生成器SSG。最后选了 SSG主要理由有三条。第一我们的内容以技术文档、协议说明、产品介绍为主变更频率其实不高完全不需要动态渲染。第二SSG 天然生成纯静态页面部署到 CDN 后加载速度很快SEO 也友好搜索引擎直接抓取 HTML不需要等服务端渲染。第三成本低、不需要维护一套动态站点服务整个官网可以用 Git 管理改版、回滚都非常方便。具体选型上用了常见的站点生成器Markdown 写内容组件化开发前端模板。目录结构按照内容区块拆分产品介绍、协议文档、博客分别对应不同内容集合。文档部分直接支持 Markdown 语法研发同学写技术文档没有任何额外负担。这里有个小建议标题里那些“官网改版”经常只关注视觉但技术选型一定要先想清楚你的内容由谁维护、更新频率多高再决定动态还是静态盲目上框架只会增加维护成本。为了保证发布流程顺畅我们搭了一套很轻的 CI代码推送到主干分支后自动构建、自动跑一遍死链检查然后部署到对象存储再由 CDN 分发。整个过程 10 分钟以内完成。以前改一个页面要折腾一天现在写文档、提交、自动上线这个体验差别非常大。2.3 性能指标与上线前回归不只是跑分性能数据在改版启动时就定了基准。我们针对首页和文档页各做了三轮优化。第一轮是图片资源。旧官网很多图片没有压缩一张产品图 2MB 很常见。这次全部改用 WebP 格式尺寸按实际展示大小输出配合懒加载首页图片体积从整体 8MB 降到 900KB。第二轮是字体。旧站引用了多套中文字体文件体积大还阻塞渲染。我们系统字体为主自定义字体只保留 logo 场景并且开启字体子集。第三轮是缓存和 CDN。所有静态资源加了内容哈希缓存策略设到一年然后接入 CDN弱网环境下首屏速度和之前完全不是一个级别。上线前的回归检查也列了清单除了常规的浏览器兼容外重点做三件事移动端 375px 宽度逐页检查确认没有横向滚动老 URL 逐个测试 301 跳转把搜索引擎权重接续过来检查 sitemap 和 robots 文件确保搜索引擎能正确抓取新版页面同时屏蔽掉我们不想被收录的后台路径。这些检查看起来琐碎但对后续自然搜索流量影响很大漏掉一个就可能在改版后掉一半收录。3. 协议库首批 20 协议怎么选领域盘点与代表协议拆解3.1 20 协议全景分布协议库首批收录最关键的决策是选哪些协议。我们的逻辑很简单优先覆盖团队日常开发测试中高频遇到的协议同时兼顾知识体系的完整度。按领域分成几组我在表格里列一下落地方案。协议分类收录协议示例收录原因典型应用场景工业现场总线Modbus RTU、Modbus TCP、CAN 2.0B、HART工业设备数据采集最常遇到客户存量设备多PLC、仪表、变频器、传感器数据读取物联网无线MQTT 3.1.1/5.0、Matter、CoAP、经典蓝牙、IEEE 802.11IoT 平台对接、设备配网、智能家居场景高频出现传感器上云、家居设备互联、设备远程控制汽车电子UDS 诊断协议、SOME/IP车载诊断和整车通信是重点业务方向ECU 诊断刷写、车内服务发现、车辆远程诊断网络传输与流媒体TCP/IP、ARP、TLS/SSL、RTMP、RTSP、SRT音视频传输、设备网络调试、安全通信链路视频上云、低延迟直播、抓包排查嵌入式与芯片接口SPI、IIC、MIPI、PCIe、AHB、AXI、USB、UART嵌入式底层开发、芯片寄存器调试、驱动联调传感器采集、显示屏驱动、高速数据传输文件与特殊协议YMODEM、Robots 协议、北斗协议 2.1特定业务场景和项目刚需固件升级、爬虫规范、定位授时设备对接第一批能够正式入库并通过验证的是 22 个协议另外还有 5 个在评审阶段后续版本会逐步放开。别看 20 多个好像不多每个协议要整理到“可开发、可测试”的程度工作量远比想象中高。这里我特别想强调的是协议库不是放一堆协议名称就完了重点在于每个协议都有结构化的字段说明和不只一个的报文示例。3.2 Modbus、MQTT 等工业与物联网协议拆解这里挑两个有代表性的协议展开说说入库过程和难点。第一个是 Modbus。Modbus 之所以值得做细是因为它在工业领域太普及了几乎到了“没有 Modbus 就没法跟现场设备对话”的地步。但 Modbus 的坑也很多RTU 模式和 TCP 模式帧结构不同CRC16 校验算错一个字节顺序就全错了。以 Modbus RTU 为例一条完整的请求报文结构是从站地址1 字节 功能码1 字节 数据区N 字节 CRC16低字节在前。很多人第一次写代码就栽在 CRC 这里CRC16 结果低字节在前发送这是最容易忽略的。我们在协议库条目里专门把字节序写清楚还配了正反两个示例报文一个正确一个错误方便测试同学直接拿来做比对。Modbus TCP 则多了 MBAP 头包含事务标识符、协议标识符、长度和单元标识符端口默认 502但实际项目里很多设备会改端口这点也单独做了提示。第二个是 MQTT。这个协议看起来简单但版本之间差异不小。首批收录同时覆盖 3.1.1 和 5.0 两个版本重点整理了连接报文、心跳保活、订阅发布流程以及 QoS 0/1/2 的区别和适用场景。很多团队第一次接 MQTT 会忽略遗嘱消息LWT的作用设备异常掉线时服务器无法感知有了遗嘱消息才能及时更新设备在线状态。这些细节如果只看官方规范很难有直观感受但放到协议库里结合实际场景写研发和测试都能省很多排查时间。3.3 嵌入式与芯片接口协议为什么连 SPI、IIC 这种“底层协议”也收录有人可能会问SPI、IIC、PCIe 这种芯片接口协议也需要入库其实对我们做嵌入式相关产品的人来说这类协议比上层网络协议更容易踩坑。SPI 有四种工作模式区别只在时钟极性和相位配置错一个 bit读取的数据就是乱的IIC 的地址有 7 位和 10 位之分还要注意读写位拼在地址最后一位MIPI 的 CSI/DSI 差分信号时序更是严格稍有偏差屏幕或者摄像头就工作异常。把这些底层总线协议录入协议库主要价值有两个。第一是统一术语和参数定义团队内部讨论时不会出现“SPI 模式 0 还是模式 2”这种分歧。第二是形成模块化的驱动参考比如 IIC 的起始条件、停止条件、应答信号在文档里都有时序图和代码片段新同学做驱动开发时可以直接照做不用再满世界翻芯片手册。实际上我们在做固件升级功能时YMODEM 协议也是靠协议库快速搞定的——文件传输的分包、ACK/NAK 重传机制、EOF 结束符处理这些细节一旦记漏联调时就会卡住很久。4. 协议库从文档到产品字段设计、入库流程与版本管理4.1 协议条目的数据结构从文档到结构化字段协议库能不能用很大程度取决于数据模型。如果只是把手册原文搬上来那和 PDF 有什么区别。我们在设计条目字段时反复推敲之后定了以下核心结构协议名称、协议别名、分类标签、传输载体、参考标准、版本号、帧结构描述、字段表、数据校验方式、典型时序、误用风险点、报文示例、适用场景。字段表是重点每个字段包含字段名、偏移量、长度、取值说明、是否必填、示例值。这个设计参考了真实抓包工具的做法让开发人员不需要从大段文字里自己“翻译”协议直接看字段表就能理解报文。时序部分我们用文字加简化的步骤描述不引入复杂的图表工具保证内容在任意设备上都能正常查看。我放一个简单的 JSON 结构示例供参考{ protocol_id: modbus-rtu, name: Modbus RTU, category: industrial-bus, transport: RS-485/RS-232, reference: MODBUS Application Protocol V1.1b3, frame_schema: 从站地址 功能码 数据区 CRC16(低字节在前), fields: [ {name: 从站地址, offset: 0, length: 1, required: true}, {name: 功能码, offset: 1, length: 1, required: true}, {name: 数据区, offset: 2, length: N, required: true}, {name: CRC16, offset: 2N, length: 2, required: true, note: 低字节在前} ], checksum: CRC16_MODBUS多项式 0x8005初始值 0xFFFF, examples: [ {direction: 请求, hex: 01 03 00 00 00 0A C5 CD}, {direction: 响应, hex: 01 03 14 10 12 33 ...} ], risk_points: [设备地址为 0 时不响应, 波特率不一致会导致响应超时] }这个结构不是一次定稿的中间改过两轮。第一轮发现没有“误用风险点”字段很多只有踩坑之后才知道的细节无处安放第二轮发现报文示例需要同时提供请求和响应两条否则测试无法闭环。结构定了以后内容的录入规范也就顺了。4.2 一条协议从原始文档到入库的完整流程协议入库不是写文章我们规定了六步流程收集原始资料、提取关键字段、编写结构化描述、技术评审、模拟验证、入库发布。收集原始资料这一步尽量找官方标准文档和原始芯片/设备手册网上转载的文章只作为参考。提取关键字段是最费时间的部分需要把几十页手册浓缩成一张字段表。编写结构化描述就是按 4.1 里的 JSON 结构填充内容。技术评审由另一位协议经验更足的同事来做重点看字段是否遗漏、字节序是否写反、时序步骤是否可执行。模拟验证是很多人会忽略的一步。我们在内网搭了简单的模拟端用 Python 脚本去解析协议库条目里提供的示例报文校验请求报文按文档结构解析能否得到预期字段CRC 校验能否通过响应报文能否按文档描述的时序正常处理。这一步能筛掉大部分低级错误。入库前还有一次双人交叉核验一个人写、另一个人独立验证确认无误才正式发布。这样一套流程下来一条简单协议入库大概需要一天复杂协议像 SOME/IP 可能要两三天。4.3 版本管理和接下来的协议扩展协议库上多了以后版本管理会变成一个隐形大坑。我们的策略是协议版本与文档版本分开记录。比如 Modbus 有 1.0、1.1b3 等官方版本那就在条目里记录参考标准版本我们自己整理的协议条目本身也有编辑版本每次修改保留历史记录方便回滚和追溯。另一个决策是优先支持用户自定义协议。客户设备不可能只用标准协议私有协议才是对接里最常见的痛点。我们计划下一步提供协议编辑器团队内部或者客户可以把私有协议的字段结构录入到系统里再自动生成解析代码模板。这个功能已经在规划中首批 20 标准协议更像是打地基真正的长期价值在于“协议结构化”这件事本身。5. 踩坑复盘官网与协议库上线时的排查记录5.1 官网改版上线时踩过的三个坑第一个坑是字体加载拖慢首屏。新版站点最开始引用了两套网络字体看起来效果不错但 Lighthouse 跑分直接掉到 80 以下。后来查资源加载时序字体文件阻塞了首屏渲染。解决办法是把全局字体改成系统字体只在特殊标题场景用字体子集首屏性能立刻提上来。这个坑提醒我们设计效果和性能必须同时考虑。第二个坑是旧 URL 重定向遗漏。我们以为整理得很全面了结果上线后一周搜索引擎搜索控制台里陆续报出 404 链接都是旧站的产品详情页。排查发现有一部分 URL 是市场同学以前手动发布的没在整理清单里。我们的补救措施是写脚本爬取搜索引擎收录的旧链接列表逐个补做 301 重定向花了大半天才清完。建议以后做官网改版在上线之前就导出搜索控制台的全部外链和收录页面对照着整理重定向。第三个坑是移动端横向滚动。新版页面在手机端测试时发现部分页面出现轻微横向滚动原因是内容区里一个表格设置了最小宽度。我们在代码里漏掉了小屏溢出处理最后统一给表格和代码块容器加了横向滚动策略才解决。这种东西不多做几次真发现不了上线前一定要做小屏逐页截图对比。5.2 协议库上线的流程漏洞与数据质量问题协议库这边的问题主要集中在数据质量而不是代码逻辑。第一个典型问题是术语不统一。不同协议对同一个含义用的词完全不同比如“报文”有的叫 frame有的叫 packet有的叫 telegram字段里“字节序”有的写 little-endian有的写 low byte first。我们最终建了一个术语对照表所有协议条目统一用中文为主、英文关键词辅助标注的方式。第二个问题是校验算法容易被误解。Modbus RTU 的 CRC16 和通用 CRC16 不是同一个算法多项式、初始值、输出异或值都不一样第一次录入时差点把两个混在一起。后来我们在每条协议里直接注明校验算法全名并把计算方法写清楚避免“用错算法”这个低级错误再发生。UDS 诊断协议更麻烦会话控制、安全等级、服务 ID 都有依赖关系不能简单只列帧格式还要把状态流转写出来这部分内容花的时间比预期多一倍。第三个问题是报文示例不够完整。最初我们打算每个协议只给一个示例但评审时发现只给一条报文没法验证响应和重传机制。于是改成“请求报文 响应报文 异常报文”三件套能包含异常分支的尽量包含。这件事让录入工作量增加不少但对测试环节的价值非常大值得做。5.3 常见问题速查表我把这次项目中遇到的高频问题整理成了一张速查表方便大家直接对照。问题可能原因解决思路官网改版后搜索流量下降旧 URL 未做 301 重定向、sitemap 未更新导出旧站收录清单逐个 301重新提交 sitemap官网首屏加载慢字体阻塞渲染、图片体积过大、缺少 CDN系统字体优先、图片转 WebP 压缩、静态资源加 CDNModbus RTU 解析数据错误CRC16 字节序写反、寄存器地址偏移未处理对照协议库字段表核对字节序用已知报文反测MQTT 设备频繁掉线心跳间隔配置不合理、未设置遗嘱消息按网络环境调整 keep-alive启用 LWT 机制SPI 读取数据全 0 或乱码SPI 模式配置错误、时钟极性相位不匹配确认主从设备 SPI 模式一致再检查信号线连接UDS 诊断无法进入扩展会话服务 ID 或安全等级不匹配核协议库状态流转说明先发送会话控制指令协议库条目出现数据错误原始资料版本混杂、缺少交叉验证坚持官方标准优先、双人复核、模拟验证再入库这张表目前只是第一批问题后续使用中肯定还会补充。我个人的习惯是把每次联调遇到的问题都回填到对应协议条目的“误用风险点”里这样协议库越用越厚后面的人就越踩不到坑。这个项目做完以后我自己的体会是官网改版和协议库本质上都在做同一件事——把团队内部已经掌握的知识和经验结构化地沉淀下来变成别人可以访问、可以使用的东西。无论是官网的文档前置还是协议库的字段表设计核心思路都一样用户找东西的成本越低产品的可信度就越高。下一步我们打算把协议库的协议解析辅助工具开放出来配合模拟报文功能让协议对接这件事从“查文档靠经验”变成“查条目靠工具”。