Chuyển từ Easypanel sang Tugport: năm lỗi phát sinh và bài học kinh nghiệm

Vào ngày 24 tháng 10, một nhà phát triển đã di chuyển máy chủ sản xuất chính của họ từ nền tảng triển khai Easypanel sang Tugport, một công cụ mới mà họ đang xây dựng. Việc di chuyển bao gồm 14 dự án và 57 dịch vụ, trong đó có cơ sở dữ liệu, blog và bot, được thực hiện thông qua một dòng lệnh duy nhất. Mặc dù quá trình chuyển đổi nhìn chung thành công, nhưng năm vấn đề cụ thể đã nảy sinh, làm nổi bật những cạm bẫy phổ biến trong việc tự động hóa di chuyển hạ tầng.

Điều gì đã xảy ra

Quá trình di chuyển bắt đầu bằng một lần chạy thử (dry run) để lập bản đồ các dịch vụ mà không thay đổi cấu hình, sau đó là việc thực thi lệnh tugport migrate easypanel. Tugport, một binary viết bằng Rust hoạt động song song với Docker, đã nhập trạng thái từ Easypanel, bao gồm các dự án, biến môi trường, tên miền và chứng chỉ. Sau đó, nó di chuyển từng cơ sở dữ liệu một, đảm bảo rằng phiên bản cũ dừng lại trước khi phiên bản mới khởi động trên cùng thư mục dữ liệu để tránh hỏng hóc. Các ứng dụng được khởi động cạnh phiên bản cũ của chúng bằng cách sử dụng chính xác các image giống nhau, tránh việc build lại trong quá trình chuyển đổi.

Việc chuyển hướng lưu lượng truy cập diễn ra khi proxy của Tugport tiếp quản các cổng 80 và 443 từ proxy Traefik của Easypanel trong vòng nửa giây. Một cơ chế an toàn đảm bảo rằng nếu proxy mới không phản hồi trong vòng 30 giây, proxy cũ sẽ giành lại quyền kiểm soát. Hệ thống ghi nhật ký mọi bước, cho phép tiếp tục hoặc hoàn tác nếu cần thiết. Các volume và bind mount vẫn giữ nguyên vị trí, và chứng chỉ được nhập vào thay vì cấp phát lại. Cuối cùng, 54 dịch vụ chạy trên Tugport, trong khi ba dịch vụ trước đó đã thu nhỏ quy mô vẫn ở trạng thái dừng.

Mặc dù được thiết kế cẩn thận, năm lỗi đã xuất hiện trong lần di chuyển sản xuất đầu tiên này. Thứ nhất, các mẫu biến môi trường từ Easypanel, chẳng hạn như $(PROJECT_NAME), được sao chép nguyên văn thay vì được giải quyết giá trị, đòi hỏi phải sửa chữa thủ công. Thứ hai, các tên miền placeholder do Easypanel gán gây nhầm lẫn cho các kiểm tra sức khỏe của Tugport, khiến các dịch vụ phi web bị treo khi chờ phản hồi HTTP. Thứ ba, một xung đột subnet mạng xảy ra vì stack CI runner cũ vẫn giữ mạng được ghim (pinned network), yêu cầu dọn dẹp thủ công. Thứ tư, một mã lỗi vô hại được hiển thị trong các lần chạy lại, gây báo động không cần thiết. Cuối cùng, các bot Telegram polling gặp xung đột tạm thời khi cả phiên bản cũ và mới đều cố gắng lấy cập nhật đồng thời.

Chi tiết chính

• Việc di chuyển đã đưa 57 dịch vụ thuộc 14 dự án, bao gồm các cơ sở dữ liệu Postgres, MySQL và Mongo.
• Năm lỗi cụ thể được xác định: sao chép nguyên văn mẫu env, thất bại trong kiểm tra sức khỏe do tên miền placeholder, chồng chéo pool mạng, ghi log lỗi mang tính thẩm mỹ và xung đột polling của bot.
• Kiểm tra sức khỏe cơ sở dữ liệu ban đầu bị timeout dưới tải cao vì chúng chạy mỗi 5 giây với timeout 5 giây; các tham số này đã được điều chỉnh thành khoảng thời gian 30 giây với timeout 15 giây.
• Một tag Docker floating (mysql:9) đã gây ra nâng cấp phiên bản phụ ngoài ý muốn từ 9.7.0 lên 9.7.4, dẫn đến ba phút downtime.
• Công cụ migrator hiện nay ghim (pin) các image cơ sở dữ liệu vào đúng phiên bản của chúng và tự động giải quyết các mẫu biến môi trường.

Bối cảnh

Tugport là một bảng điều khiển triển khai self-hosted được viết bằng Rust. Nó hoạt động bên cạnh Docker trên máy chủ thuộc sở hữu của người dùng, xử lý các build từ git push, kết thúc HTTPS và quản lý dịch vụ. Khác với một số nền tảng trừu tượng hóa hạ tầng cơ bản, Tugport được thiết kế cho tính minh bạch và khả năng kiểm soát, cung cấp các API key có phạm vi (scoped) cho AI agents và các công cụ di chuyển tích hợp sẵn cho các đối thủ cạnh tranh như Easypanel và Coolify. Công cụ này là mã nguồn mở theo giấy phép MIT.

Easypanel là một bảng điều khiển quản lý máy chủ phổ biến giúp đơn giản hóa việc triển khai ứng dụng qua Docker. Nó sử dụng Traefik làm reverse proxy và quản lý các dịch vụ thông qua giao diện đồ họa. Khi di chuyển giữa các bảng điều khiển như vậy, thách thức không chỉ nằm ở việc di chuyển dữ liệu, mà còn ở việc dịch các sắc thái cấu hình, cài đặt mạng và logic kiểm tra sức khỏe vốn thường ngầm định trong nền tảng gốc.

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

Đối với các nhóm vận hành phần mềm self-hosted, nghiên cứu tình huống này minh họa rằng các cuộc di chuyển tự động hiếm khi diễn ra suôn sẻ. Ngay cả với một công cụ được thiết kế tốt, sự khác biệt trong cách các nền tảng xử lý biến môi trường, mạng nội bộ và kiểm tra sức khỏe có thể gây gián đoạn dịch vụ. Hiểu rõ các chế độ lỗi này giúp kỹ sư dự đoán rủi ro khi chuyển đổi nhà cung cấp hạ tầng hoặc công cụ. Nó nhấn mạnh nhu cầu về kiểm thử kỹ lưỡng và tầm quan trọng của việc đọc kỹ đầu ra của dry-run trước khi thực hiện các thay đổi trực tiếp.

Sự cố với tag Docker floating là lời nhắc nhở quan trọng cho các môi trường sản xuất. Việc dựa vào các tag mutable như latest hoặc tag chỉ chứa phiên bản lớn có thể dẫn đến các nâng cấp bất ngờ và downtime. Ghim image vào các phiên bản cụ thể đảm bảo tính tái lập và ổn định, một thực hành tốt thường bị bỏ quên cho đến khi một cuộc di chuyển buộc phải đánh giá lại cấu hình triển khai.

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

• Luôn chạy một cuộc di chuyển dry-run trước để xác định các vấn đề lập bản đồ, cấu hình thiếu và các dịch vụ sẽ không tự động chuyển đổi.
• Ghim tất cả container image vào các phiên bản cụ thể thay vì sử dụng tag floating để ngăn chặn các nâng cấp ngoài ý muốn trong quá trình redeploy.
• Xem xét và điều chỉnh khoảng thời gian và timeout của health check sau khi di chuyển, đặc biệt nếu nền tảng mới có các mẫu sử dụng tài nguyên mặc định khác nhau.
• Xác minh thủ công các biến môi trường sử dụng cú pháp template, vì các công cụ tự động có thể không giải quyết đúng các placeholder đặc thù của nền tảng.
• Lên kế hoạch cho các xung đột tạm thời trong các dịch vụ dựa trên polling, chẳng hạn như chat bot, bằng cách đảm bảo các phiên bản cũ đã dừng hoàn toàn trước khi phiên bản mới bắt đầu xử lý yêu cầu.
• Dọn dẹp các mạng cũ và tài nguyên không sử dụng sau khi di chuyển thành công để giải phóng dung lượng ổ đĩa và ngăn ngừa xung đột subnet.