控制面统一鉴权，以及原生客户端需要的接口

[zhangsmallchi]

你好，想在提 PR 之前先确认两个方向。

1. 鉴权与授权集中到一处

require_admin_session 默认保护所有 /api/*，这个做法是对的。但有几处可以收紧：

• WebSocket 各自检查。 HTTP 中间件看不到 WebSocket 握手，/ws 和 softphone/ws 各自调用 auth.session(...)。新增的 WebSocket 端点如果忘了检查，就是默认开放的。
• 特殊情况写成中间件里的分支。 公开路径、引擎回调令牌和会话检查混在一个函数里，每多一种凭据就多一个分支。
• 认证即全部权限。 处理函数拿到的是会话字典而不是"这是谁"，审计日志也只能记来源地址。

提议拆成几个小 PR：

1. 一个同时处理 HTTP 和 WebSocket 的 ASGI 中间件，由 principal(scope) 统一回答"这是谁"。
2. 一张显式的凭据来源表（公开路径、引擎令牌、会话 cookie），中间件只负责分派。
3. 一个授权决策点 authorize(principal, method, path)：现有权限保持不变，未声明的路由一律拒绝。
4. 审计记录写入操作者。

如果你认可，我们就按这个顺序逐个提交 PR。

2. 原生 iOS 客户端

我们在做一个原生 iOS 客户端（CallKit、PushKit、WebRTC、原生短信彩信界面），放在独立仓库，只通过网关的 HTTP/WebSocket 接口通信，不是外部 SIP 账号。

它不上架、不提供 TestFlight，需要的人自己构建。免费 Apple ID 构建的版本只能在前台使用；锁屏来电需要构建者自己的付费开发者账号，并在自己的网关里填入自己的 APNs 密钥。

客户端需要网关提供：

• 设备令牌：长期有效、按设备签发、可撤销，以 Authorization: Bearer 发送（即第 1 节凭据来源表里的一条）。
• APNs 推送渠道：与现有通知渠道并列，使用用户自己的密钥。
• 来电标识：在呼入 INVITE 和推送里带上引擎的 UNIQUEID（X-MDD-Call-Id），让被唤醒的手机认出是同一通来电。
• 响铃查询接口：iOS 不允许用 VoIP 推送通知通话结束，App 醒来后改为查询。

想请教两点：

1. 这些接口能否分别以独立 PR 进入上游？
2. 客户端做到第一个可用版本后，你是否愿意接手这个仓库？它依赖网关，放在一起更合适，许可证与网关一致用 GPL-3.0 即可。

请看看这两个方向是否合适，谢谢。

[zhangsmallchi]

Hi, @MddIdd 不确定发帖你能不能收到通知，所以艾特提醒一下你。

另外想一起问下 #102 的方向：iOS 客户端离开局域网时也需要 TURN 中继。能否把 coturn 做成可选项，默认关闭，由用户自己决定是否启用；启用或者不启用网关有不同的行为，之后网关通过接口将配置提供给客户端或者网页软电话。这样是否引入这个外部依赖由用户决定。你觉得可以的话，我们再按这个思路改。

[MddIdd]

你好，谢谢你写得这么细，提 PR 前先来讨论这个做法很好。下面说说我的想法，供参考。

1. 统一鉴权

现状你说得没错：两个 WebSocket 端点各自调用 auth.session()，新增端点如果忘了检查就没有保护。我对四步的想法：

• 第 1 步（同时覆盖 HTTP 和 WebSocket 的 ASGI 中间件）： 我觉得很有价值，可以先做。建议顺带加上 WebSocket 握手的 Origin 校验。WebSocket 用 cookie 鉴权，如果不校验 Origin，别的网站有机会借用户的登录态连进来，放在统一中间件里一起处理比较自然。
• 第 2 步（凭据来源表）： 我也赞成。我的想法是这一步最好保持纯重构、不改变现有行为，这样审查和回归都比较轻松。测试如果能覆盖现有三种情况和 CSRF 检查，就更放心了。
• 第 3、4 步（授权决策点、审计写操作者）： 我倾向于先放一放，等设备令牌进来时一起做。目前网关只有一个管理员账号，"是谁"永远是 admin，现在加"未声明路由一律拒绝"收益不大，反而每加一个接口都要多维护一处。等出现设备令牌这第二种身份时，它就很有意义了：比如设备令牌只开放通话和短信相关的接口，审计日志也能记下是哪台设备。所以我的建议是把第 3、4 步和设备令牌放在一起，你看是否合适。

2. iOS 客户端需要的接口

我觉得分成独立 PR 进来挺好。下面是我想到的几点，供你设计时参考：

• 设备令牌：我的想法是只保存哈希，能单独撤销，最好在 WebUI 上能看到并吊销。权限范围可以按上面说的只开放客户端需要的部分。Bearer 请求可以不走 CSRF，只是要留意 cookie 会话那条路径的 CSRF 检查别受影响。
• APNs 推送：有一点顾虑想先说一下。APNs 要求 HTTP/2，现在的 requests 不支持，大概要新增 h2 或 httpx[http2]。之前的经验是，改动 control/requirements.txt 会让自动更新依赖在线 pip，国内网络下容易失败（feat(mms): gateway-side attachment conversion and composer improvements #103 遇到过）。所以我的想法是把它做成可选依赖：没装时推送渠道显示"不可用"，控制面照常启动。JWT 签名用现有的 cryptography 应该就够了。你看这样是否可行，或者你有更好的办法。
• X-MDD-Call-Id：这个会改引擎的 Asterisk 模板，模板一变，所有用户的引擎都会重建。方向上我没问题，只是我可能会和其他引擎改动攒在同一个版本里一起发，所以单独一个小 PR 会比较方便。
• 响铃查询接口：我觉得没问题，返回的内容尽量精简就好。

顺序上，我的想法大致是：鉴权第 1、2 步 → 设备令牌（含授权与审计）→ 响铃查询 → Call-Id → APNs。仅供参考，你按实际开发节奏调整也完全可以。

关于接手客户端仓库：非常感谢你的信任。坦白说，我这边暂时没有条件测试 CallKit 和 PushKit，担心接过来后维护不好，反而对用户不负责。我的想法是仓库先留在你那边，发布可用版本后我在 README 里链接过去，并注明它是社区项目。以后如果情况变了，我们再聊。

3. 关于 #102 / TURN

内置 coturn 这个方向，我目前还是有些顾虑，改成默认关闭也一样。我担心的主要不是"开没开"，而是它会改到本来就会执行的路径：

• 安装和更新时要本地构建一个基于 Docker Hub 镜像的容器。不少用户的设备连不上 Docker Hub，构建失败可能拖累整个更新。
• engine.start 里新增了网络创建，担心这个可选功能出问题时影响核心线路启动。
• IMS 那条腿的媒体地址绑定和 swu_apply_pcscf 的改动，会波及所有用户的通话。

我的一个想法是改做 "外部 TURN 服务器"设置：用户在网关里填自己的 TURN 地址和凭据（可以是自建的 coturn，也可以是任何 TURN 服务），网关通过接口把 iceServers 下发给网页软电话和 iOS 客户端。没填就保持现在的行为。这样是否引入外部依赖由用户决定，网关本身不构建、不运行、不改引擎网络，也正好符合你说的"由用户决定"。你觉得这个思路是否能满足客户端的需求？如果可以，#102 可以关掉，另开一个 PR 来做。

另外，离开局域网时也可以走 Tailscale 或 WireGuard，不需要 TURN，这个我会在文档里补充说明。

以上都只是我的想法，欢迎继续讨论，再次感谢！

[zhangsmallchi]

@MddIdd 谢谢详细的回复。这里先把 #102 的来龙去脉说清楚。

为什么需要中继

我们在做 iOS 客户端，客户端不能靠 VPN 接入内网：来电时 App 是被推送临时唤醒的，要在很短时间内直接连上网关，CallKit 才能正常响铃和接通。iOS 同一时间只能有一个 VPN，也无法保证唤醒那一刻 VPN 已经连上。所以网关必须能从公网直接访问。

信令走 HTTPS/WSS，一个端口就够了；难的是通话媒体。不用中继的话，就要把每条线路 12–60 个 RTP 端口都转发到公网：端口数量随线路增减而变，公网上任何人都能直接向 Asterisk 的 RTP 端口发包，客户端所在的网络也常常拦截高位 UDP 端口。中继让网关对外只开一个固定端口，只有拿到网关签发的临时凭据的客户端才能使用，还可以回退到 TCP/TLS。外部 TURN 在容器运行环境下访问不到内部网络上的引擎，所以需要网关自带。

为什么 #102 改了网络、加了防火墙

中继对公网开放，它就是外部进入内部的入口，必须限制它只能碰到引擎的通话媒体。engine 网络上还有 mdd-egress 的 SOCKS 端口、控制面和 AMI，所以中继不能直接加入，需要一个只有中继和引擎的专用网络，再用防火墙规则限制在 RTP 端口上。这些改动是出于安全边界，不是为了改拓扑。

针对你的三点顾虑：

1. 镜像来源。 中继镜像改在 release 流程里和其他组件一起构建，发布到 ghcr 和 release 附件，不再在用户机器上从 Docker Hub 构建。coturn 今年更新很频繁，其中有安全修复，也有默认行为的变化，所以版本按摘要固定，只用一小组稳定的配置项。版本升级和相关测试由我们来跟。
2. 网络。 媒体网络只给名字，不指定网段，由 Docker 自动分配，不会和已有网段冲突，也不需要用户配置。中继启动时读取自己网卡所在的网段作为允许转发的范围；引擎不需要知道这个地址，也不再分配固定 IP。engine.start 只是把引擎接入这个网络（和现在接入 uplink 的写法一样）。媒体网络和中继镜像在安装和更新时准备，失败会在那里明确报错；运行中中继不可用时，线路的注册和短信照常，通话会明确提示中继不可用，不会回退到对外发布端口。引擎原有的网络、默认路由和 SWU_SOURCE 都不变，SWu 注册不受影响。
3. IMS 侧。 运营商那一侧只能经引擎内部的 IPsec 隧道到达，中继碰不到，所以 IMS 的 RTP 绑定和对 swu_apply_pcscf 的依赖都去掉。

我们建议中继默认开启：开启后引擎不再需要对外发布 RTP 端口段，所有外部媒体都只能经过一个需要凭据的入口，这本身就是一次权限收紧。

中继不可达时的提示 #102 里已经实现了：浏览器连不上中继，8 秒内结束呼叫并说明原因。这也顺带解决了现在的一个假象：VoWiFi 显示已注册，但 RTP 端口不可达时没有任何提示，用户只看到通话失败，不知道问题出在哪。

提 PR 前我们会在测试机上验证注册、重新接入和通话。

你看这个方向可以的话，我们就关掉 #102，按这个范围重新提。

[MddIdd]

谢谢解释得这么清楚，推送唤醒和 VPN 冲突这一点我之前确实没考虑到，远程媒体需要一个公网可达的入口，这点我认同。

在决定具体做法之前，想和你一起把几种可能的方案比较一下，看看哪种对客户端和对网关用户都比较合适。

先补充一个情况： 现在引擎的 RTP 端口本来就发布在主机上（[ice_host_candidates] 把容器地址改写成主机的局域网 IP）。所以公网上的 TURN 确实访问不到引擎，但局域网内的 TURN 是可以访问到的，比如跑在网关主机本机、NAS 或 OpenWrt 路由器上的 coturn。这样一来，可选的路就不止内置中继一条了。

我目前想到的几种：

1. 直接转发 RTP 端口段。 网关增加一个"公网地址"设置，让 Asterisk 在 ICE 候选里报出公网 IP 或域名，用户在路由器上转发各线路的 RTP 端口段。网关改动最小，但你提到的问题都在：端口多、对公网开放、只有 UDP、容易被拦。另外一条映射只能报一个地址，局域网内的使用也会受影响。
2. 用户自建 TURN，网关只下发配置。 用户在局域网里自己跑 coturn，网关增加"TURN 服务器"设置，通过接口把 iceServers 和临时凭据（TURN REST 共享密钥方式）发给网页软电话和 iOS 客户端。路由器只转发一个端口，也有 TCP/TLS 回退。网关不用引入新组件，但部署和访问限制（allowed-peer-ip 等）要靠用户自己做好。
3. 网关内置中继（你的方案）。 体验最好、默认最安全，代价是网关多一个组件和一个网络。
4. 音频也走 HTTPS 那一个端口。 控制面把 WebSocket 音频桥接到 Asterisk（例如 AudioSocket），只需要一个 443 端口。不过这会走 TCP，客户端也要自己处理音频，我觉得不太划算，列出来只是为了完整。

我现在的初步想法是，可以先从方案 2 开始（顺带把方案 1 的公网地址设置做了）：改动小，不引入新组件，iOS 客户端先用起来，也能积累真实的使用反馈；以后如果发现很多用户部署 TURN 有困难，再考虑把中继内置进网关。那时现有的接口（凭据下发、iceServers）都能直接复用，不会白做。

当然，你们实际做了客户端，对使用场景比我了解，所以想先听听你们的意见：

• 方案 2 能否满足 iOS 客户端的需求？有没有我没想到的障碍？
• 你们预期的使用者是偏会折腾的用户，还是希望普通用户也能开箱即用？
• 如果你们仍然觉得内置中继更合适，我也愿意继续讨论。那样的话我会有几点想法，比如：先默认关闭、准备失败时降级而不是中断更新、媒体网络设为 internal、防火墙规则按各线路实际的端口段生成，以及在 Pi 上实测资源占用。到时候再细聊。

另外，不管最后选哪种方案，既然网关要对公网提供服务，我觉得 #134 里鉴权的第 1、2 步最好先合入，你觉得呢？

再次感谢！

[zhangsmallchi]

@MddIdd 鉴权第 1 步已提交：#178（统一的 ASGI 中间件同时覆盖 HTTP 和 WebSocket，并按你的建议加了 WebSocket 握手的 Origin 校验）。第 2 步（凭据来源表，纯重构）和设备令牌（含授权与审计）已经在本地做好并测试，等 #178 合并后按顺序逐个提交。

[zhangsmallchi]

@MddIdd 谢谢把几种方案列得这么清楚。你说得对，局域网内的 TURN 是能访问到引擎的，我们之前那句说法不准确。

我们倾向方案 3（内置中继）。 理由主要是两点：

外部部署拿不到 Docker 原生部署的安全边界。 中继只要被拿到凭据，就能替人访问它能到达的地址。内置时，中继只在一个 internal 的媒体网络上，只看得到引擎。外部 TURN 最多只能限制到"只能转发到网关主机"，端口级的限制 coturn 本身做不到，只能由用户在 TURN 所在机器上手写防火墙，并随线路增减手动维护，配错就是一个通往局域网的开放中继。
既然项目选择了 Docker，目标就是开箱即用。 让用户另外部署和维护一套 TURN，和这个初衷相反。
凭据下发和 iceServers 接口两种方案是共用的。内置中继做完之后，如果有用户需要外部 TURN，只是在设置里多一个选项，到时候再加也不会白做。

我们考虑在方案3的基础上增加两种模式的选择：

网关增加一个媒体模式设置，默认是直连，也就是现在的行为，代码路径完全不变。启用中继后，按中继的前提把直连需要的补丁都去掉：

引擎不再发布任何端口；
所有引擎用同一个固定的 RTP 范围（各自在媒体网络上有独立地址，不需要再按线路错开）；
Asterisk 不再改写 ICE 候选地址，直接报媒体网卡的地址；
中继的防火墙只有一条固定规则：只允许 UDP 发往媒体网段的这个范围，不随线路增减变化。
网页软电话和 iOS 客户端从同一个接口取媒体配置：直连时返回空的 iceServers，中继时返回中继地址和临时凭据，客户端只有一条代码路径。

切换

切换由安装脚本完成，WebUI 上只显示当前模式和中继状态。因为端口发布在创建容器时就定了，切换需要重建所有引擎，线路会重新注册；另外还涉及建网络、拉镜像、放行端口，这些本来就是安装脚本的事。

启用时先准备、验证，再切换：创建媒体网络、拉取镜像、生成密钥、启动中继并通过健康检查，全部成功后才写入设置并依次重建引擎。任何一步失败都会清理掉已做的部分，保持直连模式，报出原因后退出，不会留下半套中继。关闭时反过来，删除中继、恢复端口发布。线路原有的端口分配一直保留，切回直连不需要重新分配。

降级

更新时： 只有启用了中继才拉取中继镜像。拉取失败就继续用旧镜像，更新照常完成，并提示没有拿到新版本。
运行中： 控制面对中继做健康检查，挂了自动拉起。恢复不了时，引擎照常运行，注册和短信不受影响；线路状态显示中继不可用及原因，客户端在拨号前就能拿到明确提示。这时不会回退到对外发布端口，避免在用户不知情时放宽暴露面。
路由器没有转发端口这类网关自己查不到的情况，由客户端提示。浏览器连不上中继时 8 秒内结束呼叫并说明原因，这在 #102 里已经实现了。它也顺带解决了现在的一个假象：VoWiFi 显示已注册，但 RTP 端口不可达时没有任何提示，用户只看到通话失败。

另外两点：媒体网络设为 internal，不指定网段，由 Docker 分配；目前我手头没有 Pi，无法在 Pi 上实测资源占用。根据预估，中继模式不会带来太多资源占用，可以并行测试一段时间的之后，再考虑两种模式的去留。

关于鉴权： 第 1 步已经提交在 #178，第 2 步（凭据来源表）会在它之后提交。中继和客户端的接口都排在这两步后面。

再次感谢！

[MddIdd]

谢谢，这版设计很清楚。"直连 / 中继"两种模式各走各的代码路径，默认直连、行为不变，切换时先准备、验证，失败就清理，这几点我都很认同。方向上我没有问题，可以按这个思路来做。#178 我会尽快看。

下面几点想法，供实现时参考：

1. 防火墙放在哪一侧
我看了一下引擎模板，AMI 监听在 0.0.0.0（manager.conf），SIP 5060 UDP 也是 0.0.0.0。引擎接入媒体网络后，拿到凭据的人就能经中继把包发到这些端口。所以这条规则其实是整个方案里最关键的安全边界。

我的想法是把规则放在引擎一侧：引擎本来就有 NET_ADMIN，在媒体网卡上只放行 RTP 范围的 UDP，其他一律丢弃。这样对公网开放的中继容器不需要 NET_ADMIN，即使它出了问题也改不了规则。coturn 这边再加上 no-tcp-relay，用 allowed-peer-ip/denied-peer-ip 限定只能转发到媒体网段，形成两层保护。你看是否可行？

2. ICE 候选和 IMS 那条腿
引擎会同时有引擎网络、媒体网络和 IPsec 隧道三个网卡。希望能确认 WebRTC 那条腿只报媒体网卡的地址，IMS 那条腿仍然走隧道、完全不受影响。最好在测试里覆盖。

3. 切换脚本
希望原生安装和容器安装两种部署方式都能支持模式切换。

4. 资源实测
测试设备我这边有，PR 提上来后我来实测空闲和通话时的资源占用，你们不用为此担心。

顺序上就按你说的来：#178 → 凭据来源表 → 设备令牌 → 中继和客户端接口。再次感谢！