'# Golang 搭建 WebSocket 应用 - jwt 认证
一、背景与问题
在实时通信场景中，WebSocket 协议已成为替代 HTTP 长轮询的首选方案。然而，传统的 WebSocket 连接缺乏身份认证机制，容易导致以下问题：
- 任意用户可建立连接
- 无法区分用户权限
- 无法追踪连接状态
- 存在安全漏洞
为解决这些问题，我们需要在 WebSocket 层面引入身份认证机制。JWT（JSON Web Token）作为一种自包含的认证方案，天然适合与 WebSocket 结合使用。本文将深入探讨如何在 Golang 中实现基于 JWT 的 WebSocket 认证系统。
二、基本原理
1. WebSocket 协议原理
WebSocket 是基于 TCP 的全双工通信协议，通过 HTTP 升级实现。其握手过程包含以下关键步骤：
GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: somekey
服务器响应：
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pJ44Yh32s8g7C3VJpqQbJm5jY=
2. JWT 认证原理
JWT 是一个紧凑的 token，包含以下三部分：
- Header（头部）
- Payload（载荷）
- Signature（签名）
典型结构示例：
{
"alg": "HS256",
"typ": "JWT"
}
{
"iss": "myapp",
"sub": "1234567890",
"exp": 1516239022,
"nbf": 1516238422,
"iat": 1516238422,
"jti": "unique_id",
"username": "john_doe",
"roles": ["user", "admin"]
}
3. 认证流程设计
- 用户通过 HTTP 接口获取 JWT
- WebSocket 客户端携带 JWT 建立连接
- 服务端验证 JWT 有效性
- 建立认证上下文，处理后续通信
三、环境准备
// 安装依赖
go get github.com/gorilla/websocket
go get github.com/dgrijalva/jwt-go
go get github.com/gin-gonic/gin
四、核心实现
1. JWT 生成与验证
package auth
import (
"time"
"github.com/dgrijalva/jwt-go"
)
// 生成JWT
func GenerateToken(username string, secret string) (string, error) {
token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
"username": username,
"exp": time.Now().Add(24 * time.Hour).Unix(),
"nbf": time.Now().Unix(),
"iss": "websocket-auth",
})
return token.SignedString([]byte(secret))
}
// 验证JWT
func ValidateToken(tokenString string, secret string) (*jwt.Token, error) {
return jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
return nil, fmt.Errorf("unexpected signing method")
}
return []byte(secret), nil
})
}
关键点解析：
- 使用 HS256 算法保证安全性
- 设置 exp（过期时间）和 nbf（生效时间）
- 通过 iss 字段防止 token 被其他系统使用
2. WebSocket 中间件
package middleware
import (
"fmt"
"github.com/gorilla/websocket"
"github.com/dgrijalva/jwt-go"
"net/http"
)
// WebSocket 中间件
func AuthMiddleware(next websocket.Upgrader) func(w http.ResponseWriter, r *http.Request) {
return func(w http.ResponseWriter, r *http.Request) {
// 从 header 获取 token
tokenString := r.Header.Get("Authorization")
if tokenString == "" {
http.Error(w, "Missing token", http.StatusUnauthorized)
return
}
// 验证 token
token, err := ValidateToken(tokenString, "your-secret-key")
if err != nil || !token.Valid {
http.Error(w, "Invalid token", http.StatusUnauthorized)
return
}
// 继续处理连接
next.Upgrade(w, r, nil)
}
}
关键点解析：
- 从 Authorization 头获取 token（通常采用 Bearer 令牌）
- 验证 token 的有效性
- 通过中间件控制连接建立流程
3. WebSocket 服务端处理
package main
import (
"fmt"
"github.com/gorilla/websocket"
"github.com/gin-gonic/gin"
"net/http"
"sync"
)
var (
upgrader = websocket.Upgrader{
CheckOrigin: func(r *http.Request, w http.ResponseWriter) bool {
return true
},
}
connections = make(map[string]*websocket.Conn)
mu = &sync.Mutex{}
)
func main() {
r := gin.Default()
// 获取 token 接口
r.POST("/login", func(c *gin.Context) {
// 假设这里进行用户认证
username := "test_user"
token, _ := GenerateToken(username, "your-secret-key")
c.JSON(http.StatusOK, gin.H{"token": token})
})
// WebSocket 接口
r.GET("/ws", AuthMiddleware(upgrader), func(c *gin.Context) {
conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
if err != nil {
fmt.Println("Upgrade error:", err)
return
}
mu.Lock()
defer mu.Unlock()
connID := fmt.Sprintf("%d", time.Now().UnixNano())
connections[connID] = conn
// 处理消息
go func(conn *websocket.Conn) {
for {
_, msg, err := conn.ReadMessage()
if err != nil {
delete(connections, connID)
break
}
fmt.Printf("Received: %s\n", msg)
conn.WriteMessage(websocket.TextMessage, msg)
}
}(conn)
})
}
关键点解析：
- 使用 map 存储所有连接
- 使用 sync.Mutex 保证并发安全
- 实现简单的消息回显功能
五、完整案例
1. 项目结构
websocket-auth/
├── main.go
├── auth/
│ └── auth.go
├── middleware/
│ └── auth.go
├── models/
│ └── user.go
├── config/
│ └── config.go
└── utils/
└── logger.go
2. 完整实现
前端代码（HTML + JavaScript）
<!DOCTYPE html>
<html>
<head>
<title>WebSocket JWT Auth</title>
</head>
<body>
<input type="text" id="message" placeholder="Enter message">
<button onclick="sendMessage()">Send</button>
<pre id="output"></pre>
<script>
async function login() {
const response = await fetch('/login', { method: 'POST' });
const data = await response.json();
return data.token;
}
async function connect() {
const token = await login();
const ws = new WebSocket('ws://localhost:8080/ws', {
headers: {
'Authorization': token
}
});
ws.onmessage = function(event) {
document.getElementById('output').textContent += event.data + '\n';
};
document.getElementById('message').addEventListener('keypress', function(e) {
if (e.key === 'Enter') {
sendMessage();
}
});
}
function sendMessage() {
const input = document.getElementById('message');
const msg = input.value;
if (msg.trim() !== '') {
const ws = new WebSocket('ws://localhost:8080/ws', {
headers: {
'Authorization': token
}
});
ws.send(msg);
input.value = '';
}
}
connect();
</script>
</body>
</html>
后端代码（关键部分）
package main
import (
"fmt"
"github.com/gorilla/websocket"
"github.com/gin-gonic/gin"
"net/http"
"sync"
"time"
)
var (
upgrader = websocket.Upgrader{
CheckOrigin: func(r *http.Request, w http.ResponseWriter) bool {
return true
},
}
connections = make(map[string]*websocket.Conn)
mu = &sync.Mutex{}
)
func main() {
r := gin.Default()
r.POST("/login", func(c *gin.Context) {
// 假设这里进行用户认证
username := "test_user"
token, _ := GenerateToken(username, "your-secret-key")
c.JSON(http.StatusOK, gin.H{"token": token})
})
r.GET("/ws", AuthMiddleware(upgrader), func(c *gin.Context) {
conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
if err != nil {
fmt.Println("Upgrade error:", err)
return
}
connID := fmt.Sprintf("%d", time.Now().UnixNano())
mu.Lock()
connections[connID] = conn
mu.Unlock()
go func(conn *websocket.Conn) {
for {
_, msg, err := conn.ReadMessage()
if err != nil {
mu.Lock()
delete(connections, connID)
mu.Unlock()
break
}
fmt.Printf("Received: %s\n", msg)
conn.WriteMessage(websocket.TextMessage, msg)
}
}(conn)
})
r.Run(":8080")
}
六、源码解析
1. JWT 验证流程
func ValidateToken(tokenString string, secret string) (*jwt.Token, error) {
return jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
return nil, fmt.Errorf("unexpected signing method")
}
return []byte(secret), nil
})
}
关键点：
- 使用 jwt.Parse 方法解析 token
- 验证签名算法是否为 HMAC
- 返回解析后的 token 对象
2. WebSocket 中间件
func AuthMiddleware(next websocket.Upgrader) func(w http.ResponseWriter, r *http.Request) {
return func(w http.ResponseWriter, r *http.Request) {
tokenString := r.Header.Get("Authorization")
if tokenString == "" {
http.Error(w, "Missing token", http.StatusUnauthorized)
return
}
token, err := ValidateToken(tokenString, "your-secret-key")
if err != nil || !token.Valid {
http.Error(w, "Invalid token", http.StatusUnauthorized)
return
}
next.Upgrade(w, r, nil)
}
}
关键点：
- 从 Authorization 头获取 token
- 验证 token 有效性
- 通过中间件控制连接建立流程
七、进阶使用
1. 动态权限控制
func HandleMessage(conn *websocket.Conn, claims jwt.MapClaims) {
if claims["roles"].([]string) == nil {
return
}
if contains(claims["roles"].([]string), "admin") {
// 处理管理员消息
} else {
// 处理普通用户消息
}
}
2. token 刷新机制
func RefreshToken(tokenString string, secret string) (string, error) {
token, err := ValidateToken(tokenString, secret)
if err != nil || !token.Valid {
return "", err
}
newToken := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
"username": claims["username"].(string),
"exp": time.Now().Add(7*24*time.Hour).Unix(),
})
return newToken.SignedString([]byte(secret))
}
3. Redis 缓存 token
import (
"github.com/go-redis/redis/v8"
)
func CacheToken(token string, expire time.Duration) {
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
})
err := rdb.Set(ctx, "token:"+token, "1", expire).Err()
if err != nil {
log.Fatal(err)
}
}
八、性能与工程实践
1. 性能优化方案
- 连接池管理：使用 map 存储连接，避免频繁创建销毁
- token 缓存：使用 Redis 缓存 token，减少数据库访问
- 异步处理：将消息处理逻辑放入 goroutine
- 限流控制：使用令牌桶算法控制连接数
- 压缩传输：对消息内容进行压缩减少传输量
2. 安全风险分析
- token 篡改：应使用 HMAC 算法保证签名安全
- token 泄露：应使用 HTTPS 传输 token
- 过期 token：设置合理的过期时间（建议 15 分钟）
- 令牌撤销：可使用黑名单机制管理已撤销的 token
- 注入攻击：对用户输入进行严格校验
3. 代码优化建议
使用结构体定义 claims：
type CustomClaims struct {
jwt.StandardClaims
Roles []string `json:"roles"`
}
增加 token 有效期校验：
if time.Now().After(claims["exp"].(float64)) {
return errors.New("token expired")
}
使用并发安全的 map：
type SafeMap struct {
mu sync.Mutex
data map[string]*websocket.Conn
}
九、常见问题与踩坑
1. 常见错误及解决方案
错误示例：
token, _ := ValidateToken(tokenString, "your-secret-key")
问题分析：忽略错误处理，导致潜在安全漏洞
解决方案：增加错误处理逻辑
token, err := ValidateToken(tokenString, "your-secret-key")
if err != nil || !token.Valid {
// 处理错误
}
错误示例：
conn, err := upgrader.Upgrade(w, r, nil)
问题分析：未处理升级错误，可能导致连接失败
解决方案：增加错误处理
if err != nil {
http.Error(w, "Upgrade error", http.StatusInternalServerError)
return
}
2. 常见问题分析
问题1：token 无法验证
- 原因：secret 键不匹配
- 解决方案：确保 secret 键一致
问题2：WebSocket 连接失败
- 原因：未正确设置 Upgrade 头
- 解决方案：确保客户端发送正确的 Upgrade 请求
问题3：消息无法接收
- 原因：未正确处理消息读取循环
- 解决方案：确保在独立 goroutine 中处理消息
十、最佳实践
- 使用结构体定义 claims：提高代码可读性和类型安全
- 设置合理 token 有效期：建议 15 分钟以内
- 使用 HTTPS 传输 token：防止 token 泄露
- 增加 token 黑名单：支持 token 撤销
- 使用 Redis 缓存 token：提高性能
- 实现 token 刷新机制：支持长时在线
- 使用并发安全的数据结构：避免并发访问问题
- 增加详细的错误日志：便于问题排查
十一、总结
本文深入探讨了在 Golang 中实现基于 JWT 的 WebSocket 认证系统。通过分析 WebSocket 协议原理、JWT 认证机制，结合实际案例展示了如何构建安全可靠的实时通信系统。
适用场景：
- 需要实时通信的在线协作工具
- 要求用户身份认证的实时数据推送系统
- 需要权限控制的实时聊天应用
不适用场景：
- 对性能要求极高的场景（建议使用长连接+消息队列）
- 需要细粒度权限控制的场景（建议结合 RBAC 模型）
- 需要支持大规模并发的场景（建议使用分布式系统）
通过合理设计和实现，JWT 认证机制可以有效提升 WebSocket 应用的安全性和可靠性。在实际开发中，应根据具体业务需求选择合适的认证方案，并持续进行安全审计和性能优化。