# n8n

> Cài n8n từ Kho ứng dụng, tạo tài khoản chủ sau khoá thiết lập, sao lưu workflow và khoá mã hoá, cập nhật và làm việc trong giới hạn mạng của container.

Source: https://zopanel.net/vi/docs/app-n8n  
Updated: 2026-10-09

n8n là công cụ tự động hoá quy trình bằng giao diện kéo thả, một lựa chọn tự host thay cho Zapier hay Make: một sự kiện kích hoạt (webhook, lịch hẹn giờ, email mới) chạy một chuỗi bước gọi API, xử lý dữ liệu và gửi tin nhắn. Hãy chọn n8n khi bạn tự động hoá công việc giữa nhiều dịch vụ online, không muốn trả phí theo số tác vụ và muốn dữ liệu nằm trên máy chủ của mình. Trang này hướng dẫn cài từ **Kho ứng dụng**, thiết lập lần đầu, sao lưu, cập nhật và những gì container được hoặc không được kết nối tới.

## Yêu cầu

| Mục | Giá trị |
| --- | --- |
| Image | `n8nio/n8n:2.42.5` |
| Giới hạn RAM | 1024 MB, 1 CPU |
| Đĩa trống để cài | Khoảng 2,6 GB trên ổ của Docker ở lần cài đầu (image cộng 1 GB chừa lại cho máy chủ) |
| Docker | Đã cài trên máy chủ (**Kho ứng dụng → Cài Docker**) |
| Tên miền | Tên miền hoặc tên miền phụ có bản ghi A trỏ về máy chủ, ví dụ `n8n.example.com` |

Giới hạn RAM được tính vào RAM của gói hosting. Workflow lớn giữ nhiều item hoặc file lớn trong bộ nhớ có thể cần hơn 1 GB; xem mục Xử lý sự cố.

## Cài n8n

### Với quản trị viên

1. Mở **Kho ứng dụng**. Nếu thấy **Cần cài Docker**, bấm **Cài Docker** trước và chờ tác vụ chạy xong.
2. Trên thẻ **n8n**, bấm **Cài đặt**.
3. Điền hộp thoại:

   | Trường | Nội dung |
   | --- | --- |
   | **Tên miền** | Tên miền ứng dụng chạy, không gồm `http://`, ví dụ `n8n.example.com`. Hệ thống tạo một website mới cho tên miền này. |
   | **Chủ sở hữu** | Tài khoản hosting sở hữu ứng dụng. Giới hạn của gói tài khoản áp dụng cho container. |
   | **SSL miễn phí (Let's Encrypt)** | Để bật. Chứng chỉ được cấp ở cuối quá trình cài nếu tên miền đã trỏ về máy chủ. |

4. Bấm **Cài đặt**. Log tác vụ hiển thị quá trình tải image, khởi động container và cuối cùng là `n8n is available at http://<tên miền>`.
5. Nếu log báo `SSL could not be issued yet`, trỏ bản ghi A của tên miền về máy chủ rồi bấm **Cấp chứng chỉ** trong tab **SSL** của website (xem [Chứng chỉ SSL](/vi/docs/ssl)).

n8n không có trường cài đặt bổ sung. ZoPanel tự đặt các biến sau:

| Biến | Giá trị | Mục đích |
| --- | --- | --- |
| `N8N_HOST`, `N8N_PROTOCOL`, `N8N_PORT` | tên miền của bạn, `https`, `5678` | Địa chỉ n8n dùng để tạo đường dẫn |
| `WEBHOOK_URL` | `https://<tên miền>/` | URL webhook trong trình soạn thảo dùng tên miền của bạn qua HTTPS |
| `GENERIC_TIMEZONE` | `Asia/Ho_Chi_Minh` | Múi giờ của trigger hẹn giờ và các hàm ngày giờ |
| `N8N_ENCRYPTION_KEY` | khoá ngẫu nhiên, riêng cho mỗi lần cài | Mã hoá credential lưu trong n8n |
| `N8N_PROXY_HOPS` | `1` | n8n tin nginx đứng trước để lấy IP người truy cập |

Các biến này không sửa được từ panel. Muốn dùng múi giờ khác, đặt riêng cho từng workflow trong n8n (**Workflow settings → Timezone**).

### Với khách hàng

Khách tự cài từ **Kho ứng dụng** trong panel của mình khi gói hosting cho phép. Đầu trang hiển thị hạn mức, ví dụ "Gói của bạn: 0/2 ứng dụng · RAM 0/4096 MB." Không có trường **Chủ sở hữu**: ứng dụng thuộc tài khoản của bạn.

Quản trị viên đặt hạn mức tại **Gói hosting → Ứng dụng Docker** (`0` = không cho phép) và **RAM (MB)**. n8n cần 1024 MB trong RAM của gói. Xem [Gói hosting và giới hạn](/vi/docs/packages-limits).

## Thiết lập lần đầu

n8n vừa cài nằm sau **khoá thiết lập**: người đầu tiên mở n8n sẽ tạo tài khoản chủ, nên ZoPanel hiển thị trang "đang được thiết lập" cho mọi người khác tới khi bạn làm xong.

**Quan trọng:** chờ SSL được cấp rồi mới thiết lập n8n. ZoPanel chạy n8n với `N8N_PROTOCOL=https`, và cookie đăng nhập của n8n chỉ hoạt động qua HTTPS.

1. Mở website (**Website → n8n.example.com**) và vào tab **Docker**. Chờ trạng thái là `running`.
2. Trong thẻ **Đang khoá thiết lập**, bấm **Mở ứng dụng (chỉ mình tôi)**. Một tab mới mở tên miền; trình duyệt này được đi qua khoá (trong 30 ngày).
3. Lần khởi động đầu mất khoảng nửa phút. Nếu trang báo site đang bận hoặc "n8n is starting up", hãy chờ, trang tự tải lại.
4. Ở màn hình tạo tài khoản chủ, nhập email, họ tên và mật khẩu (tối thiểu 8 ký tự, có số và chữ hoa), rồi bấm **Next**.
5. Trả lời hoặc bỏ qua bảng câu hỏi ngắn. n8n có thể mời bạn nhận license key miễn phí cho một số tính năng cộng đồng; việc này không bắt buộc.
6. Quay lại tab **Docker**, bấm **Đã thiết lập xong — mở công khai**. Khoá được gỡ và webhook bắt đầu nhận yêu cầu từ bên ngoài.

**Lưu ý:** khi khoá còn bật, lời gọi webhook từ dịch vụ bên ngoài cũng nhận trang "đang được thiết lập". Hãy mở công khai trước khi thử webhook production.

## Thiết lập cần thiết

- **Người dùng:** mở **Settings → Users → Invite** để thêm đồng nghiệp. Bình thường n8n gửi lời mời qua email; bản n8n của ZoPanel không có cấu hình SMTP cho việc này, nên hãy sao chép link mời n8n hiển thị và tự gửi. Không có tính năng đặt lại mật khẩu qua email, vì vậy hãy lưu mật khẩu tài khoản chủ trong trình quản lý mật khẩu.
- **Webhook:** URL webhook production có dạng `https://n8n.example.com/webhook/<path>`, URL thử nghiệm là `https://n8n.example.com/webhook-test/<path>`. Workflow phải được kích hoạt (active) thì URL production mới trả lời.
- **Credential:** API key và mật khẩu lưu trong **Credentials** được mã hoá bằng `N8N_ENCRYPTION_KEY`. Hãy giữ khoá này cùng bản sao lưu (xem bên dưới).
- **Gửi email từ workflow:** node **Send Email** dùng được với mọi máy chủ SMTP. Hộp mail tạo trên panel dùng được: host = tên máy chủ mail của bạn, cổng `587` (STARTTLS) hoặc `465` (SSL), địa chỉ đầy đủ và mật khẩu.

## Container kết nối được tới đâu

Mọi container của Kho ứng dụng chạy sau tường lửa container của ZoPanel:

| Đích | Được phép? |
| --- | --- |
| Dịch vụ và API trên internet (HTTPS, mọi địa chỉ công khai) | Có |
| Website trên máy chủ này qua tên miền công khai (cổng 80/443) | Có |
| Mail trên máy chủ này (cổng 25, 465, 587) | Có |
| DNS | Có |
| MariaDB, PostgreSQL, Redis hoặc panel trên máy chủ này | **Không** |
| Mạng nội bộ (10.x, 172.16–31.x, 192.168.x, 100.64.x), loopback, metadata của cloud | **Không** |
| Container khác | **Không** |

Ý nghĩa với n8n:

- **Node MySQL/MariaDB, Postgres hay Redis trỏ vào máy chủ này sẽ không kết nối được.** `localhost` và `127.0.0.1` bên trong container là chính container đó, và cổng database của máy chủ bị chặn với container, kể cả khi đã bật [Truy cập từ xa](/vi/docs/databases). Thay vào đó, hãy:
  - đặt một endpoint HTTPS nhỏ trên một website của bạn (ví dụ script PHP đọc/ghi database bằng thông tin đăng nhập riêng của nó) rồi gọi bằng node **HTTP Request**;
  - dùng database trên máy chủ khác, cho phép kết nối từ IP công khai của máy chủ này.
- Gọi chính các website của bạn qua tên miền công khai vẫn được, gọi API công khai cũng vậy.
- Dịch vụ trong mạng nội bộ (Ollama hay database ở địa chỉ VPC, NAS ở nhà) không kết nối được.

## Dữ liệu nằm ở đâu và sao lưu

Dữ liệu ứng dụng nằm trong `/var/lib/zopanel-apps/<instance>/`, với `<instance>` là tên miền đổi dấu chấm thành gạch ngang (`n8n.example.com` → `n8n-example-com`). Container có tên `zp-app-<instance>`.

| Đường dẫn trên máy chủ | Nội dung |
| --- | --- |
| `/var/lib/zopanel-apps/<instance>/data/` | Thư mục `/home/node/.n8n` của n8n: database SQLite chứa workflow, credential và lịch sử chạy, cùng file cấu hình của n8n |
| `/var/lib/zopanel-apps/<instance>/.env` | Các biến ở trên, gồm `N8N_ENCRYPTION_KEY` (chỉ root đọc được) |

**ZoPanel sao lưu gì và không sao lưu gì:**

- Thẻ **Sao lưu** trong tab **Docker** của website sao lưu toàn bộ thư mục ứng dụng, gồm dữ liệu và file `.env` chứa khoá mã hoá.
- Bản sao lưu tài khoản và sao lưu gia tăng gồm thư mục website, database và hộp mail của tài khoản. **Chúng không gồm `/var/lib/zopanel-apps`**, nên workflow và credential của n8n chỉ nằm trong bản sao lưu riêng của ứng dụng.
- Bản sao lưu cấu hình (`.zpb`, xem [Cứu hộ thảm họa](/vi/docs/disaster-recovery)) chứa database của panel, nơi lưu thiết lập của ứng dụng và các biến được tạo tự động, gồm cả khoá mã hoá. Nó không chứa dữ liệu của n8n.

Để sao lưu n8n, bấm **Sao lưu ngay** trong thẻ **Sao lưu**. Quản trị viên còn đặt được **Lịch** (**Tắt**, **Mỗi ngày** hoặc **Mỗi tuần**; mặc định tắt) và số bản **Giữ lại** (1–60, mặc định 7), rồi bấm **Lưu**. Mỗi bản sao lưu nén `/var/lib/zopanel-apps/<instance>/` thành `/var/backups/zopanel-apps/<instance>/YYYYMMDD-HHMMSS.tar.gz`, trong thư mục chỉ root đọc được và không tính vào dung lượng đĩa của tài khoản. Container được tạm dừng (pause, không phải stop) trong vài giây sao chép, nên bản sao nhất quán. Các bản cũ vượt quá số **Giữ lại** bị xoá, và khi một lần sao lưu theo lịch thất bại, quản trị viên nhận cảnh báo **Sao lưu thất bại**.

Để khôi phục, quản trị viên bấm **Khôi phục** cạnh một bản sao lưu (khách hàng nhờ nhà cung cấp). n8n được dừng và dữ liệu được thay bằng nội dung file nén; dữ liệu hiện tại được giữ riêng tới khi ứng dụng khôi phục khởi động được, và được đặt lại nếu nó không khởi động. Mọi thay đổi sau thời điểm sao lưu sẽ mất. Mỗi bản sao lưu còn có nút xoá (chỉ quản trị viên), và xoá ứng dụng kèm file của nó cũng xoá luôn các bản sao lưu.

Các file nén này không nằm trong bản sao lưu tài khoản và vẫn ở trên cùng máy chủ. Hãy chép những bản quan trọng ra ngoài (ví dụ bằng `scp` hoặc `rclone` từ `/var/backups/zopanel-apps/<instance>/`) và lưu ở dạng mã hoá: chúng chứa khoá mã hoá. Hãy khôi phục file nén vào chính bản cài đó; bản cài mới trên máy chủ khác có khoá mã hoá riêng, nên hãy chuyển workflow và credential sang bằng bản xuất bên dưới.

Bản xuất di động, nhập được vào bất kỳ n8n nào:

```bash
docker exec -u node zp-app-n8n-example-com n8n export:workflow --all --output=/home/node/.n8n/workflows.json
docker exec -u node zp-app-n8n-example-com n8n export:credentials --all --decrypted --output=/home/node/.n8n/credentials.json
```

Các file xuất hiện trong `/var/lib/zopanel-apps/n8n-example-com/data/`. File credential chứa bí mật ở dạng chữ thường: chuyển nó tới nơi an toàn và xoá khỏi máy chủ. Nhập vào n8n khác bằng `n8n import:workflow --input=…` và `n8n import:credentials --input=…`.

Khách hàng không chạy được các lệnh này, nhưng có thể bấm **Sao lưu ngay** trong tab **Docker**; việc đặt lịch và khôi phục do nhà cung cấp thực hiện. Để tự giữ một bản, hãy tải các workflow quan trọng từ trình soạn thảo (**Download** trong menu của workflow).

## Cập nhật n8n

1. Sao lưu trước (**Sao lưu ngay** trong thẻ **Sao lưu**). n8n chuyển đổi database khi khởi động và bản cập nhật không hoàn tác được từ panel.
2. Trong tab **Docker** của website, bấm **Cập nhật bản mới** (chỉ quản trị viên; khách hàng nhờ nhà cung cấp).
3. Tác vụ kéo image có trong danh mục ZoPanel hiện tại và tạo lại container. Dữ liệu và khoá mã hoá được giữ. n8n gián đoạn khoảng một phút trong lúc khởi động lại.

Danh mục ghim một phiên bản n8n cụ thể (`2.42.5`), nên **Cập nhật bản mới** cài phiên bản đi kèm bản ZoPanel bạn đang dùng; các bản n8n mới hơn đến cùng [bản cập nhật ZoPanel](/vi/docs/updating).

## Xử lý sự cố

| Hiện tượng hoặc thông báo | Cách xử lý |
| --- | --- |
| Khách truy cập hoặc webhook nhận trang "This app is being set up" | Khoá thiết lập vẫn bật. Bấm **Đã thiết lập xong — mở công khai** trong tab **Docker**. |
| n8n cảnh báo về secure cookie, hoặc đăng nhập bị lặp | Bạn đang mở qua `http://`. Cấp SSL cho tên miền rồi mở `https://<tên miền>`. |
| `not enough disk space: this app needs about 2.6 GB free and the server has … GB; free some space first` | Giải phóng dung lượng đĩa trên máy chủ rồi cài lại. |
| `your plan does not include applications; ask your provider` / `your plan allows N application(s)` | Hạn mức **Ứng dụng Docker** của gói bằng 0 hoặc đã dùng hết. |
| `n8n needs 1024 MB of memory; your plan has … MB and your apps use … MB` | Tăng **RAM (MB)** của gói hoặc gỡ một ứng dụng khác. |
| `the app did not start listening: …` | Container không trả lời trong 2 phút. Đọc phần cuối thông báo và **Log ứng dụng** trong tab **Docker**, rồi bấm **Khởi động lại**. |
| Node MySQL/Postgres/Redis bị timeout hoặc bị từ chối | Đúng như thiết kế với database trên máy chủ này hoặc trong mạng nội bộ; xem mục Container kết nối được tới đâu. |
| Workflow lớn bị dừng giữa chừng và container khởi động lại | Đã chạm giới hạn 1024 MB. Xử lý item theo lô nhỏ (**Loop Over Items**) và tránh giữ file lớn trong bộ nhớ. |
| n8n không khởi động sau khi khôi phục dữ liệu vào một bản cài mới, báo lỗi khoá mã hoá không khớp | Dữ liệu đến từ bản cài có khoá khác. Khôi phục bản sao lưu vào bản cài gốc, hoặc chuyển workflow và credential bằng lệnh export/import. |
| Mất quyền vào tài khoản chủ | Bằng root: `docker exec -u node zp-app-<instance> n8n user-management:reset`, rồi thiết lập lại tài khoản chủ. Lệnh này xoá mọi người dùng; workflow và credential được giữ. |

## Xem thêm

- [Kho ứng dụng và lưu trữ S3](/vi/docs/apps)
- [Từng ứng dụng dùng để làm gì](/vi/docs/app-catalog)
- [Gói hosting và giới hạn](/vi/docs/packages-limits)
- [Cơ sở dữ liệu](/vi/docs/databases)
- [Sao lưu](/vi/docs/backups)
- [Tài liệu n8n](https://docs.n8n.io) và [lệnh CLI](https://docs.n8n.io/hosting/cli-commands/)