TCP OTA 服务端手册

一、服务端在链路中的位置

1、链路上的角色

2、多设备并发与 sid 回显

tcp_mux 与本服务之间只有一条 TCP 长连接，这条连接上同时承载多台设备 （各自不同 sid）。因此：

• 每处理一个请求帧，就记下这个帧的 sid 与 svc_type， 并在回包里原样带上；
• 绝不能把 sid 缓存在连接对象上 —— 期间其它设备的请求会把它改掉。

/* ✅ 正确：逐请求记录 */
if (f->frame_type == DATA) { cur_sid = f->sid; cur_svc = f->svc_type; }
send_frame(DATA, cur_svc, cur_sid, payload, len);

/* ❌ 错误：多设备并发必然串台 */
conn->sid = f->sid;              // 设备 A 的请求
... send_frame(..., conn->sid)   // 期间设备 B 的请求可能已改掉它

二、帧收发契约

1、帧头与同步字

与客户端一致（详见 客户端手册 · 帧格式），服务端实现要点：

• 同步字固定 AA 55 5A A5 FF EC（6 字节），帧头 14 字节，多字节字段大端；
• 帧长 = 14 + 数据长度，无填充、无帧级校验和；
• 发 JSON 响应用 DATA（0x00）帧，一帧一条消息； 二进制分片的每个字节帧也是独立的 DATA 帧。

2、收帧容错

3、发帧要求

• 回包的 frame_type / svc_type / sid 取本请求的值（见 一、2）；
• JSON 响应与字节帧都在同一连接上按序发出（pull 的 JSON 元信息帧在前， cnt 个字节帧紧随其后）；
• 发送队列满时不丢帧：pull 走 again 流控 （见 六、4），其它响应排队发送。

三、请求处理契约

1、报文校验与错误映射

2、动作分发表

3、按需扫描固件库

• 只有 check / changelog / start 三类动作会触发固件库扫描（它们才开始「一次新的判断 / 传输」）；
• 扫描有最小间隔（SCAN_INTERVAL_SEC，默认 10 秒），间隔内重复请求零系统调用开销；
• 写锁（write_busy）每秒检查，秒级生效，不受扫描间隔影响；
• 配置热加载走同一套节奏：只在收到设备请求时看一眼配置文件， 冷却 ≥10 秒（与 SCAN_INTERVAL_SEC 取大者），冷却期内零 IO； 改完配置 → 下一个请求即生效（日志出现 配置已热加载， 统计行有「配置重载 N」计数）；
• 设计意图：没有升级任务时系统完全静止，不空转、不浪费 CPU （闲时既不扫固件库，也不读配置文件）。

4、响应序列化规则

• 失败：{"ok":0,"err":N,"msg":"…"}（msg 供日志 / 排障， 客户端不必解析）；
• 成功：{"ok":1, …} + 该动作的字段；字段按「是否非零 / 非空」决定是否输出， 客户端只读它关心的；
• check 的 busy 字段与 latest 一起判断是否输出； 无更新时附带 "nonew":1，便于客户端直接分支。

四、各动作实现要点

1、hello

• 返回本协议的 pver、允许区间 min / max 与生效分片 chunk；
• 客户端带了 chunk → 按本协议区间钳制后返回；
• 带了 product → 顺带返回该产品配置里的推荐分片（同样钳制）， 客户端可以据此少配一个参数。

2、check

判定顺序（前面的条件命中就直接返回，不读固件文件）：

1. 写锁 / 维护中 → busy=1 + upd=0（不暴露版本）
2. 产品不存在 → err=3
3. 产品停用 → err=4
4. 灰度未命中（按 did）→ err=10
5. 固件文件缺失 → err=5
6. 版本比对 → 相同则「无更新」：upd=0 + nonew=1（ok 仍为 1）
7. 有更新时再选差分：补丁可用且客户端版本支持差分 → delta=1 + dsize

3、start

• 分配下载会话并返回 sid；会话表满 → err=13；
• trans 返回实际采用的方式：请求显式指定就按指定（无补丁 → err=6、 版本过低 → err=14），未指定则「有补丁优先差分」；
• size 是本次传输对象的大小：全量 = 完整包；差分 = 补丁大小；
• md5 恒为目标完整包的 MD5（差分路径下即「旧包 + 补丁」合成产物的校验基准）；
• total = ⌈size / chunk⌉（按实际生效分片向上取整）。

4、pull

5、finish / abort / report

• finish：结束下载会话，返回 sid / size / 目标完整包 md5；请求里的 result 与客户端产物 md5 仅记日志，用于对账排障，不参与决策；
• abort：直接释放会话，回 {"ok":1}（缺 sid → err=8）；
• report：把 event / msg 写进日志后回 {"ok":1}，客户端上报失败原因靠它落盘。

6、changelog

• 返回更新日志全文；没有日志文件时回 {"ok":1,"content":""}，不是错误；
• 日志超过 60 KB（OTA_CHANGELOG_MAX）→ err=11 （不截断成半截 JSON）；
• cv 可忽略：一律返回「最新版本的日志」；
• 错误分支与 check 对齐：缺 product → err=2、 未知产品 → err=3、停用 → err=4、灰度未命中 → err=10、维护中 → err=7、读文件失败 → err=11。

五、错误码触发场景全表

服务端视角：什么情况回哪个码。客户端侧的建议动作见 客户端手册 · 错误码全表。

六、分片与传输参数

1、钳制规则与优先级

客户端传来的 chunk 一律钳制到本协议区间；生效值的优先级（高 → 低）：

1. start 请求里的 chunk
2. product.ini 的 CHUNK_SIZE
3. [transfer.tcp] DEFAULT_CHUNK_SIZE
4. [transfer] DEFAULT_CHUNK_SIZE（公共默认）

2、TCP 通道参数

3、文本模式片数反推

bin=0 时每片以 hex 内嵌 JSON（体积 ×2 加包装），因此按消息上限反推安全片数：

/* 每片约占用 chunk*2 + 64 字节，留出 JSON 包装余量 */
int per          = chunk * 2 + 64;
int max_by_size  = (TCP_OTA_MSG_MAX - 256) / per;   /* TCP_OTA_MSG_MAX = 64 KB */
if (batch > max_by_size) batch = max_by_size;

4、发送队列与 again

• 每连接一个发送队列（512 槽）；二进制模式下每片占一个槽，元信息 JSON 还要占 1 格；
• 可用槽位不足时不裁剪 cnt 偷发一部分，而是整体回 again=1 —— 保证「声明 N 片就一定发 N 片」；
• 客户端按 off 不变、退避 50 ms 重发即可（见 客户端手册 · 流控信号 again）。

5、限速与传输节奏

• 下载限速在 [throttle] 配置：分「空闲时段 / 拥挤时段」两档速率 （默认 00:00~17:00 = 8 Mbps，17:00~24:00 = 2 Mbps）；
• PER_CONN=0 表示所有连接共享一份速率（保服务器出口）， =1 表示每连接独立；
• 限速只影响发送节奏，不影响正确性：表现为客户端更频繁地收到 again， 不会出现数据缺口。

七、会话与资源管理

1、会话生命周期

• start 创建下载会话（分配 sid）；
• pull / finish 都会刷新活动时间；
• 空闲超过 600 秒（SESSION_IDLE_SEC）自动回收并记日志；
• finish / abort 立即释放；服务重启后会话全部丢失 （客户端需重新 start，check 结果仍有效）。

2、上限与回收

3、内存与并发

• 固件用 mmap 共享映射：N 台设备同时下载同一固件只占一份物理内存；
• MD5 带缓存（按 mtime + size 失效，条目上限 256），避免每个 check 都重算大文件；
• 下载走 writev(mmap)，不做编码与复制 —— 二进制模式的大流量路径零拷贝。

八、固件库与产品名（服务端视角）

1、产品名匹配

• product = 固件库目录名，按字节精确比对（区分大小写）；
• 名字缓冲 FW_NAME_MAX = 128 → 上限 127 字节；
• 允许中文；客户端发 GBK 字节时会自动归一化成 UTF-8 再比一次（老设备兼容）， 两种编码指向同一份固件；
• 目录组织、补丁命名、发布流程见 ota/docs/固件管理.md。

2、版本与差分基线

• 版本号按 X.Y.Z 解析（各段 1~4 位数字，可带 v 前缀）； 解析失败的 cv 一律签名为「不支持差分」（不下发补丁）；
• 补丁按 cv → 当前发布版本 查找；找到才给 delta=1； 找不到就把客户端要的差分拒掉（err=6），客户端回退全量；
• 校验基准始终是目标完整包 MD5：全量时它等于文件 MD5，差分时用于校验合成产物。

3、灰度与写锁

九、运维与排障

1、与协议相关的配置项

2、自检与日志

cd /home/user/install/ota

./ota_server config/ota_config.ini --check-config   # 打印生效配置 + 固件库全貌（版本/大小/MD5/补丁）
python3 scripts/test_ota_e2e.py --via-mux           # 经真实链路端到端自测
python3 scripts/verify_real.py --via-mux            # 真实大包 + 官方差分补丁验证

• 日志关键字：check:（版本判定 / 差分选择）、start:（会话与传输方式）、 pull 相关（队列满 → 退避）、客户端上报（report 内容）；
• 响应里的 msg 与日志同源，排障时先看 err 再看日志里的产品名与版本号。

3、常见故障对照表

十、相关文档