Quản lý tên miền

Hướng dẫn Quản lý Tên miền (Whitelist Domain)

Nhằm đảm bảo tính bảo mật tối đa cho nền tảng, các Mini App chỉ được phép giao tiếp với các máy chủ bên ngoài đã được khai báo và xác thực. Bất kỳ request nào gửi đến các tên miền không nằm trong danh sách an toàn này đều sẽ bị nền tảng chặn tự động.

Lưu ý quan trọng về bản build

Các tên miền mới được cấu hình thành công sẽ chỉ áp dụng cho các bản build được upload sau thời điểm thêm tên miền. Các bản build cũ đã tồn tại trên hệ thống sẽ không tự động nhận danh sách whitelist mới. Bạn bắt buộc phải tạo và upload một bản build mới để các thay đổi này có hiệu lực.

Các bước thực hiện

Bước 1: Truy cập tính năng Quản lý tên miền

1. Đăng nhập vào V-Console bằng tài khoản Admin của Mini App.
2. Chọn Mini App bạn muốn cấu hình từ danh sách.
3. Trên menu điều hướng bên trái, cuộn xuống phần Cài đặt và chọn Quản lý tên miền.
4. Tại màn hình chính, nhấn vào nút Tạo tên miền ở góc trên bên phải.

Bước 2: Khai báo tên miền và tải tệp xác thực Trên cửa sổ "Thêm tên miền" vừa hiện ra, thực hiện theo Bước 1 trên giao diện:

1. Nhập chính xác tên miền bạn muốn thêm vào ô trống.
   • Lưu ý: Định dạng bắt buộc phải bao gồm giao thức https:// hoặc wss:// (ví dụ: https://domain.example.com).
2. Nhấn nút Tải tệp xác thực. Hệ thống sẽ tải xuống một tệp .txt (ví dụ: vsf-verification.txt) chứa mã xác thực duy nhất cho domain của bạn.

Bước 3: Tích hợp tệp xác thực lên Server Đây là bước để bạn chứng minh mình sở hữu tên miền đã khai báo (Bước 2 trên giao diện):

1. Đưa tệp .txt vừa tải về lên thư mục gốc (root directory) của máy chủ web đang chạy tên miền đó.
2. Kiểm tra lại để đảm bảo tệp có thể được truy cập công khai qua trình duyệt theo đường dẫn chuẩn. Ví dụ: https://domain.example.com/vsf-verification.txt.

Bước 4: Hoàn tất kiểm tra

1. Sau khi đã cấu hình xong tệp xác thực trên server, quay lại màn hình V-Console.
2. Nhấn nút Thêm tên miền.
3. V-Console sẽ tự động giao tiếp với Backend để kiểm tra sự tồn tại và tính hợp lệ của tệp xác thực theo đường dẫn tên miền của bạn.
4. Nếu kiểm tra thành công, bạn sẽ nhận được thông báo "Thêm tên miền thành công" và tên miền mới sẽ xuất hiện trong danh sách Quản lý với đầy đủ thông tin về người tạo và ngày tạo.

Các lỗi thường gặp (Troubleshooting)

1. Hệ thống báo không tìm thấy tệp (Lỗi 404)

• Nguyên nhân: Tệp xác thực chưa được tải lên đúng thư mục gốc (root directory) của máy chủ web, hoặc tên tệp bị thay đổi so với file gốc tải về từ V-Console.
• Cách xử lý:
  • Kiểm tra lại vị trí lưu tệp trên server.
  • Mở trình duyệt ẩn danh và tự truy cập vào đường dẫn tệp (Ví dụ: https://domain.example.com/vsf-verification.txt). Nếu trình duyệt của bạn không hiển thị nội dung tệp mà báo lỗi 404, Backend của hệ thống cũng sẽ không thể tìm thấy tệp.

2. Lỗi nội dung tệp không hợp lệ

• Nguyên nhân: Nội dung chuỗi ký tự bên trong tệp .txt đã bị thay đổi vô tình trong quá trình tải xuống hoặc upload lên server (ví dụ: bị thêm khoảng trắng, đổi encoding).
• Cách xử lý: Xóa tệp hiện tại trên server. Quay lại V-Console, tải xuống một tệp xác thực mới tinh và upload lại lên server, đảm bảo giữ nguyên nội dung và định dạng tệp.

3. Lỗi chứng chỉ bảo mật (SSL/TLS Invalid)

• Nguyên nhân: Nền tảng bắt buộc sử dụng giao thức bảo mật https:// hoặc wss://. Nếu chứng chỉ SSL của tên miền bị hết hạn, không hợp lệ (chứng chỉ tự ký - self-signed) hoặc cấu hình sai, Backend sẽ từ chối kết nối để đảm bảo an toàn.
• Cách xử lý: Kiểm tra lại trạng thái SSL của tên miền. Đảm bảo chứng chỉ SSL đang hợp lệ và được cấp bởi một Tổ chức phát hành chứng chỉ (CA) uy tín.

4. Bị chặn bởi tường lửa hoặc hệ thống bảo mật (Lỗi 403 Forbidden / Timeout)

• Nguyên nhân: Máy chủ của bạn, tường lửa (Firewall), hoặc các dịch vụ Proxy/CDN (như Cloudflare) đang chặn request kiểm tra tự động từ Backend của nền tảng.
• Cách xử lý:
  • Kiểm tra log của server hoặc Firewall để xem có request nào đến tệp vsf-verification.txt bị chặn không.
  • Cấu hình ngoại lệ (bypass/whitelist) cho phép các HTTP/HTTPS request đọc tệp văn bản này một cách công khai.

5. Lỗi do chuyển hướng (Redirect Error)

• Nguyên nhân: Tên miền bạn nhập vào V-Console bị cấu hình tự động chuyển hướng sang một URL khác (ví dụ: khai báo https://domain.com nhưng server tự động redirect sang https://www.domain.com). Backend có thể không bám theo (follow redirect) các cấu hình này để đọc tệp.
• Cách xử lý:
  • Đảm bảo tên miền khai báo trên V-Console khớp chính xác 100% với URL thực tế đang hoạt động.
  • Cấu hình máy chủ web để không áp dụng các rule chuyển hướng (redirect) đối với đường dẫn chứa tệp vsf-verification.txt.