WebSocket 鉴权入门（实战版）：握手票据 / 首帧鉴权 + 连接级 `cid`

连接建立后，服务端立刻生成 cid，将连接置为 pending（未鉴权）：
- 仅允许 auth 消息；
- 设 5–10 秒鉴权超时；
- 对 pending 做连接数/速率限制（防滥用）。
客户端首帧发送 {type:'auth', token:<JWT>}；服务端校验：
- 通过 → ws.ctx = { cid, userId, ... }，迁移到 authenticated；
- 失败/超时 → close(4401)。

优点

token 不暴露在 URL；适合必须在应用层协议统一鉴权/续期的场景。

注意

必须实现未鉴权状态机与超时控制；鉴权前不得给该连接推送用户数据。
同样需要 wss:// 与 Origin 校验。

4 握手只发生一次：`ticket` 过期不影响已连接

HTTP Upgrade 仅在“新建连接”时发生一次。
带着 ticket 的 URL 只在握手时使用；握手成功后进入 WS 帧流，不会再回到 Upgrade。
因此 ticket 过期不影响已建立的连接，只影响新建/重连。

5 全链路时序（含 `cid`）

流程图

6 代码骨架（TypeScript + Node.js `ws`）

服务端：`cid` + pending/authed 管理（适配方案二；方案一可省略 pending）

import http from "http";
import { WebSocketServer } from "ws";
import { randomUUID } from "crypto";

const server = http.createServer();
const wss = new WebSocketServer({ server });

type Ctx = { cid: string; userId?: string; subs: Set<string> };

const cidMap = new Map<string, WebSocket>(); // cid -> ws
const userMap = new Map<string, Set<WebSocket>>(); // userId -> Set<ws>

wss.on("connection", (ws, req) => {
  // 1) 连接建立就分配 cid（连接层标识）
  (ws as any).ctx = { cid: randomUUID(), subs: new Set<string>() } as Ctx;
  const { cid } = (ws as any).ctx;
  cidMap.set(cid, ws);

  // 可选：回给前端，用于日志串联
  ws.send(JSON.stringify({ type: "hello", cid }));

  // 2) ——若你用方案二：设置鉴权超时，仅允许 'auth' —— //
  const authTimeout = setTimeout(() => {
    if (!(ws as any).ctx.userId) ws.close(4401, "auth timeout");
  }, 10_000);

  ws.on("message", (raw) => {
    let msg: any;
    try {
      msg = JSON.parse(String(raw));
    } catch {
      return;
    }

    // 未鉴权：只接受首帧 auth
    if (!(ws as any).ctx.userId) {
      if (msg.type !== "auth") return ws.close(4401, "auth required");
      const payload = verifyToken(msg.token); // TODO: 自己实现
      if (!payload) return ws.close(4401, "invalid token");

      // 3) 绑定身份（身份层）
      (ws as any).ctx.userId = payload.sub;
      clearTimeout(authTimeout);
      if (!userMap.has(payload.sub)) userMap.set(payload.sub, new Set());
      userMap.get(payload.sub)!.add(ws);

      ws.send(JSON.stringify({ type: "auth_ok" }));
      return;
    }

    // 4) 已鉴权：业务处理（身份来自 ws.ctx，不信任消息体携带的 userId/cid）
    handleBusiness((ws as any).ctx, msg, ws);
  });

  ws.on("close", () => {
    clearTimeout(authTimeout);
    cidMap.delete(cid);
    const userId = (ws as any).ctx.userId;
    if (userId) {
      const set = userMap.get(userId);
      set?.delete(ws);
      if (set && set.size === 0) userMap.delete(userId);
    }
  });
});

server.listen(8080);

// 广播/定向推送
function sendToUser(userId: string, message: any) {
  const set = userMap.get(userId);
  if (!set) return;
  const data = JSON.stringify(message);
  for (const ws of set) if (ws.readyState === ws.OPEN) ws.send(data);
}

若使用方案一（握手即鉴权），在 server.on('upgrade') 时先校验并作废 ticket，成功才 handleUpgrade()，随后直接设置 ws.ctx.userId = payload.userId 即可，基本不需要 pending 状态机。

客户端：断线重连 + 快照/增量

let ws: WebSocket | null = null;
let retry = 0;
let lastEventId: string | null = null;
const subs = new Set<string>(["orders"]);

async function getTicket() {
  const r = await fetch("/auth/ws-ticket", { method: "POST" });
  return r.json() as Promise<{ ticket: string; expireAt: number }>;
}

async function connect() {
  const { ticket } = await getTicket();
  ws = new WebSocket(
    `wss://example.com/ws?ticket=${encodeURIComponent(ticket)}`
  );

  ws.onopen = () => {
    retry = 0;
    for (const topic of subs) {
      ws!.send(
        JSON.stringify({
          type: "subscribe",
          topic,
          snapshot: true,
          since: lastEventId,
        })
      );
    }
  };

  ws.onmessage = (ev) => {
    const msg = JSON.parse(ev.data);
    if (msg.eventId) lastEventId = msg.eventId; // 记录递增ID便于断线补偿
    // TODO: 业务处理
  };

  ws.onclose = () => {
    const delay = Math.min(30000, 1000 * 2 ** retry++) + Math.random() * 300;
    setTimeout(connect, delay);
  };
}

connect();

7 常见问答（FAQ）

Q1：cid 是协议自带的吗？

不是。原生 WS 没有连接 ID。cid 应由服务端在 connection 事件里自行生成并绑定到连接上下文。

Q2：为何不要在每条消息里带 userId？

身份来自“这条连接是谁”（ws.ctx.userId），每条消息带 userId 容易被伪造，还会重复冗余。除非你做每消息签名（复杂度高），否则不要把 userId 当作消息体凭据。

Q3：ticket 过期会影响已建立的连接吗？

不会。Upgrade 只发生在建立连接时。ticket 过期只影响新建/重连。

Q4：access token 很短，需要在连接内续期吗？

看需求。最简单是断线重连即可；若希望无缝续期，可以设计 reauth { token:newJWT } 消息更新 ws.ctx，或服务端发 reauth_required 提示前端重连。

8 最佳实践清单

[ ] 全程 wss://，并校验 Origin 白名单
[ ] 服务端生成唯一 cid，贯穿整个连接生命周期（日志/指标都打上 cid）
[ ] 握手即鉴权（推荐）：URL 查询参数携带一次性短票据，校验通过即作废
[ ] 首帧鉴权（可选）：未鉴权只允许 auth，5–10s 超时，对 pending 做限流/限并发
[ ] 鉴权通过后将 { userId, roles, subs } 绑定到连接上下文（后续消息不再带凭据）
[ ] 快照 + 增量：subscribe(snapshot:true, since:lastEventId?)
[ ] 心跳（ping/pong）与背压阈值（send 队列长度限制）
[ ] 集群路由：Redis/NATS 维护 userId -> {instance, socketIds/cids}，跨实例转发
[ ] 关闭码：4401（auth failed/timeout）、4403（reauth required）、1012（service restart）
[ ] 日志串联：必要时把 cid 回给前端用于问题定位，但不要把客户端自报 cid 当权威

9 TL;DR

每条连接都有唯一 cid（服务端生成）：用于区分连接、日志追踪与限流排障。
鉴权把“谁在用这条连接”绑定到连接上下文（userId）；后续消息无需再带身份。
默认为握手票据方案；特殊场景用首帧鉴权但要写好 pending 状态机与超时。
断线重连 = 新 cid；重放快照或按 lastEventId 补增量恢复状态。