auth_basic不能直接保护WebSocket接口，因其仅作用于HTTP请求阶段，而WebSocket升级请求会跳过该模块；需在location块中同时配置auth_basic、Upgrade/Connection头及proxy_pass才能生效。
不能直接用 auth_basic 保护 WebSocket 接口本身，因为 Nginx 的 auth_basic 模块只作用于 HTTP 请求阶段，而 WebSocket 升级（Upgrade）请求在协议层面是特殊的——它依赖于 Connection: Upgrade 和 Upgrade: websocket 头，Nginx 默认不会对这类请求触发 Basic Auth 挑战。
为什么 auth_basic 对 /ws 路径默认不生效
Nginx 在处理 WebSocket 连接时，通常需显式配置 proxy_set_header Upgrade $http_upgrade; 和 proxy_set_header Connection "upgrade";。一旦启用这些指令，Nginx 就进入“升级代理”模式，此时大部分 HTTP 模块（包括 auth_basic）会被跳过，除非你把它放在正确的上下文里。
常见误区是把 auth_basic 写在 location /ws { ... } 块里却没配全代理参数，结果认证被绕过；或者写在 server 级别，但因 location 匹配优先级或 upgrade 流程中断，导致未触发验证。
正确配置：在 location 块中启用 auth_basic + 完整 WebSocket 代理链
必须同时满足三个条件：开启认证、保留升级头、确保认证发生在 upgrade 请求被转发前。推荐配置如下：
- 使用
location ^~ /ws/或精确匹配（如location = /ws），避免正则干扰执行顺序 - 在该 location 内启用
auth_basic和auth_basic_user_file - 显式设置
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade"; - 确保
proxy_pass指向后端 WebSocket 服务（如http://127.0.0.1:8080/ws）
示例片段：
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
location ^~ /ws/ {
auth_basic "WebSocket Access Required";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}客户端连接时需携带认证信息
浏览器原生 WebSocket API 不支持传入用户名密码，所以不能像 HTTP 那样自动弹窗或带 Basic Auth 头。你有三种可行方式：
-
用带凭据的 URL：客户端连接时写成
ws://user:pass@your-domain.com/ws/（注意：现代浏览器已禁用该语法，仅部分 Node.js 客户端或 wscat 支持） -
前置 HTTP 登录页：让用户先访问一个受
auth_basic保护的普通页面（如/login），成功后才加载含 WebSocket 的 JS，此时浏览器会复用已认证的会话上下文（需同域且 Cookie 可用） -
Token 参数替代方案：放弃 Basic Auth，改用 URL 查询参数（如
ws://domain.com/ws?token=xxx），由后端服务自行校验 JWT 或 session —— 更灵活，也更主流
替代建议：Basic Auth + 反向代理是最简方案，但要注意局限
它适合内网管理后台、测试环境或小团队快速上线。不适用于面向公众的 Web 应用，因为：
- 浏览器不支持 WebSocket 自动发送 Basic Auth 头
- URL 中硬编码账号密码存在泄露风险（历史记录、日志、代理缓存）
- 无法实现登出、权限分级、多因子等进阶控制
若需生产级控制，应结合后端鉴权（如 JWT 校验）、IP 白名单或 OAuth 2.0 Bearer Token 方案。Nginx 层可配合 auth_request 模块做子请求校验，把复杂逻辑交给专用认证服务。
