Communitygithub.com

Nuvraxis/nuvraxis-plugins

Nuvraxis Next.js 應用程式的 Helm Chart 規則 — 每個應用程式在 charts/ 下有一個 Chart（以應用程式命名），發佈至 oci://ghcr.io/nuvraxis/charts，並由 Argo CD 同步；Chart.yaml 中的 version/appVersion 僅由 release.yaml 設定；包含 startup/liveness/readiness 探針、非 root 唯讀安全上下文、emptyDir、ConfigMap + 現有 Secret、Service、Ingress（搭配 cert-manager）、HPA、PDB、ServiceAccount、拓撲分佈；無 Helm hooks；使用 helm lint --strict + kubeconform 驗證。

nuvraxis-plugins 是什麼？

此技能定義了一套嚴謹的 Helm Chart 規則，專為 Nuvraxis Next.js 應用程式設計。它強制每個應用程式在儲存庫根目錄的 charts/<app>/ 下擁有獨立 Chart，以支援 Argo CD 進行 Git 同步或 OCI 註冊表部署。核心規則包括：禁止手動編輯 version/appVersion（由 release.yaml 根據 Git 標籤設定）、使用 /api/health 端點進行 startup/liveness/readiness 探針、強制非 root 唯讀安全上下文（uid/gid 1001）、以及使用 emptyDir 管理 .next/cache 目錄。配置管理上，透過 envFrom 注入 ConfigMap（可觸發滾動更新）和既有的 Secret（避免在 Chart 中模板化敏感資料），且不包含 NEXT_PUBLIC_* 變數（已在建置階段處理）。技能也涵蓋高可用性預設值（2 個副本、PDB maxUnavailable: 1、滾動更新策略、ScheduleAnyway 拓撲分佈）、選擇性的 Ingress 搭配 cert-manager TLS、資源限制（無 CPU 限制）、以及無 Helm hooks、lookup 或隨機值的純函數渲染原則。驗證方面，要求同時對 values.yaml 和 values-production.yaml 執行 helm lint --strict 和 kubeconform，以確保輸出的 Kubernetes 資源語法正確。此技能主要支援的命令列工具為 Helm 和 Argo CD，並可與 kubeconform 搭配使用。

相容平台~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/<app>/ 以及 Argo CD 如何使用它。Chart 所運行的映像來自 docker-nextjs；同時發佈這兩者的管道是 github-actions。

模板中的 charts/__APP__/ 是源頭。所有含註解的 values 請見：references/values.md。Argo CD 的接線方式請見：references/argocd.md。

規則

  1. 每個應用程式一個 Chart，位於應用程式儲存庫根目錄的 charts/<app>/。 為何放在那裡：Argo CD 可以直接從 git 同步（path: charts/<app>）用於開發環境，並從 OCI 註冊表用於生產環境，使用相同的檔案；它位於 apps/ 之外，因此既不在 Docker 建置環境中，也不在 pnpm 工作區套件內；而且 Chart 的變更與需要它的程式碼在同一個 PR 中。Chart 是專為單一應用程式設計的：沒有總 chart，沒有子 chart。僅在單一應用程式需要切換時，才使用通用、由 values 驅動的模板（如後端總 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/<app>:vX.Y.Z。從 git 同步時，appVersion 為 0.0.0，因此 Argo CD Application 會設定 image.tag: sha-<short-sha>（或 main）。image.repository 始終為小寫。

  4. 探針：startup、liveness 和 readiness，全部指向 /api/health。 startup 探針（2 秒 × 30 次）涵蓋啟動過程；liveness 和 readiness 僅在它之後才開始。該路由永不觸及任何依賴項，因此資料庫中斷不會重新啟動 Pod。不要將探針指向 /：它會渲染一個頁面。

  5. 安全上下文與映像匹配：uid/gid 1001、runAsNonRoot、readOnlyRootFilesystem、無權限提升、捨棄所有能力、RuntimeDefault seccomp。 automountServiceAccountToken: false 同時設定在 ServiceAccount 和 Pod 上：應用程式不會呼叫 Kubernetes API。

  6. .next/cache 是一個帶有 sizeLimit 的 emptyDir。 它是唯一可寫入的路徑（/app/apps/<app>/.next/cache）。限制可以防止失控的映像快取填滿節點。

  7. 透過 envFrom 進行配置：一個來自 values.config 的 ConfigMap，以及一個已存在的 Secret。

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

    Chart 永遠不會模板化 Secret 值：沒有包含從 values 取得 data 的 kind: Secret，沒有 --set secret=…。Secret 是由 External Secrets、Sealed Secrets 或運算子建立的，只有其名稱存在於 values 中。ConfigMap 的變更會透過 checksum/config 註解滾動 Pod。

  8. Chart 中沒有 NEXT_PUBLIC_*。 它們在建置映像時就已嵌入（請參閱 docker-nextjs）；在執行時期設定它們不會有任何作用。

  9. 資源：請求 CPU 和記憶體、記憶體限制、無 CPU 限制。 CPU 限制會在流量高峰時限制 Node 伺服器並增加尾端延遲；記憶體限制則保留，因為 Node 的堆積會增長到分配的大小為止。

  10. 預設高可用性：2 個副本、PDB maxUnavailable: 1、滾動更新策略 maxUnavailable: 0、跨可用區和節點的拓撲分佈（ScheduleAnyway）。 啟用 autoscaling.enabled 時，Deployment 會省略 replicas，這樣 Argo CD 和 HPA 就不會爭奪它。

  11. Ingress 為選擇性啟用，TLS 透過 cert-manager 註解處理。 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 會在每次同步時變化，導致應用程式永遠顯示為不同步。所有渲染的內容必須是 values 的純函數。

  13. 私有 GHCR 套件需要拉取憑證。 GHCR 套件在首次發佈時是私有的。對於映像：一個帶有 read:packages 權杖的 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 實際會遇到的錯誤是渲染輸出中的錯誤欄位名稱、類型或 API 版本，kubeconform 可以針對真實的 Kubernetes 架構在零測試程式碼的情況下捕捉到這些錯誤。helm-unittest 斷言的是模板邏輯，而這個 Chart 幾乎沒有。如同 pr.yaml 所做的那樣，對兩個 values 檔案都進行 lint 和驗證。

新增項目

需求變更方式
一個執行時期環境變數values 中的 config:（非機密）或現有 Secret 中的一個金鑰
一個 Secret將其新增到外部的 Secret；Chart 中不需任何變更
另一個埠或 sidecar先證明其必要性；一個 Next 應用程式只需要一個埠
一個 CronJob一個單獨的 Chart 或應用程式，不是這個 Deployment
NetworkPolicy新增 templates/networkpolicy.yaml，由 networkPolicy.enabled 切換

驗證

helm lint --strict charts/<app>
helm lint --strict charts/<app> -f charts/<app>/values-production.yaml
helm template <app> charts/<app> -f charts/<app>/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