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:Frontend được build tĩnh (minified, chunked) và phục vụ bởi Nginx, không chạy trực tiếp trên Node.js dev server.
Source map bị loại bỏ để bảo vệ mã nguồn.
Kết nối với Backend API Engine thuộc nhánh staging, dữ liệu hoàn toàn tách biệt với môi trường Local.
Build diễn ra trực tiếp trên server (on-server build) thay vì build trên máy CI runner rồi push image.
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 TRAFFIC_DEV_77_37_47_88_KEY (được lưu dạng base64) 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, bao gồm: cài đặt Node.js dependencies, chạy npm run build:dev, copy output vào Nginx container.
Khởi động container mới với image vừa build.
Chạy ở chế độ detached (-d).
docker container restart nginx-service khởi động lại Nginx để áp dụng cấu hình mới và phục vụ file tĩnh mới nhất.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/admin | /home/traffic/project/traffic/stg/admin |
| Repository | devops/develop/traffic/admin.git | devops/staging/traffic/admin.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:Kỹ thuật lấy IP qua AWS tag thay vì hardcode IP giúp pipeline hoạt động đúng ngay cả khi EC2 instance bị thay thế hoặc IP thay đổi.
6. Cấu Hình Nginx Trong Container#
6.1. Cấu Hình SPA Fallback#
Vì Admin Dashboard sử dụng HTML5 History Mode, Nginx cần cấu hình try_files để xử lý SPA routing:Không có cấu hình này, khi người dùng làm mới trang tại URL như /system-management/proxy-management, Nginx sẽ tìm file vật lý tương ứng và trả về 404.6.2. Cấu Hình Cache#
7. Dockerfile Cho Môi Trường Development/Staging#
Lưu ý: Dockerfile này sử dụng npm run preview (Vite preview server) thay vì Nginx thuần túy. Đây là cách tiếp cận đơn giản cho môi trường non-production.
8. Xử Lý Sự Cố Triển Khai#
8.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ó được thêm vào ~/.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'.
8.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:8.3. Lỗi npm install Trong Docker Build#
Triệu chứng: npm install thất bại do lỗi mạng hoặc registry timeout.Hoặc cấu hình npm registry mirror trong Dockerfile:8.4. Kiểm Tra Cấu Hình Nginx Trong Container#
Để xem file cấu hình và biến môi trường đang được áp dụng:Nếu runtime.config.js trỏ về sai địa chỉ API, cần sửa file public/runtime.config.js trong mã nguồn và deploy lại. Không sửa trực tiếp trong container vì thay đổi sẽ mất khi container restart.8.5. Ổ Cứng Server Đầy#
Triệu chứng: Docker build thất bại với lỗi no space left on device.
9. Quy Trình Triển Khai Thủ Công#
Trong trường hợp pipeline CI/CD gặp sự cố, có thể triển khai thủ công:9.1. Kết Nối SSH Đến Server#
9.2. Cập Nhật Code Và Build#
9.3. Kiểm Tra Sau Khi Deploy#
10. Quy Trình Kiểm Thử Trên Staging#
10.1. Checklist Kiểm Thử Sau Deploy#
Sau mỗi lần deploy lên Staging, thực hiện kiểm tra theo checklist:Truy cập URL Staging và trang đăng nhập hiển thị đúng.
Đăng nhập với tài khoản test thành công.
Trang reportDaily hiển thị dữ liệu.
Sidebar menu hiển thị đầy đủ các mục.
Breadcrumb cập nhật đúng khi chuyển trang.
Thực hiện các test case cho tính năng vừa được deploy.
Kiểm tra các tính năng liên quan có bị ảnh hưởng không (regression testing).
DevTools → Console → Không có lỗi JavaScript.
DevTools → Network → Không có request nào trả về 4xx hoặc 5xx.
Kiểm tra responsive trên màn hình 1280px và 1920px.
10.2. Quy Trình Báo Cáo Lỗi#
Khi phát hiện lỗi trên Staging:Tạo issue trên GitLab với tiêu đề mô tả ngắn gọn.
Đính kèm screenshot hoặc video ghi lại lỗi.
Mô tả các bước tái hiện lỗi.
Đính kèm log từ DevTools Console và Network tab.
Gán issue cho developer phụ trách tính năng liên quan.
10.3. Môi Trường Staging Vs Production#
| Khía Cạnh | Staging | Production |
|---|
| Phương thức build | On-server build (Docker Compose) | Pre-built image từ ECR |
| Kích thước image | Lớn (bao gồm Node.js) | Nhỏ (chỉ Nginx + file tĩnh) |
| Thời gian deploy | 5-10 phút (bao gồm npm install và build) | 1-2 phút (chỉ pull image và restart) |
| Rollback | Cần build lại | Chỉ cần đổi tag image |
| Bảo mật | Mã nguồn có trên server | Không có mã nguồn trên server |
| Mục đích | Kiểm thử tính năng | Phục vụ người dùng thực tế |
11. Quản Lý Nhánh Git Và Môi Trường#
11.1. Chiến Lược Nhánh#
Dự án sử dụng chiến lược nhánh theo môi trường:| 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ế |
11.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
11.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.
12. Tối Ưu Hóa Pipeline CI/CD#
12.1. Giảm Thời Gian Build#
Các kỹ thuật tối ưu thời gian build trên server:Sử dụng npm ci thay vì npm install trong Dockerfile để cài đặt dependencies nhanh hơn và nhất quán hơn.
Cache node_modules giữa các lần build bằng Docker layer caching.
Sử dụng .dockerignore để loại trừ các file không cần thiết khỏi build context.
node_modules
dist
.git
.gitignore
*.md
docs/
12.2. Parallel Jobs#
Nếu cần tăng tốc pipeline, có thể chạy các job song song:12.3. Thông Báo Kết Quả Pipeline#
Cấu hình GitLab để gửi thông báo khi pipeline thành công hoặc thất bại:Vào GitLab project → Settings → Integrations → Slack notifications.
Cấu hình Slack webhook URL.
Chọn các sự kiện cần thông báo: Pipeline succeeded, Pipeline failed.
13. Bảo Mật Môi Trường Staging#
13.1. Hạn Chế Truy Cập#
Môi trường Staging không nên được truy cập công khai. Các biện pháp bảo vệ:Cấu hình Nginx với HTTP Basic Authentication để yêu cầu username/password khi truy cập.
Giới hạn IP được phép truy cập qua firewall hoặc Security Group của AWS.
Sử dụng VPN để chỉ cho phép truy cập từ mạng nội bộ của công ty.
13.2. Dữ Liệu Test#
Môi trường Staging nên sử dụng dữ liệu test, không phải dữ liệu production thực tế:Tài khoản test với quyền hạn đầy đủ để kiểm thử mọi tính năng.
Dữ liệu proxy test (không phải proxy thực đang sử dụng).
Dữ liệu chiến dịch test với số lượng nhỏ.
13.3. Không Commit Thông Tin Nhạy Cảm#
Kiểm tra trước khi commit:Không commit file .env.local hay bất kỳ file chứa thông tin nhạy cảm.
Không commit SSH key hay AWS credentials.
Sử dụng git-secrets hoặc detect-secrets để tự động phát hiện secret trong code.
Modified at 2026-03-27 04:37:32
