Câu hỏi thường gặp (FAQ) — Environment Variables

Sử dụng

Thay đổi biến có cần restart server không?

Tùy loại biến. Plugin áp dụng giá trị mới vào app.environment ngay lập tức (hot reload). Tuy nhiên:

• Không cần restart: Biến được tham chiếu qua $env trong template (REST API headers, v.v.)
• Cần restart: Biến ảnh hưởng đến cấu hình khởi động (database connection, port, SSL cert path)

Khi có thay đổi cần restart, giao diện hiển thị banner nhắc nhở.

Biến môi trường lưu ở đâu?

Trong bảng environmentVariables của database, với các trường:

Trường	Kiểu	Mô tả
name	string (PK)	Tên biến (chữ, số, gạch dưới)
type	string	default hoặc secret
value	text	Giá trị (mã hóa AES nếu secret)

Biến secret bị ẩn giá trị, làm sao kiểm tra?

Khi API list trả về, giá trị secret hiển thị là undefined. Để kiểm tra:

1. Tạo logic sử dụng biến đó (ví dụ: test connection trong REST API plugin)
2. Hoặc tạo biến mới với cùng giá trị nhưng type default để kiểm tra, rồi xóa đi

Có thể đổi tên biến không?

Không trực tiếp. Tên biến (name) là primary key. Để đổi tên:

1. Ghi nhớ giá trị hiện tại
2. Xóa biến cũ
3. Tạo biến mới với tên mới

Tên biến có phân biệt chữ hoa/thường không?

Có. API_KEY và api_key là hai biến khác nhau. Khuyến nghị dùng convention UPPER_SNAKE_CASE cho nhất quán.

Biến từ plugin có ghi đè file .env không?

Có. Biến từ plugin có ưu tiên cao nhất — ghi đè cả process.env và file .env. Cẩn thận khi đặt tên biến trùng.

Tích hợp

Làm sao sử dụng biến trong REST API plugin?

Trong cấu hình REST API data source, sử dụng template syntax:

Headers:
  Authorization: Bearer {{$env.API_TOKEN}}
  X-API-Key: {{$env.EXTERNAL_API_KEY}}

Làm sao sử dụng biến trong form cấu hình?

Một số form cấu hình hỗ trợ component TextAreaWithGlobalScope. Khi nhập giá trị, bạn có thể tham chiếu biến:

{{$env.DATABASE_HOST}}

Plugin nào sử dụng biến môi trường?

Bất kỳ plugin nào truy cập app.environment.getVariables() hoặc app.environment.getVariable(name) đều có thể sử dụng. Ví dụ:

• plugin-data-source-rest-api — API token, base URL
• plugin-email — SMTP credentials
• plugin-file-manager — Storage credentials (S3, OSS)

Lỗi thường gặp

Biến không có hiệu lực?

Kiểm tra:

1. Tên biến đúng (phân biệt hoa/thường)
2. Giá trị không để trống (plugin từ chối giá trị rỗng)
3. Nếu biến ảnh hưởng cấu hình khởi động, thử restart server
4. Kiểm tra flag updated trong response API — nếu true, server cần restart

Lỗi "Invalid environment variable format"?

Khi import hàng loạt, mỗi dòng phải có format KEY=VALUE. Kiểm tra:

• Không thiếu dấu =
• Tên biến không để trống
• Giá trị không để trống

Lỗi giải mã biến secret?

Nếu AES key thay đổi (ví dụ: chuyển server), biến secret cũ không thể giải mã. Cần:

1. Backup AES key cũ
2. Hoặc xóa và tạo lại biến secret sau khi đổi AES key

Biến không đồng bộ giữa các instance?

Plugin sử dụng sync message. Kiểm tra:

• Hệ thống message broker (Redis pub/sub) hoạt động đúng
• Tất cả instance cùng nhóm sync
• Log có lỗi sync không

Bảo mật

Biến secret có an toàn không?

Biến secret được:

• Mã hóa AES trước khi lưu vào database
• Ẩn giá trị khi trả về qua API (value: undefined)
• Giải mã chỉ trong memory khi ứng dụng cần sử dụng

Tuy nhiên, bất kỳ ai có access vào AES key đều có thể giải mã. Bảo vệ AES key cẩn thận.

Ai có quyền xem biến môi trường?

Hành động	Quyền yêu cầu
Xem danh sách biến (tên + type)	loggedIn (mọi user đã đăng nhập)
Xem giá trị biến default	loggedIn
Xem giá trị biến secret	Không ai (luôn ẩn qua API)
Tạo/sửa/xóa biến	Admin (snippet pm.environment-variables)