配置项参考

配置由应用及已接入模块共同定义。本页列出默认模板中的常用字段；已安装应用的完整配置元数据通过 pnpm nocobase config variables --json 查询。配置开发流程见应用配置（config.yml）。

文件与覆盖顺序

默认模板按以下顺序合并，后者覆盖前者：

server/config/ 中的代码默认值
    → config.yml
    → 已声明映射的环境变量

普通对象递归合并；数组和标量整体替换。环境变量需要显式声明映射，不会按名称任意转换成配置路径。YAML 中的 ${NAME} 是普通字符串，不会自动插值。

在未初始化的应用中运行 pnpm nocobase config init --dialect sqlite。该命令根据示例生成本地配置和密钥；已有应用应保留原密钥，不通过重新初始化来完成升级。

常用配置项

这是配置位置索引，不是可以原样复制的完整配置。缺省值、支持字段和插件分区以当前模板与包声明为准。

例如，已经初始化的本地开发应用可以在原配置中合并以下值：

server:
  host: 127.0.0.1
  port: 13000

client:
  app:
    title: My App
    defaultColorScheme: system

保留原文件中的数据库和密钥配置。局域网访问时，按需将监听地址改为 0.0.0.0，并在浏览器使用机器的实际 IP；0.0.0.0 本身不是浏览器访问地址。开发服务可能还包含独立的前端端口，以 pnpm dev 打印的地址为准。

数据库配置

连接位于 database.connections.<name>，database.default 指定默认连接。SQLite 使用 filename，其他方言通常使用 host、port、database、username 和 password，特殊字段见数据库支持与版本兼容。

schemaManagement: managed 表示框架可管理结构。external 用于外部数据库，限制框架的结构变更，不代表业务数据自动只读；仍需配置账号权限和授权策略。

SQLite 配置还兼容模板中的 database 文件名写法；同时存在时 database 优先于 filename。调整文件位置时统一使用一种写法，避免 DB_FILENAME 被文件中的旧 database 值覆盖。

默认 DB_* 环境变量只映射 main。额外连接需要自己声明映射；可使用 @nocobase/app-server/database 的 connectionEnvironment(name, prefix)，并保留原有默认连接映射。为连接修改方言或地址不会自动迁移原数据库内容。

环境变量

下表来自已核对应用的配置清单。认证、邮件、通知等映射依赖对应模块；精确类型、说明和敏感标记以当前应用命令输出为准。

另外三个变量由运行时读取：

SECRETS_KEYS 使用 版本:密钥 条目，以逗号分隔，第一项为当前密钥。新增密钥时保留仍用于解密旧数据的条目，并按密钥轮换流程处理数据；密钥变化也可能使已有登录会话失效。各模块按自身规则选择显式密钥或主密钥派生值：例如会话优先使用显式 session.secret，未设置时才尝试从 Secrets 派生。配置变更前核对所用模块的配置契约和密钥轮换要求。

浏览器可见配置

client 分区会写入应用页面，浏览器可以读取。其他服务端分区只通过 defineAppConfig() 的 public 叶子路径明确公开。数据库密码、签名密钥、邮件凭证等不能放入 client 或公开路径。

增加一个公告配置分区，例如 server/config/announcements.ts：

import { defineAppConfig, envInteger } from '@nocobase/app-server/config';

export default defineAppConfig({
  defaults: { pageSize: 20 },
  env: {
    ANNOUNCEMENTS_PAGE_SIZE: envInteger('pageSize', {
      description: 'Default number of announcements per page.',
    }),
  },
  public: ['pageSize'],
  validate(value, context) {
    if (!Number.isInteger(value.pageSize) || value.pageSize < 1 || value.pageSize > 100) {
      context.error('pageSize', 'Expected an integer between 1 and 100.');
    }
  },
});

在 server/config/index.ts 的现有 defaultAppConfigs({ ... }) 中导入并加入 announcements，同时更新该文件显式列出的返回类型。对应文件配置为 announcements.pageSize，环境变量为 ANNOUNCEMENTS_PAGE_SIZE。public: ['pageSize'] 仅公开这个字段。

校验函数在启动、重新加载和 config check 时运行，应检查实际值，避免在其中发起网络请求或写入数据。重新加载配置也不保证已经创建的服务自动切换行为，需要服务自身处理更新。

修改与检查

pnpm nocobase config set server.port=13000
pnpm nocobase config env
pnpm nocobase config variables --json
pnpm nocobase config check --no-connect

从现有环境变量读取敏感值并写入本地配置：

pnpm nocobase config set --from-env database.connections.main.password=MAIN_DB_PASSWORD

先通过自己的环境管理方式设置 MAIN_DB_PASSWORD。该命令把其当前值写入配置文件，不保存一个动态变量引用。设置以后若仍有 DB_PASSWORD，后者会覆盖文件值。

config check 默认检查配置并尝试非 SQLite 连接；--no-connect 适合离线检查，--strict 将警告视为失败。不要在问题反馈中直接贴出整个配置文件；提供字段名、脱敏后的错误和包版本即可。命令行为见命令行参考。

核对范围

定义机制按 Core 015404ecd0db 的配置源码核对；配置清单与离线检查在默认模板 beta.83、@nocobase/app-cli 1.0.0-beta.29、@nocobase/config 0.1.0-beta.3 下执行。安装其他插件后可能出现更多分区和映射。