Hướng Dẫn Sử Dụng

Quick Start

1. Bắt Đầu Nhanh

Những nguyên tắc cơ bản để người vận hành và người xem job cùng theo một flow rõ ràng, không lẫn giữa admin console và viewer.

Công cụ này giúp bạn di chuyển email từ máy chủ IMAP này sang máy chủ IMAP khác. Giao diện hiện hỗ trợ cả Tiếng Việt và Tiếng Anh để thuận tiện cho vận hành nội bộ lẫn chia sẻ với khách hàng.

Lưu ý quan trọng

Hai máy chủ nguồn và đích phải hỗ trợ giao thức IMAP.
Job Password: Bắt buộc nhập để mã hóa và bảo vệ phiên làm việc.

Bulk Workflow

2. Di Chuyển Hàng Loạt (Bulk Migration)

Checklist thao tác cho các đợt sync số lượng lớn, ưu tiên rõ host, CSV, job password và các tùy chọn an toàn trước khi chạy.

Phương pháp này phù hợp khi bạn cần di chuyển hàng chục hoặc hàng trăm tài khoản email cùng lúc.

Truy cập: Chọn nút Create New Job từ trang chủ ("Dashboard").
Cấu hình Server:
- Nhập host nguồn (Nơi chứa email cũ). Ví dụ: imap.gmail.com
- Nhập host đích (Nơi nhận email mới). Bạn có thể dùng các nút chọn nhanh (Presets) ngay trên form.
- Cổng (Port) thường là 993 (SSL/TLS) hoặc 143 (STARTTLS).
Chuẩn bị file CSV: Mở Excel hoặc Notepad, tạo file với cấu trúc đúng 4 cột, không có dòng tiêu đề (header do NOT provide):
Hình thức CSV
```
[email protected],pass_nguon1,[email protected],pass_dich1
[email protected],pass_nguon2,[email protected],pass_dich2
```
Lưu ý: Nếu mật khẩu có chứa dấu phẩy (,) hoặc ký tự đặc biệt, hãy bọc chúng trong dấu ngoặc kép ("...") hoặc thay đổi mật khẩu trước khi di chuyển.
Bảo mật Job (Job Password): Nhập một mật khẩu bảo mật (Job Password) cho phiên di chuyển này. Bạn sẽ cần mật khẩu này để:
- Xem chi tiết tiến trình trong Dashboard.
- Tải file log hoặc xuất báo cáo.
Tuỳ chọn nâng cao (Advanced Options): Mở "Advanced Settings" nếu bạn muốn:
- Sync Internal Dates: Kéo nguyên gốc ngày tháng của email cũ.
- Skip Trash: Bỏ qua thư mục Thùng rác (giảm thời gian).
- Dry Run: Chỉ chạy giả lập để kiểm tra lỗi, không copy mail thật.
Kéo thả file CSV vào khu vực tải lên và nhấn Start Bulk Migration.

Single Mailbox

3. Đồng Bộ Đơn Lẻ (Single Sync)

Gọn hơn cho các ca test, recovery hoặc các đợt chuyển từng mailbox cần kiểm soát thủ công cao hơn.

Khuyên dùng nếu bạn chỉ cần chuyển email cho 1 tài khoản duy nhất.

Tại trang Create Job, chọn Tab Single Sync.
Cấu hình máy chủ Nguồn và Đích (giống phần Bulk).
Điền trực tiếp thông tin tài khoản người dùng và mật khẩu Nguồn vào form.
Điền thông tin tài khoản người dùng và mật khẩu Đích vào form.
Nhập Job Password để bảo vệ kết quả di chuyển.
Nhấn Start Single Migration.

Monitoring

4. Theo Dõi & Xuất Báo Cáo

Theo dõi dashboard, xem log thời gian thực và tải báo cáo nghiệm thu sau khi toàn bộ mailbox hoàn tất.

Hệ thống xử lý chạy nền (background worker). Bạn có thể tắt trình duyệt và tự động quay lại sau.

4.1 Tại Dashboard chính

Bạn sẽ thấy danh sách các Job đang chạy.
Cột Progress: Biểu thị % lượng hòm thư đã hoàn tất.
Click nút View Details để xem chi tiết. Hệ thống sẽ yêu cầu nhập Job Password.

4.2 Tại trang Job Detail (Cập nhật thời gian thực - WebSockets)

Thanh tiến trình sẽ tự động trượt mà không cần làm mới trang (F5).
Danh sách các tài khoản sẽ hiện trạng thái: In Progress, Completed, Failed.
Click View Logs tại từng tài khoản để xem chi tiết kết nối `imapsync` ở dưới nền. Màn hình console đen sẽ hiện ra cho thấy email nào đang được copy.
Dừng tác vụ (Stop All): Nút này cho phép hủy các lệnh copy đang chạy nếu phát hiện sai sót.

4.3 Nghiệm thu và trả kết quả (Export Report)

Sau khi tiến trình 100%, bạn có thể nhấn nút Export Report ở góc trên trang chi tiết (Job Detail).

Hệ thống sẽ tải về một file CSV báo cáo số lượng email chuyển thành công, thất bại và tổng dung lượng dữ liệu. Đây là file dùng để gửi khách hàng nghiệm thu.

Credential QA

5. Kiểm Tra Mật Khẩu Hàng Loạt

Rà soát trước host, app password và khả năng đăng nhập để giảm lỗi phát sinh ở giữa phiên migration.

Trước khi chạy khối lượng lớn, tính năng Check Credentials giúp bạn rà soát lại tất cả mật khẩu và App Password tránh lọt lỗi hỏng kết nối lúc Sync.

Truy cập Check Credentials qua thanh điều hướng phía trên.
Chọn Bulk Check và tải lên file CSV (Cấu trúc: email,password).
Khác với Bulk Migration (4 cột), Check CSV chỉ yêu cầu 2 cột.
Chọn Auto-detect Server (Tự động nhận diện IMAP theo đuôi @gmail.com, @yandex.com) hoặc Force (Ép dùng 1 server cho toàn file).
Sau khi quét xong, nhấn Export Failed để lọc ra chỉ những tài khoản bị sai pass và báo khách hàng cấp lại.

Gmail Setup

6. Khởi tạo App Password Gmail & Workspace

Phần này dùng để xử lý nhanh nhóm lỗi đăng nhập Gmail và Google Workspace, đặc biệt khi người dùng đã bật xác thực hai lớp.

Bắt buộc: Bạn không thể dùng mật khẩu đăng nhập thông thường của Google nữa do chính sách bảo mật. Bắt buộc phải tạo Mật khẩu ứng dụng (App Password) dài 16 ký tự.

Bật IMAP trong Cài đặt Gmail (Settings → Forwarding and POP/IMAP → Enable IMAP).
Truy cập myaccount.google.com/security.
Đảm bảo Xác minh 2 bước (2-Step Verification) đã được Bật.
Tìm đến mục Mật khẩu ứng dụng (App passwords). Hoặc nhấp trực tiếp vào Link này.
Đặt tên ứng dụng (vd: "imapsync") và nhấn Tạo (Create).
Copy chuỗi 16 ký tự màu vàng (ví dụ: abcd efgh ijkl mnop) - Nhớ xóa dấu cách khi dán vào file CSV (abcdefghijklmnop).

Office 365

7. Hướng dẫn Office 365 (O365)

Tập hợp các bước tenant-admin và user-level để xử lý xác thực Microsoft 365 theo một luồng dễ đối chiếu.

Lưu ý Microsoft: Từ T9/2025, Microsoft sẽ khai tử hoàn toàn Basic Auth trên IMAP. Hiện tại hãy làm theo cấu hình dưới đây.

Quyền Quản trị viên (Tenant Admin) phải vào Microsoft 365 admin center.
Truy cập Settings → Org settings → Modern authentication và đảm bảo Turn on basic authentication for IMAP vẫn được đánh dấu (nếu còn).
Người dùng cũng vào trang Bảo mật tài khoản (My Sign-ins), kích hoạt xác thực 2 bước (MFA) và tạo App Passwords.
Nếu user liên tục gặp lỗi "AUTHENTICATIONFAILED", admin có thể cần tắt "Security Defaults" trong Entra ID (Azure AD).

Security Model

8. Cơ Chế Bảo Mật Tích Hợp

Tóm tắt ngắn các lớp bảo vệ áp vào file CSV, job password và session truy cập để người xem hiểu đúng phạm vi chia sẻ.

Bảo mật File CSV

File CSV bạn tải lên chỉ lưu trữ vào RAM/ổ đĩa tạm (Temp file) trên máy chủ nội bộ. Nó sẽ bị tự động xóa bỏ hoàn toàn ngay sau khi quá trình đọc file hoàn tất (< 1 giây).

Bảo mật Job Password (JWT)

Job Password bạn nhập sẽ được mã hóa Hash phía Backend. Trình duyệt đóng vai trò xác thực thông qua JSON Web Token (JWT) ngăn ngừa các cuộc tấn công nghe lén (XSS).

Troubleshooting

9. Trả Lời Câu Hỏi & Xử Lý Sự Cố

Các lỗi thường gặp được gom thành accordion để kỹ thuật viên và khách dễ tra cứu ngay trong lúc job đang chạy.

Lỗi "AUTHENTICATIONFAILED"

Sai tên đăng nhập hoặc mật khẩu: Kiểm tra lại các khoảng trống thừa trong file CSV.
Nếu dùng Gmail/Outlook: Bạn CHƯA tạo App Password. Mật khẩu web thông thường sẽ bị chối từ.
Tài khoản bị khóa IMAP.

Lỗi "Connection timed out" hoặc "No route to host"

Bạn đã cấu hình sai địa chỉ IMAP Host hoặc Port. Ví dụ: nhập gmail.com thay vì imap.gmail.com. Hoặc nhập port 143 (không bảo mật) trong khi máy chủ chỉ mở 993 (SSL).

Lỗi "Too many simultaneous connections"

Máy chủ IMAP giới hạn số kết nối cùng lúc từ một IP. Hệ thống mặc định giới hạn ở mức an toàn. Tuy nhiên, nếu bạn cấu hình một Job chạy một list mail có chung hostname, có thể máy chủ nguồn sẽ đá ra. Hãy phân tách list hoặc báo admin.

Lỗi "Quota exceeded" (Đầy bộ nhớ)

Hòm thư đích đã hết dung lượng lưu trữ nội bộ. Không thể copy thêm email sang. Cần mở rộng dung lượng trên server nhận.

Lỗi "Message too large"

Server đích giới hạn kích thước email nhận vào (ví dụ: Gmail max 25MB, Outlook max 20MB). Các email có file đính kèm lớn hơn mức này sẽ bị từ chối. Bạn cần xử lý thủ công các email này.

Tại sao tốc độ Sync chậm?

Giới hạn của Provider: Gmail và Outlook giới hạn băng thông mỗi ngày. Nếu vượt quá, tốc độ sẽ bị bóp nghẹt (throttling) hoặc tạm khóa.
Số lượng file nhỏ: Di chuyển 1000 email 1KB chậm hơn nhiều so với 1 email 1MB do overhead của giao thức IMAP.
Giải pháp: Hệ thống đã được tối ưu với số luồng đồng thời (MAX_WORKERS=7) phù hợp nhất cho hiệu suất và độ ổn định. Nếu bị chặn, hãy thử lại sau vài giờ.

Tài liệu vận hành rõ ràng cho các phiên di chuyển email.