1. Tổng Quan Môi Trường Staging#
Môi trường Staging là khu vực kiểm thử trước khi đưa tính năng lên Production. Đặc điểm phân biệt với môi trường Local:API được build thành Docker image và chạy trong container, không chạy trực tiếp bằng go run.
Build diễn ra trực tiếp trên server (on-server build) — Docker Compose build image từ Dockerfile ngay tại server.
Kết nối với database Staging riêng biệt, dữ liệu hoàn toàn tách biệt với Local.
AUTO_MIGRATE_DATABASE=false — Không tự động migrate schema.
Log được ghi vào file, không in ra stdout như khi chạy local với Air.
2. Cấu Trúc Pipeline CI/CD#
2.1. Các Stage Trong .gitlab-ci.yml#
2.2. Điều Kiện Kích Hoạt#
| Stage | Nhánh Git | Môi Trường |
|---|
deploy-develop | develop | Server Develop |
deploy-staging | staging | Server Staging |
deploy-release | release | Server Release (AWS EC2) |
build-master | master | Bastion Build Server |
deploy-master | master | Server Production (AWS EC2) |
3. Triển Khai Môi Trường Develop#
3.1. Cấu Hình#
3.2. Quy Trình Tự Động#
Khi có commit mới vào nhánh develop, pipeline thực hiện các bước sau trên server Develop:GitLab Runner giải mã SSH private key từ biến CI/CD và nạp vào SSH agent.Bước 2 — Kết nối SSH đến server và thực thi script:Bước 3 — Docker Compose Build:Lệnh docker compose up --build -d thực hiện:Đọc file docker-compose.yml trong thư mục deploy.
Build Docker image mới từ Dockerfile development (multi-stage build):Stage 1 (builder): golang:1.22-alpine — cài dependencies, build binary.
Stage 2 (final): alpine:latest — chỉ copy binary, không có Go toolchain.
Khởi động container mới với image vừa build.
Chạy ở chế độ detached (-d).
docker image prune -f xóa tất cả Docker image không được sử dụng bởi bất kỳ container nào. Ngăn ổ cứng server bị đầy do tích lũy image cũ.
4. Triển Khai Môi Trường Staging#
4.1. Cấu Hình#
4.2. Quy Trình Tự Động#
Quy trình tương tự Develop, nhưng:Kết nối đến cùng server (TRAFFIC_DEV_77_37_47_88_*) nhưng thư mục deploy khác (/stg/ thay vì /dev/).
Checkout nhánh staging thay vì develop.
Sử dụng repository riêng cho môi trường Staging.
4.3. Sự Khác Biệt Giữa Develop Và Staging#
| Khía Cạnh | Develop | Staging |
|---|
| Nhánh Git | develop | staging |
| Thư mục deploy | /home/traffic/project/traffic/dev/api | /home/traffic/project/traffic/stg/api |
| Repository | devops/develop/traffic/api.git | devops/staging/traffic/api.git |
| Mục đích | Kiểm thử tính năng đang phát triển | Kiểm thử UAT trước khi release |
| Dữ liệu | Dữ liệu test của developer | Dữ liệu test gần với production |
5. Triển Khai Môi Trường Release#
5.1. Cấu Hình#
5.2. Điểm Khác Biệt So Với Staging#
Môi trường Release chạy trên AWS EC2, do đó pipeline cần thêm bước lấy địa chỉ IP động:
6. Dockerfile Development (Multi-Stage Build)#
Multi-stage build đảm bảo image cuối chỉ chứa binary (~25MB) thay vì toàn bộ Go toolchain (~800MB).
7. Xử Lý Sự Cố Triển Khai#
7.1. Pipeline Thất Bại Do Lỗi SSH#
Triệu chứng: Pipeline báo lỗi Permission denied (publickey).Biến CI/CD TRAFFIC_DEV_77_37_47_88_KEY có được cấu hình đúng không.
Public key tương ứng có trong ~/.ssh/authorized_keys trên server không.
Lệnh decode base64 có hoạt động đúng không: echo "$KEY" | base64 -d | tr -d '\r'.
7.2. Pipeline Thất Bại Do Lỗi Docker Build#
Triệu chứng: Lỗi trong bước docker compose up --build.Đăng nhập SSH vào server và thực hiện:7.3. Lỗi go.mod Không Đồng Nhất#
Triệu chứng: Build thất bại với lỗi missing go.sum entry.Nguyên nhân: Developer thêm package mới nhưng quên commit file go.sum.Giải pháp: Developer local chạy go mod tidy và commit lại cả go.mod và go.sum.7.4. Container Khởi Động Rồi Tắt Ngay#
Triệu chứng: docker ps không thấy container API đang chạy.File .env trong container có cấu hình sai (database host, port).
Database chưa sẵn sàng khi API khởi động.
Lỗi panic trong hàm init() hoặc main().
7.5. Ổ Cứng Server Đầy#
Triệu chứng: Docker build thất bại với lỗi no space left on device.7.6. Kiểm Tra Cấu Hình Trong Container#
8. Quy Trình Kiểm Thử Trên Staging#
8.1. Checklist Sau Deploy#
Sau mỗi lần deploy lên Staging, thực hiện kiểm tra:Gọi GET / và nhận response {"message": "Hello, World!"}.
Đăng nhập với tài khoản test và nhận JWT token.
Gọi GET /api/user/profile với token và nhận thông tin user.
Kiểm tra một endpoint CRUD cơ bản (ví dụ: GET /api/server/).
Kiểm tra log container không có lỗi panic.
8.2. Kiểm Tra Cron Job#
Sau khi deploy, kiểm tra cron job đang chạy:Log phải có dòng: All cronjobs initialized successfully.8.3. Kiểm Tra Kết Nối Database#
9. Quản Lý Nhánh Git Và Môi Trường#
9.1. Chiến Lược Nhánh#
| Nhánh | Môi Trường | Mục Đích |
|---|
develop | Develop | Tích hợp tính năng đang phát triển |
staging | Staging | Kiểm thử UAT trước khi release |
release | Release | Kiểm thử cuối cùng trước production |
master | Production | Phiên bản đang chạy cho người dùng thực tế |
9.2. Quy Trình Merge#
feature/ten-tinh-nang
|
v (Merge Request)
develop
|
v (Merge Request sau khi test xong)
staging
|
v (Merge Request sau khi UAT xong)
release
|
v (Merge Request sau khi kiểm thử cuối)
master
9.3. Quy Tắc Bảo Vệ Nhánh#
Nhánh master, staging, release được bảo vệ (Protected Branch).
Không ai được push trực tiếp vào các nhánh này, phải qua Merge Request.
Merge Request cần ít nhất 1 approval từ Tech Lead hoặc Senior Developer.
Pipeline CI/CD phải pass trước khi được phép merge.
Modified at 2026-03-26 10:42:49
