企业官网建设流程全解析

• WebRTC
• 音视频
• 即时通讯
• 通信

本文以 Pion WebRTC 仓库中的 examples/ice-restart 示例为主体，完整讲解如何运行一个可随时触发 ICE Restart 的浏览器↔Go 端到端 WebRTC 演示：从克隆仓库、go run启动、浏览器打开页面，到 ICE 连接状态、选中候选对（Selected Pair）与数据通道消息的观察方式。同时结合仓库源码，深入剖析iceRestart: true从浏览器createOffer到 Pion 侧CreateOffer、ICETransport.restart()的完整调用链，帮助读者理解 ICE Restart 的底层原理，并掌握将其落地到真实应用中的关键细节。

一、示例概览：这个 demo 到底演示了什么

ice-restart是 Pion WebRTC（v4，即github.com/pion/webrtc/v4）官方仓库中专门用于演示ICE Restart 能力的最小可运行示例。与仓库中其他示例不同，它不是一个纯 Go 的"pion-to-pion"程序，而是一个浏览器（HTML/JS）与 Go 进程混合架构的端到端演示：

• 浏览器端（examples/ice-restart/index.html）创建RTCPeerConnection，与 Go 进程建立对等连接；
• Go 端（examples/ice-restart/main.go）同时充当HTTP 静态文件服务器和WebRTC 信令服务端，为页面提供资源并通过/doSignaling接口完成 SDP 交换。

页面加载后会自动建立 PeerConnection，随后用户可以随时点击ICE Restart按钮，触发一次携带iceRestart: true的新 Offer 协商，从而在不断开既有媒体/数据通道的前提下更换 ICE 传输凭证、重新进行候选收集与连通性检查——这正是 ICE Restart 在实际生产中的典型用途：网络切换、链路劣化或 NAT 绑定过期时，无需重建整个 PeerConnection 即可恢复连接。

读完本文，你将掌握：

1. 如何在本地一键运行该示例并观察 ICE 状态变化；
2. 浏览器createOffer({iceRestart: true})与 PionOfferOptions.ICERestart的对应关系；
3. Pion 内部CreateOffer→ICETransport.restart()→agent.Restart()→ 重新Gather()的完整实现路径；
4. 单次信令交换场景下GatheringCompletePromise的作用与取舍。

二、运行步骤：三步跑起这个 demo

原文档明确指出，本示例必须克隆整个仓库后才能运行，因为 Go 进程依赖http.FileServer(http.Dir("."))把示例目录下的静态 HTML 作为根目录对外提供。

1. 获取仓库并进入示例目录

git clone https://gitcode.com/gh_mirrors/we/webrtc.git cd webrtc/examples/ice-restart

说明：由于示例通过相对路径"."提供静态文件，直接在任意目录单独拷贝index.html与main.go也会正常工作，只要go run时index.html与main.go位于同一目录即可。最稳妥的方式仍是克隆整个仓库，保证依赖版本（go.mod 中的pion/webrtc/v4）与示例一致。

2. 启动 Go 进程

go run *.go

该命令会编译并启动 main.go。程序入口逻辑如下（main.go#L80-L87）：

func main() { http.Handle("/", http.FileServer(http.Dir("."))) http.HandleFunc("/doSignaling", doSignaling) fmt.Println("Open http://localhost:8080 to access this demo") panic(http.ListenAndServe(":8080", nil)) }

即：根路径提供静态文件，/doSignaling处理信令 POST 请求，服务监听:8080。终端会打印Open http://localhost:8080 to access this demo。

3. 打开浏览器页面

访问 http://localhost:8080。页面 JavaScript（index.html#L84）会在加载时立即调用window.doSignaling(false)，自动发起一次不带 ICE Restart 的常规 Offer/Answer 协商，因此无需任何手动操作，PeerConnection 就会建立。

三、页面交互与四个观察维度

页面布局非常简单（index.html#L10-L22），包含一个按钮和三个信息展示区，对应原文档列出的四个观察点：

3.1 ICE Restart 按钮的前端实现

按钮直接调用window.doSignaling(true)（index.html#L11）。该函数是核心：

window.doSignaling = iceRestart => { pc.createOffer({iceRestart}) // 关键：iceRestart: true/false .then(offer => { pc.setLocalDescription(offer) return fetch(`/doSignaling`, { // POST 给 Pion 信令端 method: 'post', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(offer) }) }) .then(res => res.json()) // 拿回 answer SDP .then(res => pc.setRemoteDescription(res)) .catch(alert) }

值得注意的细节是：createOffer({iceRestart})传入的就是布尔值本身——页面首次加载时iceRestart为false（正常建连），点击按钮后为true（执行 Restart）。这是 WebRTC 规范中标准的 ICE Restart 触发方式：在已有连接上重新发起携带ice-ufrag/ice-pwd变化的 Offer。

3.2 ICE Connection States 的记录

页面通过pc.oniceconnectionstatechange回调把每一次状态迁移追加到页面中：

pc.oniceconnectionstatechange = () => { let el = document.createElement('p') el.appendChild(document.createTextNode(pc.iceConnectionState)) document.getElementById('iceConnectionStates').appendChild(el); }

配合 Pion 侧同样注册的OnICEConnectionStateChange（main.go#L29-L31）打印到终端，可以同时从浏览器控制台与 Go 进程两端交叉验证 ICE 连接状态机。

3.3 ICE Selected Pairs 的读取方式

示例展示了如何通过标准浏览器 API 获取当前选中的候选对：

dc.onopen = () => { setInterval(function() { let selectedPair = pc.sctp.transport.iceTransport.getSelectedCandidatePair() el.innerHTML = `<div> <ul> <li><i> Local</i> - ${selectedPair.local.candidate}</li> <li><i> Remote</i> - ${selectedPair.remote.candidate}</li> </ul> </div>` document.getElementById('iceSelectedPairs').appendChild(el.content.firstChild); }, 3000); }

每次点击ICE Restart后，新收集的候选对中uFrag、uPwd以及传输端口都会发生变化——这正是原文档强调的观察点，也是 ICE Restart 生效的直观证据。uFrag/uPwd是 ICE 凭证（用于 STUN 连通性检查的认证），ICE Restart 的核心动作之一就是替换这两组凭证（详见下文源码剖析）。

3.4 Inbound DataChannel Messages

Pion 进程在收到浏览器创建的 DataChannel 后，会每 3 秒通过d.SendText(time.Now().String())发送一次当前时间（main.go#L34-L42），浏览器通过dc.onmessage将其展示在页面上：

dc.onmessage = event => { let el = document.createElement('p') el.appendChild(document.createTextNode(event.data)) document.getElementById('inboundDataChannelMessages').appendChild(el); }

实验要点：在点击 ICE Restart 前后观察这条消息流。若消息持续到达而从未断开，就证明 Restart 没有中断既有连接——这是 ICE Restart 与"重建 PeerConnection"最本质的区别。

四、Go 端信令处理：一次协商的完整流程

Pion 侧的信令入口是/doSignaling，对应 main.go#L19-L78 的doSignaling函数。一次完整协商分为以下步骤：

步骤 1：惰性创建 PeerConnection

首次请求时创建连接并注册回调（main.go#L22-L43）：

if peerConnection == nil { if peerConnection, err = webrtc.NewPeerConnection(webrtc.Configuration{}); err != nil { panic(err) } // 监听 ICE 连接状态变化 peerConnection.OnICEConnectionStateChange(func(connectionState webrtc.ICEConnectionState) { fmt.Printf("ICE Connection State has changed: %s\n", connectionState.String()) }) // 浏览器创建 DataChannel 后，每 3 秒发送一次当前时间 peerConnection.OnDataChannel(func(d *webrtc.DataChannel) { d.OnOpen(func() { for range time.Tick(time.Second * 3) { if err = d.SendText(time.Now().String()); err != nil { panic(err) } } }) }) }

注意这里使用空配置webrtc.Configuration{}——示例刻意没有配置 STUN 服务器，因此 Pion 侧只产生 host 候选，依靠浏览器侧配置的stun:stun.l.google.com:19302（index.html#L25-L31）来发现公网地址。在局域网演示环境下，双方 host 候选即可直连。

步骤 2：解析浏览器 Offer 并设置远端描述

var offer webrtc.SessionDescription if err = json.NewDecoder(req.Body).Decode(&offer); err != nil { panic(err) } if err = peerConnection.SetRemoteDescription(offer); err != nil { panic(err) }

浏览器 POST 上来的是完整的 Offer JSON，Pion 直接反序列化为webrtc.SessionDescription并调用SetRemoteDescription。

步骤 3：等待 ICE 收集完成并生成 Answer

gatherComplete := webrtc.GatheringCompletePromise(peerConnection) answer, err := peerConnection.CreateAnswer(nil) if err != nil { panic(err) } else if err = peerConnection.SetLocalDescription(answer); err != nil { panic(err) } <-gatherComplete // 阻塞直到 ICE Gathering 完成 response, err := json.Marshal(*peerConnection.LocalDescription()) // ... 以 application/json 返回给浏览器

这段代码蕴含一个重要的架构取舍（main.go#L54-L67）：示例使用GatheringCompletePromise阻塞到所有 ICE 候选收集完成后才一次性返回 Answer，即禁用了 trickle ICE，因为信令往返只有一次请求。原文档未展开说明，但这一点对理解示例限制至关重要——仓库在 gathering_complete_promise.go 的注释中明确告诫：

GatheringCompletePromise是 Pion 特有的辅助函数，返回一个在收集完成时关闭的 channel；它适用于无法 trickle ICE 候选的场景。但不建议使用它，而应优先 trickle 候选；使用它会带来更长的建连时间（连接建立后无影响）。

该函数还处理了一个边界情况（gathering_complete_promise.go#L20-L26）：由于 handler 注册是原子操作，可能在收集已经完成后才创建 Promise，因此它会额外检查pc.ICEGatheringState() == ICEGatheringStateComplete以立即关闭 channel，避免调用方被永久阻塞。

在生产应用中，标准做法是改用OnICECandidate逐个向远端推送候选（即 trickle ICE），以缩短建连延迟。

五、源码级剖析：iceRestart: true在 Pion 内部做了什么

这是理解本示例技术价值最深的一层。从浏览器点击按钮到 Pion 生成携带新凭证的 Offer，调用链如下。

5.1 浏览器侧：createOffer({iceRestart: true})

浏览器按照 WebRTC 规范在 Offer 中携带新的ice-ufrag/ice-pwd，并通过/doSignaling把该 Offer 发给 Pion。

5.2 Pion 侧：OfferOptions.ICERestart的语义

Pion 在 offeransweroptions.go 中定义了OfferOptions：

// OfferOptions structure describes the options used to control the offer // creation process. type OfferOptions struct { OfferAnswerOptions // ICERestart forces the underlying ice gathering process to be restarted. // When this value is true, the generated description will have ICE // credentials that are different from the current credentials ICERestart bool }

源码注释直接点明了本示例的观察结论：ICERestart为 true 时，生成的 SDP 中 ICE 凭证（uFrag/uPwd）必然与当前凭证不同。这就是上一节页面中候选对里uFrag/uPwd发生变化的原因。

5.3CreateOffer中的分支处理

在 peerconnection.go#L701-L714 中，CreateOffer首先检查选项：

func (pc *PeerConnection) CreateOffer(options *OfferOptions) (SessionDescription, error) { useIdentity := pc.idpLoginURL != nil switch { case useIdentity: return SessionDescription{}, errIdentityProviderNotImplemented case pc.isClosed.Load(): return SessionDescription{}, &rtcerr.InvalidStateError{Err: ErrConnectionClosed} } if options != nil && options.ICERestart { if err := pc.iceTransport.restart(); err != nil { return SessionDescription{}, err } } // ... 后续按现有 transceiver 状态生成 matched/unmatched SDP }

即：只要ICERestart为 true，Pion 会在生成 Offer 之前先对 ICE 传输层执行一次 restart。注意它发生在 SDP 生成之前，所以后续构建出的 SDP 自然携带了全新的 ICE 凭证与重新收集的候选。

5.4ICETransport.restart()的实现

真正执行 restart 逻辑的是 icetransport.go#L213-L230：

func (t *ICETransport) restart() error { t.lock.Lock() defer t.lock.Unlock() agent := t.gatherer.getAgent() if agent == nil { return fmt.Errorf("%w: unable to restart ICETransport", errICEAgentNotExist) } if err := agent.Restart( t.gatherer.api.settingEngine.candidates.UsernameFragment, t.gatherer.api.settingEngine.candidates.Password, ); err != nil { return err } return t.gatherer.Gather() }

这段代码拆解后包含三个关键动作：

1. 取得底层 ICE agent：若 transport 尚未初始化（agent == nil），返回errICEAgentNotExist错误，这是 restart 失败的一种典型情况；
2. 调用agent.Restart(uFrag, uPwd)：向底层 ICE agent（来自 Pion 的ice传输库）传递新的凭证片段与密码，促使 agent 生成新的 uFrag/uPwd 并重置连接性检查状态；
3. 重新触发t.gatherer.Gather()：立即开始新一轮 ICE 候选收集，为重新协商准备全新的候选集合。

这三步合在一起，就是"ICE Restart"在 Pion 实现中的全部本质：换凭证 + 重收集 + 重新跑连通性检查，而 PeerConnection、DTLS 传输和 DataChannel 本身都原样保留，因此媒体与数据通道不会中断。

5.5 与常规 Offer 的区别

对比页面首次加载时的doSignaling(false)：ICERestart为 false 时CreateOffer不会触碰 ICE transport，直接基于现有传输与 transceiver 状态生成 Offer。只有在连接已经建立、希望更换 ICE 凭证时才需要传true。这一设计使得同一套信令代码既能承担"初始建连"又能承担"连接恢复"两种职责——本示例正是通过复用同一个doSignaling接口做到了这一点。

六、实战要点与常见注意事项

基于以上运行与源码分析，整理出将该示例能力落地到真实项目时的几个关键点：

1. ICE Restart 不重建连接：Restart 只更换 ICE 凭证并重新收集候选、重新执行连通性检查，DTLS/媒体/数据通道状态全部保留。页面中持续不断的数据通道消息就是最直接的验证。
2. uFrag/uPwd/Port 变化是生效标志：Restart 后新的 Selected Pair 中，本地与远端候选的uFrag、uPwd及端口都会改变；若观察不到变化，说明 Restart 未按预期触发（常见原因：createOffer未传iceRestart: true，或 Pion 侧OfferOptions.ICERestart未生效）。
3. 单次信令的限制：本示例因只有一次信令往返而禁用了 trickle ICE（GatheringCompletePromise），代价是建连时间变长。生产环境应改用OnICECandidate逐个推送候选（main.go#L64-L67 注释也明确提示了这一点）。
4. 连接状态迁移可观察：Restart 过程中ICEConnectionState会依次经历connected→checking→connected等迁移，示例同时在浏览器页面与 Go 终端（main.go#L29-L31）打印，便于调试真实网络的切换场景。
5. 触发时机由业务决定：示例把触发权交给用户手动点击，实际产品中通常由网络探测逻辑自动触发，例如检测到远端候选变化、连通性超时或网络类型切换时再发起 Restart。

七、小结

examples/ice-restart是理解 Pion WebRTC ICE Restart 能力的最佳切入点：它用最少的代码打通了"浏览器发起 → Go 信令应答 → 凭证更换 → 候选重收集"的完整链路，并以页面上的四个实时观察区提供了直观的验证手段。结合 offeransweroptions.go、peerconnection.go#L701-L714、icetransport.go#L213-L230 与 gathering_complete_promise.go 四份源码，读者可以完整掌握 ICE Restart 从 API 到 ICE agent 的实现路径，并据此在自己的应用中实现网络切换场景下的连接无缝恢复。

• WebRTC
• 音视频
• 即时通讯
• 通信