n8n chạy bằng Docker: những cấu hình cần đặt cho đúng

Container chạy lên. Giao diện n8n mở được. Workflow đầu tiên chạy qua trót lọt. Mọi thứ trông ổn cho tới khi webhook báo lỗi lúc nửa đêm, hoặc dữ liệu workflow biến mất sau một lần restart. Phần lớn sự cố đó không phải bug của n8n. Đó là biến môi trường chưa đặt đúng ngay từ lúc dựng container.

Vì sao n8n chạy bằng Docker vẫn lỗi dù container khởi động thành công

n8n chạy bằng Docker khởi động được không có nghĩa là đã sẵn sàng chạy thật. Image mặc định chỉ bật cấu hình tối thiểu để demo. Phần bảo mật và bền dữ liệu phải người dựng tự khai báo qua biến môi trường. Container xanh trên lệnh `docker ps` chỉ xác nhận tiến trình còn sống, không xác nhận dữ liệu có được giữ lại hay webhook có nhận đúng địa chỉ.

Ba nhóm hay bị bỏ sót nhất: nơi lưu dữ liệu, địa chỉ webhook thật, và khoá mã hoá credential. Cả ba không gây lỗi ngay khi cài. Chúng chỉ lộ ra khi đã có vài chục workflow đang chạy, lúc đó sửa tốn công hơn nhiều so với đặt đúng từ đầu. Đội chưa quen Docker nên nhờ đội quản trị máy chủ BizMaC soát cấu hình trước khi đưa workflow vào chạy thật.

Volume phải trỏ đúng chỗ để không mất dữ liệu khi container khởi động lại

Container Docker mặc định là ephemeral. Xoá container thì mọi thứ ghi bên trong cũng mất theo, kể cả khi không ai cố ý gõ lệnh xoá. Image cập nhật, Docker tạo lại container mới, và toàn bộ workflow, lịch sử chạy, credential lưu trong container cũ biến mất sạch.

Cách tránh là mount volume ra ngoài container ngay từ file `docker-compose.yml` đầu tiên, không đợi sự cố mới thêm vào:

Theo tài liệu docs.n8n.io, thiếu bước mount này là nguyên nhân phổ biến nhất khiến người mới tự host báo mất sạch workflow sau một lần `docker compose down`. Lệnh đó không xoá volume. Nhưng nếu volume chưa từng được khai báo, dữ liệu vốn dĩ chưa bao giờ ra khỏi container để lệnh đó có thể giữ lại.

Ba biến hay đặt sai nhất: timezone, webhook URL và HTTPS

Ba biến này không làm container chết, nên bản cài nhanh bỏ qua được. Hậu quả chỉ lộ khi chạy thật: lịch sai giờ, hệ thống ngoài không gọi tới được, đăng nhập bị đá ra.

Timezone lệch làm lịch chạy cronjob sai giờ thực tế

Container Docker mặc định chạy theo giờ UTC, lệch 7 tiếng so với giờ Việt Nam. Một workflow đặt lịch chạy 8 giờ sáng thực chất chạy lúc 15 giờ nếu biến `TZ` không được khai báo trong file compose. Báo cáo tự động vì thế gửi vào 3 giờ sáng thay vì 8 giờ như đã đặt.

Khai báo `TZ=Asia/Ho_Chi_Minh` và `GENERIC_TIMEZONE=Asia/Ho_Chi_Minh` cùng lúc. Biến đầu chỉnh giờ hệ thống của container. Biến sau n8n dùng riêng cho node Schedule Trigger và log hiển thị trên giao diện. Thiếu một trong hai, phần còn lại vẫn chạy theo UTC dù cái kia đã đúng giờ Việt Nam. Cách kiểm nhanh: chạy docker exec TEN_CONTAINER date rồi so với đồng hồ tường, lệch đúng 7 tiếng là dấu hiệu chắc chắn thiếu biến `TZ`.

Webhook URL đặt sai khiến hệ thống bên ngoài không gọi được vào n8n

n8n chạy bằng Docker thường nằm sau một domain và reverse proxy, không mở trực tiếp ra Internet bằng IP. Nếu biến `WEBHOOK_URL` không được đặt, n8n tự suy ra địa chỉ webhook từ URL nội bộ của container, ví dụ `http://localhost:5678`. Đó là địa chỉ mà Zalo OA, Google Sheets hay phần mềm kế toán bên ngoài không bao giờ gọi tới được.

Workflow trong giao diện trông hoàn toàn bình thường. Nút Active bật xanh. Nhưng không request nào từ bên ngoài chạm được vào node Webhook. Đặt đúng: `WEBHOOK_URL=https://n8n.tenmiendoanhnghiep.vn/`, khớp với domain thật đã trỏ DNS, có dấu gạch chéo ở cuối theo đúng cú pháp tài liệu yêu cầu.

HTTPS và secure cookie: hai biến phải đi cùng nhau

n8n chạy bằng Docker phía sau reverse proxy có TLS cần khai báo rõ giao thức. Không khai báo đúng, phần đăng nhập có thể chặn luôn chính người quản trị. Biến `N8N_SECURE_COOKIE` mặc định là `true`, buộc cookie phiên đăng nhập chỉ gửi qua kết nối HTTPS.

Vấn đề nảy sinh khi domain chưa gắn SSL nhưng biến này vẫn giữ giá trị mặc định. n8n cấp cookie yêu cầu HTTPS, trình duyệt chỉ nhận được HTTP, phiên đăng nhập bị từ chối ngay sau khi nhập đúng mật khẩu. Hai cách xử lý, chọn một: bật SSL cho domain trước rồi giữ nguyên mặc định. Hoặc tạm đặt `N8N_SECURE_COOKIE=false` trong lúc thử nghiệm nội bộ chưa có chứng chỉ. Reverse proxy như Nginx hay Caddy cũng cần forward đúng header `X-Forwarded-Proto`, để n8n biết request gốc là HTTPS chứ không phải suy đoán từ kết nối nội bộ.

Encryption key mất là mất luôn quyền đọc mọi credential đã lưu

Mỗi lần n8n khởi động lần đầu, nó tự sinh một encryption key ngẫu nhiên để mã hoá toàn bộ credential lưu trong database: API key, mật khẩu, token OAuth. Key này không tự migrate sang container mới nếu không được khai báo tường minh bằng biến `N8N_ENCRYPTION_KEY`.

Container cũ chết. Container mới dựng lên với key sinh ngẫu nhiên khác. Database volume vẫn còn nguyên, nhưng mọi credential bên trong trở thành chuỗi mã hoá không đọc được bằng key mới. Không có lệnh khôi phục. Phải nhập lại từng credential bằng tay, việc mất vài giờ nếu workflow đã kết nối hàng chục tài khoản. Cách tránh triệt để: đặt cố định `N8N_ENCRYPTION_KEY` bằng một chuỗi ngẫu nhiên tự tạo, ghi lại nơi lưu trữ mật khẩu riêng, dùng đúng key đó cho mọi lần dựng lại hoặc di chuyển container sang máy khác.

Doanh nghiệp không có người rành Docker để tự soát các biến này trước khi đưa vào chạy thật có thể giao phần vận hành máy chủ cho dịch vụ quản trị máy chủ BizMaC, đội kỹ thuật kiểm cấu hình, theo dõi tài nguyên và xử lý khi container gặp sự cố.

Danh sách biến môi trường cần đặt trước khi chạy thật

Trước khi đưa n8n chạy bằng Docker vào môi trường thật, đối chiếu qua bảng dưới một lượt. Đừng chờ sự cố mới quay lại sửa từng biến một.

Chạy nhiều instance n8n trên cùng một VPS, ví dụ một bản test và một bản chạy thật, thì mỗi container cần cổng riêng và tên volume riêng. Trộn chung là tranh cổng 5678 mặc định hoặc ghi đè dữ liệu lên nhau.

Không muốn dò từng biến môi trường thì gói VPS n8n cài sẵn đã khai sẵn phần này từ lúc bàn giao.

Câu hỏi thường gặp khi chạy n8n bằng Docker

Tóm tắt

n8n chạy bằng Docker không khó dựng. Nhưng 5 biến trong bảng trên quyết định workflow có sống sót qua lần restart đầu tiên hay không: volume để giữ dữ liệu, timezone để lịch chạy đúng giờ, webhook URL để hệ thống ngoài gọi vào được, secure cookie để đăng nhập không bị chặn, và encryption key để không mất credential khi đổi container. Đặt đúng cả 5 biến trước khi đưa vào chạy thật. Đừng đợi lỗi xuất hiện mới quay lại sửa từng cái một.