diff --git a/deploy/k8s/README.md b/deploy/k8s/README.md new file mode 100644 index 00000000..fe362866 --- /dev/null +++ b/deploy/k8s/README.md @@ -0,0 +1,47 @@ +# HiClaw Kubernetes Deployment + +> 在 Kubernetes 集群上部署 HiClaw 多 Agent 协作平台 + +## 快速开始 + +```bash +# 1. 修改配置 +vim secrets.yaml # 设置 LLM API Key 和密码 + +# 2. 一键部署 +kubectl apply -k . + +# 3. 配置 hosts 文件 +# 获取 Ingress IP +kubectl get ingress -n hiclaw + +# 添加到 /etc/hosts +# element.hiclaw.local matrix.hiclaw.local gateway.hiclaw.local +``` + +## 文件说明 + +| 文件 | 说明 | +|------|------| +| `kustomization.yaml` | Kustomize 配置文件 | +| `namespace.yaml` | 命名空间定义 | +| `secrets.yaml` | 敏感信息 Secret | +| `minio.yaml` | MinIO 文件存储 | +| `matrix.yaml` | Matrix (Tuwunel) IM 服务 | +| `higress.yaml` | Higress AI Gateway | +| `element.yaml` | Element Web 前端 | +| `manager.yaml` | HiClaw Manager | +| `ingress.yaml` | Ingress 路由规则 | +| `deploy.sh` | 一键部署脚本 | + +## 详细文档 + +参见 [K8s 部署教程](../../docs/zh-cn/deployment/hiclaw-k8s-deployment-tutorial.md) + +## 相关 Issue + +- [#245](https://github.com/alibaba/hiclaw/issues/245) - K8s 部署模式支持请求 + +## 贡献 + +欢迎提交 Issue 和 PR 来完善 K8s 部署方案！ \ No newline at end of file diff --git a/deploy/k8s/deploy.sh b/deploy/k8s/deploy.sh new file mode 100644 index 00000000..9518fc51 --- /dev/null +++ b/deploy/k8s/deploy.sh @@ -0,0 +1,90 @@ +#!/bin/bash +# HiClaw K8s 一键部署脚本 + +set -e + +echo "🦞 HiClaw Kubernetes 部署脚本" +echo "==============================" + +# 颜色定义 +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# 检查 kubectl +if ! command -v kubectl &> /dev/null; then + echo -e "${RED}错误: kubectl 未安装${NC}" + echo "请先安装 kubectl: https://kubernetes.io/docs/tasks/tools/" + exit 1 +fi + +# 检查集群连接 +if ! kubectl cluster-info &> /dev/null; then + echo -e "${RED}错误: 无法连接到 Kubernetes 集群${NC}" + echo "请检查 kubeconfig 配置" + exit 1 +fi + +echo -e "${GREEN}✓ Kubernetes 集群连接正常${NC}" + +# 提示输入配置 +echo "" +echo "请输入配置信息：" +echo "----------------" + +read -p "LLM API Key: " LLM_API_KEY +if [ -z "$LLM_API_KEY" ]; then + echo -e "${RED}错误: LLM API Key 不能为空${NC}" + exit 1 +fi + +read -p "管理员密码 [自动生成]: " ADMIN_PASSWORD +if [ -z "$ADMIN_PASSWORD" ]; then + ADMIN_PASSWORD=$(openssl rand -base64 16) + echo -e "${YELLOW}已生成管理员密码: $ADMIN_PASSWORD${NC}" +fi + +read -p "MinIO 密码 [minioadmin]: " MINIO_PASSWORD +MINIO_PASSWORD=${MINIO_PASSWORD:-minioadmin} + +# 更新 Secret +echo "" +echo "正在更新配置..." +sed -i.bak "s/your-api-key-here/$LLM_API_KEY/g" secrets.yaml +sed -i.bak "s/change-me-secure-password/$ADMIN_PASSWORD/g" secrets.yaml +sed -i.bak "s/minioadmin/$MINIO_PASSWORD/g" secrets.yaml + +# 部署 +echo "" +echo "开始部署..." +kubectl apply -k . + +# 等待 Pod 就绪 +echo "" +echo "等待 Pod 就绪..." +kubectl wait --for=condition=ready pod -l app.kubernetes.io/name -n hiclaw --timeout=300s || true + +# 显示状态 +echo "" +echo "==============================" +echo -e "${GREEN}✓ 部署完成！${NC}" +echo "" +echo "访问地址：" +echo " Element Web: http://element.hiclaw.local" +echo " Higress 控制台: http://higress-console.hiclaw.local" +echo " OpenClaw 控制台: http://openclaw-console.hiclaw.local" +echo " MinIO 控制台: http://minio-console.hiclaw.local" +echo "" +echo "凭据信息：" +echo " 管理员用户名: admin" +echo " 管理员密码: $ADMIN_PASSWORD" +echo " MinIO 用户名: minioadmin" +echo " MinIO 密码: $MINIO_PASSWORD" +echo "" +echo "请将以下内容添加到 /etc/hosts：" +echo " element.hiclaw.local matrix.hiclaw.local gateway.hiclaw.local" +echo " higress-console.hiclaw.local openclaw-console.hiclaw.local" +echo " minio.hiclaw.local minio-console.hiclaw.local" +echo "" +echo "获取 Ingress IP: kubectl get ingress -n hiclaw" \ No newline at end of file diff --git a/deploy/k8s/element.yaml b/deploy/k8s/element.yaml new file mode 100644 index 00000000..d590d943 --- /dev/null +++ b/deploy/k8s/element.yaml @@ -0,0 +1,99 @@ +# Element Web - 前端客户端 +apiVersion: v1 +kind: ConfigMap +metadata: + name: element-config + namespace: hiclaw + labels: + app.kubernetes.io/name: element-web +data: + config.json: | + { + "default_home_server": "matrix-local.hiclaw.io:8080", + "default_server_config": { + "m.homeserver": { + "base_url": "http://tuwunel.hiclaw.svc.cluster.local:8080" + }, + "m.identity_server": { + "base_url": "https://vector.im" + } + }, + "disable_custom_urls": false, + "disable_guests": true, + "disable_login_language_selector": false, + "disable_3pid_login": true, + "brand": "HiClaw", + "integrations_ui_url": "https://scalar.vector.im/", + "integrations_rest_url": "https://scalar.vector.im/api", + "show_labs_settings": true, + "room_directory": { + "servers": ["matrix-local.hiclaw.io:8080"] + } + } +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: element-web + namespace: hiclaw + labels: + app.kubernetes.io/name: element-web + app.kubernetes.io/component: frontend +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: element-web + template: + metadata: + labels: + app.kubernetes.io/name: element-web + spec: + containers: + - name: element-web + image: vectorim/element-web:v1.11.58 + ports: + - containerPort: 80 + name: http + volumeMounts: + - name: config + mountPath: /app/config.json + subPath: config.json + resources: + limits: + cpu: "200m" + memory: "128Mi" + requests: + cpu: "50m" + memory: "32Mi" + livenessProbe: + httpGet: + path: / + port: 80 + initialDelaySeconds: 10 + periodSeconds: 10 + readinessProbe: + httpGet: + path: / + port: 80 + initialDelaySeconds: 5 + periodSeconds: 5 + volumes: + - name: config + configMap: + name: element-config +--- +apiVersion: v1 +kind: Service +metadata: + name: element-web + namespace: hiclaw + labels: + app.kubernetes.io/name: element-web +spec: + ports: + - port: 80 + targetPort: 80 + name: http + selector: + app.kubernetes.io/name: element-web \ No newline at end of file diff --git a/deploy/k8s/higress.yaml b/deploy/k8s/higress.yaml new file mode 100644 index 00000000..44d5b52d --- /dev/null +++ b/deploy/k8s/higress.yaml @@ -0,0 +1,94 @@ +# Higress - AI Gateway +apiVersion: v1 +kind: ServiceAccount +metadata: + name: higress + namespace: hiclaw +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: higress + namespace: hiclaw + labels: + app.kubernetes.io/name: higress + app.kubernetes.io/component: gateway +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: higress + template: + metadata: + labels: + app.kubernetes.io/name: higress + spec: + serviceAccountName: higress + containers: + - name: higress-gateway + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:1.4.0 + ports: + - containerPort: 8080 + name: http + - containerPort: 8443 + name: https + - containerPort: 15020 + name: metrics + resources: + limits: + cpu: "1" + memory: "1Gi" + requests: + cpu: "200m" + memory: "256Mi" + livenessProbe: + httpGet: + path: /healthz/ready + port: 15020 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /healthz/ready + port: 15020 + initialDelaySeconds: 10 + periodSeconds: 5 + - name: higress-controller + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/higress:1.4.0 + ports: + - containerPort: 8001 + name: console + env: + - name: LLM_API_KEY + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: LLM_API_KEY + resources: + limits: + cpu: "500m" + memory: "512Mi" + requests: + cpu: "100m" + memory: "128Mi" +--- +apiVersion: v1 +kind: Service +metadata: + name: higress + namespace: hiclaw + labels: + app.kubernetes.io/name: higress +spec: + type: LoadBalancer + ports: + - port: 80 + targetPort: 8080 + name: http + - port: 443 + targetPort: 8443 + name: https + - port: 8001 + name: console + selector: + app.kubernetes.io/name: higress \ No newline at end of file diff --git a/deploy/k8s/ingress.yaml b/deploy/k8s/ingress.yaml new file mode 100644 index 00000000..7a874564 --- /dev/null +++ b/deploy/k8s/ingress.yaml @@ -0,0 +1,105 @@ +# Ingress - 外部访问入口 +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: hiclaw-ingress + namespace: hiclaw + labels: + app.kubernetes.io/name: hiclaw + app.kubernetes.io/component: ingress + annotations: + nginx.ingress.kubernetes.io/rewrite-target: / + nginx.ingress.kubernetes.io/proxy-body-size: "100m" +spec: + ingressClassName: nginx + rules: + # Element Web 前端 + - host: element.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: element-web + port: + number: 80 + + # Matrix 服务器 + - host: matrix.hiclaw.local + http: + paths: + - path: /_matrix + pathType: Prefix + backend: + service: + name: tuwunel + port: + number: 6167 + - path: /.well-known + pathType: Prefix + backend: + service: + name: tuwunel + port: + number: 8080 + + # AI Gateway + - host: gateway.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: higress + port: + number: 80 + + # Higress 控制台 + - host: higress-console.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: higress + port: + number: 8001 + + # OpenClaw 控制台 + - host: openclaw-console.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: hiclaw-manager + port: + number: 18888 + + # MinIO 文件系统 + - host: minio.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: minio + port: + number: 9000 + + # MinIO 控制台 + - host: minio-console.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: minio + port: + number: 9001 \ No newline at end of file diff --git a/deploy/k8s/kustomization.yaml b/deploy/k8s/kustomization.yaml new file mode 100644 index 00000000..9db94c8b --- /dev/null +++ b/deploy/k8s/kustomization.yaml @@ -0,0 +1,17 @@ +# HiClaw Kubernetes Deployment +# 一键部署: kubectl apply -k . + +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +namespace: hiclaw + +resources: + - namespace.yaml + - secrets.yaml + - minio.yaml + - matrix.yaml + - higress.yaml + - element.yaml + - manager.yaml + - ingress.yaml \ No newline at end of file diff --git a/deploy/k8s/manager.yaml b/deploy/k8s/manager.yaml new file mode 100644 index 00000000..94cddce9 --- /dev/null +++ b/deploy/k8s/manager.yaml @@ -0,0 +1,141 @@ +# HiClaw Manager - Agent 管理器 +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: manager-pvc + namespace: hiclaw + labels: + app.kubernetes.io/name: hiclaw-manager + app.kubernetes.io/component: storage +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: hiclaw-manager + namespace: hiclaw + labels: + app.kubernetes.io/name: hiclaw-manager + app.kubernetes.io/component: manager +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: hiclaw-manager + template: + metadata: + labels: + app.kubernetes.io/name: hiclaw-manager + spec: + containers: + - name: manager + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/hiclaw/manager:latest + ports: + - containerPort: 8080 + name: http + - containerPort: 18888 + name: console + env: + # LLM 配置 + - name: HICLAW_LLM_API_KEY + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: LLM_API_KEY + - name: HICLAW_LLM_PROVIDER + value: "qwen" + + # 管理员凭据 + - name: HICLAW_ADMIN_USER + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: ADMIN_USER + - name: HICLAW_ADMIN_PASSWORD + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: ADMIN_PASSWORD + + # Matrix 配置 + - name: HICLAW_MATRIX_DOMAIN + value: "matrix-local.hiclaw.io:8080" + - name: HICLAW_MATRIX_CLIENT_DOMAIN + value: "matrix-client-local.hiclaw.io" + + # MinIO 配置 + - name: HICLAW_MINIO_ENDPOINT + value: "minio.hiclaw.svc.cluster.local:9000" + - name: HICLAW_MINIO_USER + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_USER + - name: HICLAW_MINIO_PASSWORD + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_PASSWORD + + # Gateway 配置 + - name: HICLAW_MANAGER_GATEWAY_KEY + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MANAGER_GATEWAY_KEY + + # 域名配置 + - name: HICLAW_FS_DOMAIN + value: "fs-local.hiclaw.io" + - name: HICLAW_CONSOLE_DOMAIN + value: "console-local.hiclaw.io" + - name: HICLAW_AI_GATEWAY_DOMAIN + value: "aigw-local.hiclaw.io" + + resources: + limits: + cpu: "2" + memory: "4Gi" + requests: + cpu: "500m" + memory: "1Gi" + livenessProbe: + httpGet: + path: /health + port: 8080 + initialDelaySeconds: 60 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /health + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 5 + volumeMounts: + - name: data + mountPath: /data + volumes: + - name: data + persistentVolumeClaim: + claimName: manager-pvc +--- +apiVersion: v1 +kind: Service +metadata: + name: hiclaw-manager + namespace: hiclaw + labels: + app.kubernetes.io/name: hiclaw-manager +spec: + ports: + - port: 8080 + name: http + - port: 18888 + name: console + selector: + app.kubernetes.io/name: hiclaw-manager \ No newline at end of file diff --git a/deploy/k8s/matrix.yaml b/deploy/k8s/matrix.yaml new file mode 100644 index 00000000..c184070b --- /dev/null +++ b/deploy/k8s/matrix.yaml @@ -0,0 +1,71 @@ +# Matrix (Tuwunel) - IM 服务器 +apiVersion: apps/v1 +kind: Deployment +metadata: + name: tuwunel + namespace: hiclaw + labels: + app.kubernetes.io/name: tuwunel + app.kubernetes.io/component: matrix +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: tuwunel + template: + metadata: + labels: + app.kubernetes.io/name: tuwunel + spec: + containers: + - name: tuwunel + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/tuwunel:20260216 + ports: + - containerPort: 6167 + name: matrix + - containerPort: 8080 + name: well-known + env: + - name: SERVER_NAME + value: "matrix-local.hiclaw.io:8080" + resources: + limits: + cpu: "500m" + memory: "512Mi" + requests: + cpu: "100m" + memory: "128Mi" + livenessProbe: + httpGet: + path: /_matrix/client/versions + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /_matrix/client/versions + port: 8080 + initialDelaySeconds: 10 + periodSeconds: 5 + volumeMounts: + - name: data + mountPath: /data + volumes: + - name: data + emptyDir: {} +--- +apiVersion: v1 +kind: Service +metadata: + name: tuwunel + namespace: hiclaw + labels: + app.kubernetes.io/name: tuwunel +spec: + ports: + - port: 6167 + name: matrix + - port: 8080 + name: well-known + selector: + app.kubernetes.io/name: tuwunel \ No newline at end of file diff --git a/deploy/k8s/minio.yaml b/deploy/k8s/minio.yaml new file mode 100644 index 00000000..f9b18bfc --- /dev/null +++ b/deploy/k8s/minio.yaml @@ -0,0 +1,100 @@ +# MinIO - 文件存储服务 +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: minio-pvc + namespace: hiclaw + labels: + app.kubernetes.io/name: minio + app.kubernetes.io/component: storage +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 20Gi +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: minio + namespace: hiclaw + labels: + app.kubernetes.io/name: minio + app.kubernetes.io/component: storage +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: minio + template: + metadata: + labels: + app.kubernetes.io/name: minio + spec: + containers: + - name: minio + image: minio/minio:RELEASE.2024-01-01T00-00-00Z + args: + - server + - /data + - --console-address + - ":9001" + env: + - name: MINIO_ROOT_USER + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_USER + - name: MINIO_ROOT_PASSWORD + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_PASSWORD + ports: + - containerPort: 9000 + name: api + - containerPort: 9001 + name: console + volumeMounts: + - name: data + mountPath: /data + resources: + limits: + cpu: "1" + memory: "1Gi" + requests: + cpu: "100m" + memory: "256Mi" + livenessProbe: + httpGet: + path: /minio/health/live + port: 9000 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /minio/health/ready + port: 9000 + initialDelaySeconds: 10 + periodSeconds: 5 + volumes: + - name: data + persistentVolumeClaim: + claimName: minio-pvc +--- +apiVersion: v1 +kind: Service +metadata: + name: minio + namespace: hiclaw + labels: + app.kubernetes.io/name: minio +spec: + ports: + - port: 9000 + name: api + - port: 9001 + name: console + selector: + app.kubernetes.io/name: minio \ No newline at end of file diff --git a/deploy/k8s/namespace.yaml b/deploy/k8s/namespace.yaml new file mode 100644 index 00000000..1c02cd85 --- /dev/null +++ b/deploy/k8s/namespace.yaml @@ -0,0 +1,7 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: hiclaw + labels: + app.kubernetes.io/name: hiclaw + app.kubernetes.io/component: namespace \ No newline at end of file diff --git a/deploy/k8s/secrets.yaml b/deploy/k8s/secrets.yaml new file mode 100644 index 00000000..e29a260a --- /dev/null +++ b/deploy/k8s/secrets.yaml @@ -0,0 +1,20 @@ +apiVersion: v1 +kind: Secret +metadata: + name: hiclaw-secrets + namespace: hiclaw +type: Opaque +stringData: + # LLM API Key (必填) + LLM_API_KEY: "your-api-key-here" + + # 管理员凭据 (必填) + ADMIN_USER: "admin" + ADMIN_PASSWORD: "change-me-secure-password" + + # MinIO 凭据 + MINIO_USER: "minioadmin" + MINIO_PASSWORD: "minioadmin" + + # Manager Gateway Key (自动生成或手动设置) + MANAGER_GATEWAY_KEY: "hiclaw-manager-key-change-me" \ No newline at end of file diff --git a/docs/zh-cn/deployment/hiclaw-k8s-deployment-tutorial.md b/docs/zh-cn/deployment/hiclaw-k8s-deployment-tutorial.md new file mode 100644 index 00000000..080ebd3a --- /dev/null +++ b/docs/zh-cn/deployment/hiclaw-k8s-deployment-tutorial.md @@ -0,0 +1,683 @@ +# HiClaw K8s 部署教程 + +> 基于 Kubernetes 部署 HiClaw 多 Agent 协作平台 + +> ⚠️ **注意**：HiClaw 官方目前尚未提供原生 K8s 支持，本教程基于 Docker 架构转换为 K8s 部署方案。相关 Issue: [#245](https://github.com/alibaba/hiclaw/issues/245) + +--- + +## 目录 + +- [架构概览](#架构概览) +- [前置条件](#前置条件) +- [部署步骤](#部署步骤) +- [验证部署](#验证部署) +- [配置说明](#配置说明) +- [故障排查](#故障排查) +- [生产环境建议](#生产环境建议) + +--- + +## 架构概览 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Kubernetes Cluster │ +│ ┌─────────────────────────────────────────────────────────┐│ +│ │ hiclaw Namespace ││ +│ │ ││ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ +│ │ │ Manager │ │ Worker │ │ Worker │ ││ +│ │ │ (OpenClaw) │ │ Alice │ │ Bob │ ││ +│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ ││ +│ │ │ │ │ ││ +│ │ ┌──────┴────────────────┴────────────────┴──────┐ ││ +│ │ │ Matrix (Tuwunel) │ ││ +│ │ └───────────────────────────────────────────────┘ ││ +│ │ ││ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ +│ │ │ MinIO │ │ Higress │ │ Element Web │ ││ +│ │ │ (文件存储) │ │ (AI Gateway)│ │ (前端) │ ││ +│ │ └─────────────┘ └─────────────┘ └─────────────┘ ││ +│ └─────────────────────────────────────────────────────────┘│ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 前置条件 + +### 集群要求 + +| 组件 | 版本要求 | +|------|---------| +| Kubernetes | ≥ 1.24 | +| kubectl | ≥ 1.24 | +| Helm | ≥ 3.0（可选） | + +### 资源要求 + +| 资源 | 最低 | 推荐 | +|------|------|------| +| 节点数 | 1 | 3+ | +| CPU | 4 核 | 8 核 | +| 内存 | 8 GB | 16 GB | +| 存储 | 50 GB | 100 GB | + +### 存储类 + +确保集群有默认 StorageClass： + +```bash +kubectl get storageclass +``` + +--- + +## 部署步骤 + +### 第一步：创建命名空间 + +```bash +kubectl create namespace hiclaw +``` + +### 第二步：创建 Secret + +```bash +# 创建 API Key Secret +kubectl create secret generic hiclaw-secrets \ + --from-literal=LLM_API_KEY=your-api-key-here \ + --from-literal=ADMIN_USER=admin \ + --from-literal=ADMIN_PASSWORD=your-secure-password \ + --from-literal=MINIO_USER=minioadmin \ + --from-literal=MINIO_PASSWORD=minioadmin \ + --namespace hiclaw +``` + +### 第三步：部署 MinIO + +```yaml +# minio.yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: minio-pvc + namespace: hiclaw +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 20Gi +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: minio + namespace: hiclaw +spec: + replicas: 1 + selector: + matchLabels: + app: minio + template: + metadata: + labels: + app: minio + spec: + containers: + - name: minio + image: minio/minio:latest + args: + - server + - /data + - --console-address + - ":9001" + env: + - name: MINIO_ROOT_USER + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_USER + - name: MINIO_ROOT_PASSWORD + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_PASSWORD + ports: + - containerPort: 9000 + name: api + - containerPort: 9001 + name: console + volumeMounts: + - name: data + mountPath: /data + volumes: + - name: data + persistentVolumeClaim: + claimName: minio-pvc +--- +apiVersion: v1 +kind: Service +metadata: + name: minio + namespace: hiclaw +spec: + ports: + - port: 9000 + name: api + - port: 9001 + name: console + selector: + app: minio +``` + +```bash +kubectl apply -f minio.yaml +``` + +### 第四步：部署 Matrix (Tuwunel) + +```yaml +# matrix.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: tuwunel + namespace: hiclaw +spec: + replicas: 1 + selector: + matchLabels: + app: tuwunel + template: + metadata: + labels: + app: tuwunel + spec: + containers: + - name: tuwunel + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/tuwunel:20260216 + ports: + - containerPort: 6167 + name: matrix + - containerPort: 8080 + name: well-known + env: + - name: SERVER_NAME + value: "matrix-local.hiclaw.io:8080" + volumeMounts: + - name: data + mountPath: /data + volumes: + - name: data + emptyDir: {} +--- +apiVersion: v1 +kind: Service +metadata: + name: tuwunel + namespace: hiclaw +spec: + ports: + - port: 6167 + name: matrix + - port: 8080 + name: well-known + selector: + app: tuwunel +``` + +```bash +kubectl apply -f matrix.yaml +``` + +### 第五步：部署 Higress AI Gateway + +```yaml +# higress.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: higress + namespace: hiclaw +spec: + replicas: 1 + selector: + matchLabels: + app: higress + template: + metadata: + labels: + app: higress + spec: + containers: + - name: higress-gateway + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:latest + ports: + - containerPort: 8080 + name: http + - containerPort: 8443 + name: https + - containerPort: 15020 + name: metrics + - name: higress-controller + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/higress:latest + ports: + - containerPort: 8001 + name: console + env: + - name: LLM_API_KEY + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: LLM_API_KEY +--- +apiVersion: v1 +kind: Service +metadata: + name: higress + namespace: hiclaw +spec: + type: LoadBalancer + ports: + - port: 80 + targetPort: 8080 + name: http + - port: 443 + targetPort: 8443 + name: https + - port: 8001 + name: console + selector: + app: higress +``` + +```bash +kubectl apply -f higress.yaml +``` + +### 第六步：部署 Element Web + +```yaml +# element.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: element-web + namespace: hiclaw +spec: + replicas: 1 + selector: + matchLabels: + app: element-web + template: + metadata: + labels: + app: element-web + spec: + containers: + - name: element-web + image: vectorim/element-web:latest + ports: + - containerPort: 80 + volumeMounts: + - name: config + mountPath: /app/config.json + subPath: config.json + volumes: + - name: config + configMap: + name: element-config +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: element-config + namespace: hiclaw +data: + config.json: | + { + "default_home_server": "matrix-local.hiclaw.io:8080", + "default_server_config": { + "m.homeserver": { + "base_url": "http://tuwunel.hiclaw.svc.cluster.local:8080" + } + } + } +--- +apiVersion: v1 +kind: Service +metadata: + name: element-web + namespace: hiclaw +spec: + ports: + - port: 80 + selector: + app: element-web +``` + +```bash +kubectl apply -f element.yaml +``` + +### 第七步：部署 Manager Agent + +```yaml +# manager.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: hiclaw-manager + namespace: hiclaw +spec: + replicas: 1 + selector: + matchLabels: + app: hiclaw-manager + template: + metadata: + labels: + app: hiclaw-manager + spec: + containers: + - name: manager + image: higress-registry.cn-hangzhou.cr.aliyuncs.com/hiclaw/manager:latest + ports: + - containerPort: 8080 + env: + - name: HICLAW_LLM_API_KEY + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: LLM_API_KEY + - name: HICLAW_ADMIN_USER + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: ADMIN_USER + - name: HICLAW_ADMIN_PASSWORD + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: ADMIN_PASSWORD + - name: HICLAW_MATRIX_DOMAIN + value: "matrix-local.hiclaw.io:8080" + - name: HICLAW_MINIO_ENDPOINT + value: "minio.hiclaw.svc.cluster.local:9000" + - name: HICLAW_MINIO_USER + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_USER + - name: HICLAW_MINIO_PASSWORD + valueFrom: + secretKeyRef: + name: hiclaw-secrets + key: MINIO_PASSWORD + volumeMounts: + - name: data + mountPath: /data + volumes: + - name: data + persistentVolumeClaim: + claimName: manager-pvc +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: manager-pvc + namespace: hiclaw +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +--- +apiVersion: v1 +kind: Service +metadata: + name: hiclaw-manager + namespace: hiclaw +spec: + ports: + - port: 8080 + selector: + app: hiclaw-manager +``` + +```bash +kubectl apply -f manager.yaml +``` + +### 第八步：创建 Ingress + +```yaml +# ingress.yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: hiclaw-ingress + namespace: hiclaw + annotations: + nginx.ingress.kubernetes.io/rewrite-target: / +spec: + ingressClassName: nginx + rules: + - host: element.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: element-web + port: + number: 80 + - host: matrix.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: tuwunel + port: + number: 8080 + - host: gateway.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: higress + port: + number: 80 + - host: console.hiclaw.local + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: higress + port: + number: 8001 +``` + +```bash +kubectl apply -f ingress.yaml +``` + +--- + +## 验证部署 + +### 检查 Pod 状态 + +```bash +kubectl get pods -n hiclaw +``` + +预期输出： +``` +NAME READY STATUS RESTARTS AGE +minio-xxx 1/1 Running 0 5m +tuwunel-xxx 1/1 Running 0 5m +higress-xxx 2/2 Running 0 5m +element-web-xxx 1/1 Running 0 5m +hiclaw-manager-xxx 1/1 Running 0 5m +``` + +### 检查服务状态 + +```bash +kubectl get svc -n hiclaw +``` + +### 访问服务 + +配置本地 `/etc/hosts`： + +``` + element.hiclaw.local matrix.hiclaw.local gateway.hiclaw.local console.hiclaw.local +``` + +获取 Ingress IP： + +```bash +kubectl get ingress -n hiclaw +``` + +--- + +## 配置说明 + +### 环境变量 + +| 变量名 | 说明 | 默认值 | +|--------|------|--------| +| `HICLAW_LLM_API_KEY` | LLM API 密钥 | - | +| `HICLAW_LLM_PROVIDER` | LLM 提供商 | `qwen` | +| `HICLAW_MATRIX_DOMAIN` | Matrix 服务器域名 | `matrix-local.hiclaw.io:8080` | +| `HICLAW_MINIO_ENDPOINT` | MinIO 端点 | `minio:9000` | +| `HICLAW_ADMIN_USER` | 管理员用户名 | `admin` | +| `HICLAW_ADMIN_PASSWORD` | 管理员密码 | - | + +### 资源限制 + +建议为生产环境配置资源限制： + +```yaml +resources: + limits: + cpu: "2" + memory: "4Gi" + requests: + cpu: "500m" + memory: "1Gi" +``` + +--- + +## 故障排查 + +### Pod 启动失败 + +```bash +# 查看 Pod 事件 +kubectl describe pod -n hiclaw + +# 查看容器日志 +kubectl logs -n hiclaw +``` + +### 服务无法访问 + +```bash +# 检查 Service 端点 +kubectl get endpoints -n hiclaw + +# 检查 Ingress 配置 +kubectl describe ingress -n hiclaw +``` + +### Manager 连接失败 + +```bash +# 进入 Manager Pod 检查网络 +kubectl exec -it -n hiclaw -- /bin/bash +curl http://tuwunel:6167/_matrix/client/versions +curl http://minio:9000/minio/health/live +``` + +--- + +## 生产环境建议 + +### 1. 高可用配置 + +```yaml +# 多副本部署 +spec: + replicas: 3 + +# Pod 反亲和性 +affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchLabels: + app: hiclaw-manager + topologyKey: kubernetes.io/hostname +``` + +### 2. 数据持久化 + +- 使用高可用存储类（如 Ceph、NFS） +- 配置定期备份 +- 启用 MinIO 集群模式 + +### 3. 安全配置 + +- 启用 TLS +- 配置 NetworkPolicy +- 使用 Secret 管理工具（如 Vault） + +### 4. 监控告警 + +- 部署 Prometheus + Grafana +- 配置 Pod 监控 +- 设置资源告警规则 + +--- + +## 一键部署脚本 + +将以上所有配置合并： + +```bash +# 克隆配置仓库（待创建） +git clone https://github.com/xxx/hiclaw-k8s.git +cd hiclaw-k8s + +# 修改配置 +vim config/secrets.env + +# 一键部署 +./deploy.sh +``` + +--- + +## 相关 Issue + +- [#245](https://github.com/alibaba/hiclaw/issues/245) - [feature] 希望支持 k8s 部署模式 + +欢迎在 Issue 中讨论 K8s 部署的最佳实践！ \ No newline at end of file