weiyu/deploy/k8s

Kubernetes 部署微语系统

文件说明

.
├── deploy.sh                        # 自动化部署脚本（推荐使用）
├── namespace.yaml                   # 创建微语系统专用命名空间
├── configmap.yaml                   # 应用配置映射
├── secret.yaml                      # 敏感信息密钥
├── scripts/                         # 部署脚本目录
│   ├── deploy.sh                    # 自动化部署脚本
│   └── cleanup.sh                   # PVC 和数据清理脚本
├── mysql-deployment.yaml            # MySQL 数据库部署
├── mysql-service.yaml               # MySQL 服务
├── redis-deployment.yaml            # Redis 缓存部署
├── redis-service.yaml               # Redis 服务
├── elasticsearch-deployment.yaml    # Elasticsearch 向量数据库部署
├── elasticsearch-service.yaml       # Elasticsearch 服务
├── artemis-deployment.yaml          # ActiveMQ Artemis 消息队列部署
├── artemis-service.yaml             # Artemis 服务
├── minio-deployment.yaml            # MinIO 对象存储部署
├── minio-service.yaml               # MinIO 服务
├── zipkin-deployment.yaml           # Zipkin 分布式追踪部署
├── zipkin-service.yaml              # Zipkin 服务
├── bytedesk-deployment.yaml         # 微语主应用部署
├── bytedesk-service.yaml            # 微语服务
├── ingress.yaml                     # Ingress 路由配置
├── mysql-pvc.yaml                   # MySQL 持久化存储
├── redis-pvc.yaml                   # Redis 持久化存储
├── elasticsearch-pvc.yaml           # Elasticsearch 持久化存储
├── artemis-pvc.yaml                 # Artemis 持久化存储
├── minio-pvc.yaml                   # MinIO 持久化存储
├── zipkin-pvc.yaml                  # Zipkin 持久化存储
├── uploads-pvc.yaml                 # 文件上传持久化存储
└── ollama-deployment.yaml           # Ollama AI 模型服务（可选）

前置要求

1. Kubernetes 集群

• Kubernetes 1.20+
• kubectl 命令行工具
• 至少 4GB 可用内存
• 至少 20GB 可用存储空间

2. 存储类

确保集群中有可用的 StorageClass，用于动态创建持久化卷：

# 查看可用的存储类
kubectl get storageclass

3. Ingress Controller

如果使用 Ingress 进行外部访问，需要安装 Ingress Controller：

# 安装 NGINX Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/cloud/deploy.yaml

# 或者使用 Helm 安装
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx

快速部署

使用自动化部署脚本（推荐）

1. 克隆项目并进入 K8s 目录

# 克隆项目
git clone https://github.com/Bytedesk/bytedesk.git

# 进入 K8s 部署目录
cd bytedesk/deploy/k8s

2. 配置敏感信息

# 编辑 secret.yaml 文件，配置数据库密码、API密钥等敏感信息
# 注意：请修改默认密码和密钥
# 使用 stringData 字段，可以直接使用原文本，无需 base64 编码
vim secret.yaml

3. 执行自动化部署脚本

# 给脚本执行权限
chmod +x scripts/deploy.sh

# 执行部署脚本
./scripts/deploy.sh

• scripts/deploy.sh：安全部署，保留现有数据
• scripts/cleanup.sh：独立清理脚本，用于清理所有数据

手动部署（可选）

如果需要手动部署，可以参考 deploy.sh 脚本中的步骤，或者查看各个 YAML 文件中的注释说明。

注意：手动部署需要按顺序执行以下步骤：

1. 创建命名空间
2. 配置密钥
3. 部署持久化存储
4. 部署中间件服务
5. 等待服务就绪
6. 部署主应用
7. 配置外部访问

推荐使用自动化脚本，可以避免手动操作错误并节省时间：

# 使用自动化部署脚本
./scripts/deploy.sh

# 使用清理脚本
./scripts/cleanup.sh

可选服务部署

部署 Ollama AI 服务

如果需要使用本地 AI 模型，可以部署 Ollama：

# 部署 Ollama
kubectl apply -f ollama-deployment.yaml

# 拉取 AI 模型
kubectl exec -it deployment/ollama -n bytedesk -- ollama pull qwen3:0.6b
kubectl exec -it deployment/ollama -n bytedesk -- ollama pull bge-m3:latest
kubectl exec -it deployment/ollama -n bytedesk -- ollama pull linux6200/bge-reranker-v2-m3:latest

配置外部访问

# 部署 Ingress（可选）
kubectl apply -f ingress.yaml

# 或者使用 NodePort 服务直接访问
kubectl get svc -n bytedesk

使用建议

1. 首次部署：推荐使用 deploy.sh 脚本
2. 重新部署：脚本会自动清理旧资源，适合重新部署
3. 生产环境：建议先测试脚本，确认无误后再在生产环境使用
4. 自定义部署：如需自定义部署流程，可参考脚本内容手动执行

脚本输出示例

$ ./deploy.sh
开始部署微语系统（修复版）...
创建命名空间...
应用密钥配置...
清理旧的 PVC...
部署持久化存储...
等待 PVC 绑定...
部署中间件...
等待中间件就绪...
尝试 1/10...
MySQL 状态: Running
Redis 状态: Running
Elasticsearch 状态: Running
Artemis 状态: Running
Zipkin 状态: Running
MinIO 状态: Running
中间件启动成功！
部署微语应用...
部署完成！
查看状态: kubectl get pods -n bytedesk
查看服务: kubectl get svc -n bytedesk
查看日志: kubectl logs -f deployment/mysql -n bytedesk

配置说明

Secret 配置

secret.yaml 文件包含所有敏感信息，使用 stringData 字段可以直接使用原文本，无需 base64 编码：

stringData:
  # MySQL 配置
  mysql-root-password: r8FqfdbWUaN3
  mysql-username: root
  mysql-database: bytedesk
  
  # Redis 配置
  redis-password: qfRxz3tVT8Nh
  
  # Elasticsearch 配置
  elasticsearch-password: bytedesk123
  elasticsearch-username: elastic
  
  # JWT 密钥
  jwt-secret-key: 1dfaf8d004207b628a9a6b859c429f49a9a7ead9fd8161c1e60847aeef06dbd2
  
  # MinIO 配置
  minio-root-user: minioadmin
  minio-root-password: minioadmin123
  
  # Artemis 配置
  artemis-username: admin
  artemis-password: admin
  
  # AI API Keys (请替换为实际的 API 密钥)
  zhipuai-api-key: sk-xxx
  openai-api-key: sk-xxx
  # ... 其他 AI 提供商

重要提示：

• 生产环境中请修改所有默认密码和密钥

• 使用 stringData 字段可以直接使用原文本，Kubernetes 会自动进行 base64 编码

• 所有 AI 提供商的 API 密钥都需要替换为实际值

• 数据安全：scripts/deploy.sh 脚本安全部署，保留现有数据；如需清理数据请使用 scripts/cleanup.sh

• 数据备份：重要数据建议定期备份，可使用以下命令：

  # 备份 MySQL 数据
  kubectl exec -n bytedesk deployment/mysql -- mysqldump -u root -p bytedesk > backup.sql
  
  # 备份 MinIO 数据
  kubectl exec -n bytedesk deployment/minio -- mc mirror /data backup/
  

环境变量配置

配置采用分层管理，避免重复：

ConfigMap (configmap.yaml)：包含所有非敏感配置

• 基础配置（时区、端口等）
• 应用配置（调试、版本等）
• 自定义配置（品牌、UI等）
• 中间件配置（数据库、Redis、Elasticsearch等）
• AI 配置（模型、参数等）

Secret (secret.yaml)：包含所有敏感信息

• 数据库密码
• API 密钥
• JWT 密钥
• 中间件认证信息

Deployment (bytedesk-deployment.yaml)：引用 ConfigMap 和 Secret

• 使用 envFrom 引用整个 ConfigMap
• 使用 env 单独引用 Secret 中的敏感信息

这种设计避免了配置重复，提高了维护性。

• 数据库配置：MySQL 连接信息
• Redis 配置：缓存和会话存储
• Elasticsearch 配置：向量数据库
• AI 模型配置：支持多种 AI 提供商
• 文件上传配置：本地存储或 MinIO
• 自定义配置：品牌、功能开关等

资源限制

建议的资源分配：

• 微语主应用：CPU 1-2核，内存 2-4GB
• MySQL：CPU 1核，内存 1-2GB
• Redis：CPU 0.5核，内存 1GB
• Elasticsearch：CPU 1-2核，内存 2-4GB
• MinIO：CPU 0.5核，内存 1GB

存储配置

• MySQL 数据：10-50GB
• Redis 数据：1-5GB
• Elasticsearch 数据：10-50GB
• 文件上传：根据业务需求，建议 50GB+
• MinIO 数据：根据业务需求

访问地址

部署完成后，可以通过以下方式访问：

微语系统

• Web 界面：http://your-domain 或 http://your-node-ip:30090
• API 文档：http://your-domain/swagger-ui/index.html

Ingress 配置说明

概述

Ingress 提供了统一的入口点，支持以下功能：

• 负载均衡：自动分发流量到多个 Pod
• SSL/TLS 终止：支持 HTTPS 访问
• 路径路由：根据 URL 路径路由到不同服务
• 域名路由：支持多域名访问
• WebSocket 支持：支持实时通信

当前配置

ingress.yaml 文件配置了以下路由：

# 主应用
- path: /
  backend: bytedesk-service:9003

# API 文档
- path: /swagger-ui
  backend: bytedesk-service:9003

# Knife4j 文档
- path: /doc.html
  backend: bytedesk-service:9003

# 文件上传
- path: /uploads
  backend: bytedesk-service:9003

# WebSocket 支持
- path: /websocket
  backend: bytedesk-service:9885

重要注解配置

# WebSocket 超时配置
nginx.ingress.kubernetes.io/proxy-connect-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"

# 文件上传大小限制
nginx.ingress.kubernetes.io/proxy-body-size: "50m"

# CORS 配置
nginx.ingress.kubernetes.io/cors-allow-origin: "*"
nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"

# 安全头配置
nginx.ingress.kubernetes.io/server-snippet: |
  add_header X-Frame-Options "SAMEORIGIN" always;
  add_header X-Content-Type-Options "nosniff" always;

使用步骤

1. 安装 Ingress Controller（如果尚未安装）：

   # 安装 NGINX Ingress Controller
   kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/cloud/deploy.yaml
   

2. 修改域名：

   # 编辑 ingress.yaml，将 weiyu.example.com 替换为您的实际域名
   sed -i 's/weiyu.example.com/your-domain.com/g' ingress.yaml
   

3. 部署 Ingress：

   # 手动部署
   kubectl apply -f ingress.yaml
   
   # 或使用 deploy.sh 脚本（已包含 Ingress 部署）
   ./scripts/deploy.sh
   

4. 配置 DNS：

   • 将域名解析到 Kubernetes 集群的入口 IP
   • 或使用本地 hosts 文件进行测试

本地测试

如果不需要 Ingress，可以使用端口转发进行本地测试：

# 端口转发到本地
kubectl port-forward svc/bytedesk-service 9003:9003 -n bytedesk

# 访问应用
curl http://localhost:9003

管理界面

• MinIO Console：http://your-domain:30091
• ActiveMQ Artemis Console：http://your-domain:30181
• Zipkin：http://your-domain:30411

默认管理员账户

• 邮箱：admin@email.com
• 密码：admin
• 手机号：13345678000
• 验证码：123456

监控和日志

查看应用状态

# 查看所有资源状态
kubectl get all -n bytedesk

# 查看 Pod 状态
kubectl get pods -n bytedesk

# 查看服务状态
kubectl get svc -n bytedesk

# 查看持久化卷
kubectl get pvc -n bytedesk

查看日志

# 查看微语应用日志
kubectl logs -f deployment/bytedesk -n bytedesk

# 查看 MySQL 日志
kubectl logs -f deployment/mysql -n bytedesk

# 查看 Redis 日志
kubectl logs -f deployment/redis -n bytedesk

# 查看 Elasticsearch 日志
kubectl logs -f deployment/elasticsearch -n bytedesk

进入容器调试

# 进入微语应用容器
kubectl exec -it deployment/bytedesk -n bytedesk -- /bin/bash

# 进入 MySQL 容器
kubectl exec -it deployment/mysql -n bytedesk -- mysql -u root -p

# 进入 Redis 容器
kubectl exec -it deployment/redis -n bytedesk -- redis-cli -a <password>

升级和回滚

升级应用

# 更新镜像版本
kubectl set image deployment/bytedesk bytedesk=registry.cn-hangzhou.aliyuncs.com/bytedesk/bytedesk:latest -n bytedesk

# 查看升级状态
kubectl rollout status deployment/bytedesk -n bytedesk

回滚应用

# 查看部署历史
kubectl rollout history deployment/bytedesk -n bytedesk

# 回滚到上一个版本
kubectl rollout undo deployment/bytedesk -n bytedesk

# 回滚到指定版本
kubectl rollout undo deployment/bytedesk --to-revision=2 -n bytedesk

备份和恢复

数据库备份

# 备份 MySQL 数据
kubectl exec deployment/mysql -n bytedesk -- mysqldump -u root -p<password> bytedesk > backup.sql

# 备份 Redis 数据
kubectl exec deployment/redis -n bytedesk -- redis-cli -a <password> BGSAVE

数据恢复

# 恢复 MySQL 数据
kubectl exec -i deployment/mysql -n bytedesk -- mysql -u root -p<password> bytedesk < backup.sql

故障排除

deploy.sh 脚本故障排除

脚本执行失败

1. kubectl 未安装

   错误: kubectl 未安装
   

   解决方案：安装 kubectl 命令行工具

   # 下载 kubectl
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
   chmod +x kubectl
   sudo mv kubectl /usr/local/bin/
   

2. PVC 绑定失败

   error: timed out waiting for the condition
   

   解决方案：检查存储类配置

   # 查看存储类
   kubectl get storageclass
   
   # 检查 PVC 状态
   kubectl get pvc -n bytedesk
   kubectl describe pvc mysql-pvc -n bytedesk
   

3. 中间件启动超时

   警告: 中间件启动超时，继续部署主应用...
   

   解决方案：手动检查中间件状态

   # 查看 Pod 状态
   kubectl get pods -n bytedesk
   
   # 查看 Pod 详情
   kubectl describe pod <pod-name> -n bytedesk
   
   # 查看 Pod 日志
   kubectl logs <pod-name> -n bytedesk
   

4. 权限不足

   Error from server (Forbidden): ...
   

   解决方案：检查 RBAC 权限

   # 检查当前用户权限
   kubectl auth can-i create pods --namespace bytedesk
   kubectl auth can-i create pvc --namespace bytedesk
   

脚本优化建议

1. 增加超时时间：如果网络较慢，可以修改脚本中的超时时间
2. 添加更多检查：可以根据需要添加更多的健康检查
3. 日志记录：可以添加日志文件记录部署过程

常见问题

1. Pod 启动失败

   # 查看 Pod 详细状态
   kubectl describe pod <pod-name> -n bytedesk
   
   # 查看 Pod 日志
   kubectl logs <pod-name> -n bytedesk
   

2. 服务无法访问

   # 检查服务状态
   kubectl get svc -n bytedesk
   
   # 检查 Endpoints
   kubectl get endpoints -n bytedesk
   

3. 存储问题

   # 检查 PVC 状态
   kubectl get pvc -n bytedesk
   
   # 检查 PV 状态
   kubectl get pv
   

4. 网络问题

   # 检查网络策略
   kubectl get networkpolicy -n bytedesk
   
   # 测试服务连通性
   kubectl run test-pod --image=busybox -n bytedesk --rm -it --restart=Never -- nslookup mysql-service
   

性能优化

1. 资源调优

   • 根据实际负载调整 CPU 和内存限制
   • 配置合适的副本数

2. 存储优化

   • 使用 SSD 存储类提高 I/O 性能
   • 配置合适的存储大小

3. 网络优化

   • 使用 Service Mesh 进行流量管理
   • 配置合适的网络策略

清理资源

使用清理脚本（推荐）

# 运行清理脚本，会提示确认
./scripts/cleanup.sh

重新部署

# 清理后重新部署
./scripts/cleanup.sh
./scripts/deploy.sh

手动清理资源

# 删除所有微语相关资源
kubectl delete namespace bytedesk

# 或者逐个删除
kubectl delete -f . -n bytedesk

# 删除持久化存储（谨慎操作，会删除所有数据）
kubectl delete pvc --all -n bytedesk

清理特定服务

# 只删除主应用，保留数据
kubectl delete deployment bytedesk -n bytedesk
kubectl delete service bytedesk -n bytedesk

# 只删除中间件，保留数据
kubectl delete deployment mysql redis elasticsearch artemis minio zipkin -n bytedesk
kubectl delete service mysql-service redis-service elasticsearch-service artemis-service minio-service zipkin-service -n bytedesk

许可证说明

请遵守 Business Source License 1.1 许可证条款：

• 不得销售、转售或将微语系统作为服务托管
• 违反条款将自动终止您的许可证权利
• 详细条款：https://github.com/Bytedesk/bytedesk/blob/main/LICENSE

技术支持

• 官方网站：https://www.weiyuai.cn
• 文档地址：https://www.weiyuai.cn/docs
• GitHub：https://github.com/Bytedesk/bytedesk
• 联系方式：270580156@qq.com