VOIP 示例/库不支持自定义 SIP 域名 (AUD-6615)

[liangtea]

ADF示例路径
examples/protocols/voip

反馈内容
你好，我在使用 ESP 系列（如 ESP32-S3）进行 VoIP 功能开发时，发现目前 esp-adf的voip示例中无法单独设置 SIP 域（realm/domain），导致某些场景下无法正常使用。

在 SIP 协议 中，domain（有时称为 realm）是注册认证的重要部分，通常与 SIP 服务器地址不同。
例如：

SIP 服务器地址（proxy/registrar）：voip.example.com
SIP 域名（realm）：hotel1.sip.com

当前库似乎将 domain 固定为与服务器相同，导致以下情况无法支持：

• 服务器部署在公网 IP，但 SIP 域名不同
• 多个虚拟域名共享同一个 IP
• 运营商或 PBX 系统要求 realm 与服务器地址不同

期望行为
提供 API 或配置项，允许在初始化 VoIP 时单独设置 domain/realm，并在 REGISTER 请求的 From / To / Authorization 头中使用该域名。

复现步骤

1. 使用官方 VoIP 示例
2. 无法设置realm

技术背景

• 根据 RFC 3261，SIP REGISTER 的认证字段 realm 应该由服务器挑战响应（401/407）提供，或由客户端配置。
• 目前实现中缺少显式配置，限制了与部分 SIP 服务的兼容性。
• 在多域部署（如酒店多分店 PBX）中，域名是区分租户的重要参数。

[jimforr]

@liangtea 你好，根据查阅的资料，realm字段并非由客户端配置，客户端首次发起的REGISTER请求中不应该包含此字段

而是服务器用于标识客户端需要认证的区域，告知客户端在哪个领域进行身份验证，通过服务器回复的401 Unauthorized响应

客户端从中提取，作为构建鉴权信息（计算HA1，从而计算response）的参数，客户端再次发起的带鉴权信息的REGISTER请求中realm字段需与服务器提供的一致

针对你说的无法支持的三种情况，服务器返回的响应中携带符合预期的realm，Voip示例可以支持，我们目前的逻辑也是从服务器的401响应中提取realm，是符合协议符合预期的，且realm字段仅鉴权时使用，和From/To头无关。

不知是否能解决你的问题，或者如果你确认可以由客户端配置，是否可以提供你查阅到的文档？

[liangtea]

@jimforr 感谢回复。

我举个实际场景：在酒店应用中，像小度、天猫精灵这样的 VoIP 电话，通常都是通过同一个 IP（或域名）连接到同一个 SIP 服务器（一般是 5060 端口）。

问题是：如果没有区分机制，不同酒店的设备就会互相呼叫，而且用户名还不能重名，这显然不符合业务需求。
因此，SIP 协议中通常会通过 realm（或域） 来区分不同租户/酒店。

示例配置：

{
    "uri": "sip:1001@hotel1.sip.com",
    "server": "192.168.1.50:5060",
    "realm": "hotel1.sip.com",
    "username": "1001",
    "password": "pass1234"
}

在上面的例子中，hotel1.sip.com 与 hotel2.sip.com 是两个不同的虚拟 realm，它们共享同一台服务器（192.168.1.50:5060），但注册时通过 realm 区分用户归属的酒店。

像 Linphone 这样的客户端支持在用户名中直接携带 realm，例如 1001@hotel1.sip.com，从而实现区分。
但在 ESP-ADF 的 VOIP 示例中：

1. 用户名和密码字段不允许携带 @、# 等特殊字符（会直接报错）
2. 没有提供单独设置 realm 的接口

这就导致无法支持“同服务器多租户（多酒店）”的 SIP 注册需求。

参考 PJSIP 开源项目，它就支持显式填写 realm。例如，有人在 ESP 上移植了较旧版本的 PJSIP（[代码链接](https://github.com/kerwinpeng/pjsip-for-esp32/blob/main/pjsip/main/main.c)），在第 245 行可见：

cfg.cred_info[0].realm = pj_str(SIP_DOMAIN);

这种方式允许用户在配置中直接指定 realm，从而满足多租户的需求。

[jimforr]

@liangtea 你的需求是否为指定VOIP示例启动时注册的服务器，如若是，可尝试修改以下配置

• 在 VoIP App Configuration > SIP_URI 中配置 SIP 登陆相关信息（Transport://user:password@server:port）。
  • 例如：tcp://100:100@192.168.1.123:5060
  • 如终端房间号为1001，默认密码为123456，你想向hotel1.sip.com注册，修改SIP_URI为（tcp://1001:123456@hotel1.sip.com:5060）

[liangtea]

@jimforr 你好。需求不是你说的那样子。假设服务器的域名是：sip.example.com。
那么SIP_URI需要支持这样子：
tcp://1001@hotel1.com:123456@sip.example.com:5060
tcp://1001@hotel2.com:123456@sip.example.com:5060
以上是两个酒店，hotel1和hotel2都有1001，然后hotel1只能拨号hotel1的账号，而hotel2只能拨号hotel2的账号。

或者说可以有函数可以让我们设置realm

[liangtea]

我明白你的意思，你是想搞清楚 SIP realm 在连接认证中的作用，以及它和 SIP 服务器（5060 端口） 之间的区别。
我用通俗但准确的方式给你拆开解释一下。

---

1. SIP 服务器（5060 端口）

• 是什么：
  SIP 服务器就是运行 SIP 协议的信令服务器（常见于 Asterisk、FreeSWITCH、Kamailio 等），它通常监听 UDP/TCP/TLS 的 5060 端口 来收发信令。

• 作用：
  负责：

  • 注册（REGISTER）

  • 呼叫建立（INVITE）

  • 呼叫结束（BYE）

  • 呼叫转接等

• 地址表现：

  • 可以是 IP（192.168.1.10:5060）

  • 可以是域名（sip.example.com:5060）

这个只是“通信管道”和“接线员”，不涉及你是谁、能不能用的问题。

---

2. Realm（领域）

• 是什么：
  realm 在 SIP 中是 身份认证的作用域，主要出现在 SIP Digest 认证中。
  它是一个字符串（通常是域名形式），告诉客户端“你要在哪个身份域下验证身份”。

• 在 SIP REGISTER 时的作用：
  当你的 UA（用户代理）向 SIP 服务器注册时，如果服务器要求认证，它会返回类似：

  SIP/2.0 401 Unauthorized
  WWW-Authenticate: Digest realm="hotelA.example.com", nonce="abc123"
  

  • realm 就是 hotelA.example.com

  • UA 会用这个 realm + 用户名 + 密码 + nonce 进行哈希计算，生成 response 发回给服务器验证。

• 设计意义：

  • 可以区分不同的用户域，即使用同一台 SIP 服务器和同一个 IP，也能隔离用户组（常见于多租户系统）。

  • 同一台 SIP 服务器可以配置多个 realm，例如：

    realm = hotelA.example.com
    realm = hotelB.example.com
    

    这样 Hotel A 的设备不会和 Hotel B 的设备互通，除非显式允许。

---

3. Realm 和 SIP 服务器的区别

对比点	SIP 服务器（5060端口）	Realm（领域）
本质	一个网络地址 + 端口，负责收发信令	一个认证作用域标识字符串
作用	提供 SIP 协议服务（注册、呼叫等）	用于区分和验证用户身份
位置	网络层（IP:Port）	应用层（SIP 协议认证字段）
典型值	192.168.1.10:5060 或 sip.example.com:5060	"example.com" 或 "hotelA.example.com"
多租户作用	不直接隔离	可以逻辑隔离不同租户或业务

---

4. 举个酒店场景例子

假设你有一台 SIP 服务器，IP 是 203.0.113.10:5060，上面跑着 FreeSWITCH，接入两家酒店：

• Hotel A → realm: hotelA.example.com

• Hotel B → realm: hotelB.example.com

即使它们都连接同一个 203.0.113.10:5060，
但注册的时候：

• Hotel A 设备：

  REGISTER sip:hotelA.example.com SIP/2.0
  

• Hotel B 设备：

  REGISTER sip:hotelB.example.com SIP/2.0
  

认证时，服务器根据 realm 判断它是哪个酒店的账号，然后限制呼叫只在本 realm 内互通，这样避免了“跨酒店乱打电话”。

---

✅ 总结一句：

• SIP 服务器（5060） 是电话交换机的“门牌号”。

• Realm 是认证时的“房间号”，用来划分和隔离不同的用户组。

---

如果你愿意，我可以帮你画一个 SIP realm 与服务器关系图，让你直观看到两者的区别和交互过程，这样酒店多租户的场景就更容易理解了。
你要我画吗？

@jimforr 这是chatgpt的回复。

[jimforr]

@liangtea 你好，我大概理解你的需求了，以下两点满足其一即可
1.User可以支持@#符号以让服务器区分客户端属于哪个租户
2.realm可自定义配置

针对第一点chatgpt的回复：
在 SIP URI 中，username 部分通常 不能包含 @ 字符，因为 @ 是 SIP URI 的语法中用来分隔 用户标识符（username） 和 主机部分（host/domain） 的关键字符。
在 SIP URI 中，username 部分通常 不能包含 # 字符，因为 # 字符在 URI 中有特殊含义。具体来说，# 是 URI 的 分隔符，用于指示 URI 中的 fragment（片段标识符），并且其后面的内容通常是用来指定资源的特定部分或某些附加参数。

针对第二点再确认下，因为第一条注册消息不会携带realm字段，是希望收到401回复之后的第二条注册消息realm字段使用自己配置的吗？如是，我会尽快提供可修改realm的方法。

[liangtea]

@jimforr
针对第二点再确认下，因为第一条注册消息不会携带realm字段，是希望收到401回复之后的第二条注册消息realm字段使用自己配置的吗？如是，我会尽快提供可修改realm的方法。

是的。是这个意思。麻烦你了。

[jimforr]

@liangtea
有个API：esp_rtc_set_private_header 可以在header头里自定义添加字段，客户端可以使用这个API来告知服务器，服务器解析后拿去构建realm。

[liangtea]

@jimforr 谢谢回复。不过我查了下这个rtc header应该是设置不了的。可能是我描述问题，客户端应该不能叫realm，一般叫域。我们是按照你VOIP的示例用freeswitch作为服务器的，那么你那边是否可以实现这样一个非常常见的需求：两个酒店，分别叫酒店A和酒店B，A和B都有101，两个不同酒店的ESP分别注册101时，怎么告诉服务器它属于哪个酒店呢？不然服务器如何判断它是哪个酒店呢？经过我们测试，现有VOIP代码无法实现这个需求。但是Linphone（比较出名的SIP客户端，有PC端手机端），市面上的SIP VOIP电话机都能实现这个需求。比如Linphone，我的用户名填101@hotelA.com.cn，连接到freeswitch，那么101@hotelA.com.cn只可以和102@hotelA.com.cn互通，同理101@hotelB.com.cn只可以和102@hotelB.com.cn互通（注意：这里的hotelA.com.cn并不等于SIP服务器的域名或者IP，虽然他们可以一样，一样的时候就是不区分不同酒店了，就是不允许有两个101了）。

[liangtea]

这是我freeswitch的目录结构（/usr/local/freeswitch/conf/directory）：
├── hotelA.com
│   ├── 100.xml
│   ├── 101.xml
│   ├── 102.xml
│   ├── brian.xml
│   ├── default.xml
│   ├── example.com.xml
│   └── skinny-example.xml
├── hotelA.com.xml
├── hotelB.com
│   ├── 100.xml
│   ├── 101.xml
│   ├── 102.xml
│   ├── brian.xml
│   ├── default.xml
│   ├── example.com.xml
│   └── skinny-example.xml
└── hotelB.com.xml

然后在以下目录配置相应配置就可以实现多域区分不同酒店了。

@jimforr 以上是我的freeswitch的配置。配置了两个域。你是否可以用这种配置来测试一下？

[liangtea]

@jimforr 或者sip相关的库代码是否可以开源给我们去想办法修改？我们来测试。

[jimforr]

@liangtea 请稍等，我正在尝试配置不同域来测试

[jimforr]

@jimforr 谢谢回复。不过我查了下这个rtc header应该是设置不了的。可能是我描述问题，客户端应该不能叫realm，一般叫域。我们是按照你VOIP的示例用freeswitch作为服务器的，那么你那边是否可以实现这样一个非常常见的需求：两个酒店，分别叫酒店A和酒店B，A和B都有101，两个不同酒店的ESP分别注册101时，怎么告诉服务器它属于哪个酒店呢？不然服务器如何判断它是哪个酒店呢？经过我们测试，现有VOIP代码无法实现这个需求。但是Linphone（比较出名的SIP客户端，有PC端手机端），市面上的SIP VOIP电话机都能实现这个需求。比如Linphone，我的用户名填101@hotelA.com.cn，连接到freeswitch，那么101@hotelA.com.cn只可以和102@hotelA.com.cn互通，同理101@hotelB.com.cn只可以和102@hotelB.com.cn互通（注意：这里的hotelA.com.cn并不等于SIP服务器的域名或者IP，虽然他们可以一样，一样的时候就是不区分不同酒店了，就是不允许有两个101了）。

@liangtea 你好，我尝试使用linphone按照你说的配置用户名，但是无法添加账户，日志显示这个用户名组装的sip uri是个bad uri，如图所示。

在 SIP URI 中，username 部分通常 不能包含 @ 字符，因为 @ 是 SIP URI 的语法中用来分隔 用户标识符（username） 和 主机部分（host/domain） 的关键字符。
所以请问你是如何使用linphone等客户端按照你说的方式成功设置用户名的

[liangtea]

@jimforr 非常感谢你测试调试我提出的问题。

账号配置

手机端

需要在代理地址那里填写服务器IP

PC端

我的测试结果

手机配置了hotelA.com的1000，PC端配置了hotelA.com的1001。如下图所示，拨打成功。

手机配置了hotelB.com的1000，PC端配置了hotelB.com的1001。如下图所示，拨打成功。

当手机配置hotelA.com的1000，PC端配置了hotelB.com的1001。两者无法互相拨打。

Freeswitch的客户端连接信息

服务端hotelA的配置信息（hotelB一样这么配）

以下这个文件是配置在conf/diaplan的
diaplan-hotelA.com.xml
以下这个文件是配置在conf/directory的
directory-hotelA.com.xml