Bạn đã có một storefront Next.js dựng từ starter. Trang này đưa nó lên tên miền thật.

XSTORE_DEPLOY_TOKEN=dk_live_… xstore deploy

Một lệnh. xStore kiểm tra gói, khởi động thử trên một cổng phụ, rồi mới chuyển tên miền sang — và tự động quay lại bản cũ nếu bản mới hỏng sau khi chuyển.

0. Cài CLI#

Tải gói và cài:

xstore-cli-0.1.0.tgz

npm install -g ./xstore-cli-0.1.0.tgz
xstore --version

Cần Node 20 trở lên. Cùng một CLI cũng chạy xstore theme cho giao diện Liquid.

1. Yêu cầu#

Máy chủ xStore chạy Node 22, và nodeMajor trong manifest được so sánh chính xác — build bằng major khác sẽ bị từ chối ngay khi tải lên, chứ không phải sau khi đã lên sóng. CLI kiểm tra trước khi build để bạn không phải chờ.

2. Lấy deploy token#

Quản trị → Website → Hosting → Tạo token.

Token chỉ hiện một lần. xStore lưu bản băm sha256, nên không có cách nào hiện lại — mất thì xoay (rotate) một token mới.

Có hai loại token và chúng không thay thế cho nhau:

• Deploy token (dk_live_…) — của bạn. Dùng trên máy hoặc trong CI để chạy xstore deploy.
• Agent token (ak_live_…) — do xStore cài trên máy chủ. Bạn thường không cần tạo.

3. Triển khai#

Trong thư mục dự án Next:

XSTORE_DEPLOY_TOKEN=dk_live_… xstore deploy

→ Đang build (next build)…
→ Đang chuẩn hoá cấu trúc bản build…
→ Đang đóng gói…
→ Đang tải lên…
• Đã tải lên release k3n8vq2ml0 (48.2 MB).
→ Đang kích hoạt…
→ Đang chờ máy chủ triển khai (có thể mất 1-2 phút)…
✔ Đã lên sóng.

Lệnh thoát với mã khác 0 nếu bản triển khai không lên sóng, nên pipeline CI của bạn sẽ đỏ đúng lúc.

Các lệnh khác: xstore releases (liệt kê), xstore rollback (quay lại bản trước).

4. Điều gì xảy ra sau khi tải lên#

tải lên → kiểm tra gói → smoke boot trên cổng phụ → chuyển → kiểm tra sức khoẻ → xong
                              │                                 │
                              └── không đạt ──┐                 └── không đạt ──┐
                                              ▼                                 ▼
                        website hiện tại VẪN chạy            tự động quay lại bản trước

Một bản build không khởi động được sẽ không bao giờ thay thế website đang chạy.

Đó là lý do xstore deploy mất 1-2 phút: xStore khởi động bản mới trên một cổng phụ và chờ nó trả HTTP 200 trong 30 giây trước khi chuyển tên miền sang. Nếu nó không khởi động được, tên miền không hề bị động đến.

Nếu bản mới khởi động được nhưng hỏng ngay sau khi chuyển, xStore tự quay lại bản trước mà không cần bạn làm gì.

xStore giữ lại 5 bản gần nhất.

5. Biến môi trường#

Quản trị → Website → Hosting → Biến môi trường.

xStore tự đặt ba biến này, bạn không sửa được:

Bạn thêm biến của riêng mình (khoá analytics, DSN giám sát…). Các tên sau bị từ chối, vì chúng đã được runtime hoặc xStore đặt:

HURA8_*, DB_*, MYSQL_*, DATABASE_*, AUTH_DB_*, AUDIT_DB_*, REDIS_*, CELERY_*, SECRET_*, LLM_*, NODE_ENV, PORT, HOSTNAME, NODE_OPTIONS, PATH, HOME, USER, LD_PRELOAD, LD_LIBRARY_PATH, NODE_TLS_REJECT_UNAUTHORIZED.

Biến môi trường có hiệu lực ở lần triển khai tiếp theo, không phải ngay khi lưu.

Tiến trình Node của bạn không bao giờ nhận thông tin đăng nhập cơ sở dữ liệu. Nó chỉ thấy ba biến trên cộng với biến của bạn — mã của bạn đọc dữ liệu qua API công khai, đúng như trên máy bạn.

6. Chuyển engine#

Quản trị → Website → Hosting → Engine.

Chuyển engine áp dụng trong khoảng 15 giây. Bạn không thể chuyển sang Next.js khi chưa có bản nào đang chạy — xStore từ chối, vì làm vậy sẽ trỏ tên miền vào một cổng không có gì lắng nghe.

Chuyển ngược về Liquid luôn được, và bản Next vẫn còn nguyên.

7. Quay lại bản trước#

Nút Quay lại bản trước trong Quản trị, hoặc:

xstore rollback

Cả hai đều quay về bản gần nhất từng phục vụ khách. Một bản chưa bao giờ khởi động được thì không phải là đích quay lại — quay về nó là đi tới, không phải đi lùi.

8. Khi có lỗi#

Hai trạng thái đầu có một điểm chung đáng nhớ: website đang phục vụ khách không bị ảnh hưởng.

9. Giới hạn hiện tại#

• Không có preview / staging. Đường lùi là rollback.
• Giữ 5 bản. Bản cũ hơn bị xoá.
• Một website mỗi tenant.
• Gói tối đa 200 MB, Node 22.

Phụ lục — xstore.json#

CLI tự ghi tệp này; bạn không cần sửa tay.

{
  "manifestVersion": 2,
  "engine": "next",
  "engineVersion": "15",
  "nodeMajor": 22,
  "entrypoint": "server.js",
  "staticDir": ".next/static",
  "publicDir": "public",
  "requiredEnv": ["XSTORE_API_URL", "XSTORE_PUBLISHABLE_KEY", "XSTORE_SITE_URL"]
}

entrypoint là server.js ở gốc, không phải .next/standalone/server.js: next build với output: "standalone" không copy .next/static và public/ vào thư mục standalone, nên CLI ghép lại thành một cây chạy được ngay rồi mới đóng gói. Đây chính là nguồn gốc của mọi báo cáo "website triển khai xong không có CSS".