SkyPilot Dashboard 开发与部署实战：从源码构建到前端联调完整指南-酒店常州论坛

SkyPilot Dashboard 开发与部署实战：从源码构建到前端联调完整指南

【免费下载链接】skypilotThe AI Compute Platform for frontier teams. SkyPilot turns fragmented AI compute into one AI supercomputer, so frontier AI teams build custom intelligence faster.项目地址: https://gitcode.com/GitHub_Trending/sk/skypilot

SkyPilot Dashboard 是 SkyPilot 官方提供的可视化控制台，用于统一管理集群（Clusters）、任务（Jobs）、基础设施（Infra）、存储卷（Volumes）、工作区（Workspaces）等核心资源。本文以仓库中 sky/dashboard/README.md 为主干，结合其 Next.js 前端工程与 API Server 的集成源码，完整讲解从源码构建 Dashboard、启动开发服务器、连接远端 API Server 到前端联调的全过程。读完本文，你将掌握两种访问方式（官方包直连与源码构建）、开发模式下的代理链路原理，以及相关工程命令与目录结构，能够独立搭建并二次开发自己的 SkyPilot 控制台。

Dashboard 是什么

SkyPilot Dashboard 是一个基于 Next.js 目录。它不是一个独立的"玩具演示"，而是与 SkyPilot API Server（FastAPI 服务）深度耦合的官方前端：

从 src/pages 的页面结构可以看到，它提供了clusters（集群）、jobs（任务详情与日志）、infra（基础设施）、volumes（存储卷）、workspaces（工作区）、recipes（配方）、users（用户）、plugins（插件）、settings（设置）等完整的管理页面；
前端通过src/data/connectors目录下的连接器（connector）与 API Server 通信，例如 client.js 实现了统一的apiClient；
API Server 侧在 sky/server/server.py 中为 Dashboard 提供了静态资源托管、/internal/dashboard前缀路由和/dashboard_config配置端点。

因此，阅读本文前建议先了解 SkyPilot API Server 的启动方式：Dashboard 的一切数据都来自 API Server，二者必须搭配使用。

两种访问 Dashboard 的方式

根据 README，访问 Dashboard 有两种途径，取决于你的 SkyPilot 安装方式。

方式一：官方包安装后直接访问

如果你从官方渠道安装了 SkyPilot 发行包，Dashboard 的前端构建产物已经随包分发。只需启动 API Server，然后通过浏览器访问：

${API_Server_Endpoint}/dashboard

其中${API_Server_Endpoint}是 API Server 的地址。本地默认 API Server 地址为http://127.0.0.1:46580，因此本地访问地址为：

http://127.0.0.1:46580/dashboard

关于默认端口 46580，可以在 sky/server/common.py 中看到DEFAULT_SERVER_PORT = 46580的定义，它同时也可被SKYPILOT_API_SERVER_LOCAL_PORT环境变量覆盖。如果你将 API Server 部署在远端（例如http://skypilot-api.domain.com:30050），那么 Dashboard 就位于该端点下的/dashboard路径。

注意：从源码安装时，Dashboard 构建产物目录sky/dashboard/out默认不包含在内部 wheel 中（参见 sky/backends/wheel_utils.py 中关于排除sky/dashboard/out的处理逻辑），因此源码安装必须手动构建，见下文。

方式二：源码安装后手动构建

如果你通过源码方式安装 SkyPilot，在启动 API Server 之前，需要先手动生成 Dashboard 的生产构建（production build）。源码安装启动 API Server 时，sky/server/common.py 会检测DASHBOARD_DIR目录是否存在：

若不存在，提示你执行npm --prefix sky/dashboard install && npm --prefix sky/dashboard run build；
若存在但可能是过期版本，也会提示重新构建。

从源码构建 Dashboard（生产构建）

以下步骤严格对应 sky/dashboard/README.md 的 "Getting Started" 章节。

第一步：安装 Node.js 与 npm

Dashboard 工程要求 Node.js 18。README 推荐使用 nvm 安装：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 18 nvm use 18

说明：如果你的环境中 nvm 已就绪，可跳过 curl 安装步骤，直接nvm install 18 && nvm use 18。若此前安装依赖时因缓存导致权限问题，可以先执行npm cache clean --force清理缓存。

第二步：安装依赖并构建

在仓库根目录下进入 Dashboard 工程目录执行（README 中的命令默认在sky/dashboard目录内运行）：

# 安装当前目录下的全部依赖 npm install # 生成生产构建 npm run build

npm run build对应 package.json 中的脚本：next build && cp .next/routes-manifest.json out/routes-manifest.json。即先用 Next.js 执行生产构建，再把路由清单复制到导出目录out/，供 API Server 静态托管时解析路由使用。

构建完成后即可正常启动 API Server，并访问${API_Server_Endpoint}/dashboard。

构建配置说明

Dashboard 的生产构建行为由 next.config.mjs 控制，其中值得关注的关键配置：

basePath: process.env.NEXT_BASE_PATH || '/dashboard'：所有页面挂在/dashboard前缀下，这也解释了为什么访问路径是.../dashboard；
output: 'export'：采用静态导出模式，产物输出到out/目录；
env中注入了SKYPILOT_API_SERVER_ENDPOINT、SKYPILOT_RELEASE_NAME、INFRA_CACHE_DURATION_MINUTES（默认'10'）与INFRA_CACHE_DEBUG（默认'false'）等环境变量，供前端运行时读取。

运行 Dashboard 开发服务器

如果你需要修改 Dashboard 代码、调试页面或验证新功能，应使用开发服务器模式。开发服务器支持热更新，页面会随文件修改自动刷新。

安装依赖

npm install

同样，若遇到缓存权限问题可先执行npm cache clean --force。

配置 API Server 连接（可选）

默认情况下，开发服务器会连接本地 API Server，地址为http://127.0.0.1:46580。如果需要连接其他（如远端、集群内或带认证的）API Server，设置环境变量：

export SKYPILOT_API_SERVER_ENDPOINT=http://username:password@skypilot-api.domain.com:30050

这里username:password@是可选的 Basic Auth 凭据前缀。设置后，开发服务器对 API 的请求都会转发到该端点。

启动开发服务器

npm run dev

然后用浏览器打开：

http://localhost:3000/dashboard

即可看到运行结果。npm run dev对应 package.json 中的脚本node server.js。

开发服务器背后发生了什么

开发模式与生产模式共用同一个自定义服务器入口 server.js，理解它就能明白"开发服务器如何连接 API Server"：

它基于express+next启动，dev标志由NODE_ENV决定（开发模式走热更新渲染，生产模式npm start时走静态产物）；
监听 3000 端口，并输出> Ready on http://localhost:3000/dashboard；
通过http-proxy-middleware把三类请求代理到 API Server（默认目标为SKYPILOT_API_SERVER_ENDPOINT环境变量或http://localhost:46580）：
- /internal/dashboard→ 转发到 API Server 并去掉该前缀（pathRewrite: '^/internal/dashboard': ''），即浏览器请求/internal/dashboard/jobs会被转发为 API Server 的/jobs；
- /plugins→ 转发到 API Server 的/plugins（插件 JS 包静态资源）；
- /grafana→ 转发到 API Server 的/grafana（Grafana 监控面板嵌入）。

因此，只要SKYPILOT_API_SERVER_ENDPOINT指向正确的 API Server，前端所有数据请求都会被代理过去，无需在浏览器里做跨域配置。

前端如何调用 API：连接器与版本协商

为了让读者理解"前端联调"的本质，这里简要展开 README 未细讲、但对二次开发至关重要的连接层实现。

Dashboard 的 API 调用统一收敛在 src/data/connectors/client.js 的apiClient对象中，核心机制包括：

版本协商头：每次请求都会带上X-SkyPilot-API-Version（当前硬编码为'62'）与X-SkyPilot-Version两个头。API Server 的APIVersionMiddleware依赖这两个头判断客户端是否为新版客户端，两者缺一不可（详见 constants.jsx 中的注释，且有 tests/unit_tests/test_api_version_consistency.py 保证前后端版本号一致性）；
请求/响应模式：apiClient.fetch先 POST 提交请求，从响应头X-Skypilot-Request-ID拿到请求 ID，再通过${ENDPOINT}/api/get?request_id=...轮询获取结果——这是 SkyPilot API Server 典型的异步请求模型；
端点前缀：ENDPOINT在浏览器环境中动态从当前路径推导，即当前 URL 中/dashboard之前的部分 +/internal/dashboard（见 constants.jsx）。

API Server 侧对应的处理见 sky/server/server.py 的InternalDashboardPrefixMiddleware：它把/internal/dashboard/...前缀剥掉后映射到内部路由，从而让前端与内部 API 共用一套路由体系。同时 sky/server/server.py 的PathCleanMiddleware会对/dashboard/路径做路径穿越防护（path traversal），非法路径直接返回 403，保证静态资源安全。

常用开发命令速查

package.json 中定义了一组与开发、质量保障相关的脚本：

命令	作用	说明
`npm run dev`	启动开发服务器	等价于`node server.js`，默认监听 3000 端口
`npm run build`	生产构建	`next build`后复制`routes-manifest.json`到`out/`
`npm start`	以生产模式运行	`NODE_ENV=production node server.js`
`npm run lint`	静态代码检查	`next lint --max-warnings 0`，warning 即失败
`npm run lint:fix`	自动修复 lint 问题	`next lint --fix`
`npm run format`	用 prettier 格式化全部代码	`prettier --write .`
`npm run format:check`	检查格式是否符合 prettier	`prettier --check .`
`npm run test`	运行 Jest 单元测试	仓库内有大量`.test.jsx`测试用例
`npm run test:watch`	监听模式运行测试	`jest --watch`
`npm run stop`	停止开发服务器	杀掉 next 进程及 3000 端口占用进程

从源码理解 Dashboard 目录结构

初次接触 Dashboard 工程时，建议按以下脉络阅读 sky/dashboard/src：

src/pages/：页面路由定义，与浏览器 URL 一一对应（clusters.js、jobs.js、infra.js、volumes.js、workspaces.js、users.js、recipes.js、settings/等），以及各资源的详情页与动态路由（如jobs/[job]/[task].js、clusters/[cluster]/[job].js）；
src/components/：UI 组件，其中elements/是通用元素（状态徽章StatusBadge.jsx、分页PaginationControls.jsx、空状态EmptyState.jsx等），shared/是跨页面复用的过滤系统FilterSystem.jsx，ui/是基于 Radix 与 shadcn 风格的基础组件（table.jsx、dialog.jsx、yaml-editor.jsx等）；
src/data/connectors/：与 API Server 通信的连接层，client.js是核心请求客户端，各资源连接器（clusters.jsx、jobs.jsx、infra.jsx、volumes.jsx、workspaces.jsx、users.js、recipes.js）负责拉取并转换数据；
src/hooks/：React Hooks，如useLogStreamer.js（日志流式拉取）、useUrlFilterState.js（URL 过滤状态）、useUpgradeDetection.js（版本升级检测）、useTour.js（引导式教程）；
src/lib/：前端缓存与工具库，包括cache.js、jobs-cache-manager.js、analytics.js、yamlUtils.js；
src/plugins/：插件加载与插槽机制（PluginProvider.jsx、PluginSlot.jsx），配合 API Server 的/plugins代理实现可扩展 UI；
src/utils/：纯工具函数（apiInterceptor.js、gpuUtils.js、grafana.js、infraUtils.js、resourceUtils.js、externalLinks.js等）。

前端的过滤系统、缓存管理等关键逻辑均有配套的 Jest 测试（如src/components/shared/FilterSystem.test.jsx、src/lib/cache.test.js、src/data/connectors/jobs.test.jsx），二次开发时建议保持"改动必带测试"的习惯。

常见问题排查

Dashboard is not built提示：源码安装后未执行构建。回到仓库根目录执行npm --prefix sky/dashboard install && npm --prefix sky/dashboard run build（或按上文进入sky/dashboard目录操作）后重启 API Server；
Dashboard may be stale提示：检测到sky/dashboard/out已存在，但可能与当前代码不同步，重新执行npm run build即可；
开发服务器 3000 端口被占用：执行npm run stop清理残留进程，或自行处理占用 3000 端口的进程；
访问 Dashboard 页面空白/接口 401：确认SKYPILOT_API_SERVER_ENDPOINT指向的 API Server 已启动且端口正确（本地默认 46580）；若端点带认证，需按http://username:password@host:port格式携带凭据；
页面样式/路由 404：确认访问路径包含/dashboard前缀（开发模式为http://localhost:3000/dashboard），因为next.config.mjs中的basePath默认为/dashboard；
版本不一致报错：Dashboard 前端的CLIENT_API_VERSION与 sky/server/constants.py 的API_VERSION必须保持一致，二者随发行版本同步升级，本地开发时若前后端来自不同版本需统一。

小结

本文围绕 sky/dashboard/README.md 完整复现了 Dashboard 的两种使用路径：官方包安装后零构建直达，以及源码安装下"装 Node 18 →npm install→npm run build"三步构建；同时深入讲解了开发服务器模式下的代理链路（/internal/dashboard、/plugins、/grafana）、SKYPILOT_API_SERVER_ENDPOINT环境变量的作用，以及 API Server 侧的路由剥离、缓存与安全中间件。掌握了这些，你既可以按部就班地把 Dashboard 跑起来，也可以顺着 sky/dashboard/src 的目录脉络继续做二次开发与调试。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析