Communitygithub.com

Nuvraxis/nuvraxis-plugins

Helm chart 规则，用于 Nuvraxis Next.js 应用：每个应用在 charts/ 下拥有一个独立 chart，发布至 oci://ghcr.io/nuvraxis/charts 并由 Argo CD 同步；Chart.yaml 中的 version/appVersion 仅由 release.yaml 设置；部署包含 /api/health 探测、非 root 只读安全上下文、emptyDir 用于 .next/cache、ConfigMap 与现有 Secret 通过 envFrom、Service、Ingress 结合 cert-manager、HPA、PDB、ServiceAccount、拓扑分布；无 Helm hooks；需通过 helm lint --strict 和 kubeconform 验证。当仓库包含 charts/、Chart.yaml、values*.yaml、templates/*.yaml（Helm 语法），或存在 Argo CD Application，或要求在 Kubernetes 上部署、扩缩、暴露或配置应用时使用。

nuvraxis-plugins 是什么？

此技能为 Nuvraxis Next.js 应用定义了严格的 Helm chart 创建与维护规则。每个应用在仓库根目录 charts/<应用名>/ 下拥有独立 chart，通过 OCI 注册表 oci://ghcr.io/nuvraxis/charts 发布，并可被 Argo CD 同步。核心规则包括：禁止手动修改 version/appVersion 字段（由 release.yaml 基于 Git 标签自动设置）；image.tag 默认使用 appVersion，仅用于 Git 同步环境时需显式覆盖；所有探针（startup、liveness、readiness）均指向 /api/health 端点，不依赖后端服务以提高稳定性；安全上下文强制非 root、只读文件系统、禁止权限提升并丢弃所有能力；应用不调用 Kubernetes API，因此 automountServiceAccountToken 为 false；.next/cache 使用大小受限的 emptyDir 卷。配置通过 envFrom 注入，ConfigMap 用于非敏感变量，Secret 由外部服务（如 External Secrets）管理，chart 内不模板化密文。资源方面设置 CPU 和内存请求、内存限制但无 CPU 限制，以避免对 Node 服务器造成节流。默认高可用配置包括 2 个副本、PDB（maxUnavailable: 1）、滚动更新（maxUnavailable: 0）及跨可用区和节点的拓扑分布（ScheduleAnyway）。Ingress 为可选，通过 cert-manager 注解管理 TLS。技能还禁止使用 Helm hooks、lookup 和随机值，确保 Argo CD 渲染结果纯函数化。验证流程要求 helm lint --strict 和 kubeconform 严格检查所有 values 文件。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Nuvraxis/nuvraxis-plugins/tree/HEAD/plugins/nuvraxis-frontend/skills/helm-nextjs
查看原文→浏览所有技能

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

文档

Next.js 应用的 Helm chart

用于 charts/<应用>/ 以及 Argo CD 如何使用它。它运行的镜像来自 docker-nextjs；发布两者的流水线是 github-actions。

模板的 charts/__APP__/ 是唯一真相来源。所有带注释的值：references/values.md。Argo CD 配置：references/argocd.md。

规则

  1. 每个应用一个 chart，位于应用仓库根目录的 charts/<应用>/ 下。 原因：Argo CD 可以从 Git（path: charts/<应用>）直接同步用于开发环境，并从 OCI 注册表同步用于生产环境，文件相同；它位于 apps/ 之外，因此既不在 Docker 构建上下文中，也不是 pnpm workspace 包；chart 与需要它的代码在同一 PR 中变更。该 chart 特意设计为单应用：无 umbrella、无子 chart。仅当单个应用需要时，才使用基于值驱动的通用模板（如后台 umbrella chart）：ingress、HPA、PDB、拓扑分布。

  2. 永远不要手动编辑 version 或 appVersion。 两者在 Git 中均保持 0.0.0。release.yaml 从标签 vX.Y.Z 运行 helm package --version X.Y.Z --app-version vX.Y.Z，因此发布的 chart 和镜像标签始终匹配。

  3. image.tag 默认使用 appVersion；仅对 Git 同步环境进行设置。 从 OCI 获取时，appVersion 是发布标签，镜像为 ghcr.io/nuvraxis/<应用>:vX.Y.Z。从 Git 同步时，appVersion 为 0.0.0，因此 Argo CD Application 设置 image.tag: sha-<短 SHA>（或 main）。image.repository 始终小写。

  4. 探针：startup、liveness 和 readiness，均指向 /api/health。 startup 探针（2s × 30）覆盖启动过程；liveness 和 readiness 仅在其之后启动。该路由从不依赖任何依赖项，因此数据库故障不会重启 Pod。不要将探针指向 /：它会渲染页面。

  5. 安全上下文与镜像匹配：uid/gid 1001、runAsNonRoot、readOnlyRootFilesystem、无权限提升、丢弃所有能力、RuntimeDefault seccomp。 ServiceAccount 和 Pod 上均设置 automountServiceAccountToken: false：应用不调用 Kubernetes API。

  6. .next/cache 是带有 sizeLimit 的 emptyDir。 它是唯一的可写路径（/app/apps/<应用>/.next/cache）。该限制防止失控的镜像缓存填满节点。

  7. 通过 envFrom 配置：一个来自 values.config 的 ConfigMap，以及一个已存在的 Secret。

    config:
  API_BASE_URL: https://api.nuvraxis.com
existingSecret: portal-secrets

    chart 永远不会模板化密文值：无 kind: Secret 带来自 values 的 data、无 --set secret=…。Secret 由 External Secrets、Sealed Secrets 或 operator 创建，且仅在 values 中指定其名称。ConfigMap 变更通过 checksum/config 注解滚动 Pod。

  8. chart 中不包含 NEXT_PUBLIC_*。 它们在镜像构建时被编译进去（参见 docker-nextjs）；运行时设置它们无效。

  9. 资源：设置 CPU 和内存的 requests，设置内存 limit，不设置 CPU limit。 CPU limit 会在突发期间限制 Node 服务器并增加尾延迟；内存 limit 保持，因为 Node 的堆会增长到分配的大小。

  10. 默认高可用：2 个副本、PDB maxUnavailable: 1、滚动更新 maxUnavailable: 0、跨可用区和节点的拓扑分布（ScheduleAnyway）。 当 autoscaling.enabled 启用时，Deployment 省略 replicas，以避免 Argo CD 和 HPA 冲突。

  11. Ingress 为可选，通过 cert-manager 注解管理 TLS。 ingress.enabled、className、hosts、带有 secretName 的 tls，以及注解中的 cert-manager.io/cluster-issuer。对于 ingress-nginx 的流式响应，添加 nginx.ingress.kubernetes.io/proxy-buffering: "off"；对于速率限制，添加 limit-rps（参见 nextjs-security）。

  12. 无 Helm hooks、无 lookup、无随机值。 Argo CD 使用 helm template 渲染 chart 并应用结果：hooks 会变成具有不同语义的 Argo hooks，lookup 返回空值，randAlphaNum 在每次同步时变化并导致应用永久不同步。渲染的所有内容必须是值的纯函数。

  13. 私有 GHCR 包需要拉取凭据。 GHCR 包首次推送时默认为私有。对于镜像：一个包含具有 read:packages 权限的 token 的 docker-registry Secret，在 imagePullSecrets 中引用（生产 values 中引用 ghcr-pull）。对于 Argo CD 中的 chart：一个包含 enableOCI: "true" 的仓库 Secret（参见 references/argocd.md）。或者如果代码是公开的，在 GitHub 中将包设为公开。

  14. values-production.yaml 仅包含生产环境中不同的值。 分层使用：-f values.yaml -f values-production.yaml。不要将默认值复制到其中。

  15. 使用 helm lint --strict 和 helm template | kubeconform -strict 进行验证。 为什么选择 kubeconform 而不是 helm-unittest：单应用 chart 实际遇到的 bug 是渲染输出中的错误字段名、类型或 API 版本，kubeconform 可以针对真实的 Kubernetes schema 捕获这些问题，且无需编写任何测试代码。helm-unittest 用于断言模板逻辑，而这个 chart 几乎不需要。对两个 values 文件都运行 lint 和 validate，就像 pr.yaml 所做的那样。

添加内容

需求变更
运行时环境变量config: 在 values 中（非秘密）或现有 Secret 中的键
密文将其添加到外部 Secret；chart 中无需任何更改
另一个端口或 sidecar首先说明理由；一个 Next 应用只需要一个端口
CronJob一个单独的 chart 或应用，而非此 Deployment
NetworkPolicy添加 templates/networkpolicy.yaml，通过 networkPolicy.enabled 开关

验证

helm lint --strict charts/<应用>
helm lint --strict charts/<应用> -f charts/<应用>/values-production.yaml
helm template <应用> charts/<应用> -f charts/<应用>/values-production.yaml \
  | docker run --rm -i ghcr.io/yannh/kubeconform:v0.8.0 -strict -summary -kubernetes-version 1.34.0 -

来源

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Nuvraxis/nuvraxis-plugins

>- Biome 2.5 setup and rules for Nuvraxis monorepos — root biome.json with pinned $schema, VCS ignore, formatter settings, the recommended preset with a11y and the react/next domains, nursery policy, organize imports, overrides, nested per-package configs ("extends": "//"), biome check --write locally, biome ci in CI, VS Code settings, and migrating from ESLint/Prettier. Use when the repo has biome.json or biome.jsonc, @biomejs/biome in package.json, .eslintrc*/eslint.config.*/.prettierrc* to migrate, or when fixing lint and formatting errors.

Nuvraxis/nuvraxis-plugins

>- Dockerfile rules for Next.js standalone apps in a pnpm + Turborepo monorepo — multi-stage build (turbo prune → pnpm fetch/offline install → turbo build → minimal runner), pinned Node 26 Alpine by digest, checksum-verified pnpm binary, non-root uid 1001, read-only root filesystem with a writable .next/cache, HEALTHCHECK on /api/health, build args only for NEXT_PUBLIC_* values, BuildKit secrets and cache mounts, multi-arch, OCI labels and .dockerignore. Use when the repo has a Dockerfile, .dockerignore, compose file, or next.config with output "standalone", or when asked to containerise, shrink, harden or debug an image.

Nuvraxis/nuvraxis-plugins

>- GitHub Actions conventions for Nuvraxis Next.js apps — exactly three workflows: pr.yaml (every PR to any branch: Biome, stylelint, typecheck/test/build with turbo --affected, Docker build + health check, helm lint + kubeconform; publishes nothing), main.yaml (push to main: one multi-arch image to GHCR tagged sha-SHORTSHA and main, provenance + SBOM, gha cache), release.yaml (tag vX.Y.Z: verify on main, retag the existing image without rebuilding, package and push the Helm chart to OCI, GitHub Release with chart, digest and SBOM). Minimal permissions per job, GITHUB_TOKEN only, pinned action majors. Use when editing .github/workflows/*, adding a CI step, or debugging a failed run or release.

Nuvraxis/nuvraxis-plugins

>- Production rules for Next.js 16 App Router apps at Nuvraxis — Server/Client Component boundaries, Cache Components ("use cache", cacheLife, cacheTag, updateTag), Server Actions, route handlers, env handling, instrumentation, output standalone and the /api/health route. Use when the project has "next" in package.json, an app/ or src/app/ directory, next.config.ts, proxy.ts, instrumentation.ts, or files named page.tsx, layout.tsx, route.ts, loading.tsx, error.tsx.

相关技能

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community