NocoDB Quickstart Demo：内置 Postgres + Redis 的最小化 Docker Compose 生产部署实战

本文基于 NocoDB 官方示例 docker-compose/examples/quickstart-demo 展开，讲解如何用最少的容器编排把 NocoDB 以"生产形态"跑起来：内置 PostgreSQL 与 Redis、无反向代理、无 SSL，全部配置集中在一个 docker-compose.yml 中，docker compose up -d 即可开箱即用。读完后你将理解每个环境变量与服务的真实作用、健康检查驱动的启动依赖链、数据持久化卷的划分方式，以及如何安全替换演示密码并激活企业许可证。

一、定位：最小化"生产形态"配置

quickstart-demo 示例官方将其定义为 "The smallest production-shaped configuration"（最小的生产形态配置），其取舍非常明确：

• PostgreSQL：内置（bundled），数据持久化到命名卷 postgres_data；
• Redis：内置（bundled），数据持久化到命名卷 redis_data；
• 反向代理：无。NocoDB 直接监听 http://localhost:8080，不做 SSL 终结。

这意味着它不追求对外暴露的完整链路（对比同目录下的 traefik-custom-ssl、managed-postgres 等示例），而是把"应用 + 元数据库 + 缓存/任务队列"三件套收敛到一个网络内，适合作为自托管的起点模板——你在其上叠加代理、外部数据库或证书时，改动面最小。

二、完整的 docker-compose.yml 解析

示例的完整编排文件见 docker-compose.yml，共 4 个服务加 1 个 bridge 网络和 3 个命名卷：

services:

  nocodb:
    image: nocodb/nocodb:latest
    environment:
      NC_DB: 'pg://db:5432?u=nocodb&p=quickstart_demo_pw_change_me&d=nocodb'
      NC_REDIS_URL: 'redis://redis:6379'
      NC_SITE_URL: 'http://localhost:8080'
      NC_DISABLE_MUX: 'true'
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - nocodb_data:/usr/app/data
    networks:
      - nocodb-network
    ports:
      - '8080:8080'
    healthcheck:
      test: ['CMD-SHELL', 'wget -q --tries=1 --spider http://localhost:8080/api/v1/health || exit 1']
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s

  worker:
    image: nocodb/nocodb:latest
    environment:
      NC_DB: 'pg://db:5432?u=nocodb&p=quickstart_demo_pw_change_me&d=nocodb'
      NC_REDIS_URL: 'redis://redis:6379'
      NC_SITE_URL: 'http://localhost:8080'
      NC_WORKER_CONTAINER: 'true'
    depends_on:
      nocodb:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - nocodb_data:/usr/app/data
    networks:
      - nocodb-network

  db:
    image: postgres:17.10
    environment:
      POSTGRES_USER: nocodb
      POSTGRES_PASSWORD: quickstart_demo_pw_change_me
      POSTGRES_DB: nocodb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U nocodb -d nocodb']
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - nocodb-network

  redis:
    image: redis:7
    volumes:
      - redis_data:/data
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - nocodb-network

networks:
  nocodb-network:
    driver: bridge

volumes:
  nocodb_data:
  postgres_data:
  redis_data:

四个服务各司其职：

服务	镜像	职责
nocodb	nocodb/nocodb:latest	Web/API 主服务，对外暴露 8080 端口
worker	nocodb/nocodb:latest	后台任务消费者，不暴露端口，由 NC_WORKER_CONTAINER=true 区分角色
db	postgres:17.10	NocoDB 元数据库（存 schema、视图、权限等元信息）
redis	redis:7	缓存、WebSocket IO 与后台任务的公共通道

三、关键环境变量逐项说明

NC_DB：元数据库连接串

NC_DB: 'pg://db:5432?u=nocodb&p=quickstart_demo_pw_change_me&d=nocodb'

NocoDB 使用自有的紧凑 URI 格式描述数据库连接：pg://<host>:<port>?u=<user>&p=<password>&d=<database>。该格式在源码的本地开发脚本中同样被使用，例如 dockerRunPG.ts 中即写入 pg://localhost:5432?u=postgres&p=password&d=${metaDb}，与示例中的写法完全一致。host=db 指向同一 compose 网络内的 Postgres 服务，无需公网可达。

NC_REDIS_URL 与 worker 容器的强绑定

NC_REDIS_URL: 'redis://redis:6379'

nocodb 与 worker 两个容器必须共享同一个 Redis，这是 worker 架构成立的前提。从源码 Noco.ts 可以看到硬性校验：

if (process.env.NC_WORKER_CONTAINER === 'true') {
  if (!getRedisURL()) {
    throw new Error('NC_REDIS_URL is required');
  }
  process.env.NC_DISABLE_TELE = 'true';
}

即：一旦声明自己是 worker 容器，缺少 NC_REDIS_URL 会直接抛错终止启动，同时强制关闭 TELE（前端资源服务）——worker 不需要提供前端页面。此外 worker 还会跳过数据同步初始化，Noco.ts 中仅在 NC_WORKER_CONTAINER !== 'true' 时才执行 DataReflection.init()；后台任务的 Redis 消费逻辑也依据该变量分流，见 jobs-redis.ts 与 jobs.service.ts。这解释了为什么示例中 worker 服务与 nocodb 服务挂载同一个 nocodb_data 卷并使用相同镜像——它们是同一应用的两种运行模式。

NC_SITE_URL

NC_SITE_URL: 'http://localhost:8080'

告知 NocoDB 自身的对外访问地址，用于生成分享链接、邮件中的 URL 等。示例中无代理、无 SSL，直接是本机 8080。

NC_DISABLE_MUX

NC_DISABLE_MUX: 'true'

官方 Helm Chart 中对同一变量有明确说明：values.yaml 注释为 "Set NC_DISABLE_MUX=true (recommended for self-hosted)"，即自托管部署推荐开启。同仓库的其他 compose 示例（managed-postgres/docker.env、traefik-custom-ssl/docker.env 等）也一致设置 NC_DISABLE_MUX=true，quickstart-demo 遵循同一约定。

四、启动依赖链：healthcheck 驱动的编排

示例没有使用 start_period 之外的 sleep 或 retry 脚本，而是用"健康检查 + 条件依赖"编排启动顺序：

1. db 以 pg_isready -U nocodb -d nocodb 检查就绪（每 10s 一次）；
2. redis 以 redis-cli ping 检查就绪；
3. nocodb 声明 depends_on: db / redis, condition: service_healthy，二者未健康前不会启动；
4. nocodb 自身用 wget --spider http://localhost:8080/api/v1/health 做健康检查（每 30s，启动宽限期 30s）；
5. worker 再依赖 nocodb 的 service_healthy。

由此形成 db/redis → nocodb → worker 的严格启动链，任何一环不健康，后续容器不会盲目拉起，避免连接风暴。/api/v1/health 端点由主服务提供，Noco.ts 中对根路由的处理也保证非浏览器请求（如健康探测）返回 200。

五、数据持久化：三个命名卷

卷	挂载点	内容
nocodb_data	/usr/app/data	附件、导入导出等应用数据（nocodb 与 worker 共享挂载）
postgres_data	/var/lib/postgresql/data	PostgreSQL 数据目录（NocoDB 元数据库）
redis_data	/data	Redis 持久化目录

使用命名卷（而非绑定挂载）意味着数据落在 Docker 管理的存储中，docker compose down（不带 -v）不会丢失数据；restart: unless-stopped 则保证宿主重启后所有容器自动恢复。镜像入口由 start.sh 触发（node docker/main.js），/usr/app/data 即容器内应用数据目录。

六、运行步骤

按照 README 的操作方式：

cp -r docker-compose/examples/quickstart-demo ./my-deployment
cd my-deployment
docker compose up -d

由于全部值都在 docker-compose.yml 里（不依赖额外的 .env 文件），复制后即可直接 up -d，无需任何前置配置。启动完成后访问 http://localhost:8080 即为 NocoDB 界面。

演示密码警告（必读）

compose 文件使用了硬编码演示密码 quickstart_demo_pw_change_me，目的是让示例开箱即用。官方 README 明确要求：在任何真实使用场景下，替换 docker-compose.yml 中出现它的三处位置：

1. db 服务的 POSTGRES_PASSWORD；
2. nocodb 服务的 NC_DB 连接串中的 p= 参数；
3. worker 服务的 NC_DB 连接串中的 p= 参数。

三处必须保持一致，否则应用与 worker 将无法通过元数据库认证。

七、激活企业许可证

该示例同时满足 NocoDB 激活企业许可证的前提条件（必须使用 PostgreSQL，本示例正好是 bundled Postgres）：

1. NocoDB 启动后访问 http://localhost:8080；
2. 注册第一个用户——首位用户自动成为超级管理员（super admin）；
3. 进入 Admin Panel → License，粘贴许可证密钥完成激活。

八、小结

quickstart-demo 的价值在于用一份文件演示了 NocoDB 自托管的"最小生产骨架"：app/worker 双容器同镜像靠 NC_WORKER_CONTAINER 区分角色（源码见 Noco.ts）、Redis 作为缓存与任务队列的共享通道（worker 模式下 NC_REDIS_URL 为强制项）、健康检查驱动的四容器启动链、以及三类数据各自的命名卷持久化。掌握这个模板后，升级到带 SSL 的反向代理（traefik-custom-ssl 示例）或接入外部托管 Postgres（managed-postgres 示例）都只是在该骨架上做增量替换。