Giao diện

Cài đặt và sử dụng — Environment Variables ​

Tổng quan ​

Plugin plugin-environment-variables cho phép quản lý biến môi trường trực tiếp từ giao diện quản trị, thay vì phải SSH vào server để sửa file .env. Biến được lưu trong database, mã hóa AES cho giá trị nhạy cảm, và tự động load khi khởi động ứng dụng.

Yêu cầu ​

Thành phầnYêu cầu
Server DigiforcePhiên bản >= 1.0
QuyềnChỉ admin mới có quyền quản lý biến môi trường

Bước 1: Kích hoạt plugin ​

  1. Truy cập Settings → Plugin Manager
  2. Tìm plugin-environment-variables
  3. Bật công tắc Enable

Plugin đăng ký resource environmentVariables với quyền ACL:

  • list — cho phép user đã đăng nhập xem danh sách biến (giá trị secret bị ẩn)
  • CRUD đầy đủ — chỉ admin (qua snippet pm.environment-variables)

Bước 2: Quản lý biến môi trường ​

Vào Settings → Environment Variables để xem và quản lý:

Thêm biến mới ​

  1. Nhấn Add variable
  2. Nhập tên biến (bắt buộc tuân theo quy tắc: bắt đầu bằng chữ cái, chỉ chứa chữ, số, gạch dưới)
  3. Nhập giá trị
  4. Chọn loại: Default (hiển thị) hoặc Secret (mã hóa, ẩn giá trị)
  5. Lưu

Quy tắc đặt tên ​

Tên biến phải khớp với regex: ^[A-Za-z][A-Za-z0-9_]*$

Hợp lệKhông hợp lệ
API_KEY123_KEY (bắt đầu bằng số)
smtpHostsmtp-host (chứa dấu gạch ngang)
DB_PORT_5432DB PORT (chứa khoảng trắng)

Import hàng loạt ​

Plugin hỗ trợ import biến từ text có format giống file .env:

API_KEY=your-api-key-here
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
# Đây là comment, sẽ bị bỏ qua
DATABASE_URL=postgres://user:pass@host:5432/db

Quy tắc:

  • Mỗi dòng một biến theo format KEY=VALUE
  • Dòng bắt đầu bằng # là comment, bị bỏ qua
  • Dòng trống bị bỏ qua
  • Tên biến không được để trống
  • Giá trị không được để trống (plugin từ chối biến không có giá trị)

Loại biến ​

LoạiMô tảGiá trị hiển thị
defaultBiến thông thườngHiển thị đầy đủ
secretBiến nhạy cảm (API key, password...)Ẩn khi list, mã hóa AES trong database

Mã hóa Secret ​

Khi lưu biến loại secret:

  1. Giá trị được mã hóa AES trước khi ghi vào database
  2. Khi load lên memory, giá trị được giải mã tự động
  3. Khi API list trả về, giá trị secret hiển thị là undefined (ẩn)

Lưu ý bảo mật

Mã hóa AES sử dụng key từ app.aesEncryptor. Đảm bảo AES key được cấu hình và bảo mật đúng cách.

Cách sử dụng biến trong ứng dụng ​

Từ server-side code ​

typescript
// Lấy giá trị biến môi trường
const value = app.environment.getVariable('API_KEY');

// Lấy tất cả biến
const allVars = app.environment.getVariables();

Từ plugin khác (ví dụ: REST API Data Source) ​

Trong template variables, sử dụng $env:

{{$env.API_KEY}}
{{$env.SMTP_HOST}}

Trong cấu hình form (TextAreaWithGlobalScope) ​

Một số trường cấu hình hỗ trợ biến môi trường. Khi nhập giá trị, bạn có thể tham chiếu đến biến:

{{$env.DATABASE_HOST}}

Cơ chế đồng bộ (Sync) ​

Khi biến thay đổi, plugin gửi sync message đến tất cả instance (trong môi trường multi-instance):

Sự kiệnMessage TypeHành động
Thêm/sửa biếnsetVariableCập nhật biến trong memory
Xóa biếnremoveVariableXóa biến khỏi memory, đánh dấu updated = true
Cập nhật bất kỳupdatedĐánh dấu updated = true

Response của API list bao gồm meta.updated — frontend sử dụng flag này để hiển thị thông báo "Cần restart để áp dụng thay đổi".

Thứ tự ưu tiên ​

Biến từ plugin ghi đè giá trị trong process.env. Thứ tự load:

  1. Biến hệ thống (OS environment)
  2. File .env
  3. Biến từ plugin (ưu tiên cao nhất)

Lưu ý ​

  • Biến lưu trong database nên không mất khi restart (khác với process.env)
  • Thay đổi biến có hiệu lực ngay cho các request mới (hot reload)
  • Một số tính năng cần restart (ví dụ: database connection string)
  • Chỉ admin mới có quyền tạo/sửa/xóa biến; user thường chỉ xem danh sách tên
  • Tên biến là primary key — không thể đổi tên, cần xóa và tạo lại