opensource/nocobase
3
0
Fork 0
mirror of https://github.com/nocobase/nocobase.git synced 2026-09-01 14:57:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: remove Russian CLI migration guide

Browse Source
This commit is contained in:
chenos
2026-07-03 15:41:40 +08:00
parent b66925820d
commit 0926ea5a38
1 changed files with 0 additions and 407 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs/ru/ai/install-upgrade-migration.mdx
-407
View File
@@ -1,407 +0,0 @@
---
title: "Руководство по установке, обновлению и миграции с использованием NocoBase CLI"
description: "Переход со старых способов установки и обновления (Docker, create-nocobase-app, Git) на новый рабочий процесс через NocoBase CLI."
keywords: "NocoBase CLI,миграция установки,миграция обновления,nb init,nb app upgrade,Docker,create-nocobase-app,исходный код Git"
---
# Руководство по установке, обновлению и миграции с использованием NocoBase CLI
:::danger
Возможности CLI по установке и сопровождению приложений всё ещё находятся в активной разработке. На текущий момент они больше подходят для локальной разработки, тестовых окружений и сценариев подключения AI Agent. Не рекомендуется использовать их напрямую для установки, обновления и эксплуатации в продуктивных средах.
:::
Новый NocoBase CLI (`nb`) объединяет установку, подключение, запуск, остановку, просмотр логов, обновление и очистку в единый набор команд. По сравнению со старой документацией, где для Docker, create-nocobase-app и установки из исходников Git поддерживались отдельные процессы, CLI лучше подходит для локальной разработки, сопровождения тестовых окружений, а также для подключения и совместной работы с AI Agent.
Эта статья применима к следующим сценариям:
- Вы устанавливаете или обновляете NocoBase по старой документации и хотите перейти на новый способ через CLI.
- У Вас уже есть NocoBase, развёрнутый старым способом, и Вы хотите, чтобы CLI управлял им или подключался к нему.
- Вам нужно подготовить для AI Agent окружение NocoBase, к которому можно подключаться и которое можно сопровождать.
## Различия между старым и новым способами
Старый способ разделял документацию по источнику установки — для каждого источника требовалось отдельно выполнять команды загрузки, настройки, установки, запуска и обновления.
**Старая документация по установке**
- [Установка через Docker](/get-started/installation/docker)
- [Установка через create-nocobase-app](/get-started/installation/create-nocobase-app)
- [Установка из исходного кода Git](/get-started/installation/git)
**Старая документация по обновлению**
- [Обновление установки через Docker](/get-started/upgrading/docker)
- [Обновление установки через create-nocobase-app](/get-started/upgrading/create-nocobase-app)
- [Обновление установки из исходного кода Git](/get-started/upgrading/git)
Новый способ имеет единую точку входа — `nb init`, и использует один env CLI для записи источника приложения, рабочего каталога, каталога хранения, настроек базы данных и параметров подключения к API. После этого, независимо от того, используется Docker, npm или Git как источник, по возможности применяется единый набор команд `nb app`, `nb source`, `nb db`.
| Сценарий | Старый способ | Новый способ через CLI |
| --- | --- | --- |
| Точка входа установки | `docker compose`, `create-nocobase-app`, `git clone` | `nb init` или `nb init --ui` |
| Управление приложением | переход в каталог, правка compose, выполнение yarn/pm2 | `nb app start/stop/restart/logs/down` |
| Обновление | свой набор команд для каждого способа установки | `nb app upgrade -e <env>` |
| Режим разработки | `yarn dev` | `nb source dev -e <env>` |
| Состояние БД | вручную смотреть контейнер или сервис БД | `nb db ps -e <env>` |
| Просмотр статуса и деталей окружения | вручную записывать пути, порты и адреса | `nb env list`, `nb env info <env>` |
| Подключение к существующему приложению | в старой документации единого подхода не было | `nb init --ui` или `nb init --api-base-url` |
## Установка CLI
```bash
npm install -g @nocobase/cli@beta
nb --version
```
После установки можно посмотреть справку:
```bash
nb --help
nb init --help
```
## Установка NocoBase новым способом
### Рекомендуется: визуальный мастер
```bash
nb init --ui
```
Мастер проведёт Вас по следующим шагам:
- Создать новое приложение или подключить существующее
- Выбрать источник установки: Docker, npm, Git
- Выбрать версию NocoBase
- Использовать встроенную базу данных или внешнюю
- Создать учётную запись и пароль администратора
### Терминальный интерактивный мастер
```bash
nb init
```
### Неинтерактивные команды
По умолчанию используется установка через Docker и встроенный PostgreSQL:
```bash
nb init --yes --env app1
```
Установка указанной версии через Docker:
```bash
nb init --yes --env app1 --source docker --version beta
```
Установка через npm:
```bash
nb init --yes --env app1 --source npm --version beta --app-port 13080
```
Установка из исходного кода Git:
```bash
nb init --yes --env app1 --source git --version beta
```
Установка из исходного кода Git с указанием типа встроенной базы данных:
```bash
nb init --yes --env app1 --source git --version beta --db-dialect mysql
```
Подключение к существующему приложению NocoBase:
```bash
# По умолчанию используется аутентификация OAuth
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api
# Аутентификация по token
nb init --yes --env app1 \
--api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
--auth-type=token \
--access-token=<token>
```
:::tip
`--env` — это имя окружения в CLI. Все последующие команды запуска, обновления, просмотра логов и т. д. могут использовать его через `-e app1`.
:::
## Обновление новым способом
В старом подходе команды обновления для Docker, create-nocobase-app и Git исходников отличаются. В новом CLI они объединены:
```bash
nb app upgrade -e app1
```
Если Вы хотите выполнить обновление, используя уже загруженный исходный код или образ, без подтягивания новой версии:
```bash
nb app upgrade -e app1 --skip-code-update
```
Или сокращённый вариант:
```bash
nb app upgrade -e app1 -s
```
## Часто используемые команды сопровождения
| Действие | Команда |
| --- | --- |
| Запустить приложение | `nb app start -e app1` |
| Остановить приложение | `nb app stop -e app1` |
| Перезапустить приложение | `nb app restart -e app1` |
| Просмотреть логи | `nb app logs -e app1` |
| Посмотреть env и статус аутентификации API | `nb env list` |
| Посмотреть детали env | `nb env info app1` |
| Посмотреть статус встроенной БД | `nb db ps -e app1` |
| Обновить приложение | `nb app upgrade -e app1` |
| Остановить и очистить ресурсы | `nb app down -e app1` |
`nb app down` по умолчанию останавливает приложение и удаляет контейнеры, управляемые CLI, а также локальные файлы приложения, но сохраняет данные `storage` и конфигурацию env. Удалить всё содержимое можно только с явным подтверждением:
```bash
nb app down -e app1 --all --yes
```
:::warning
`--all --yes` удалит данные `storage` и конфигурацию env CLI для этого окружения. Используйте только после того, как убедитесь, что у Вас есть резервная копия и окружение больше не нужно.
:::
## Команды для повседневной разработки
`nb source` управляет локальным проектом исходников и применяется в основном для env с источниками npm и Git.
| Действие | Команда |
| --- | --- |
| Запуск приложения в режиме разработки | `nb source dev -e app1` |
| Сборка исходников | `nb source build --cwd /your/workspace/app1/source` |
| Запуск тестов | `nb source test --cwd /your/workspace/app1/source` |
| Загрузка или обновление исходников/образа | `nb source download --source git --version beta` |
:::tip
Для Docker-окружения обычно используются `nb app start`, `nb app logs` и `nb app upgrade`, а `nb source dev` не применяется.
:::
## NB_CLI_ROOT и структура каталогов
CLI сохраняет глобальную конфигурацию и локальные файлы приложений в каталоге, на который указывает `NB_CLI_ROOT`.
По умолчанию `NB_CLI_ROOT` равен домашнему каталогу текущего пользователя — пути, который возвращает `os.homedir()` в Node.js. Например, на macOS это обычно `/Users/<user>`. Поэтому без дополнительной настройки файлы, создаваемые `nb init --yes --env app1`, как правило, окажутся здесь:
```text
~
├── .nocobase
│ └── config.json
└── app1
├── source
└── storage
```
Вы также можете явно задать `NB_CLI_ROOT`:
```bash
export NB_CLI_ROOT=/your/workspace
```
После этого файлы конфигурации и каталог приложения по умолчанию будут располагаться внутри указанного каталога:
```text
/your/workspace
├── .nocobase
│ └── config.json
└── app1
├── source
└── storage
```
Где:
- `.nocobase/config.json` хранит env, текущее окружение, адрес API, путь к исходникам, путь к storage, настройки БД и т. д.
- `<envName>/source` — управляемый CLI каталог исходного кода или приложения.
- `<envName>/storage` — управляемый CLI каталог хранения приложения.
:::warning
После инициализации одного и того же приложения используйте один и тот же `NB_CLI_ROOT`. Если позже Вы измените `NB_CLI_ROOT`, CLI начнёт искать `.nocobase/config.json` в новом каталоге, а относительные пути `appRootPath` и `storagePath` будут разрешаться относительно нового каталога — это может привести к тому, что приложение не будет найдено или произойдёт чтение/запись в неправильный каталог.
:::
В настоящее время CLI использует только глобальный scope конфигурации. Если Вам нужно изменить расположение конфигурации и локальных файлов приложений, задавайте `NB_CLI_ROOT`.
При просмотре и поиске приложений отдавайте предпочтение командам `nb env list` и `nb env info`:
```bash
# Посмотреть настроенные env и статус аутентификации API
nb env list
# Посмотреть подробную информацию о конкретном env
nb env info app1
```
`nb env list` ориентирован на быстрый общий обзор. В нём `App Status` — это статус аутентификации, полученный после обращения к API приложения по сохранённым Token/OAuth-учётным данным. Состояние базы данных в этом списке больше не отображается. Для просмотра состояния встроенной базы данных используйте:
```bash
nb db ps -e app1
```
Менять env по умолчанию следует только при необходимости:
```bash
nb env use app1
```
## Миграция со старого способа на CLI
Существуют две стратегии миграции: **подключение к существующему приложению** или **передача каталога локального приложения под управление CLI**. Если Ваше старое приложение уже стабильно работает, рекомендуем сначала использовать «подключение к существующему приложению» — это наименее рискованный путь.
### Способ 1. Подключение к существующему приложению
Подходит для NocoBase, развёрнутого через Docker, create-nocobase-app, исходники Git или серверное развёртывание.
```bash
# По умолчанию используется аутентификация OAuth
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api
# Аутентификация по token
nb init --yes --env "app$RANDOM" \
--api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
--auth-type=token \
--access-token=<token>
```
При таком способе сохраняется только подключение по API. CLI не берёт на себя запуск, остановку, обновление, каталоги исходников или storage старого приложения. Подходит для подключения AI Agent или команд `nb api` к существующему приложению.
Если нужно обновить аутентификацию:
```bash
nb env auth app1
```
### Способ 2. Создание нового env CLI и миграция файлов
Подходит, если в дальнейшем Вы планируете управлять локальным приложением через `nb app` и `nb source`.
Перед миграцией обязательно выполните:
1. Остановите старое приложение.
2. Сделайте резервную копию старой базы данных.
3. Сделайте резервную копию старого каталога `storage`.
4. Зафиксируйте ключевые переменные окружения старого приложения, например `APP_KEY`, `TZ`, `DB_*`, `DB_UNDERSCORED`.
#### Миграция со старой Docker-установки
Старая Docker-установка обычно хранит данные приложения в каталоге `storage` внутри проекта:
```text
/old-docker-project
├── docker-compose.yml
└── storage
```
Рекомендуется сначала определить новый `NB_CLI_ROOT`, а затем создать новое Docker-env через CLI. В примере ниже предполагается, что `NB_CLI_ROOT` равен `/your/workspace`.
```bash
export NB_CLI_ROOT=/your/workspace
nb init --yes --env app2 --source docker --version beta
nb app stop -e app2
```
Новый env по умолчанию будет использовать следующие каталоги:
```text
/your/workspace
└── app2
├── source
└── storage
```
Затем скопируйте старый `storage` в `/your/workspace/app2/storage` и убедитесь, что параметры подключения к БД и значения `APP_KEY` и т. п. совпадают со старым окружением.
После копирования и проверки настроек БД запустите приложение:
```bash
nb app start -e app2
nb app logs -e app2
```
#### Миграция с create-nocobase-app или установки из исходников Git
В старом способе через npm/Git исходный код, файл `.env` и `storage` обычно находятся в одном каталоге проекта:
```text
/old-nocobase
├── .env
├── package.json
├── packages
└── storage
```
Рекомендуется сначала определить новый `NB_CLI_ROOT`, а затем создать новое npm- или Git-env. В примере ниже предполагается, что `NB_CLI_ROOT` равен `/your/workspace`.
```bash
export NB_CLI_ROOT=/your/workspace
nb init --yes --env app3 --source git --version beta
nb app stop -e app3
```
Затем выполните миграцию по необходимости:
- Перенесите исходный код собственных плагинов из старого проекта в соответствующий каталог `/your/workspace/app3/source`.
- Скопируйте старый каталог `storage` в `/your/workspace/app3/storage`.
- Перенесите ключевые настройки из старого `.env` в конфигурацию env CLI или в параметры инициализации.
- При использовании прежней БД отключите встроенную базу данных при инициализации и укажите параметры подключения к старой БД.
Пример инициализации с внешней базой данных:
```bash
nb init --yes --env app3 --source git --version beta \
--no-builtin-db \
--db-dialect postgres \
--db-host 127.0.0.1 \
--db-port 5432 \
--db-database nocobase \
--db-user nocobase \
--db-password nocobase
```
После миграции запустите приложение и просмотрите логи:
```bash
nb app start -e app3
nb app logs -e app3
```
:::warning
Не перезаписывайте `source`, `storage` и не запускайте обновление с подключением к продуктивной базе данных без резервной копии. Перед реальной миграцией рекомендуется полностью отрепетировать процедуру в тестовом окружении.
:::
## Шпаргалка по миграции старых команд
| Старая команда | Новая команда CLI |
| --- | --- |
| `docker compose up -d app` | `nb app start -e app1` |
| `docker compose stop app` | `nb app stop -e app1` |
| `docker compose logs -f app` | `nb app logs -e app1` |
| `docker compose pull app && docker compose up -d app` | `nb app upgrade -e app1` |
| `yarn create nocobase-app my-nocobase-app ...` | `nb init --yes --env app1 --source npm --version beta` |
| `npx create-nocobase-app@beta my-nocobase-app ...` | `nb init --yes --env app1 --source npm --version beta` |
| `git clone ... -b next --depth=1 my-nocobase` | `nb init --yes --env app1 --source git --version beta` |
| `git clone ... -b develop --depth=1 my-nocobase` | `nb init --yes --env app1 --source git --version alpha` |
| `yarn dev` | `nb source dev -e app1` |
| `yarn nocobase upgrade` | `nb app upgrade -e app1` |
| `yarn nocobase upgrade --skip-code-update` | `nb app upgrade -e app1 -s` |
| Ручное ведение списка адресов нескольких приложений | `nb env list`, `nb env info app1` |
| Ручное подключение к существующему приложению | `nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api` |
## Связанные материалы
- [Руководство по подключению AI Agent](/ai/quick-start)
- [Справочник команд NocoBase CLI](/api/cli)
- [Сравнение способов установки и версий](/get-started/quickstart)
- [Установка и обновление плагинов](/get-started/install-upgrade-plugins)