NocoDB Docker Compose 部署示例全解析：五种生产形态的选型、配置与源码印证

本文基于 NocoDB 仓库中 docker-compose/examples/ 目录的五套预构建部署配置（索引文档），逐一解析 quickstart-demo、managed-postgres、external-postgres-and-redis、traefik-custom-ssl 与 postgres-private-ca 各方案的适用场景、需要替换的占位符、关键环境变量与 db.json 数据库连接配置，并结合 NocoDB 服务端源码印证 worker 容器与健康检查的实际工作原理。读完本文，你可以根据自身的数据库与证书约束，直接复制对应示例目录完成可运行的 NocoDB 部署，并理解配置项在源码层面如何被解析。

五种部署形态的选型速查

官方文档 docker-compose/examples/README.md 明确说明：这些示例是预构建的部署配置，适合希望获得细粒度控制或有特定基础设施约束的场景。如果你的需求更简单，可以直接运行上一级目录的交互式向导 setup.sh 生成配置；而当你需要精确控制每个参数时，复制对应示例目录作为起点是更稳妥的做法。

五套示例在 PostgreSQL、Redis 与反向代理三个维度上的组合差异如下：

示例	PostgreSQL	Redis	Proxy	适用场景
quickstart-demo	内置（Bundled）	内置	无（端口 8080）	本地评估 / "让我看看 NocoDB"
managed-postgres	外部托管（RDS/Azure/Cloud SQL）	外部	无（端口 8080）	置于自有负载均衡器之后的生产环境
external-postgres-and-redis	外部自管	外部	无（端口 8080）	最小化 Docker 资源占用
traefik-custom-ssl	外部托管	外部	Traefik + 自定义 TLS 证书	使用自有 SSL 证书的生产环境
postgres-private-ca	外部（私有 CA）	外部	Traefik + Let's Encrypt	私有云 / 本地机房数据库

选型时可以先问自己两个问题：数据库和 Redis 是否需要容器外托管？前端是否需要 SSL 终结？前者决定选 bundled 还是 external 系列，后者决定是否需要 Traefik 两个示例之一。

快速上手：复制示例并启动

所有示例的统一操作范式是"复制目录 → 替换占位符 → docker compose up -d"。以最简单的 quickstart-demo 为例：

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

对于生产形态的示例（managed-postgres 及其同类），官方文档强调在运行 docker compose up -d 之前，必须先编辑三个文件来替换占位符：

1. docker-compose.yml — 如需更换宿主侧端口、域名路由等；
2. docker.env — 替换 your-redis-host 等 Redis 连接占位符，以及站点公开 URL；
3. nocodb/db.json — 填入数据库 host、账号、密码，并把 CHANGE_ME_db_password 之类的占位值全部替换。

需要特别注意的占位符包括 CHANGE_ME_db_password、your-managed-db-host、your-redis-host 等。唯一的例外是 quickstart-demo：它内置了确定性的演示密码 quickstart_demo_pw_change_me 以保证开箱即用，但文档明确警告在真实使用前必须替换它——该密码在 quickstart-demo 的 docker-compose.yml 中共出现三处：db 服务的 POSTGRES_PASSWORD，以及 nocodb 和 worker 两个服务 NC_DB 连接串中的 p= 参数。

quickstart-demo：最小生产形态的完整解剖

quickstart-demo 是"最小生产形态"（the smallest production-shaped configuration）：内置 PostgreSQL 与 Redis，无反向代理、无 SSL，NocoDB 监听 http://localhost:8080。其 docker-compose.yml 定义了四个服务，全部值都写在 compose 文件内，无需额外配置即可启动：

• nocodb：主服务容器，通过 NC_DB: 'pg://db:5432?u=nocodb&p=quickstart_demo_pw_change_me&d=nocodb' 连接名为 db 的 Postgres 容器，等待 db 与 redis 均通过 healthcheck 后才启动；
• worker：与 nocodb 共用同一镜像，但额外注入 NC_WORKER_CONTAINER: 'true'，且 depends_on.nocodb.condition: service_healthy，即等待主容器健康后再启动；
• db：postgres:17.10，通过 pg_isready -U nocodb -d nocodb 做健康检查，数据持久化到命名卷 postgres_data；
• redis：redis:7，通过 redis-cli ping 做健康检查，数据持久化到 redis_data 卷。

主服务的健康检查值得注意，它出现在所有示例中且完全一致：

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

这里的 /api/v1/health 端点在源码中真实存在，定义于 utils.controller.ts，由 @Get('/api/v1/health') 路由声明。也就是说 worker 容器"等 nocodb 健康后再启动"的依赖链（condition: service_healthy）最终由这个 GET 端点的可达性驱动。

NC_WORKER_CONTAINER 在源码中的实际作用

quickstart-demo 与 external 系列示例中，worker 服务都通过 NC_WORKER_CONTAINER: 'true' 与主服务区分角色。从源码结构看，这个环境变量是 NocoDB 拆分"Web 服务"与"后台 Worker"两种运行模式的开关：

• 在 Noco.ts 中，process.env.NC_WORKER_CONTAINER === 'true' 的分支决定了以 worker 模式启动（第 192 行），而非 worker 的分支执行常规 Web 初始化（第 265 行附近）；
• 在 use-worker.decorator.ts 中，装饰器逻辑是 if (process.env.NC_WORKER_CONTAINER !== 'false') return descriptor;——即控制器方法是否被 worker 接管取决于该变量的取值；
• auth.module.ts 中，worker 容器不会注册 AuthController：...(process.env.NC_WORKER_CONTAINER !== 'true' ? [AuthController] : [])，说明 worker 不承担面向用户的认证请求；
• RedisCacheMgr.ts 中同样以 NC_WORKER_CONTAINER !== 'true' 作为缓存行为分支条件。

因此所有示例里"nocodb + worker 双容器、共享 nocodb_data 卷"的编排模式，对应的是 NocoDB 将长耗时后台任务从 Web 请求路径中剥离的架构设计：主容器处理 API，worker 容器消费异步任务，两者通过共享数据卷和 Redis 协作。这也解释了为什么 traefik-custom-ssl 文档 中给出的水平扩容建议只针对 nocodb 服务的 deploy.replicas 做调整。

managed-postgres：托管数据库 + SSL + 外部 Redis

managed-postgres 面向使用 AWS RDS、Azure Database、Google Cloud SQL 这类公共 CA 托管数据库的团队。它的服务拓扑与 quickstart-demo 相同（nocodb + worker 双容器、共享卷、healthcheck），但 PostgreSQL 和 Redis 全部在 Docker 之外。

docker.env：环境变量清单

该示例把环境配置抽到了 docker.env 文件（通过 compose 的 env_file 引入），内容完整如下，可作为生产环境变量模板：

# Database
NC_DB_JSON_FILE=/usr/app/data/db.json

# Redis
NC_REDIS_URL=redis://your-redis-host:6379

# Public URL (email links, webhooks, OAuth redirects). Set to your public-facing URL.
NC_SITE_URL=https://nocodb.example.com

# Settings
NC_SECURE_ATTACHMENTS=true
NC_DISABLE_MUX=true

各变量含义：

变量	作用	示例中的取值
NC_DB_JSON_FILE	指向数据库连接配置文件，替代 NC_DB 连接串	/usr/app/data/db.json
NC_REDIS_URL	Redis 连接串	redis://your-redis-host:6379
NC_SITE_URL	站点公开 URL，用于邮件链接、webhook、OAuth 重定向	https://nocodb.example.com
NC_SECURE_ATTACHMENTS	附件安全存储开关	true
NC_DISABLE_MUX	关闭 Mux 遥测	true

这里体现了两种数据库接入方式的分工：quickstart-demo 用 NC_DB 连接串（pg://host:port?u=...&p=...&d=...），而所有 external 系列示例统一改用 NC_DB_JSON_FILE 指向挂载的 db.json 文件。后者能表达更丰富的连接属性（如 SSL 配置），是生产部署的推荐形态。

db.json：托管数据库的 SSL 配置

managed-postgres/nocodb/db.json 的完整内容：

{
  "client": "pg",
  "connection": {
    "host": "your-managed-db-host.rds.amazonaws.com",
    "port": "5432",
    "user": "nocodb",
    "password": "CHANGE_ME_db_password",
    "database": "nocodb",
    "ssl": {
      "rejectUnauthorized": true
    }
  }
}

ssl.rejectUnauthorized: true 表示 NocoDB 会用公共受信 CA 链校验数据库证书的合法性，这与 RDS、Azure、Cloud SQL 这类使用公网可信证书的托管数据库天然兼容。文档给出的标准操作流程是：

cp -r examples/managed-postgres ./my-deployment
cd my-deployment
# Edit docker.env: set NC_REDIS_URL
# Edit nocodb/db.json: set your database host, credentials, and port
docker compose up -d

置于负载均衡器之后

managed-postgres 不内置反向代理，NocoDB 直接暴露 8080 端口，官方建议在 ALB、Nginx 等反向代理之后转发流量到 8080。如需更换宿主侧端口，修改 docker-compose.yml 即可：

ports:
  - '3000:8080'  # expose on port 3000 instead

external-postgres-and-redis：最小化容器占用

external-postgres-and-redis 与 managed-postgres 的 compose 文件结构完全一致（同样的 nocodb + worker 双容器、env_file: docker.env、healthcheck 与共享卷），区别在于定位：它面向"自管 Postgres + Redis 跑在专用主机上"或"某个 Postgres 托管服务不完全适配 managed-postgres 预设"的场景。此时 Docker 内只运行 NocoDB 与一个 worker 容器，是全部示例中 Docker 足迹最小的方案。

其 db.json 与 managed-postgres 相同，同样默认 ssl.rejectUnauthorized: true。文档对 SSL 的指引是二选一：

• 外部 Postgres 使用公共受信 CA → 保持默认 ssl.rejectUnauthorized: true；
• 使用自签名或私有 CA → 改用 postgres-private-ca 示例。

traefik-custom-ssl：自带 TLS 证书的生产部署

traefik-custom-ssl 是五个示例中唯一内置反向代理且使用自有证书的方案：Traefik v3.6 用你自己的证书（企业证书、泛域名证书等）终结 TLS，PostgreSQL 与 Redis 均外部化。

证书文件布局与操作

证书链与私钥放在部署目录的 certs/ 下：

文件	内容
certs/cert.pem	完整证书链（服务器证书 + 中间证书）
certs/key.pem	私钥

标准操作流程：

cp -r examples/traefik-custom-ssl ./my-deployment
cd my-deployment

# Place your TLS certificate and key
mkdir -p certs
cp /path/to/cert.pem certs/cert.pem
cp /path/to/key.pem certs/key.pem

# Edit docker.env: set NC_REDIS_URL
# Edit nocodb/db.json: set your database host and credentials
# Edit docker-compose.yml: replace nocodb.example.com with your domain
docker compose up -d

Traefik 的路由与 TLS 配置

该示例的 docker-compose.yml 中，nocodb 服务通过一组 labels 接入 Traefik：

labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.nocodb.rule=Host(`nocodb.example.com`)'
  - 'traefik.http.routers.nocodb.entrypoints=websecure'
  - 'traefik.http.routers.nocodb.tls=true'

Traefik 容器以 --providers.docker.exposedbydefault=false 启动（只有显式 traefik.enable=true 的服务才会被暴露，其余 worker 服务因此不会出现在路由中），并做了 80 → 443 的强制 HTTPS 跳转：

command:
  - '--providers.docker=true'
  - '--providers.docker.exposedbydefault=false'
  - '--providers.file.filename=/etc/traefik/certs.yml'
  - '--entryPoints.web.address=:80'
  - '--entryPoints.websecure.address=:443'
  - '--entryPoints.web.http.redirections.entryPoint.to=websecure'
  - '--entryPoints.web.http.redirections.entryPoint.scheme=https'

证书本身由挂载的 certs.yml 声明，内容只有三行，指向容器内 /etc/traefik/certs/ 路径（对应宿主机的 ./certs 目录只读挂载）：

tls:
  certificates:
    - certFile: /etc/traefik/certs/cert.pem
      keyFile: /etc/traefik/certs/key.pem

如果需要为多个域名配置多张证书，向 certs.yml 追加条目即可（官方文档给出的多证书写法）：

tls:
  certificates:
    - certFile: /etc/traefik/certs/cert.pem
      keyFile: /etc/traefik/certs/key.pem
    - certFile: /etc/traefik/certs/other-cert.pem
      keyFile: /etc/traefik/certs/other-key.pem

水平扩容

由于数据库与 Redis 全部外部化，NocoDB 本身无状态，可水平扩容。官方文档给出的改法是把 nocodb 服务的 deploy 段改为：

deploy:
  mode: replicated
  replicas: 3

docker.env 与 managed-postgres 的 完全同构（NC_DB_JSON_FILE、NC_REDIS_URL、NC_SITE_URL、NC_SECURE_ATTACHMENTS、NC_DISABLE_MUX 五项）。

postgres-private-ca：私有 CA 数据库的 SSL 接入

postgres-private-ca 解决一个特定难题：本地机房或私有云中的数据库使用私有 / 自签名 CA 证书，NocoDB 默认无法通过 rejectUnauthorized: true 的证书校验。

db.json 中的 CA 内嵌写法

与 managed-postgres 的差异集中在 db.json：在 ssl 块中除 rejectUnauthorized: true 外，额外用 ca 字段把私有 CA 证书以单行字符串（换行用 \n 转义）内嵌：

{
  "client": "pg",
  "connection": {
    "host": "your-private-db-host.internal",
    "port": "5432",
    "user": "nocodb",
    "password": "CHANGE_ME_db_password",
    "database": "nocodb",
    "ssl": {
      "rejectUnauthorized": true,
      "ca": "-----BEGIN CERTIFICATE-----\nPASTE_YOUR_CA_PEM_HERE_AS_ONE_LINE\n-----END CERTIFICATE-----"
    }
  }
}

文档提供了把 PEM 证书转换为一行的现成命令：

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' your-ca.pem

把输出粘贴为 db.json 中 ca 的值即可。

其余配置

该示例同时内置 Traefik 作为前端代理，但 TLS 用的是 Let's Encrypt 自动 HTTPS（而非自定义证书），因此操作流程比 traefik-custom-ssl 多两步编辑：把 docker-compose.yml 中的 nocodb.example.com 换成你的域名、[e-mail] 换成你的邮箱（用于 ACME 注册），再加上 docker.env 的 Redis 与 db.json 的数据库配置。

激活 License

官方文档 docker-compose/examples/README.md 指出：堆栈启动后，打开 NocoDB，以第一个用户身份注册（成为 super admin），然后在 Admin Panel → License 激活 License。前置条件是必须使用 PostgreSQL 才能激活 License——五个示例全部满足这一要求（bundled 或 external 都是 Postgres）。quickstart-demo 的 README 也给出了同样的企业版 License 激活路径说明。

小结：按约束条件选配置

把五个示例压缩成一张决策路径：

1. 本地快速体验 → quickstart-demo，唯一要求是真实使用前替换三处演示密码；
2. 数据库是云上托管服务（RDS/Cloud SQL/Azure） → managed-postgres，db.json 保持 rejectUnauthorized: true 即可；
3. 数据库与 Redis 都是自有主机、追求最小容器占用 → external-postgres-and-redis；
4. 需要前端 HTTPS 且证书自持（企业 CA / 泛域名） → traefik-custom-ssl，把证书链与私钥放入 certs/；
5. 私有云 / 机房数据库使用私有 CA → postgres-private-ca，用 awk 命令把 CA 证书压成单行填入 db.json 的 ssl.ca。

所有示例共享同一套服务骨架（nocodb 主容器 + NC_WORKER_CONTAINER: 'true' 的 worker 容器 + /api/v1/health 健康检查 + 共享 nocodb_data 卷），该骨架与 NocoDB 源码中 NC_WORKER_CONTAINER 的角色判定逻辑一一对应，因此在任一示例上做端口、域名、副本数的局部调整都是安全且可预测的。