Cài Kite trên VPS

00 · Chuẩn bị

Bốn thứ cần có trước khi chạy lệnh.

Thiếu một thứ là CLI dừng ngay ở bước kiểm tra đầu và báo lỗi, nên bạn nên chuẩn bị đủ trước.

Một VPS Ubuntu 22.04 hoặc 24.04, chip x64 hoặc arm64, tối thiểu 1 GB RAM. VPS trắng, chưa chạy web khác trên cổng 80 và 443.
Cổng 80 và 443 mở trên tường lửa của nhà cung cấp VPS. Caddy trong Kite dùng hai cổng này để lấy chứng chỉ HTTPS và phục vụ cửa hàng.
Một tên miền với hai bản ghi A trỏ về địa chỉ IP của VPS: tên-miền và pages.tên-miền. Chi tiết ở bước 03.
Đăng nhập SSH được vào VPS bằng một tài khoản có quyền sudo không hỏi mật khẩu (tài khoản mặc định ubuntu hoặc root của hầu hết nhà cung cấp đều được). Có sẵn khoá SSH của bạn.

Cũng cần mã giấy phép: bạn nhận mã qua email khi được cấp bản quyền. Trong lúc nối dịch vụ, Kite sẽ hỏi thêm thông tin SePay, email và Bunny; mỗi dịch vụ có hướng dẫn riêng.

01 · Tải CLI

Chọn đúng file cho máy bạn.

Các link dưới đây luôn trỏ tới bản Kite stable mới nhất. macOS và Linux cần thêm quyền chạy sau khi tải. Windows dùng file .exe.

macOS

Apple Silicon
kite-darwin-arm64
Intel
kite-darwin-x64

# Apple Silicon
curl -fL https://sky.kite.vibery.app/v1/releases/latest/cli/kite-darwin-arm64 -o digisell && chmod +x digisell

# Intel
curl -fL https://sky.kite.vibery.app/v1/releases/latest/cli/kite-darwin-x64 -o digisell && chmod +x digisell

Linux

ARM64
kite-linux-arm64
x64
kite-linux-x64

# ARM64
curl -fL https://sky.kite.vibery.app/v1/releases/latest/cli/kite-linux-arm64 -o digisell && chmod +x digisell

# x64
curl -fL https://sky.kite.vibery.app/v1/releases/latest/cli/kite-linux-x64 -o digisell && chmod +x digisell

Windows

x64
kite-windows-x64.exe

Invoke-WebRequest `
  -Uri "https://sky.kite.vibery.app/v1/releases/latest/cli/kite-windows-x64.exe" `
  -OutFile digisell.exe

02 · Tùy chọn: kiểm tra file

Đối chiếu checksum nếu bạn muốn chắc tay hơn.

Hub có danh sách checksum đã ký cho cả năm file CLI. Tải danh sách về rồi so sánh SHA-256 của file bạn vừa tải với mục cùng tên trong body.entries.

curl -fL https://sky.kite.vibery.app/v1/releases/latest/cli-checksums -o cli-checksums.json

# Linux
sha256sum digisell

# macOS
shasum -a 256 digisell

# Windows PowerShell
Get-FileHash .\digisell.exe -Algorithm SHA256

Nếu hai giá trị SHA-256 không giống nhau, xoá file đó và tải lại. Link checksum cũng tự chuyển sang đúng bản phát hành stable.

03 · Trỏ tên miền

Cho tên miền và pages.<tên-miền> cùng trỏ về VPS.

Trong DNS của tên miền, tạo hai bản ghi A. Thay example.com và địa chỉ IP bên dưới bằng thông tin của bạn.

example.comA → 203.0.113.10

pages.example.comA → 203.0.113.10

Hai bản ghi phải trỏ về cùng một VPS. Chờ DNS cập nhật xong rồi chạy CLI để bước kiểm tra tên miền không bị lỗi.

04 · Chạy CLI

Đưa mã giấy phép vào biến môi trường, rồi cài.

Chạy lệnh này trên máy của bạn. CLI kết nối SSH tới VPS, cài Docker và dựng Kite. Mã giấy phép nằm trong email khi bạn được cấp bản quyền; không cần dán mã vào tham số dòng lệnh.

Linux hoặc macOS

export KITE_LICENSE_TOKEN="mã-giấy-phép-của-bạn"
digisell init example.com \
  --host 203.0.113.10 \
  --host-key-fingerprint SHA256:... \
  --storage seaweedfs

Windows PowerShell

$env:KITE_LICENSE_TOKEN = "mã-giấy-phép-của-bạn"
./digisell.exe init example.com `
  --host 203.0.113.10 `
  --host-key-fingerprint SHA256:... `
  --storage seaweedfs

Đăng nhập bằng tài khoản khác root thì thêm --user ubuntu và --identity-file ~/.ssh/khoa-cua-ban (hoặc đặt biến KITE_SSH_USER và KITE_SSH_KEY).

Gần cuối, CLI lưu một file recovery kit vào thư mục bạn đang đứng rồi hỏi bạn gõ lại 6 ký tự để xác nhận. Cất file này ở nơi an toàn ngoài VPS: nó cần khi bạn khôi phục cửa hàng lên máy mới.

Thay example.com, địa chỉ 203.0.113.10 và fingerprint SSH bằng thông tin thật. Để lấy fingerprint, chạy ssh-keyscan -t ed25519 203.0.113.10 | ssh-keygen -lf - rồi chép phần bắt đầu bằng SHA256:; nhà cung cấp VPS cũng thường hiện fingerprint này trong trang quản lý máy. Flag --storage seaweedfs dùng SeaweedFS đi kèm Kite trên VPS.

05 · Cất cánh

Mở link setup CLI in ra.

Khi cài xong, CLI sẽ in một dòng bắt đầu bằng Setup:. Mở link đó trong trình duyệt để vào Cất cánh, rồi đi qua từng bước nối email, thanh toán và các dịch vụ bạn dùng.

Ví dụ

Setup: https://example.com/setup#t=...

Link này có token dùng một lần. Giữ nó riêng tư và mở ngay sau khi CLI in ra.

Nếu bị lỗi

CLI báo lỗi: đọc dòng bắt đầu bằng `kite:`.

Mỗi lỗi dưới đây là phần chữ đầu tiên của dòng báo lỗi. Sửa xong thì chạy lại lệnh digisell init.

CLI báo	Nghĩa là gì, sửa thế nào
`license_required`	Chưa có mã giấy phép. Đặt biến `KITE_LICENSE_TOKEN` như ở bước 04, rồi chạy lại. Không dán mã vào tham số dòng lệnh, CLI từ chối.
`license_malformed_token`, `license_invalid_claims` hoặc `license_…` khác	Mã chép thiếu, thừa khoảng trắng hoặc xuống dòng giữa chừng. Chép lại nguyên mã từ email, đặt trong dấu nháy kép.
`license_domain_mismatch`	Giấy phép đã gắn với một tên miền khác. Dùng đúng tên miền ghi trong giấy phép, hoặc liên hệ mình để thêm tên miền.
`preflight_failed:…`	VPS chưa đạt yêu cầu. Phần sau dấu hai chấm nói rõ: cần Ubuntu 22.04 hoặc 24.04, cần x64 hoặc arm64, cần tối thiểu 1 GB RAM, hoặc cổng 80 và 443 đang bị chiếm. Đổi VPS cho đúng hoặc tắt dịch vụ đang chiếm cổng.
`warning: DNS A record for … is not …`	Đây là cảnh báo, CLI vẫn chạy tiếp, nhưng nếu bạn bỏ qua thì HTTPS sẽ không lấy được chứng chỉ và cửa hàng mở không ra. Sửa hai bản ghi A cho đúng IP của VPS, chờ DNS cập nhật rồi chạy lại.
`ssh_host_key_confirmation_required`	CLI chưa biết VPS này. Thêm `--host-key-fingerprint SHA256:…` như ở bước 04 (lấy bằng lệnh `ssh-keyscan` ở trên).
`ssh_host_key_mismatch:…`	Fingerprint của VPS khác với fingerprint bạn đưa. Nếu bạn vừa cài lại VPS thì lấy fingerprint mới. Nếu không, dừng lại: có thể bạn đang nối nhầm máy.
`ssh_host_key_unavailable:…`	Không đọc được khoá của VPS. Kiểm tra địa chỉ `--host`, cổng 22 mở, và VPS đã khởi động xong.
`All configured authentication methods failed`	Đăng nhập SSH thất bại. Thêm `--user` và `--identity-file` đúng với VPS của bạn.
`release_download_unauthenticated`	Kite Sky không nhận mã giấy phép này. Kiểm tra mã chép đủ chưa. Giấy phép đã bị thu hồi (ví dụ sau hoàn tiền) thì không cài được.
`release_download_updates_expired`	Gói cập nhật của giấy phép đã hết hạn trước bản này. Gia hạn Kite Wind, hoặc thêm `--release <bản cũ hơn>`.
`release_download_rate_limited`	Tải quá nhiều lần trong ngày. Thử lại vào ngày mai.
`init_version_mismatch:…`	VPS đã cài một bản Kite khác. Muốn đổi phiên bản thì dùng `digisell update`, không chạy lại `init`.
`recovery_kit_confirmation_required`	Bạn chưa gõ 6 ký tự xác nhận recovery kit. Chạy lại trong một cửa sổ terminal bình thường và gõ đúng 6 ký tự CLI yêu cầu.
`setup_already_completed:…`	Cửa hàng đã cài xong, link Cất cánh chỉ dùng một lần. Vào trang quản trị bằng `digisell login-link --owner`.

Vẫn kẹt? Gửi mình email tại [email protected], kèm nguyên dòng báo lỗi (che mã giấy phép) và nhà cung cấp VPS bạn dùng.

Cài Kite lên máy chủ của bạn.

Bốn thứ cần có trước khi chạy lệnh.

Chọn đúng file cho máy bạn.

macOS

Linux

Windows

Đối chiếu checksum nếu bạn muốn chắc tay hơn.

Cho tên miền và pages.<tên-miền> cùng trỏ về VPS.

Đưa mã giấy phép vào biến môi trường, rồi cài.

Mở link setup CLI in ra.

CLI báo lỗi: đọc dòng bắt đầu bằng `kite:`.

Cài xong thì phần còn lại nằm trong Kite.

Bốn thứ cần có trước khi chạy lệnh.

Chọn đúng file cho máy bạn.

macOS

Linux

Windows

Đối chiếu checksum nếu bạn muốn chắc tay hơn.

Cho tên miền và pages.<tên-miền> cùng trỏ về VPS.

Đưa mã giấy phép vào biến môi trường, rồi cài.

Mở link setup CLI in ra.

CLI báo lỗi: đọc dòng bắt đầu bằng kite:.

Cài xong thì phần còn lại nằm trong Kite.

CLI báo lỗi: đọc dòng bắt đầu bằng `kite:`.