n8n 2.48.5 là bản stable phát hành ngày 18/11/2026. Đây chủ yếu là bản vá: release notes chính thức liệt kê 10 bug fixes, nổi bật ở AI Agent, expression engine, quyền credential trong team project, Microsoft Teams Trigger và Qdrant. Bản phát hành không liệt kê breaking change, nhưng người self-host vẫn phải backup trước khi nâng cấp vì n8n có thể chạy migration cơ sở dữ liệu khi khởi động.
Nếu đang dùng Docker Compose, nguyên tắc quan trọng nhất là: chỉ thay image, không xóa volume; giữ nguyên database và encryption key. Lệnh docker compose down không xóa named volume, nhưng docker compose down -v thì có. Một ký tự -v dùng nhầm có thể khiến instance SQLite khởi động như cài mới.

n8n 2.48.5 sửa những lỗi nào đáng chú ý?
GitHub đánh dấu n8n@2.48.5 là bản không phải prerelease và công bố lúc 08:50 UTC ngày 18/11/2026. Tài liệu cài Docker của n8n cũng ghi stable hiện tại là 2.48.5 tại thời điểm biên soạn.
AI Agent ổn định hơn khi xử lý nhiều item và streaming
Hai bản sửa trực tiếp liên quan AI Agent Node:
- Tách lịch sử tool call theo từng input item: Trước đây, khi một execution đưa nhiều item vào AI Agent, lịch sử gọi tool có thể không được cô lập đúng giữa các item. Bản vá giữ history riêng cho từng item, giảm nguy cơ ngữ cảnh của item này ảnh hưởng item khác.
- Không tự chèn newline giữa các chunk streaming: Nội dung model trả theo luồng không còn bị thêm dấu xuống dòng giữa các đoạn text, giúp output cuối giữ đúng định dạng hơn.
Nếu workflow của bạn chạy AI Agent theo batch, có tool hoặc trả kết quả streaming cho chat UI, đây là hai lý do thực tế để ưu tiên kiểm thử 2.48.5.
Sửa expression và dữ liệu Error trong sandbox
Phần core có hai thay đổi đáng chú ý cho workflow dùng expression phức tạp:
- Việc đọc thuộc tính dấu dollar được chuyển cho expression engine xử lý, thay vì đường đánh giá nhanh tự quyết định. Mục tiêu là giữ hành vi nhất quán với engine, nhất là dữ liệu XML/RSS có key
$. - Các object nhỏ nằm bên trong một đối tượng
Errorđược giữ lại trong sandboxed expressions. Điều này hữu ích khi node database hoặc SDK trả lỗi có metadata lồng nhau.
Đây là bug fix về tính nhất quán, không phải thông báo thay đổi cú pháp expression. Tuy vậy, nên chạy lại workflow có Filter, Code, Execute Workflow hoặc biểu thức đọc dữ liệu lỗi trước khi kết thúc cửa sổ bảo trì.
Microsoft Teams Trigger không bỏ sót notification trong batch
Microsoft Teams có thể gửi nhiều change notification trong một request. Bản 2.48.5 sửa Trigger để phát ra mọi notification hợp lệ trong batch thành các item của cùng một execution, thay vì có nguy cơ chỉ xử lý không đầy đủ. Workflow đồng bộ message hoặc sự kiện Teams nên được test bằng một batch có nhiều thay đổi.
Qdrant, credential và team project
Các bản sửa còn lại đáng lưu ý gồm:
- Qdrant Vector Store giữ subpath của reverse proxy làm prefix cho client;
- Instance owner và admin được xem là thành viên team project khi kiểm tra quyền credential;
- Editor cho phép chuyển workflow vào team project mà không yêu cầu Sharing license;
- Fresh install nhận instance ID ngẫu nhiên;
- Kích thước chữ Callout Markdown trong editor được đồng bộ với cỡ chữ nhỏ.
Bản phát hành còn nêu hai feature nhỏ về audit event khi thay đổi Public API rate limit và một thử nghiệm taxonomy của n8n Assistant. Release notes không công bố breaking change cho 2.48.5; không nên tự suy diễn rằng bản này thay đổi database, credential hoặc license ngoài những mục upstream đã nêu.
Vì sao cập nhật Docker có thể làm mất workflow hoặc credential?
Container n8n là thành phần có thể tạo lại; dữ liệu bền vững phải nằm ngoài writable layer của container. Với cấu hình mặc định SQLite, workflow, credential và execution nằm trong database ở thư mục /home/node/.n8n. Thư mục này còn chứa encryption key được n8n tự sinh ở lần chạy đầu.
Với PostgreSQL, workflow và credential nằm trong PostgreSQL, nhưng n8n vẫn khuyến nghị persist /home/node/.n8n vì nơi này còn chứa encryption key, log instance và tài sản source control. Credential trong database được mã hóa; có database nhưng mất key tương ứng thì n8n không thể giải mã credential cũ.
Vì vậy cần giữ đủ ba lớp:
- Database: SQLite trong volume hoặc bản dump PostgreSQL;
- Encryption key: Volume
.n8n, hoặc đúng giá trịN8N_ENCRYPTION_KEYhiện dùng; - Cấu hình triển khai:
compose.yml,.env, secret file và cấu hình reverse proxy.
Nếu cần dựng mới từ đầu, xem hướng dẫn cài n8n trên VPS Ubuntu bằng Docker Compose và Traefik. Bài này chỉ tập trung cập nhật instance đang chạy.
Chuẩn bị trước khi cập nhật n8n Docker Compose
Ví dụ dưới đây giả định thư mục dự án là /opt/n8n, service tên n8n và dùng named volume gắn vào /home/node/.n8n. Hãy thay đường dẫn/tên service theo hệ thống thật.
Đầu tiên, ghi lại phiên bản và cấu hình hiện tại:
cd /opt/n8n
docker compose ps
docker compose exec -T n8n n8n --version
docker compose config -q
Xuất bản Compose đã resolve biến và sao lưu file cấu hình:
backup_dir="$HOME/n8n-backups/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$backup_dir"
docker compose config > "$backup_dir/compose.rendered.yml"
cp -a compose.yml "$backup_dir"/
cp -a .env "$backup_dir"/ 2>/dev/null || true
chmod -R go-rwx "$backup_dir"
printf 'Backup directory: %s\n' "$backup_dir"
File rendered và .env có thể chứa secret. Không upload chúng lên Git, cloud drive công khai hoặc gửi vào ticket hỗ trợ.
Backup instance dùng SQLite
Lấy tên named volume đang mount vào .n8n trước khi dừng container:
n8n_container="$(docker compose ps -q n8n)"
n8n_volume="$(docker inspect "$n8n_container" \
--format '{{range .Mounts}}{{if eq .Destination "/home/node/.n8n"}}{{.Name}}{{end}}{{end}}')"
test -n "$n8n_volume" || { echo 'Không tìm thấy named volume .n8n'; exit 1; }
printf 'n8n volume: %s\n' "$n8n_volume"
Dừng n8n để SQLite không ghi giữa lúc đóng gói, sau đó backup toàn bộ volume:
docker compose stop n8n
docker run --rm \
-v "$n8n_volume":/data:ro \
-v "$backup_dir":/backup \
alpine:3.22 sh -c 'tar -czf /backup/n8n-data.tar.gz -C /data .'
Chỉ chuyển sang bước nâng cấp sau khi file n8n-data.tar.gz tồn tại và có dung lượng hợp lý.
Backup instance dùng PostgreSQL
Dump database bằng chính container PostgreSQL, rồi dừng n8n và backup volume .n8n như trên:
docker compose exec -T postgres sh -c \
'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
> "$backup_dir/n8n-postgres.dump"
test -s "$backup_dir/n8n-postgres.dump"
docker compose stop n8n
Nếu service database không tên postgres, thay bằng tên thực tế. Không nâng major version PostgreSQL trong cùng cửa sổ với cập nhật n8n; đó là một quy trình migration riêng.
Cập nhật lên n8n 2.48.5

Nên ghim phiên bản trong .env thay vì dùng latest:
N8N_VERSION=2.48.5
Trong Compose, image nên tham chiếu biến và volume phải được giữ nguyên:
services:
n8n:
image: docker.n8n.io/n8nio/n8n:${N8N_VERSION}
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:
Nếu hệ thống đang đặt N8N_ENCRYPTION_KEY, phải giữ đúng giá trị cũ. Nếu trước đây để n8n tự sinh key trong .n8n, không tự thêm một key mới trong lần cập nhật này.
Kiểm tra và tạo lại stack theo quy trình cập nhật Docker Compose chính thức:
cd /opt/n8n
docker compose config -q
docker compose pull
docker compose down
docker compose up -d
Tuyệt đối không thêm -v vào lệnh down. docker compose down xóa container và network của project nhưng giữ named volume; down -v xóa cả volume đã khai báo.
Kiểm tra sau cập nhật
Không chỉ thấy container “Up” rồi kết luận thành công. Hãy kiểm tra phiên bản, log và health endpoint:
docker compose ps
docker compose exec -T n8n n8n --version
docker compose logs --tail=200 n8n
curl -fsS https://n8n.example.com/healthz
Sau đó đăng nhập và xác nhận:
- Danh sách workflow, credential và user vẫn đầy đủ;
- Mở thử một credential nhưng không cần hiển thị secret;
- Chạy manual một workflow quan trọng;
- Test webhook qua URL công khai;
- Test AI Agent nhiều item/streaming nếu đang dùng;
- Test Microsoft Teams Trigger hoặc Qdrant nếu liên quan;
- Theo dõi failed executions và log trong ít nhất một chu kỳ workflow.
Có thể tham khảo thêm bài bảo mật Docker Socket khi dùng Traefik nếu n8n đang được publish qua Traefik.
Rollback n8n 2.48.5 đúng cách

Nếu chỉ lỗi ở image và chưa có thay đổi dữ liệu, đặt N8N_VERSION về phiên bản cũ đã ghi lại rồi tạo lại container:
cd /opt/n8n
# Sửa N8N_VERSION về phiên bản cũ trong .env
docker compose pull
docker compose down
docker compose up -d
docker compose logs --tail=200 n8n
Rollback image không đảm bảo rollback database sau khi migration đã chạy. Nếu bản cũ báo schema không tương thích, dừng stack và restore database cùng volume .n8n từ cùng mốc backup.
Với SQLite, lệnh sau xóa dữ liệu hiện tại trong volume rồi giải nén bản backup:
docker compose down
docker run --rm \
-v "$n8n_volume":/data \
-v "$backup_dir":/backup:ro \
alpine:3.22 sh -c \
'find /data -mindepth 1 -maxdepth 1 -exec rm -rf {} + && tar -xzf /backup/n8n-data.tar.gz -C /data'
Với PostgreSQL tự host, tạo lại database rồi restore dump; sau đó restore volume .n8n bằng bản cùng mốc:
docker compose down
docker compose up -d postgres
docker compose exec -T postgres sh -c \
'dropdb -U "$POSTGRES_USER" --if-exists "$POSTGRES_DB" && createdb -U "$POSTGRES_USER" "$POSTGRES_DB"'
docker compose exec -T postgres sh -c \
'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
< "$backup_dir/n8n-postgres.dump"
Đặt lại N8N_VERSION cũ rồi chạy docker compose up -d. Không trộn database với encryption key từ backup khác. Hãy thử restore trên project tách biệt trước production.
Câu hỏi thường gặp
Có thể dùng tag latest để nhận n8n 2.48.5 không?
Có thể, nhưng production nên ghim 2.48.5 để việc triển khai và rollback có tính xác định. Tài liệu n8n phân biệt stable và beta; không dùng next/beta trên instance production nếu chưa kiểm thử.
docker compose down có xóa workflow không?
Không, nếu dữ liệu nằm trong named volume hoặc bind mount và bạn không dùng -v. Nhưng workflow vẫn có thể mất nếu trước đó database chỉ nằm trong filesystem của container hoặc Compose mới vô tình đổi tên/mount sang volume khác.
Backup workflow JSON có đủ không?
Không. Export workflow không bao gồm đầy đủ user, credential, execution, project và encryption key. Backup vận hành phải gồm database, .n8n/encryption key và cấu hình triển khai.
Có cần đổi N8N_ENCRYPTION_KEY khi cập nhật không?
Không. Cập nhật version không phải lúc rotate key. Thay key tùy tiện sẽ làm credential cũ không giải mã được. Chỉ thực hiện rotation theo quy trình riêng của n8n và backup database đầy đủ trước đó.
n8n 2.48.5 có breaking change không?
Release notes 2.48.5 không liệt kê breaking change. Đây không phải lý do để bỏ backup: migration database, custom/community node và cấu hình riêng vẫn có thể tạo rủi ro tương thích trong môi trường self-host.
Kết luận
n8n 2.48.5 là bản stable đáng cân nhắc cho hệ thống dùng AI Agent, Microsoft Teams Trigger, Qdrant hoặc expression phức tạp. Cách nâng cấp an toàn không phải chỉ là docker compose pull: cần ghim version, backup đúng database, giữ nguyên volume .n8n và encryption key, kiểm tra workflow thật, đồng thời chuẩn bị rollback cả image lẫn dữ liệu.
Sau khi hệ thống ổn định, bạn có thể thử một workflow thực tế qua bài thiết lập nhận email qua Telegram với n8n.
Nguồn tham khảo
- n8n GitHub — Release n8n@2.48.5 ngày 18/11/2026
- n8n Docs — Install with Docker: stable version và Updating Docker Compose
- n8n Docs — Install using Docker Compose
- n8n Docs — Deployment environment variables và N8N_ENCRYPTION_KEY
- n8n Docs — Cấu trúc database n8n
