Tài liệu triển khai dự án WSport API
Tài Liệu Triển Khai wsport-api — Golang trên Docker
🔎 Tổng Quan
Hạ Tầng Chính
| Thành phần | Dịch vụ AWS | Mục đích |
|---|---|---|
| Container Images | AWS ECR | Registry Docker image riêng tư |
| Process Manager | Supervisor | Quản lý tiến trình Go binary trong container |
4 Thành Phần API
| Thành phần | ECR Repository | Source Branch | Services | Go Version |
|---|---|---|---|---|
| internal | sports/wsport-api-internal-prod | wcip-rapid-dev | app + cron | Go 1.24 |
| commercial | sports/wsport-api-commercial-prod | wcip-rapid-dev | app + cron | Go latest |
| wacp | sports/wsport-api-wacp-prod | wcip-rapid-dev | app + cron | Go 1.24 |
| websocket | sports/wsport-websocket-internal-prod | wcip-rapid-dev | app only | Go 1.23 |
Base Images
Dockerfile-wsport-api-base:| Thành phần | Base Image ECR |
|---|---|
| internal | sports/wsport-api-internal-base-prod:latest |
| commercial | sports/wsport-api-commercial-base-prod:latest |
| wacp | sports/wsport-api-wacp-prod:base-latest |
| websocket | sports/wsport-websocket-internal-base-prod:latest |
📖 Tài Liệu Tham Khảo
🏗 Tổng Quan Kiến Trúc
Cấu Trúc Thư Mục
wsport-api/
├── build/
│ ├── Dockerfile-wsport-api-base # Base image chung (Debian + Supervisor)
│ ├── Dockerfile-wsport-api-internal.production # Build image: internal (app + cron + searchsync)
│ ├── Dockerfile-wsport-api-commercial.production # Build image: commercial (app + cron)
│ ├── Dockerfile-wsport-api-wacp.production # Build image: wacp (app + cron)
│ ├── Dockerfile-wsport-websocket-internal.production # Build image: websocket (app only)
│ ├── conf/ # Cấu hình Supervisor & TLS certs
│ └── source/ # Git submodule → source code
├── .env-wsport-api-internal.production # Biến môi trường production — internal
├── .env-wsport-api-commercial.production # Biến môi trường production — commercial
├── .env-wsport-api-wacp.production # Biến môi trường production — wacp
├── .env-wsport-websocket-internal.production # Biến môi trường production — websocket
├── docker-compose.yml-wsport-api-internal.production # Docker Compose — internal
├── docker-compose.yml-wsport-api-commercial.production # Docker Compose — commercial
├── docker-compose.yml-wsport-api-wacp.production # Docker Compose — wacp
├── docker-compose.yml-wsport-websocket-internal.production # Docker Compose — websocket
└── docs/ # Tài liệuPipeline Build Multi-Stage
internal (phức tạp nhất — 3 build stages + 2 final stages)
┌──────────────────────────────────────────────────────────────────────────┐
│ PIPELINE BUILD MULTI-STAGE — INTERNAL │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ build_app │ │ build_cron │ │ build_searchsync │ │
│ │ │ │ │ │ │ │
│ │ • Go 1.24 │ │ • Go 1.24 │ │ • Go 1.24 │ │
│ │ • sqlc gen │ │ • sqlc gen │ │ • sqlc gen │ │
│ │ • go build │ │ • go build │ │ • 9 binaries │ │
│ │ → app bin │ │ → cron bin │ │ → man*, │ │
│ │ │ │ │ │ clear* │ │
│ └──────┬───────┘ └──────┬───────┘ └───────┬──────────┘ │
│ │ │ │ │
│ ▼ │ ▼ │
│ ┌──────────────┐ │ ┌──────────────────────┐ │
│ │ app │ │ │ (merged into app) │ │
│ │ (BASE_IMAGE) │◄────────┘ │ app + searchsync │ │
│ │ │ │ binaries │ │
│ │ • Supervisor │ └──────────────────────┘ │
│ │ • app binary │ │
│ │ • searchsync │ ┌──────────────┐ │
│ └──────┬───────┘ │ cron │ │
│ │ │ (BASE_IMAGE) │ │
│ ▼ │ │ │
│ ┌──────────────┐ │ • Supervisor │ │
│ │ ECR Push │ │ • cron binary│ │
│ │ :app-latest │ └──────┬───────┘ │
│ └──────────────┘ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ ECR Push │ │
│ │ :cron-latest │ │
│ └──────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘commercial / wacp (2 build stages + 2 final stages)
┌──────────────────────────────────────────────────────────────────────────┐
│ PIPELINE BUILD MULTI-STAGE — COMMERCIAL / WACP │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ build_app │ │ build_cron │ │
│ │ │ │ │ │
│ │ • Go build │ │ • Go build │ │
│ │ • sqlc gen* │ │ • sqlc gen* │ │
│ │ → app bin │ │ → cron bin │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ app │ │ cron │ │
│ │ (BASE_IMAGE) │ │ (BASE_IMAGE) │ │
│ │ • Supervisor │ │ • Supervisor │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ ECR Push │ │ ECR Push │ │
│ │ :app-latest │ │ :cron-latest │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ * sqlc generate chỉ dùng cho wacp, commercial không sử dụng │
└──────────────────────────────────────────────────────────────────────────┘websocket (1 build stage + 1 final stage)
┌──────────────────────────────────────────────────────────────────────────┐
│ PIPELINE BUILD — WEBSOCKET │
│ │
│ ┌──────────────┐ │
│ │ build_app │ │
│ │ │ │
│ │ • Go 1.23 │ │
│ │ • go build │ │
│ │ → app bin │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ app │ │
│ │ (BASE_IMAGE) │ │
│ │ • Supervisor │ │
│ └──────┬───────┘ │
│ ▼ │
│ ┌──────────────┐ │
│ │ ECR Push │ │
│ │ :app-latest │ │
│ └──────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘Kiến Trúc Runtime Production
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ MÔI TRƯỜNG PRODUCTION AWS │
│ │
│ ┌──────────────────────────────────────┐ ┌──────────────────────────────────────┐ │
│ │ Docker Host │ │ DỊCH VỤ AWS │ │
│ │ │ │ │ │
│ │ ┌────────────────────────────────┐ │ │ ┌──────────────────────────────┐ │ │
│ │ │ internal.app Container │ │ │ │ AWS ECR │ │ │
│ │ │ │ │ │ │ • :app-latest (×4) │ │ │
│ │ │ • Go API binary │ │ │ │ • :cron-latest (×3) │ │ │
│ │ │ • Supervisor managed │ │ │ │ • base images (×4) │ │ │
│ │ │ • .env mounted (RO) │ │ │ └──────────────────────────────┘ │ │
│ │ │ • TLS cert mounted (RO) │ │ │ │ │
│ │ │ • Port 51011 exposed │ │ │ │ │
│ │ └────────────────────────────────┘ │ │ │ │
│ │ │ │ │ │
│ │ ┌────────────────────────────────┐ │ │ │ │
│ │ │ internal.cron Container │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ • Go cron binary │ │ │ │ │
│ │ │ • SP_ENABLE_CRON=false │ │ │ │ │
│ │ │ • .env mounted (RO) │ │ │ │ │
│ │ └────────────────────────────────┘ │ │ │ │
│ │ │ │ │ │
│ │ ┌────────────────────────────────┐ │ │ │ │
│ │ │ commercial.app Container │ │ │ │ │
│ │ │ commercial.cron Container │ │ │ │ │
│ │ │ (tương tự internal) │ │ │ │ │
│ │ └────────────────────────────────┘ │ │ │ │
│ │ │ │ │ │
│ │ ┌────────────────────────────────┐ │ │ │ │
│ │ │ wacp.app / wacp.cron │ │ │ │ │
│ │ │ websocket.app │ │ │ │ │
│ │ └────────────────────────────────┘ │ │ │ │
│ │ │ │ │ │
│ └──────────────────────────────────────┘ │ │ │
│ │──────────────────────────────────────┘ │
│ Networks: prod-network, backend-network │ │
│ proxy-network (wacp) │ │
└────────────────────────────────────────────┴────────────────────────────────────────┘📦 Yêu Cầu Tiên Quyết
Công cụ cần thiết
| Công cụ | Phiên bản tối thiểu | Mục đích |
|---|---|---|
| Docker | ≥ 24.0.0 | Build và chạy container |
| Docker Compose | ≥ 2.20.0 | Điều phối nhiều container |
| AWS CLI | ≥ 2.0 | Xác thực và push lên AWS ECR |
| Git | ≥ 2.30 | Quản lý source code & submodules |
Yêu cầu AWS
⚙ Cấu Hình
Bước 1: Clone Repository và Khởi Tạo Submodule
Bước 2: Cấu Hình Biến Môi Trường
.env riêng. Copy file mẫu production tương ứng:internal
commercial
wacp
websocket
Bước 3: Cấu Hình Source .env
🏭 Build & Đẩy Image Lên AWS ECR
Bước 1: Đăng Nhập AWS ECR
Bước 2: Build Base Image (nếu cần cập nhật)
Lưu ý: Lặp lại cho mỗi base image của các thành phần khác (commercial, wacp, websocket) nếu cần.
Bước 3: Build & Push Image Cho Từng Thành Phần
3.1 internal
3.2 commercial
3.3 wacp
3.4 websocket
🚀 Triển Khai Lên Production
Bước 1: Chuẩn Bị Trên Server Production
Bước 2: Đăng Nhập ECR Và Pull Images Mới
Bước 3: Triển Khai Từng Thành Phần
3.1 Triển khai internal
3.2 Triển khai commercial
3.3 Triển khai wacp
3.4 Triển khai websocket
Bước 4: Kiểm Tra Trạng Thái
📋 Tham Khảo Cấu Hình Runtime
Container Services
| Thành phần | Service | Image Source | Port | Mục đích |
|---|---|---|---|---|
| internal | *.app | ECR :app-latest | 51011 | API chính + searchsync binaries |
| internal | *.cron | ECR :cron-latest | — | Scheduled tasks |
| commercial | *.app | ECR :app-latest | 51010 | Commercial API |
| commercial | *.cron | ECR :cron-latest | — | Scheduled tasks + leftovers cleanup |
| wacp | *.app | ECR :app-latest | 51011 | WACP API |
| wacp | *.cron | ECR :cron-latest | — | Scheduled tasks |
| websocket | *.app | ECR :app-latest | 51011 | WebSocket server |
Volume Mounts
| Đường dẫn mount (Container) | Nguồn | Chế độ | Mục đích |
|---|---|---|---|
/app/.env | build/source/.env | RO | Biến môi trường ứng dụng |
/app/tls/ca.crt | build/conf/cert/ca.crt | RO | TLS certificate (internal, wacp) |
Lưu ý: Websocket không mount TLS cert. Wacp mount .envtừ${SPORT_SOURCE}/.envthay vì${SPORT_ENV}.
Networks
| Thành phần | Networks |
|---|---|
| internal | prod-network, backend-network |
| commercial | prod-network, backend-network |
| wacp | proxy-network |
| websocket | prod-network |
Biến Môi Trường Đặc Biệt
| Biến | Thành phần | Service | Giá trị mặc định | Mục đích |
|---|---|---|---|---|
SP_ENABLE_CRON | all (×3) | cron | false | Bật/tắt cron scheduler |
SP_LEFTOVERS_INTERVAL_SECS | commercial | cron | 43200 | Interval cleanup leftovers (12h) |
Modified at 2026-03-23 04:37:24