Bỏ qua đến nội dung
ShopNexus Docs
Trên trang này Các node 1/7

Một cluster k3d tên shopnexus chạy hai stack ShopNexus là dev và prod. Mỗi stack nằm trong namespace riêng và có database, cluster Restate, object store và hub AI của riêng nó. Argo CD giữ cả hai stack khớp với repo tổng; bản thiết kế nằm ở docs/superpowers/specs/2026-11-04-infra-k3d-stacks-design.md.

Các node

Cả hai file cấu hình k3d, infra/cluster/k3d-direct.yaml và infra/cluster/k3d-behind-proxy.yaml, tạo một server node và ba agent từ image rancher/k3s:v1.37.1-k3s1. Mỗi agent đóng vai một máy và mang một nhãn role mà các workload của chart ưu tiên.

NodeNhãnƯu tiên chạy
server-0control planeTraefik (cả hai cấu hình biên ghim nó ở đây bằng nodeSelector)
agent-0role=statefulRustFS
agent-1role=appserver, website, docs, console, ai-gateway, ai-models
agent-2role=appgiống agent-1
flowchart TB
  subgraph s0["server-0 (control plane)"]
    traefik[Traefik]
  end
  subgraph a0["agent-0, role=stateful"]
    rustfs[rustfs]
  end
  subgraph a1["agent-1, role=app"]
    app1["server, website, docs,<br/>console, ai-gateway, ai-models"]
  end
  subgraph a2["agent-2, role=app"]
    app-android["server, website, docs,<br/>console, ai-gateway, ai-models"]
  end
  spread["pod postgres và restate:<br/>mỗi node một pod nếu được"] -.-> a0
  spread -.-> a1
  spread -.-> a2
  traefik --> app1
  traefik --> app-android
  traefik --> rustfs
Pod ưu tiên chạy ở đâu

Mọi quy tắc xếp chỗ đều là ưu tiên. Node affinity theo role và pod anti-affinity của server, website, docs, console dùng preferredDuringSchedulingIgnoredDuringExecution. CloudNativePG dùng podAntiAffinityType: preferred, còn RestateCluster rải pod bằng topologySpreadConstraints với whenUnsatisfiable: ScheduleAnyway. Vì vậy pod vẫn được xếp lịch khi một agent bị dừng; khi cả ba agent chạy, ba pod Restate của prod nằm trên ba agent.

k3d chạy mỗi node thành một container Docker trên cùng một host, nên các agent dùng chung một kernel và một ổ đĩa. Với Kubernetes, dừng một agent bằng docker stop vẫn giống mất một máy, và các bài diễn tập failover cần đúng điều đó. Đây là dự án để học, và k3d giữ chi phí ở mức một máy. Không file nào ngoài infra/cluster/ nhắc tới k3d, nên chuyển sang k3s trên máy thật chỉ đổi infra/cluster/.

Các stack

devprod
Tên miềndev.shopnexus.id.vnshopnexus.id.vn
Namespaceshopnexus-devshopnexus-prod
Namespace Restaterestate-devrestate-prod
Application Argo CDstack-devstack-prod
File valuesvalues-dev.yamlvalues-prod.yaml
APP_ENVdevprod
Image:main, theo digestX.Y.Z của bản phát hành vX.Y.Z của repo tổng

RestateCluster của một stack tên là restate-<stack>, và restate-operator đặt nó vào namespace cùng tên. Chart tạo namespace đó ở sync wave -1 để restate-secrets đã seal có mặt trước khi cluster khởi động. NetworkPolicy chặn mọi ingress trong namespace của stack và chỉ mở những đường stack cần (Biên và mạng liệt kê chúng). Không policy nào mở đường giữa shopnexus-dev và shopnexus-prod.

Các thành phần

Mỗi dòng là một resource mà chart trong infra/stack render vào namespace của stack. Số lượng lấy từ values.yaml (dev) và values-prod.yaml (prod).

Thành phầnKindCổngdevprod
serverRestateDeployment8080 HTTP, 9080 Restate13
websiteDeployment300012
docsDeployment8011
consoleDeployment8012
postgresCluster của CloudNativePG54321 instance, 5Gi2 instance, 10Gi
restate-<stack>RestateCluster8080 ingress, 9070 admin1 node, 2 GiB3 node, 4 GiB
rustfsStatefulSet90001, 10Gi1, 10Gi

Application ai-<stack> render ai-gateway (cổng 4000) và ai-models (cổng 8000) vào cùng namespace từ chart của repo ai, mỗi thứ một replica ở cả hai stack.

Restate nhân bản mỗi partition ra min(2, replicas) node, tức 1 bản ở dev và 2 bản ở prod. Postgres chạy image paradedb/paradedb:0.26.4-pg18; ai-gateway có database riêng litellm trên cùng cluster CloudNativePG. Service server-api ở cổng 8080 chọn mọi pod server thuộc mọi phiên bản, còn restate-operator tạo cho mỗi phiên bản server một Service ở cổng 9080.

Ba Job chạy dưới dạng Sync hook của Argo CD:

JobWaveViệc làm
migrate1chạy migration của server (cmd/migrate)
objectstore-init1tạo bucket shopnexus
objectstore-init-snapshots1tạo bucket restate-snapshots

Argo CD áp dụng một stack theo các sync wave từ -1 tới 2. Bảng ghi mỗi wave gồm những gì, cùng các workload có trạng thái, nằm ở trang Postgres, Restate và RustFS.

App-of-apps

Ở lần khởi động đầu, k3s cài Argo CD (chart argo-cd 10.11.7, namespace argocd) từ infra/cluster/argocd.yaml và apply một Application duy nhất là root; cả hai file đến từ danh sách files: trong file cấu hình k3d. Từ đó Argo CD quản lý mọi thứ còn lại, kể cả root. Khi server node khởi động lại, k3s apply lại bản root.yaml nó nhận lúc tạo cluster, và self-heal của Argo CD đưa bản trong git trở lại trong vòng vài phút.

flowchart LR
  root["root<br/>infra/platform + infra/argocd"]
  root -->|wave 0| cnpg["cnpg<br/>cloudnative-pg 0.29.1<br/>ns cnpg-system"]
  root -->|wave 0| ss["sealed-secrets<br/>sealed-secrets 2.22.0<br/>ns kube-system"]
  root -->|wave 0| iuapp["image-updater<br/>argocd-image-updater 1.4.0<br/>ns argocd"]
  root -->|wave 0| ro["restate-operator<br/>restate-operator-helm 3.2.0<br/>ns restate-operator"]
  root -->|wave 1| dev["stack-dev<br/>infra/stack + values-dev.yaml"]
  root -->|wave 1| prod["stack-prod<br/>infra/stack + values-prod.yaml<br/>ở vX.Y.Z"]
  root -->|wave 1| iu["ImageUpdater shopnexus"]
  root -->|wave 2| aidev["ai-dev<br/>repo ai, chart/"]
  root -->|wave 2| aiprod["ai-prod<br/>repo ai, chart/"]
  iu -. "digest của :main" .-> dev
  iu -. "digest của :main" .-> aidev
  dev --> devns[shopnexus-dev]
  prod --> prodns[shopnexus-prod]
  aidev --> devns
  aiprod --> prodns
Các Application trong Argo CD

root có hai nguồn trong repo tổng: infra/platform, chứa một Application cho mỗi chart nền tảng, và infra/argocd, chứa chính root.yaml, stack-dev, stack-prod, ImageUpdater, cùng ai-dev và ai-prod trong ai.yaml. Các chart nền tảng lấy từ Helm repository gốc của chúng, không được vendor vào repo. Chart của restate-operator được đọc từ GHCR dưới dạng OCI repository qua Secret repo-restatedev-oci. ai-dev và ai-prod render chart trong chart/ của repo ai (shopnexus/ai) vào namespace của stack, ai-dev ở nhánh main và ai-prod ở commit ai của bản phát hành, sau các stack; trang Hub AI mô tả chúng.

Từ bản 1.8, Argo CD không còn tự đánh giá health của một Application. Phần values trong infra/cluster/argocd.yaml thêm một health check cho argoproj.io/Application, nhờ đó root chờ các Application nền tảng ở wave 0 Healthy rồi mới tạo các stack ở wave 1. Mọi Application tự sync với prune và selfHeal, và retry không giới hạn. root bỏ qua /spec/source/helm/parameters trên các Application, vì Image Updater ghi tag image của stack-dev và ai-dev vào đó và self-heal sẽ đặt lại giá trị cũ nếu không bỏ qua.

Cấu trúc thư mục

infra/
infra/
├── check.sh                      # lint chart, chạy test của chart, kiểm Argo CD và biên; CI chạy file này
├── smoke.hurl                    # hurl --test --variable domain=<domain>: gọi mọi host của một stack
├── go.mod                        # module Go cho cmd/
├── cmd/
│   └── seal/                     # go -C infra run ./cmd/seal dev|prod [-dry-run]: seal secret của một stack
│       ├── main.go
│       └── main_test.go          # go -C infra test ./...; cần Docker
├── cluster/                      # dùng một lần cho mỗi máy; phần duy nhất gắn với k3d
│   ├── k3d-direct.yaml           # cấu hình k3d: Traefik trên 80/443 với ACME, Argo CD, root
│   ├── k3d-behind-proxy.yaml     # cấu hình k3d: Traefik sau một proxy, tại 127.0.0.1:18080, Argo CD, root
│   └── argocd.yaml               # HelmChart của k3s: Argo CD, kèm health check cho Application
├── argocd/
│   ├── root.yaml                 # app-of-apps
│   ├── stacks.yaml               # stack-dev, stack-prod và ImageUpdater
│   └── ai.yaml                   # ai-dev, ai-prod: chart của repo ai, ngân sách key theo stack
├── platform/                     # mỗi chart gốc một Application
│   ├── cnpg.yaml
│   ├── image-updater.yaml
│   ├── restate-operator.yaml
│   └── sealed-secrets.yaml
└── stack/                        # Helm chart "shopnexus": một stack
    ├── Chart.yaml
    ├── values.yaml               # giá trị mặc định, cũng là giá trị của dev
    ├── values-dev.yaml           # stack, domain, appEnv, loại vector nào bật
    ├── values-prod.yaml          # như trên, thêm replica, storage và tag 0.1.0
    ├── secrets/
    │   ├── example.env           # mẫu mà cmd/seal chép thành <stack>.env
    │   ├── dev/                  # SealedSecret của stack-dev, có commit
    │   └── prod/                 # SealedSecret của stack-prod, có commit
    ├── templates/                # server, web, postgres, restate, rustfs,
    │                             # jobs, ingress, networkpolicy, secrets, validate
    └── tests/                    # các suite helm-unittest, và SealedSecret mẫu mà chúng render cùng

Lệnh seal giữ các khóa nó sinh ra trong infra/stack/secrets/<stack>.env và <stack>.restate.pem. Git bỏ qua các file này, và chúng cần được sao lưu cùng khóa của controller (Secret).

Nguyên tắc thiết kế

Quy tắc chính

  • Một Helm chart, infra/stack, render cả hai stack. values-dev.yaml và values-prod.yaml chứa mọi khác biệt giữa chúng.
  • Mọi host suy ra từ một giá trị domain: <domain>, api.<domain>, media.<domain>, docs.<domain> và console.<domain>.
  • Mọi thứ riêng của một môi trường đều nằm trong infra/. Ngoại lệ duy nhất là file proxy trên host conf.d/shopnexus.caddy trong linux-server-setup, dùng cho chế độ behind-proxy.
  • Chỉ infra/cluster/ biết đến k3d.
  • CI build image và không bao giờ kết nối tới cluster; Argo CD kéo mọi thay đổi từ git.

Một bản fork, theo trang Dựng một cluster, đổi repoURL trong infra/argocd/root.yaml và infra/argocd/stacks.yaml, và domain trong hai file values. Image thuộc owner khác ghcr.io/shopnexus thì cần thêm tên mới trong values.yaml và stacks.yaml. Image website đặt API_URL=http://server-api:8080/v1, tên một Service trong cluster, phân giải được trong bất kỳ namespace stack nào website đang chạy, nên một image dùng được cho cả hai stack.

Việc để sau

Bản thiết kế để sao lưu, quan sát hệ thống, máy thật và file docker-compose.yml ở gốc repo ra ngoài phạm vi.

  • Không có gì sao lưu Postgres, RustFS hay Restate. Khóa của controller Sealed Secrets và các file lệnh seal ghi ra phải được lưu bằng tay.
  • Chart đặt OTEL_EXPORTER_OTLP_ENDPOINT là chuỗi rỗng, nên server không gửi gì qua OTLP và chỉ ghi log JSON ra stdout. Cluster không chạy collector nào.
  • Các agent là container trên cùng một host và dùng chung ổ đĩa của nó, nên hỏng ổ đĩa là mất mọi node. Chuyển sang k3s trên các máy riêng thì đổi infra/cluster/.
  • File docker-compose.yml ở gốc repo giờ có ba stack, mỗi profile một stack, mỗi stack có network, Postgres, Restate, RustFS và volume riêng. dev chạy server bằng go run và dev server của các web app với Compose Watch, sau Caddy ở cổng 56481. prod build mọi thành phần từ Dockerfile của nó, sau Caddy ở cổng 56480. test chạy các test Go của server. infra/check.sh báo lỗi khi tag image của Postgres, Restate và RustFS trong file đó khác với infra/stack/values.yaml.
  • Trước khi có tìm bằng ảnh, bản thiết kế ước tính hai stack dùng 6 đến 8 GB bộ nhớ. Tìm bằng ảnh thêm ai-models: xin 6Gi ở prod, có SigLIP 2 (giữ 4,0 GiB lúc rảnh, đo ngày 2026-11-10), và 2Gi ở dev, nơi không nạp SigLIP 2 từ 2026-11-17. ai-gateway giữ khoảng 0,6 GiB mỗi stack. Embedding chữ lấy từ OpenRouter, nên không stack nào chạy TEI. Ngày 2026-11-17, TEI (5,5 GiB) và ai (4,1 GiB) cùng các dự án khác đã lấp đầy máy dev 19 GiB. Phương án dự phòng là scale dev về 0 khi không dùng, hoặc giảm cluster xuống hai agent.
ShopNexus Docs
EN VI

Gợi ý cho trang này

Thao tác nhanh