Headlamp 插件发布与上架指南从打包到 Artifact Hub 全流程实战【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlamp本指南对应 Headlamp 官方入门教程系列的第 11 篇Getting Started Tutorial 11讲解如何把已经开发完成的hello-headlamp插件含侧边栏、页面、Kubernetes 数据集成、列表/详情视图、设置、自定义主题与 Map 节点推向正式发布并借助 Artifact Hub 让全球 Headlamp 用户能够发现、检索与安装它。读完本文你将掌握插件发布前的质量检查、构建打包、GitHub Release 托管、Artifact Hub 元数据编写与注册、以及后续版本更新的完整发布流程。发布就绪检查清单Release Readiness Checklist在打包与上架之前请按顺序逐项确认以下检查。按序执行能最快暴露最常见的问题#检查项命令为什么要做1代码格式统一npm run format风格一致是 ESLint 通过的前提2无 Lint 错误npm run lint提前捕获 bug 与代码质量问题3TypeScript 编译无错误npm run tsc在错误到达用户之前拦截类型问题4全部测试通过npm run test确认没有引入回归5版本号正确编辑package.json版本号决定 tarball 的文件名6构建成功npm run build产出生产环境用的dist/main.js7打包成功npm run package产出可上传的.tar.gz安装包下文将逐一展开每个检查项并给出可在本地直接复现的命令与预期输出。插件自带的 npm 脚本当你用npx kinvolk/headlamp-plugin create hello-headlamp创建插件时模板会生成一套封装了headlamp-pluginCLI 的 npm 脚本。仓库中的模板定义位于 plugins/headlamp-plugin/template/package.json生成的package.jsonscripts 段如下{ scripts: { start: headlamp-plugin start, build: headlamp-plugin build, format: headlamp-plugin format, lint: headlamp-plugin lint, lint-fix: headlamp-plugin lint --fix, package: headlamp-plugin package, tsc: headlamp-plugin tsc, storybook: headlamp-plugin storybook, storybook-build:headlamp-plugin storybook-build, test: headlamp-plugin test, i18n: headlamp-plugin i18n } }各脚本的作用如下脚本作用start监听src/目录变化并自动重新构建用于开发期build编译 TypeScript 并打包为dist/main.js用于生产format运行 Prettier 自动格式化全部源码lint运行 ESLint 并报告代码质量问题lint-fix运行 ESLint 并自动修复所有可修复项package将dist/打包为 Headlamp 约定格式的.tar.gztsc以仅检查模式运行 TypeScript 编译器找出类型错误storybook启动 Storybook 开发服务器用于构建组件 storystorybook-build构建静态 Storybook 站点test运行插件单元测试i18n抽取可翻译字符串用于国际化每次发布前必跑的四个脚本是format、lint、tsc、test随后是build和package。这些命令背后是kinvolk/headlamp-plugin当前仓库版本为 0.14.0见 plugins/headlamp-plugin/package.json提供的完整 CLI。在 plugins/headlamp-plugin/README.md 中可以查到headlamp-plugin --help的完整命令清单除上述脚本对应的命令外还包括create创建插件、extract提取已构建插件、upgrade升级 headlamp-plugin 并自动审计、格式化、lint、类型检查、以及list/install/update/uninstall等插件管理命令——后者的插件管理能力来自其底层依赖headlamp-k8s/pluginctl而headlamp-plugin在它之上叠加了完整的开发工具链。格式化代码Headlamp 插件使用 Prettier 进行代码格式化通过共享配置headlamp-k8s/eslint-config/prettier-config统一风格模板的prettier字段指向该配置见 plugins/headlamp-plugin/template/package.json。先跑格式化可以避免 linter 报出纯样式类错误。cd hello-headlamp npm run format一切正常时的输出类似hello-headlamp/src/index.tsx 52msPrettier 会逐个列出处理的文件如果某文件需要修改Prettier 会原地重写首次运行时会看到稍长的耗时。:::tip 格式化前先提交一次代码这样可以用git diff清晰看到格式化工具改了什么。 :::Lint 代码Lint 使用 ESLint 检查源码重点关注未使用的变量与导入列表缺少 React key prop可访问性问题jsx-a11y插件TypeScript 特定代码质量规则Headlamp 共享 ESLint 配置禁止的其它模式模板的eslintConfig实际扩展了headlamp-k8s、prettier与plugin:jsx-a11y/recommended三套配置这些都可以在 plugins/headlamp-plugin/template/package.json 中确认。npm run lint如果发现可自动修复的问题执行npm run lint-fix干净运行的输出如下 hello-headlamp0.1.0 lint headlamp-plugin lint任何报错都会包含文件路径、行号与违反规则的描述src/index.tsx 42:7 error unusedVar is defined but never used typescript-eslint/no-unused-vars ✖ 1 problem (1 error, 0 warnings)请先修复所有错误再继续——即使带着 lint 错误构建仍能成功但把已知问题交付给用户是不良实践。类型检查tsc脚本以--noEmit模式运行 TypeScript 编译器它会类型检查每个文件但不输出任何 JavaScript从而捕获 ESLint 无法发现的类型不匹配。npm run tsc干净运行不产生任何输出并以退出码0结束。任何错误都会带文件、行号与清晰描述src/index.tsx:78:24 - error TS2345: Argument of type string is not assignable to parameter of type number.继续之前必须修复所有 TypeScript 错误——类型错误是插件运行时崩溃最常见的根源。运行测试如果你编写了单元测试或有此计划现在就运行它们npm run test该命令通过headlamp-plugin test发现并运行src/下的全部*.test.ts(x)与*.spec.ts(x)测试文件并报告结果在当前仓库中kinvolk/headlamp-plugin的测试基础设施基于 Vitest见 plugins/headlamp-plugin/config/vite.config.mjs 中的 test 配置PASS src/components/MyPage.test.tsx MyPage ✓ renders without crashing (23 ms) ✓ displays cluster name (18 ms) Test Suites: 1 passed, 1 total Tests: 2 passed, 2 total所有测试必须通过后才能继续。设置版本号插件版本遵循语义化版本Semantic Versioning即MAJOR.MINOR.PATCH段何时递增示例MAJOR破坏性变更——移除或改变既有行为1.0.0 → 2.0.0MINOR以向后兼容方式新增功能1.0.0 → 1.1.0PATCH纯 bug 修复无新功能或破坏性变更1.0.0 → 1.0.1首次公开发布通常从1.0.0开始。模板默认从0.1.0起步——该版本号表示尚未稳定适合早期开发阶段。打开package.json更新version字段{ name: hello-headlamp, version: 1.0.0, description: A Headlamp plugin tutorial series — sidebar, data, settings, themes, and map nodes., ... }这里设置的版本号直接决定npm run package产出的 tarball 文件名hello-headlamp-1.0.0.tar.gz并且必须与稍后写入artifacthub-pkg.yml的版本一致。生产构建build命令编译 TypeScript 源码并打包成dist/main.js——这是 Headlamp 运行时加载的单一 JavaScript 文件npm run build你会看到类似如下的 Vite 输出 hello-headlamp1.0.0 build headlamp-plugin build Building . for production with plugin name: hello-headlamp... Injecting env var: NODE_ENV production vite v6.4.1 building for production... Plugin name detected: hello-headlamp ✓ 4 modules transformed. dist/main.js 11.90 kB │ gzip: 4.23 kB ✓ built in 135ms Successfully copied extra dist files Finished building . for production.关键产物是dist/main.js这是 Headlamp 在运行时真正加载的文件。:::notenpm run start开发监听器也会写入dist/main.js但该构建未压缩也未优化。发布时务必使用npm run build。 :::从源码角度可以进一步理解这个单一文件是如何形成的headlamp-plugin的构建基于 Vite 的库模式UMD 格式并把 React、MUI、react-router、recharts、kinvolk/headlamp-plugin提供的ApiProxy、Crd、K8s、CommonComponents等一整套前端依赖声明为 external运行时统一由 Headlamp 通过pluginLib全局对象注入见 plugins/headlamp-plugin/config/vite.config.mjs 的externalModules映射。这正是插件包能保持极小体积、且与宿主 Headlamp 版本共享同一套库实例的原因——也解释了为什么artifacthub-pkg.yml需要声明version-compat兼容范围。打包插件package命令把dist/目录打包成 Headlamp 安装约定格式的.tar.gztarballnpm run package输出会明确告知生成了什么以及上架 Artifact Hub必需的 SHA256 校验和Created tarball: hello-headlamp-1.0.0.tar.gz Tarball checksum (SHA256): a3b4c5d6e7f8...:::important务必保存该校验和稍后要写入artifacthub-pkg.yml。如果丢失可在 Linux/macOS 上用sha256sum hello-headlamp-1.0.0.tar.gz重新计算Windows 上使用Get-FileHash。 :::tarball 里有什么tarball 至少始终包含hello-headlamp/ ├── main.js ← 编译后的插件 bundle └── package.json ← 插件元数据name、version、description如果插件使用了国际化npm run package会自动把翻译文件也打进去hello-headlamp/ ├── main.js ├── package.json └── locales/ ← i18n 翻译文件仅当存在 locales/ 目录时 ├── en/ │ └── translation.json └── ...你还可以通过package.json的headlamp.extraDist字段声明需要额外打包的文件{ headlamp: { extraDist: { assets/logo.png: src/assets/logo.png } } }这会把src/assets/logo.png复制进 tarball 并命名为hello-headlamp/assets/logo.png。这与桌面端安装器在解析插件包时读取的元数据结构一一对应——在 app/electron/plugin-management.ts 中安装逻辑会读取归档内的package.json与extraDist清单来确定解压后的文件布局。创建 GitHub Release出于安全考虑Headlamp 只允许从GitHub、GitLab 或 Bitbucket下载插件。GitHub Release 是托管 tarball 的标准方式便于 Artifact Hub 引用。推送代码如果还没把插件推到 GitHub现在执行# 在 hello-headlamp/ 目录内 git init # 如果还不是 git 仓库 git add . git commit -m chore: release v1.0.0 git remote add origin https://github.com/YOUR_USERNAME/hello-headlamp.git git push -u origin main打版本标签Git 标签是 GitHub 识别发布版本的依据。按惯例语义化版本的标签加v前缀git tag v1.0.0 git push origin v1.0.0在 GitHub 上创建 Release进入你的 GitHub 仓库。点击Releases→Draft a new release。在 Choose a tag 中选择刚推送的v1.0.0标签。将 release 标题设为v1.0.0。添加变更说明。在Assets下点击Attach binaries上传hello-headlamp-1.0.0.tar.gz。点击Publish release。发布后点击.tar.gz资产复制下载 URL形如https://github.com/YOUR_USERNAME/hello-headlamp/releases/download/v1.0.0/hello-headlamp-1.0.0.tar.gz稍后要把这个 URL 填进artifacthub-pkg.yml。Headlamp 如何使用 Artifact HubArtifact Hub 是一个云原生软件包的开源中心。Headlamp 的Plugin Catalog桌面应用内置的插件管理器直接读取 Artifact Hub 上的插件元数据来构建可用插件列表。整体流转如下你的 GitHub 仓库 │ │ artifacthub-repo.yml ← 证明你拥有该仓库 │ artifacthub-pkg.yml ← 描述该插件 │ ▼ Artifact Hub (artifacthub.io) │ │ 扫描并索引你的插件 │ ▼ Headlamp Plugin Catalog │ │ 从 Artifact Hub API 读取插件列表 │ 从 GitHub Release 下载 tarball │ ▼ 用户的 Headlamp 安装在前端源码中可以找到这条链路的具体实现桌面应用通过 frontend/src/components/App/pluginManager.ts 中的PluginManager.install()向 Electron 主进程发送INSTALL动作携带的 URL 就是 Artifact Hub 的https://artifacthub.io/packages/headlamp/repo_name/plugin_name形式而 frontend/src/helpers/backendTokenFetch.test.ts 则展示了前端如何代理请求https://artifacthub.io/api/v1/packages/search来获取插件搜索结果。安装时插件包的解压、兼容性校验与归档 URL 白名单校验仅允许 GitHub/GitLab/Bitbucket 域名位于 app/electron/plugin-management.ts 的validateArchiveURL与下载安装逻辑中。需要在仓库中添加两个 YAML 文件文件位置用途artifacthub-repo.yml仓库根目录声明对仓库的所有权artifacthub-pkg.yml插件文件夹根目录描述单个插件包添加 Artifact Hub 仓库文件在你的 GitHub 仓库根目录不是插件文件夹内创建artifacthub-repo.ymlowners: - name: Your Name email: your-emailexample.com把Your Name和your-emailexample.com替换为你的真实姓名以及注册 Artifact Hub 时使用的邮箱。Artifact Hub 借此验证你对所注册仓库的所有权。如果仓库包含多个插件每个插件一个文件夹根目录下这一个artifacthub-repo.yml即可覆盖全部插件。添加 Artifact Hub 包文件在插件文件夹根目录与package.json同级创建artifacthub-pkg.ymlversion: 1.0.0 name: hello-headlamp displayName: Hello Headlamp createdAt: 2025-01-20T00:00:00Z description: A complete Headlamp plugin tutorial: sidebar navigation, Kubernetes data, list and detail views, plugin settings, custom themes, and map visualization. annotations: headlamp/plugin/archive-url: https://github.com/YOUR_USERNAME/hello-headlamp/releases/download/v1.0.0/hello-headlamp-1.0.0.tar.gz headlamp/plugin/archive-checksum: SHA256:a3b4c5d6e7f8... headlamp/plugin/version-compat: 0.22 headlamp/plugin/distro-compat: in-cluster,web,docker-desktop,desktop:::tip 真实案例参考 KEDA 插件的artifacthub-pkg.yml是生产级文件的良好参照。 :::字段参考字段必填说明version是必须与package.json及 GitHub 标签中的版本一致name是唯一标识符小写、用连字符或下划线用于 Artifact Hub URLdisplayName是Plugin Catalog 中展示的人类可读名称createdAt是本次发布的 ISO 8601 时间戳description是Plugin Catalog 搜索结果中展示的简短摘要logoURL否方形 PNG/SVG 徽标 URL强烈建议提供提升可见度注解参考Headlamp 特有的元数据放在annotations块中注解必填说明headlamp/plugin/archive-url是GitHub或 GitLab/Bitbucket上.tar.gz的直接下载 URLheadlamp/plugin/archive-checksum是tarball 的 SHA256 校验和带SHA256:前缀大写——由npm run package输出headlamp/plugin/version-compat否所需的最低 Headlamp 版本语义化版本范围如0.22headlamp/plugin/distro-compat否插件兼容的 Headlamp 发行版逗号分隔这些字段与桌面端安装器的数据模型一一对应在 app/electron/plugin-management.ts 中插件包元数据结构包含version、archiveURL、archiveChecksum、distroCompat、versionCompat等字段安装时校验归档 URL 是否合法、并用versionCompat检查插件与当前 Headlamp 版本的兼容性不兼容则拒绝安装并提示用户。distro-compat可选值值说明in-clusterHeadlamp 运行在 Kubernetes 集群内如通过 Helm 部署web无桌面包装、通过浏览器访问的 Headlampdocker-desktopHeadlamp Docker Desktop 扩展desktopHeadlamp 桌面应用Windows、macOS、Linuxlinux仅 Linux 桌面应用windows仅 Windows 桌面应用mac仅 macOS 桌面应用如果插件处处可用使用in-cluster,web,docker-desktop,desktop如果依赖仅桌面应用才有的特性就只写desktop。version-compat取值建议查阅 Headlamp release notes确认你所用 API 引入的版本。如果不确定对使用本系列教程 API 开发的插件0.22是安全的起点。推送到 GitHub把两个文件加入仓库、提交并推送# 在仓库根目录 git add artifacthub-repo.yml hello-headlamp/artifacthub-pkg.yml git commit -m chore: add Artifact Hub metadata git push origin main如果你的仓库只包含一个插件本系列采用的结构中插件文件夹就是仓库根目录两个文件位于同一目录git add artifacthub-repo.yml artifacthub-pkg.yml git commit -m chore: add Artifact Hub metadata git push origin main在 Artifact Hub 上注册访问 artifacthub.io 并登录或免费创建账户。打开Control Panel右上角用户菜单 → Control Panel。在 Repositories 部分点击Add按钮。填写表单Kind:Headlamp pluginName:仓库条目名称如hello-headlampDisplay name:人类可读名称URL:你的 GitHub 仓库 URL如https://github.com/YOUR_USERNAME/hello-headlamp点击Add。Artifact Hub 会在几分钟内扫描你的仓库。如果找到有效的artifacthub-repo.yml和artifacthub-pkg.yml插件就会出现在Headlamp分类下。:::info官方 vs 社区插件默认情况下Headlamp 的 Plugin Catalog 只显示在 Artifact Hub 中标记为官方、或位于 Headlamp 允许列表上的插件。社区插件仍会上架 Artifact Hub 且可正常安装——用户只需在 Plugin Catalog 设置中启用Show all plugins即可看到。这是一项安全措施而非质量门槛。 :::索引完成后你的插件 Artifact Hub URL 形如https://artifacthub.io/packages/headlamp/YOUR_REPO/hello-headlamp发布更新当你做了改动并想发布新版本时按以下步骤操作运行发布前检查npm run format npm run lint npm run tsc npm run test递增版本号按 SemVer 更新package.json中的version# 使用 npm 内置版本命令会更新 package.json 并创建 git 标签 npm version patch # 1.0.0 → 1.0.1 (bug 修复) npm version minor # 1.0.0 → 1.1.0 (新功能) npm version major # 1.0.0 → 2.0.0 (破坏性变更)也可以手动编辑package.json。构建与打包npm run build npm run package记下输出中的新校验和。创建新的 GitHub Release推送新标签并上传新 tarballgit push origin main git push origin --tags # 推送 npm version 创建的标签然后为新标签创建 GitHub Release 并附加新的.tar.gz。更新artifacthub-pkg.yml更新三个字段version: 1.0.1 # ← 新版本号 createdAt: 2025-03-01T00:00:00Z # ← 今天的日期 annotations: headlamp/plugin/archive-url: https://github.com/YOUR_USERNAME/hello-headlamp/releases/download/v1.0.1/hello-headlamp-1.0.1.tar.gz headlamp/plugin/archive-checksum: SHA256:new-checksum # ← 来自 npm run package 输出提交并推送git add package.json artifacthub-pkg.yml git commit -m chore: release v1.0.1 git push origin mainArtifact Hub 会在下一次扫描时自动拾取新的artifacthub-pkg.yml并更新列表。已安装旧版本的用户会在 Plugin Catalog 中看到可用更新。下一步恭喜——你已完成整个Getting Started入门教程系列你的hello-headlamp插件现在✅ 向应用栏添加了按钮✅ 有侧边栏条目与自定义页面✅ 获取并展示 Kubernetes 数据✅ 提供带自定义列的列表与详情视图✅ 扩展了既有资源详情页✅ 有可配置的设置页✅ 注册了自定义主题✅ 为 Map 视图贡献了节点✅ 已构建、打包并发布到 Artifact Hub快速参考发布前命令npm run format # 用 Prettier 自动格式化 npm run lint # 用 ESLint 检查代码问题 npm run lint-fix # 自动修复 ESLint 可修复项 npm run tsc # TypeScript 类型检查成功时无输出 npm run test # 运行单元测试发布命令npm run build # 编译 TypeScript → dist/main.js npm run package # 打包 dist/ → hello-headlamp-X.Y.Z.tar.gz 并输出校验和artifacthub-repo.yml仓库根目录owners: - name: Your Name email: your-emailexample.comartifacthub-pkg.yml插件根目录version: 1.0.0 name: hello-headlamp displayName: Hello Headlamp createdAt: 2025-01-20T00:00:00Z description: My Headlamp plugin description. logoURL: https://raw.githubusercontent.com/YOUR_USERNAME/hello-headlamp/main/logo.png annotations: headlamp/plugin/archive-url: https://github.com/YOUR_USERNAME/hello-headlamp/releases/download/v1.0.0/hello-headlamp-1.0.0.tar.gz headlamp/plugin/archive-checksum: SHA256:checksum from npm run package headlamp/plugin/version-compat: 0.22 headlamp/plugin/distro-compat: in-cluster,web,docker-desktop,desktop相关源码参考plugins/headlamp-plugin/template/package.json — 插件模板与全部 npm 脚本plugins/headlamp-plugin/README.md —headlamp-pluginCLI 完整命令清单plugins/headlamp-plugin/config/vite.config.mjs — 构建配置与pluginLibexternal 映射app/electron/plugin-management.ts — 安装器数据模型、归档 URL 校验与兼容性检查frontend/src/components/App/pluginManager.ts — 桌面端 Plugin Catalog 的安装/更新/卸载入口【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlamp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考