#Hướng dẫn cài đặt và chuyển đổi nâng cấp: Sử dụng NocoBase CLI

NocoBase CLI mới (nb) hợp nhất các thao tác cài đặt, kết nối, khởi động, dừng, xem log, nâng cấp và dọn dẹp vào một bộ lệnh thống nhất. So với quy trình được duy trì riêng biệt trong tài liệu cũ theo Docker, create-nocobase-app, mã nguồn Git, CLI phù hợp hơn cho phát triển cục bộ, bảo trì môi trường test, cũng như tích hợp và cộng tác với AI Agent.

Bài viết này phù hợp với các tình huống sau:

• Bạn đang cài đặt hoặc nâng cấp NocoBase theo tài liệu cũ và muốn chuyển sang phương thức CLI mới.
• Bạn đã có một NocoBase được triển khai theo cách cũ và muốn để CLI quản lý hoặc kết nối với nó.
• Bạn cần chuẩn bị một môi trường NocoBase có thể kết nối và bảo trì cho AI Agent.

#Sự khác biệt giữa cách cũ và cách mới

Cách cũ chia tài liệu theo nguồn cài đặt, mỗi nguồn cần thực hiện các lệnh tải xuống, cấu hình, cài đặt, khởi động và nâng cấp riêng biệt.

Tài liệu cài đặt cũ

• Cài đặt qua Docker
• Cài đặt qua create-nocobase-app
• Cài đặt qua mã nguồn Git

Tài liệu nâng cấp cũ

• Nâng cấp khi cài qua Docker
• Nâng cấp khi cài qua create-nocobase-app
• Nâng cấp khi cài qua mã nguồn Git

Cách mới lấy nb init làm điểm vào, sử dụng một CLI env duy nhất để ghi nhận nguồn ứng dụng, thư mục chạy, thư mục lưu trữ, cơ sở dữ liệu và thông tin kết nối API. Sau đó, dù nguồn là Docker, npm hay Git, đều cố gắng dùng cùng bộ lệnh nb app, nb source, nb db để bảo trì.

#Cài đặt CLI

npm install -g @nocobase/cli@beta
nb --version

Sau khi cài đặt có thể xem trợ giúp:

nb --help
nb init --help

#Sử dụng cách mới để cài đặt NocoBase

#Khuyến nghị: Sử dụng trình hướng dẫn trực quan

nb init --ui

Trình hướng dẫn sẽ giúp bạn chọn:

• Tạo ứng dụng mới hoặc kết nối ứng dụng đã có
• Nguồn cài đặt: Docker, npm, Git
• Phiên bản NocoBase
• Sử dụng cơ sở dữ liệu tích hợp sẵn hoặc cơ sở dữ liệu bên ngoài
• Tài khoản và mật khẩu quản trị

#Sử dụng trình hướng dẫn tương tác trên terminal

nb init

#Sử dụng lệnh phi tương tác

Phương thức cài đặt mặc định là Docker và sử dụng PostgreSQL tích hợp sẵn:

nb init --yes --env app1

Cài đặt phiên bản chỉ định qua Docker:

nb init --yes --env app1 --source docker --version beta

Cài đặt qua npm:

nb init --yes --env app1 --source npm --version beta --app-port 13080

Cài đặt qua mã nguồn Git:

nb init --yes --env app1 --source git --version beta

Cài đặt qua mã nguồn Git và chỉ định loại CSDL tích hợp sẵn:

nb init --yes --env app1 --source git --version beta --db-dialect mysql

Kết nối với ứng dụng NocoBase đã có:

# Mặc định sử dụng xác thực OAuth
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# Sử dụng xác thực token
nb init --yes --env app1 \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>

#Sử dụng cách mới để nâng cấp

Trong cách cũ, lệnh nâng cấp của Docker, create-nocobase-app, mã nguồn Git khác nhau; CLI mới thống nhất thành:

nb app upgrade -e app1

Nếu chỉ muốn dùng mã nguồn hoặc image đã tải xuống để chạy quy trình nâng cấp, không kéo code hoặc image mới:

nb app upgrade -e app1 --skip-code-update

Hoặc dùng dạng viết tắt:

nb app upgrade -e app1 -s

#Các lệnh bảo trì thường dùng

nb app down mặc định sẽ dừng ứng dụng, xóa container đang chạy do CLI quản lý và file ứng dụng cục bộ, nhưng vẫn giữ lại dữ liệu storage và cấu hình env. Khi muốn xóa toàn bộ nội dung phải xác nhận rõ ràng:

nb app down -e app1 --all --yes

#Các lệnh phát triển hằng ngày

nb source dùng để quản lý dự án mã nguồn cục bộ, chủ yếu áp dụng cho npm và Git source env.

#NB_CLI_ROOT và cấu trúc thư mục

CLI sẽ lưu cấu hình toàn cục và file ứng dụng cục bộ tại thư mục tương ứng với NB_CLI_ROOT.

Mặc định, NB_CLI_ROOT là thư mục home của người dùng hiện tại, tức là đường dẫn được Node.js os.homedir() trả về. Ví dụ trên macOS thường là /Users/<user>. Vì vậy, nếu không có cấu hình bổ sung, các file được tạo bởi nb init --yes --env app1 thường sẽ ở:

~
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

Bạn cũng có thể chỉ định rõ NB_CLI_ROOT:

export NB_CLI_ROOT=/your/workspace

Sau khi thiết lập, file cấu hình và thư mục ứng dụng mặc định đều sẽ nằm trong thư mục này:

/your/workspace
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

Trong đó:

• .nocobase/config.json lưu các thông tin về env, môi trường hiện tại, địa chỉ API, đường dẫn mã nguồn, đường dẫn storage, cấu hình CSDL...
• <envName>/source là thư mục mã nguồn hoặc ứng dụng do CLI quản lý.
• <envName>/storage là thư mục lưu trữ ứng dụng do CLI quản lý.

CLI hiện chỉ sử dụng scope cấu hình toàn cục. Nếu cần điều chỉnh vị trí lưu cấu hình và file ứng dụng cục bộ, vui lòng thiết lập NB_CLI_ROOT.

Khi xem và xác định ứng dụng, ưu tiên sử dụng nb env list và nb env info:

# Xem env đã cấu hình và trạng thái xác thực API
nb env list

# Xem thông tin chi tiết của một env
nb env info app1

nb env list hướng đến tổng quan nhanh, trong đó App Status là trạng thái xác thực có được sau khi truy cập API ứng dụng bằng Token/OAuth đã lưu, không còn hiển thị trạng thái CSDL. Khi cần xem trạng thái chạy của CSDL tích hợp sẵn, vui lòng sử dụng:

nb db ps -e app1

Chỉ khi cần chuyển env mặc định, mới sử dụng:

nb env use app1

#Chuyển từ cách cũ sang CLI

Có hai chiến lược chuyển đổi: kết nối ứng dụng đã có, hoặc đưa thư mục ứng dụng cục bộ vào quản lý của CLI. Nếu ứng dụng cũ của bạn đã chạy ổn định, khuyến nghị dùng "kết nối ứng dụng đã có" trước, rủi ro thấp nhất.

#Cách 1: Kết nối ứng dụng đã có

Phù hợp với NocoBase đã được chạy qua Docker, create-nocobase-app, mã nguồn Git hoặc triển khai trên server.

# Mặc định sử dụng xác thực OAuth
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# Sử dụng xác thực token
nb init --yes --env "app$RANDOM" \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>

Cách này chỉ lưu kết nối API, CLI sẽ không tiếp quản việc khởi động, dừng, nâng cấp, thư mục mã nguồn hoặc thư mục storage của ứng dụng cũ. Phù hợp để AI Agent hoặc lệnh CLI API kết nối với ứng dụng đã có.

Nếu cần làm mới xác thực:

nb env auth app1

#Cách 2: Tạo CLI env mới sau đó chuyển file

Phù hợp với tình huống bạn muốn dùng nb app và nb source để quản lý ứng dụng cục bộ về sau.

Trước khi chuyển, hãy hoàn tất:

1. Dừng ứng dụng cũ.
2. Sao lưu CSDL cũ.
3. Sao lưu thư mục storage cũ.
4. Ghi lại các biến môi trường quan trọng của ứng dụng cũ, ví dụ APP_KEY, TZ, DB_*, DB_UNDERSCORED.

#Chuyển từ cài đặt Docker cũ

Cách Docker cũ thường đặt dữ liệu ứng dụng trong storage của thư mục dự án:

/old-docker-project
├── docker-compose.yml
└── storage

Khuyến nghị xác định NB_CLI_ROOT mới trước, sau đó dùng CLI để tạo Docker env mới. Ví dụ dưới đây giả định NB_CLI_ROOT là /your/workspace.

export NB_CLI_ROOT=/your/workspace
nb init --yes --env app2 --source docker --version beta
nb app stop -e app2

Env mới sẽ mặc định sử dụng các thư mục sau:

/your/workspace
└── app2
    ├── source
    └── storage

Sau đó sao chép storage cũ vào /your/workspace/app2/storage, đảm bảo kết nối CSDL và APP_KEY cùng các cấu hình khác giống với môi trường cũ.

Sau khi sao chép xong và xác nhận cấu hình CSDL, hãy khởi động ứng dụng:

nb app start -e app2
nb app logs -e app2

#Chuyển từ cài đặt create-nocobase-app hoặc mã nguồn Git cũ

Cách npm/Git cũ thường đặt mã nguồn, .env và storage trong cùng một thư mục dự án:

/old-nocobase
├── .env
├── package.json
├── packages
└── storage

Khuyến nghị xác định NB_CLI_ROOT mới trước, sau đó tạo npm hoặc Git env mới. Ví dụ dưới đây giả định NB_CLI_ROOT là /your/workspace.

export NB_CLI_ROOT=/your/workspace
nb init --yes --env app3 --source git --version beta
nb app stop -e app3

Sau đó chuyển theo nhu cầu:

• Chuyển mã nguồn Plugin tùy chỉnh từ dự án cũ vào thư mục tương ứng /your/workspace/app3/source.
• Sao chép storage từ dự án cũ vào /your/workspace/app3/storage.
• Đồng bộ các cấu hình quan trọng từ .env cũ sang cấu hình CLI env hoặc tham số khởi tạo.
• Khi sử dụng CSDL gốc, vui lòng tắt CSDL tích hợp sẵn khi khởi tạo và điền thông tin kết nối CSDL cũ.

Ví dụ khởi tạo với CSDL bên ngoài:

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

Sau khi chuyển xong, khởi động và xem log:

nb app start -e app3
nb app logs -e app3

#Bảng tra cứu nhanh chuyển đổi lệnh cũ

#Liên kết liên quan

• Hướng dẫn tích hợp AI Agent
• Tài liệu tham khảo lệnh NocoBase CLI
• So sánh phương thức cài đặt và phiên bản
• Cài đặt và nâng cấp Plugin