在 nginx 中为 websocket 代理配置独立访问日志，核心做法是在 `location` 块内使用 `access_log` 指令指定专属的日志文件路径。由于 websocket 连接是长连接，默认的全局日志会记录大量无意义的 ping/pong 帧，导致日志膨胀且难以排查业务问题，因此通过覆盖该作用域的日志路径可以实现隔离。
如何定义独立的日志格式以区分 WebSocket 流量
要实现有效的独立日志分析，通常需要配合自定义的 `log_format`。默认的 `combined` 格式包含大量静态资源相关的字段，对于 WebSocket 来说显得冗余。我们可以定义一个仅包含关键握手信息和状态码的简洁格式，例如命名为 `websocket`，并在对应的 location 中引用它，从而确保日志文件中只保留与 WebSocket 升级请求相关的关键数据。
server {
listen 80;
# 定义专用的 WebSocket 日志格式
log_format websocket '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'upgrade=$http_upgrade';
location /ws/ {
proxy_pass http://backend_websocket;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 应用独立日志格式和文件
access_log /var/log/nginx/ws_access.log websocket;
}
}
上述配置中，`proxy_http_version 1.1` 是 WebSocket 握手的基础要求，而 `access_log` 指令覆盖了全局设置。当客户端发起 `/ws/` 路径的请求时，Nginx 会将其写入 `/var/log/nginx/ws_access.log`，并使用 `websocket` 格式。这种分离使得运维人员可以单独监控 WebSocket 的连接建立情况，而不受其他 HTTP 流量的干扰。
如何处理 WebSocket 长连接导致的日志体积过大问题
即使配置了独立日志，WebSocket 连接维持期间产生的心跳包（Ping/Pong）仍会不断写入日志。如果业务场景对日志量敏感，可以通过条件判断来过滤这些非业务关键帧。利用 Nginx 的 `map` 模块或 `if` 指令，可以识别出非升级请求或非关键帧，从而决定是否记录日志。不过，更常见的做法是调整日志级别或使用 `log_not_found off` 等指令优化，但在纯访问日志层面，最稳妥的方式是接受长连接的持续记录，并通过日志轮转策略管理磁盘空间。
# 在 http 块中定义变量，用于标记是否为 WebSocket 升级请求
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
location /ws/ {
proxy_pass http://backend_websocket;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# 依然使用独立日志，但可通过后端处理或日志工具过滤
access_log /var/log/nginx/ws_access.log websocket;
}
}
在这个进阶示例中，我们引入了 `map` 指令来标准化 `Connection` 头部的处理逻辑。虽然这没有直接改变日志的记录行为，但它确保了 WebSocket 连接的稳定性。对于日志体积问题，建议结合 `logrotate` 工具定期切割 `/var/log/nginx/ws_access.log` 文件，并压缩旧日志。此外，如果只需要统计连接数而非详细帧信息，可以考虑在后端应用层记录日志，Nginx 仅负责透传，这样能从根本上减少 Nginx 层的日志压力。
基于 $http_upgrade 变量判断日志记录的准确性
在实际排查中，开发者常关心如何确认日志中的某条记录确实来自 WebSocket 升级请求。Nginx 提供的 `$http_upgrade` 变量是关键依据。当客户端发送 `Upgrade: websocket` 头部时，该变量值为 `websocket`；否则为空。在自定义的 `log_format` 中显式包含此变量，可以直接在日志行中看到升级状态。这对于验证配置是否生效以及区分普通 HTTP 请求和 WebSocket 请求至关重要。
# 假设 ws_access.log 中的一行典型内容： # 192.168.1.100 - - [10/Oct/2023:13:55:36 +0000] "GET /ws/chat HTTP/1.1" 101 0 "-" "Mozilla/5.0" upgrade=websocket
观察上述日志输出，可以看到 `upgrade=websocket` 字段明确标识了该请求成功升级为 WebSocket 协议。如果该字段为空，则说明请求未进行升级，可能是普通的 HTTP GET 请求。通过 grep 命令筛选 `upgrade=websocket` 的行，可以快速提取所有成功的 WebSocket 握手记录，用于审计或故障排查。这种基于变量的精确匹配，比依赖 URL 路径更可靠，因为路径可能被复用，而协议升级标志是唯一的。
