NocoBase 2.2.29 Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用官方 Docker Compose 方案从零部署一套可持久化、可升级、可日常运维的 NocoBase 2.2.29 实例：官方模板逐项解读、首次启动初始化、管理员登录验证、数据落盘与重启验证、升级与回滚、常见问题。本文全部命令与回显在「Ubuntu 22.04.4 LTS / Docker Engine 29.8.1 / Docker Compose v5.5.1 / NocoBase 2.2.29 / PostgreSQL 16」环境实测通过。平台定位与选型背景见 《NocoBase 介绍与选型指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（x86_64）
• 基础组件：Docker Engine 29.8.1、Docker Compose v5.5.1（docker compose v2 命令体系）
• 应用版本：NocoBase 2.2.29（官方最新稳定版，shields.io release 徽章 + 应用内版本接口双重确认，查询日期 2026-10-21）
• 数据库：PostgreSQL 16（官方模板配套版本）
• 官方发行物：nocobase/nocobase:latest（slim 版，实测占用 1.47GB）与 nocobase/nocobase:latest-full（full 版）
• 部署目录：/opt/nocobase（本文演示路径）
• 端口规划：宿主 8140 → 应用 HTTP 80（官方默认映射为 13000:80，宿主端口按本机空闲槽位选择，绑定前用 ss -ltnp 确认）
• 初始管理员：admin@nocobase.com / admin123（官方初始账号，登录后应立即改密；本系列演示统一以 admin + q1w2e3r4 作为改密后的示例凭据）

二、发行版选型说明

官方在 Docker Hub 上为 NocoBase 维护两个常用标签线（来源：官方文档「Deployment」与 Docker Hub 官方页，查询日期 2026-10-21）：

官方文档的示例模板使用 latest-full。两点选型建议：一是生产环境应将标签固定为具体版本号（本文实测版本为 2.2.29，写作时官方标签线仍以 latest 为主，读者可在 Docker Hub 标签页核对对应版本号标签）；二是若用不到 Oracle 客户端与 LibreOffice，slim 版可节省约一半存储开销。本文实测基于 slim 版 latest（实测 digest sha256:90add22b3adf…，1.47GB），latest-full 的 compose 差异仅在 image: 一行。

三、前置条件

1. 服务器已安装 Docker Engine 与 docker compose 插件，验证命令与实测回显：

docker compose version

实测回显：

Docker Compose version v5.5.1

2. 端口未占用确认：本文用宿主 8140 端口，绑定前先用 ss -ltn 确认空闲：

ss -ltn | grep 8140 || echo "8140 端口空闲"

实测回显（部署后已监听状态，部署前该命令应无输出）：

LISTEN 0      4096         0.0.0.0:8140       0.0.0.0:*
LISTEN 0      4096            [::]:8140          [::]:*

3. 磁盘预留：slim 版下载约 1.5GB，加上 PostgreSQL 数据与上传文件，建议预留 10GB 以上；full 版按 8GB 以上预留。
4. 国外资源拉取受限的网络环境，为 Docker 守护进程配置 HTTP 代理后 docker compose pull 可正常拉取官方发行物。

四、部署步骤

4.1 创建部署目录与 compose 文件

先建目录，再写入 compose 文件（以下为本文实测使用的完整文件，基于官方 PostgreSQL 版模板，宿主端口改用 8140、时区改用上海）：

mkdir -p /opt/nocobase && cd /opt/nocobase

写入 docker-compose.yml：

name: nocobase-v2.2.29-stack

networks:
  nocobase:
    name: nocobase-v229-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.66.0/24

services:
  app:
    image: nocobase/nocobase:latest
    container_name: nocobase-app
    restart: always
    networks:
      - nocobase
    depends_on:
      - postgres
    environment:
      - APP_KEY=-q2y7vtoxlu1jq0v5vi5jveudk3yogckm
      - DB_DIALECT=postgres
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_DATABASE=nocobase
      - DB_USER=nocobase
      - DB_PASSWORD=nocobase
      - TZ=Asia/Shanghai
    volumes:
      - ./storage:/app/nocobase/storage
    ports:
      - '8140:80'

  postgres:
    image: postgres:16
    container_name: nocobase-postgres
    restart: always
    command: postgres -c wal_level=logical
    environment:
      POSTGRES_USER: nocobase
      POSTGRES_DB: nocobase
      POSTGRES_PASSWORD: nocobase
    volumes:
      - ./storage/db/postgres:/var/lib/postgresql/data
    networks:
      - nocobase

4.2 compose 配置逐项解读

name: nocobase-v2.2.29-stack：compose 项目名。必填且全机唯一——多套部署共用一台宿主时，缺省项目名取目录名，若多套栈目录同名会互相覆盖操作对象，显式命名可彻底避免。

networks.nocobase：自定义 bridge 内网，应用与数据库都在该网内，数据库只暴露网内端口（5432/tcp，无宿主映射），外部无法直连。ipam 子网按 10.89.66.0/24 显式指定，避免与宿主上其他内网段冲突（没有多网段共存需求时可省略 ipam 配置，让系统自动分配）。

app 服务逐项：

postgres 服务逐项：command: postgres -c wal_level=logical 为官方模板原样保留（逻辑复制能力，供备份迁移类插件使用）；POSTGRES_USER/DB/PASSWORD 三项须与 app 服务的 DB_* 完全一致；数据目录挂载到 ./storage/db/postgres，与应用文件同属一个 storage 树，备份时一并打包即可。

4.3 启动与首次初始化

cd /opt/nocobase && docker compose up -d

实测回显（首次启动）：

 Network nocobase-v229-net Creating
 Network nocobase-v229-net Created
 Container nocobase-v229-postgres Creating
 Container nocobase-v229-postgres Created
 Container nocobase-v229-app Creating
 Container nocobase-v229-app Created
 Container nocobase-v229-postgres Starting
 Container nocobase-v229-postgres Started
 Container nocobase-v229-app Starting
 Container nocobase-v229-app Started

首次启动会自动完成安装初始化（建表、写入初始数据、启动服务进程），无需手工执行安装命令。初始化过程用日志观察：

docker compose logs -f app

实测关键日志节选（首次启动）：

app-postgres-app-1  |  nginx started
app-postgres-app-1  |  yarn run v1.22.15
app-postgres-app-1  |  $ cross-env DOTENV_CONFIG_PATH=.env node -r dotenv/config packages/app/server/lib/index.js install -s
app-postgres-app-1  |  Done in 2.72s.
app-postgres-app-1  |  $ pm2-runtime start --node-args="-r dotenv/config" packages/app/server/lib/index.js -- start
app-postgres-app-1  |  {"level":"info","message":"app has been started",...}

看到 app has been started 即初始化完成并进入服务状态；按 Ctrl+C 退出日志跟踪（不影响后台运行）。

4.4 状态确认与健康验证

docker compose ps

实测回显：

NAME                     IMAGE                      COMMAND                  SERVICE    CREATED          STATUS         PORTS
nocobase-v229-app        nocobase/nocobase:latest   "docker-entrypoint.s…"   app        14 seconds ago   Up 14 seconds   0.0.0.0:8140->80/tcp, [::]:8140->80/tcp
nocobase-v229-postgres   postgres:16                "docker-entrypoint.s…"   postgres   14 seconds ago   Up 14 seconds   5432/tcp

两个服务均为 Up 状态后，做三层验证：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8140/

实测回显：

HTTP 200

版本接口验证（确认部署版本）：

curl -s http://127.0.0.1:8140/api/app:getInfo

实测回显：

{"data":{"database":{"dialect":"postgres"},"version":"2.2.29","lang":"en-US","name":"main","theme":"default"}}

登录接口验证（使用官方初始账号）：

curl -s -X POST http://127.0.0.1:8140/api/auth:signIn \
  -H 'Content-Type: application/json' \
  -H 'X-Authenticator: basic' \
  -d '{"account":"admin@nocobase.com","password":"admin123"}'

实测回显（节选）：

{"data":{"user":{...,"nickname":"Super Admin","email":"admin@nocobase.com"...},"token":"eyJ..."}}

返回用户信息与 token 即登录链路正常。

💡 说明：三层验证分别覆盖「前端可达、版本正确、认证可用」。日常巡检用前两条即可，登录接口验证保留在首次部署与故障排查时使用。

浏览器访问 http://<服务器IP>:8140 进入管理界面，用初始账号 admin@nocobase.com / admin123 登录后，立即在右上角个人中心修改密码（本系列后续演示统一以 admin + q1w2e3r4 作为改密后的示例凭据），并妥善保管 APP_KEY。

五、数据持久化说明

NocoBase 的全部状态都在部署目录的 storage 树内，重启、重建实例均不丢数据：

du -sh storage && find storage -maxdepth 1 -type d | sort

实测回显：

68M     storage
storage
storage/apps
storage/db
storage/logs
storage/uploads

重启验证实测（先完整停掉再拉起，验证数据不丢）：

docker compose down && docker compose up -d

实测回显（down 段）：

 Container nocobase-v229-app Stopping
 Container nocobase-v229-app Stopped
 Container nocobase-v229-app Removing
 Container nocobase-v229-app Removed
 Container nocobase-v229-postgres Stopping
 Container nocobase-v229-postgres Stopped
 Container nocobase-v229-postgres Removing
 Container nocobase-v229-postgres Removed
 Network nocobase-v229-net Removing
 Network nocobase-v229-net Removed

实测回显（up 段）：

 Network nocobase-v229-net Creating
 Network nocobase-v229-net Created
 Container nocobase-v229-postgres Creating
 Container nocobase-v229-postgres Created
 Container nocobase-v229-app Creating
 Container nocobase-v229-app Created
 Container nocobase-v229-postgres Starting
 Container nocobase-v229-postgres Started
 Container nocobase-v229-app Starting
 Container nocobase-v229-app Started

拉起后再次查询版本与页面状态：

curl -s http://127.0.0.1:8140/api/app:getInfo
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8140/

实测回显：

{"data":{"database":{"dialect":"postgres"},"version":"2.2.29","lang":"en-US","name":"main","theme":"default"}}

HTTP 200

版本、页面状态与登录账号均与重建前一致，持久化生效。日常备份策略：低峰期停写后打包 storage/ 整树（或使用内置备份插件按计划备份，见 《NocoBase 2.2.29 常用 CLI 命令与工具详解》）。

⚠️ 注意：down 会移除运行实例但不动 storage 目录，数据始终在宿主侧；反之，删除部署目录前务必先确认已有有效备份。

六、环境变量表

以下为部署与运维高频环境变量（完整参数详解与实测验证见 《NocoBase 2.2.29 配置参数详解》；取值口径来源：官方文档「Environment Variables」，查询日期 2026-10-21）：

关键差异解读：官方 compose 模板只写了 7 个必填级变量（APP_KEY + 5 个 DB_* + TZ），其余全部走内置默认值即可工作；需要显式干预的通常只有 DB_POOL_MAX（并发上来后）与 TZ（国内环境建议显式设为 Asia/Shanghai）。

七、配置参数说明

compose 之外的配置分三层，按生效优先级从高到低：

1. 环境变量（compose environment: 或 env_file:）：部署层配置，改后需重建服务生效——docker compose up -d app（compose 检测到环境变化会自动重建，业务数据不受影响，实测见第九章升级流程）；
2. 运行期自动生成的 storage/nocobase.conf：实测为内置 Nginx 的站点配置（监听 80 并转发后端 13000，覆盖 /api/、/ws、/files/ 与上传文件鉴权等规则，关键行摘录见 《NocoBase 2.2.29 配置参数详解》 3.3 节），随发行版内置，日常不手改；
3. 数据库内的 UI 配置（配置即数据）：页面、区块、角色权限等在管理界面里配置，保存即生效并入库，随 storage 树一并备份。

💡 说明：NocoBase 没有大而全的静态配置文件，这是「配置即数据」架构的直接体现——运维侧只需管好环境变量这薄薄一层，其余配置全部在界面里完成且自动持久化。

八、配置文件挂载

本文方案用 bind mount 把宿主目录挂进应用与数据库：

• ./storage:/app/nocobase/storage：应用数据树（含 db/postgres 数据库目录、uploads 上传、logs 日志）；
• ./storage/db/postgres:/var/lib/postgresql/data：PostgreSQL 数据目录。

好处是备份直观（打包 storage/ 即全量）且权限排查方便；代价是要保证宿主目录属主与进程运行用户一致（首次启动会自动创建并赋权，无需手工干预）。若改用 named volume（如 nocobase-storage:/app/nocobase/storage），数据由 Docker 统一管理，备份需先经卷导出中转才能拿到文件，操作不如 bind mount 直观——团队自运维场景推荐本文的 bind mount 方案。

💡 技术拓展：数据持久化两种主流方式的取舍——

方式	优点	缺点
bind mount（宿主目录挂载）	路径透明、备份/rsync 直接可用	依赖宿主目录权限
named volume（命名卷）	由 Docker 统一管理、跨宿主迁移规范	备份需中转导出、路径不透明

本文实测采用 bind mount，理由是「打包 storage 树即完整备份」的运维直觉。

九、升级与回滚

升级主线（官方流程）：拉取新版发行物 → 重建应用服务 → 新版首启自动完成数据库迁移与插件升级。

cd /opt/nocobase
docker compose pull

实测回显（当前 latest 无上游更新时）：

 Image nocobase/nocobase:latest Pulling
 Image postgres:16 Pulling
 Image nocobase/nocobase:latest Pulled
 Image postgres:16 Pulled

确认升级目标版本后执行重建：

docker compose up -d

新版应用首次启动会自动执行 migrate 与插件升级（与 4.3 首次初始化同一入口，无需手工命令），升级后用版本接口复核：

curl -s http://127.0.0.1:8140/api/app:getInfo

实测回显（版本未更新场景，用于确认服务在升级检查后仍正常）：

{"data":{"database":{"dialect":"postgres"},"version":"2.2.29","lang":"en-US","name":"main","theme":"default"}}

回滚方法：把 compose 文件中 image: 的标签改回旧版本号后 docker compose up -d；若新版升级执行过数据库迁移，回滚前必须先恢复 storage/ 备份——这是「升级前先备份」成为硬性步骤的原因。升级操作清单：① 停写窗口内打包 storage/；② docker compose pull；③ docker compose up -d；④ 版本接口复核 + 页面登录抽测；⑤ 异常时按回滚流程恢复。

⚠️ 注意：使用 latest 标签意味着 pull 的目标随上游变化，生产环境建议把标签固定到具体版本号（如 nocobase/nocobase:2.2.29 形态，以 Docker Hub 标签页实际存在的版本为准），把「升级」从隐式变为显式动作。

十、常用运维命令

以下命令均在部署目录 /opt/nocobase 下执行，回显为实测（更完整的实例内 CLI 体系见 《NocoBase 2.2.29 常用 CLI 命令与工具详解》）：

docker compose ps                      # 两服务状态与端口映射
docker compose logs -f app             # 跟踪应用日志（Ctrl+C 退出）
docker compose logs --tail=50 app      # 最近 50 行
docker compose restart app             # 仅重启应用
docker compose stop / start            # 停止 / 启动（不移除实例与网络）
docker compose down                    # 停止并移除（storage 数据不受影响）
docker compose pull && docker compose up -d   # 升级

docker compose restart app 实测回显：

 Container nocobase-v229-app Restarting
 Container nocobase-v229-app Started

重启后复核版本接口返回 2.2.29 与 HTTP 200 即恢复正常（实测见第五章）。

十一、常见问题（FAQ）

Q1：启动后访问返回 502 或一直无响应？ 先看日志定位：docker compose logs --tail=100 app。实测经验按出现频率排序：① 数据库尚未就绪（应用有重试，等 30 秒再看）；② 宿主端口被占（compose up 阶段直接报错，换端口）；③ DB_* 与 postgres 服务的 POSTGRES_* 不一致导致认证失败——日志中会出现数据库连接错误，改齐后 docker compose up -d 重建。

Q2：忘记 admin 密码怎么办？ 有数据库访问条件时，用 PostgreSQL 客户端连接 storage/db/postgres（或网内 5432）后重置 users 表对应账号的密码字段（密码为加密存储，需按官方文档提供的重置方式生成新哈希）；更稳妥的路径是用另一管理员账号在界面里改密。日常预防：初始 admin123 登录后立即改密。

Q3：APP_KEY 变更后所有用户被登出？ 这是设计行为——APP_KEY 用于令牌加密，变更后旧令牌全部失效，重新登录即可。因此 APP_KEY 在首次部署时定好，之后不再变更；多实例共享同一数据库时也必须使用相同 APP_KEY。

Q4：8080/13000 端口已有服务占用？ 改 compose 中 ports: 左侧宿主端口即可（如 '8140:80'），应用内置 Nginx 固定监听 80，右侧不需要动。绑定前用 ss -ltn 确认目标端口空闲。

Q5：换数据库（PostgreSQL 改 MySQL）怎么做？ 新建一套部署（新 DB_DIALECT=mysql 与对应 MySQL 服务），用内置备份插件从旧实例导出、新实例导入；不支持直接改 DB_DIALECT 指向空库「原地切换」——业务数据与 UI 配置都在原库里。

十二、卸载与清理

cd /opt/nocobase
docker compose down        # 停止并移除运行实例与内网（实测回显见第五章 down 段）
rm -rf /opt/nocobase       # 确认无需保留数据后，删除部署目录（含全部数据）

若发行物不再使用，可回收下载占用：docker rmi nocobase/nocobase:latest postgres:16。至此服务器恢复到部署前状态。

十三、参考链接

• 官方部署文档（Docker Compose）：https://docs.nocobase.com/get-started/installation/docker-compose
• 官方环境变量文档：https://docs.nocobase.com/get-started/installation/env
• Docker Hub 官方发行页：https://hub.docker.com/r/nocobase/nocobase
• GitHub 仓库：https://github.com/nocobase/nocobase
• 本系列相关篇目：《NocoBase 介绍与选型指南》、《NocoBase 2.2.29 配置参数详解》、《NocoBase 2.2.29 常用 CLI 命令与工具详解》