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 · 相关模块
部署完成后，实施者常见下一站
选型、对比、验收与商务 — 减少反复搜索