Môi trường và triển khai
Cách chạy YeChai ở từng môi trường và quy trình triển khai lên VPS.
Các môi trường
| Môi trường | URL / cổng | Cách chạy | Cơ sở dữ liệu |
|---|---|---|---|
| Local development | Gateway http://127.0.0.1:5174/, API 3001 | pnpm db:dev rồi pnpm dev | yechai_m2_development (PostgreSQL nhúng, cổng 55432) |
| Local, chỉ app | Gateway 5174 | pnpm dev:apps (không chạy API) | Dùng API đang chạy |
| Local, chỉ API | 3001 | pnpm dev:api | Như trên |
| Preview bản build | Gateway 4174 | pnpm build rồi pnpm preview | Như trên |
| vps-dev | https://yechai-dev.auranium.tech | systemd yechai-dev.service + yechai-dev-api.service | yechai_dev |
| vps-test | https://yechai.auranium.tech | systemd yechai-api.service | yechai_vps_test |
| production | Origin HTTPS riêng | Cùng cơ chế | yechai_production |
Ở local, gateway phục vụ app người dân ở /, trang quản trị ở /admin, và chuyển
tiếp /api/* sang API.
vps-dev — môi trường xem thử
https://yechai-dev.auranium.tech chạy từ chính workspace đang phát triển, dùng
cơ chế hot reload. Môi trường này cho phép xem trước thay đổi ngay khi lưu file.
Giới hạn của vps-dev
Môi trường này không phải môi trường kiểm thử nghiêm ngặt. Dữ liệu có thể thay đổi bất kỳ lúc nào và nội dung phụ thuộc vào trạng thái workspace hiện tại. Đừng dùng nó để nghiệm thu.
vps-test — môi trường dùng để nghiệm thu
Đây là môi trường mà tài liệu này chụp ảnh. Cấu trúc:
| Thành phần | Giá trị |
|---|---|
| Dịch vụ API | yechai-api.service |
| Người dùng hệ thống | yechai (nhóm yechai) |
| Tệp biến môi trường | /etc/yechai/vps-test.env |
| Cổng API | 127.0.0.1:3001 |
| Proxy tĩnh | nginx 127.0.0.1:8088, gốc /srv/yechai/current/public |
| Proxy biên | Caddy giữ TLS, chuyển tiếp về nginx |
Quy trình triển khai
Triển khai được thực hiện bằng GitHub Actions gọi script trên máy chủ.
Trình tự
- Xác minh — workflow kiểm tra commit phải là commit mới nhất của nhánh
main. - Chạy CI — typecheck, test API, test e2e, build.
- Gọi script triển khai trên máy chủ qua SSH.
- Script tạo release mới trong thư mục có tên theo mốc thời gian và 8 ký tự đầu của commit.
- Cài phụ thuộc và build trong release mới, dưới người dùng build riêng.
- Sao lưu cơ sở dữ liệu bằng
pg_dumptrước khi chạy migration. - Chạy migration với người dùng migration riêng và có bộ chặn.
- Đổi symlink
currentsang release mới. Thao tác này là nguyên tử. - Khởi động lại dịch vụ và kiểm tra sức khoẻ.
- Nếu kiểm tra sức khoẻ thất bại, tự động quay lui về release trước — nhưng chỉ khi chưa chạy migration.
Cơ sở dữ liệu không bao giờ tự quay lui
Nếu migration đã chạy mà triển khai thất bại, hệ thống dừng lại và báo động thay vì tự khôi phục. Cơ sở dữ liệu phải được xử lý bằng một bản sửa tiến (forward fix) hoặc kế hoạch phục hồi đã được duyệt riêng. Bộ chặn migration sẽ thoát với mã riêng để phân biệt lỗi migration và lỗi triển khai.
Tài khoản hệ thống
| Người dùng | Việc |
|---|---|
yechai-deploy | Chạy script triển khai, có khoá SSH riêng giới hạn lệnh. |
yechai-build | Cài phụ thuộc và build, không có shell đăng nhập. |
yechai-migrate | Chỉ chạy migration. |
Server không cấp shell tự do cho khoá triển khai; lệnh bị giới hạn bằng forced command.
Rollback
Lệnh rollback chuyển symlink current về release trước và khởi động lại dịch vụ.
Rollback chỉ có tác dụng với mã, không có tác dụng với cơ sở dữ liệu.
Biến môi trường
Chỉ liệt kê tên, không ghi giá trị. Giá trị thật nằm trong /etc/yechai/*.env
và không được đưa vào tài liệu.
Runtime
NODE_ENV, YECHAI_RUNTIME, YECHAI_DATABASE_URL, YECHAI_DATA_ROOT,
YECHAI_PUBLIC_ORIGIN, M2_API_PORT, YECHAI_SMS_PROVIDER,
YECHAI_FIREBASE_API_KEY, YECHAI_OTP_PEPPER, YECHAI_ACCOUNT_KEY,
YECHAI_FCM_SERVICE_ACCOUNT_FILE, YECHAI_NATIVE_OTP_ENABLED.
Biến dành cho app web
VITE_CITIZEN_SMS_PROVIDER, VITE_FIREBASE_API_KEY, VITE_FIREBASE_APP_ID,
VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID.
Migration
YECHAI_MIGRATION_DATABASE_URL, YECHAI_MIGRATION_PGHOST,
YECHAI_MIGRATION_PGPORT, YECHAI_MIGRATION_PGDATABASE,
YECHAI_MIGRATION_PGUSER, YECHAI_MIGRATION_PGPASSFILE.
Gateway
YECHAI_PUBLIC_PORT, YECHAI_CITIZEN_TARGET, YECHAI_ADMIN_TARGET,
YECHAI_M2_API_TARGET, YECHAI_SERVE_MODE.
Không chép mật khẩu vào tài liệu
Quy ước của dự án cấm chép tài khoản và mật khẩu development vào tài liệu hoặc chứng cứ. Lệnh in tài khoản local chỉ dùng để lấy thông tin trên máy cá nhân.