E-commerce Demo - Node.js + Nginx + MySQL Master/Slave

Dự án này là một mô hình backend e-commerce đơn giản, chạy theo kiến trúc:

• 2 API Node.js (api-node-1, api-node-2)
• 1 Nginx load balancer (nginx-lb)
• 1 MySQL Master (db-master)
• 1 MySQL Slave (db-slave)

Backend được thiết kế theo hướng:

• POST /products ghi vào Master
• GET /products đọc từ Slave

Mục tiêu: demo cách vận hành API đa node kết hợp database replication.

1) Cấu trúc dự án

.
|-- docker-compose.yaml
|-- README.md
|-- backend/
|   |-- app.js
|   |-- server.js
|   |-- package.json
|   |-- Dockerfile
|   |-- config/db.js
|   |-- controllers/productController.js
|   |-- services/productService.js
|   |-- repositories/productRepositories.js
|   `-- routes/productRoute.js
`-- infrastructure/
    |-- nginx/nginx.conf
    `-- mysql/
        |-- setup-replication.sh
        |-- master/
        |   |-- my.cnf
        |   `-- init.sql
        `-- slave/
            `-- my.cnf

2) Yêu cầu môi trường

Cần cài đặt sẵn:

• Docker Desktop (hoặc Docker Engine + Docker Compose plugin)
• Bash shell (macOS/Linux có sẵn)

Kiểm tra nhanh:

docker --version
docker compose version

3) Chạy dự án (khuyến nghị - full Docker)

Bước 1: Di chuyển vào thư mục dự án

cd e-commerce

Bước 2: Build và start tất cả service

docker compose up -d --build

Bước 3: Kiểm tra trạng thái container

docker compose ps

Bước 4: Khởi tạo replication Master -> Slave (rất quan trọng)

bash infrastructure/mysql/setup-replication.sh

Script này sẽ tự động:

• Tạo snapshot nhất quán từ Master
• Trích replication coordinates
• Seed dữ liệu vào Slave
• CHANGE REPLICATION SOURCE + START REPLICA
• In thông tin verify

Bước 5: Verify replication

docker exec e-commerce-db-slave-1 mysql -uroot -proot_password -e "SHOW REPLICA STATUS\\G"

Cần thấy:

• Replica_IO_Running: Yes
• Replica_SQL_Running: Yes

Bước 6: Test health endpoint

curl http://localhost/health

Bước 7: Test API qua Nginx

Lấy danh sách sản phẩm:

curl http://localhost/products

Tạo sản phẩm mới:

curl -X POST http://localhost/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Product D","description":"Description for Product D","price":40.99,"quantity":50}'

Gọi lại danh sách để kiểm tra:

curl http://localhost/products

4) Kiến trúc và luồng xử lý

Nginx load balancer

• Nginx lắng nghe cổng 80
• Round-robin đến 2 node backend:
  • api-node-1:3000
  • api-node-2:3000

Backend

• GET /health: trả về thông tin service/node đang xử lý
• GET /products: đọc từ MySQL Slave
• POST /products: ghi vào MySQL Master

Database replication

• Master có binary log (log-bin) và user replicator
• Slave bật read_only=1 và nhận dữ liệu từ Master sau khi chạy script setup

5) Biến môi trường chính

Trong Docker Compose, backend sử dụng:

• NODE_NAME=API_NODE_01 hoặc API_NODE_02
• DB_MASTER_HOST=db-master
• DB_SLAVE_HOST=db-slave
• TZ=Asia/Ho_Chi_Minh

Giá trị DB mặc định trong code:

• DB_USER=root
• DB_PASSWORD=root_password
• DB_NAME=ecommerce-db

6) Lệnh vận hành thường dùng

Start:

docker compose up -d --build

Stop:

docker compose down

Xem logs tất cả:

docker compose logs -f

Xem logs riêng backend:

docker compose logs -f api-node-1 api-node-2

Xem logs Nginx:

docker compose logs -f nginx-lb

7) Reset dự án từ đầu (xóa toàn bộ dữ liệu)

Khi cần test lại full flow từ đầu:

docker compose down -v
docker compose up -d --build
bash infrastructure/mysql/setup-replication.sh

down -v sẽ xóa volume dữ liệu MySQL.

8) Troubleshooting

Lỗi Replica_IO_Running hoặc Replica_SQL_Running không phải Yes

Chạy lại setup replication:

bash infrastructure/mysql/setup-replication.sh

Nếu vẫn lỗi, xem chi tiết:

docker exec e-commerce-db-slave-1 mysql -uroot -proot_password -e "SHOW REPLICA STATUS\\G"

Lỗi API không response qua localhost

Kiểm tra container:

docker compose ps

Kiểm tra health backend:

docker compose logs -f api-node-1 api-node-2

Kiểm tra Nginx:

docker compose logs -f nginx-lb

Lỗi kết nối MySQL

Kiểm tra logs MySQL:

docker compose logs -f db-master db-slave

9) Chạy backend local (tùy chọn)

Mode này dùng khi cần debug Node.js nhanh trên máy local.

Lưu ý: docker-compose.yaml hiện tại không map cổng MySQL ra host. Vì vậy nếu chạy backend local, cần phải map cổng MySQL hoặc chỉnh compose cho phù hợp.

Lệnh trong backend/:

npm install
npm start

10) API tham khảo

GET /health

Response mẫu:

{
  "status": "ok",
  "service": "API_NODE_01",
  "timestamp": "2026-04-27T10:00:00.000Z"
}

GET /products

Response mẫu:

{
  "products": [
    {
      "id": 1,
      "name": "Product A",
      "description": "Description for Product A",
      "price": "10.99",
      "quantity": 100,
      "created_at": "2026-04-27T10:00:00.000Z"
    }
  ],
  "metadata": {
    "processed_by": "API_NODE_02",
    "total_products": 1,
    "timestamp": "2026-04-27T10:00:00.000Z"
  }
}

POST /products

Request body:

{
  "name": "Product X",
  "description": "Description X",
  "price": 99.99,
  "quantity": 10
}

Response mẫu:

{
  "id": 4,
  "name": "Product X",
  "description": "Description X",
  "price": 99.99,
  "quantity": 10
}

---

Nếu cần bổ sung endpoint, monitoring, hoặc CI/CD, có thể mở rộng từ khung dự án trên.