NocoBase 2.2.29 配置参数详解

目标：把 NocoBase 2.2.29 的配置体系一次讲清——参数在哪里看、怎么改、改了何时生效；全局/数据库/日志/缓存/遥测/安全六类环境变量逐项给出官方默认值与生产建议；并附一份按 8GB 内存中小规模场景调好的生产配置模板。参数默认值来源为官方文档「环境变量」（docs.nocobase.com，查询日期 2026-10-21），标注「实测」的条目均在 Ubuntu 22.04 + NocoBase 2.2.29 + PostgreSQL 16 实例上验证过；部署过程本身见 《NocoBase 2.2.29 Docker Compose 部署指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（x86_64）
• 实例版本：NocoBase 2.2.29（应用版本接口 /api/app:getInfo 实测返回 "version":"2.2.29"）
• 数据库：PostgreSQL 16
• 部署形态：官方 Docker Compose 方案（部署目录 /opt/nocobase，数据目录 storage/）
• 参数来源标注约定：官方文档「环境变量」页查询日期 2026-10-21；「实测」= 本文实例上执行命令取得的真实回显；「官方」= 官方文档转述（未单独实测）
• 本系列相关篇目：《NocoBase 介绍与选型指南》、《NocoBase 2.2.29 Docker Compose 部署指南》、《NocoBase 2.2.29 常用 CLI 命令与工具详解》

二、前置条件

1. 已按部署篇完成 NocoBase 2.2.29 安装并能正常访问（curl http://127.0.0.1:8140/api/app:getInfo 返回 200）；
2. 可在部署目录执行 docker compose 命令（修改参数的主要入口）；
3. 理解参数生效方式：NocoBase 的环境变量在服务启动时读取，改完必须重建 app 服务才生效（官方文档明确：Docker 方式修改后需执行 docker compose up -d app），业务数据不受重建影响。

三、参数查看与修改方式

3.1 查看当前生效参数

运行中的实例直接查进程环境（实测，部署目录 /opt/nocobase 下执行）：

docker compose exec -T app sh -c 'env | grep -E "^(APP_|DB_|TZ|LOGGER_|CACHE_)" | sort'

实测回显（与部署模板一致，未设置的变量不出现在输出中、走内置默认值）：

APP_KEY=-q2y7vtoxlu1jq0v5vi5jveudk3yogckm
DB_DATABASE=nocobase
DB_DIALECT=postgres
DB_HOST=postgres
DB_PASSWORD=nocobase
DB_PORT=5432
DB_USER=nocobase
TZ=Asia/Shanghai

版本与运行形态也可通过版本接口确认（实测）：

curl -s http://127.0.0.1:8140/api/app:getInfo

{"data":{"database":{"dialect":"postgres"},"version":"2.2.29","lang":"en-US","name":"main","theme":"default"}}

3.2 修改参数的两种入口

Docker 方式下官方支持两种写法（来源：官方文档「环境变量」页，2026-10-21）：

方式一：compose 文件内联（本文部署篇采用），在 app 服务的 environment: 段追加，如 LOGGER_LEVEL=debug；

方式二：env_file，compose 中改为引用独立文件，适合参数多或区分环境时使用：

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

.env 文件每行一个 KEY=VALUE。

修改后统一执行重建使参数生效：

docker compose up -d app

官方与实测口径一致：compose 检测到配置差异会自动重建 app 服务，数据目录（bind mount）不受影响，重建后用 3.1 的命令复核新值已出现即生效。

3.3 运行期自动生成的配置文件

应用数据目录下有一个自动生成的 storage/nocobase.conf（实测路径 /app/nocobase/storage/nocobase.conf，对应宿主 storage/nocobase.conf）——它不是传统意义上的应用参数表，而是内置 Nginx 的站点配置，承担对外 80 端口到后端 127.0.0.1:13000 的转发。摘录实测关键行：

server {
    listen 80;
    server_name _;
    root /app/nocobase/node_modules/@nocobase/app/dist/client;
    client_max_body_size 0;
    access_log /var/log/nginx/nocobase.log apm;
    # ……（中略：本节选仅保留与转发相关的关键行，全文见实例内文件）
    location ^~ /api/ {
        proxy_pass http://127.0.0.1:13000;
        # ……（中略：X-Forwarded 等代理头设置见实例内文件）
    }
    location /ws {
      proxy_pass http://127.0.0.1:13000/ws;
      # ……（中略：Upgrade 升级头设置见实例内文件）
    }
    location ^~ /files/ {
        proxy_pass http://127.0.0.1:13000;
        # ……（中略：X-Forwarded 等代理头设置见实例内文件）
    }
}

要点：前端静态资源由 Nginx 直接服务，/api/、/ws（WebSocket）、/files/（文件稳定地址）转发后端；client_max_body_size 0 不限制上传体积。该文件随版本发行内置，日常不需要手改；生产接入宿主 Nginx 反代时按官方文档「生产环境部署」把同名路径转发到应用 80/13000 端口即可。

3.4 界面内的运行时配置

页面布局、区块、角色权限等属于「配置即数据」范畴，保存即生效并入库，不占环境变量，随 storage/ 一并备份——本文只覆盖环境变量层。

四、参数总览

全部环境变量按域分组速览（默认值均为官方口径，2026-10-21 查询）：

💡 技术拓展：日志传输通道（transport）是 Node.js 应用常见的多通道输出设计——

通道	原理	取舍
console	直接打标准输出，由外部（compose logs 等）收集	简单，但重启即丢、无轮转
file	写单文件并按大小滚动	文件数固定，按时间清理不便
dailyRotateFile	按天切文件、按天数过期	生产首选，检索与清理按日期直观

NocoBase 生产默认同时启用 console,dailyRotateFile：标准输出交给平台日志体系，文件留本地按 14 天过期，两头兼顾。

五、核心参数分类详解

5.1 全局与环境参数

TZ（官方默认：操作系统时区）：影响所有与时间相关的处理，官方特别提示修改 TZ 可能影响数据库中已有日期值的解释。实测部署模板设为 Asia/Shanghai 后，应用日志时间戳为本地时间（实测回显见 5.3）。

APP_ENV（官方默认：development）：标识运行环境，联动日志三项默认值（LOGGER_TRANSPORT/LOGGER_LEVEL/LOGGER_FORMAT）。实测观察：本文实例 compose 未显式设置 APP_ENV，运行日志为 JSON 格式（与官方文档所述生产形态一致，实测回显见 5.3）；调试排查时可在 environment: 显式加 APP_ENV=development 观察人类可读日志。

APP_KEY（无默认，必填）：用户令牌等敏感数据的加密密钥。官方警告：修改后旧 token 全部失效。实测确认此行为与登录接口配合——换 APP_KEY 后已获取的 token 再调用认证接口即 401，重新登录恢复。生产要点：首次部署定值，之后不变；多实例共享数据库时必须同值。

APP_PORT（官方默认：13000）：后端监听端口。Docker 方式下内置 Nginx 监听 80 并转发到该端口（见 3.3），因此 compose 映射写 宿主端口:80，改 APP_PORT 只在后端与 Nginx 间生效，对外宿主端口由 compose ports: 决定。

API_BASE_PATH（官方默认：/api/）：API 前缀。反向代理按该前缀转发，无特殊需求不改。

API_BASE_URL（官方默认：空 = 与页面同源）：仅当前端与 API 不同源时需要配置为完整地址（如 https://api.example.com/api/）。官方跨源提示：不同源时必须把页面来源加入 CORS_ORIGIN_WHITELIST，否则浏览器忽略 Set-Cookie，登录 cookie 写不进去、文件访问 403；cookie 按 hostname 存储，完全不同域名时文件稳定地址仍会失败——官方推荐反代同源部署、留空本变量。

LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS（官方默认：false）：是否允许匿名访问历史本地文件地址 /storage/uploads/。默认只有登录用户可访问；旧集成依赖公开访问时才显式开 true（改后需重启）。官方提醒：仅影响历史地址，不影响 /files/ 的记录级权限，开启可能暴露已上传文件。

CORS_ORIGIN_WHITELIST（官方默认：空）：逗号分隔的跨源白名单。配置后白名单来源获得 Access-Control-Allow-Origin 与 Access-Control-Allow-Credentials: true 回显；登录接口会校验 Origin/Referer，白名单外的跨源登录请求被拒（403）。未配置时仅同源可信。

CLUSTER_MODE（官方默认：空，v1.6.0+）：多核集群模式，值透传给 PM2 的 -i 参数（max/-1/数字）。官方注意：需配合集群模式相关插件使用，否则功能可能异常——中小规模单实例足够，开集群前先读官方「集群模式」章节。

PLUGIN_PACKAGE_PREFIX（官方默认：@nocobase/plugin-,@nocobase/preset-）：插件包名前缀映射，二次开发自有插件时追加自有前缀（如 @my-nocobase-app/plugin-），日常运维不动。

5.2 数据库参数

连接三件套与类型：DB_DIALECT（postgres/mysql/mariadb）、DB_HOST（默认 localhost，compose 内写服务名 postgres）、DB_PORT（PostgreSQL 5432、MySQL/MariaDB 3306）、DB_DATABASE/DB_USER/DB_PASSWORD。三项必须与数据库服务侧初始化参数完全一致，不一致是最常见启动故障（排障见部署篇 FAQ）。

DB_TABLE_PREFIX（官方默认：空）：表名统一加前缀，多应用共用一个库时用于隔离命名空间；部署后变更会导致新旧表名并存，应一次定好。

DB_UNDERSCORED（官方默认：false）：表名/字段名是否转 snake_case。官方明确：MySQL（MariaDB）且 lower_case_table_names=1 时必须 true；启用后数据库实际名与界面所见不一致（界面 orderDetails 对应库内 order_details），排查 SQL 时要有此意识。PostgreSQL 部署保持默认 false。

DB_LOGGING（官方默认：off）：SQL 日志开关，on 后输出 debug 级 SQL 语句——官方注明它不受 LOGGER_LEVEL 影响，是独立的调试开关。排障慢查询时临时打开，平时关闭（量大时刷屏）。

连接池六参数（官方默认）：

默认 MAX=5, MIN=0 的组合意味着空闲 10 秒后连接全部归还数据库（实测佐证：实例静置时在数据库侧查询活动连接，仅剩运维自身会话）：

docker compose exec -T postgres psql -U nocobase -d nocobase -c "SELECT count(*) AS connections FROM pg_stat_activity WHERE datname='nocobase';"

实测回显（应用静置期）：

 connections 
-------------
           1
(1 row)

生产建议：DB_POOL_MAX 按并发与数据库 max_connections 预算上调（如 20–50），多实例部署时各实例池上限之和要小于数据库上限的 80%。

5.3 日志参数

四件套默认值随 APP_ENV 联动（官方口径）：LOGGER_TRANSPORT 开发 console / 生产 console,dailyRotateFile；LOGGER_LEVEL 开发 debug / 生产 info（可选项 error/warn/info/debug/trace）；LOGGER_FORMAT 开发 console / 生产 json（可选项 console/json/logfmt/delimiter）。

实测回显——生产形态 JSON 日志（docker compose logs --tail=12 app 节选）：

nocobase-v229-app  | {"level":"info","message":"write roles to ACL","extra":{"method":"writeRolesToACL"},"meta":{},"module":"acl",...,"timestamp":"2026-10-21 23:08:56"}
nocobase-v229-app  | {"level":"info","message":"app has been started","extra":{},"meta":{},"module":"application",...,"timestamp":"2026-10-21 23:08:57"}
nocobase-v229-app  | {"level":"info","message":"response /api/app:getInfo","method":"GET","path":"/api/app:getInfo","res":{"status":200},"action":{...},"status":200,"cost":14,...,"timestamp":"2026-10-21 23:08:58"}

JSON 格式每行含 level/message/module/reqId/timestamp 等字段，timestamp 为本地时间（TZ=Asia/Shanghai 实测生效），接入日志平台时按 JSON 解析即可。

LOGGER_MAX_FILES：file 通道默认 10 个；dailyRotateFile 通道用 [n]d 表示天数，默认 14d（保留 14 天）。 LOGGER_MAX_SIZE：file 通道按字节，默认 20971520（20MB）；dailyRotateFile 支持 [n]k/[n]m/[n]g 单位，默认不按大小切。

日志文件落盘位置（实测）：storage/logs/main/（宿主 storage/logs/main/），随数据目录一并备份。

5.4 缓存参数

CACHE_DEFAULT_STORE（官方默认：memory，可选 memory/redis）：默认进程内存缓存，单实例够用；多实例（CLUSTER_MODE）或需要跨实例共享会话态时切 redis 并配置 CACHE_REDIS_URL（如 redis://localhost:6379）。

CACHE_MEMORY_MAX（官方默认：2000）：内存缓存条目上限，超限按淘汰策略腾位；大列表高频访问场景可适度上调。

5.5 遥测与安全参数

TELEMETRY_ENABLED（官方默认：off）：遥测收集总开关，默认关闭。开启后由 TELEMETRY_METRIC_READER（默认 console，可加 prometheus 等按插件注册名，逗号分隔）决定指标出口，TELEMETRY_TRACE_PROCESSOR（默认 console）决定链路数据出口。接入 Prometheus 监控的路径：开启遥测 + TELEMETRY_METRIC_READER=prometheus + 安装对应采集插件。

SERVER_REQUEST_WHITELIST（官方默认：空 = 全放行）：服务端出站请求白名单，约束由 NocoBase 服务端主动发出的请求（工作流 HTTP 请求节点、自定义请求按钮、AI 服务等；调用自身 API 的相对路径不受限）。支持精确 IP（1.2.3.4）、CIDR（10.0.0.0/8、fc00::/7）、精确域名（api.example.com）、单级通配子域（*.example.com 不匹配 example.com 与多级 a.b.example.com）。官方两点注意：配置后初始请求与每个重定向目标都必须命中白名单；白名单为域名时以请求 URL 的 host 为准（即使解析到内网地址也视为允许）。未配置时访问 loopback/内网/链路本地/元数据地址会在日志输出 warning——公网可达实例建议尽早配置明确白名单，官方提示后续版本可能逐步收紧默认策略。

5.6 集群与实验性参数

WORKER_MODE：集群模式下按节点拆分服务角色（如应用节点与工作流执行节点分离），取值与组合见官方「服务拆分」章节；单实例不配置。

APPEND_PRESET_LOCAL_PLUGINS / APPEND_PRESET_BUILT_IN_PLUGINS（实验性）：分别用于把自有插件加入「预置未激活」与「内置默认安装」清单，值为插件包名逗号分隔；需插件已存在于 node_modules，且在执行 nocobase install 或 nocobase upgrade 后生效（实测命令与回显见 《NocoBase 2.2.29 常用 CLI 命令与工具详解》）。日常自托管部署用不到，二开分发场景才需要。

5.7 临时（安装期）参数

仅在执行安装命令时生效的四个变量：INIT_APP_LANG（默认 en-US，可 zh-CN）、INIT_ROOT_EMAIL、INIT_ROOT_PASSWORD、INIT_ROOT_NICKNAME。官方示例形态：

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

与命令行参数完全等价（--lang/--root-email/--root-password/--root-nickname，实测回显见 《NocoBase 2.2.29 常用 CLI 命令与工具详解》）。Docker 方式首次启动自动安装时未传这些变量，走官方默认初始账号 admin@nocobase.com / admin123——登录后立即改密即可，无需为此重建实例。

六、生产配置模板

适用基线：8GB 内存、4 核、NVMe SSD，50 人以下团队的中等业务负载，PostgreSQL 16 与应用同机 compose 部署（更大并发需叠加 CLUSTER_MODE 与独立数据库，另行评估）：

services:
  app:
    image: nocobase/nocobase:latest
    restart: always
    depends_on:
      - postgres
    environment:
      # 全局
      - APP_KEY=<openssl rand -base64 32 生成的随机串>
      - APP_ENV=production
      - TZ=Asia/Shanghai
      # 数据库
      - DB_DIALECT=postgres
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_DATABASE=nocobase
      - DB_USER=nocobase
      - DB_PASSWORD=<强密码>
      - DB_UNDERSCORED=false
      - DB_LOGGING=off
      - DB_POOL_MAX=20
      # 日志
      - LOGGER_LEVEL=info
      - LOGGER_TRANSPORT=console,dailyRotateFile
      - LOGGER_MAX_FILES=14d
      - LOGGER_FORMAT=json
      # 缓存
      - CACHE_DEFAULT_STORE=memory
      - CACHE_MEMORY_MAX=5000
      # 安全
      - SERVER_REQUEST_WHITELIST=api.example.com,10.0.0.0/8
    volumes:
      - ./storage:/app/nocobase/storage
    ports:
      - '13000:80'

逐项解读：APP_ENV=production 锁定生产形态（JSON 日志、info 级别）；DB_POOL_MAX=20 在默认 5 的基础上按中小负载上调，为工作流高峰预留；日志按天轮转保留 14 天；CACHE_MEMORY_MAX=5000 适度上调内存缓存；SERVER_REQUEST_WHITELIST 限定服务端出站目标为业务依赖域名与内网段。APP_KEY 与数据库密码落实际生成值，不入版本库（用 env_file 分离时同样把 .env 排除在备份分发之外）。

七、常见问题（FAQ）

Q1：改了环境变量不生效？ 三类常见原因：① 未执行重建——官方明确 Docker 方式改完要 docker compose up -d app；② 改在数据库服务而非 app 服务上；③ 变量名拼写错误（env | grep 复核，见 3.1）。重建后用 3.1 命令确认新值出现即为生效。

Q2：修改 TZ 后历史数据时间不对了？ 官方警告的直接后果：已有日期值按旧时区解释写入，换时区后读取解释随之变化。正确做法是部署初期一次定好；确需变更时先评估含日期字段的业务数据，必要时在界面层做字段时区配置迁移。

Q3：APP_KEY 能定期轮换吗？ 不建议。轮换等于强制全员重新登录（旧 token 全失效），且与 APP_KEY 挂钩的本地加密数据需要评估兼容性。把 APP_KEY 视同数据库口令级别的一次性定值，通过备份与访问控制保护，而不是轮换。

Q4：日志里大量 [Workflow pre-action]: collection "app" not found warning？ 实测在 GET /api/app:getInfo 请求日志旁出现（见 5.3 实测回显后紧跟的 warn 行）——版本接口触发的预动作检查提示，不影响接口正常返回 200，属无害噪音，可忽略。

Q5：MySQL 部署要不要设 DB_UNDERSCORED？ 官方规则：MySQL/MariaDB 且 lower_case_table_names=1 时必须 true。判断方法：数据库执行 SHOW VARIABLES LIKE 'lower_case_table_names'; 值为 1 则设 true。这是安装期决定项，装完再改会造成表名混乱。

八、参考链接

• 官方环境变量文档（本文默认值来源，查询日期 2026-10-21）：https://docs.nocobase.com/get-started/installation/env
• 官方生产部署文档：https://docs.nocobase.com/get-started/deployment/production
• 本系列相关篇目：《NocoBase 介绍与选型指南》、《NocoBase 2.2.29 Docker Compose 部署指南》、《NocoBase 2.2.29 常用 CLI 命令与工具详解》