#nb init

Inicializa o workspace atual para que o coding agent possa se conectar e usar o NocoBase.

nb init pode instalar um app NocoBase local novo ou salvar as informações de conexão de um app existente.

Além disso, por padrão, nb init também sincroniza as NocoBase AI coding skills. Você só precisa adicionar --skip-skills quando já gerencia as skills por conta própria ou está executando em CI ou em um ambiente offline.

#Uso

nb init [flags]

#Modo interativo

nb init oferece três modos de interação:

• nb init: conclui o assistente passo a passo no terminal
• nb init --ui: abre um formulário no navegador local e conclui o setup com um assistente visual
• nb init --yes --env app1: pula os prompts e usa diretamente as flags; parâmetros não informados explicitamente usarão os valores padrão

O modo --yes é adequado para scripts, CI/CD ou outros cenários não interativos. Nesse modo, --env <envName> é obrigatório. Em geral, ele instala por padrão um app local novo; se você não especificar --source, docker será usado como origem de instalação por padrão.

#Retomar uma inicialização interrompida

Fluxos de instalação primeiro salvam a configuração do env e depois executam o download, o banco de dados e a instalação do app. Se falhar no meio do processo, você pode continuar:

nb init --env app1 --resume

--resume só se aplica a fluxos de inicialização em que a configuração do env já foi salva, e --env deve ser informado explicitamente.

#Preparar primeiro o env e instalar o app depois

--prepare-only foi feito para fluxos em que o env precisa ser preparado primeiro, depois a licença é ativada e só então o app é instalado e iniciado.

Se você quiser salvar primeiro a configuração do env, preparar os arquivos-fonte ou a imagem e deixar o banco de dados pronto, mas adiar a instalação real do app e a primeira inicialização, pode usar:

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

Esse modo está disponível para fluxos de instalação local, incluindo o assistente --ui. Ele não está disponível para fluxos de conexão remota. A CLI salvará o env atual no estado prepared, para que depois você possa continuar com um fluxo como este:

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

Depois disso, nb app start concluirá a primeira instalação e mudará o env do estado prepared para o estado normal installed.

#Sobre o diretório de instalação

Você pode ver o caminho completo com nb env info app1 --field app.appPath.

Por padrão, a CLI organiza os arquivos locais em app-path seguindo esta convenção:

<app-path>/
├── source/   # diretório padrão correspondente ao código-fonte do app ou ao conteúdo baixado
├── storage/  # diretório de dados em tempo de execução
└── .env      # arquivo opcional de variáveis de ambiente do app

Em geral:

• source/ corresponde principalmente ao diretório local do app para envs npm / Git. Para envs Docker, a CLI também mantém essa lógica padrão de caminho, embora na maioria das vezes você não precise se preocupar manualmente com isso. Tenha atenção especial durante upgrades: o diretório source/ será removido e baixado novamente, então não coloque aqui arquivos que precisam ser preservados
• storage/ é usado para armazenar dados de runtime, como dados do banco de dados embutido, plugins, logs etc.
• .env é um arquivo opcional de variáveis de ambiente do app. Você só precisa adicioná-lo em <app-path>/.env quando quiser personalizar variáveis de ambiente; se esse arquivo existir, as origens de instalação Docker, npm e Git o lerão por padrão

Isso representa a convenção de diretórios padrão da CLI. Dependendo da origem de instalação, dos plugins e da fase de execução, o conteúdo real gerado no diretório pode não ser exatamente o mesmo.

#Observações

#Localizar rapidamente por Steps

Os Steps exibidos variam um pouco conforme o caminho de setup. Por exemplo, ao conectar um app existente, normalmente você só usará Getting started e Remote connection.

Se você estiver seguindo o assistente local da UI passo a passo, pode usar a tabela abaixo para localizar rapidamente:

#Parâmetros

Há muitos parâmetros; fica mais claro separá-los por cenário de uso.

O “valor padrão” abaixo representa o valor ou comportamento que nb init normalmente adota quando você omite esse parâmetro.

#Básico e interação

#Conectar um app existente

#Parâmetros básicos de instalação local

#Parâmetros do banco de dados

#Parâmetros de download e código-fonte

#Exemplos

Os usos mais comuns são os seguintes.

#Concluir o assistente passo a passo no terminal

nb init

#Abrir o assistente no navegador local

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

#Preparar primeiro, depois ativar a licença e iniciar mais tarde

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

#Instalar um app local novo em modo não interativo

Se você não especificar --source, normalmente docker será usado como origem de instalação.

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

#Instalar rapidamente e usar autenticação basic

Se você quiser instalar rapidamente um app local em modo não interativo e salvar diretamente a autenticação basic após a instalação, também pode fazer assim. Dessa forma, não é necessário abrir o navegador para concluir o OAuth.

Se você mantiver a conta de administrador padrão do modo --yes, a forma mais curta é esta.

Quando ausente, a conta de administrador padrão é nocobase e a senha padrão é admin123:

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

Se você também quiser personalizar a conta de administrador, pode fazer assim:

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

#Conectar um app existente

Usar OAuth por padrão é suficiente. Se, em alguns cenários de CI/CD, não for conveniente abrir o navegador, você também pode salvar diretamente a autenticação basic; se já tiver um API token, também pode salvar diretamente a autenticação 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

#Personalizar nomes do banco de dados

Se você precisar especificar um schema PostgreSQL, prefixo de tabela ou nomes com sublinhado, pode passar os parâmetros assim:

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

#Continuar a inicialização interrompida anterior

nb init --env app1 --resume

#Exibir logs detalhados para troubleshooting

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

#Comandos relacionados

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