From 8697569b81d6e883bccb904fdcad9213868e493d Mon Sep 17 00:00:00 2001 From: zetaloop Date: Tue, 5 May 2026 12:11:30 +0800 Subject: [PATCH] docs(k01): rewrite readme following center host documentation style --- deploy/k01/README.md | 107 ++++++++++++++++--------------------------- 1 file changed, 40 insertions(+), 67 deletions(-) diff --git a/deploy/k01/README.md b/deploy/k01/README.md index 9e34ea2..ab0c281 100644 --- a/deploy/k01/README.md +++ b/deploy/k01/README.md @@ -1,53 +1,33 @@ -# k01 业务集群部署 +# k01 业务集群 -承载 juwan-backend 全部业务的 k3s 单节点集群（演示阶段），后续可扩 k02 / k03。 +k01 是 juwan-backend 的 k3s 单节点集群。公网入口由 center 的 Caddy 接管——`/wt/*` 走 UDP 直达 chat-api，其余路径反代到 envoy-gateway NodePort 30080。演示阶段一台机器跑完数据层与全部 Go 服务，之后可以加 k02 / k03 扩展。 -## 架构层次 - -| 层 | 组件 | -|---|---| -| 控制面 | k3s server（已禁用内置 traefik） | -| Operator | CloudNativePG / Strimzi Kafka / Ot-Container-Kit Redis / MongoDB Community | -| 数据 | 11 CNPG Cluster / 12 RedisReplication / Strimzi KRaft Kafka 1 broker / MongoDBCommunity 单实例 | -| 网络 | envoy-gateway（NodePort 30080）/ ratelimit + rl-redis | -| 业务 | snowflake、authz-adapter、12 rpc、14 api、email-mq、frontend | - -## 入口路径 - -``` -juwan.xhttp.zip - ├─ /wt/* → center Caddy → k01 chat-api UDP 8443（hostPort） - └─ 其他 → center Caddy → k01 envoy-gateway TCP 30080 -``` +部署机参考：Vultr Regular / 1 vCPU / 1 GB RAM / 32 GB NVMe。 ## 前置条件 - Ubuntu 26.04 LTS，root -- center 已部署，registry.juwan.xhttp.zip 可推可拉 -- DNS：`juwan.xhttp.zip` A 记录指向 k01（140.82.15.92） +- center 已部署，`registry.juwan.xhttp.zip` 可推可拉 - 仓库已复制到 `/root/juwan-backend` +- `/root/registry-password` 文件存放 zot admin 密码（`chmod 600`） ## 首次部署 ```bash cd /root/juwan-backend/deploy/k01 -# 1. zot admin 密码写到文件供 install-k3s 读取 -echo "" > /root/registry-password -chmod 600 /root/registry-password - -# 2. 装 k3s + 4 个 Operator +# 装 k3s（禁用内置 traefik）+ Helm + 四个 Operator bash install-k3s.sh -# 3. 准备 .env，填入 zot 凭据 / brevo SMTP / garage S3 凭据等 +# 准备 .env，填 zot Admin 密码 / Brevo SMTP / Garage S3 凭据 cp .env.example .env nano .env -# 4. 应用 namespace + RBAC，生成所有 k8s Secret +# 应用 namespace + RBAC，生成全部 k8s Secret kubectl apply -f 00-base/ bash secrets.sh -# 5. 应用基础设施 +# 应用基础设施（Operator CR） kubectl apply -f 01-infra/postgres.yaml kubectl apply -f 01-infra/redis.yaml kubectl apply -f 01-infra/mongo.yaml @@ -55,64 +35,57 @@ kubectl apply -f 01-infra/kafka.yaml kubectl apply -f 01-infra/ratelimit.yaml kubectl apply -f 01-infra/envoy.yaml -# 等所有 CNPG Cluster Ready，灌入 schema + fixture +# 等 PostgreSQL Cluster 全部 Ready 后再灌 schema bash 01-infra/load-schema.sh -# 6. 应用业务服务 +# 启动业务服务 kubectl apply -f 02-service/ -# 7. 观察 pod kubectl -n juwan get pods -w ``` -## 凭据管理 +## 做什么 -`secrets.sh` 生成的全部明文密码写入 `secrets/` 目录，`chmod 600`，`.gitignore` 已排除。 +四层结构。控制面是 k3s server，跑着 CNPG / Strimzi / Redis / MongoDB 四个 Operator 管理有状态服务。 -| Secret | 用途 | -|---|---| -| `registry-creds` | imagePullSecret（zot） | -| `jwt-secret` | user-rpc 签发 / 校验 JWT | -| `admin-bootstrap` | user-rpc 启动时插入 admin 账号 | -| `email-smtp` | email-mq 发邮件 | -| `objectstory-s3` | objectstory-rpc 接 garage | -| `chat-wt-tls` | chat-api WT 自签证书（来自 `deploy/dev/certs`） | -| `-redis` | 12 个 RedisReplication 的 password | -| `chat-mongodb-app-user-password` | MongoDB SCRAM 密码 | -| `-app` | CNPG 自动生成的 PG 凭据 | +数据层 11 个 per-domain PostgreSQL Cluster + 12 个 RedisReplication + 1 个 MongoDBCommunity（chat）+ Strimzi KRaft Kafka（1 broker）。 -## 已知限制 +业务层 27 个 Go 服务镜像指向 `registry.juwan.xhttp.zip/juwan/:latest`，每个 domain 一套 rpc + api，外加 snowflake、authz-adapter、email-mq 和 frontend。所有 Deployment 带 `imagePullSecrets: registry-creds`，containerd 的 `registries.yaml` 配了 zot admin 凭据。 -- snowflake 使用 Deployment + WorkerId=0。扩到多副本前需让 snowflake 业务代码支持从 env 读 WorkerId。 -- chat-api UDP 8443 走 hostPort，扩 k02/k03 时新 node 需开放 UDP 8443，DNS 也要做轮询或 LB。 -- email-api 复用 user-redis 实例（验证码 key 与 user-rpc 共享读写），跟 dev 行为一致。 -- HPA 暂不部署。加副本前把 `replicas: 1` 改大或加 HPA。 +email-api 跟 user-rpc 共用 user-redis 实例，因为注册和重置密码的验证码 key 跨服务读写。 -## 加节点（k02 / k03） +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 后自动生成 `-app` Secret（username/password/dbname/host/port），业务 pod 的 env 直接从这些 Secret 取值。 + +## 加节点 + +k01 上取 k3s 的 node-token： ```bash -# 在 k01 取 token cat /var/lib/rancher/k3s/server/node-token +``` -# 在 k02 上 +k02 加入集群： + +```bash curl -sfL https://get.k3s.io | \ K3S_URL=https://140.82.15.92:6443 K3S_TOKEN= \ sh - - -# 复制 registries.yaml -scp root@140.82.15.92:/etc/rancher/k3s/registries.yaml \ - /etc/rancher/k3s/registries.yaml +scp root@140.82.15.92:/etc/rancher/k3s/registries.yaml /etc/rancher/k3s/ systemctl restart k3s-agent ``` -## 与 center 协同 +pod 调度靠 k3s 自动分配。有状态的想粘在指定 node 上就加 `nodeSelector`。 -| 事项 | 哪一边 | -|---|---| -| `juwan.xhttp.zip` LE 证书 | center Caddy 自动签 | -| WebTransport 终结 | center Caddy（PR 7669 fork） | -| WebTransport 上游 | k01 chat-api UDP 8443（hostPort） | -| envoy-gateway 上游 | k01 NodePort 30080 | -| 镜像拉取 | k01 containerd → registry.juwan.xhttp.zip | -| S3 后端 | k01 objectstory-rpc → s3.juwan.xhttp.zip → center Garage | -| CD 触发 | gitea Actions runner（在 center） → kubectl 远程操作 k01 | +## 日常操作 + +```bash +kubectl -n juwan get pods -o wide +kubectl -n juwan rollout restart deploy/user-rpc +kubectl -n kafka get kafka,kafkatopic,kafkanodepool +```