設定リファレンス

設定は、アプリと組み込まれたモジュールが一緒に定義します。このページは既定のテンプレートのよく使うフィールドの索引です。インストールされたアプリのメタデータの全体は、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

データベースとキーの設定は保ってください。LAN からのアクセスを許可するには、必要に応じて 0.0.0.0 にバインドし、ブラウザーではマシンの実際の IP を使います。0.0.0.0 はブラウザーのアドレスではありません。開発では別のフロントエンドのポートを使うことがあります。pnpm dev が表示する URL に従ってください。

データベースの設定

接続は database.connections.<name> に置き、database.default が既定を選びます。SQLite は filename を使います。ほかのダイアレクトでは一般に host、port、database、username、password を使います。ダイアレクト固有のフィールドについては データベースの対応状況とバージョンの互換性 を参照してください。

schemaManagement: managed はフレームワークによるスキーマの管理を許可します。external は外部のデータベースに対するフレームワークのスキーマの変更を制限しますが、業務データを自動で読み取り専用にするわけではありません。アカウントの権限と認可のポリシーは引き続き適用されます。

SQLite は、テンプレートの database というファイル名の書き方も受け付け、filename と両方ある場合はそちらが優先されます。古い database の値が DB_FILENAME を上書きしないよう、ファイルの場所を変えるときは 1 つの書き方に統一してください。

既定の DB_* の対応付けは main だけを対象にします。追加の接続の対応付けは、既定の接続の対応付けを残したまま、@nocobase/app-server/database の connectionEnvironment(name, prefix) で宣言します。ダイアレクトやアドレスを変えても、既存のデータは移行されません。

環境変数

以下の対応付けは、確認したアプリのメタデータから来ています。認証、メール、通知の対応付けはそれぞれのモジュールに依存します。正確な型、説明、機密のフィールドの印は、現在のコマンドの出力を参照してください。

さらに 3 つの変数をランタイムが読み取ります。

SECRETS_KEYS には、現在のキーを先頭にして、カンマで区切った version:key のエントリーを入れます。古いデータの復号に引き続き必要なエントリーは残し、ローテーションの手順に従ってください。キーを変えると、既存のセッションが無効になることもあります。各モジュールは、それぞれのルールに従って、明示的なキーか導出したキーを選びます。たとえばセッションは明示的な session.secret を優先し、ない場合は Secrets からの導出を試みます。これらの値を変える前に、モジュールの設定の取り決めとキーのローテーションの要件を確認してください。

ブラウザーから見える設定

client セクションはアプリのページに埋め込まれ、ブラウザーから読み取れます。ほかのサーバーのセクションが公開するのは、defineAppConfig() の public オプションに明示的に列挙した末端のパスだけです。データベースのパスワード、署名のキー、メールの認証情報は、client や公開のパスに入れないでください。

announcements のセクションには、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 を使いました。追加のプラグインによって、さらにセクションと対応付けが加わることがあります。