快速完成NocoBase部署与配置，确保系统稳定运行
部署前准备：环境检查与规划
三种部署方式：Docker Compose、Dockerfile、源码安装
基础配置：系统设置与常见问题解决
环境检查与规划，确保部署顺利进行
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:latest # 生产环境请锁定具体版本，如 nocobase/nocobase:1.8.4
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:1.8.4），避免使用 latest 导致意外升级
DB_PASSWORD 与 POSTGRES_PASSWORD 保持一致
80，主机映射为 8080:80，生产环境建议前置 Nginx 反向代理启用 HTTPS
创建 Dockerfile 文件
cat > Dockerfile << 'EOF'
FROM nocobase/nocobase:latest
# 如需安装额外依赖，请在此添加
# 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:1.8.4），而非 latest 标签
RUN yarn add @nocobase/plugin-xxx）
client_max_body_size 100M 以支持大文件上传
安装 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 进行进程管理与开机自启
系统设置与初始化配置，确保系统正常运行
首次访问 NocoBase 时，系统会引导创建管理员账户。请设置强密码并妥善保管。
进入「设置」->「系统设置」，配置系统名称、LOGO、版权信息等。
进入「设置」->「邮件设置」，配置 SMTP 服务，用于发送验证码、通知等。
进入「插件市场」，安装所需的插件，如 AI 集成、图表分析等。
生产环境建议配置 HTTPS，可以通过反向代理（如 Nginx）实现。
仅开放必要的端口，如 80、443 等，关闭不必要的端口。
进入「设置」->「角色权限」，配置不同角色的权限，遵循最小权限原则。
定期备份数据库，可以通过 crontab 定时执行备份脚本。
部署与使用过程中常见问题的解决方法
docker-compose ps
docker-compose logs
psql -h localhost -U nocobase -d nocobase