NocoDB 安装与运行完全指南：从 Docker 快速上手到 NC_DB 元数据库配置解析

NocoDB 安装与运行完全指南从 Docker 快速上手到 NC_DB 元数据库配置解析【免费下载链接】nocodb A Free Self-hostable Airtable Alternative项目地址: https://gitcode.com/GitHub_Trending/no/nocodb本文以 NocoDB 官方 README 的德语版markdown/readme/languages/german.md为主体内容覆盖其全部核心章节——Docker 快速启动、生产环境部署、环境变量、本地开发搭建与功能特性清单并结合当前仓库的实际源码配置解析器、Docker Compose 示例、pnpm 工作区脚本逐层扩充使每条命令和参数都能追溯到真实的实现依据。读完后你可以独立完成用 Docker 一键拉起 NocoDB、通过NC_DB将其元数据库指向 PostgreSQL/MySQL 等外部数据库、理解 SQLite 回退机制的底层逻辑并在源码级理解端口、JWT 密钥与连接池等环境变量的实际作用。NocoDB 是什么README德语版对产品的定位一句话概括为将任何 MySQL、PostgreSQL、SQL Server、SQLite、MariaDB 转换成一张 Smart-Tabelle智能表格。即 NocoDB 并不替代你的数据库而是在既有数据库之上生成一套类电子表格的协作界面让你以 No-Code 方式完成建表、筛选、分享与集成。这一点在源码中得到直接印证NocoDB 启动时需要一个元数据库来存放表格视图的元数据与外部数据库的连接信息连接参数通过环境变量NC_DB指定。若未指定则回退到内置 SQLite。这一元数据库 外部数据表的双层结构是理解后文所有部署方式的钥匙。快速开始Docker 方式最简启动内置 SQLite原文档给出的最简命令docker run -d \ --name noco \ -v $(pwd)/nocodb:/usr/app/data/ \ -p 8080:8080 \ nocodb/nocodb:latest两个要点均出自原文档且与源码一致容器内元数据库默认目录为/usr/app/data/。原文档指出若未提供外部数据库输入NocoDB 回退到 SQLite要让 SQLite 持久化就挂载该目录即-v那行。NocoDB 要求一个数据库来存元数据SQLite 只是零配置回退生产环境建议显式指定。从源码看这一回退机制NcConfig 的默认值即为client: sqlite3、filename: noco.db且文件名会与数据目录拼接path.join(ncConfig.toolDir, filename)。toolDir的取值链在 helpers.ts 中定义为NC_APP_DATA_DIR → NC_TOOL_DIR → process.cwd()因此 Docker 镜像将其指到/usr/app/data/后SQLite 文件才会落在挂载卷内。指定外部数据库PostgreSQL 示例docker run -d \ --name noco \ -v $(pwd)/nocodb:/usr/app/data/ \ -p 8080:8080 \ -e NC_DBpg://host.docker.internal:5432?urootppassworddd1 \ -e NC_AUTH_JWT_SECRET569a1821-0a93-45e8-87ab-eb857f20a010 \ nocodb/nocodb:latest这里有两个关键环境变量NC_DB元数据库连接串格式为driver://host:port?uuserppasswordddatabaseNC_AUTH_JWT_SECRETJWT 签名的密钥用于登录态与 API Token 的签发。关于NC_DB的解析细节源码给出了比原文档更完整的规则驱动前缀映射。constants.ts 定义了mysql/mariadb → mysql2、postgres/postgresql → pg、sqlite → sqlite3、oracle → oracledb并给出默认端口映射MySQL 3306、PostgreSQL 5432、SQL Server 1433、Oracle 1521——即连接串中省略端口时按此补全。短参数别名。URL 查询参数支持缩写别名constants.ts参数别名databased、dbpasswordpuserutitletoptionsopt、optsssl/keyFilePath/certFilePath/caFilePath无别名SSL 自动启用规则。从 jdbcToXcConfig 的结构看当驱动为pg且未显式配置ssl时若主机名不在白名单[localhost, 127.0.0.1, host.docker.internal, 172.17.0.1]avoidSSL内会自动开启 SSL。这解释了为何面向公网托管数据库的连接串往往无需显式写ssltrue。连接池。元数据库连接池上限由NC_DB_POOL_MAX控制默认 10defaultConnectionOptions。连接建立时的建库逻辑。NcConfig.create 在装配完成后会调用metaDbCreateIfNotExist()SQLite 场景确保数据库文件存在其他驱动则在数据库名缺失时报错Meta database configuration missing database name——也就是说外部数据库实例需已存在NocoDB 会自动创建其中的元数据库/文件。NPM 方式原文档的 NPM 安装方式npm install create-nocodb-app需要说明当前仓库的实际状态该包名仅出现在这篇德语 README 中当前代码库的 README 与安装入口均已收敛到 Docker 与仓库内置的部署脚本见下文pnpm 工作区pnpm-workspace.yaml内也未包含该脚手架包。因此create-nocodb-app属于文档历史记载的便捷安装途径以仓库现状为准推荐的运行方式仍是 Docker 镜像或下述 Compose 方案。生产环境部署Docker Compose原文档Produktivaufbau生产构建一节指出NocoDB 需要一套数据库来保存表格视图元数据与外部数据库连接信息并通过NC_DB指定。原文档给出的 Compose 流程是克隆仓库后进入docker-compose/pg子目录执行docker compose up -d。对照当前仓库docker-compose/目录已演进为三种形态功能上是原文档docker-compose/pg的超集替代1. 交互式向导setup.sh / Auto-Upstallsetup.sh 是一个轻量包装器直接执行同级的 1_Auto_Upstall/noco.shbash docker-compose/setup.sh该向导脚本noco.sh会交互式收集参数并生成db.json、docker.env等文件——注意脚本头部注释明确写道这些生成文件包含数据库凭据需以 owner-only 权限创建umask 077对生产环境凭据管理是不错的实践参考。2. 现成示例目录docker-compose/examples当前仓库提供五套开箱即用的 Compose 配置见 docker-compose/examples/README.md示例PostgreSQLRedis代理适用场景quickstart-demo内置内置无8080 端口本地评估managed-postgres外部托管RDS 等外部无生产环境自带 LBexternal-postgres-and-redis外部自管外部无最小 Docker 占用traefik-custom-ssl外部托管外部Traefik 自定义证书自带 SSL 证书的生产环境postgres-private-ca私有 CA外部Traefik Lets Encrypt私有云/内网 DB以最简的 quickstart-demo 为例其核心环境变量配置是docker-compose.ymlnocodb: image: nocodb/nocodb:latest environment: NC_DB: pg://db:5432?unocodbpquickstart_demo_pw_change_mednocodb NC_REDIS_URL: redis://redis:6379 NC_SITE_URL: http://localhost:8080 NC_DISABLE_MUX: true volumes: - nocodb_data:/usr/app/data这比原文档的docker run示例多出了NC_REDIS_URLRedis 用于缓存/实时协作等与NC_SITE_URL站点对外地址。官方示例 README 明确提醒生产形态的示例中所有占位符如CHANGE_ME_db_password必须在docker compose up -d之前替换。环境变量速查从源码读出完整取值原文档将环境变量列表外链到官方文档站这里依据源码 NcConfig.createByEnv 给出与当前代码一一对应的核心项环境变量来源作用NC_DBprocess.env.NC_DB元数据库连接串URL 形式NC_DB_JSON/NC_DB_JSON_FILE同上以 JSON或 JSON 文件形式提供元数据库配置是 URL 形式的等价替代NC_AUTH_JWT_SECRET同上JWT 密钥NC_PORTport ?? 8080监听端口默认8080NC_TRYtryMode置真时元数据库退化为sqlite3 :memory:单连接池用于测试/试用模式NC_WORKERworker为真时进程作为 worker 运行不暴露端口NC_DASHBOARD_URLdashboardPathDashboard 挂载路径默认/一个值得注意的健壮性细节NC_DB_JSON_FILE路径不存在时直接抛错NC_DB_JSON_FILE not found: pathNcConfig.ts而不是静默回退避免生产环境误连到错误的存储。GUI 访问启动后浏览器访问http://localhost:8080/dashboard原文档GUI一节即此一句。从源码结构看Dashboard 页面由后端 Express 应用提供见 run/docker.tsserver.set(view engine, ejs)并启用 CORS、禁用 etag 等前端静态资源由构建产物内嵌提供而NC_DASHBOARD_URL允许将该路径改挂到子目录如反向代理场景下/nocodb/dashboard。功能特性Merkmale完整继承原文档特性清单并结合仓库结构补充佐证富表格界面Rich-Tabellenschnittstelle简单的搜索、排序、过滤与列隐藏视图创建GitterGrid、GalerieGallery、Kanban、FormularForm——当前仓库前端在 packages/nc-gui/composables 下可看到useGridViewData、useKanbanViewStore、useFormViewStore、useGalleryViewData等与各视图一一对应的组合式函数视图分享公开与密码保护两种方式个人视图与锁定视图单元格图片上传兼容 S3、Minio、GCP、Azure、DigitalOcean、Linode、OVH、Backblaze——存储集成插件位于 packages/nocodb/src/plugins角色体系所有者Eigentümer、创建者Ersteller、编辑者Bearbeiter、查看者Betrachter、评论者Kommentator及自定义角色——角色徽章资源可参考 packages/nc-mail-assets/badges访问控制细粒度到数据库、表、列级别。工作流自动化 App-StoreChatMicrosoft Teams、Slack、Discord、Mattermost邮件SMTP、SES、MailChimpSMSTwilioWhatsApp以及任意第三方 API。程序化 API 访问REST APISwaggerOpenAPI 规范见 packages/nocodb/src/schema/swagger.json 与根目录 APIs.jsonGraphQL APIJWT 认证与社交登录认证策略实现位于 packages/nocodb/src/strategiesAPI Token 用于 Zapier、Integromat 等集成。本地开发搭建原文档Entwicklungsaufbau开发构建一节包含三步全部保留并补充了仓库现状说明1. 克隆项目git clone https://gitcode.com/GitHub_Trending/no/nocodb cd nocodb2. 本地启动后端cd packages/nocodb pnpm install pnpm run watch:run # 浏览器访问 localhost:8080/dashboardwatch:run的真实定义packages/nocodb/package.json为cross-env NODE_ENVdevelopment NC_DISABLE_TELEtrue ENTRYPOINTsrc/run/docker rspack --config rspack.dev.config.js即通过 rspack 的 dev 配置、以src/run/docker.ts为入口的热重载启动NC_DISABLE_TELEtrue关闭遥测。同文件还提供watch:run:mysql、watch:run:pg两个变体分别指向src/run/dockerRunMysql、src/run/dockerRunPG用于直接连 MySQL/PG 元数据库调试。3. 本地启动前端cd packages/nc-gui pnpm install pnpm run dev # 浏览器访问 localhost:3000/dashboarddev即nuxt devpackages/nc-gui/package.json。原文档承诺代码修改自动重启这正是 Nuxt dev 模式与 rspack watch 的热更新行为。注意事项原文档提示框 仓库事实原文档提示packages/nocodb依赖nc-lib-guipackages/nc-lib-gui 下提供编译好的 GUI 库发布在 npm Registry。若只想改后端可直接启动后端后访问localhost:8080/dashboard无需跑前端包管理器约束根 package.json 中preinstall使用npx only-allow pnpm即只能用 pnpmnpm/yarn 会被拒绝Node 版本原文档徽章标注node 14.18.0但当前仓库 packages/nocodb/package.json 的engines已要求node 22以当前仓库为准。项目动机Why Mission最后完整保留原文档的Warum bauen wir das auf?我们为什么构建它与Unsere Aufgabe我们的使命两节的核心论述中文转述为什么绝大多数互联网业务用电子表格或数据库承载业务需求。电子表格每天被十亿以上的人协作使用而数据库是远比表格强大的计算工具人却无法以同样速度在其上工作。用 SaaS 产品解决这一问题的尝试往往意味着糟糕的访问控制、厂商锁定、数据锁定、突如其来的涨价以及对未来可能性的天花板。使命提供最强大的数据库 No-Code 界面让世界上每个互联网业务都能使用通过公平且可持续的模式广泛开放这一能力把强大的计算工具民主化让超过十亿人能在互联网上获得大胆折腾与创造的能力。小结零配置试用docker run 挂载/usr/app/data/内置 SQLite 回退生产部署NC_DB指向外部数据库连接串支持u/p/d短别名与 SSL 自动启用配合 docker-compose/setup.sh 向导或 docker-compose/examples 现成模板访问入口http://localhost:8080/dashboard可用NC_PORT、NC_DASHBOARD_URL调整本地开发pnpm 工作区下packages/nocodbpnpm run watch:run与packages/nc-guipnpm run dev两条线并行。【免费下载链接】nocodb A Free Self-hostable Airtable Alternative项目地址: https://gitcode.com/GitHub_Trending/no/nocodb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考