Cài Nod n8n trên VPS bằng Docker Compose
Cài Nod của đội ngũ n8n trên VPS bằng Docker Compose, giữ port 4310 ở private, cố định tag cài đặt và backup Vault key trước khi dùng thật.
Nod là gì và bạn sẽ xây dựng gì
Nod là một AI agent cá nhân do nhóm phát triển n8n xây dựng. Bạn có thể chạy Nod trên VPS bằng bộ Docker Compose trong repository riêng của dự án. Hướng dẫn này cố định bộ cài ở tag nod-v0.8.1 và giữ app trên một private port. Bạn truy cập Nod qua SSH tunnel hoặc HTTPS. Bước backup là một phần của quá trình cài đặt, vì không thể khôi phục credential đã lưu nếu thiếu key đó.
README mô tả Nod là một agent có máy tính và trình duyệt riêng: “Nó xử lý hóa đơn, chuẩn bị các cuộc gọi và hủy các gói dùng thử trên những website thật. Nó chạy trên máy của bạn bằng model bạn chọn và hỏi trước khi hành động thay bạn.” Bạn trao đổi với Nod trong một chat duy nhất. Nod có workspace Linux và trình duyệt riêng, đồng thời kết nối với Gmail, Calendar, Slack, Notion và web.
Có 2 điểm cần biết để đặt đúng kỳ vọng trước khi cài đặt. Thứ nhất, README gọi Nod là “bản preview cho mục đích nghiên cứu”. Website tài liệu cũng có banner “Early preview” với nội dung “Hãy dự kiến sẽ có các điểm chưa hoàn thiện và các thay đổi breaking.” Thứ hai, README nói rằng bước kiểm tra an toàn của Nod “là phán đoán của model”. Hãy xem Nod là một công cụ preview. Chỉ cấp quyền cho những account bạn sẵn sàng dùng để thử nghiệm.
VPS phù hợp với Nod vì một lý do đơn giản. Tài liệu cho biết schedule chỉ chạy khi máy đang chạy Nod được bật. Laptop sẽ chuyển sang trạng thái sleep. Server thì không.
Nod khác workflow n8n AI Agent như thế nào
Nod không phải là n8n AI Assistant và bạn không cần n8n để chạy Nod. README trả lời câu hỏi “Tôi có cần n8n không?” như sau: “Không. Nod là một app độc lập, do đội ngũ đứng sau n8n phát triển. Nod không phải là n8n AI Assistant.”
Tài liệu n8n mô tả node AI Agent như sau: “Kết nối một chat model và một hoặc nhiều tool, sau đó agent sẽ quyết định cần gọi tool nào để hoàn thành tác vụ.” Bạn xây dựng agent đó trong n8n editor và phải kết nối ít nhất một tool sub-node với nó. Nếu đó là nhu cầu của bạn, xây dựng workflow với node AI Agent trong n8n sẽ hướng dẫn phần này. Tự host n8n trên VPS bằng Docker và HTTPS cung cấp n8n server để bạn xây dựng workflow.
Đây là cách chúng tôi hiểu hai bộ tài liệu này. Node AI Agent là một agent do bạn thiết kế từng node trong n8n. Nod là một chat app hoàn chỉnh, có workspace và browser riêng; bạn giao task cho Nod bằng ngôn ngữ tự nhiên. Không có trang của vendor nào so sánh trực tiếp hai sản phẩm, nên hãy xem đây là phần tóm tắt, không phải quan điểm chính thức.
Hai sản phẩm có thể kết hợp với nhau. Trang n8n của Nod viết: “Kết nối n8n một lần, sau đó gọi n8n bằng tên trong chat.” Nod có thể xây dựng “một n8n Agent với các tool và channel mà bạn chỉ định.” Nếu request của bạn không đề cập đến n8n, Nod sẽ dùng task và schedule riêng của nó.
Giấy phép: Nod dùng Apache-2.0, còn n8n thì không
Repository của Nod, github.com/n8n-io/nod, được cấp phép theo Apache License 2.0 và chủ sở hữu bản quyền là n8n GmbH. Phần cuối README ghi: "Copyright 2026 n8n GmbH · Apache License 2.0". Các tài sản bên thứ ba đi kèm, chẳng hạn như font Geist, logo của các provider và thành phần runtime cho desktop, vẫn áp dụng điều khoản riêng.
n8n sử dụng một giấy phép khác. Code của n8n, ngoại trừ các file được đánh dấu .ee., thuộc Sustainable Use License. Giới hạn chính nằm ở câu sau: "Bạn chỉ được sử dụng hoặc sửa đổi phần mềm cho mục đích kinh doanh nội bộ của mình hoặc cho mục đích phi thương mại hay cá nhân." Apache-2.0 không đặt ra giới hạn tương tự đối với cách bạn sử dụng Nod. Nếu bạn đang quyết định có thể xây dựng gì trên n8n, hãy đọc giải thích về Sustainable Use License của n8n trước khi lập kế hoạch xây dựng sản phẩm dựa trên nó.
Các yêu cầu của VPS để chạy Nod
Tài liệu tự host liệt kê Docker Engine 25 trở lên với Compose v2, OpenSSL và sha256sum hoặc shasum. Nếu build từ source, bạn cũng cần Git. Các máy chủ được hỗ trợ là Linux trên AMD64 hoặc ARM64, hoặc Mac có Docker Desktop.
Về cấu hình, tài liệu ghi: "Bắt đầu với 2 CPU core, 8 GB memory và 50 GB disk." Đây là cấu hình khởi điểm được đề xuất, không phải mức tối thiểu được đo thực tế. Tài liệu cũng lưu ý rằng các browser task chạy đồng thời và model cục bộ cần nhiều tài nguyên hơn. Phần compose.yaml của bộ công cụ giải thích phần lớn mức memory này. Nó giới hạn container server ở 2 GB, browser ở 3 GB và workspace ở 2 GB. Bạn thay đổi các giới hạn này bằng NOD_SERVER_MEMORY, NOD_BROWSER_MEMORY và NOD_WORKSPACE_MEMORY trong .env. Postgres và Caddy không bị giới hạn.
Bạn không cần model API key để cài đặt. Sau khi app khởi động, bạn kết nối model trong app.
Nếu server chưa có Docker, hãy cài Docker trước. Tổng quan về Docker Compose trên VPS hướng dẫn quy trình này. Sau đó kiểm tra version và cài thêm các công cụ còn lại:
docker version
docker compose version
sudo apt update && sudo apt install -y git opensslPhần Server: của docker version phải hiển thị version 25 trở lên và docker compose version phải chạy thành công. Các lệnh bên dưới giả định user của bạn có thể chạy docker mà không cần sudo. Nếu không thể, hãy thêm sudo vào trước mỗi lệnh docker và sh.
Clone repository Nod tại một tag cố định
Bộ kit nằm trong deployment/self-host/ và build các image Nod từ bản checkout của bạn. Không có thành phần riêng của Nod nào được pull từ registry, nên tag bạn checkout chính là phiên bản bạn chạy.
git clone https://github.com/n8n-io/nod.git
cd nod
git checkout nod-v0.8.1
cd deployment/self-host
lsls phải liệt kê setup.sh, compose.yaml, Caddyfile, backup.sh và restore.sh cùng nhiều file khác. Cả tag nod-v0.8.0 và nod-v0.8.1 đều được tạo vào ngày 16 tháng 11 năm 2026. Đây không phải các tag mới nhất. Tính đến ngày 21 tháng 11 năm 2026, nod-v0.9.1 (ngày 20 tháng 11) được đánh dấu là Latest. Guide này được kiểm tra với bộ kit nod-v0.8.1, nên tag đó được cố định. Phần cập nhật bên dưới hướng dẫn cách chuyển lên phiên bản mới hơn.
Các image bên thứ ba trong compose.yaml được cố định bằng digest, không phải bằng :latest: postgres:17-alpine, node:24.21.0-bookworm-slim và caddy:2.11.7-alpine. Mặc định, các image Nod được gắn tag local thông qua NOD_IMAGE_TAG. Thiết lập biến đó không tải một release đã publish.
Tạo secret bằng setup.sh
sh setup.shsetup.sh không nhận flag nào. Script này sao chép .env.example thành một .env riêng tư rồi điền 4 giá trị được tạo tự động: tên project Compose, NOD_AUTH_TOKEN (từ openssl rand -hex 32), NOD_VAULT_KEY (từ openssl rand -base64 32) và NOD_POSTGRES_PASSWORD. Sau đó, script chạy chmod 600 .env để chỉ user của bạn có thể đọc file.
Script kết thúc bằng cách in Ready. Run: docker compose --file compose.yaml --env-file .env up -d --build --wait. Nếu .env đã tồn tại, script giữ nguyên file đó và in Using the existing .env. Its keys and data are unchanged.. Script từ chối chạy khi NOD_AUTH_TOKEN, NOD_VAULT_KEY hoặc NOD_POSTGRES_PASSWORD đã được set trong shell của bạn. Nếu bạn đã export biến nào trong số đó, trước tiên hãy unset chúng. Trên Docker cũ hơn, script dừng với Use Docker Engine 25 or newer.
Xây dựng và khởi động stack
docker compose up -d --build --wait
docker compose psLần build đầu tiên mất nhiều thời gian vì kit build các image Nod từ source. Giữ terminal mở cho đến khi command trả về. --wait chờ cho đến khi các service có health check báo healthy, nên nếu command trả về mà không có lỗi thì stack đã chạy. docker compose ps phải hiển thị server, postgres, browser và các service khác đang chạy, trong đó server được đánh dấu healthy.
Nếu chạy docker compose up trước setup.sh, Compose từ chối khởi động và in Run sh setup.sh first. Nguyên nhân là compose.yaml đánh dấu NOD_AUTH_TOKEN là bắt buộc, và chỉ setup.sh mới ghi giá trị này.
Để đọc log của server:
docker compose logs --tail 100 serverTài liệu cho biết token không bao giờ được in trong startup log.
Port 4310 chỉ bind vào loopback, và ufw không phải lớp bảo vệ cho cổng này
Server publish host port như sau trong compose.yaml:
'${NOD_BIND_ADDRESS:-127.0.0.1}:${PORT:-4310}:${PORT:-4310}'Vì vậy, Nod lắng nghe trên port 4310, còn phía host bind vào 127.0.0.1. Chỉ các process chạy ngay trên server mới có thể kết nối. Hãy giữ nguyên cấu hình này.
Điều này quan trọng hơn bạn nghĩ, vì các port được Docker publish sẽ bypass ufw. Tài liệu Docker nói rằng traffic đến port của container được publish “gets diverted before it goes through the ufw firewall settings”, tức là “effectively ignoring your firewall configuration.” Một rule ufw deny 4310 sẽ không bảo vệ được port publish trên tất cả interface. Chính việc bind vào loopback mới giữ cho port 4310 ở chế độ private. Vì sao port Docker bypass ufw giải thích cơ chế này và cách kiểm tra server của bạn.
Docker có một lưu ý về version. Trong các release cũ hơn 28.0.0, host trên cùng segment mạng layer 2 có thể truy cập các port được publish vào localhost. Trên VPS, segment đó là network của nhà cung cấp. Vì vậy, nếu có thể, hãy chạy Docker 28 hoặc mới hơn.
Không đổi NOD_BIND_ADDRESS thành 0.0.0.0 để truy cập app từ xa. Tài liệu nói: “Never expose PostgreSQL, the browser, the workspace, or the Docker connection.” Hãy dùng một trong hai đường dẫn truy cập bên dưới.
Mở Nod qua SSH tunnel
Tunnel này không cần domain và không cần mở thêm cổng nào ngoài SSH. Chạy lệnh này trên máy tính của bạn, không phải trên server:
ssh -L 4310:127.0.0.1:4310 user@203.0.113.10Giữ phiên SSH đó mở rồi truy cập http://localhost:4310 bằng trình duyệt trên máy local. Với thiết lập này, giữ NOD_PUBLIC_URL ở giá trị mặc định local là http://localhost:4310. Nếu bạn đã thay đổi PORT, hãy thay đổi cả hai đầu tunnel và địa chỉ trình duyệt để khớp nhau.
Ứng dụng sẽ yêu cầu access token. In token trên server:
grep NOD_AUTH_TOKEN .envDán giá trị sau = vào form xác thực, sau đó hoàn tất bước thiết lập ban đầu và kết nối một model. Token vẫn bắt buộc ngay cả khi truy cập qua tunnel.
Nếu bạn truy cập server qua Tailscale, hãy đọc Tailscale Serve và Funnel trước khi đặt bất kỳ thứ gì phía trước Nod, vì Funnel public một service lên Internet.
Hoặc chạy Nod qua HTTPS bằng profile Caddy
Với địa chỉ public, bộ kit có profile https. Profile này thêm một container Caddy để lấy và gia hạn chứng chỉ TLS (bảo mật tầng truyền tải), rồi chuyển tiếp traffic đến server. Bạn cần một domain có bản ghi DNS trỏ đến VPS. Bạn cũng cần mở TCP 80 và 443 cho chiều inbound trong network firewall của nhà cung cấp, nếu nhà cung cấp có firewall này.
Sửa .env và đặt origin chính xác:
NOD_PUBLIC_URL=https://nod.example.comNOD_PUBLIC_URL là “origin chính xác mà bạn mở Nod tại đó”. Chỉ ghi scheme và host. Path, query string và fragment sẽ bị từ chối. Profile yêu cầu origin https:// trên port 443, dùng tên DNS hoặc địa chỉ IPv4. Sau đó khởi động stack bằng profile:
docker compose --profile https up -d --build --waitTiếp tục thêm --profile https vào các lệnh start, stop và status về sau, nếu không Compose sẽ bỏ qua container Caddy. Mở https://nod.example.com và dán token như trên.
Bạn cần biết profile này mở những gì. Service Caddy publish 80:80, 443:443 và 443:443/udp mà không có bind address, nên các port đó sẽ listen trên mọi interface. Chúng luôn dùng host port 80 và 443, bất kể PORT đặt gì. Do cơ chế bypass Docker nêu trên, ufw sẽ không đóng các port này. Nếu bạn đã chạy reverse proxy, hãy bỏ qua profile này. Trỏ proxy đến 127.0.0.1:4310 và đặt NOD_PUBLIC_URL thành origin HTTPS của proxy.
Kiểm tra trạng thái dữ liệu sử dụng và phản hồi
Tài liệu ghi rằng “Chia sẻ dữ liệu sử dụng được bật cho chủ sở hữu mới”. Dữ liệu được gửi đến project PostHog do đội Nod lưu trữ tại EU, kể cả từ các bản cài đặt độc lập. Bản triển khai cũng phải cho phép tính năng này, và NOD_ANALYTICS_ENABLED=false luôn tắt tính năng đó.
Bộ mã tại nod-v0.8.1 cung cấp NOD_ANALYTICS_ENABLED=false trong .env.example, còn setup.sh sao chép dòng đó vào .env của bạn. Vì vậy, bản cài đặt mới theo hướng dẫn này sẽ tắt analytics ở cấp server. Hãy kiểm tra:
grep -n NOD_ANALYTICS_ENABLED .envNếu dòng này bị thiếu hoặc để trống, server sẽ coi analytics là được phép mỗi khi chạy ở production mode. Điều này có thể xảy ra với .env cũ hoặc được viết thủ công. Khi đó, hãy tự đặt dòng này thành false.
Bộ thu thập phản hồi là một thành phần riêng. NOD_FEEDBACK_ENABLED không nằm trong .env.example, và tài liệu ghi rằng tính năng này được bật theo mặc định. Tài liệu nêu cách opt-out hoàn toàn: đặt analytics và feedback thành false, đồng thời để NOD_ONBOARDING_EMAIL_URL trống.
echo 'NOD_FEEDBACK_ENABLED=false' >> .env
grep -n -e NOD_ANALYTICS_ENABLED -e NOD_FEEDBACK_ENABLED -e NOD_ONBOARDING_EMAIL_URL .env
docker compose up -d --wait serverLệnh cuối cùng sẽ tạo lại server với các giá trị mới. Thêm --profile https nếu bạn sử dụng nó. Chủ sở hữu cũng có thể thay đổi tùy chọn chia sẻ trong ứng dụng tại Settings, Privacy & data, Share usage data. Việc dừng chia sẻ không xóa dữ liệu đã được gửi trước đó.
Sao lưu Vault key và dữ liệu: bước này là bắt buộc
NOD_VAULT_KEY là “một key 32 byte được mã hóa bằng base64 để mã hóa các credential đã lưu”. Key này nằm trong .env, bên ngoài database. Tài liệu Vault nói rằng “Không thể đọc credential đã lưu nếu không có key này.” Nod không bao giờ tạo key thay thế sau khi dữ liệu đã được mã hóa. Trang self-host nêu rõ rằng “chỉ database thì không thể khôi phục credential đã lưu”. Nếu mất key, mọi thông tin đăng nhập bạn đã cấp cho Nod sẽ mất, ngay cả khi có một database dump hoàn chỉnh.
Vì vậy, trước tiên hãy lưu riêng key vào password manager hoặc một nơi an toàn khác bên ngoài server:
grep NOD_VAULT_KEY .envSau đó, dùng script của bộ công cụ để tạo bản backup đầy đủ. Đích phải là một absolute path chưa tồn tại:
mkdir -p "$HOME/nod-backups"
chmod 700 "$HOME/nod-backups"
sh backup.sh "$HOME/nod-backups/nod-2026-11-21"Script sẽ dừng server, browser và workspace trong lúc sao chép, rồi khởi động lại các thành phần này. Script in ra Backup saved: và đường dẫn. Thư mục này chứa .env, source-commit, một postgres.dump, các archive của dữ liệu server, workspace, tools và browser, cùng một file marker complete. Hãy kiểm tra marker này tồn tại trước khi tin cậy bản backup.
Tài liệu nói rằng “Bản backup chứa các secret.” Bản backup chứa mọi secret đã tạo, bao gồm Vault key. Hãy lưu bản backup ở dạng được mã hóa và giới hạn người có quyền đọc. Sao chép bản backup ra khỏi server, vì bản backup trên cùng một disk sẽ mất khi disk hỏng. TLS certificate không được bao gồm.
Khôi phục Nod vào một bản checkout mới
Bản khôi phục được thực hiện trong thư mục mới và một Compose project mới. Đọc commit mà backup được tạo từ đó, rồi checkout đúng commit đó:
commit="$(cat "$HOME/nod-backups/nod-2026-11-21/source-commit")"
git clone https://github.com/n8n-io/nod.git nod-restored
cd nod-restored
git checkout "$commit"
cd deployment/self-host
sh restore.sh "$HOME/nod-backups/nod-2026-11-21" nod-restoredKhông chạy setup.sh trước. restore.sh cần một checkout không có .env và có source-commit khớp với revision đã checkout. Lệnh này tạo các volume mới, khôi phục database và không khởi động app. Lệnh kết thúc bằng Restored into a new project. Review .env before starting Nod.
Dừng server gốc trước khi khởi động server đã khôi phục. Sau đó chạy docker compose up -d --build --wait, kèm --profile https nếu dùng địa chỉ public. Không bao giờ chạy docker compose down --volumes trên server mà bạn muốn giữ lại. Lệnh này xóa các data volume.
Cập nhật Nod lên tag mới hơn
Trước tiên, hãy sao lưu. Sau đó, từ nod/deployment/self-host:
docker compose stop
git fetch origin --tags
git checkout nod-v0.9.1
docker compose up -d --build --waitNod chạy migration cơ sở dữ liệu khi khởi động, vì vậy bạn không thể hoàn tác bản cập nhật bằng cách checkout tag cũ. Tài liệu ghi rõ: “Không trỏ phiên bản ứng dụng cũ vào cơ sở dữ liệu đã được nâng cấp.” Rollback nghĩa là khôi phục bản sao lưu trước khi cập nhật vào một checkout mới. Hãy đọc release notes trước mỗi lần nâng cấp, vì nhãn preview cho biết có thể có breaking changes. Không thay đổi COMPOSE_PROJECT_NAME trong khi cập nhật.
Để xoay vòng access token, hãy chạy openssl rand -hex 32, thay giá trị NOD_AUTH_TOKEN trong .env, rồi chạy docker compose up -d --wait server. Token cũ sẽ ngừng hoạt động. Không bao giờ thay NOD_VAULT_KEY để xoay vòng quyền truy cập.
FAQ
Tôi có cần n8n để chạy Nod không?
Không. README cho biết Nod là một ứng dụng độc lập, do đội ngũ đứng sau n8n phát triển, và không phải là n8n AI Assistant. Nod chạy trên stack Docker Compose riêng. Sau này bạn có thể kết nối một instance n8n rồi yêu cầu Nod sử dụng instance đó theo tên, nhưng quá trình cài đặt không phụ thuộc vào n8n.
Nod có mã nguồn mở theo cùng giấy phép với n8n không?
Không. Nod sử dụng Apache License 2.0, thuộc bản quyền của n8n GmbH, còn các asset bên thứ ba đi kèm vẫn áp dụng điều khoản riêng của chúng. Mã nguồn n8n bên ngoài các file .ee. sử dụng Sustainable Use License, giấy phép này giới hạn việc sử dụng vào mục đích kinh doanh nội bộ, phi thương mại hoặc cá nhân. Apache-2.0 không có giới hạn sử dụng như vậy.
Làm cách nào để mở Nod trên VPS mà không cần domain?
Dùng SSH tunnel từ máy tính của bạn: ssh -L 4310:127.0.0.1:4310 user@203.0.113.10. Giữ tunnel này mở, truy cập http://localhost:4310, rồi dán NOD_AUTH_TOKEN lấy từ .env trên server. Giữ NOD_PUBLIC_URL ở giá trị mặc định cục bộ. Port 4310 vẫn chỉ bind vào loopback trên server, nên không có dịch vụ mới nào bị expose.
Điều gì xảy ra nếu tôi mất NOD_VAULT_KEY?
Bạn không thể đọc lại các credential đã lưu. Key này mã hóa các credential và được lưu trong .env, bên ngoài database. Sau khi đã có dữ liệu được mã hóa, Nod sẽ không tạo key thay thế, nên chỉ có database dump thì không đủ. Hãy lưu một bản sao của key bên ngoài server. Đồng thời chạy sh backup.sh với đường dẫn tuyệt đối, vì bản backup chứa .env cùng với key.
ufw có bảo vệ các port của Nod không?
Không bảo vệ các port mà Docker publish. Docker gửi traffic đến các port của container đã publish, bypass các rule của ufw. Port 4310 chỉ ở chế độ private vì compose.yaml bind port này vào 127.0.0.1. Profile https publish 80, 443 và 443/udp trên mọi interface, nên ufw không thể đóng các port đó. Với Docker cũ hơn 28.0.0, các host trên cùng segment layer 2 cũng có thể truy cập những port được publish vào localhost.