NocoDB 自托管实战指南：Docker/二进制快速部署与 NC_DB 元数据库配置深度解析

本文以 NocoDB 后端包 packages/nocodb/README.md 为主体，完整覆盖官方 Quick Try 的三种部署方式（Docker、平台二进制、Docker Compose），并结合当前仓库源码深入解析 NC_DB、NC_AUTH_JWT_SECRET 等生产环境变量的解析链路、默认值与底层行为，帮助你在几分钟内跑起一个 NocoDB 实例，并理解其元数据库（meta database）配置在源码中的真实落地过程。

一、文档定位：packages/nocodb 是什么

packages/nocodb 是 NocoDB 的后端包（NestJS 应用），package.json 中声明 "name": "nocodb"、"description": "NocoDB Backend"，主入口为 dist/bundle.js。README 面向的使用场景是：免费且可自托管（Free & Self-hostable）的 Airtable 替代品——把已有数据库表包装成电子表格界面，提供多视图、权限控制与 REST API。

阅读本 README 前需要知道两条事实性前提（均来自当前仓库）：

• 元数据（工作区、数据源、表结构定义等）默认存储在 SQLite 中，文件为 noco.db，可通过环境变量切换为 PostgreSQL/MySQL 等；
• 当前仓库后端包的 engines 要求 node >= 22（见 package.json）。README 顶部的 node >= 16.14.0 徽章属于历史遗留，开发环境请以 package.json 为准。

二、Quick Try：三种快速上手方式

2.1 Docker 方式（README 主推路径）

README 提供了两个最简命令，分别对应 SQLite 元数据库与 PostgreSQL 元数据库：

# 使用 SQLite 作为元数据库
docker run -d --name nocodb \
-v "$(pwd)"/nocodb:/usr/app/data/ \
-p 8080:8080 \
nocodb/nocodb:latest

# 使用 PostgreSQL 作为元数据库
docker run -d --name nocodb-postgres \
-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

三个关键参数的含义：

• -v ...:/usr/app/data/：数据卷挂载点。README 特别强调自 0.10.6 版本起必须挂载该卷持久化数据，否则容器重建后数据丢失。从源码看，数据目录解析优先级为 NC_APP_DATA_DIR → NC_TOOL_DIR → 当前工作目录（getToolDir），SQLite 的 noco.db 就落在这个目录下；
• -e NC_DB="pg://host:5432?u=root&p=password&d=d1"：元数据库连接串，格式为 协议://主机:端口?u=用户&p=密码&d=数据库名。示例中 host.docker.internal 是 Docker 访问宿主机服务的专用主机名，说明宿主机上需已运行 PostgreSQL；
• -e NC_AUTH_JWT_SECRET：JWT 签名密钥。源码中它被读入 auth.jwt.secret 配置（NcConfig.createByEnv），生产环境务必换成自己的随机值——README 示例中的 UUID 仅供演示。

另外 README 给出一条字符集提醒：若在数据库中要输入特殊字符（如中文以外的多语言字符），需要在建库时自行指定字符集与排序规则（collation），否则可能出现乱码或索引问题。

2.2 Binaries 方式：各平台一行命令

README 提供了一键下载可执行文件的命令，覆盖 macOS / Linux / Windows 的 x64 与 arm64 共六种组合：

# MacOS (x64)
curl http://get.nocodb.com/macos-x64 -o nocodb -L && chmod +x nocodb && ./nocodb

# MacOS (arm64)
curl http://get.nocodb.com/macos-arm64 -o nocodb -L && chmod +x nocodb && ./nocodb

# Linux (x64)
curl http://get.nocodb.com/linux-x64 -o nocodb -L && chmod +x nocodb && ./nocodb

# Linux (arm64)
curl http://get.nocodb.com/linux-arm64 -o nocodb -L && chmod +x nocodb && ./nocodb

# Windows (x64)
iwr http://get.nocodb.com/win-x64.exe
.\Noco-win-x64.exe

# Windows (arm64)
iwr http://get.nocodb.com/win-arm64.exe
.\Noco-win-arm64.exe

二进制方式默认使用 SQLite 元数据库，文件保存在当前工作目录（即上文 getToolDir 回退到 process.cwd() 的行为），适合本地快速体验，无需任何容器环境。

2.3 Docker Compose 方式：组合编排

README 指引到仓库内的 docker-compose 目录，并给出 PostgreSQL 组合的启动示例：

git clone https://gitcode.com/GitHub_Trending/no/nocodb
# 进入 PostgreSQL 组合目录
cd nocodb/docker-compose/2_pg
docker compose up -d

需要注意：当前仓库的目录结构已演进，docker-compose 下现在提供的是交互式安装向导 setup.sh 与一组预置编排示例 examples。examples/README.md 中的对照表列出了 5 套典型生产形态：

示例	PostgreSQL	Redis	代理	适用场景
quickstart-demo	内置	内置	无（端口 8080）	本地评估 / 快速演示
managed-postgres	外部托管（RDS 等）	外部	无（端口 8080）	自管负载均衡之后的生产环境
external-postgres-and-redis	外部自管	外部	无（端口 8080）	最小 Docker 占用
traefik-custom-ssl	外部托管	外部	Traefik + 自签 TLS 证书	带自有 SSL 证书的生产环境
postgres-private-ca	外部（私有 CA）	外部	Traefik + Let's Encrypt	私有云 / 内部 CA 数据库

快速启动方式（以 quickstart-demo 为例）：

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

该示例内置了一个确定性的演示密码，examples 的 README 明确要求：任何真实使用前必须替换其中的占位值（如 CHANGE_ME_db_password）。

三、GUI 访问

启动成功后，通过以下地址进入 Dashboard：

• 默认：http://localhost:8080/dashboard

默认端口 8080 有两处源码依据：dockerEntry.ts 中 server.listen(process.env.PORT || 8080, ...)，以及 NcConfig 中 ncConfig.port = +(port ?? 8080)。若需改变端口或挂载路径，可分别通过 NC_PORT、NC_DASHBOARD_URL 环境变量控制（同样在 createByEnv 中读取）。

四、核心功能概览（README Features 章节）

README 将产品能力归纳为五块，均可在仓库中找到对应实现入口：

1. 富电子表格界面（Rich Spreadsheet Interface）：表/列/行的增删改查；排序、过滤、隐藏列；Grid（默认）、Gallery、Form、Kanban 等多视图；协作视图与锁定视图；Base/View 的公开或带密码私享分享；ID、LinkToAnotherRecord、Lookup、Rollup、SingleLineText、Attachment、Currency、Formula 等丰富单元格类型；基于角色的细粒度访问控制。GUI 侧实现位于 packages/nc-gui（如 smartsheet 组件 目录）。
2. App Store 工作流自动化集成：分三类——聊天（Slack、Discord、Mattermost 等）、邮件（AWS SES、SMTP、MailerSend 等）、存储（AWS S3、Google Cloud Storage、Minio 等）。后端依赖中可看到 @slack/web-api、@aws-sdk/client-ses、@google-cloud/storage、minio 等对应 SDK（package.json）。
3. 编程式访问（Programmatic Access）：提供 REST API 与官方 SDK 两种调用方式，用 JWT 或社交登录 token 签名请求。仓库中 SDK 位于 packages/nocodb-sdk 与 packages/nocodb-sdk-v2；后端 OpenAPI 定义见 swagger-v2.json。
4. Sync Schema：支持同步在 NocoDB 外部发生的 schema 变更；跨环境迁移时需注意自行携带 schema 迁移。相关 API 在 swagger 中的描述为 "Synchronise the meta data difference between NC_DB and external data sources"（swagger.json），印证了 NC_DB（元库）与外部数据源之间的对比同步语义。
5. Audit：集中保存用户操作日志。源码层面审计功能由环境变量开关控制：NcConfig.isAuditEnabled 仅在 NC_ENABLE_AUDIT === 'true' 时启用。

五、Production Setup：环境变量与配置解析链路

README 的 Production Setup 章节指出：默认使用 SQLite 存元数据，但可通过 NC_DB 环境变量指定其它数据库，完整变量列表指向官方文档。以下基于当前仓库源码，给出这些变量在代码中的真实解析行为，作为运维配置的可靠依据。

5.1 NC_DB 的解析入口

服务启动时，InitMetaServiceProvider 按注释所述依次执行：初始化缓存 → 初始化数据库连接（不存在则创建）→ 初始化 meta 服务 → 初始化 JWT → 运行版本升级器。其第一步就是环境归一化与配置加载：

// NC_DATABASE_URL_FILE, DATABASE_URL_FILE, DATABASE_URL, NC_DATABASE_URL to NC_DB
await prepareEnv();
const config = await NcConfig.createByEnv();

prepareEnv 说明了连接串的多个兼容别名：

• NC_DATABASE_URL_FILE / DATABASE_URL_FILE：从指定文件读取连接串（内容会经 JDBC 格式转换）后写入 NC_DB；
• NC_DATABASE_URL / DATABASE_URL：直接的值别名。

createByEnv 读取的元数据库配置有三个优先级：NC_DB（连接串 URL）→ NC_DB_JSON（内联 JSON 配置）→ NC_DB_JSON_FILE（JSON 配置文件路径，不存在会直接抛错 NC_DB_JSON_FILE not found）。

5.2 连接串如何变成 Knex 配置

URL 解析最终由 jdbcToXcConfig 完成，几个值得注意的默认行为：

• 使用 parse-database-url 解析，未知查询参数会被保留透传，已知参数会做别名归一（u/p/d 即 user/password/database）；
• 未指定端口时，按驱动映射到默认端口（defaultClientPortMapping）；
• PostgreSQL 默认开启 SSL：解析结果为 pg 且未显式配置 ssl、主机不在 avoidSSL 名单内时，自动设置 connection.ssl = true——对自建非 SSL 的本地 PG 需要显式覆盖此行为。

解析出的 client + connection 结构交给 metaDbCreateIfNotExist：SQLite 场景下会自动创建 noco.db 文件（连接缺少 filename 直接报错）；非 SQLite 场景下会自动 CREATE DATABASE（连接缺少 database 名报错）。这也解释了为什么 docker run 示例中只需给到 &d=d1 即可首次启动成功。

5.3 其余关键环境变量速查

变量	源码位置	作用
NC_DB	NcConfig.ts#L142	元数据库连接串，如 pg://host:5432?u=root&p=password&d=d1
NC_DB_JSON / NC_DB_JSON_FILE	NcConfig.ts#L143-L144	以 JSON 形式（内联或文件）提供元数据库配置，可表达 URL 无法覆盖的细粒度连接参数
NC_AUTH_JWT_SECRET	NcConfig.ts#L146	JWT 签名密钥，生产必须自定义
NC_PORT	NcConfig.ts#L147	实例对外端口，默认 8080
NC_DASHBOARD_URL	NcConfig.ts#L150	Dashboard 挂载路径，默认 /
NC_TRY	NcConfig.ts#L148	置真时元库切换为 SQLite :memory:（测试用途，NcConfig.ts#L91-L102）
NC_WORKER	NcConfig.ts#L149	置真时以 worker 形态运行（不暴露端口）
NC_APP_DATA_DIR / NC_TOOL_DIR	helpers.ts#L30-L34	数据目录，决定 noco.db 与附件等文件的落盘位置（Docker 镜像中对应 /usr/app/data/）
NC_ENABLE_AUDIT	NcConfig.ts#L182-L184	true 时启用审计日志
NC_DISABLE_TELE	tele.ts#L11	置真时禁用遥测；开发脚本中默认开启禁用（package.json）

此外，extractLimitAndOffset.ts 暴露了一组数据查询行为变量（NC_DB_QUERY_LIMIT_DEFAULT、NC_DB_QUERY_LIMIT_MIN、NC_DB_QUERY_LIMIT_MAX 等），用于调节分页大小边界，属于进阶调优项。

5.4 升级路径约束（源码可验证的运维风险点）

init-meta-service.provider.ts 内置了硬性升级检查：实例配置版本低于 0100002 时，启动会直接抛出"请先升级到 0.207.3，再升级到最新版"的错误。这意味着跨大版本直升旧版本实例不被允许，生产升级前应确认当前实例版本。

六、Development Setup 与构建体系

README 将 Development Setup 指向官方文档，仓库侧可确认的实现事实如下：

• 构建工具为 Rspack（见 rspack.config.js 与 rspack.dev.config.js），TypeScript 编译 + SWC；
• 开发入口脚本（package.json）：
  • pnpm start（即 watch:run）：ENTRYPOINT=src/run/docker，本地默认 SQLite；
  • watch:run:pg / watch:run:mysql：分别在启动前注入 NC_DB="pg://localhost:5432?u=postgres&p=password&d=..." 或 mysql2://localhost:3306?u=root&p=password&d=..."（dockerRunPG.ts、dockerRunMysql.ts），方便开发者直接连本地 PostgreSQL/MySQL 调试元库；
• 测试：Jest（pnpm test），E2E 配置见 test/jest-e2e.json；
• 贡献流程见仓库贡献指南；许可证为 LICENSE.md 声明的 Sustainable Use License。

七、小结

• 最简路径：docker run + 挂载 /usr/app/data/ 卷，即可在 http://localhost:8080/dashboard 得到一个 SQLite 元库的可用实例；需要更高并发可靠性时用 NC_DB 指向 PostgreSQL；
• 所有生产配置最终收敛到 NC_DB、NC_AUTH_JWT_SECRET、NC_PORT、NC_APP_DATA_DIR 等少量环境变量，且都能在当前仓库源码（nc-config、init-meta-service.provider.ts）中找到确定性的解析与默认值；
• 跨环境迁移与旧版本升级要格外谨慎：外部 schema 变更需走 Sync Schema 流程，低于 0.207.3 的旧实例必须先逐级升级。