基于 SpringBoot + Vue + Netty 构建实时视频聊天系统

2. 核心实体类与消息处理器

信令消息需要包含'消息类型''发送方 ID''接收方 ID''消息内容'，所以定义对应的属性。

public class Message {
    // 消息类型：register(注册)、call(呼叫)、answer(应答)、ice(ICE 候选)
    private String type;
    // 发送方 ID
    private String from;
    // 接收方 ID
    private String to;
    // 消息内容（SDP/ICE 数据）
    private String data;
}

接下来是 Netty WebSocket 处理器，这是服务端的核心逻辑，负责处理 WebSocket 连接的建立、消息接收与转发、连接断开等事件。

import com.alibaba.fastjson.JSON;
import com.example.chat.entity.Message;
import io.netty.channel.Channel;
import io.netty.channel.ChannelHandler;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.SimpleChannelInboundHandler;
import io.netty.handler.codec.http.websocketx.TextWebSocketFrame;
import io.netty.handler.codec.http.websocketx.WebSocketServerProtocolHandler;
import org.springframework.context.annotation.Configuration;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

/**
 * 描述：WebSocket 消息处理器
 */
@Configuration
@ChannelHandler.Sharable
public class WebSocketHandler extends SimpleChannelInboundHandler<TextWebSocketFrame> {
    // 存储用户 ID 与 Channel 的映射（线程安全）
    public static final ConcurrentHashMap<String, Channel> USER_CHANNEL_MAP = new ConcurrentHashMap<>();

    @Override
    public void channelActive(ChannelHandlerContext ctx) throws Exception {
        System.out.println("与客户端建立连接，通道开启！");
    }

    /**
     * 处理接收到的文本消息
     */
    @Override
    protected void channelRead0(ChannelHandlerContext ctx, TextWebSocketFrame msg) throws Exception {
        // 解析 JSON 消息
        String text = msg.text();
        Message message = JSON.parseObject(text, Message.class);
        System.out.println("收到消息：" + text);

        switch (message.getType()) {
            case "register":
                // 注册用户 ID 与 Channel 的映射
                USER_CHANNEL_MAP.put(message.getFrom(), ctx.channel());
                System.out.println("用户 " + message.getFrom() + " 注册成功");
                break;
            case "call":
            case "answer":
            case "ice":
                // 转发消息到接收方
                Channel targetChannel = USER_CHANNEL_MAP.get(message.getTo());
                if (targetChannel != null && targetChannel.isActive()) {
                    targetChannel.writeAndFlush(new TextWebSocketFrame(text));
                    System.out.println("转发消息到用户 " + message.getTo());
                } else {
                    System.out.println("用户 " + message.getTo() + " 不在线");
                }
                break;
            default:
                System.out.println("未知消息类型：" + message.getType());
        }
    }

    /**
     * 处理连接断开事件
     */
    @Override
    public void channelInactive(ChannelHandlerContext ctx) throws Exception {
        System.out.println("与客户端断开连接，通道关闭！");
    }

    /**
     * 处理异常
     */
    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) throws Exception {
        System.out.println("连接异常：" + cause.getMessage());
        USER_CHANNEL_MAP.entrySet().removeIf(entry -> entry.getValue() == ctx.channel());
        ctx.close();
    }
}

3. Netty 服务启动与 SpringBoot 集成

我们需要在 SpringBoot 项目启动时，自动启动 Netty 的 WebSocket 服务，监听指定端口（8004）。这里使用了 CommandLineRunner 接口来确保服务在 Spring 容器加载完成后启动。

import io.netty.bootstrap.ServerBootstrap;
import io.netty.channel.ChannelFuture;
import io.netty.channel.ChannelInitializer;
import io.netty.channel.ChannelOption;
import io.netty.channel.EventLoopGroup;
import io.netty.channel.nio.NioEventLoopGroup;
import io.netty.channel.socket.SocketChannel;
import io.netty.channel.socket.nio.NioServerSocketChannel;
import io.netty.handler.codec.http.HttpObjectAggregator;
import io.netty.handler.codec.http.HttpServerCodec;
import io.netty.handler.codec.http.websocketx.WebSocketServerProtocolHandler;
import io.netty.handler.stream.ChunkedWriteHandler;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;

/**
 * Netty WebSocket 服务端
 */
@Configuration
public class NettyWebSocketServer {
    @Autowired
    private WebSocketHandler coordinationSocketHandler;

    public void start() throws Exception {
        EventLoopGroup bossGroup = new NioEventLoopGroup();
        EventLoopGroup group = new NioEventLoopGroup();
        try {
            ServerBootstrap sb = new ServerBootstrap();
            sb.option(ChannelOption.SO_BACKLOG, 1024);
            sb.group(group, bossGroup)
                    // 绑定线程池
                    .channel(NioServerSocketChannel.class)
                    // 指定使用的 channel
                    .localAddress(8004)
                    .childHandler(new ChannelInitializer<SocketChannel>() {
                        // 绑定客户端连接时候触发操作
                        @Override
                        protected void initChannel(SocketChannel ch) throws Exception {
                            // websocket 协议本身是基于 http 协议的，所以这边也要使用 http 解编码器
                            ch.pipeline().addLast(new HttpServerCodec());
                            // 以块的方式来写的处理器
                            ch.pipeline().addLast(new ChunkedWriteHandler());
                            ch.pipeline().addLast(new HttpObjectAggregator(8192));
                            ch.pipeline().addLast(new WebSocketServerProtocolHandler("/ws", "WebSocket", true, 65536 * 10));
                            ch.pipeline().addLast(coordinationSocketHandler); // 自定义消息处理类
                        }
                    });
            ChannelFuture cf = sb.bind().sync();
            // 服务器异步创建绑定
            cf.channel().closeFuture().sync();
            // 关闭服务器通道
        } finally {
            group.shutdownGracefully().sync();
            // 释放线程池资源
            bossGroup.shutdownGracefully().sync();
        }
    }
}

主启动类需要实现 CommandLineRunner 接口，以便在 Spring 启动后调用 Netty 服务。

import com.example.chat.server.NettyWebSocketServer;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.example.chat.dao")
public class Application implements CommandLineRunner {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Autowired
    private NettyWebSocketServer nettyServer;

    @Override
    public void run(String... args) throws Exception {
        nettyServer.start();
    }
}

前端开发

1. 模板结构

前端主要使用 Vue 3 进行开发，界面包括用户 ID 输入、呼叫按钮以及本地和远程视频的展示区域。

<template>
  <div class="container">
    <h2>WebRTC 视频聊天</h2>
    <!-- 1. 用户 ID 输入与连接服务器区域 -->
    <div class="input-group">
      <input v-model="userId" placeholder="输入你的用户 ID（如 user1）" type="text" />
      <button @click="connect">连接服务器</button>
    </div>
    <!-- 2. 呼叫功能区域（仅连接成功后显示） -->
    <div v-if="socketConnected">
      <input v-model="targetUserId" placeholder="输入对方用户 ID（如 user2）" type="text" />
      <button @click="call">发起视频呼叫</button>
    </div>
    <!-- 3. 挂断按钮 -->
    <div v-if="socketConnected && remoteVideo?.srcObject">
      <button @click="hangUp">挂断通话</button>
    </div>
    <!-- 4. 视频展示区域 -->
    <div class="video-container">
      <div class="video-item">
        <p>本地视频</p>
        <!-- muted：本地视频静音，避免回声；autoplay：自动播放 -->
        <video ref="localVideo" autoplay muted></video>
      </div>
      <div class="video-item">
        <p>远程视频</p>
        <video ref="remoteVideo" autoplay></video>
      </div>
    </div>
  </div>
</template>

<style scoped>
.container {
  width: 900px;
  margin: 20px auto;
  text-align: center;
  font-family: "Microsoft YaHei", sans-serif;
}
.input-group {
  margin: 25px 0;
}
input {
  padding: 10px 15px;
  width: 220px;
  margin-right: 10px;
  border: 1px solid #ddd;
  border-radius: 4px;
  font-size: 14px;
}
button {
  padding: 10px 20px;
  background: #42b983;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
}
button:hover {
  background: #359469;
}
.video-container {
  display: flex;
  justify-content: center;
  gap: 30px;
  margin-top: 30px;
}
.video-item p {
  margin-bottom: 8px;
  font-size: 16px;
  color: #333;
}
video {
  width: 400px;
  height: 300px;
  border: 1px solid #ccc;
  border-radius: 8px;
  background-color: #f5f5f5;
}
</style>

2. 核心交互逻辑

初始化与变量定义

首先导入 Vue 内置的响应式变量和生命周期钩子，定义页面用到的动态数据和 DOM 引用。

<script setup>
import { ref, onUnmounted } from 'vue';

const userId = ref('');
const targetUserId = ref('');
const socketConnected = ref(false);
const localVideo = ref(null);
const remoteVideo = ref(null);

let socket = null;
let peerConnection = null;
let localStream = null;
</script>

配置 STUN 与 WebSocket 连接

WebRTC 必须配置 STUN 服务器，否则内网设备无法找到彼此的网络地址。这里列出了几个常用的免费 STUN 服务器。

<script setup>
// 接上一步代码

// 配置 STUN 服务器
const iceServers = {
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'stun:stun.qq.com:3478' },
    { urls: 'stun:stun.aliyun.com:3478' }
  ]
};

// 连接 WebSocket 服务器函数
const connect = () => {
  if (!userId.value.trim()) {
    alert('请输入你的用户 ID！（不能为空/仅空格）');
    return;
  }

  socket = new WebSocket(`ws://localhost:8004/ws`);

  socket.onopen = () => {
    console.log('✅ WebSocket 连接成功');
    socketConnected.value = true;
    sendMessage({ type: 'register', from: userId.value, to: '', data: '' });
  };

  socket.onmessage = (e) => {
    try {
      const message = JSON.parse(e.data);
      console.log('📥 收到服务端消息：', message);
      handleMessage(message);
    } catch (err) {
      console.error('❌ 消息解析失败：', err);
    }
  };

  socket.onclose = () => {
    console.log('❌ WebSocket 连接关闭');
    socketConnected.value = false;
  };

  socket.onerror = (err) => {
    console.error('❌ WebSocket 连接错误：', err);
    socketConnected.value = false;
    alert('连接服务器失败！请检查服务端是否启动，端口是否正确。');
  };
};
</script>

消息发送与处理

封装通用的消息发送函数，并在收到信令时根据类型分发处理逻辑。

<script setup>
// 通用发送 WebSocket 消息函数
const sendMessage = (message) => {
  if (socket && socket.readyState === WebSocket.OPEN) {
    socket.send(JSON.stringify(message));
    console.log('📤 发送消息：', message);
  } else {
    console.error('❌ WebSocket 未连接，无法发送消息');
    alert('未连接服务器，请先点击'连接服务器'！');
  }
};

// 处理收到的信令消息
const handleMessage = async (message) => {
  switch (message.type) {
    case 'call':
      await answerCall(message);
      break;
    case 'answer':
      await setRemoteSDP(message.data);
      break;
    case 'ice':
      await addIceCandidate(message.data);
      break;
    default:
      console.log('📌 未知消息类型：', message.type);
  }
};
</script>

WebRTC 核心逻辑

这部分是 WebRTC 最核心的部分，包括初始化 PeerConnection、获取本地流、创建 Offer/Answer 以及处理 ICE 候选。

<script setup>
// 初始化 PeerConnection
const initPeerConnection = async () => {
  if (peerConnection) {
    peerConnection.close();
  }
  peerConnection = new RTCPeerConnection(iceServers);

  peerConnection.onicecandidate = (e) => {
    if (e.candidate) {
      sendMessage({ type: 'ice', from: userId.value, to: targetUserId.value, data: JSON.stringify(e.candidate) });
    }
  };

  peerConnection.ontrack = (e) => {
    remoteVideo.value.srcObject = e.streams[0];
    console.log('🎥 收到远程音视频流');
  };
};

// 发起视频呼叫
const call = async () => {
  if (!targetUserId.value.trim()) {
    alert('请输入对方用户 ID！');
    return;
  }
  try {
    await initPeerConnection();
    localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
    localVideo.value.srcObject = localStream;
    localStream.getTracks().forEach(track => {
      peerConnection.addTrack(track, localStream);
    });

    const offer = await peerConnection.createOffer();
    await peerConnection.setLocalDescription(offer);
    sendMessage({ type: 'call', from: userId.value, to: targetUserId.value, data: JSON.stringify(offer) });
    console.log('📞 发起视频呼叫：', targetUserId.value);
  } catch (err) {
    console.error('❌ 发起呼叫失败：', err);
    alert('发起呼叫失败！请检查摄像头/麦克风权限，或是否已连接服务器。');
  }
};

// 应答呼叫请求
const answerCall = async (message) => {
  targetUserId.value = message.from;
  try {
    await initPeerConnection();
    localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
    localVideo.value.srcObject = localStream;
    localStream.getTracks().forEach(track => {
      peerConnection.addTrack(track, localStream);
    });

    await peerConnection.setRemoteDescription(JSON.parse(message.data));
    const answer = await peerConnection.createAnswer();
    await peerConnection.setLocalDescription(answer);
    sendMessage({ type: 'answer', from: userId.value, to: targetUserId.value, data: JSON.stringify(answer) });
    console.log('📞 应答视频呼叫：', targetUserId.value);
  } catch (err) {
    console.error('❌ 应答呼叫失败：', err);
    alert('应答呼叫失败！');
  }
};

// 设置远程 SDP
const setRemoteSDP = async (sdpStr) => {
  try {
    const sdp = JSON.parse(sdpStr);
    await peerConnection.setRemoteDescription(new RTCSessionDescription(sdp));
    console.log('✅ 设置远程 SDP 成功');
  } catch (err) {
    console.error('❌ 设置远程 SDP 失败：', err);
  }
};

// 添加 ICE 候选
const addIceCandidate = async (iceStr) => {
  try {
    const ice = JSON.parse(iceStr);
    await peerConnection.addIceCandidate(new RTCIceCandidate(ice));
    console.log('✅ 添加 ICE 候选成功');
  } catch (err) {
    console.error('❌ 添加 ICE 候选失败：', err);
  }
};

// 挂断通话
const hangUp = () => {
  if (localStream) {
    localStream.getTracks().forEach(track => track.stop());
    localVideo.value.srcObject = null;
  }
  if (remoteVideo.value) {
    remoteVideo.value.srcObject = null;
  }
  if (peerConnection) {
    peerConnection.close();
    peerConnection = null;
  }
  targetUserId.value = '';
  console.log('📞 挂断通话');
  alert('已挂断通话！');
};
</script>

资源清理

最后，记得在页面销毁时清理资源，避免内存泄漏和设备占用。

<script setup>
onUnmounted(() => {
  if (socket) {
    socket.close();
    console.log('🔌 关闭 WebSocket 连接');
  }
  if (peerConnection) {
    peerConnection.close();
    console.log('🔌 关闭 PeerConnection');
  }
  if (localStream) {
    localStream.getTracks().forEach(track => {
      track.stop();
      console.log('🔇 停止本地音视频流');
    });
  }
});
</script>