Convex 自托管版 Dashboard 本地运行与配置指南

• 数据库
• 后端

导读

在自托管 Convex 的完整部署中，除后端（backend）与你的前端应用外，还需要一个可视化控制台——即本仓库npm-packages/dashboard-self-hosted目录下的自托管版 Dashboard。本篇指南基于仓库文档 self-hosted/advanced/dashboard.md，系统讲解如何从源码在本地启动 Dashboard、如何将它与后端部署对接，以及 Monaco 编辑器内核加载方式的两种可选配置（CDN 与内置），并深入到next.config.js、_app.tsx、monacoInternalLoader.ts等源码文件，帮助你理解每一步背后的实现原理。

读完本文，你将能够：在一台开发机上用just与turbo完成依赖安装和构建、以NEXT_PUBLIC_DEPLOYMENT_URL指定后端地址并启动 Dashboard、通过NEXT_PUBLIC_ADMIN_KEY传入管理员密钥、以及在内网/离线环境下把 Monaco 编辑器资源改为从本机加载。

一、Dashboard 在自托管架构中的位置

自托管 Convex 需要部署三个部分（见 self-hosted/README.md）：

1. Convex 后端（backend）；
2. Convex Dashboard（控制台）；
3. 你的前端应用（可自行托管，或托管在 Netlify、Vercel 等平台）。

其中 Dashboard 并不参与业务数据的存储与计算，它只是连接后端的控制面板：查看数据表、Schema、函数日志、Cron 调度、环境变量，管理认证配置等。它的核心能力来自npm-packages/dashboard-self-hosted/src/pages/下的页面集合，例如：

• data.tsx（数据浏览）、schema.tsx（Schema 管理）、functions.tsx（函数管理）；
• logs.tsx（日志查看）、history.tsx（历史记录）、files.tsx（文件存储）；
• schedules/crons.tsx与schedules/functions.tsx（调度任务）；
• settings/下的认证、环境变量、集成、用量限制等设置页。

使用默认的 Docker 方式（docker compose up）时，Dashboard 已经随后端一起被提供在http://localhost:6791。而本文档所讲的"本地运行"，则是直接从源码构建 Dashboard，适合在开发自托管环境、调试 Dashboard 自身，或对 Dashboard 做定制时使用。

二、运行前的环境准备

2.1 安装 Just

仓库的 JavaScript 构建流程统一由Justfile驱动，因此需要先安装 Just 命令工具。Just 是一个通用的命令执行器，被用来封装install-js、turbo、pnpm等脚本，避免直接手敲一串串命令。

• 可以通过cargo install just或brew install just安装；
• 也可以通过官方 Packages 页面获取对应平台的安装包。

安装完成后，在仓库根目录执行just（或just --list）即可看到所有可用 recipe（见 Justfile 的_default定义）。

2.2 理解端口约定

在本地运行前，先明确 Dashboard 与后端、CLI 之间的端口分工（下表依据 dashboard-self-hosted/package.json 的 scripts 与 self-hosted/README.md 整理）：

在 Docker 部署场景中，访问地址是http://localhost:6791；本地源码运行时，next dev默认在 6790 端口。

三、本地运行 Dashboard 的完整步骤

官方文档 self-hosted/advanced/dashboard.md 给出的核心流程是在npm-packages/dashboard-self-hosted目录下依次执行四条命令：

just install-js just turbo run build --filter=dashboard-self-hosted^... npm run build NEXT_PUBLIC_DEPLOYMENT_URL="<your-backend-url>" npm run start

下面逐条拆解其含义，并结合仓库实现说明每一步做了什么。

3.1 安装 JavaScript 依赖：just install-js

install-js定义在 Justfile：

install-js: cd "{{justfile_directory()}}/npm-packages"; just pnpm install --frozen-lockfile

它切换到npm-packages目录，用仓库固定的 pnpm 版本执行pnpm install --frozen-lockfile——即严格按照pnpm-lock.yaml锁定版本安装依赖，保证任何人拉取同一 commit 后得到一致的依赖树。dashboard-self-hosted是 pnpm workspace 中的一员（其依赖如@convex-dev/design-system、dashboard-common、convex、system-udfs均以workspace:*形式引用，见 package.json），所以依赖需要在整个 workspace 层面安装。

3.2 构建 Dashboard 的依赖项目：just turbo run build --filter=dashboard-self-hosted^...

turborecipe 同样封装在 Justfile 中：它把scripts/node_modules/.bin/turbo放入 PATH，进入npm-packages目录执行 turbo。--filter=dashboard-self-hosted^...的含义是"构建dashboard-self-hosted的所有依赖项目（但不包含它自己）"，例如dashboard-common、system-udfs等 workspace 包会先被构建产出。这一步保证了后面npm run build时引用的 workspace 依赖都是最新的构建产物。

3.3 构建 Dashboard 本体：npm run build

buildscript 在 package.json 中定义为：

"build": "npm run build:generated && next build"

其中build:generated会执行：

"build:generated": "python3 ../dashboard-common/scripts/build-convexServerTypes.py"

该脚本为 Dashboard 生成与后端交互所需的 Convex server 类型定义，然后执行next build。

关于构建产物，next.config.js 中有一个值得注意的分支逻辑：

• 默认情况下（BUILD_TYPE未设为export），使用output: "standalone"模式，生成可独立部署的 standalone 服务；
• 若设置BUILD_TYPE=export，则切换为静态导出模式（output: "export"），并关闭图片优化（images.unoptimized: true）。build:exportscript 还额外设置了NEXT_PUBLIC_USE_CURRENT_DEPLOYMENT_API=true与NEXT_PUBLIC_DEFAULT_LIST_DEPLOYMENTS_API_PORT=6791。

3.4 启动 Dashboard 并指向你的后端：npm run start

启动命令为：

NEXT_PUBLIC_DEPLOYMENT_URL="<your-backend-url>" npm run start

• NEXT_PUBLIC_DEPLOYMENT_URL是必填的核心环境变量，指向你的 Convex 后端地址。它可以是一个本地后端（如http://127.0.0.1:3210）、远程自托管后端，甚至 Convex Cloud 的部署地址（Cloud 地址可在部署设置页找到）。
• startscript 为next start -p 6791，即生产模式下在6791端口提供服务。

从 src/pages/_app.tsx 的App.getInitialProps可以看到该变量的消费逻辑：服务端渲染时读取process.env.NEXT_PUBLIC_DEPLOYMENT_URL，经normalizeUrl去掉尾部斜杠后注入页面 props；客户端导航时则从window.__NEXT_DATA__.props.pageProps读取，保证整个会话内 URL 一致。

3.5 更省事的封装：just run-dashboard

如果你使用仓库根目录的just，其实无需手动执行上述多步。仓库在 Justfile 中提供了run-dashboardrecipe：

run-dashboard *ARGS: cd '{{justfile_directory() / "npm-packages/dashboard-self-hosted"}}' && \ if [ -n "{{ARGS}}" ]; then \ NEXT_PUBLIC_DEPLOYMENT_URL="{{ARGS}}" npm run dev; \ else \ NEXT_PUBLIC_DEPLOYMENT_URL="http://127.0.0.1:3210" \ NEXT_PUBLIC_ADMIN_KEY="$(just generate-admin-key)" \ npm run dev; \ fi

用法（对应 dashboard-self-hosted/README.md）：

# 先完成一次性初始化 just install-js just turbo run build --filter=dashboard-self-hosted^... # 传入部署地址启动（dev 模式，端口 6790） just run-dashboard "YOUR_DEPLOYMENT_URL"

• 不传参数时，run-dashboard会自动指向本地后端http://127.0.0.1:3210，并用just generate-admin-key（见 Justfile，基于本地 instance secret 通过generate_key二进制派生 admin key）自动注入NEXT_PUBLIC_ADMIN_KEY，实现本地一键启动；
• 传入参数时，则把参数作为NEXT_PUBLIC_DEPLOYMENT_URL传入，适合连接远程部署。

四、把 Dashboard 对接后端：URL 与 Admin Key

Dashboard 与后端的所有管理交互都基于"部署 URL + Admin Key"。除了上文的NEXT_PUBLIC_DEPLOYMENT_URL，还有以下相关环境变量（见 src/pages/_app.tsx）：

Admin Key 的鉴权方式在 src/lib/checkDeploymentInfo.ts 中有直接体现：Dashboard 会向后端发起GET /api/check_admin_key请求，请求头携带Authorization: Convex <adminKey>，用于探测当前密钥允许的操作集合（allowedOps）与是否只读（isReadOnly）；当端点返回 404（旧版后端）时，则放行所有操作。另外，src/lib/fetchCurrentDeployment.ts 说明了 CLI 匿名模式下/api/current_deployment端点的用途——自托管 Dashboard 下该端点返回 404，因此会回退到其他凭据来源（即环境变量）。

注意：在生产部署中，Admin Key 拥有后端全部管理权限，务必妥善保管，不要把带密钥的.env.local提交到版本库（参考 self-hosted/README.md 中对CONVEX_SELF_HOSTED_ADMIN_KEY的说明）。

五、可选配置：Monaco 编辑器的加载方式

这是 self-hosted/advanced/dashboard.md 中列出的唯一一条 Dashboard 可选配置，核心内容如下：

Dashboard 的所有编辑器类元素（Schema 编辑、函数代码查看、环境变量编辑等）都使用monaco-editornpm 包。默认情况下，Monaco 的核心资源从 CDN 加载；如果希望从内部（本地/内网）加载，可将环境变量NEXT_PUBLIC_LOAD_MONACO_INTERNALLY设置为true。

5.1 两种加载模式的差异

• 默认（CDN 模式）：@monaco-editor/react的 loader 会从公共 CDN 拉取 Monaco 核心与语言服务资源。优点是不增加自身打包体积；缺点是在离线、内网或网络受限环境下无法加载，且每次首次打开编辑器页面都要依赖外部网络。
• 内置（internal）模式：NEXT_PUBLIC_LOAD_MONACO_INTERNALLY=true时，Monaco 相关资源会随 Dashboard 自身打包并由本机提供，适合离线部署与对资源来源有严格要求的场景。

5.2 源码中的实现

在 src/pages/_app.tsx 中，应用启动时会根据环境变量按需加载内置 loader：

// Monaco only runs in the browser, and pulling it into the server bundle makes // it fail to evaluate there. if ( typeof window !== "undefined" && process.env.NEXT_PUBLIC_LOAD_MONACO_INTERNALLY === "true" ) { import("../lib/monacoInternalLoader").then((a) => a).catch(console.error); }

注意两点实现细节：

1. 该模块只在浏览器端（typeof window !== "undefined"）动态import，避免 Monaco 被打进 Next.js 的 server bundle 导致服务端求值失败；
2. 当环境变量不是字符串"true"时，走默认的 CDN 加载路径。

内置加载的核心实现在 src/lib/monacoInternalLoader.ts：它通过window.MonacoEnvironment.getWorker把 JSON、TypeScript/JavaScript 等语言服务的工作线程全部改为从monaco-editor/esm/vs/...的本地 chunk 创建（Turbopack 会把每个new Worker(new URL(…))打成独立 chunk），再调用loader.config({ monaco })将本地实例注入@monaco-editor/react的 loader。

5.3 使用方式

以npm run start（生产模式）为例，在启动命令前加上环境变量即可：

NEXT_PUBLIC_DEPLOYMENT_URL="http://127.0.0.1:3210" \ NEXT_PUBLIC_LOAD_MONACO_INTERNALLY="true" \ npm run start

dev 模式（next dev）下同样适用。需要注意的是，该变量属于NEXT_PUBLIC_前缀，会在构建时被 Next.js 内联进产物（源码注释也标明该判断发生在构建期），因此修改后需要重新执行npm run build再start才能生效，仅重启next start不会更新取值。

六、常见问题与排查建议

1. 页面加载了但看不到数据，或提示鉴权失败

• 确认NEXT_PUBLIC_DEPLOYMENT_URL指向的后端可达：自托管后端默认监听http://127.0.0.1:3210；
• 确认 Admin Key 有效：Docker 部署用docker compose exec backend ./generate_admin_key.sh生成（见 self-hosted/README.md），源码本地后端用just generate-admin-key；
• 若后端较旧，/api/check_admin_key不存在时 Dashboard 会按放行处理，可先确认后端版本。

2. 编辑器区域空白或控制台报 Monaco 加载失败

• 网络受限环境下优先设置NEXT_PUBLIC_LOAD_MONACO_INTERNALLY=true并重新构建；
• 确认环境变量在构建时已生效（可检查构建产物中的内联值）。

3. 端口被占用

• dev 模式占用 6790（next dev --port 6790），生产模式占用 6791（next start -p 6791），冲突时可调整对应 script 中的端口参数。

4. 需要了解构建产物形态

• 默认next build产出 standalone 服务；如需纯静态文件部署（如直接挂到对象存储），可用BUILD_TYPE=export npm run build（即npm run build:export），此时会启用/api/current_deployment兼容逻辑并默认对接 6791 端口的列表接口。

七、延伸阅读

• self-hosted/advanced/running_binary_directly.md：不依赖 Docker，直接运行后端二进制；
• self-hosted/advanced/hosting_on_own_infra.md：在自有服务器上托管；
• self-hosted/advanced/fly/README.md 与 self-hosted/advanced/railway/README.md：托管到 Fly.io 与 Railway；
• self-hosted/advanced/postgres_or_mysql.md：把后端数据库从默认 SQLite 切换到 PostgreSQL 或 MySQL；
• self-hosted/advanced/s3_storage.md：将文件、导出、快照等存储到 S3；
• self-hosted/advanced/knobs.md：通过 knobs 对后端做高级调优；
• Justfile 与 npm-packages/dashboard-self-hosted/README.md：本地运行相关的全部 recipe 与命令参考。

结语

自托管版 Dashboard 的本地运行本质上是一条清晰的流水线：用just install-js锁定安装 workspace 依赖 → 用just turbo run build --filter=dashboard-self-hosted^...构建依赖包 → 用npm run build构建 Dashboard 本体 → 以NEXT_PUBLIC_DEPLOYMENT_URL（必要时加上NEXT_PUBLIC_ADMIN_KEY）启动并指向后端。如果运行环境无法访问公网 CDN，再通过NEXT_PUBLIC_LOAD_MONACO_INTERNALLY=true将 Monaco 编辑器内核切换到内部加载。掌握这三个环节的环境变量与端口约定，即可在本地复现与定制完整的自托管 Convex 控制台。

• 数据库
• 后端