Helm Chart 文档（实验性）(languages: en • zh • hi • ru)

⚠️ 实验性： Helm/Kubernetes 安装方法是实验性的，可能尚不完全稳定。

对于更可靠的安装，我们建议改用 Docker 安装方法。

本文档提供了使用 Helm 在 Kubernetes 上部署 Hive Mind 的全面指南。

前提条件

Kubernetes 集群 1.19+
Helm 3.0+
已配置访问集群的 kubectl
足够的集群资源（参见资源要求）

安装

添加 Helm 仓库

helm repo add link-assistant https://link-assistant.github.io/hive-mind
helm repo update

安装 Chart

基本安装

helm install hive-mind link-assistant/hive-mind

使用自定义值安装

helm install hive-mind link-assistant/hive-mind -f custom-values.yaml

在特定命名空间中安装

kubectl create namespace hive-mind
helm install hive-mind link-assistant/hive-mind -n hive-mind

配置

默认值

默认的 values.yaml 为大多数部署提供了合理的默认值。关键配置选项：

资源要求

默认资源分配：

resources:
  limits:
    cpu: 1000m
    memory: 2Gi
  requests:
    cpu: 500m
    memory: 1Gi

每个 Pod 推荐的最低资源：

CPU：500m（0.5 核）
内存：1Gi RAM
磁盘：50Gi 持久存储

持久化配置

默认情况下，持久存储已启用，大小为 50Gi：

persistence:
  enabled: true
  accessMode: ReadWriteOnce
  size: 50Gi

使用特定存储类：

persistence:
  enabled: true
  storageClass: 'fast-ssd'
  size: 100Gi

使用现有 PVC：

persistence:
  enabled: true
  existingClaim: 'my-existing-pvc'

认证配置

Hive Mind 需要 GitHub 和 Claude 认证。这些应通过 Kubernetes 密钥配置：

创建 GitHub Token 密钥

kubectl create secret generic hive-github-token \
  --from-literal=token='ghp_your_github_token_here'

创建 Claude API 密钥密钥

kubectl create secret generic hive-claude-api-key \
  --from-literal=apiKey='sk-ant-your_claude_key_here'

在 Values 中引用密钥

secrets:
  githubToken: 'hive-github-token'
  claudeApiKey: 'hive-claude-api-key'

作为 Telegram Bot 运行

要在 Kubernetes 中将 Hive Mind 作为 Telegram bot 运行：

command:
  - /bin/bash
  - -c
  - |
    # Authenticate with GitHub using token from secret
    echo "$GITHUB_TOKEN" | gh auth login --with-token

    # Start the telegram bot
    hive-telegram-bot --configuration "
      TELEGRAM_BOT_TOKEN: '$TELEGRAM_BOT_TOKEN'
      TELEGRAM_ALLOWED_CHATS:
        -1002975819706
      TELEGRAM_HIVE_OVERRIDES:
        --all-issues
        --once
        --attach-logs
        --verbose
      TELEGRAM_BOT_VERBOSE: true
    "

env:
  TELEGRAM_BOT_TOKEN: 'your-telegram-bot-token'

自动扩缩容

为多个 bot 实例启用水平 Pod 自动扩缩容：

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

节点选择与亲和性

节点选择器

部署到特定节点：

nodeSelector:
  disktype: ssd
  workload: ai-intensive

容忍度

允许在有污点的节点上调度：

tolerations:
  - key: 'ai-workload'
    operator: 'Equal'
    value: 'true'
    effect: 'NoSchedule'

亲和性规则

共置或分散 Pod：

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: app.kubernetes.io/name
                operator: In
                values:
                  - hive-mind
          topologyKey: kubernetes.io/hostname

常见使用场景

示例 1：单个 Bot 实例

用于测试或小规模使用的简单部署：

# values-simple.yaml
replicaCount: 1

persistence:
  enabled: true
  size: 50Gi

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 1000m
    memory: 2Gi

helm install hive-mind link-assistant/hive-mind -f values-simple.yaml

示例 2：生产 Telegram Bot

带自动扩缩容的高可用部署：

# values-production.yaml
replicaCount: 3

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

persistence:
  enabled: true
  storageClass: 'fast-ssd'
  size: 100Gi

resources:
  requests:
    cpu: 1000m
    memory: 2Gi
  limits:
    cpu: 2000m
    memory: 4Gi

secrets:
  githubToken: 'hive-github-token'
  claudeApiKey: 'hive-claude-api-key'

command:
  - /bin/bash
  - -c
  - |
    echo "$GITHUB_TOKEN" | gh auth login --with-token
    hive-telegram-bot --token "$TELEGRAM_BOT_TOKEN" --verbose

podAntiAffinity:
  requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchExpressions:
          - key: app.kubernetes.io/name
            operator: In
            values:
              - hive-mind
      topologyKey: 'kubernetes.io/hostname'

helm install hive-mind link-assistant/hive-mind -f values-production.yaml

示例 3：开发环境

用于开发/测试的最小资源配置：

# values-dev.yaml
replicaCount: 1

persistence:
  enabled: false

resources:
  requests:
    cpu: 250m
    memory: 512Mi
  limits:
    cpu: 500m
    memory: 1Gi

helm install hive-mind-dev link-assistant/hive-mind -f values-dev.yaml

升级

更新仓库

helm repo update

升级发布版本

helm upgrade hive-mind link-assistant/hive-mind

使用新值升级

helm upgrade hive-mind link-assistant/hive-mind -f new-values.yaml

回滚

# 列出发布历史
helm history hive-mind

# 回滚到上一个版本
helm rollback hive-mind

# 回滚到特定修订版
helm rollback hive-mind 2

卸载

helm uninstall hive-mind

注意： 默认情况下，PersistentVolumeClaim 不会自动删除。要删除它们：

kubectl delete pvc -l app.kubernetes.io/name=hive-mind

故障排除

检查 Pod 状态

kubectl get pods -l app.kubernetes.io/name=hive-mind

查看 Pod 日志

kubectl logs -l app.kubernetes.io/name=hive-mind --tail=100 -f

访问 Pod Shell

kubectl exec -it deployment/hive-mind -- /bin/bash

检查 PVC 状态

kubectl get pvc
kubectl describe pvc hive-mind

常见问题

Pod 无法启动

症状： Pod 卡在 Pending 状态

解决方案：

检查节点资源：kubectl describe node
验证 PVC 是否已绑定：kubectl get pvc
检查存储类是否存在：kubectl get storageclass

认证问题

症状： GitHub/Claude 命令失败

解决方案：

验证密钥是否存在：kubectl get secrets
检查密钥内容：kubectl describe secret hive-github-token

在 Pod 内手动认证：

kubectl exec -it deployment/hive-mind -- /bin/bash
gh auth login
claude

内存不足

症状： Pod 因 OOMKilled 崩溃

解决方案：

在 values.yaml 中增加内存限制
监控实际使用情况：kubectl top pods
考虑使用自动扩缩容

高级配置

多个 Helm 发布版本

运行多个隔离的 Hive Mind 实例：

# 实例 1 - 团队 A
helm install hive-team-a link-assistant/hive-mind \
  -n team-a --create-namespace \
  -f team-a-values.yaml

# 实例 2 - 团队 B
helm install hive-team-b link-assistant/hive-mind \
  -n team-b --create-namespace \
  -f team-b-values.yaml

自定义镜像

使用自定义 Docker 镜像：

image:
  repository: myregistry.com/custom-hive-mind
  tag: '1.0.0'
  pullPolicy: Always

imagePullSecrets:
  - name: myregistrykey

额外卷

挂载额外卷：

volumes:
  - name: custom-config
    configMap:
      name: hive-config

volumeMounts:
  - name: custom-config
    mountPath: /etc/hive-config
    readOnly: true

监控与可观测性

资源监控

# 观察资源使用情况
kubectl top pods -l app.kubernetes.io/name=hive-mind

# 持续观察
watch kubectl top pods -l app.kubernetes.io/name=hive-mind

日志记录

与 ELK、Loki 或 CloudWatch 等日志系统集成：

podAnnotations:
  prometheus.io/scrape: 'true'
  prometheus.io/port: '9090'

安全最佳实践

使用密钥管理： 将 GitHub token 和 API 密钥存储在 Kubernetes 密钥或外部密钥管理器（HashiCorp Vault、AWS Secrets Manager）中

网络策略： 限制 Pod 之间的网络访问：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: hive-mind-netpol
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: hive-mind
  policyTypes:
    - Ingress
    - Egress
  egress:
    - to:
        - namespaceSelector: {}

Pod 安全标准： 使用受限的 Pod 安全标准：

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000
  seccompProfile:
    type: RuntimeDefault

RBAC： 为服务账户创建最小角色权限
定期更新： 保持 chart 和容器镜像更新

支持与贡献

GitHub Issues： https://github.com/link-assistant/hive-mind/issues
文档： https://github.com/link-assistant/hive-mind
Docker Hub： https://hub.docker.com/r/konard/hive-mind
ArtifactHub： https://artifacthub.io/packages/helm/link-assistant/hive-mind

许可证

此 Helm chart 在 Unlicense 下发布。详情请参阅 LICENSE 文件。

FilesExpand file tree

HELM.zh.md

Latest commit

History

HELM.zh.md

File metadata and controls

Helm Chart 文档（实验性）(languages: en • zh • hi • ru)

前提条件

安装

添加 Helm 仓库

安装 Chart

基本安装

使用自定义值安装

在特定命名空间中安装

配置

默认值

资源要求

持久化配置

认证配置

创建 GitHub Token 密钥

创建 Claude API 密钥密钥

在 Values 中引用密钥

作为 Telegram Bot 运行

自动扩缩容

节点选择与亲和性

节点选择器

容忍度

亲和性规则

常见使用场景

示例 1：单个 Bot 实例

示例 2：生产 Telegram Bot

示例 3：开发环境

升级

更新仓库

升级发布版本

使用新值升级

回滚

卸载

故障排除

检查 Pod 状态

查看 Pod 日志

访问 Pod Shell

检查 PVC 状态

常见问题

Pod 无法启动

认证问题

内存不足

高级配置

多个 Helm 发布版本

自定义镜像

额外卷

监控与可观测性

资源监控

日志记录

安全最佳实践

支持与贡献

许可证