简介针对中国移动短信网关通讯协议CMPP2.0的教案文档面向需要接入移动短信网络的应用开发商、SP服务商及平台运维人员。文档系统讲解了协议适用范围、缩略语含义以及SP与ISMG之间的网络结构并围绕CMPP提供的短信提交、查询、接收、取消等核心功能逐项说明消息编码与交互流程。资源为单个PDF文件大小478KB内容为2002年中国移动发布的官方协议规范包含完整目录与章节划分可作为开发调试时随时查阅的权威手册。其中对CMPP_CONNECT建立连接、CMPP_SUBMIT提交短信、CMPP_DELIVER状态上报等关键命令均给出了消息头字段定义、消息体参数说明和应答要求同时还涉及TCP长连接维护、心跳机制、错误码定义等细节能帮助开发者系统掌握协议全貌快速定位接入异常。目前已有79人学习下载适合刚接触CMPP2.0的工程师作为入门指导也适合有经验者作为案头参考。1. CMPP2.0 是短信接入的第一道门槛先弄清它是谁、管什么第一次对接中国移动短信网关服务商发来一份《教案之中国移动短信网关通讯协议cmpp2.0.pdf》。原以为照着文档写个 TCP 客户端就能发短信结果真正跑通用了一周一半时间耗在鉴权上。CMPP2.0 是中国移动短信网关与内容提供商之间的二进制 TCP 协议负责四件事建立连接、双向鉴权、短信提交与状态报告。它让业务系统用统一格式与运营商网关交换数据省去各家自定接口的混乱。适合要接移动短信通道的后端开发、负责联调的网络工程师以及想评估短信通道的技术负责人。下面我按落地顺序拆解协议骨架、业务流程、避坑点并给你一套没有真实网关也能验证的模拟方案。2. CMPP2.0 协议骨架连接、鉴权与报文格式2.1 连接建立从 TCP 连接到 CMPP_CONNECTCMPP2.0 选用 TCP 长连接而不是 HTTP 短连接核心原因是网关需要持续跟踪链路状态短信提交对时延又敏感。短连接每次都要握手连接建立成本高长连接一旦建立就可以连续发包。代价是链路空闲时要用心跳维持这个点我会在后面单说。接入参数通常不在协议文档里而是在运营商下发的工单中网关 IP、TCP 端口、SP 源地址、共享密码、业务代码。端口号不少资料写 7891但不同省份、不同网关版本可能都不一样连不上时先核对工单别死等。连接阶段我一般按这个步骤走先在本机用nc -vz 网关IP 端口确认 TCP 层能通。建立 TCP 连接后客户端必须先发 CMPP_CONNECT网关不会先开口。等待 CMPP_CONNECT_RESP超时时间设为 10 秒左右。检查响应里的状态码0 表示成功别的值去码表定位。成功后才能发业务包否则网关会直接丢弃 CMPP_SUBMIT。CMPP_CONNECT 消息体的关键字段如下表。字段全部按网络字节序大端序组装这一个字节序问题就能让鉴权包错位。字段长度含义常见坑Source_Addr8SP 源地址位数不足要补 0不能带符号AuthenticatorSource16MD5 结果算法见 2.3Version1协议版本要和对端一致Timestamp4时间戳按对端要求格式化连接也有重试策略。我见过很多客户端不断新开 TCP 连接重连把网关连接数打满。正确做法是失败时指数退避比如 1 秒、2 秒、4 秒、8 秒最大 30 秒并且每次退避后重新分配 Sequence_Id。重连不是越快越好太频繁会让网关误判为攻击。2.2 报文头与消息类型12字节头怎么读CMPP2.0 没有 HTTP 那样的行分隔符所有消息都以固定 12 字节头开始。头部字段统一大端序任何一个字节错位Total_Length 都会变得离谱。三个字段分别是Total_Length整个消息长度包含 12 字节头。Command_Id命令字请求和响应通过最高位区分。Sequence_Id32 位无符号整数客户端生成关联请求与响应。Command_Id 常用值我整理成一张表写协议栈时可以直接抄Command_Id命令名方向0x00000001CMPP_CONNECTSP→网关0x80000001CMPP_CONNECT_RESP网关→SP0x00000002CMPP_TERMINATESP→网关0x00000003CMPP_SUBMITSP→网关0x80000003CMPP_SUBMIT_RESP网关→SP0x00000004CMPP_DELIVER网关→SP0x80000004CMPP_DELIVER_RESPSP→网关0x00000005CMPP_QUERYSP→网关0x00000007CMPP_ACTIVE_TESTSP→网关0x80000007CMPP_ACTIVE_TEST_RESP网关→SP解析时最容易踩的坑是认为一次 recv 就能拿到一个完整包。TCP 是字节流可能两个 CMPP 包粘在同一个段里也可能一个包被拆成多次到达。正确做法是先读满 12 字节头解析出 Total_Length再循环读取直到读满Total_Length - 12字节才算拿完整条消息。我在写客户端时通常会封装一个read_exact(n)函数专门处理这种半包。提示包体长度以头部 Total_Length 为准不要依赖一次 recv 返回的字节数。很多诡异的中文乱码、命令错位都从这里来。2.3 鉴权算法AuthenticatorSource 到底怎么算CMPP_CONNECT 里最难的是 AuthenticatorSource。它不是直接传密码而是把若干字节拼成原始串后做 MD5。不同网关实现的细微差异会让结果完全不同这也是联调阶段卡壳率最高的地方。我通常按四步实现将源地址按 ASCII 转字节不足 8 字节补 0x00 或空格以工单规定的位数为准。拼接 9 个 0x00 字节。拼上共享密码的 ASCII 字节。再拼当前 Sequence_Id 的 4 字节大端值最后拼时间戳。对拼接结果取 MD5得到 16 字节摘要。这里有个容易反复确认的口径文档里写“Timestamp 为 MMDDHHMMSS”但在原始串里这串数字到底以 10 字节 ASCII 形式存在还是 4 字节整数不同实现确实不一样。我建议联调前先让对方提供一份正常连接抓包或者用对方 SDK 发一个包然后用工具把客户端算出的 16 字节和网关日志里的 16 字节逐项对比。不要一上来就改代码先确认算法口径。1990在自测时可以用openssl md5对同样原始串计算和代码结果比对。MD5 结果是大写还是小写不重要重要的是二进制字节不能转成字符串再比较很多十六进制字符串大小写问题都是这里来的。3. 从建连到下发短信CMPP2.0 的完整业务流程3.1 提交短信 CMPP_SUBMIT字段与编码连接建立后真正干活的是 CMPP_SUBMIT。这条消息决定了短信能不能被网关正确接收、按什么编码发送、要不要回状态报告。我先把关键字段列出来再说怎么填。字段含义填法Msg_Id消息编号请求时填 0响应时由网关生成Pk_total拆分总条数不拆分填 1Pk_number当前条序号从 1 开始Registered_Delivery是否需要状态报告要状态报告就填 1否则 0Msg_Fmt内容格式0 ASCII、3 GBK、4 UCS2Msg_Content短信内容按编码后的字节Msg_Length内容字节数用字节长度不是字符数提交流程的常规顺序是把短信内容按选定编码转成字节中文我优先选 UCS2避免 GBK 在部分网关上二次转码出乱码。填充目标号码。联调初期我建议一个包只发一个号码跑通后再放开批量目标号码否则多号码的字节排列规则会干扰问题定位。设置 Registered_Delivery1。不然后续没有投递状态对账很难受。拼装消息头和消息体按 Total_Length 发送。等待 CMPP_SUBMIT_RESP检查 Result 是否为 0。注意 Result 为 0 只表示网关受理不代表用户已收到最终以状态报告为准。编码这块有个高频误用Msg_Length 的单位是字节不是字符。一个 70 字的中文短信UCS2 编码后字节数是 140如果填 70网关要么截断要么解析错乱。英文和数字混排时也要按实际字节数算不能按字符串长度塞进去。3.2 短信回执 CMPP_DELIVER 和状态报告CMPP_DELIVER 是网关主动推给 SP 的消息分两种用户回复的上行短信或者短信状态报告。区分方式是看消息内容结构状态报告有特定标志。我几乎每次都提醒新人状态报告由你在 SUBMIT 里的 Registered_Delivery 控制如果不置 1网关默认不给你报告投递到底成功失败你根本不知道。状态报告主要关注三个字段和 SUBMIT_RESP 的 Msg_Id 对应的消息编号、投递状态 stat、完成时间 doneTime。stat 常见值 DELIVRD 表示成功UNDELIV 表示失败还有 MOBILE_BLACK 这类特殊值。收到状态报告后要立刻回一个 CMPP_DELIVER_RESP结果填 0。如果迟迟不回网关会按重发策略反复推堆积的状态报告最终会压垮连接。我习惯在客户端维护一张Msg_Id - 业务单号映射表。SUBMIT_RESP 到达后记录 Msg_IdDELIVER 状态报告到达后匹配到业务单并更新数据库。即使状态报告先到、SUBMIT_RESP 后到也要允许这种时序因为 Msg_Id 是网关全局唯一可以直接做匹配。3.3 长短信与超长内容处理超过单条短信长度上限纯英文 140 字节、中文 70 字时必须拆分。拆分有两个关键动作一是把 TP_udhi 置 1告诉网关消息内容里带用户数据头二是在每条内容最前面加 GSM 03.40 的长短信 UDH 头格式类似06 05 00 03 0C 01 01其中 0C 是参考号最后两个字节分别是总包数和当前序号。拆分时三个点容易错每条可用长度要扣除 UDH 头。中文 UCS2 下每条最长 70 汉字但 UDH 头占 6 字节所以实际每条只能放 67 个汉字否则整体超 140 字节。Pk_total 和 Pk_number 要正确填等于拆分总数和当前第几条。UDH 里的参考号应由发送任务生成同一次拆分的参考号一致不同批次尽量不重复。拆分逻辑必须在字符串转成字节之后做不能在字符串层数。中英混排时按汉字个数判断会严重出错。3.4 链路检测 CMPP_ACTIVE_TESTTCP 长连接最怕空闲。网关侧有 idle 超时一段时间收不到任何字节就会断开。CMPP2.0 心跳用 CMPP_ACTIVE_TESTSP 发起网关回 CMPP_ACTIVE_TEST_RESP。我一般把心跳间隔设为 30 秒远低于常见的 60 秒或 300 秒超时既能及时感知故障又不会因为太频繁触发网关告警。心跳流程如下连接建立成功后启动定时器每 30 秒触发一次。发送 CMPP_ACTIVE_TESTSequence_Id 使用全局序列号不要重新从 1 开始。收到 RESP 记录时间。如果连续 3 次没有收到主动断开并重新执行建连、鉴权。重连成功后恢复业务发包。容易忽略的一个点如果业务消息足够频繁心跳可以不发但定时统计“距上次发包时间”的逻辑必须一直在跑。有些实现只在收到上行包时重置计时遇到长时间没有上行消息时就会误判连接健在实际链路已经断了。4. 对接 CMPP2.0 的避坑指南五次踩坑记录4.1 鉴权失败源地址与密码双方约定的坑现象CMPP_CONNECT_RESP 返回状态码不为 0客户端不断重试日志全是鉴权失败。原因最常见的是源地址位数不对、密码首尾有隐藏空格或者 Timestamp 的字节表示方式和对端不一致。隐藏空格特别坑因为你看日志看不出密码字符串末尾可能带了一个不可见字符。解决不要单方面猜先拿到网关侧日志或抓包把源地址、密码、时间戳格式逐字段核对。我的做法是写一个小工具把客户端算出的 AuthenticatorSource 和网关日志里的 16 字节用十六进制逐字节打印出来对比差一个 0x00 都能立刻看到。4.2 中文内容被截断编码和长度别算错现象短信提交成功但用户收到的内容只有前半截或者出现大量乱码。原因Msg_Length 填了字符串长度而不是编码后的字节长度或者 Msg_Fmt 填了 ASCII内容是中文。这两个错误会导致网关读取内容的字节窗口不对截断乱码随之而来。解决严格按字节长度填充。UCS2 编码下每个汉字占 2 字节GBK 下英文仍占 1 字节不要统一按 2 字节处理。把“70 字中文140 字节”和“140 字英文140 字节”写进单元测试能挡住 90% 的问题。4.3 状态报告收不到submit 里的 Registered_Delivery 没设现象短信能发出去但业务系统永远没有最终状态用户投诉后只能靠运营商后台人工查。原因CMPP_SUBMIT 里 Registered_Delivery 填了 0网关不会产生状态报告。解决把 Registered_Delivery 固定置 1。另外注意收到状态报告后要及时回 DELIVER_RESP否则网关会重复推送同一份报告造成消息堆积。联调阶段这个坑很坑因为测试号状态报告本身可能延迟你以为设置没生效其实是回执没回网关在反复重推。4.4 连接被断开心跳间隔不是越长越好现象连接空闲几分钟后再发 SUBMIT 发现 Socket 已关闭重连又要重新鉴权导致发短信延迟突然飙升。原因心跳间隔设得比网关 idle 超时还长空闲时网关先断开客户端却感知不到下次发包才暴露。解决心跳间隔设为网关超时时间的 1/3 到 1/2我常用 30 秒。注意心跳包要从业务线程之外独立发送不能指望业务包代替心跳。如果业务频率不稳定定时器里该发心跳就发心跳。4.5 重发风暴重复消息 vs sequence_number现象某个 SUBMIT 响应超时客户端重发后用户收到两条相同短信。原因客户端重发时重新分配了 Sequence_Id网关不认识它是同一笔业务于是当成新消息处理。解决客户端要做幂等。响应超时后重发同一笔业务时使用相同的 Sequence_Id同时维护Sequence_Id - 业务单号映射表收到响应后去重。网关侧可能也有基于 Sequence_Id 的去重但你不能依赖对端第一责任人是自己。5. 在没有真实网关的情况下验证你的 CMPP2.0 客户端开发阶段经常拿不到测试账号或者测试网关地址限时开放。这时自建一个模拟网关非常划算。按 CMPP2.0 规范实现最小收发就能把客户端的建连、鉴权、提交、心跳全流程跑通。5.1 自建模拟网关把协议栈跑通下面的 Python 脚本是一个最小模拟网关监听 TCP 端口收到 CMPP_CONNECT 后回成功收到 CMPP_SUBMIT 后回成功并打印消息。它不含状态报告逻辑但足够验证客户端的收发和解析。import socket, struct, threading def recv_exact(sock, n): data b while len(data) n: chunk sock.recv(n - len(data)) if not chunk: return b data chunk return data def handle_conn(conn): while True: head recv_exact(conn, 12) if len(head) 12: return total_len, cmd_id, seq_id struct.unpack(III, head) body recv_exact(conn, total_len - 12) if len(body) total_len - 12: return if cmd_id 0x00000001: # CMPP_CONNECT # 响应体Status(1) AuthenticatorISMG(16) Version(1) resp (struct.pack(III, 30, 0x80000001, seq_id) struct.pack(B, 0) b\x01 * 16 struct.pack(B, 0x20)) conn.send(resp) elif cmd_id 0x00000003: # CMPP_SUBMIT print(recv submit seq:, seq_id) # 响应体Msg_Id(8) Result(4) resp (struct.pack(III, 24, 0x80000003, seq_id) b\x00 * 8 struct.pack(I, 0)) conn.send(resp) elif cmd_id 0x00000007: # CMPP_ACTIVE_TEST # 响应体Reserved(1) resp (struct.pack(III, 13, 0x80000007, seq_id) struct.pack(B, 0)) conn.send(resp) HOST, PORT 0.0.0.0, 7900 server socket.socket(socket.AF_INET, socket.SOCK_STREAM) server.bind((HOST, PORT)) server.listen(5) while True: conn, _ server.accept() threading.Thread(targethandle_conn, args(conn,), daemonTrue).start()代码逻辑说明头部用struct.unpack(III)解析因为 CMPP2.0 是大端序。recv_exact循环读满指定字节数避免 TCP 半包问题真实客户端也应该这样做。对 CONNECT、SUBMIT、ACTIVE_TEST 分别按规范回响应。AuthenticatorISMG 我随意填了 16 字节 0x01实际网关会校验模拟器只做流程验证。版本号 0x20 是我这里用的示例请按你对端要求的版本修改。5.2 用 Wireshark 抓包重点看 TCP 负载与 TCP 层行为模拟网关跑起来后用 Wireshark 抓本机回环包过滤条件写tcp.port 7900。重点看两层。TCP 层要看有没有大量重传、乱序、窗口为 0。CMPP 业务频繁时如果发送缓冲区管理不当Nagle 算法和延迟 ACK 互相作用会出现单个提交包延迟异常上升。CMPP 层要把 TCP 负载按 12 字节头切分检查每个包的 Total_Length 是否和后续负载一致。抓包能直观看出粘包比如一个 TCP 段里带了两个 CMPP 包你的解析器必须能按 Total_Length 逐个切出来。如果解析器没有循环读 body这里就会错位导致后面的命令字全部认错。我习惯在客户端日志里同时打印“发送序列号”和“收到的响应序列号”再和 Wireshark 里的 seq_id 对上这样能快速发现错位、重复消息和响应超时。5.3 回归测试与压测验证下发的质量模拟网关只能做流程验证要验证边界问题需要设计一组用例用例验证点70 字纯中文UCS2字节长度 140不拆分71 字纯中文UCS2必须拆分Pk_total2140 字节纯英文ASCII顶格长度不拆分Registered_Delivery1模拟网关能回一条状态报告重复 Sequence_Id同一 seq 重发客户端能去重压测时要控制并发。CMPP2.0 是请求-响应式客户端在收到 SUBMIT_RESP 之前可以持续发 SUBMIT但不要无限制并发。我一般用 Token 桶限制 in-flight 数比如保持 200 个左右超过后就停止发包等响应腾出窗口。这样做能避免序列号混乱也让问题定位更容易。6. 把协议读薄一份 CMPP2.0 文档应该怎么用最后一章分享一个非常实用的进阶用法怎么把那份 PDF 变成一张能照着干的接口契约。我的做法是第一次读时做三件事。第一画状态机。CMPP2.0 本质是一个状态机等待鉴权、鉴权成功、可发送、等待响应、链路超时。不要花精力背字段先把状态转换画清楚。这样连接异常时你能马上判断是卡在鉴权还是卡在心跳。第二做参数速查表。把消息头、命令字、提交字段、响应码、超时值摘到一张 A4 纸上。现场联调时不用反复翻 PDF直接看表。比如 Status 码对照、Msg_Fmt 枚举、Registered_Delivery 取值这些都值得放在手边。第三提前写对账脚本。这是我被现实教育出来的习惯。第一次上线时我没处理状态报告短信渠道成功率全靠人工问运营几百条投诉后才意识到状态报告比发送本身重要。后来我把 Registered_Delivery 设为必填项并写了一个按 Msg_Id 聚合的小工具每天拉状态报告和发送记录做差集才真正形成闭环。第四所有重试逻辑先想幂等。无论是连接重试还是提交重试都要有全局唯一的 Sequence_Id 分配器并且重试时携带相同 ID。这个习惯让我少踩了很多次重复短信的坑也减轻了网关侧的重复判断压力。CMPP2.0 这份文档其实只定义了一件事SP 与网关之间怎么用字节流约定消息。按状态机、速查表、对账脚本三个维度去消化它就不再是厚厚的 PDF而是一张可以执行的协议契约。希望帮到你。本文还有配套的精品资源点击获取
