NocoDB 自托管部署实战：Docker、PostgreSQL 与 Auto-upstall 一键生产环境搭建

本文基于 NocoDB 官方仓库中的土耳其语 README（markdown/readme/languages/turkish.md）整理，完整覆盖 NocoDB 的三种主流自托管安装方式：Docker + SQLite、Docker + PostgreSQL，以及面向生产环境的 Auto-upstall 一键安装脚本。读完本篇后，你可以独立完成从本地快速验证到带 HTTPS、Traefik 网关的生产部署，并结合仓库内源码理解 NC_DB、NC_AUTH_JWT_SECRET 等关键环境变量在 NocoDB 配置体系中的实际作用。

一、NocoDB 是什么：定位与核心价值

NocoDB 定位为"开源的 Airtable 替代品"，是快速搭建在线数据库的最便捷方式之一。其设计出发点在官方 README 中阐述得比较清楚：

• 大量互联网创业团队要么依赖电子表格、要么直接操作数据库；表格虽然易用（每天被十亿以上用户使用），但在处理能力上远不如数据库；
• 而用 SaaS 表格方案替代数据库，又会带来访问控制不足、供应商锁定、数据被"圈养"、价格突变等问题；
• NocoDB 的使命是面向全球互联网创业团队，提供功能最强大的开源无代码（no-code）数据库界面。

功能层面，官方 README 将其核心能力归纳为三大类，这里完整继承原文档的描述：

1. 富电子表格界面（Zengin E-Tablo Arayüzü）

• 基础 CRUD：表、列、行的创建、读取、更新与删除；
• 数据操作：排序、过滤、分组、列的隐藏/显示；
• 多视图类型：网格（默认）、画廊、表单、看板（Kanban）与日历视图；
• 视图权限类型：协作视图与锁定视图；
• 分享选项：公开或私有（密码保护）；
• 丰富的数据类型：ID、Link、Lookup、Rollup、单行文本、文件附件、货币、公式、用户等；
• 基于角色的访问控制（RBAC）：多层级细粒度权限控制。

2. 应用商店（工作流自动化集成）

提供三大类集成：

• 聊天：Slack、Discord、Mattermost 等；
• 邮件：AWS SES、SMTP、MailerSend 等；
• 存储：AWS S3、Google Cloud Storage、Minio 等。

3. 程序化访问

用户可通过以下途径以编程方式触发操作，请求使用 token（JWT 或社交登录认证）授权：

• REST API；
• NocoDB SDK（仓库中对应 packages/nocodb-sdk 与 packages/nocodb-sdk-v2 两个包）。

此外，该实例采用 AGPLv3 协议开源（见 LICENSE.md）。

二、安装方式一：Docker + SQLite（单容器最快起步）

这是最轻量的本地验证方式，一条命令即可运行：

docker run -d \
  --name noco \
  -v "$(pwd)"/nocodb:/usr/app/data/ \
  -p 8080:8080 \
  nocodb/nocodb:latest

参数说明：

参数	作用
-v "$(pwd)"/nocodb:/usr/app/data/	将当前目录下的 nocodb 文件夹挂载为容器数据目录，元数据库（默认 SQLite 文件 noco.db）会持久化在宿主机上
-p 8080:8080	暴露 8080 端口，与容器内默认监听端口一致
nocodb/nocodb:latest	官方镜像

从源码可以印证 SQLite 是默认元数据库：NcConfig 中的 meta.db 初始值即为 { client: DriverClient.SQLITE, connection: { filename: 'noco.db' } }，且该文件路径会拼接 NC_APP_DATA_DIR/NC_TOOL_DIR 环境变量所指目录（见 helpers.ts 的 getToolDir()）。因此将宿主机目录挂载到 /usr/app/data 即可让 SQLite 文件落在卷内，实现数据持久化。

本地运行时通过 http://localhost:8080/dashboard 访问管理面板。

三、安装方式二：Docker + PostgreSQL（推荐用于多用户/生产场景）

将元数据库指向外部 PostgreSQL，需要额外传入两个环境变量：

docker run -d \
  --name noco \
  -v "$(pwd)"/nocodb:/usr/app/data/ \
  -p 8080:8080 \
  -e NC_DB="pg://host.docker.internal:5432?u=root&p=password&d=d1" \
  -e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
  nocodb/nocodb:latest

两个关键环境变量的源码级解读：

3.1 NC_DB：元数据库连接串

NC_DB 采用 NocoDB 自定义的 URL 语法 协议://host:port?u=用户&p=密码&d=数据库。解析逻辑位于 packages/nocodb/src/utils/nc-config/helpers.ts：

• jdbcToXcConfig() 会借助 parse-database-url 解析连接串，并依据 driver 映射到对应的客户端（如 pg）与默认端口；
• NcConfig.create() 支持三种元数据库配置来源，优先级为：NC_DB（URL）→ NC_DB_JSON（内联 JSON）→ NC_DB_JSON_FILE（JSON 文件），见 NcConfig.ts；
• 对 pg 客户端，若连接串未显式指定 SSL 配置且主机不在白名单中，源码会自动补上 ssl: true（helpers.ts）。生产环境对接托管数据库时建议显式指定 SSL 参数。

host.docker.internal 是 Docker 官方提供的指向宿主机的 DNS 名称，适用于宿主机上直接运行 PostgreSQL 的场景。

3.2 NC_AUTH_JWT_SECRET：JWT 签名密钥

该变量用于签发/校验会话 token。在 NcConfig.ts 中被读入 ncConfig.auth.jwt.secret。此外源码中还有一处强依赖：元数据库中的敏感字段（如数据源凭据）使用该密钥进行加解密，见 version-upgrader/upgraders/0225002_ncDatasourceDecrypt.ts。因此该密钥必须固定不变——一旦更换，已存储的加密数据将无法还原，会话也会全部失效。示例中的 UUID 仅用于演示，实际部署请自行生成强随机值。

四、安装方式三：Auto-upstall（生产环境一键安装）

官方 README 对 Auto-upstall 的原文定位是："一条为生产环境准备 NocoDB 的命令，会在后台自动为你生成 docker-compose 文件"。其执行命令为：

bash <(curl -sSL http://install.nocodb.com/noco.sh) <(mktemp)

README 列出的四项能力：

• 自动安装 Docker、Docker Compose 等全部前置依赖；
• 通过 Docker Compose 自动部署 NocoDB + PostgreSQL + Redis + Traefik 网关；
• 重复执行命令即可自动升级到最新版本；
• 自动安装并续期 SSL 证书（安装过程中需输入域名或子域名）。

4.1 脚本真实位置与本地运行方式

该脚本就存放在仓库内：docker-compose/1_Auto_Upstall/noco.sh。如果已克隆仓库，也可以直接通过薄包装脚本运行：

cd nocodb/docker-compose && ./setup.sh

docker-compose/setup.sh 仅执行 exec bash .../1_Auto_Upstall/noco.sh "$@"，两个入口完全等价。

4.2 安装模式判定逻辑

从 noco.sh 的 determine_mode() 源码看，脚本按输入域名自动选择三种模式之一：

模式	触发条件	结果
local	域名为空或 localhost	端口 8080，无 SSL
production	合法域名（正则校验）	Traefik + Let's Encrypt 自动签发 HTTPS
production-ip	输入的是 IP	端口 80 直连，明文 HTTP，无 SSL

前置检查包括：Docker 与 Compose V2 插件、curl 是否可用（check_prereqs()）；SELinux Enforcing 环境会自动为 bind mount 追加 :Z 后缀（check_selinux()）；生产模式会检查 80/443 端口占用（check_ports()）。

4.3 交互式问答与关键参数

安装向导依次询问（源码 noco.sh）：

1. 域名：默认自动探测公网 IP，留空则进入本地模式；
2. Postgres：选择内置（Bundled，脚本自动生成 24 位强随机密码）或已有实例（需输入 host/port/库名/用户/密码，并选择 SSL 模式：托管数据库公共 CA、自定义 CA 证书文件、或无 SSL）；
3. Redis：内置或已有实例（提供 redis://host:6379 形式 URL）；
4. Let's Encrypt 邮箱：仅生产模式必需。

4.4 生成的文件清单

执行完成后，当前目录下生成 ./nocodb/ 部署目录：

./nocodb/
├── docker-compose.yml      # nocodb + worker + (内置 db/redis) + (可选 traefik)
├── docker.env              # NC_DB_JSON_FILE、NC_REDIS_URL、NC_SECURE_ATTACHMENTS、NC_SITE_URL 等
├── nocodb/db.json          # knex 格式数据库连接配置，支持内联自定义 CA
├── update.sh               # docker compose pull && up -d && image prune
└── .gitignore              # 排除密钥与运行时数据

几个值得注意的实现细节（均可在 noco.sh 中逐行核对）：

• 凭据文件安全：脚本以 umask 077 创建文件，并将 docker.env 与 nocodb/db.json 收权为 600（tighten_perms()），防止凭据泄露；
• 元数据接入方式：生成的 docker.env 使用 NC_DB_JSON_FILE=/usr/app/data/db.json 而非 NC_DB URL——这对应第三节提到的 NcConfig 三种配置来源之一；db.json 会被 bind-mount 到容器内，与数据卷分离，实现"配置与数据解耦"（见 Auto-Upstall README）；
• 服务编排：nocodb 主服务带 GET /api/v1/health 健康检查（30s 间隔、30s 启动宽限期），worker 服务以 NC_WORKER_CONTAINER=true 启动并依赖主服务健康后再启动；
• SSL：生产模式下生成 Traefik v3.6 服务，配置 Let's Encrypt HTTP-01 挑战、80→443 强制跳转。

4.5 非交互模式与常用参数

CI/自动化场景可使用标志位跳过所有提问，缺失必填项时会快速失败而不是挂起在提示符上：

bash <(curl -sSL http://install.nocodb.com/noco.sh) \
  --non-interactive \
  --domain=nocodb.example.com \
  --acme-email=[e-mail] \
  --pg=bundled --redis=bundled

常用标志位（源自 noco.sh 的 --help 输出）：

标志	说明
--quick	内置 Postgres + Redis 的本地快速安装（端口 8080），可与 --domain= 组合获得生产 HTTPS
--domain=HOST	指定域名或 IP；隐含启用非交互模式
--acme-email=EMAIL	Let's Encrypt 邮箱，生产模式必填
--image-tag=TAG	固定 nocodb/nocodb 镜像 tag，默认 latest
--pg=bundled|external	内置/外部 Postgres
--pg-host= / --pg-port= / --pg-database= / --pg-user= / --pg-password=	外部 Postgres 连接参数
--pg-ssl=managed|none|/path/to/ca.pem	外部 Postgres SSL 模式
--redis=bundled|external、--redis-url=URL	Redis 配置

生产环境建议通过 --image-tag= 固定版本，避免 latest 漂移。

4.6 仓库内的等价编排示例

仓库还提供了现成的 compose 文件可对照参考：

• docker-compose/1_Auto_Upstall/docker-compose.yml：本地快速评估栈，包含 nocodb、worker、db（postgres:17.10）、redis（redis:7）四个服务，全部带健康检查，docker compose up -d 后访问 http://localhost:8080；
• docker-compose/examples/external-postgres-and-redis：外部 Postgres + Redis 示例；
• docker-compose/examples/managed-postgres、docker-compose/examples/postgres-private-ca：托管数据库及私有 CA 证书示例；
• docker-compose/examples/traefik-custom-ssl：Traefik 自定义 SSL 证书示例。

五、其他安装方式：平台二进制（仅限本地快速测试）

官方 README 明确提示："二进制文件仅用于本地环境的快速测试目的"。完整命令表如下：

安装方式	安装命令
MacOS arm64（二进制）	curl http://get.nocodb.com/macos-arm64 -o nocodb -L && chmod +x nocodb && ./nocodb
MacOS x64（二进制）	curl http://get.nocodb.com/macos-x64 -o nocodb -L && chmod +x nocodb && ./nocodb
Linux arm64（二进制）	curl http://get.nocodb.com/linux-arm64 -o nocodb -L && chmod +x nocodb && ./nocodb
Linux x64（二进制）	curl http://get.nocodb.com/linux-x64 -o nocodb -L && chmod +x nocodb && ./nocodb
Windows arm64（二进制）	iwr http://get.nocodb.com/win-arm64.exe -OutFile Noco-win-arm64.exe && .\Noco-win-arm64.exe
Windows x64（二进制）	iwr http://get.nocodb.com/win-x64.exe -OutFile Noco-win-x64.exe && .\Noco-win-x64.exe

无论哪种方式，本地启动后均通过 http://localhost:8080/dashboard 访问。

六、部署后的日常运维

Auto-upstall 生成的部署目录同时给出了管理命令（见脚本 display_completion() 输出）：

cd nocodb
docker compose logs -f nocodb   # 跟踪启动日志
docker compose ps               # 查看容器状态
docker compose down             # 停止（数据保留在命名卷中）

升级则执行生成的 ./update.sh（等价于 docker compose pull && docker compose up -d && docker image prune -f）。数据存放在 Docker 命名卷 nocodb_data、postgres_data、redis_data 中，down 不会删除数据；密钥类文件（docker.env、nocodb/db.json）已被 .gitignore 排除，切勿提交到版本库。

七、小结

NocoDB 的自托管路径可按环境复杂度三档选择：

1. 验证/演示：单容器 + SQLite，一条 docker run；
2. 团队使用：外部 PostgreSQL + 固定 NC_AUTH_JWT_SECRET 的 Docker 部署，元数据持久化且会话密钥可控；
3. 生产环境：Auto-upstall 一键生成带 Traefik、Let's Encrypt、worker 拆分与健康检查依赖的完整 compose 栈，重复运行即可升级。

理解 NC_DB / NC_DB_JSON_FILE / NC_AUTH_JWT_SECRET 这三个变量在 NcConfig 中的落地方式后，你就能对任意部署方案做二次定制，并安全地管理密钥与数据卷。更多安装细节可参考仓库内 docker-compose/1_Auto_Upstall/README.md 与 docker-compose/examples 目录。