简介SIP注册是SIP用户代理UA向服务器表明在线状态和可达性的关键信令过程也是VoIP客户端开发的基础环节。这份资源聚焦SIP注册到服务器的完整实现面向使用osip/eXosip协议栈的C语言开发者配套讲解eXosip2-3.6.0中MD5加密验证的认证机制。压缩包内包含SipClient与SipServer两套示例工程覆盖UA启动、构造REGISTER请求、MD5摘要认证、服务器校验、200 OK响应及Expires续约的完整链路可帮助理解REGISTER头域构造和401重试逻辑。资源共8个文件以C源码cpp为主配合dsp/dsw工程文件与7z压缩包整体仅222KB轻量易用。已有1567人学习下载。通过示例工程可直接编译运行观察eXosip_init、eXosip_build_register、eXosip_set_credentials等核心API的调用方式为后续开发可靠的VoIP通信应用提供参考。1. SIP 注册流程到底在做什么别把它当成一次普通心跳凌晨两点分公司四十几部 SIP 话机在话务台上同时变灰页面里一片“未注册”。做 VoIP 运维的多少都见过这种场面问题往往不出在拨号而出在最容易被忽略的 sip 注册流程。终端作为客户端必须周期性地把“我在哪、还能不能找到我”上报给服务器只有成功注册到服务器分机才会被路由找到。这篇文章把注册流程里的消息交互、鉴权计算、参数边界、服务端接收习惯连同常见故障一起拆开适合正在接话机、软交换或安防 SIP 设备的工程师。看完你至少能把“注册失败”从黑匣子变成一张可以逐行检查的清单。2. 把注册流程拆开看REGISTER、401 与摘要鉴权计算2.1 三次消息的“标准剧本”注册不是一问一答SIP 注册表面上只是发一个 REGISTER但它最常见的完整序列是三次交互而不是一次请求一次响应。UA话机、摄像头、软终端先发一条不带凭据的 REGISTER服务器用 401 Unauthorized 回绝同时在 WWW-Authenticate 头里给出 realm 和 nonceUA 收到挑战后用账号密码算出摘要再发第二条带 Authorization 的 REGISTER服务器校验通过后回 200 OK这条链路才算建立。如果中间还隔着一层 SIP 代理你还会遇到 407 Proxy Authentication Required。它要求的是 Proxy-Authorization而不是 Authorization。很多自研终端只处理 401对接第三方平台时报 407第一反应往往是“服务器拒绝”其实只是认证层级不同。处理方式是把第二条 REGISTER 里的认证头换成 Proxy-Authorization流程完全对称。为什么不能一次 REGISTER 直接带密码因为 SIP 摘要鉴权从一开始就不允许在网络里传明文。服务器给一个一次性 nonceUA 把账号、realm、nonce、密码、请求方法、URI 一起做 MD5服务器拿到结果后用自己存的密码做同样计算再比对。密码始终没有经过链路这是比 HTTPS 更古老但依然可靠的挑战应答思路。2.2 摘要鉴权nonce、realm、MD5 怎么拼SIP 的摘要鉴权与 HTTP Digest 基本同源。标准公式分三步。第一步算 HA1MD5(username:realm:password)。 第二步算 HA2MD5(method:request-uri)这里 method 是 REGISTERuri 是 REGISTER 里的 Request-URI比如sip:sip.example.cn。 第三步拼 response分两种情况。无 qop 时MD5(HA1:nonce:HA2)。带qopauth时RFC 3261 规定的是MD5(HA1:nonce:nc:cnonce:qop:HA2)nonce-count、cnonce、qop 都要拼进去。实际话机基本都会带 qop这就是为什么很多简化实现的终端对接标准服务器总在鉴权上翻车。还有两个容易踩的细节一是 nonce 是一次性的或有时间窗401 之后不能把上一次的 nonce 拿出来重放二是同一个 Call-ID 生命周期里CSeq 必须逐条递增第二条 REGISTER 不能再带 CSeq: 1。服务器看到 CSeq 没变会直接丢弃或回 500这跟鉴权正确与否无关。2.3 用 Python 模拟一次注册最小可复现的代码排查注册问题最怕被话机配置干扰。我一般会先甩开话机用一段最小 Python 脚本直接对着服务器走一遍注册流程确认服务端是好的再回头查设备配置。下面这段只依赖 Python 标准库UDP 发 REGISTER收到 401 后解析 realm 和 nonce计算摘要再重发import socket import hashlib import re import random SERVER (192.168.1.10, 5060) # 注册服务器地址和端口 DOMAIN sip.example.cn # SIP 域名通常等于 Request-URI 里的域 USER 1001 PASSWORD 123456 CALL_ID f{random.randint(10000000, 99999999)}{DOMAIN} def build_register(nonceNone, responseNone, realmNone, cseq1): branch fz9hG4bK{random.randint(100000, 999999)} auth if nonce and response: auth ( fAuthorization: Digest username{USER}, realm{realm}, fnonce{nonce}, urisip:{DOMAIN}, response{response}, falgorithmMD5\r\n ) return ( fREGISTER sip:{DOMAIN} SIP/2.0\r\n fVia: SIP/2.0/UDP 192.168.1.100:5060;branch{branch};rport\r\n fMax-Forwards: 70\r\n fFrom: sip:{USER}{DOMAIN};tag{random.randint(1000, 9999)}\r\n fTo: sip:{USER}{DOMAIN}\r\n fCall-ID: {CALL_ID}\r\n fCSeq: {cseq} REGISTER\r\n fContact: sip:{USER}192.168.1.100:5060;expires300\r\n fUser-Agent: py-sip-register\r\n fContent-Length: 0\r\n f{auth}\r\n ) sock socket.socket(socket.AF_INET, socket.SOCK_DGRAM) sock.settimeout(5) # 第一发不带凭据等服务器发 401 sock.sendto(build_register(cseq1).encode(), SERVER) data, _ sock.recvfrom(4096) print(data.decode()) # 从 401/407 响应里提取 realm 和 nonce m re.search(rrealm([^]), data.decode()) realm m.group(1) m re.search(rnonce([^]), data.decode()) nonce m.group(1) # 无 qop 的摘要计算HA1:nonce:HA2 ha1 hashlib.md5(f{USER}:{realm}:{PASSWORD}.encode()).hexdigest() ha2 hashlib.md5(fREGISTER:sip:{DOMAIN}.encode()).hexdigest() response hashlib.md5(f{ha1}:{nonce}:{ha2}.encode()).hexdigest() # 第二发带 AuthorizationCSeq 必须递增Call-ID 保持不变 sock.sendto(build_register(nonce, response, realm, cseq2).encode(), SERVER) data, _ sock.recvfrom(4096) print(data.decode())这段脚本做的事情就是话机注册到服务器的核心动作。逻辑上要注意三点第一次 REGISTER 只是诱饵真正起效的是第二次第二次必须沿用同一个 Call-IDCSeq 加一nonce 必须来自服务器刚下发的 401拿旧的拼出来的 response 在支持 nonce 时效校验的服务器上一定失败。脚本里expires300表示期望注册有效期为 5 分钟实际服务器可能通过 200 OK 里的 Expires 头把它改短或改长客户端应当以服务器返回为准。注意如果服务器直接回 200 而没回 401说明当前域名允许匿名注册或该账号在 IP 白名单里。这种情况在调试时要格外小心看起来“注册上了”其实根本没有鉴权保护。2.4 为什么很多方案里还有一个 OPTIONS 在“保活”有些人会把 REGISTER 当成心跳这是理解上的偏差。REGISTER 更新的是绑定关系告诉服务器“这个 AOR 当前对应哪个 Contact 地址”。注册到期后没有续约绑定才消失。而真正的链路保活交给 OPTIONS 或 Keep-Alive很多话机每 30 到 60 秒发一个 OPTIONS 或空 UDP 包作用是维持 NAT 映射不老化顺带让服务器知道终端还活着。排查“注册成功但过一会儿变离线”时先分清是 REGISTER 过期没人续还是 OPTIONS 探活失败被服务器判定离线方向完全不同。3. 注册参数怎么设Contact、Expires、NAT 与多账号边界3.1 Contact 里的 IP 和端口NAT 环境第一战场REGISTER 里最容易被忽略也最容易出错的是 Contact 头。它写的是“你能在哪里找到我”格式形如sip:1001192.168.1.100:5060;expires300。局域网里一切都好一旦设备在 NAT 后面问题就来了终端向外网服务器注册时Contact 里填的往往是内网 IP比如 192.168.x.x服务器之后按这个地址转发呼叫包根本到不了终端。解决思路有几条实践中我按顺序用。第一是在服务器侧开启 NAT 识别Kamailio 里常见做法是fix_nated_contact()Asterisk 的 pjsip 则通过 transport 的external_media_address和 NAT 相关参数处理第二是让终端侧配合端口映射把公网地址和端口显式填进 Contact第三是依赖 rport 机制服务器从请求来源 IP 和端口反推 NAT 映射关系Kamailio 开启add_contact_alias()后会在 Contact 里打上别名参数后续按别名路由回包。很多公网注册不成功的案例抓包一看服务器回的 200 到了但后续来话被呼到内网地址。这属于典型的“注册成功、寻址失败”本质上不是注册流程坏了而是 Contact 地址不可达。排查时第一个动作就是把客户端抓包和服务器抓包里的 Contact 值对比一遍。3.2 Expires 与刷新周期掉线的临界值注册有效期由 Expires 控制。终端在 REGISTER 的 Contact 参数里带期望值服务器允许通过 Max-Expires 和 Min-Expires 做裁剪最终生效值以 200 OK 返回的 Expires 为准。不同设备的默认值差别很大有 300 秒的有 600 秒的也有 3600 秒的。刷新时机也容易被误配。常见话机设置里“注册有效期”设了 3600但服务器的 Max-Expires 只有 300200 OK 里返回的 Expires 被改成了 300话机如果不按返回值重新安排刷新而是继续按 3600 记那么注册必然中途失效。另一个常见问题是防火墙或运营商会把长时间无流量的 UDP 会话老化掉注册周期设太长等到 REGISTER 刷新时 NAT 映射已经没了服务器回包根本到不了终端。我一般建议把常规注册周期设在 120 到 300 秒之间刷新提前量设置在有效期剩余三分之一左右。太短会让注册服务器产生大量无效负载太长在 NAT 和中间设备面前不可靠。这个参数属于低成本换来高稳定性的典型值得先调它而不是先换设备。3.3 Call-ID、CSeq 与同一账号多终端SIP 协议规定一次注册会话内 Call-ID 必须保持一致CSeq 必须逐条递增。很多终端重启后 Call-ID 会变化这没问题服务器会当作新注册处理。但如果在同一个进程内反复用新 Call-ID 重发 REGISTER有些服务器会判定为异常刷新甚至触发防注册风暴逻辑。同一账号多终端是另一个坑。服务器端常设置max_contacts1意即一个账号只允许一个 Contact 绑定。此时后注册的话机会把先注册的话机踢下线表象就是“A 机能打B 机一注册A 立刻掉线”。处理上有两种思路如果业务就是一人一号一机保持 max_contacts1 没问题如果需要分机共享账号要在服务器端放开 max_contacts 限制同时在多 Contact 之间做路由策略否则来话会被随机分发到某一台终端。3.4 密码存储与特殊字符鉴权里容易忽略的工程细节摘要鉴权虽然不传明文密码但服务器要完成校验要么存明文密码要么存 HA1。HA1 是根据username:realm:password算出来的存 HA1 的话服务器不需要知道密码本身而且在 realm 不变的情况下可以直接复用。很多企业选型时为了省事把密码明文放进数据库一旦库被拖走所有分机密码全部暴露这种习惯我建议尽早改掉。密码里的特殊字符也常让设备翻车。部分老话机在拼接 Digest 时不对 URI 里的特殊字符做转义账号密码里带、:、空格就容易算出错误的 response。规范做法是对 username 中的特殊字符做百分号编码但很多终端实现并不规范。遇到“密码明明没错却一直 401”的诡异场景先把密码改成纯字母数字试一次往往能快速定位是设备实现问题还是配置问题。4. 服务端注册接收的常见做法从 Kamailio、Asterisk 到安防平台对接4.1 注册服务器和代理服务器的角色不能混服务端接收注册时先要分清自己在扮演什么角色。Registrar 负责接收 REGISTER、维护 AOR 到 Contact 的绑定表Proxy 负责后续呼叫按这张表寻址。Kamailio、OpenSIPS 这类是独立的 ProxyRegistrarAsterisk、FreeSWITCH 则是 B2BUA注册表在各自内部维护。理解这层区别对排查很有用。比如 Kamailio 把绑定存进 location 表后续 INVITE 按 location 路由注册和代理是清晰的两段而 Asterisk 的 pjsip 里 endpoint 和 aor 绑定注册成功只是第一步还要看路由配置是否正确。很多“能注册但打不通电话”的问题本质是服务器没把注册表和路由串起来而不是注册本身失败。4.2 最小 Registrar 配置Kamailio 与鉴权模块Kamailio 的注册能力并不复杂。核心是鉴权模块和 Registrar 模块协同工作。一个最小可用的配置片段大致长这样# kamailio.cfg 注册相关片段 listenudp:0.0.0.0:5060 aliassip.example.cn request_route { if (is_method(REGISTER)) { # 先做摘要鉴权失败则下发挑战并要求重新注册 if (!auth_db_www_authenticate($td, subscriber)) { auth_challenge($td, 0); exit; } # 鉴权通过后把 Contact 写入 location 绑定表 save(location); exit; } # 非 REGISTER 请求走其他路由 ... }这段配置的逻辑核心是auth_db_www_authenticate和save(location)的组合前者从 subscriber 表里取 HA1 或密码完成摘要校验后者把 UA 的 Contact、 expires、call-id 等一并写入位置表。后续有 INVITE 到同一 AOR 时registrar 模块按 location 表找到对应 Contact呼叫才能继续。参数层面最值得注意的是auth_challenge($td, 0)第二个参数是 nonce 有效期相关策略“0”表示即刻失效每次挑战都是新 nonce。如果改成较长有效期客户端可以用同一 nonce 完成多次重试方便调试但安全性下降。4.3 Asterisk 与 FreeSWITCH想快速跑通选哪个如果只想快速验证终端注册行为Asterisk 的 pjsip 比 Kamailio 更容易上手。一个最小 endpoint 配置如下; pjsip.conf 注册相关片段 [transport-udp] typetransport protocoludp bind0.0.0.0:5060 [1001-auth] typeauth auth_typeuserpass password123456 username1001 [1001] typeaor max_contacts1 qualify_frequency30 [1001-endpoint] typeendpoint contextinternal disallowall allowulaw auth1001-auth aors1001Asterisk 里 endpoint、auth、aor 三者是分开定义的理解这一点比记命令更重要。endpoint 代表话机账号auth 存密码aor 定义这账号能注册到哪、能绑定几个 Contact。max_contacts1就是前面说的“同账号互踢”开关qualify_frequency30会让 Asterisk 每 30 秒主动发 OPTIONS 探活一旦连续没响应就标记为不可达。FreeSWITCH 的 Sofia 模块更省事默认 internal profile 就允许注册关键参数在 profile 的 XML 配置里比如auth-calls控制是否鉴权apply-register-acl控制访问白名单。查注册表现在也方便一条sofia status profile internal reg就能看到当前有多少注册绑定。4.4 安防平台对接海康平台 SIP 对接配置中的注册要点摄像头和 NVR 作为 SIP UA 注册到服务器流程跟话机一样但配置界面完全不同。海康设备对接 SIP 平台时页面上通常是 SIP 服务器地址、端口、SIP 域/服务器 ID、设备 ID、注册用户名、密码、注册有效期这几项。SIP 域和服务器 ID 一旦跟平台不一致设备会反复显示“注册中”甚至注册失败这是海康平台 SIP 对接配置里最常见的问题。安防设备和话机还有一个显著差异话机可以修改 Contact 和 Expires安防设备很多不允许细调注册周期可能固定或只能选档位。遇到这类设备注册不稳定优先调整服务器侧的 Max-Expires 去兼容设备而不是指望设备做精细配置。参数对照可以按下面这张表快速核对配置项常见取值不一致时的现象SIP 服务器地址平台 IP 或域名注册请求发不出去或超时SIP 端口默认 5060端口不对时请求无响应SIP 域/服务器 ID平台配置的域注册成功但平台侧列表为空设备 ID平台内唯一编号平台无法关联到具体设备注册密码平台生成或自定义一直 401 或鉴权失败注册有效期300-3600 秒周期过短造成注册风暴过长则离线感知延迟5. SIP 注册排查与避坑反复 401、秒掉线、NAT 端口翻车5.1 现象客户端反复 401像死循环越简单的现象越容易被误判。注册请求发出去服务器回 401客户端又发带 Authorization 的 REGISTER服务器还是回 401如此循环。原因通常有三种密码确实错了客户端没有正确处理 nonce用的还是第一次 401 里的旧 nonce服务器要求 qop 但客户端不带 qop 计算。第一种最好查第二种在自研 UA 里很常见第三种在老旧设备上较多。解决方法是抓包看第二条 REGISTER 的 Authorization 头如果 nonce 跟第一条 401 里的 nonce 一致说明客户端做了本地缓存如果 nonce 是新的但 response 依然不对多半是 qop 算法分支写错。拿 2.3 节的 Python 脚本先绕开设备能快速把责任切到设备侧还是服务端。5.2 现象注册成功但几十秒后就掉线注册返回 200 OK设备界面上能看到“已注册”但过一会又变成离线有时候还会反复横跳。最常见原因是 NAT 会话老化。终端注册成功后很长一段时间没有流量运营商或防火墙把 UDP 映射删了服务器的后续请求进不来。其次是注册周期与服务器 Max-Expires 不一致设备按自己的 Expires 设定了刷新计划但服务器实际只给了更短的有效期。解决方法是把注册周期调短到 120 到 180 秒同时开启终端侧的 NAT Keep-Alive 或 OPTIONS 周期性探活。注意别把“注册刷新”和“NAT 保活”混成一个参数两者都要有。5.3 现象局域网能注册公网注册就超时内网测试一切正常放到公网立刻失败。这类问题九成出在 Contact 和 NAT 上。终端在内网发起注册Contact 填的是内网 IP服务器回 200 能到达终端但注册完成后服务器按 Contact 去寻址时包就断了。解决方法是服务器侧开启 NAT 重写Kamailio 用fix_nated_contact()Asterisk 在 pjsip 里配置 NAT 相关参数或者在公网防火墙做端口映射后终端侧把公网 IP 和映射端口直接写进 Contact。还有一种隐蔽情况是经 SIP 代理转发代理没有开启 rport 处理回包走错路径。抓包时多看服务器的响应路径不要只看注册请求有没有发出去。5.4 现象系统时间不对导致 401/403注册鉴权里 nonce 经常带时间戳或绝对过期时间。服务器校验 nonce 时发现已经过期直接拒绝从客户端看密码没错、算法没错但就是鉴权失败。这不是玄学是设备时钟和服务器时钟偏差太大造成的。话机、摄像头这类设备长期断电后 RTC 不准很常见。解决方法是让设备启用 NTP 服务并确认服务器端 NTP 同步正常。排查这类故障最省事的方法是在服务器日志里看 nonce 校验的拒绝原因多数软交换会明确写 nonce expired而不是笼统的 auth failed。5.5 现象同一账号两台话机后注册的踢掉先注册的场景很常见行政和前台共用账号或者测试时拿两台话机用同一个账号。A 分机注册成功B 分机一上线A 分机立刻下线。原因是服务器端max_contacts1注册表只允许该 AOR 保留一个 Contact新注册会覆盖旧的。解决方法是明确业务意图一人一号就用独立账号设备数量大于账号数量且需要同时在线时把 aor 的 max_contacts 调大并按终端型号设置 contact 区分策略。这里要留意放开多 Contact 后来电会在多个终端同时振铃还是按序尝试取决于后续路由策略注册本身只是一半。6. 让注册链路更可控三个验证角度与一个压箱底习惯注册问题最难的地方在于黑匣子验证方法则要把黑匣子打开。我常用的验证有三个角度。第一是抓包验证直接在终端侧或服务器侧跑一条tcpdump -i any -s 0 -A -f port 5060重点看三条消息第一发 REGISTER 是否到达401 的 nonce 是什么第二发 REGISTER 是否带了正确的 Authorization。只要第二个 REGISTER 存在且 200 回来注册链路本身是通的后面的问题就该转向 NAT 寻址和应用层路由。第二是服务器注册表现场查验。Kamailio 用kamcmd ul.dump看 location 表Asterisk 用pjsip show contactsFreeSWITCH 用sofia status profile internal reg。这里有价值的信息不只是“有没有这条注册”还包括 Contact 地址是不是内网 IP、Expires 还剩多少秒、User-Agent 是什么。很多“在线但打不通”的案例在这个步骤就能直接看出 Contact 地址不对。第三是到期前刷新行为验证。注册成功后观察设备是否在 Expires 到期前主动重发 REGISTER以及重发时是否复用了旧 nonce。很多设备在弱网环境下刷新不及时导致注册黑洞。把刷新提前量调到合理区间后这个问题通常能稳定消失。这行干久了我养成了一个习惯凡是报注册问题的先把抓包、时钟、Contact、Expires 这四样东西摆到桌面上再谈其他。时钟不对的不谈鉴权Contact 地址不对的不谈掉线Expires 对不上不谈 NAT。按这个顺序过一遍至少七成注册问题能在十分钟内定位剩下三成也会因为排除了这些常规项而变得更好查。这习惯帮我少翻了很多车希望帮到你。本文还有配套的精品资源点击获取