juwan-backend/deploy/k01/README.md

k01 业务集群

该目录是 juwan-backend 所有 k3s 节点的初始化配置。公网入口由 center 的 Caddy 接管——/wt/* 走 UDP 直达 chat-api，其余路径反代到 envoy-gateway NodePort 30080。

第一台机器按以下步骤初始化为 k3s server；后续加入的 k02、k03 只运行 install-k3s.sh agent，其他步骤（k8s Secret、CR、业务 yaml）在 server 上 apply 一次即可。

前置条件

• Ubuntu 26.04 LTS，root
• center 已部署，registry.juwan.xhttp.zip 可推可拉
• 已从 Gitea 拉取仓库：git clone https://git.juwan.xhttp.zip/juwan/juwan-backend.git
• /root/registry-password 文件存放 zot admin 密码（chmod 600）

k3s server 初始化

cd /root/juwan-backend/deploy/k01

# 装 k3s（禁用内置 traefik）+ Helm + 四个 Operator
bash install-k3s.sh

# 准备 .env，填 zot Admin 密码 / Brevo SMTP / Garage S3 凭据
cp .env.example .env
nano .env

# 应用 namespace + RBAC，生成全部 k8s Secret
kubectl apply -f 00-base/
bash secrets.sh

# 应用基础设施（Operator CR）
kubectl apply -f 01-infra/postgres.yaml
kubectl apply -f 01-infra/redis.yaml
kubectl apply -f 01-infra/mongo.yaml
kubectl apply -f 01-infra/kafka.yaml
kubectl apply -f 01-infra/ratelimit.yaml
kubectl apply -f 01-infra/envoy.yaml

# 等 PostgreSQL Cluster 全部 Ready 后再灌 schema
bash 01-infra/load-schema.sh

# 启动业务服务
kubectl apply -f 02-service/

kubectl -n juwan get pods -w

做什么

四层结构。控制面是 k3s server，跑着 CNPG / Strimzi / Redis / MongoDB 四个 Operator 管理有状态服务。

数据层 11 个 per-domain PostgreSQL Cluster + 12 个 RedisReplication + 1 个 MongoDBCommunity（chat）+ Strimzi KRaft Kafka（1 broker）。

业务层 27 个 Go 服务镜像指向 registry.juwan.xhttp.zip/juwan/<name>:latest，每个 domain 一套 rpc + api，外加 snowflake、authz-adapter、email-mq 和 frontend。所有 Deployment 带 imagePullSecrets: registry-creds，containerd 的 registries.yaml 配了 zot admin 凭据。

email-api 跟 user-rpc 共用 user-redis 实例，因为注册和重置密码的验证码 key 跨服务读写。

chat-api 的 WebTransport 走 UDP 8443 hostPort，center Caddy 的 PR 7669 fork 把这路流量终结后反代过来。

生成的 Secret

secrets.sh 生成随机密码写入 secrets/ 目录，同时 kubectl create secret 到 juwan namespace。需要手动填的是 .env 里的 zot admin 密码、Brevo SMTP key 和 Garage S3 access key。

CNPG 每个 Cluster Ready 后自动生成 <cluster>-app Secret（username/password/dbname/host/port），业务 pod 的 env 直接从这些 Secret 取值。

加节点

在 server 上取 token：

cat /var/lib/rancher/k3s/server/node-token

新机器上执行：

cd /root/juwan-backend/deploy/k01
echo "<zot-admin-password>" > /root/registry-password && chmod 600 /root/registry-password

K3S_URL=https://<server-ip>:6443 K3S_TOKEN=<token> bash install-k3s.sh agent

日常操作

kubectl -n juwan get pods -o wide
kubectl -n juwan rollout restart deploy/user-rpc
kubectl -n kafka get kafka,kafkatopic,kafkanodepool