#nb init

Инициализирует текущее рабочее пространство, чтобы агент для разработки мог подключаться к NocoBase и использовать его.

nb init может установить новое локальное приложение NocoBase, а также сохранить параметры подключения уже существующего приложения.

Кроме того, nb init по умолчанию синхронизирует навыки ИИ-разработки NocoBase. Добавлять --skip-skills нужно только если вы уже самостоятельно управляете навыками либо запускаете команду в CI или офлайн-среде.

#Использование

nb init [flags]

#Интерактивные режимы

nb init поддерживает три интерактивных режима:

• nb init：пошаговое выполнение настройки в терминале
• nb init --ui：открывает форму в локальном браузере и завершает настройку через визуальный мастер
• nb init --yes --env app1：пропускает запросы и сразу использует флаги; параметры, не переданные явно, обрабатываются со значениями по умолчанию

Режим --yes подходит для скриптов, CI/CD и других неинтерактивных сценариев. В этом режиме --env <envName> обязателен. Как правило, по умолчанию будет установлено новое локальное приложение; если вы не укажете --source, источником установки по умолчанию будет docker.

#Возобновление прерванной инициализации

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

nb init --env app1 --resume

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

#Сначала подготовить окружение, а приложение установить позже

--prepare-only предназначен для сценариев, где сначала нужно подготовить окружение, затем активировать лицензию, и только после этого установить и запустить приложение.

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

nb init --env app1 --prepare-only
nb init --env app1 --prepare-only --ui
nb init --env app1 --prepare-only --yes

Этот режим доступен для сценариев локальной установки, включая мастер --ui. Он недоступен для сценариев удалённого подключения. CLI сохранит окружение как подготовленное, поэтому позже вы сможете продолжить с помощью такого сценария:

nb license activate --env app1
nb app start --env app1

После этого nb app start завершит первую установку и переведёт окружение из подготовленного состояния в обычное установленное состояние.

#Структура каталога установки

Полный путь можно посмотреть через nb env info app1 --field app.appPath.

По умолчанию CLI организует локальные файлы в app-path по следующему соглашению:

<app-path>/
├── .nb/      # Метаданные CLI для этого окружения, например hooks.mjs
├── source/   # Каталог по умолчанию для исходного кода приложения или загруженного содержимого
├── storage/  # Каталог данных среды выполнения
└── .env      # Необязательный файл переменных окружения приложения

Обычно:

• .nb/ хранит метаданные, управляемые CLI. Скрипт, переданный через --hook-script, копируется в <app-path>/.nb/hooks.mjs, чтобы последующие nb app upgrade и локальное восстановление исходного кода могли использовать его повторно
• source/ в основном соответствует локальному каталогу приложения для окружений типов npm / Git. Для Docker-окружений CLI тоже сохраняет эту схему путей по умолчанию, но в большинстве случаев вам не нужно заботиться об этом вручную. При обновлении обратите особое внимание: каталог source/ будет удалён и загружен заново, поэтому не храните здесь файлы, которые нужно сохранить
• storage/ используется для данных среды выполнения, например встроенной базы данных, плагинов, логов и т. д.
• .env — необязательный файл переменных окружения приложения. Добавлять его в <app-path>/.env нужно только если вы хотите настроить свои переменные окружения; если файл существует, источники установки Docker, npm и Git по умолчанию будут его читать

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

#Примечания

#Быстрая навигация по Steps

В разных путях настройки отображаются разные шаги. Например, при подключении к существующему приложению обычно используются только «Начало настройки» и «Удалённое подключение».

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

#Параметры

Параметров довольно много, поэтому понятнее рассматривать их по сценариям использования.

Под “значением по умолчанию” ниже имеется в виду значение или поведение, которое nb init обычно использует, если параметр опущен.

#Базовые и интерактивные

#Подключение существующего приложения

#Базовые параметры локальной установки

#Параметры базы данных

#Параметры загрузки и исходного кода

#Примеры

Ниже приведены несколько самых распространённых вариантов использования.

#Пошаговое выполнение мастера в терминале

nb init

#Открытие мастера в локальном браузере

nb init --ui
nb init --ui --ui-port 3000

#Сначала подготовить, затем активировать лицензию и запустить позже

nb init --env app1 --prepare-only
nb license activate --env app1
nb app start --env app1

#Неинтерактивная установка нового локального приложения

Если не указывать --source, обычно в качестве источника установки используется Docker.

nb init --env app1 --yes
nb init --env app1 --yes --source docker --version latest
nb init --env app1 --yes --source docker --version beta
nb init --env app1 --yes --source docker --version alpha
nb init --env app1 --yes --source docker --version main \
  --docker-registry registry.cn-beijing.aliyuncs.com/nocobase/nocobase
nb init --env app1 --yes --source npm --version latest
nb init --env app1 --yes --source npm --version beta
nb init --env app1 --yes --source npm --version alpha
nb init --env app1 --yes --source npm --version beta --app-port 13080
nb init --env app1 --yes --source git --version latest
nb init --env app1 --yes --source git --version beta
nb init --env app1 --yes --source git --version alpha
nb init --env app1 --yes --source git --version feat/plugin-workflow-timeout
nb init --env app1 --yes --source git --version latest \
  --git-url https://gitee.com/nocobase/nocobase.git

#Расширение процесса установки с помощью модуля хука

Если во время установки нужно подготовить дополнительные файлы, передайте локальный ESM-модуль через --hook-script:

nb init --env app1 --yes --source git --hook-script ./hooks.mjs

CLI копирует этот файл в <app-path>/.nb/hooks.mjs и сохраняет hookScript: ".nb/hooks.mjs" в конфигурации окружения. Последующие nb app start, nb app restart и nb app upgrade используют его из этого места.

Файл хука должен экспортировать объект по умолчанию. Реализуйте только нужные методы:

export default {
  beforeDependencyInstall: async (context) => {
    // Выполняется после git clone / npm-шаблона и перед yarn install.
  },
  beforeAppInstall: async (context) => {
    // Выполняется перед командой установки или обновления на уровне приложения.
  },
  afterAppStart: async (context) => {
    // Выполняется после фактического запуска приложения и успешной проверки работоспособности.
  },
};

• beforeDependencyInstall применяется только к источникам npm/Git и запускается прямо перед настоящим yarn install; источник Docker его не запускает
• beforeAppInstall запускается перед командами установки или обновления на уровне приложения и применяется к источникам npm/Git/Docker
• afterAppStart запускается после фактического старта приложения и успешного __health_check; его могут вызвать nb app start, nb app restart и nb app upgrade

--prepare-only только сохраняет конфигурацию окружения и копирует файл хука. Хуки при этом не выполняются. Когда позже вы впервые запустите nb app start, CLI выполнит хуки первой установки с context.phase равным init и context.command равным app:start.

context содержит сведения о жизненном цикле, например phase, command, source, version, appPath, sourcePath, storagePath, hookScript и envConfig. Если хук выбросит ошибку, текущая CLI-команда завершится с ошибкой. Так как afterAppStart может выполняться повторно при start, restart и upgrade, сделайте его идемпотентным.

#Быстрая установка и использование аутентификации basic

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

Если использовать стандартную учётную запись администратора из режима --yes, самый короткий вариант такой.

Если не указано, имя администратора по умолчанию — nocobase, а пароль по умолчанию — admin123:

nb init --env app1 --yes --auth-type basic

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

nb init --env app1 --yes \
  --auth-type basic \
  --root-username admin \
  --root-password secret123

#Подключение существующего приложения

Обычно достаточно OAuth по умолчанию. Если в некоторых сценариях CI/CD неудобно открывать браузер, можно сразу сохранить аутентификацию basic; если у вас уже есть токен API, можно сразу сохранить аутентификацию token.

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api \
  --auth-type basic \
  --username <username> \
  --password <password>

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api \
  --auth-type token \
  --access-token <token>

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api \
  --auth-type oauth \
  --skip-auth

#Настройка именования базы данных

Если вам нужно указать schema PostgreSQL, префикс таблиц или стиль именования с подчёркиваниями, можно передать параметры так:

nb init --env app1 --yes \
  --db-dialect postgres \
  --db-schema public \
  --db-table-prefix nb_ \
  --db-underscored

#Продолжение предыдущей прерванной инициализации

nb init --env app1 --resume

#Подробные логи для устранения неполадок

nb init --env app1 --yes --source docker --version latest --verbose

#Связанные команды

• nb env add
• nb env auth
• nb source download