Bỏ qua đến nội dung
ShopNexus Docs
Trên trang này Thứ tự khởi động 1/3

Bài hướng dẫn này đưa một bản fork của repo umbrella thành một cluster k3d tên shopnexus chạy hai stack: dev trong shopnexus-dev và prod trong shopnexus-prod. Bạn chạy ba lệnh: k3d cluster create với một file cấu hình trong infra/cluster/ tạo cluster, và k3s cài Argo CD vào đó; go -C infra run ./cmd/seal ghi các secret; còn Hurl chạy infra/smoke.hurl để kiểm tra kết quả. Argo CD cài và đồng bộ mọi thứ còn lại từ bản fork của bạn.

Trước khi bắt đầu

Thời gian: 1 giờ Ai làm được: Quản trị viên và lập trình viên
  • Một máy Linux có địa chỉ IP công khai và đủ bộ nhớ trống cho hai stack. Kế hoạch dựng hệ thống của tác giả dừng lại để cân nhắc khi còn dưới 6 GB khả dụng.
  • Docker. Lệnh seal cũng dùng Docker để chạy image server sinh khóa.
  • k3d. Cluster được dựng bằng k3d v5.9.0; server của tác giả chạy v5.8.3. Cả hai file cấu hình trong infra/cluster/, k3d-direct.yaml và k3d-behind-proxy.yaml, ghim image node rancher/k3s:v1.37.1-k3s1.
  • kubectl (đã thử với v1.37.2), Helm (v4.3.1) và kubeseal (0.41.2).
  • Go, để chạy lệnh seal trong infra/cmd/seal. infra/go.mod yêu cầu Go 1.27.
  • Hurl, để chạy smoke test trong infra/smoke.hurl.
  • yq (v4.54.1) và plugin Helm helm-unittest (v1.2.1), chỉ infra/check.sh cần, để kiểm tra chart trước khi bạn push một thay đổi. Cài plugin bằng helm plugin install https://github.com/helm-unittest/helm-unittest --version v1.2.1 --verify=false.
  • Một tên miền mà bạn quản lý được DNS, và một tài khoản GitHub để chứa bản fork.

Thứ tự khởi động

flowchart TD
  up["k3d cluster create<br/>--config infra/cluster/k3d-#lt;mode#gt;.yaml"] --> k3d["Cluster k3d shopnexus<br/>+ cấu hình edge của Traefik"]
  k3d --> argo["Argo CD<br/>(Helm chart 10.11.7)"]
  argo --> root["Application root"]
  root --> w0["Wave 0: platform<br/>cnpg, sealed-secrets,<br/>restate-operator, image-updater"]
  w0 --> w1["Wave 1: stack-dev, stack-prod,<br/>ImageUpdater shopnexus"]
  w1 --> w2["Wave 2: ai-dev, ai-prod"]
  w1 -->|"ComparisonError:<br/>chưa có sealed secret"| seal["cmd/seal dev, cmd/seal prod<br/>commit và push"]
  seal --> sm1["Wave -1 của stack<br/>Namespace restate-#lt;stack#gt;"]
  sm1 --> s0["Wave 0 của stack<br/>postgres, rustfs, SealedSecret"]
  s0 --> s1["Wave 1 của stack<br/>migrate, objectstore-init,<br/>RestateCluster"]
  s1 --> s2["Wave 2 của stack<br/>server, website, docs,<br/>console, Ingress"]
  s2 --> a0["Wave 0 của ai-#lt;stack#gt;<br/>ai-gateway, ai-models"]
  a0 --> a1["Wave 1 của ai-#lt;stack#gt;<br/>ai-gateway-keys"]
Những gì chạy sau k3d cluster create

Application root đồng bộ infra/platform và infra/argocd từ bản fork của bạn. Wave 0 của nó cài bốn operator của platform, wave 1 tạo mỗi stack một Application, và wave 2 tạo ai-dev và ai-prod. Mỗi Application của stack render Helm chart trong infra/stack và áp dụng nó theo các wave riêng. ai-<stack> render chart trong chart/ của repo ai vào cùng namespace khi Application của stack đã Healthy, nên Postgres của stack đã có database litellm.

Các bước

  1. Fork repo và trỏ cấu hình về bản fork

    Fork shopnexus/shopnexus trên GitHub rồi clone bản fork về máy. Argo CD đọc bản fork mà không dùng thông tin đăng nhập, nên bản fork phải ở chế độ public.

    Đặt repoURL thành URL clone của bản fork trong hai file:

    • infra/argocd/root.yaml, có hai chỗ, một cho infra/platform và một cho infra/argocd;
    • infra/argocd/stacks.yaml, một chỗ trong stack-dev và một chỗ trong stack-prod.

    infra/argocd/ai.yaml đọc repo ai, https://github.com/shopnexus/ai.git, một chỗ trong ai-dev và một chỗ trong ai-prod. Trỏ nó về bản fork ai của bạn nếu bạn sửa hub.

    Đặt domain trong infra/stack/values-dev.yaml và infra/stack/values-prod.yaml. Giá trị gốc là dev.shopnexus.id.vn và shopnexus.id.vn; giữ nguyên cấu trúc đó, với dev nằm dưới prod một nhãn.

    ai-gateway của mỗi stack gửi mọi lời gọi mô hình tới mô hình mà alias của nó ghi trong gateway.aliases ở chart/values.yaml của repo ai, phần lớn trên OpenRouter, nên mỗi stack cần một khóa OpenRouter. Ngân sách theo ngày của từng key nằm trong infra/argocd/ai.yaml. Nếu bạn tự build image, đổi các tên ghcr.io/shopnexus/* trong infra/stack/values.yaml, infra/argocd/stacks.yaml và images của chart ai, và đặt các package GHCR ở chế độ public.

    Commit và push lên main.

    Bạn sẽ thấy URL clone của mình trên mọi dòng repoURL:

    Terminal
    grep -n repoURL infra/argocd/*.yaml
  2. Tạo bản ghi DNS

    Tạo bốn bản ghi A trỏ về IP công khai của máy. Lấy example.com làm tên miền prod:

    Bản ghiPhủ
    @example.com, website prod
    *api., media., docs. và console.example.com
    *.devapi.dev., media.dev., docs.dev. và console.dev.example.com
    devdev.example.com, website dev

    Khi đã có *.dev, bản ghi * không còn phủ dev.example.com, nên website dev cần bản ghi dev riêng (trang Biên và mạng giải thích lý do).

    Bạn sẽ thấy IP của máy cho cả website dev lẫn một host bên dưới nó:

    Terminal
    dig +short dev.example.com
    dig +short api.dev.example.com
  3. Tạo cluster bằng k3d

    Chọn chế độ biên. direct để Traefik trong cluster giữ cổng 80 và 443 và lấy chứng chỉ từ Let’s Encrypt. behind-proxy dành cho máy đã có một proxy khác giữ các cổng đó; khi ấy Traefik nghe ở 127.0.0.1:18080 và proxy lo phần TLS. Máy mới dùng direct. Server của tác giả dùng behind-proxy, đứng sau một Caddy dùng chung.

    ACME_EMAIL là bắt buộc; k3d điền ${ACME_EMAIL} trong file cấu hình từ biến môi trường. Traefik lấy chứng chỉ từ server production của Let’s Encrypt.

    Terminal
    ACME_EMAIL=you@example.com k3d cluster create --config infra/cluster/k3d-direct.yaml

    Để thử với server staging của Let’s Encrypt, có giới hạn tần suất cao hơn và chứng chỉ mà trình duyệt không tin, thêm caServer: https://acme-staging-v02.api.letsencrypt.org/directory dưới acme trong infra/cluster/k3d-direct.yaml trước khi tạo cluster. k3d chép cấu hình Traefik vào cluster lúc tạo cluster, nên sửa file về sau không đến được cluster đang chạy.

    Traefik trả lời thử thách TLS-ALPN-01 trên cổng 443, nên cổng 443 phải mở ra internet. Cổng 80 chuyển hướng sang HTTPS bằng mã 301. Trang Biên và mạng có ánh xạ cổng và các thiết lập Traefik của chế độ này.

    Terminal
    k3d cluster create --config infra/cluster/k3d-behind-proxy.yaml

    Proxy trên máy host kết thúc TLS và chuyển HTTP thường đến 127.0.0.1:18080. Traefik tin các header X-Forwarded-* đến từ địa chỉ private. Khối Caddy trên server của tác giả liệt kê mọi host của cả hai stack:

    /etc/caddy/conf.d/shopnexus.caddy
    shopnexus.id.vn, api.shopnexus.id.vn, console.shopnexus.id.vn, media.shopnexus.id.vn, docs.shopnexus.id.vn,
    dev.shopnexus.id.vn, api.dev.shopnexus.id.vn, console.dev.shopnexus.id.vn, media.dev.shopnexus.id.vn, docs.dev.shopnexus.id.vn {
    	request_body {
    		max_size 50MB
    	}
    	reverse_proxy 127.0.0.1:18080
    }

    Thay các tên bằng tên miền của bạn, chạy caddy validate --adapter caddyfile --config <file> rồi reload Caddy. Proxy phải giữ nguyên header Host, và reverse_proxy mặc định làm vậy: một lượt upload presigned lên media. được ký cho đúng host đó. Caddy chuyển hướng HTTP thường bằng mã 308.

    Cluster có một node server và ba agent, với ánh xạ cổng của chế độ biên. agent-0 mang nhãn role=stateful, còn agent-1 và agent-2 mang role=app. Danh sách files: của file cấu hình đặt ba manifest vào thư mục manifests của k3s trên node server, và k3s áp dụng chúng ở lần khởi động đầu:

    1. Một HelmChartConfig cấu hình lại Traefik đi kèm k3s. Nó được viết thẳng trong file cấu hình k3d của từng chế độ.
    2. infra/cluster/argocd.yaml, một HelmChart của k3s cài chart argo-cd, phiên bản 10.11.7, vào namespace argocd. Phần values của nó thêm kiểm tra health cho Application; thiếu nó, root sẽ không chờ platform healthy rồi mới khởi động các stack.
    3. infra/argocd/root.yaml. k3s thử lại file này cho đến khi các CRD của Argo CD tồn tại. Từ đó Argo CD quản lý luôn file đó.

    Khi node server khởi động lại, k3s áp dụng lại bản root.yaml mà nó nhận lúc tạo cluster. Nếu file trong git đã đổi từ đó, cơ chế self-heal của Argo CD đưa bản trong git trở lại trong vòng vài phút.

    Bạn sẽ thấy root trong danh sách khi Argo CD đã lên:

    Terminal
    kubectl -n argocd get applications
  4. Đọc những gì Argo CD hiển thị

    Terminal
    kubectl -n argocd get applications

    Sau vài phút, bốn Application của platform là cnpg, sealed-secrets, restate-operator và image-updater ở trạng thái Synced và Healthy. stack-dev và stack-prod hiện Unknown kèm một ComparisonError:

    infra/stack/secrets/dev/ holds no sealed secrets: run go -C infra run ./cmd/seal dev, commit and push

    Lỗi này nằm trong dự tính. Chart trong infra/stack/templates/secrets.yaml từ chối render khi infra/stack/secrets/<stack>/ chưa có SealedSecret nào, vì stack không thể chạy thiếu chúng. Lúc này các secret chưa thể có: kubeseal mã hóa bằng chứng chỉ của controller Sealed Secrets, và controller đó vừa lên ở wave 0 một phút trước. Cả hai Application của stack thử lại, với thời gian chờ tăng dần từ 30 giây đến 5 phút, cho đến khi các file đã niêm phong có mặt trong git.

    Để vào giao diện web, chuyển tiếp một cổng và đọc mật khẩu admin ban đầu:

    Terminal
    kubectl -n argocd port-forward svc/argocd-server 8080:443
    kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d
  5. Niêm phong các secret

    Chạy lệnh seal một lần cho mỗi stack, từ thư mục gốc của umbrella. Lệnh cần Docker, Go và một context kubectl trỏ vào cluster này; k3d đã đặt nó làm context hiện tại.

    Terminal
    go -C infra run ./cmd/seal dev

    Lần chạy đầu chép infra/stack/secrets/example.env thành infra/stack/secrets/dev.env với quyền 600 và sinh mọi khóa stack cần, điền thẳng vào dòng KEY= còn trống hoặc thêm một dòng mới: khóa JWT, khóa console và khóa ký của Restate (từ /envgen trong image server), khóa RustFS, master key và mật khẩu database của gateway, và virtual key của server và console agent. Khóa riêng của Restate nằm ở dev.restate.pem bên cạnh. Rồi lệnh dừng:

    seal: .../infra/stack/secrets/dev.env: set OPENROUTER_API_KEY

    Mở dev.env và điền các giá trị mà lệnh không tự sinh được:

    Biếndevprod
    OPENROUTER_API_KEYbắt buộcbắt buộc
    FCM_CREDENTIALStùy chọn; để trống thì thông báo đẩy chỉ được ghi log thay vì gửi đibắt buộc; APP_ENV=prod không chấp nhận giá trị trống, và lệnh seal cho prod cũng vậy

    OPENROUTER_API_KEY là khóa OpenRouter của stack, ai-gateway gửi nó cho mọi alias trên OpenRouter; hãy đặt cho khóa một hạn mức credit theo ngày trên OpenRouter. FCM_CREDENTIALS là JSON của một service account Firebase, mã hóa base64.

    Chạy lại lệnh cho dev, rồi hai lần cho prod:

    Terminal
    go -C infra run ./cmd/seal dev
    go -C infra run ./cmd/seal prod     # tạo prod.env rồi dừng
    go -C infra run ./cmd/seal prod     # sau khi điền prod.env

    Lần chạy thứ hai giữ các khóa đã có trong <stack>.env, nên niêm phong đúng những giá trị đó. Mỗi lần chạy thành công ghi bốn SealedSecret vào infra/stack/secrets/<stack>/: server-secrets.yaml, restate-secrets.yaml, litellm-secrets.yaml và litellm-db.yaml. Commit và push chúng:

    Terminal
    git add infra/stack/secrets/dev infra/stack/secrets/prod
    git commit -m "infra: sealed secrets for dev and prod"
    git push

    Các file .env và .pem bị git bỏ qua và chỉ nằm trên máy.

    Sau mỗi lần chạy thành công, bạn sẽ thấy sealed into .../infra/stack/secrets/<stack>; commit and push.

  6. Theo dõi các sync wave

    Argo CD nhận bản push ở lần poll repo tiếp theo. Để nó xem ngay:

    Terminal
    kubectl -n argocd annotate application stack-dev argocd.argoproj.io/refresh=normal
    kubectl -n argocd annotate application stack-prod argocd.argoproj.io/refresh=normal

    Sau đó mỗi stack đồng bộ theo các wave từ -1 tới 2, rồi ai-<stack> của nó theo wave 0 và 1, như sơ đồ ở trên. Argo CD chờ một wave healthy rồi mới bắt đầu wave sau. Trang Postgres, Restate và RustFS liệt kê mọi resource của từng wave.

    Terminal
    kubectl -n argocd get applications -w
    kubectl -n shopnexus-prod get pods -o wide
    kubectl -n restate-prod get pods -o wide

    Bạn sẽ thấy stack-dev, stack-prod, ai-dev và ai-prod ở trạng thái Synced và Healthy. Dev chạy mỗi thứ một bản. Prod chạy ba pod server trên agent-1 và agent-2, hai pod Postgres trên hai node khác nhau và ba pod Restate trên ba node khác nhau.

  7. Chạy smoke test

    infra/smoke.hurl gửi request đến mọi host công khai của một stack. Thêm --insecure nếu chứng chỉ đến từ staging của Let’s Encrypt.

    Terminal
    hurl --test --continue-on-error --variable domain=dev.example.com infra/smoke.hurl
    hurl --test --continue-on-error --variable domain=example.com infra/smoke.hurl

    File kiểm tra https://<domain>/, https://api.<domain>/healthz và /readyz, https://docs.<domain>/, https://console.<domain>/ và https://media.<domain>/health trả 200, và http://api.<domain>/healthz trả về chuyển hướng sang HTTPS (301 từ Traefik, 308 từ Caddy). --continue-on-error chạy đủ bảy request kể cả khi một request thất bại, nên báo cáo liệt kê mọi host lỗi.

    Bạn sẽ thấy file được báo là thành công và mã thoát 0.

  8. Mở console

    Console ở console.<domain> cần một tài khoản nhân viên, và cluster mới chưa có tài khoản nào. API và console chỉ tạo được moderator; admin đầu tiên được tạo bằng lệnh console trong một pod server:

    Terminal
    kubectl -n shopnexus-prod exec -it $(kubectl -n shopnexus-prod get pod -l app.kubernetes.io/name=server -o name | head -1) -- \
      /console create-admin --email you@example.com --name "Your Name"

    Lệnh in ra created admin you@example.com (<id>) và một mật khẩu tạm. Mở https://console.example.com và đăng nhập bằng mật khẩu đó. Console yêu cầu đặt mật khẩu mới, rồi đăng ký một ứng dụng xác thực TOTP. Chạy cùng lệnh đó trong shopnexus-dev cho console của dev.

    Bạn sẽ thấy trang chính của console. Trang Runbook có các lệnh console còn lại.

Gỡ bỏ

Terminal
k3d cluster delete shopnexus

Lệnh này xóa mọi node, volume và database trong cluster, kể cả khóa của controller Sealed Secrets. Các SealedSecret trong git chỉ mở được trên một cluster mới nếu bạn khôi phục khóa đó từ bản sao lưu trước khi niêm phong lại; trang Secret có quy trình. Nếu không có khóa, chạy lệnh seal với cluster mới, lệnh dùng lại các khóa trong <stack>.env, rồi commit các SealedSecret mới.

ShopNexus Docs
EN VI