Cấu Hình Môi Trường — Admin Dashboard Traffic Tools V2

Phiên bản: 0.0.1
Cập nhật lần cuối: 26/03/2026
Phạm vi: Toàn bộ cơ chế cấu hình môi trường của Admin Dashboard: biến môi trường Vite, cấu hình build, alias đường dẫn, chiến lược bundle và xử lý đa môi trường.

1. Tổng quan

Admin Dashboard dùng hệ thống file .env của Vite để tách biệt cấu hình giữa các môi trường. Vite đọc tất cả biến bắt đầu bằng VITE_ và nhúng giá trị đó vào mã nguồn tại thời điểm build (compile-time), không phải lúc chạy (runtime).

Điều này có nghĩa là:

Biến môi trường không thể thay đổi sau khi build mà không build lại.

Để thay đổi địa chỉ API server mà không build lại, dùng cơ chế window.configs injection (xem mục 3).

Không có file .env nào chứa secret key hay mật khẩu database — mã nguồn frontend hoàn toàn có thể bị đọc qua DevTools.

2. Các file environment

2.1. File .env theo môi trường

File	Lệnh kích hoạt	Môi trường mục tiêu
`.env.development`	`npm run dev` hoặc `npm run build:dev`	Máy cục bộ của developer
`.env.staging`	`npm run build:stg`	Server kiểm thử chung
`.env.release`	`npm run build:release`	Server Release trước Production
`.env.production`	`npm run build:prod` hoặc `npm run build:prod:docker`	Môi trường vận hành thực tế

Thứ tự ưu tiên đọc file: .env → .env.{mode} → .env.{mode}.local. File sau ghi đè file trước. File kết thúc bằng .local không được commit vào Git.

2.2. Nội dung các file

.env.development:

NODE_MODE=development
VITE_API_SERVER=http://localhost:33001

.env.production:

NODE_MODE=production
VITE_API_SERVER=https://traffic-api.longtu.club

Các file .env.staging và .env.release có cấu trúc tương tự, chỉ khác ở giá trị VITE_API_SERVER.

3. Biến môi trường đang sử dụng

3.1. Biến cấu hình chính

Tên biến	Dev	Prod	Ý nghĩa
`VITE_API_SERVER`	`http://localhost:33001`	`https://traffic-api.longtu.club`	Base URL của Backend API Engine. Axios nối thêm `/api` vào sau.
`NODE_MODE`	`development`	`production`	Phân biệt chế độ chạy Node.js. Không có tiền tố `VITE_`.

3.2. Biến Vite hệ thống

Biến	Ví dụ	Mô tả
`import.meta.env.MODE`	`development`, `staging`, `production`	Đọc từ `--mode` của lệnh build.
`import.meta.env.BASE_URL`	`/`	Base URL của ứng dụng.
`import.meta.env.PROD`	`true` / `false`	`true` khi `MODE !== development`.
`import.meta.env.DEV`	`true` / `false`	`true` khi `MODE === development`.

3.3. Cách đọc biến môi trường trong mã nguồn

Dự án dùng hàm useEnv trong src/composables/utils.ts thay vì đọc trực tiếp import.meta.env:

Thứ tự ưu tiên:

window.configs[key] — Có thể được inject từ Nginx để override mà không cần build lại.

import.meta.env[key] — Giá trị đã nhúng cứng lúc build.

undefined nếu cả hai đều không có.

Nơi useEnv được dùng:

4. Window.configs — override không cần build lại

4.1. Mục đích

Trong production, build lại ứng dụng chỉ để thay đổi địa chỉ API server là không thực tế. Cơ chế window.configs cho phép inject giá trị cấu hình vào runtime mà không cần build lại.

4.2. Cách hoạt động

File public/runtime.config.js được phục vụ trực tiếp bởi Nginx (không qua build pipeline) và được nhúng vào index.html trước khi ứng dụng Vue khởi động:

Nội dung runtime.config.js:

4.3. Override qua Nginx sub_filter

Có thể inject window.configs trực tiếp qua Nginx sub_filter — hữu ích khi deploy cùng một Docker image lên nhiều môi trường khác nhau:

5. Cấu hình Vite

5.1. Path alias

Alias	Trỏ đến	Ví dụ
`@`	`./src`	`import { useAuthStore } from '@/stores/authStore'`
`@api`	`./src/services/api`	`import { apiAuth } from '@api/auth'`
`@locales`	`./locales`	Dùng trong cấu hình i18n plugin

5.2. Auto-import plugin

unplugin-auto-import tự động import vào mọi file từ:

vue, vue-router, pinia, @vueuse/core, @iconify/vue, naive-ui, zod.

src/composables/**, src/stores/**, src/services/api/**.

File khai báo type được tạo tự động tại types/auto-imports.d.ts.

5.3. Auto-import component

unplugin-vue-components tự động resolve và import tất cả Naive UI components trong template — không cần import thủ công.

5.4. Phân tách bundle

5.5. Xử lý xlsx-js-style

5.6. Cấu hình i18n plugin

6. Cấu hình TypeScript

strict: true — Bật tất cả kiểm tra strict mode.

noUnusedLocals: true — Báo lỗi khi có biến cục bộ không dùng.

noUnusedParameters: true — Báo lỗi khi có tham số hàm không dùng.

noImplicitReturns: true — Báo lỗi khi hàm không có return rõ ràng.

paths — Khai báo alias @/* tương ứng với cấu hình Vite.

vue-tsc được dùng thay cho tsc để kiểm tra kiểu TypeScript trong file .vue. Lệnh npm run typecheck chạy vue-tsc --build --force.

7. Cấu hình Nginx cho frontend

7.1. Cấu hình cơ bản

7.2. Tại sao cần SPA fallback

Admin Dashboard dùng HTML5 History Mode (createWebHistory()). Khi người dùng truy cập trực tiếp vào URL như /system-management/proxy-management hoặc F5 trang, Nginx sẽ tìm file vật lý tương ứng và trả về 404 nếu không có try_files. Cấu hình try_files $uri $uri/ /index.html đảm bảo mọi request đều trả về index.html và Vue Router xử lý điều hướng phía client.

7.3. Chiến lược cache

File trong assets/ có hash trong tên — cache vĩnh viễn vì tên file thay đổi khi nội dung thay đổi.

index.html và runtime.config.js không có hash — phải cache với no-cache để browser luôn lấy phiên bản mới nhất.

8. Biến môi trường trong CI/CD

8.1. GitLab CI variables

Biến	Môi trường	Mô tả
`TRAFFIC_DEV_77_37_47_88_KEY`	Develop, Staging	SSH private key (base64) để kết nối server dev/staging.
`TRAFFIC_DEV_77_37_47_88_USER`	Develop, Staging	Username SSH.
`TRAFFIC_DEV_77_37_47_88_IP`	Develop, Staging	Địa chỉ IP server.
`TRAFFIC_DEV_77_37_47_88_PORT`	Develop, Staging	Port SSH.
`AWS_TRAFFIC_REL_KEY`	Release	SSH private key cho server release.
`BASTION_BUILD_KEY`	Production Build	SSH private key cho Bastion Build Server.
`BASTION_BUILD_USER`	Production Build	Username SSH.
`BASTION_BUILD_IP`	Production Build	Địa chỉ IP.
`BASTION_BUILD_PORT`	Production Build	Port SSH.
`AWS_TRAFFIC_PROD_KEY`	Production Deploy	SSH private key cho server production.
`AWS_ACCESS_KEY_ID`	Production	AWS Access Key ID để đăng nhập ECR.
`AWS_SECRET_ACCESS_KEY`	Production	AWS Secret Access Key.
`AWS_DEFAULT_REGION`	Production	AWS Region (ap-southeast-1).

8.2. Biến cố định trong .gitlab-ci.yml

TAG_COMMIT dùng $CI_COMMIT_SHORT_SHA — 8 ký tự đầu của commit hash — cho phép rollback về bất kỳ phiên bản nào bằng cách chỉ định tag cụ thể.

9. Cấu hình Tailwind CSS

10. Cấu hình theme Naive UI

Áp dụng trong App.vue:

<template>
  <NConfigProvider :theme-overrides="themeOverrides">
    <RouterView />
  </NConfigProvider>
</template>

11. Cấu hình ESLint

vue/multi-word-component-names: off — Cho phép component tên một từ như IndexView.vue.

@typescript-eslint/no-explicit-any: warn — Cảnh báo khi dùng any, không chặn hoàn toàn.

no-console: warn — Cảnh báo khi dùng console.log, nhưng cho phép console.error và console.warn.

12. Cấu hình Prettier

{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "none",
  "tabWidth": 2,
  "useTabs": false,
  "endOfLine": "lf",
  "vueIndentScriptAndStyle": false
}

semi: false — Không dùng dấu chấm phẩy cuối câu.

singleQuote: true — Dùng nháy đơn.

printWidth: 100 — Độ rộng tối đa 100 ký tự.

endOfLine: lf — Dùng LF (Unix) để nhất quán giữa các hệ điều hành.

13. Cấu hình Husky và lint-staged

Pre-commit hook (.husky/pre-commit):

Commit-msg hook (.husky/commit-msg):

lint-staged (.husky/lintstagedrc.js):

Chỉ lint và format các file đã staged, không lint toàn bộ dự án mỗi lần commit.

14. Quản lý phiên bản

Dự án dùng conventional-changelog-cli để tự động tạo CHANGELOG.md từ lịch sử commit:

Phiên bản hiện tại được định nghĩa trong package.json:

{
  "name": "wallet",
  "version": "0.0.1"
}

Tên package là wallet — đây là tên nội bộ của dự án.

Environment & Configuration

Cấu Hình Môi Trường — Admin Dashboard Traffic Tools V2#

1. Tổng quan#

2. Các file environment#

2.1. File .env theo môi trường#

2.2. Nội dung các file#

3. Biến môi trường đang sử dụng#

3.1. Biến cấu hình chính#

3.2. Biến Vite hệ thống#

3.3. Cách đọc biến môi trường trong mã nguồn#

4. Window.configs — override không cần build lại#

4.1. Mục đích#

4.2. Cách hoạt động#

4.3. Override qua Nginx sub_filter#

5. Cấu hình Vite#

5.1. Path alias#

5.2. Auto-import plugin#

5.3. Auto-import component#

5.4. Phân tách bundle#

5.5. Xử lý xlsx-js-style#

5.6. Cấu hình i18n plugin#

6. Cấu hình TypeScript#

7. Cấu hình Nginx cho frontend#

7.1. Cấu hình cơ bản#

7.2. Tại sao cần SPA fallback#

7.3. Chiến lược cache#

8. Biến môi trường trong CI/CD#

8.1. GitLab CI variables#

8.2. Biến cố định trong .gitlab-ci.yml#

9. Cấu hình Tailwind CSS#

10. Cấu hình theme Naive UI#

11. Cấu hình ESLint#

12. Cấu hình Prettier#

13. Cấu hình Husky và lint-staged#

14. Quản lý phiên bản#