NocoBase 實施者指南
Docker / 原始碼部署 · 基礎配置 · 常見問題 — 部署文件 + 選型/商務內鏈，交付一條龍。
你在做什麼？選一個路徑
📋 部署前準備
環境檢查與規劃，確保部署順利進行
硬體與網路要求
最低配置（測試環境）
- CPU：2核
- 記憶體：4GB
- 磁碟：50GB
- 網路：穩定的網際網路連線
推薦配置（生產環境）
- CPU：4核及以上
- 記憶體：8GB及以上
- 磁碟：100GB SSD及以上
- 網路：穩定的網際網路連線，建議使用專線
軟體環境要求
Docker 部署方式（推薦）
- Docker Engine：24.0+（推薦 27.x）
-
Docker Compose：V2 2.20+（命令為
docker compose，注意無連字元） - 作業系統：Linux（推薦 Ubuntu 22.04 LTS / CentOS Stream 9）、Windows 10/11、macOS 12+
- 國內部署建議配置 Docker 映象加速器
原始碼安裝方式
- Node.js：20.x LTS 或 22.x LTS（v1.x 不再支援 Node 16/18）
- 包管理器：Yarn 1.22+ 或 pnpm 8+（官方模板預設使用 Yarn）
- 資料庫：PostgreSQL 16+（推薦）或 MySQL 8.0+ / MariaDB 10.7+ / SQLite 3.x
- 作業系統：Linux（推薦）、Windows 10/11、macOS 12+
部署規劃
1 環境準備
- 確認伺服器硬體配置
- 安裝必要的軟體依賴
- 配置網路和防火牆
2 部署方式選擇
- 測試環境：Docker Compose
- 生產環境：Dockerfile
- 深度定製：原始碼安裝
3 後續規劃
- 資料備份策略
- 監控與告警
- 定期更新計劃
🚀 部署方式
三種部署方式詳細教程，滿足不同場景需求
方式一：Docker Compose 一鍵部署（推薦測試環境）
部署步驟
建立部署目錄與資料卷目錄
mkdir -p nocobase/storage && cd nocobase
生成必填金鑰 APP_KEY（用於會話加密，缺失則啟動失敗）
openssl rand -base64 36 # 將輸出的字串填入下面 APP_KEY 及 .env
建立 docker compose.yml（完整可用版本）
cat > docker compose.yml << 'EOF'
# Compose Spec 不再需要 version 欄位
services:
app:
image: nocobase/nocobase:2.1.20 # 生產環境請鎖定具體版本，如 nocobase/nocobase:2.1.20
restart: unless-stopped
depends_on:
- postgres
environment:
# ── 應用金鑰（必填）──
- APP_KEY=請替換為 openssl 生成的隨機字串
- APP_PORT=8080
- APP_ENV=production
- TZ=Asia/Shanghai
# ── 資料庫連線（NocoBase 使用 DB_* 獨立變數，不要用 DATABASE_URL）──
- DB_DIALECT=postgres
- DB_HOST=postgres
- DB_PORT=5432
- DB_DATABASE=nocobase
- DB_USER=nocobase
- DB_PASSWORD=請修改為強密碼
# ── 首次啟動自動建立管理員（可選，推薦）──
- INIT_ROOT_EMAIL=admin@example.com
- INIT_ROOT_PASSWORD=請修改為強密碼
- INIT_ROOT_NICKNAME=Super Admin
volumes:
- ./storage:/app/nocobase/storage # 上傳檔案/外掛/日誌，絕不能省
ports:
- "8080:80"
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
- POSTGRES_DB=nocobase
- POSTGRES_USER=nocobase
- POSTGRES_PASSWORD=請修改為強密碼 # 與上方 DB_PASSWORD 保持一致
- TZ=Asia/Shanghai
volumes:
- ./postgres-data:/var/lib/postgresql/data
EOF
啟動服務（注意是 Docker Compose V2，命令為 docker compose、無連字元）
docker compose up -d && docker compose logs -f app
訪問 NocoBase
開啟瀏覽器，訪問 http://伺服器IP:8080，使用 INIT_ROOT_EMAIL / INIT_ROOT_PASSWORD 登入
注意事項
-
未設定
APP_KEY會導致啟動失敗，請務必用openssl rand -base64 36生成隨機金鑰 -
必須掛載
./storage卷，否則容器重啟後上傳檔案、外掛、日誌全部丟失 -
生產環境請鎖定具體版本（如
nocobase/nocobase:2.1.20），避免使用latest導致意外升級 -
預設資料庫密碼請修改為強密碼，且
DB_PASSWORD與POSTGRES_PASSWORD保持一致 -
容器內部服務監聽埠是
80，主機對映為8080:80，生產環境建議前置 Nginx 反向代理啟用 HTTPS
方式二：Dockerfile 自定義構建（推薦生產環境）
部署步驟
建立 Dockerfile 檔案
cat > Dockerfile << 'EOF'
FROM nocobase/nocobase:2.1.20
# 如需安裝額外依賴，請在此新增
# RUN npm install some-package
# 如需複製自定義配置，請在此新增
# COPY config.yml /app/config/
EOF
構建映象
docker build -t my-nocobase .
建立 docker compose.yml（生產環境完整可用版本，請先用 openssl rand -base64 36 生成 APP_KEY）
cat > docker compose.yml << 'EOF'
# Compose Spec 不再需要 version 欄位
services:
app:
image: my-nocobase
restart: unless-stopped
depends_on:
- postgres
environment:
# ── 應用金鑰（必填）──
- APP_KEY=請替換為 openssl 生成的隨機字串
- APP_PORT=8080
- APP_ENV=production
- TZ=Asia/Shanghai
# ── 資料庫連線（DB_* 獨立變數）──
- DB_DIALECT=postgres
- DB_HOST=postgres
- DB_PORT=5432
- DB_DATABASE=nocobase
- DB_USER=nocobase
- DB_PASSWORD=your_strong_password
# ── 生產環境項──
- LOGGER_LEVEL=info
- LOGGER_TRANSPORT=console,file
volumes:
- ./storage:/app/nocobase/storage # 檔案上傳/外掛/日誌持久化
ports:
- "8080:80"
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
- POSTGRES_DB=nocobase
- POSTGRES_USER=nocobase
- POSTGRES_PASSWORD=your_strong_password # 與 DB_PASSWORD 保持一致
- TZ=Asia/Shanghai
volumes:
- ./postgres-data:/var/lib/postgresql/data
EOF
啟動服務（Docker Compose V2）
docker compose up -d
注意事項
-
生產環境必填
APP_KEY（會話加密金鑰），請使用openssl rand -base64 36生成 -
必須掛載
./storage卷以持久化檔案、外掛、日誌 - 生產環境請務必修改資料庫密碼為強密碼，且兩處密碼保持一致
-
建議使用固定版本映象（如
nocobase/nocobase:2.1.20），而非latest標籤 -
可根據需要在 Dockerfile 中新增自定義配置和依賴（如
RUN yarn add @nocobase/plugin-xxx） -
生產環境推薦前置 Nginx 反向代理、開啟 HTTPS，並設定
client_max_body_size 100M以支援大檔案上傳
方式三：create-nocobase-app 原始碼安裝（適合深度定製）
部署步驟
安裝 Node.js
使用 nvm 安裝 Node.js 20.x LTS：nvm install 20 && nvm use 20
建立專案（以 PostgreSQL 為例，互動式填寫資料庫資訊）
yarn create nocobase-app my-nocobase-app -d postgres
可選 -d postgres / mysql / mariadb / sqlite；npm 使用者可用 npm create nocobase-app@latest
配置資料庫
根據提示配置資料庫連線資訊
安裝依賴 & 啟動服務（開發模式）
cd my-nocobase-app && yarn install && yarn nocobase install && yarn dev
生產環境構建 & 啟動
yarn build && yarn start --quickstart
推薦使用 pm2 start "yarn start" --name nocobase 進行程序管理與開機自啟
注意事項
- 此方式適合需要深度定製或二次開發的場景
- 需要更多的系統資源和 Node.js 相關知識
- 生產環境建議使用 PM2 等程序管理工具
⚙️ 基礎配置
系統設定與初始化配置，確保系統正常執行
初始配置
1. 建立管理員賬戶
首次訪問 NocoBase 時，系統會引導建立管理員賬戶。請設定強密碼並妥善保管。
2. 配置系統資訊
進入「設定」->「系統設定」，配置系統名稱、LOGO、版權資訊等。
3. 配置郵件服務
進入「設定」->「郵件設定」，配置 SMTP 服務，用於傳送驗證碼、通知等。
4. 安裝必要外掛
進入「外掛市場」，安裝所需的外掛，如 AI 整合、圖表分析等。
安全配置
1. 配置 HTTPS
生產環境建議配置 HTTPS，可以透過反向代理（如 Nginx）實現。
2. 配置防火牆
僅開放必要的埠，如 80、443 等，關閉不必要的埠。
3. 配置許可權管理
進入「設定」->「角色許可權」，配置不同角色的許可權，遵循最小許可權原則。
4. 配置資料備份
定期備份資料庫，可以透過 crontab 定時執行備份指令碼。
效能最佳化
伺服器最佳化
- 調整伺服器核心引數
- 配置合適的 swap 空間
- 使用 SSD 儲存
資料庫最佳化
- 調整 PostgreSQL 配置引數
- 定期清理無用資料
- 建立合適的索引
應用最佳化
- 啟用快取機制
- 合理配置外掛
- 最佳化圖片和靜態資源
🔧 常見問題及解決方案
部署與使用過程中常見問題的解決方法
問題：Docker 部署後無法訪問
可能原因
- 埠未開放
- 防火牆阻止
- 容器未正常啟動
解決方案
-
檢查埠對映是否正確：
docker compose ps - 檢查防火牆設定，開放相應埠
-
檢視容器日誌：
docker compose logs
問題：資料庫連線失敗
可能原因
- 資料庫配置錯誤
- 資料庫服務未啟動
- 網路連線問題
解決方案
- 檢查資料庫配置是否正確
- 確保資料庫服務正常執行
-
測試資料庫連線：
psql -h localhost -U nocobase -d nocobase
問題：外掛安裝失敗
可能原因
- 網路連線問題
- 外掛版本與系統不相容
- 伺服器資源不足
解決方案
- 檢查網路連線是否正常
- 確保外掛版本與系統版本相容
- 檢查伺服器記憶體和磁碟空間是否充足
問題：系統執行緩慢
可能原因
- 伺服器資源不足
- 資料庫未最佳化
- 外掛過多或配置不當
解決方案
- 增加伺服器資源（CPU、記憶體）
- 最佳化資料庫配置，建立合適的索引
- 禁用不必要的外掛，最佳化系統配置
NocoBase · 相關模組
部署完成後，實施者常見下一站
選型、對比、驗收與商務 — 減少反覆搜尋