AI agent có thể hỗ trợ đọc template, soạn cấu hình và kiểm tra triển khai n8n. Trước khi khởi chạy, cần chốt máy đích, kiến trúc, tên miền và cách phục hồi dữ liệu. Bài này tập trung vào single mode trên một máy Linux mới, có HTTPS qua Caddy.
An AI agent can inspect templates, prepare configuration and verify an n8n deployment. Establish the target machine, architecture, domain and recovery plan first. This guide focuses on single mode on a fresh Linux host with HTTPS through Caddy.
Trong bài nàyOn this page
1. Chọn kiến trúc và kiểm tra máy đích1. Choose the architecture and inspect the host
Single mode dùng một tiến trình n8n, thường bắt đầu với SQLite. Queue mode bổ sung PostgreSQL, Redis và worker cho nhu cầu xử lý khác. Chọn theo tải dự kiến và khả năng vận hành; chuyển chế độ sau này cần kế hoạch dữ liệu, không chỉ thêm một biến môi trường.
Chuẩn bị quyền quản trị máy Linux, Docker Engine và Compose v2, tên miền do bạn kiểm soát, DNS đúng, email TLS và timezone. Kiểm tra cổng 80/443 ở cả firewall máy và nhà cung cấp cloud. Giữ cổng quản trị cần thiết trước khi sửa firewall. Không tự xóa dịch vụ đang dùng các cổng đó.
Cài và đọc n8n-self-hosting. Skill hướng dẫn triển khai hạ tầng; nó không phải một bộ workflow n8n đã hoàn chỉnh. Các tính năng Assistant hoặc sandbox của phiên bản mới có yêu cầu riêng, ngoài cấu hình single cơ bản ở đây.
Single mode uses one n8n process, commonly starting with SQLite. Queue mode adds PostgreSQL, Redis and workers for different processing needs. Choose according to expected load and operating capacity. Switching later requires a data plan, not merely another environment variable.
Prepare Linux administration access, Docker Engine and Compose v2, a domain you control, correct DNS, a TLS email and timezone. Check ports 80/443 in both host and cloud firewalls. Preserve required administrative access when changing firewall rules, and do not remove existing services occupying those ports.
Install and read n8n-self-hosting. It covers deployment infrastructure, not a finished set of n8n workflows. Newer Assistant or sandbox features have additional requirements beyond the basic single setup here.
Chuẩn bị kế hoạch triển khai n8n single mode trên máy Linux đã chỉ định.
Đọc skill và template; kiểm tra OS, Docker, DNS, cổng và dung lượng.
Cho tôi xem cấu hình, phiên bản image và kế hoạch backup trước khi khởi chạy.
Không đổi dịch vụ hiện có, tạo tài nguyên cloud hoặc bật module ngoài phạm vi.
Không đưa secret vào chat, Git hoặc log cấu hình.Prepare an n8n single-mode deployment plan for the specified Linux host.
Read the skill and templates; check OS, Docker, DNS, ports and storage.
Show the configuration, image versions and backup plan before starting it.
Do not alter existing services, provision cloud resources or enable extra modules.
Keep secrets out of chat, Git and configuration logs.2. Đặt đúng tệp và đường dẫn2. Place the correct files and paths
Trong thư mục skill đã cài, đọc SINGLE_MODE.md, SECURITY.md và DAY2.md. Chuyển các template trong assets/ vào thư mục triển khai đã thống nhất trên máy đích:
docker-compose.single.yml→docker-compose.ymlCaddyfile→caddy_config/Caddyfile.env.single.example→.env- Tạo thư mục
local_files/cho các tệp workflow được phép dùng.
Trong bản Caddyfile vừa sao chép, xóa dòng header_up X-Forwarded-For {http.request.header.X-Forwarded-For} có trong snapshot. Dòng này chuyển tiếp giá trị client gửi; khi Caddy trực tiếp nhận kết nối từ Internet, hãy để reverse_proxy tự thiết lập các header forwarded theo mặc định. Với một proxy Caddy trước n8n, dùng N8N_PROXY_HOPS=1. Nếu có CDN hoặc proxy khác phía trước, cấu hình trusted_proxies theo đúng dải IP tin cậy và số hop thực tế trước khi mở dịch vụ.
DATA_FOLDER trong .env phải trùng đường dẫn tuyệt đối thật. Đặt DOMAIN_NAME, SUBDOMAIN, SSL_EMAIL và GENERIC_TIMEZONE theo môi trường. Đây là hướng dẫn cho máy mới; nếu đã có n8n, kiểm kê volume và backup trước khi thay cấu hình.
Read SINGLE_MODE.md, SECURITY.md and DAY2.md in the installed skill. Transfer these templates from assets/ into the agreed deployment directory on the target host:
docker-compose.single.yml→docker-compose.ymlCaddyfile→caddy_config/Caddyfile.env.single.example→.env- Create
local_files/for approved workflow files.
In the copied Caddyfile, remove the snapshot line header_up X-Forwarded-For {http.request.header.X-Forwarded-For}. It forwards a client-supplied value; when Caddy receives Internet traffic directly, let reverse_proxy set forwarded headers using its defaults. With one Caddy proxy before n8n, use N8N_PROXY_HOPS=1. If a CDN or another proxy sits in front, configure trusted_proxies for the actual trusted IP ranges and reconcile the hop count before exposing the service.
DATA_FOLDER in .env must match the actual absolute directory. Set DOMAIN_NAME, SUBDOMAIN, SSL_EMAIL and GENERIC_TIMEZONE for the environment. This procedure assumes a fresh host; inventory and back up an existing installation before changing it.
3. Kiểm tra secrets và phiên bản trước khi chạy3. Verify secrets and versions before launch
Tạo encryption key mới trên máy đích theo SECURITY.md, lưu vào .env với quyền phù hợp và sao lưu qua kênh bảo mật. N8N_ENCRYPTION_KEY cần được giữ ổn định để giải mã credentials đã lưu. Không lấy key từ bài mẫu hoặc một hệ thống khác.
Đặt N8N_IMAGE_TAG thành phiên bản cụ thể đã xem release notes; template mặc định stable có thể thay đổi giữa các lần pull. Kiểm tra cả phiên bản Caddy và tên biến cấu hình theo release n8n đã chọn. Chẳng hạn, tài liệu hiện nêu N8N_WEBHOOK_URL từ n8n 2.30.0, trong khi snapshot template dùng WEBHOOK_URL; đối chiếu hướng dẫn của phiên bản trước khi áp dụng.
Template giữ n8n trong mạng Docker riêng; chỉ proxy công khai 80/443. Không thêm mapping 5678 ra Internet để né lỗi proxy. Các volume trong snapshot có tên cố định: nếu máy đã có volume trùng tên, dừng lại và xác định quyền sở hữu trước.
Generate a fresh encryption key on the target host following SECURITY.md, store it in the protected .env and back it up through a secure channel. Keep N8N_ENCRYPTION_KEY stable so stored credentials remain decryptable. Do not reuse a tutorial value or another deployment’s key.
Set N8N_IMAGE_TAG to a specific release after reviewing its notes; the default stable tag can change between pulls. Review Caddy versions and configuration names for the selected n8n release too. Current documentation introduces N8N_WEBHOOK_URL in n8n 2.30.0, while the template snapshot uses WEBHOOK_URL; reconcile the selected version’s guidance before applying it.
The template keeps n8n on a private Docker network, exposing only proxy ports 80/443. Do not publish 5678 to bypass proxy failures. Snapshot volume names are fixed: stop and establish ownership if the host already has volumes with those names.
4. Khởi chạy và kiểm tra từng tầng4. Launch and verify each layer
Chạy từ thư mục triển khai trên máy đích sau khi cấu hình và phạm vi đã được chốt. Dùng config --quiet để kiểm tra cú pháp mà không in cấu hình đã nội suy secrets.
Run from the target deployment directory after the configuration and scope are agreed. config --quiet validates syntax without printing the secret-expanded configuration.
docker compose version
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose exec -T n8n wget -qO- http://localhost:5678/healthz
docker compose exec -T n8n wget -qO- http://localhost:5678/healthz/readinessKiểm tra tiếp HTTPS từ bên ngoài bằng tên miền thật, đăng nhập và tạo một workflow thử không gọi hệ thống sản xuất. Health check chỉ xác nhận một phần trạng thái; cần kiểm tra owner account, lưu workflow và chạy một thao tác thử. Hoàn tất thiết lập owner trước khi chia sẻ URL.
Nếu nội bộ khỏe nhưng HTTPS lỗi, xem DNS, chứng chỉ, Caddy và firewall. Nếu readiness lỗi, xem kết nối dữ liệu và migration của phiên bản đang chạy. Chỉ đọc log cần thiết và loại dữ liệu riêng trước khi chia sẻ.
Check external HTTPS using the actual domain, sign in and create a harmless test workflow that does not call production systems. Health endpoints prove only part of the setup; verify owner access, workflow persistence and a test execution. Complete owner setup before sharing the URL.
If internal health succeeds but HTTPS fails, inspect DNS, certificates, Caddy and firewalls. If readiness fails, inspect data connectivity and migrations for the running version. Read only necessary logs and remove private data before sharing them.
5. Bàn giao khả năng phục hồi5. Hand over a recoverable deployment
Ghi vị trí compose, image đã pin, tên volume, lịch backup và nơi giữ encryption key. Theo tài liệu backup n8n, cần bảo vệ thư mục người dùng .n8n và database ngoài nếu dùng PostgreSQL. Sao chép tùy tiện database SQLite đang ghi không thay thế một quy trình backup nhất quán.
Thử restore vào môi trường tách biệt và kiểm tra credentials vẫn giải mã được. Trước nâng cấp, đọc hướng dẫn migration và tạo backup có thể phục hồi; đổi image cũ không tự đảo ngược migration database. Không dùng thao tác xóa volume như một bước cập nhật thông thường.
Record compose location, pinned images, volume names, backup schedule and protected key storage. The n8n backup guide covers the .n8n user folder and the external database when using PostgreSQL. Copying a live SQLite file arbitrarily is not a consistent backup procedure.
Test restoration in an isolated environment and verify credentials remain decryptable. Review migrations and create a recoverable backup before upgrading; reverting an image does not automatically reverse database migrations. Volume removal is not a routine update step.