Cấu hình WebSocket Nginx Proxy Manager cho HA, Node.js, n8n

Cách cấu hình WebSocket trong Nginx Proxy Manager cho Home Assistant, Node.js và n8n

WebSocket là thứ “chạy ngầm” nhưng rất dễ làm hỏng trải nghiệm nếu reverse proxy cấu hình sai. Home Assistant mất cập nhật realtime, dashboard đứng im. Node.js app báo connected rồi disconnect liên tục. n8n editor không nhận trạng thái workflow, execution treo hoặc UI cập nhật chậm.

Nếu bạn dùng Nginx Proxy Manager (NPM) để public dịch vụ nội bộ qua domain + SSL, cấu hình WebSocket không khó. Nhưng phải đúng vài điểm: header upgrade, scheme, port, SSL, trusted proxy, timeout. Bài này đi thẳng vào cấu hình thực tế cho Home Assistant, Node.js và n8n.

WebSocket cần gì khi đi qua reverse proxy?

HTTP bình thường là request → response. WebSocket khác: client gửi HTTP request kèm yêu cầu Upgrade, server đồng ý → kết nối được giữ mở lâu dài.

Reverse proxy như Nginx/Nginx Proxy Manager phải chuyển đúng các header sau:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Nếu thiếu, backend chỉ thấy HTTP thường → WebSocket fail.

Trong Nginx Proxy Manager, phần lớn trường hợp chỉ cần bật:

– Websockets Support – SSL đúng – Forward đúng scheme/host/port – Thêm vài dòng trong Advanced nếu app cần

Chuẩn bị trước khi cấu hình

1. Có domain/subdomain riêng

Ví dụ:

– ha.example.com → Home Assistant – app.example.com → Node.js – n8n.example.com → n8n

DNS cần trỏ về IP public của server chạy NPM.

Nếu dùng Cloudflare:

– Proxy cam bật được, nhưng cần kiểm tra WebSocket đang bật. – Với lỗi khó debug, tạm chuyển DNS record sang DNS only để loại trừ Cloudflare.

2. Port forward router

NPM cần nhận traffic từ ngoài:

– 80 → server NPM port 80 – 443 → server NPM port 443

Backend nội bộ không cần public trực tiếp.

3. Backend phải reachable từ NPM

Ví dụ NPM chạy Docker cùng network với app:

– Có thể dùng container name: homeassistant, n8n, node-app – Hoặc IP LAN: 192.168.1.50

Test nhanh từ host/NPM:

curl http://192.168.1.50:8123
curl http://192.168.1.60:5678
curl http://192.168.1.70:3000

Cấu hình chung trong Nginx Proxy Manager

Vào Nginx Proxy Manager → Hosts → Proxy Hosts → Add Proxy Host.

Tab Details:

– Domain Names: domain/subdomain – Scheme: http hoặc https tùy backend – Forward Hostname / IP: IP/container name backend – Forward Port: port app – Bật Websockets Support – Bật Block Common Exploits

Tab SSL:

– Chọn Request a new SSL Certificate – Bật Force SSL – Bật HTTP/2 Support – Nhập email – Đồng ý Let’s Encrypt Terms

Thông thường, chỉ vậy đã đủ cho WebSocket.

Nếu app vẫn lỗi, vào tab Advanced thêm:

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;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

Lưu ý: NPM đã tự thêm một số dòng. Chỉ thêm khi cần, tránh cấu hình chồng chéo quá mức.

Cấu hình WebSocket cho Home Assistant

Home Assistant dùng WebSocket rất nhiều: Lovelace dashboard, state update, mobile app, entity realtime. Nếu WebSocket lỗi, UI có thể vẫn mở được nhưng không cập nhật đúng.

Proxy Host cho Home Assistant

Trong NPM:

– Domain Names: ha.example.com – Scheme: http – Forward Hostname / IP: IP Home Assistant, ví dụ 192.168.1.50 – Forward Port: 8123 – Bật Websockets Support – Bật SSL + Force SSL

Advanced thường không cần. Nếu cần:

proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

Cấu hình configuration.yaml

Home Assistant cần biết nó đang đứng sau reverse proxy. Thêm:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.1.10

Trong đó 192.168.1.10 là IP của server chạy Nginx Proxy Manager.

Nếu NPM chạy Docker bridge, IP proxy có thể là subnet Docker, ví dụ:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.18.0.0/16

Cẩn thận: đừng trust toàn bộ mạng quá rộng nếu không cần.

Sau đó restart Home Assistant.

Lỗi thường gặp với Home Assistant

→ thiếu trusted_proxies hoặc khai báo sai IP.

→ WebSocket chưa được proxy đúng. Bật Websockets Support, kiểm tra SSL, kiểm tra console browser.

→ kiểm tra External URL trong Home Assistant:

homeassistant:
  external_url: "https://ha.example.com"
  internal_url: "http://192.168.1.50:8123"

Cấu hình WebSocket cho Node.js

Node.js có nhiều kiểu WebSocket: ws, socket.io, NestJS Gateway, Vite dev server, Next.js custom server. Nguyên tắc vẫn giống nhau: proxy phải giữ được upgrade connection.

Proxy Host cho Node.js

Ví dụ app chạy ở 192.168.1.70:3000.

NPM:

– Domain Names: app.example.com – Scheme: http – Forward Hostname / IP: 192.168.1.70 – Forward Port: 3000 – Bật Websockets Support – Bật SSL

Advanced:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;

Nếu dùng Socket.IO

Socket.IO thường dùng path:

/socket.io/

Nếu app chạy root domain, không cần thêm gì.

Nếu app nằm sau path như:

https://example.com/myapp

→ dễ lỗi hơn. Socket.IO cần cấu hình path cả client lẫn server. Khuyến nghị thực tế: dùng subdomain riêng thay vì subpath.

Tốt:

https://app.example.com

Tránh nếu không bắt buộc:

https://example.com/app

Node.js phải listen đúng interface

Sai phổ biến:

server.listen(3000, '127.0.0.1')

Nếu NPM ở container/máy khác, nó không truy cập được.

Nên dùng:

server.listen(3000, '0.0.0.0')

Hoặc chỉ:

server.listen(3000)

Kiểm tra WebSocket Node.js

Dùng wscat nếu có:

wscat -c wss://app.example.com

Nếu endpoint riêng:

wscat -c wss://app.example.com/ws

Với Socket.IO, wscat không test đơn giản được vì Socket.IO không phải raw WebSocket thuần.

Cấu hình WebSocket cho n8n

n8n dùng WebSocket/SSE cho editor UI, trạng thái execution, queue mode, webhook callback. Khi đặt sau reverse proxy, quan trọng nhất là khai báo đúng URL public.

Proxy Host cho n8n

n8n mặc định chạy port 5678.

NPM:

– Domain Names: n8n.example.com – Scheme: http – Forward Hostname / IP: IP/container n8n – Forward Port: 5678 – Bật Websockets Support – Bật SSL + Force SSL

Advanced:

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-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

Biến môi trường n8n nên có

Nếu chạy Docker Compose:

environment:
  - N8N_HOST=n8n.example.com
  - N8N_PROTOCOL=https
  - WEBHOOK_URL=https://n8n.example.com/
  - N8N_EDITOR_BASE_URL=https://n8n.example.com/

Nếu n8n dùng secure cookie:

- N8N_SECURE_COOKIE=true

Nếu bạn test nội bộ qua HTTP, secure cookie có thể gây lỗi login. Nhưng khi public HTTPS qua NPM, nên bật.

Lỗi thường gặp với n8n

→ thiếu WEBHOOK_URL, N8N_PROTOCOL.

→ WebSocket/long polling bị proxy timeout. Bật Websockets Support, tăng timeout.

→ kiểm tra N8N_SECURE_COOKIE, HTTPS, domain, browser cookie.

Kiểm tra sau khi cấu hình

1. Kiểm tra SSL

Mở:

https://ha.example.com
https://app.example.com
https://n8n.example.com

Không nên có mixed content hoặc certificate warning.

2. Kiểm tra browser DevTools

Chrome/Edge:

– F12 → Network – Filter: WS – Reload page – Click connection WebSocket – Status nên là 101 Switching Protocols

Nếu thấy 400, 403, 502, 504 → proxy/backend/config sai.

3. Kiểm tra log NPM

Trong Docker:

docker logs nginx-proxy-manager

Hoặc vào UI NPM → logs nếu có.

Lỗi hay gặp:

– connect() failed → sai IP/port/backend down – upstream timed out → timeout thấp/backend treo – 400 Bad Request → app không trust proxy hoặc host/proto sai

Checklist cấu hình nhanh

Home Assistant

– NPM bật Websockets Support – Forward http://IP:8123 – SSL + Force SSL – configuration.yaml có use_x_forwarded_for – trusted_proxies đúng IP/subnet NPM

Node.js

– App listen 0.0.0.0 – NPM forward đúng port – Bật Websockets Support – Dùng subdomain thay vì subpath – Kiểm tra WebSocket path /ws, /socket.io, v.v.

n8n

– Forward http://IP:5678 – Bật Websockets Support – Có WEBHOOK_URL – Có N8N_EDITOR_BASE_URL – Có N8N_PROTOCOL=https – SSL ổn định

Kết luận thực tế

Cấu hình WebSocket trong Nginx Proxy Manager thường không phức tạp: đúng domain, đúng backend, bật Websockets Support, bật SSL. Phần dễ sai nằm ở cấu hình riêng của từng ứng dụng.

Với Home Assistant, nhớ trusted_proxies. Với Node.js, nhớ app phải listen được từ proxy và tránh subpath nếu dùng Socket.IO. Với n8n, nhớ khai báo URL public bằng biến môi trường.

Cách debug nhanh nhất: mở DevTools → Network → WS → tìm status 101 Switching Protocols. Nếu chưa có 101, đừng sửa lung tung. Kiểm tra lần lượt: DNS → SSL → NPM host → backend reachable → header upgrade → app config. Chậm nhưng chắc, ít cấu hình thừa, ít lỗi về sau.