n8n 3.0 loại bỏ cài đặt qua npm và làm hỏng các node workflow cũ

Nền tảng tự động hóa n8n đang chuẩn bị cho bản phát hành phiên bản lớn 3.0, giới thiệu những thay đổi mang tính phá vỡ (breaking changes) đáng kể đối với các instance tự lưu trữ. Được phát hành dưới dạng beta vào ngày 27 tháng 10 năm 2026, với kế hoạch ra mắt ổn định vào đầu tháng 12, bản cập nhật này thay đổi căn bản cách triển khai phần mềm cũng như cách hoạt động của các workflow hiện có. Các đội ngũ vận hành máy chủ n8n riêng cần chuẩn bị sẵn sàng cho những thay đổi hạ tầng bắt buộc và việc tái cấu trúc mã nguồn trước khi cửa sổ nâng cấp đóng lại.

Chuyện gì đã xảy ra

Thay đổi vận hành tức thời nhất là việc loại bỏ các phương pháp cài đặt dựa trên npm. Phiên bản 3.0 sẽ không xuất bản gói n8n có thể chạy được lên npm, đồng nghĩa với việc các lệnh như npm install n8n hoặc npx n8n không còn được hỗ trợ. Người dùng tự lưu trữ phải chuyển sang sử dụng container Docker để chạy phần mềm. Sự thay đổi này cũng bao gồm việc điều chỉnh đường dẫn lưu trữ tệp; thư mục cũ ~/.n8n/binaryData được thay thế bằng ~/.n8n/storage. Ứng dụng sẽ từ chối khởi động nếu cả hai thư mục này cùng tồn tại, đòi hỏi phải dọn dẹp thủ công trong quá trình chuyển đổi. Ngoài ra, việc xoay vòng khóa mã hóa (encryption key rotation) giờ đây được bật theo mặc định, và node Compression áp đặt các giới hạn nghiêm ngặt hơn, giới hạn thao tác ở mức 256 MiB hoặc 1.000 mục.

Ngoài vấn đề hạ tầng, bản cập nhật còn loại bỏ một số node và chức năng cốt lõi vốn đã bị ngừng hỗ trợ (deprecated) trong các phiên bản trước đó. Các trigger Cron và Interval đã biến mất, được thay thế hoàn toàn bởi Schedule Trigger. Các node cũ như Function, Function Item và Item Lists đã bị xóa, khiến các lần thực thi thất bại nếu chúng vẫn còn xuất hiện trong các workflow cũ. Công cụ di chuyển có thể chuyển đổi một số node này sang Code nodes, nhưng cần phải xem xét thủ công. Hơn nữa, phương thức biểu thức $getPairedItem đã bị loại bỏ khỏi Code nodes, đòi hỏi các nhà phát triển phải cập nhật script của họ để sử dụng các giải pháp thay thế như .itemMatching() hoặc .pairedItem().

Các thiết lập về bảo mật và tích hợp cũng được thắt chặt. Trigger Slack giờ đây yêu cầu Signature Secret trong thông tin đăng nhập (credentials), điều này sẽ làm gián đoạn các luồng phê duyệt và cảnh báo hiện có nếu không được cập nhật. Nền tảng đã mở rộng danh sách chặn Server-Side Request Forgery (SSRF) để bao gồm dải 100.64.0.0/10 theo mặc định, có khả năng chặn kết nối đến một số dịch vụ nội bộ riêng tư trừ khi chúng được thêm vào danh sách cho phép (allow-list) rõ ràng thông qua biến môi trường. Các gói cộng đồng chưa xác minh bị vô hiệu hóa theo mặc định, nghĩa là các node tùy chỉnh từ bên thứ ba sẽ không tải trừ khi người dùng chấp nhận rủi ro một cách tường minh bằng cách thiết lập cờ biến môi trường.

Chi tiết chính

• Thay đổi triển khai: Cài đặt qua npm và npx không còn được hỗ trợ; người dùng phải chuyển sang Docker.
• Loại bỏ node: Các node Cron, Interval, Function, Function Item và Item Lists bị xóa.
• Thay đổi mã nguồn: $getPairedItem bị loại bỏ; thời gian chờ mặc định cho tác vụ Code giảm từ 300 giây xuống 60 giây.
• Tích hợp Slack: Trigger giờ đây bắt buộc phải có Signature Secret trong cấu hình thông tin đăng nhập.
• Đường dẫn lưu trữ: ~/.n8n/binaryData được đổi tên thành ~/.n8n/storage; đường dẫn cũ phải được xóa.
• Dòng thời gian hỗ trợ: Hỗ trợ cho phiên bản 1.x kết thúc vào ngày 31 tháng 12 năm 2026; các bản vá bảo mật cho 2.x kết thúc sau 12 tháng kể từ khi phiên bản 3.x ổn định được phát hành.

Bối cảnh

n8n là một công cụ tự động hóa workflow cho phép người dùng kết nối các ứng dụng và dịch vụ khác nhau thông qua giao diện trực quan. Đối với nhiều công ty, đặc biệt là những đơn vị xử lý dữ liệu nhạy cảm, việc tự lưu trữ n8n giúp kiểm soát nơi dữ liệu được lưu trữ và cách nó được xử lý. Tuy nhiên, duy trì phần mềm tự lưu trữ đòi hỏi phải theo kịp các thay đổi từ phía nhà phát triển gốc (upstream). Những thay đổi mang tính phá vỡ trong các phiên bản lớn thường liên quan đến việc loại bỏ các tính năng đã lỗi thời nhằm giảm nợ kỹ thuật và cải thiện bảo mật. Trong bối cảnh này, việc loại bỏ hỗ trợ npm giúp đơn giản hóa gánh nặng bảo trì cho các nhà phát triển bằng cách tập trung vào một mô hình triển khai container hóa duy nhất. Tương tự, việc loại bỏ các node cũ buộc người dùng phải áp dụng các thực hành lập trình hiện đại, hiệu quả và an toàn hơn trong workflow của họ.

Tại sao điều này quan trọng

Đối với các đội ngũ quản lý hạ tầng tự động hóa riêng, bản nâng cấp này không phải là tùy chọn nếu họ muốn tiếp tục được hỗ trợ. Việc loại bỏ hỗ trợ npm có nghĩa là bất kỳ pipeline CI/CD hoặc thiết lập máy chủ hiện có nào phụ thuộc vào việc cài đặt node trực tiếp sẽ gặp sự cố khi nâng cấp. Điều này đòi hỏi phải tái kiến trúc cơ bản các script triển khai. Hơn nữa, việc giảm cứng nhắc thời gian chờ (hard timeout) cho Code nodes từ 300 giây xuống 60 giây có thể khiến các phép biến đổi dữ liệu chạy lâu bị thất bại ngoài dự kiến. Các đội ngũ xử lý tập dữ liệu lớn hoặc thực hiện tính toán phức tạp trong code node JavaScript phải tối ưu hóa script của họ hoặc cấu hình biến môi trường N8N_RUNNERS_TASK_TIMEOUT để ngăn ngừa sự cố ngừng hoạt động trong môi trường production.

Tác động đối với các workflow kinh doanh then chốt là rất lớn. Các luồng xử lý đơn hàng, hóa đơn hoặc biến động kho thường phụ thuộc vào các node cũ hoặc trigger định thời cụ thể. Nếu những yếu tố này không được xác định và di chuyển trước khi nâng cấp, hoạt động kinh doanh có thể bị đình trệ. Yêu cầu xác minh thủ công các workflow được tự động di chuyển bổ sung thêm một lớp công việc đảm bảo chất lượng không thể bỏ qua. Ngoài ra, các biện pháp bảo vệ SSRF nghiêm ngặt hơn có thể âm thầm chặn các cuộc gọi API nội bộ vốn được cho phép trước đây, đòi hỏi các đội ngũ mạng phải xem xét và cập nhật danh sách cho phép cho các dải IP riêng tư.

Bạn có thể làm gì

• Kiểm tra phiên bản hiện tại: Nếu bạn đang dùng phiên bản 1.x, hãy nâng cấp lên 2.x trước, vì không có đường dẫn trực tiếp để nâng cấp lên 3.x.
• Chạy Báo cáo Di chuyển (Migration Report): Sử dụng công cụ tích hợp sẵn trong Settings (có sẵn trong n8n 2.39+) để xác định các vấn đề về workflow và instance.
• Ưu tiên các luồng quan trọng: Sửa chữa các workflow liên quan đến giao dịch tài chính hoặc tồn kho trước tiên, và xem xét cẩn thận mã nguồn được tự động di chuyển.
• Kiểm toán Code nodes: Tìm kiếm các phương thức đã bị ngừng hỗ trợ như $getPairedItem và xác định các tác vụ chạy lâu hơn 60 giây.
• Thử nghiệm trong staging: Sao lưu instance production của bạn, khôi phục nó vào môi trường staging, nâng cấp và phát lại các input thực tế để xác minh số lượng bản ghi.
• Lên lịch thời gian chết: Thực hiện bản nâng cấp cuối cùng trong một khoảng thời gian yên tĩnh và xác nhận rằng tất cả các workflow theo lịch trình kích hoạt đúng cách sau đó.