Environment 系统

通过可配置的存储后端管理环境变量。

概述

环境系统将存储与访问分离：

• Storages - 值的存储位置（OS、文件、内存）
• Variables - 对存储中值的命名引用

变量可以通过以下方式引用：

• 公共名称 - variable 字段值（必须在系统中唯一）
• Entry ID - 完整的 namespace:name 引用

如果不希望变量可以通过名称公开访问，请省略 variable 字段。

Entry 类型

存储后端

内存存储

易失性内存存储。

- 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

OS 存储

只读访问操作系统环境变量。

- name: os_env
  kind: env.storage.os

始终只读。Set 操作返回 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"

始终只读。Set 操作返回 PERMISSION_DENIED。

路由器存储

链接多个存储。按顺序搜索读取直到找到。写入仅到第一个存储。

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Primary (writes here)
    - app.config:file      # Fallback
    - app.config:os        # Fallback

变量

变量提供对存储值的命名访问。

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

变量命名

变量名只能包含：a-z、A-Z、0-9、_

访问模式

# Public variable - accessible by name "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Private variable - accessible only by ID "app.config:internal_key"
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

占位符插值

已注册的变量通过 ${env:NAME} 占位符引入条目配置，在解码时统一根据此注册表解析。条目数据中的任何字符串字段都可以通过这种方式引用变量。

NAME 是已注册变量的公共名称或其条目 ID（带点号/冒号的注册表 ID 形式，例如 app.env:tls_cert）。它不是原始的 OS 环境变量：只有当以 env.storage.os 为后端的变量以该名称注册时，OS 值才可被访问。

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: ${env:app.env:tls_cert}
    key:  ${env:app.env:tls_key}

整个值为单个占位符的字段取变量的类型化值（给定类型化默认值时强制转换为 bool/int/float）；占位符与周围文本混合时则插值为字符串。变量自身的 default 优先于占位符的内联 |default。解析不到值且没有默认值的引用会导致解码失败。

解析只发生在解码时：存储的注册表条目保留原始占位符，因此解析后的密钥绝不会出现在 registry.get 结果或持久化状态中。引用 ${env:...} 的条目在启动时会自动排在其所依赖的 env 存储和变量之后。

错误

运行时访问

• env 模块 - Lua 运行时访问

参见

• Security 模型 - 环境变量的访问控制
• 配置指南 - 应用配置模式