#nb init

Khởi tạo workspace hiện tại để coding agent có thể kết nối và sử dụng NocoBase.

nb init có thể cài đặt một ứng dụng NocoBase cục bộ mới, hoặc lưu thông tin kết nối của một ứng dụng đã có sẵn.

Ngoài ra, nb init mặc định cũng sẽ đồng bộ NocoBase AI coding skills. Chỉ khi bạn đã tự quản lý skills, hoặc đang chạy trong CI hay môi trường offline, bạn mới cần thêm --skip-skills.

#Cách dùng

nb init [flags]

#Chế độ tương tác

nb init hỗ trợ ba chế độ tương tác:

• nb init：hoàn tất hướng dẫn từng bước trong terminal
• nb init --ui：mở biểu mẫu trên trình duyệt cục bộ và hoàn tất setup bằng trình hướng dẫn trực quan
• nb init --yes --env app1：bỏ qua các lời nhắc và dùng trực tiếp flags; các tham số không được truyền rõ ràng sẽ được xử lý theo giá trị mặc định

Chế độ --yes phù hợp cho script, CI/CD hoặc các tình huống không tương tác khác. Ở chế độ này, --env <envName> là bắt buộc. Thông thường, nó sẽ mặc định cài đặt một ứng dụng cục bộ mới; nếu bạn không chỉ định --source, mặc định sẽ dùng docker làm nguồn cài đặt.

#Tiếp tục quá trình khởi tạo bị gián đoạn

Với các luồng cài đặt, env config sẽ được lưu trước, sau đó mới thực hiện tải xuống, cơ sở dữ liệu và cài đặt ứng dụng. Nếu thất bại giữa chừng, bạn có thể tiếp tục:

nb init --env app1 --resume

--resume chỉ áp dụng cho các luồng khởi tạo mà env config đã được lưu trước đó, và bắt buộc phải truyền rõ ràng --env.

#Chuẩn bị env trước, cài app sau

--prepare-only dành cho các luồng mà bạn cần chuẩn bị env trước, sau đó kích hoạt license, rồi mới cài đặt và khởi động app.

Nếu bạn muốn lưu cấu hình env trước, chuẩn bị source code hoặc image, đồng thời chuẩn bị sẵn cơ sở dữ liệu, nhưng tạm hoãn việc cài đặt app thực tế và lần khởi động đầu tiên, bạn có thể dùng:

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

Chế độ này khả dụng cho các luồng cài đặt cục bộ, bao gồm cả trình hướng dẫn --ui. Nó không khả dụng cho các luồng kết nối từ xa. CLI sẽ lưu env hiện tại ở trạng thái prepared, để sau đó bạn có thể tiếp tục với luồng như sau:

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

Sau đó, nb app start sẽ hoàn tất lần cài đặt đầu tiên và chuyển env từ trạng thái prepared sang trạng thái installed thông thường.

#Giải thích thư mục cài đặt

Bạn có thể xem đường dẫn đầy đủ bằng nb env info app1 --field app.appPath.

Theo mặc định, CLI sẽ tổ chức các tệp cục bộ dưới app-path theo quy ước sau:

<app-path>/
├── source/   # Thư mục mặc định tương ứng với mã nguồn ứng dụng hoặc nội dung đã tải xuống
├── storage/  # Thư mục dữ liệu runtime
└── .env      # Tệp biến môi trường ứng dụng tùy chọn

Thông thường:

• source/ chủ yếu tương ứng với thư mục ứng dụng cục bộ của env kiểu npm / Git. Với Docker env, CLI cũng giữ quy ước suy luận đường dẫn mặc định này, nhưng phần lớn trường hợp bạn không cần quan tâm thủ công đến nó. Hãy đặc biệt chú ý khi nâng cấp: thư mục source/ sẽ bị xóa rồi tải lại, vì vậy đừng đặt các tệp cần giữ lại ở đây
• storage/ dùng để lưu dữ liệu runtime, chẳng hạn như dữ liệu cơ sở dữ liệu tích hợp, plugin, log, v.v.
• .env là tệp biến môi trường ứng dụng tùy chọn. Chỉ khi bạn cần tùy chỉnh biến môi trường thì mới cần thêm nó vào <app-path>/.env; nếu tệp này tồn tại, các nguồn cài đặt Docker, npm và Git sẽ mặc định đọc nó

Đây là quy ước thư mục mặc định của CLI. Với các nguồn cài đặt, plugin và giai đoạn runtime khác nhau, nội dung thư mục thực tế được tạo ra có thể không hoàn toàn giống nhau.

#Lưu ý

#Định vị nhanh theo Steps

Các Steps hiển thị sẽ không hoàn toàn giống nhau tùy theo đường dẫn setup. Ví dụ, khi kết nối tới ứng dụng đã có sẵn, thông thường chỉ dùng Getting started và Remote connection.

Nếu bạn đang thao tác từng bước theo trình hướng dẫn UI cục bộ, có thể dùng bảng dưới đây để định vị nhanh:

#Tham số

Có khá nhiều tham số, nên sẽ dễ hiểu hơn nếu tách ra theo từng tình huống sử dụng.

“Giá trị mặc định” bên dưới là giá trị hoặc hành vi mà nb init thường sử dụng khi bạn bỏ qua tham số đó.

#Cơ bản và tương tác

#Kết nối ứng dụng đã có sẵn

#Tham số cơ bản cho cài đặt cục bộ

#Tham số cơ sở dữ liệu

#Tham số tải xuống và mã nguồn

#Ví dụ

Dưới đây là một số cách dùng phổ biến nhất.

#Hoàn tất hướng dẫn từng bước trong terminal

nb init

#Mở trình hướng dẫn trên trình duyệt cục bộ

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

#Chuẩn bị trước, rồi kích hoạt license và khởi động sau

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

#Cài đặt không tương tác một ứng dụng cục bộ mới

Nếu bạn không chỉ định --source, thông thường Docker sẽ được dùng làm nguồn cài đặt.

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

#Cài nhanh và dùng xác thực basic

Nếu bạn muốn nhanh chóng cài một ứng dụng cục bộ trong chế độ không tương tác, đồng thời lưu luôn xác thực basic ngay sau khi cài xong, bạn có thể viết như sau. Khi đó sẽ không cần mở trình duyệt để hoàn tất OAuth nữa.

Nếu dùng tài khoản quản trị viên mặc định trong chế độ --yes, cách ngắn nhất là như sau.

Nếu không được chỉ định, tài khoản quản trị viên mặc định là nocobase, và mật khẩu mặc định là admin123:

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

Nếu bạn muốn đồng thời tùy chỉnh tài khoản quản trị viên, cũng có thể viết như sau:

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

#Kết nối một ứng dụng đã có sẵn

Thông thường chỉ cần dùng OAuth mặc định. Nếu trong một số tình huống CI/CD bạn không tiện mở trình duyệt, cũng có thể lưu trực tiếp xác thực basic; nếu bạn đã có API token, cũng có thể lưu trực tiếp xác thực 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

#Tùy chỉnh quy ước đặt tên cơ sở dữ liệu

Nếu bạn cần chỉ định PostgreSQL schema, tiền tố bảng hoặc cách đặt tên với gạch dưới, có thể truyền tham số như sau:

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

#Tiếp tục lần khởi tạo trước bị gián đoạn

nb init --env app1 --resume

#Hiển thị log chi tiết khi xử lý sự cố

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

#Lệnh liên quan

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