#环境变量

#如何设置环境变量？

#Git 源码或 create-nocobase-app 安装方式

在项目根目录下的 .env 文件里设置环境变量，修改环境变量之后需要 kill 应用进程，重新启动。

#Docker 安装方式

修改 docker-compose.yml 配置，在 enviroment 参数里设置环境变量。示例：

services:
  app:
    image: nocobase/nocobase:latest
    environment:
      - APP_ENV=production

也可以使用 env_file, 即可在 .env 文件中设置环境变量。示例：

services:
  app:
    image: nocobase/nocobase:latest
    env_file: .env

修改环境变量之后，需要重建 app 容器。

docker compose up -d app

#全局环境变量

#TZ

用于设置应用的时区，默认为操作系统时区。

https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

#APP_ENV

应用环境，默认值 development，可选项包括：

• production 生产环境
• development 开发环境

APP_ENV=production

#APP_KEY

应用的密钥，用于生成用户 token 等，修改为自己的应用密钥，并确保不对外泄露

APP_KEY=app-key-test

#APP_PORT

应用端口，默认值 13000

APP_PORT=13000

#API_BASE_PATH

NocoBase API 地址前缀，默认值 /api/

API_BASE_PATH=/api/

#API_BASE_URL

前端页面访问 NocoBase API 使用的基础地址，默认为空，表示使用与页面同源的 ${APP_PUBLIC_PATH}api/。

API_BASE_URL=

只有当页面和 API 服务不同源（协议、域名、端口任一不同）时，才需要配置为 API 的完整地址：

API_BASE_URL=https://api.example.com/api/

#LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS

是否允许匿名访问历史本地文件地址 /storage/uploads/，默认值为 false，即只有登录用户可以访问。

如果已有集成依赖该地址的公开访问，可以显式启用兼容模式：

LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true

修改后需要重启应用。该变量仅影响历史 /storage/uploads/ 地址，不影响 /files/ 的文件记录级权限。启用公开访问可能暴露已上传文件，请仅在确认文件可以公开时使用。

#CORS_ORIGIN_WHITELIST

允许跨源携带凭证（cookie）访问 API 的来源白名单，多个来源以逗号分隔，默认为空。

CORS_ORIGIN_WHITELIST=https://www.example.com,https://admin.example.com

• 未配置时，只有与 API 同源的请求会被视为可信来源；跨源请求仍可匿名调用 API，但浏览器不允许其读写 cookie。
• 配置后，白名单中的来源会获得精确回显的 Access-Control-Allow-Origin 和 Access-Control-Allow-Credentials: true 响应头，浏览器才会在跨源请求中发送并保存登录 cookie。
• 登录接口会校验请求的 Origin / Referer 是否可信，来自白名单之外的跨源登录请求会被拒绝（403）。

#CLUSTER_MODE

v1.6.0+

多核（集群）启动模式，如配置了该变量，会透传至 pm2 start 命令中作为 -i <instances> 的参数。可选项与 pm2 -i 参数一致（参考 PM2: Cluster Mode），包括：

• max：使用 CPU 最大核数
• -1：使用 CPU 最大核数 -1
• <number>：指定核数

默认值为空，代表不开启。

更多可参考：集群模式。

#PLUGIN_PACKAGE_PREFIX

插件包名前缀，默认为：@nocobase/plugin-,@nocobase/preset-。

例如，添加 hello 插件到 my-nocobase-app 项目，插件的完整包名则为 @my-nocobase-app/plugin-hello。

PLUGIN_PACKAGE_PREFIX 可以配置为：

PLUGIN_PACKAGE_PREFIX=@nocobase/plugin-,@nocobase/preset-,@my-nocobase-app/plugin-

则插件名称和包名对应关系如下：

• users 插件的包名为 @nocobase/plugin-users
• nocobase 插件的包名为 @nocobase/preset-nocobase
• hello 插件的包名为 @my-nocobase-app/plugin-hello

#DB_DIALECT

数据库类型，可选项包括：

• mariadb
• mysql
• postgres

DB_DIALECT=mysql

#DB_HOST

数据库主机（使用 MySQL 或 PostgreSQL 数据库时需要配置）

默认值 localhost

DB_HOST=localhost

#DB_PORT

数据库端口（使用 MySQL 或 PostgreSQL 数据库时需要配置）

• MySQL、MariaDB 默认端口 3306
• PostgreSQL 默认端口 5432

DB_PORT=3306

#DB_DATABASE

数据库名（使用 MySQL 或 PostgreSQL 数据库时需要配置）

DB_DATABASE=nocobase

#DB_USER

数据库用户（使用 MySQL 或 PostgreSQL 数据库时需要配置）

DB_USER=nocobase

#DB_PASSWORD

数据库密码（使用 MySQL 或 PostgreSQL 数据库时需要配置）

DB_PASSWORD=nocobase

#DB_TABLE_PREFIX

数据表前缀

DB_TABLE_PREFIX=nocobase_

#DB_UNDERSCORED

数据库表名、字段名是否转为 snake case 风格，默认为 false。如果使用 MySQL（MariaDB）数据库，并且 lower_case_table_names=1，则 DB_UNDERSCORED 必须为 true

#DB_LOGGING

数据库日志开关，默认值 off，可选项包括：

• on 打开
• off 关闭

DB_LOGGING=on

#DB_POOL_MAX

数据库连接池最大连接数，默认值 5。

#DB_POOL_MIN

数据库连接池最小连接数，默认值 0。

#DB_POOL_IDLE

数据库连接池空闲时间，默认值 10000（10 秒）。

#DB_POOL_ACQUIRE

数据库连接池获取连接最大等待时间，默认值 60000（60 秒）。

#DB_POOL_EVICT

数据库连接池连接最大存活时间，默认值 1000（1 秒）。

#DB_POOL_MAX_USES

连接在被丢弃并替换之前可被使用的次数，默认值 0（不限制）。

#LOGGER_TRANSPORT

日志输出方式，多个用 , 分隔。开发环境默认值 console, 生产环境默认值 console,dailyRotateFile. 可选项：

• console - console.log
• file - 文件
• dailyRotateFile - 按天滚动文件

LOGGER_TRANSPORT=console,dailyRotateFile

#LOGGER_LEVEL

输出日志级别，开发环境默认值 debug, 生产环境默认值 info. 可选项：

• error
• warn
• info
• debug
• trace

LOGGER_LEVEL=info

数据库日志输出级别为 debug, 由 DB_LOGGING 控制是否输出，不受 LOGGER_LEVEL 影响。

#LOGGER_MAX_FILES

最大保留日志文件数。

• LOGGER_TRANSPORT 为 file 时，默认值为 10.
• LOGGER_TRANSPORT 为 dailyRotateFile, 使用 [n]d 代表天数。默认值为 14d.

LOGGER_MAX_FILES=14d

#LOGGER_MAX_SIZE

按大小滚动日志。

• LOGGER_TRANSPORT 为 file 时，单位为 byte, 默认值为 20971520 (20 * 1024 * 1024).
• LOGGER_TRANSPORT 为 dailyRotateFile, 可以使用 [n]k, [n]m, [n]g. 默认不配置。

LOGGER_MAX_SIZE=20971520

#LOGGER_FORMAT

日志打印格式，开发环境默认 console, 生产环境默认 json. 可选项:

• console
• json
• logfmt
• delimiter

LOGGER_FORMAT=json

参考：日志格式

#CACHE_DEFAULT_STORE

使用缓存方式的唯一标识，指定服务端默认缓存方式，默认值 memory, 内置可选项：

• memory
• redis

CACHE_DEFAULT_STORE=memory

#CACHE_MEMORY_MAX

内存缓存项目最大个数，默认值 2000。

CACHE_MEMORY_MAX=2000

#CACHE_REDIS_URL

Redis连接，可选。示例：redis://localhost:6379

CACHE_REDIS_URL=redis://localhost:6379

#TELEMETRY_ENABLED

启动遥测数据收集，默认为 off.

TELEMETRY_ENABLED=on

#TELEMETRY_METRIC_READER

启用的监控指标采集器，默认为 console. 其他值需要参考对应采集器插件注册的名字，如 prometheus. 多个使用 , 分隔。

TELEMETRY_METRIC_READER=console,prometheus

#TELEMETRY_TRACE_PROCESSOR

启用的链路数据处理器，默认为 console. 其他值需要参考对应处理器插件注册的名字。多个使用 , 分隔。

TELEMETRY_TRACE_PROCESSOR=console

#WORKER_MODE

用于配置集群模式下进行服务拆分时，不同节点的工作模式，详情查看「服务拆分：如何拆分服务」。

#SERVER_REQUEST_WHITELIST

服务端对外发送 HTTP 请求的目标白名单，用于限制由 NocoBase 服务端主动发出的请求。逗号分隔，支持精确 IP、CIDR 范围、精确域名和通配符子域名（单级）。

SERVER_REQUEST_WHITELIST=api.example.com,*.trusted.com,10.0.0.0/8,127.0.0.1

适用范围：工作流「HTTP 请求」节点、自定义操作按钮的「自定义请求」、AI 服务等服务端请求。相对路径（调用 NocoBase 自身 API）不受此限制影响。

未配置时：所有 http / https 请求均放行（保持原有行为）。不过，如果目标是 loopback、内网、link-local、metadata 地址，或者域名解析到了这些地址，服务端日志会输出 warning。

配置后：初始请求和每个重定向目标都必须匹配白名单。不匹配时，会在发出下一跳请求前报错。后续版本可能会逐步收紧默认策略，如果你的部署需要访问内网服务，建议提前配置明确的白名单。

支持的格式：

#实验性环境变量

#APPEND_PRESET_LOCAL_PLUGINS

用于附加预置的未激活插件，值为插件包名（package.json 的 name 参数），多个插件英文逗号分隔。

APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar

#APPEND_PRESET_BUILT_IN_PLUGINS

用于附加内置并默认安装的插件，值为插件包名（package.json 的 name 参数），多个插件英文逗号分隔。

APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar

#临时环境变量

安装 NocoBase 时，可以通过设置临时的环境变量来辅助安装，如：

yarn cross-env \
  INIT_APP_LANG=zh-CN \
  INIT_ROOT_EMAIL=demo@nocobase.com \
  INIT_ROOT_PASSWORD=admin123 \
  INIT_ROOT_NICKNAME="Super Admin" \
  nocobase install

# 等同于
yarn nocobase install \
  --lang=zh-CN  \
  --root-email=demo@nocobase.com \
  --root-password=admin123 \
  --root-nickname="Super Admin"

# 等同于
yarn nocobase install -l zh-CN -e demo@nocobase.com -p admin123 -n "Super Admin"

#INIT_APP_LANG

安装时的语言，默认值 en-US，可选项包括：

• en-US
• zh-CN

yarn cross-env \
  INIT_APP_LANG=zh-CN \
  nocobase install

#INIT_ROOT_EMAIL

Root 用户邮箱

yarn cross-env \
  INIT_APP_LANG=zh-CN \
  INIT_ROOT_EMAIL=demo@nocobase.com \
  nocobase install

#INIT_ROOT_PASSWORD

Root 用户密码

yarn cross-env \
  INIT_APP_LANG=zh-CN \
  INIT_ROOT_EMAIL=demo@nocobase.com \
  INIT_ROOT_PASSWORD=admin123 \
  nocobase install

#INIT_ROOT_NICKNAME

Root 用户昵称

yarn cross-env \
  INIT_APP_LANG=zh-CN \
  INIT_ROOT_EMAIL=demo@nocobase.com \
  INIT_ROOT_PASSWORD=admin123 \
  INIT_ROOT_NICKNAME="Super Admin" \
  nocobase install

#其他插件提供的环境变量

#WORKFLOW_SCRIPT_MODULES

工作流 JavaScript 节点可用的模块列表，详情查看「JavaScript 节点：使用外部模块」。

#WORKFLOW_LOOP_LIMIT

工作流循环节点的最大循环次数限制，详情查看「循环节点」。