docs/zh/deploy/astrbot/kubernetes.md

使用 Kubernetes 部署 AstrBot

通过 Kubernetes (K8s) 可以将 AstrBot 以高可用的方式部署在集群环境中，当出现故障时可以自动拉起恢复。

由于 AstrBot 当前使用 SQLite 数据库，此部署方案不支持多副本水平扩展。同时，若采用 Sidecar 模式，NapCat 的登录状态持久化需要您特别关注。

以下教程默认您的环境已安装并配置好 kubectl，且能够连接到您的 K8s 集群。

准备工作

在开始之前，请确保您的 Kubernetes 集群满足以下条件：

1. 拥有默认的 StorageClass：用于动态创建 PersistentVolumeClaim (PVC)。您可以通过 kubectl get sc 查看。如果没有，您需要手动创建 PersistentVolume (PV) 或安装相应的存储插件 (如 nfs-client-provisioner)。
2. 网络访问：确保您的集群节点可以从 docker.io 或您指定的镜像仓库拉取镜像。

部署方式

我们提供两种部署方案：

• **集成部署 (Sidecar 模式)**：将 AstrBot 和 NapCat 部署在同一个 Pod 中，推荐用于 QQ 个人号。
• 独立部署：只部署 AstrBot，适用于其他平台或您希望独立管理 NapCat 的场景。

---

方式一：和 NapCatQQ 一起部署 (Sidecar)

此方式位于 k8s/astrbot_with_napcat 目录。

1. 部署

# 1. 创建命名空间
kubectl apply -f k8s/astrbot_with_napcat/00-namespace.yaml

# 2. 创建持久化存储卷
# 注意：astrbot-data-shared-pvc 需要 ReadWriteMany (RWX) 访问模式。
# 如果您的集群不支持 RWX，您需要配置 NFS 等共享存储，并修改 01-pvc.yaml 中的 storageClassName。
kubectl apply -f k8s/astrbot_with_napcat/01-pvc.yaml

# 3. 部署应用
kubectl apply -f k8s/astrbot_with_napcat/02-deployment.yaml

2. 暴露服务 (二选一)

• 方式 A: NodePort

  kubectl apply -f k8s/astrbot_with_napcat/03-service-nodeport.yaml
  

  服务将通过节点 IP 和一个由 Kubernetes 自动分配的端口暴露。您可以通过以下命令查看端口：

  kubectl get svc -n astrbot-ns
  

  在输出中找到 astrbot-webui-svc 和 napcat-web-svc 的 PORT(S) 列，格式为 <内部端口>:<NodePort端口>/TCP。例如 8080:30185/TCP，则访问地址为 http://<NodeIP>:30185。

• 方式 B: LoadBalancer

  如果您的集群支持 LoadBalancer 类型的服务 (通常在云厂商的 K8s 服务中提供)，可以使用此方式。

  kubectl apply -f k8s/astrbot_with_napcat/04-service-loadbalancer.yaml
  

  执行后，通过 kubectl get svc -n astrbot-ns 查看分配到的外部 IP (EXTERNAL-IP)。

3. 配置连接

由于 AstrBot 和 NapCat 在同一个 Pod 中，它们可以通过 localhost 直接通信。

1. 在 AstrBot 中添加消息平台：

   • 进入 AstrBot WebUI，选择 设置 -> 消息平台 -> 添加。
   • 选择消息平台类别: aiocqhttp
   • 机器人名称: napcat (或自定义)
   • 反向 Websocket 主机: 0.0.0.0
   • 反向 Websocket 端口: 6199
   • 保存配置。

2. 在 NapCat 中配置 Websocket Client：

   • 进入 NapCat WebUI，选择 设置 -> 反向WS -> 添加。
   • 启用: 开启
   • URL: ws://localhost:6199/ws
   • 消息格式: Array
   • 保存配置。

---

方式二：只部署 AstrBot (通用方式)

此方式位于 k8s/astrbot 目录。

1. 部署

# 1. 创建命名空间
kubectl apply -f k8s/astrbot/00-namespace.yaml

# 2. 创建持久化存储卷
kubectl apply -f k8s/astrbot/01-pvc.yaml

# 3. 部署应用
kubectl apply -f k8s/astrbot/02-deployment.yaml

2. 暴露服务 (二选一)

• 方式 A: NodePort

  kubectl apply -f k8s/astrbot/03-service-nodeport.yaml
  

  服务将通过节点 IP 和一个由 Kubernetes 自动分配的端口暴露。您可以通过以下命令查看端口：

  kubectl get svc -n astrbot-standalone-ns
  

  在输出中找到 astrbot-webui-svc 的 PORT(S) 列，格式为 <内部端口>:<NodePort端口>/TCP。例如 8080:30185/TCP，则访问地址为 http://<NodeIP>:30185。

• 方式 B: LoadBalancer

  kubectl apply -f k8s/astrbot/04-service-loadbalancer.yaml
  

  执行后，通过 kubectl get svc -n astrbot-standalone-ns 查看分配到的外部 IP (EXTERNAL-IP)。

---

高级配置

镜像加速 (中国大陆用户)

如果拉取 soulter/astrbot:latest 或 mlikiowa/napcat-docker:latest 镜像困难，可以手动修改对应的 02-deployment.yaml 文件，将 image 字段替换为国内的镜像加速地址，例如：

# 示例：
# image: soulter/astrbot:latest
# 替换为
image: m.daocloud.io/docker.io/soulter/astrbot:latest

启用 Docker 沙箱代码执行器

如果您需要使用沙箱代码执行器，需要将 Docker 的 socket 文件挂载到 Pod 中。

编辑 02-deployment.yaml 文件，在 spec.template.spec 下添加 volumes 和 volumeMounts：

1. 在 astrbot 容器的 volumeMounts 列表下添加以下内容：

   - name: docker-sock
     mountPath: /var/run/docker.sock
   

2. 在 spec.template.spec.volumes 列表下添加以下内容：

   - name: docker-sock
     hostPath:
       path: /var/run/docker.sock
       type: Socket
   

将 Docker socket 挂载到 Pod 中存在安全风险，请确保您了解其影响。

查看日志

• Sidecar 部署模式:

  # 查看 AstrBot 日志
  kubectl logs -f -n astrbot-ns deployment/astrbot-stack -c astrbot
  
  # 查看 NapCat 日志
  kubectl logs -f -n astrbot-ns deployment/astrbot-stack -c napcat
  

• 独立部署模式:

  kubectl logs -f -n astrbot-standalone-ns deployment/astrbot-standalone
  

🎉 大功告成

部署并暴露服务后，您就可以通过相应的 IP 和端口访问 AstrBot 管理面板了。

默认用户名和密码是 astrbot 和 astrbot。