Tham chiếu Cấu hình
Nền tảng VENI-AI sử dụng các biến môi trường cho mọi thiết lập cấu hình. Shell API xác thực các biến này khi khởi động bằng Zod để đảm bảo tính toàn vẹn của hệ thống.
🐚 Các biến Shell API (shell/api/.env)
Các biến này được định nghĩa trong shell/api/env.example và là bắt buộc để Shell API hoạt động chính xác.
1. Cấu hình Ứng dụng
| Biến | Mặc định | Mô tả |
|---|---|---|
APP_ENV_PORT | 3000 | Cổng HTTP mà API lắng nghe. |
APP_ENV_SERVER_BASE_PATH | /api | Đường dẫn gốc cho tất cả các route API. |
APP_ENV_APPLICATION_NAME | shell | Tên nội bộ của ứng dụng. |
APP_ENV_APPLICATION_TIMEZONE | Asia/Ho_Chi_Minh | Múi giờ của ứng dụng. |
DEBUG | true | Bật nhật ký chi tiết và thông báo lỗi. |
NODE_ENV | development | development, production, hoặc test. |
2. Cơ sở dữ liệu & Cache
| Biến | Giá trị mặc định | Mô tả |
|---|---|---|
APP_ENV_DATABASE_URL | postgresql://shell:shell@localhost:15433/shell_db | Chuỗi kết nối PostgreSQL. |
APP_ENV_REDIS_URL | redis://localhost:16379 | Kết nối Redis cho cache và trạng thái. |
3. Định danh & Bảo mật
| Biến | Mặc định | Mô tả |
|---|---|---|
APP_ENV_JWT_SECRET | 8fc28702811e... | Secret để ký HS256 (Dự phòng/Phát triển local). |
APP_ENV_JWT_PRIVATE_KEY | - | Khóa riêng RSA (PEM) để ký RS256. |
🔑 Khởi tạo Secret & Khóa
Để nền tảng được bảo mật, bạn phải tạo các secret và khóa duy nhất cho môi trường của mình.
1. Tạo APP_ENV_JWT_SECRET (HS256)
Được sử dụng cho phát triển local hoặc khi không cung cấp khóa RSA.
bash
# Sử dụng openssl
openssl rand -hex 32
# HOẶC sử dụng Bun/Node
bun -e "console.log(require('crypto').randomBytes(32).toString('hex'))"2. Tạo APP_ENV_JWT_PRIVATE_KEY (RS256)
Shell sử dụng khóa này để ký token bằng thuật toán RS256. Điều này cho phép các ứng dụng remote xác thực token thông qua điểm cuối JWKS công khai.
bash
# 1. Tạo khóa riêng RSA 2048-bit
openssl genrsa -out private.pem 2048
# 2. Chuyển đổi sang định dạng PKCS#8 (bắt buộc bởi Shell)
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out pkcs8.pem
# 3. Sao chép nội dung của pkcs8.pem vào tệp .env của bạn
# Đảm bảo chuỗi nhiều dòng được xử lý chính xác trong trình tải env của bạn.Shell sẽ tự động trích xuất thành phần công khai và cung cấp tại /api/.well-known/jwks.json.
4. Tích hợp Keycloak (OIDC)
| Biến | Mặc định | Mô tả |
|---|---|---|
APP_ENV_KEYCLOAK_URL | http://localhost:18080 | URL Keycloak công khai (trình duyệt có thể truy cập). |
APP_ENV_KEYCLOAK_REALM | veni-ai | Tên realm trong Keycloak. |
APP_ENV_KEYCLOAK_CLIENT_ID | veni-ai-platform | Client ID được cấu hình trong Keycloak. |
APP_ENV_KEYCLOAK_CLIENT_SECRET | y8fEBCBHdEPR... | Client secret để giao tiếp OIDC. |
APP_ENV_KEYCLOAK_REDIRECT_URI | http://localhost:3000/api/auth/callback | URL callback cho luồng OIDC. |
5. Xác thực bên thứ ba (Tùy chọn)
| Biến | Mô tả |
|---|---|
APP_ENV_GOOGLE_CLIENT_ID | Google OAuth client ID. |
APP_ENV_GOOGLE_CLIENT_SECRET | Google OAuth client secret. |
🎨 Các biến Shell UI (shell/ui/.env.development)
| Biến | Mặc định | Mô tả |
|---|---|---|
VITE_API_URL | http://localhost:3000 | URL đầy đủ của Shell API. |
🛰️ Các biến của Satellite (SCS)
Các satellite yêu cầu các cấu hình cụ thể để tương tác với Shell.
API (api/.env)
| Biến | Mặc định | Mô tả |
|---|---|---|
APP_ENV_SHELL_JWKS_URL | http://localhost:3000/api/.well-known/jwks.json | URL cho các khóa công khai của Shell. |
APP_ENV_DATABASE_URL | - | Chuỗi kết nối cơ sở dữ liệu riêng của satellite. |
UI (ui/.env)
| Biến | Mặc định | Mô tả |
|---|---|---|
VITE_API_URL | - | URL API của chính satellite đó. |
VITE_SHELL_URL | http://localhost:5173 | URL của Shell UI (để chuyển hướng SSO). |
💡 Kinh nghiệm Quản lý Môi trường
...
- Phát triển Local: Sử dụng các tệp
.envhoặc.env.local(đã được tự động gitignore). - Môi trường Production (K8s): Sử dụng Kubernetes Secrets hoặc ConfigMaps.
- Bảo mật: Không bao giờ commit các khóa (keys) hoặc mật khẩu thật. Sử dụng tệp
.env.exampleđi kèm để làm mẫu.