vietqr-core-sdk

Hướng Dẫn Cài Đặt và Cấu Hình Tên Miền (Linux, Docker, SSL)

Tài liệu này hướng dẫn cách triển khai hệ thống VietQR Gateway Service lên môi trường Linux (Ubuntu, Debian, CentOS, RHEL, Alpine) theo chuẩn PaaS/SaaS với tên miền riêng và chứng chỉ SSL Let’s Encrypt tự động.

---

1. Triển khai bằng Docker Compose (Khuyên dùng cho SaaS)

Bước 1: Chuẩn bị thư mục và biến môi trường

Tạo file .env từ file mẫu tại deploy/docker/.env.example:

cd deploy/docker
cp .env.example .env
nano .env

Nội dung .env:

DOMAIN=qr.yourdomain.com
PORT=8080
SCHEME=https
ACME_EMAIL=admin@yourdomain.com
VIETQR_API_KEYS=sk_live_tenant_prod_1,sk_live_tenant_prod_2

Bước 2: Khởi động hệ thống có tự động cấp SSL

docker-compose -f docker-compose.prod.yml up -d

Container Caddy sẽ tự động trỏ đến Let’s Encrypt để đăng ký chứng chỉ SSL cho domain qr.yourdomain.com và chuyển tiếp yêu cầu đến Gateway Rust chạy tại cổng 8080.

Kiểm tra trạng thái:

docker-compose -f docker-compose.prod.yml ps
docker-compose -f docker-compose.prod.yml logs -f

---

2. Cài đặt trực tiếp lên Linux (Native Systemd Service)

Hệ thống cung cấp script tự động nhận diện kiến trúc CPU (x86_64, aarch64/ARM64, armv7l) và tải bản binary phát hành từ GitHub Release.

Bước 1: Chạy script cài đặt

sudo bash deploy/linux/install.sh --domain qr.yourdomain.com --scheme https

Script sẽ tự động:

1. Tạo người dùng hệ thống không đặc quyền vietqr.
2. Tạo thư mục làm việc /opt/vietqr và copy tài nguyên assets, font.
3. Thiết lập file cấu hình môi trường /etc/vietqr/vietqr.env.
4. Cài đặt và kích hoạt systemd service vietqr.service.

Bước 2: Quản lý dịch vụ

# Kiểm tra trạng thái
sudo systemctl status vietqr

# Khởi động lại
sudo systemctl restart vietqr

# Xem log thời gian thực
sudo journalctl -u vietqr -f

---

3. Cấu hình Nginx Reverse Proxy (Nếu dùng Nginx có sẵn)

Nếu máy chủ của bạn đã có sẵn Nginx:

1. Sao chép file cấu hình:

   sudo cp deploy/reverse-proxy/nginx/vietqr.conf /etc/nginx/sites-available/vietqr.conf
   sudo ln -s /etc/nginx/sites-available/vietqr.conf /etc/nginx/sites-enabled/
   

2. Thay thế qr.yourdomain.com bằng tên miền của bạn:

   sudo sed -i 's/qr.yourdomain.com/tenmien.cua.ban/g' /etc/nginx/sites-available/vietqr.conf
   

3. Cấp chứng chỉ SSL bằng Certbot:

   sudo certbot --nginx -d tenmien.cua.ban
   sudo systemctl reload nginx
   

---

4. Kiểm tra dịch vụ sau khi cấu hình

Truy cập qua trình duyệt hoặc cURL:

• Health check: https://qr.yourdomain.com/health
• Xem Studio: https://qr.yourdomain.com/studio
• Xem thử VietQR hình ảnh: https://qr.yourdomain.com/image/970436-1234567890-compact2.png?amount=50000&addInfo=Test
• Xem Pay Hub Deeplink: https://qr.yourdomain.com/qr/pay?bin=970436&acc=1234567890&amount=50000

This site is open source. Improve this page.