• Русский

      • Конфигурация приложения и .env

      Эта страница относится только к приложениям, созданным или размещенным через NocoBase CLI.

      Если вы только что прочитали Установка с помощью CLI (рекомендуется) и просмотрели раздел «Каталог установки», то наиболее распространенные проблемы, с которыми вы столкнетесь, обычно следующие:

      • Где находится файл .env?
      • Какие конфигурации еще подходят для записи в .env
      • Какие конфигурации сейчас больше подходят для передачи nb env update

      Сначала поговорим о выводах:

      • Для приложений, установленных через интерфейс командной строки, .env по умолчанию помещается в <app-path>/.env.
      • Этот файл не является обязательным, не каждый env необходимо создавать вручную. – Базовые конфигурации, такие как APP_KEY, TZ, APP_PORT, APP_PUBLIC_PATH и DB_*, по умолчанию управляются nb env update.
      • .env в основном используется для дополнения переменных времени выполнения, которые CLI не использует напрямую, таких как хранилище, кеш, журналы, наблюдения и некоторые переменные расширения подключаемого модуля.

      Сначала найдите app-path

      В [Установить с помощью CLI (рекомендуется)](./cli.md#Installation Directory) структура каталогов по умолчанию для CLI env выглядит следующим образом:

      <app-path>/
├── source/
├── storage/
└── .env

      Если вы не уверены, где находится текущий применяемый app-path, вы можете проверить напрямую:

      nb env info app1 --field app.appPath

      Просто замените app1 на свое имя окружения.

      То есть для приложения, созданного или размещенного через CLI, наиболее подходящим расположением файла .env является:

      <app-path>/.env

      Вообще говоря, нет необходимости ставить его в source/.env, и нет необходимости находить .env в корневом каталоге проекта Docker Compose по старому методу установки.

      Когда вам нужно создать .env самостоятельно?

      .env не является обязательным.

      Если вы просто хотите сначала запустить приложение или просто изменить базовые конфигурации, такие как порты, часовые пояса, подключения к базе данных и пути общего доступа, то во многих случаях нет необходимости создавать .env вручную.

      Добавляйте их в <app-path>/.env только в том случае, если вам нужно добавить некоторые переменные времени выполнения, которые CLI не использует напрямую.

      По умолчанию сначала используется nb env update

      В новом методе установки CLI рекомендуется по умолчанию отдавать приоритет базовой конфигурации приложения nb env update.

      Это имеет два преимущества:

      • Конфигурация и сама среда сохраняются в одном интерфейсе командной строки, что упрощает проверку и изменение.
      • В будущем вы, скрипты и ИИ-агенты можете продолжать использовать один и тот же набор команд для обслуживания, поэтому не так-то просто получить ситуацию «в файл вносится один набор изменений, а в CLI записывается другой набор».

      Эти конфигурации теперь более подходят для передачи nb env update

      Следующие элементы, возможно, раньше записывались непосредственно в .env. Однако в режиме установки CLI рекомендуется использовать nb env update по умолчанию:

      Я хочу измениться...Как изменить значение по умолчанию
      APP_KEYnb env update <name> --app-key <value>
      TZnb env update <name> --timezone <value>
      APP_PORTnb env update <name> --app-port <value>
      APP_PUBLIC_PATHnb env update <name> --app-public-path <value>
      CDN_BASE_URLnb env update <name> --cdn-base-url <value>
      Тип базы данных и параметры подключения, например DB_DIALECT, DB_HOST, DB_PORT, DB_DATABASE, DB_USER, DB_PASSWORDnb env update <name> --db-dialect ... --db-host ... --db-port ... --db-database ... --db-user ... --db-password ...
      Схема PostgreSQL, префикс таблицы, подчеркивание в именах таких дополнительных элементов базы данных, например DB_SCHEMA, DB_TABLE_PREFIX, DB_UNDERSCOREDnb env update <name> --db-schema ... --db-table-prefix ... --db-underscored

      Например, если вы хотите изменить порт приложения и часовой пояс, вы можете написать прямо так:

      nb env update app1 --app-port 13080 --timezone Asia/Shanghai

      Если вы хотите изменить параметры подключения к базе данных, вы можете написать так:

      nb env update app1 \
  --db-dialect postgres \
  --db-host 127.0.0.1 \
  --db-port 5432 \
  --db-database nocobase \
  --db-user nocobase \
  --db-password nocobase

      После внесения изменений CLI обычно предложит вам выполнить nb app restart позже. Более полное описание параметров см. в nb env update.

      Какие ситуации лучше записать в .env

      Если у переменной еще нет соответствующего параметра CLI или она больше похожа на расширенную конфигурацию, «передаваемую непосредственно в среду выполнения приложения», то просто продолжайте писать <app-path>/.env.

      Обычно включают в себя следующие категории:

      – Конфигурации хранилища файлов и объектов, например LOCAL_STORAGE_*, AWS_S3_*, ALI_OSS_*, TX_COS_*.

      • Конфигурация кэша и Redis, например CACHE_*, REDIS_URL.
      • Конфигурации журнала и наблюдения, такие как LOGGER_*, TELEMETRY_*.
      • Определенные переменные, специфичные для подключаемого модуля или расширения, такие как экспорт, асинхронные задачи, рабочий процесс и переменные, связанные с расширением AI.

      например:

      LOCAL_STORAGE_DEST=storage/uploads
AWS_S3_BUCKET=your-bucket
AWS_S3_REGION=ap-southeast-1
LOGGER_LEVEL=info
REDIS_URL=redis://127.0.0.1:6379

      Этот тип переменной по существу представляет собой конфигурацию времени выполнения приложения, и CLI в настоящее время не обрабатывает ее поэлементно. Наиболее естественно разместить его в .env.

      Как разделить работу между .env и nb env update

      Если вы не уверены, куда должна идти определенная конфигурация, просто следуйте этому правилу по умолчанию:

      • Если у nb env update уже есть соответствующий параметр, по умолчанию он будет использоваться первым.
      • Если соответствующий параметр отсутствует или он явно принадлежит конфигурации расширений среды выполнения, например подключаемым модулям, хранилищу, кешу и журналам, поместите его в <app-path>/.env.

      В большинстве сценариев такого разделения труда достаточно.

      Распространенное недоразумение

      Не храните одновременно две копии одной и той же конфигурации.

      Например, если вы сохранили базовые элементы, такие как APP_PORT, TZ, APP_PUBLIC_PATH и DB_HOST, с помощью nb env update, вам обычно не нужно записывать их снова в .env. В противном случае при последующем устранении неполадок можно будет легко не определить, какой уровень является тем значением, которое вы действительно хотите применить.

      Минимальный пример .env

      Если ваша базовая конфигурация была сохранена через CLI, то .env, вероятно, нужно сохранить только несколько переменных расширения, таких как:

      LOGGER_LEVEL=info
REDIS_URL=redis://127.0.0.1:6379
AWS_S3_BUCKET=your-bucket
AWS_S3_REGION=ap-southeast-1

      Это также менталитет, который эта страница больше всего хочет помочь вам создать:

      .env по-прежнему полезен, но в новом методе установки CLI речь идет скорее о дополнении конфигурации расширения среды выполнения, а не о продолжении принятия всех основных параметров установки.

      Куда смотреть дальше

      • Если вы не подтвердили структуру каталога приложения, сначала вернитесь к [Установить с помощью CLI (рекомендуется)](./cli.md#Каталог установки)
      • Если вы хотите изменить базовые конфигурации, такие как порты, часовые пояса, подключения к базе данных и пути общего доступа, продолжайте просматривать nb env update.
      • Если вы хотите запустить, перезапустить или просмотреть журналы приложения, перейдите к разделу Управление приложением.