浏览器 WebSocket API 不支持自定义 HTTP header，这给需要通过 header 传递认证信息的语音识别服务带来了挑战。本文分享 HagiCode 项目中如何通过后端代理方案解决这个问题，以及从 playground 到生产环境的实践过程。
其实在做 HagiCode 项目的语音识别功能时，我们也是满怀信心地选择了字节跳动的豆包语音识别服务。刚开始的设计很简单嘛——前端直接连豆包的 WebSocket 服务。这有什么难的？不就是建个连接，传点数据的事儿吗？
可是吧，万万没想到——豆包的 API 要求通过 HTTP header 传递认证信息，什么 accessToken、secretKey 之类的。这下就有点尴尬了，因为浏览器的 WebSocket API 根本不支持设置自定义 header。
你说不支持怎么办嘛？
那时候也是纠结了一阵子的。毕竟摆在面前的两个选择：
第一种方案吧，凭证就直接暴露在前端代码和本地存储里了。这安全吗？反正我是不太敢苟同的。而且有些 API 必须用 header 验证，根本走不通。
最终想了想，还是选了第二种方案——在后端实现一个 WebSocket 代理。说起来也是巧合，这个方案最初是在我们的 playground 试验场里验证的，后来确认稳定了才应用到生产环境。毕竟谁也不想在生产环境当小白鼠嘛，这点儿道理我还是懂的。
本文分享的方案来自我们在 HagiCode 项目中的实践经验。
HagiCode 是一个 AI 代码助手项目，支持语音交互功能。怎么说呢，也就是因为需要在前端调用语音识别服务，我们才遇到了这个 WebSocket 认证问题，也才有了后面的解决方案。有时候想想吧，困难这东西也不是完全没有好处，至少让我们学会了用代理，不是吗？
标准 WebSocket API 看起来真的很简单：
const ws = new WebSocket('wss://example.com/ws');但问题就出在”简单”这两个字上——它只在 URL 里传递参数，没法像 HTTP 请求那样设置 headers：
// 这在 WebSocket API 里是不支持的const ws = new WebSocket('wss://example.com/ws', { headers: { 'Authorization': 'Bearer token' }});你看看，这找谁说理去？对于豆包语音识别这类需要 header 认证的服务，这个限制简直就是一道迈不过去的坎儿。
罢了罢了，又能怎样呢？
在设计方案的时候，我们也是左思右想，权衡了又权衡。
决策一：代理模式选择
我们比较了两种方案：
| 方案 | 优点 | 缺点 | 决策 |
|---|---|---|---|
| 原生 WebSocket | 轻量、简单、直接转发 | 需手动处理连接管理 | 选择 |
| SignalR | 自动重连、强类型 | 过度复杂、额外依赖 | 不选 |
最后选了原生 WebSocket。说实话，也就是因为它最轻量，适合简单的双向二进制流转发。加个 SignalR 吧，确实有点杀鸡用牛刀的感觉，而且会增加延迟——这又何苦呢？
决策二：连接管理策略
我们采用了”每连接单会话”模式——每个前端 WebSocket 连接对应一个独立的豆包后端连接。
这样做的好处也是显而易见的：
其实说白了也就是——简单粗暴有时候反而是最好的选择。复杂的方案不一定好，简单的不一定差。
决策三：认证信息存储
凭证存在后端配置文件（appsettings.yml 或环境变量）里，通过依赖注入加载：
这安全感嘛，总归是要有的。毕竟谁也不想自己的凭证满天飞，不是吗？
整体数据流是这样的：
前端 (浏览器) │ │ ws://backend/api/voice/ws │ WebSocket (二进制) ▼后端 (代理) │ │ wss://openspeech.bytedance.com/ │ (带认证 header) ▼豆包 API流程倒也不复杂，也就是这么几步：
一切看起来都是那么自然，不是吗？
app.Map("/ws", async context =>{ if (context.WebSockets.IsWebSocketRequest) { // 从查询参数读取配置 var appId = context.Request.Query["appId"]; var accessToken = context.Request.Query["accessToken"];
// 验证必需参数 if (string.IsNullOrEmpty(appId) || string.IsNullOrEmpty(accessToken)) { context.Response.StatusCode = 400; return; }
// 接受 WebSocket 连接 using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
// 消息处理循环 var buffer = new byte[4096]; while (!webSocket.CloseStatus.HasValue) { var result = await webSocket.ReceiveAsync(buffer, CancellationToken.None);
if (result.MessageType == WebSocketMessageType.Close) { await webSocket.CloseAsync( result.CloseStatus.Value, result.CloseStatusDescription, CancellationToken.None); break; }
// 处理音频数据 await HandleAudioDataAsync(buffer, result.Count); } }});public class DoubaoSessionManager : IDoubaoSessionManager{ private readonly ConcurrentDictionary<string, DoubaoSession> _sessions = new();
public DoubaoSession CreateSession(string connectionId) { var session = new DoubaoSession(connectionId); _sessions[connectionId] = session; return session; }
public async Task SendAudioAsync(string connectionId, byte[] audioData) { if (_sessions.TryGetValue(connectionId, out var session)) { await session.SendAudioAsync(audioData); } }
public void RemoveSession(string connectionId) { if (_sessions.TryRemove(connectionId, out var session)) { session.Dispose(); } }}用 ConcurrentDictionary 管理会话，线程安全也就不用操心了。每个连接进来就创建一个 Session，断开时自动清理——这大概就是所谓的”来也匆匆，去也匆匆”罢。
public class ClientConfigDto{ public string AppId { get; set; } = null!; public string Access set; } =Token { get; null!; public string? ServiceUrl { get; set; } public string? ResourceId { get; set; } public int? SampleRate { get; set; } public int? BitsPerSample { get; set; } public int? Channels { get; set; }
public void Validate() { if (string.IsNullOrWhiteSpace(AppId)) throw new ArgumentException("AppId is required"); if (string.IsNullOrWhiteSpace(AccessToken)) throw new ArgumentException("AccessToken is required"); }}配置验证嘛，也就是为了在启动时就发现问题，避免运行时出什么幺蛾子。这点儿保障还是要的。
前端和后端之间用 JSON 格式的文本消息做控制，用二进制消息传音频数据。
控制消息示例：
{ "type": "control", "messageId": "msg_123", "timestamp": "2026-03-03T10:00:00Z", "payload": { "command": "StartRecognition", "parameters": { "hotwordId": "hotword1", "boosting_table_id": "table123" } }}识别结果示例：
{ "type": "result", "timestamp": "2026-03-03T10:00:03Z", "payload": { "text": "你好世界", "confidence": 0.95, "duration": 1500, "isFinal": true, "utterances": [ { "text": "你好", "startTime": 0, "endTime": 800, "definite": true } ] }}这种设计把控制信号和音频数据分开，处理起来也是更清晰一些。有时候分而治之确实是个不错的办法。
class DoubaoVoiceClient { constructor(config) { this.config = config; this.ws = null; }
async connect() { const url = new URL(this.config.wsUrl); // 添加查询参数 Object.entries(this.config.params).forEach(([key, value]) => { url.searchParams.set(key, value); });
this.ws = new WebSocket(url);
return new Promise((resolve, reject) => { this.ws.onopen = () => { console.log('[DoubaoVoice] Connected'); resolve(); };
this.ws.onmessage = (event) => { this._handleMessage(JSON.parse(event.data)); };
this.ws.onerror = reject; }); }
_handleMessage(message) { switch (message.type) { case 'status': this._handleStatus(message.payload); break; case 'result': this.onResult?.(message.payload); break; case 'error': console.error('[DoubaoVoice] Error:', message.payload); break; } }}
// 使用示例const client = new DoubaoVoiceClient({ wsUrl: 'ws://localhost:5000/ws', params: { appId: 'your-app-id', accessToken: 'your-access-token', sampleRate: 16000, bitsPerSample: 16, channels: 1 }});用 AudioWorkletNode 做音频处理，性能也会更好一些：
class AudioProcessorWorklet extends AudioWorkletProcessor { process(inputs, outputs, parameters) { const input = inputs[0]?.[0]; if (!input) return true;
// 转换为 16-bit PCM const pcm = new Int16Array(input.length); for (let i = 0; i < input.length; i++) { pcm[i] = Math.max(-32768, Math.min(32767, input[i] * 32767)); }
this.port.postMessage({ type: 'audioData', data: pcm.buffer }, [pcm.buffer]);
return true; }}
registerProcessor('audio-processor', AudioProcessorWorklet);
// 主线程代码async function startAudioRecording() { const stream = await navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true, sampleRate: 48000 } });
const audioContext = new AudioContext(); const audioSource = audioContext.createMediaStreamSource(stream);
await audioContext.audioWorklet.addModule('/audio-worklet.js'); const audioWorkletNode = new AudioWorkletNode(audioContext, 'audio-processor');
audioWorkletNode.port.onmessage = (event) => { if (event.data.type === 'audioData' && ws?.readyState === WebSocket.OPEN) { ws.send(event.data.data); // 直接发送二进制数据 } };
audioSource.connect(audioWorkletNode);}AudioWorklet 比 ScriptProcessorNode 性能好很多，不会有音频卡顿的问题。这年代，谁还愿意听那种刺刺拉拉的噪音呢？
{ "Serilog": { "MinimumLevel": { "Default": "Information", "Override": { "Microsoft": "Warning", "System": "Warning" } }, "WriteTo": [ { "Name": "Console" }, { "Name": "File", "Args": { "path": "logs/log-.txt", "rollingInterval": "Day" } } ] }, "Kestrel": { "Urls": "http://0.0.0.0:5000" }}日志配置很重要，方便排查问题。Serilog 的 File sink 可以按天滚动，日志文件也不会太大。毕竟有些问题嘛，事后诸葛亮总是要容易一点的。
这些也就是一些基本的操作罢了。
总而言之，稳字当头。
格式不对会导致识别失败或者效果很差。这点儿规矩还是要守的。
安全无小事，且行且珍惜罢。
这些优化手段，能用上的就用上罢。
部署这事儿吧，说简单也简单，说复杂也复杂。也就是因人而异，因地制宜罢。
WebSocket 代理方案解决了浏览器 WebSocket API 不支持自定义 header 的根本问题。在 HagiCode 项目中，这个方案从 playground 验证到生产环境部署，证明了它的可行性和稳定性。
关键点总结：
如果你也在做需要 WebSocket 认证的功能，希望这个方案能给你一些启发。
有什么问题的话，欢迎来讨论。毕竟技术这东西嘛，都是在交流中进步的。
感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。
本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。