K3s + Rancher Desktop 本地部署 Runbook¶

本文说明如何在 Windows/macOS 上的 Rancher Desktop（内置 K3s） 部署本仓库全栈：代理商 backend、typed workers、Temporal 视频管线、OSS storage、Hermes Chat、多前端、PostgreSQL、Redis、db-backup 及完整可观测性栈。

前置条件¶

项	要求
Rancher Desktop	已安装并启动
Kubernetes	Preferences → Kubernetes → Enable Kubernetes
容器引擎	General → Container Engine → dockerd (moby)（便于本地镜像直接被 K3s 使用）
内存	建议 ≥ 10GB（全栈 + 可观测性）
工具	`kubectl`、`docker`（Rancher Desktop 自带）

验证：

kubectl config current-context
# 预期：rancher-desktop

kubectl cluster-info

架构概览¶

harness-app：postgres、redis、backend（API）、typed workers、temporal（Server + UI + video Worker）、hermes、storage、agent/admin/demo/chat/canvas 前端、db-backup CronJob
harness-obs：prometheus、loki、promtail、tempo、grafana、alertmanager、oncall-relay
Ingress（Traefik）：*.localhost 域名路由

清单位于仓库 deploy/k3s/。

首次部署¶

1. 准备环境变量（可选）¶

从模板复制并填写（用于 Secret 注入，尤其是 NoneLinear 生图 Key 与 OSS AK）：

copy .env.example .env
copy src\backend\.env.example src\backend\.env
copy src\storage\.env.example src\storage\.env

2. 构建镜像并部署¶

make k3s-deploy

或分步执行：

.\deploy\k3s\scripts\build-images.ps1
.\deploy\k3s\scripts\create-secrets.ps1
kubectl apply -k deploy/k3s/overlays/rancher-desktop

create-secrets.ps1 会从 .env / src/backend/.env 合并密钥到 deploy/k3s/secrets/（该目录下 *-secrets.yaml 已加入 .gitignore）。

3. 等待 Pod 就绪¶

make k3s-status
kubectl wait --for=condition=ready pod -l app=backend -n harness-app --timeout=300s

首次启动 backend/myapp 会在 initContainer 中执行 Alembic 迁移，可能需要 1～3 分钟。

4. 访问服务¶

地址	说明
http://agent.localhost	代理商前端（API 走 `/api` 代理到 backend）
http://admin.localhost	Canvas Admin
http://demo.localhost	用户端 Demo
http://chat.localhost	图现 Chat（对接集群内 Hermes）
http://canvas.localhost	Infinite Canvas（`/api` → backend；`/api/storage` → storage）
http://upload.localhost	OSS storage 微服务
http://docs.localhost	MkDocs
http://temporal.localhost	Temporal Web UI（视频 Workflow）
http://grafana.localhost	Grafana（默认 admin / 见 `secrets.example/obs-secrets.yaml`）

现代浏览器通常可直接解析 *.localhost，无需修改 hosts 文件。

常用命令¶

make k3s-build       # 重建业务镜像 + Hermes/db-backup（已存在则跳过）
make k3s-build-extra # 仅 Hermes 拉取 + db-backup 构建
make k3s-secrets     # 重新生成 Secret（含 hermes / backup / payment-certs）
make k3s-status      # 查看 Pod / Service / Ingress
make k3s-delete      # 卸载（删除 harness-app、harness-obs 命名空间）

Chat / Hermes 需在仓库根 .env 配置 HERMES_OPENAI_API_KEY（或 OPENAI_API_KEY）与 HERMES_API_SERVER_KEY（≥8 字符），再执行 make k3s-secrets。

排错¶

Pod 一直 Pending¶

Rancher Desktop 内存不足：Preferences → Virtual Machine → Memory 调大
PVC 无法绑定：检查 kubectl get pvc -A

ImagePullBackOff¶

确认使用 dockerd (moby) 引擎
重新执行 make k3s-build
确认 Deployment 中 imagePullPolicy: IfNotPresent

backend 迁移失败¶

kubectl logs -n harness-app deploy/backend -c migrate
kubectl logs -n harness-app deploy/backend -c backend

常见原因：PostgreSQL 未就绪（init 容器会等待）、DATABASE_URL Secret 错误。

backend-worker 不 Ready¶

Worker Init 容器等待 Redis PONG。确认 redis-0 Running：

kubectl get pods -n harness-app -l app=redis
kubectl logs -n harness-app deploy/backend-worker -c wait-redis

本地开发等价命令：make run-backend-worker（需 Redis 或 MESSAGING_USE_MEMORY=true）。

Ingress 无法访问¶

kubectl get ingress -n harness-app
kubectl get ingress -n harness-obs
kubectl get svc -n kube-system traefik

确认 Traefik 在 K3s 中运行（Rancher Desktop 默认启用）。

Prometheus targets DOWN¶

Prometheus 通过集群 DNS 抓取：

myapp.harness-app.svc.cluster.local:8000
backend.harness-app.svc.cluster.local:8001

确认对应 Pod Running 且 /metrics 可访问。

Promtail 无日志¶

K3s 版 Promtail 使用 kubernetes-pods 采集容器 stdout，不再读取宿主机 ./logs。请确保应用日志输出到 stdout（不要设置 LOG_FILE 卷挂载）。

与 Docker Compose 的对照¶

Compose	K3s
`docker compose up`（app + postgres）	`deploy/k3s/base` 中 postgres + myapp
`poetry run backend`	backend Deployment
`pnpm dev`（前端）	静态 nginx 镜像 + Ingress
`observability/docker-compose.yml`	`deploy/k3s/observability`

安全说明¶

deploy/k3s/secrets.example/ 仅为开发默认值
切勿将含真实 API Key 的 deploy/k3s/secrets/*.yaml 提交到 Git
Grafana 默认密码仅用于本地；生产请使用 Sealed Secrets 或外部 Secret 管理

后续扩展¶

MkDocs 文档站：继续 make docs-up 或单独增加 Ingress
阿里云 ACK 生产：见 ACK Runbook（ACR + SLB + ESSD）
云 K8s 仅 myapp + HPA：参考仓库 deploy/k8s/deployment-hpa.yaml 与 K8s 升级方案模板
CI 镜像推送：acr-build-push.yml