Система окружения

Управление переменными окружения через настраиваемые бэкенды хранения.

Обзор

Система окружения разделяет хранение и доступ:

Хранилища — где хранятся значения (ОС, файлы, память)
Переменные — именованные ссылки на значения в хранилищах

На переменные можно ссылаться по:

Публичному имени — значение поля variable (должно быть уникальным в системе)
ID записи — полная ссылка namespace:name

Если переменная не должна быть доступна публично по имени, не указывайте поле variable.

Типы записей

Тип	Описание
`env.storage.memory`	Хранилище в памяти
`env.storage.file`	Файловое хранилище (формат .env)
`env.storage.os`	Доступ к переменным ОС (только чтение)
`env.storage.static`	Статическое хранилище (только чтение)
`env.storage.router`	Объединение нескольких хранилищ
`env.variable`	Именованная переменная со ссылкой на хранилище

Бэкенды хранения

Хранилище в памяти

Волатильное хранилище в памяти:

- name: runtime_env
  kind: env.storage.memory

Файловое хранилище

Персистентное хранилище в формате .env (KEY=VALUE с комментариями #):

- name: app_config
  kind: env.storage.file
  file_path: /etc/app/config.env
  auto_create: true
  file_mode: 0600
  dir_mode: 0700

Поле	Тип	По умолчанию	Описание
`file_path`	string	обязательно	Путь к .env файлу
`auto_create`	boolean	false	Создать файл, если не существует
`file_mode`	integer	0644	Права на файл
`dir_mode`	integer	0755	Права на директорию

Хранилище ОС

Доступ к переменным окружения операционной системы (только чтение):

- name: os_env
  kind: env.storage.os

Всегда только для чтения. Операции записи возвращают PERMISSION_DENIED.

Статическое хранилище

Хранилище только для чтения со значениями, определёнными непосредственно в конфигурации. Значения встраиваются в запись и не могут быть изменены во время выполнения. Полезно для публичных конфигурационных констант, поставляемых с модулем или пакетом.

- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    PUBLIC_WS_HOST: "wss://api.example.com/ws"
    APP_ENV: "production"

Поле	Тип	Описание
`values`	map	Пары ключ-значение (строка в строку)

Всегда только для чтения. Операции записи возвращают PERMISSION_DENIED.

Маршрутизирующее хранилище

Объединяет несколько хранилищ. Чтение ищет по порядку до первого найденного. Запись идёт только в первое хранилище.

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Основное (запись сюда)
    - app.config:file      # Резервное
    - app.config:os        # Резервное

Поле	Тип	Описание
`storages`	array	Упорядоченный список ссылок на хранилища

Переменные

Переменные обеспечивают именованный доступ к значениям в хранилищах:

- name: DATABASE_URL
  kind: env.variable
  variable: DATABASE_URL
  storage: app.config:file
  default: postgres://localhost/app
  read_only: false

Поле	Тип	Описание
`variable`	string	Публичное имя переменной (необязательно, должно быть уникальным)
`storage`	string	Ссылка на хранилище (`namespace:name`)
`default`	string	Значение по умолчанию, если не найдено
`read_only`	boolean	Запретить изменения

Именование переменных

Имена переменных могут содержать только: a-z, A-Z, 0-9, _

Паттерны доступа

# Публичная переменная — доступна по имени "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Приватная переменная — доступна только по ID "app.config:internal_key"
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

Ошибки

Ситуация	Тип	Повтор
Переменная не найдена	`errors.NOT_FOUND`	нет
Хранилище не найдено	`errors.NOT_FOUND`	нет
Переменная только для чтения	`errors.PERMISSION_DENIED`	нет
Хранилище только для чтения	`errors.PERMISSION_DENIED`	нет
Неверное имя переменной	`errors.INVALID`	нет

Доступ во время работы

Модуль env — доступ из Lua

См. также

Модель безопасности — контроль доступа к переменным окружения
Руководство по конфигурации — паттерны конфигурации приложений