JiuwenClaw 持久化存储落地：从方案到生产的实践验证

JiuwenClaw 持久化存储落地：从方案到生产的实践验证

继上一篇《JiuwenClaw StatefulSet 持久化存储落地实践》介绍了方案设计和核心配置后，本文分享我们在实际生产环境中的验证过程、踩坑经验和优化方向。

👉 上一篇：JiuwenClaw StatefulSet 持久化存储落地实践

---

一、生产验证：从理论到现实的跨越

在完成方案设计和配置后，我们选择了两个代表性 Pod（jiuwenclaw-2 和 jiuwenclaw-18）进行完整的业务级验证，确保方案在真实场景下可靠运行。

1.1 验证目标

验证维度	具体内容	验证方法
文件持久化	创建测试文件，Pod重建后验证存在	touch + 删除Pod + ls
技能管理	安装/卸载技能，验证变更持久化	前端操作 + 目录检查
会话历史	产生对话，验证历史记录保留	前端对话 + 日志检查
业务功能	完整业务流程验证	端到端测试

1.2 实战验证过程

步骤1：记录初始状态

# 查看挂载状态
kubectl exec -it jiuwenclaw-2 -- df -h /app/.JiuwenClaw
# 输出: /dev/sda         49G  4.7M   49G   1% /app/.JiuwenClaw

# 创建测试文件
kubectl exec -it jiuwenclaw-2 -- touch /app/.JiuwenClaw/test-persist.txt

步骤2：模拟真实业务操作

• 通过前端为该租户安装技能 <技能名称A>
• 卸载原有技能 <技能名称B>
• 产生两次对话会话

步骤3：模拟故障场景

# 删除Pod，触发StatefulSet重建
kubectl delete pod jiuwenclaw-2

# 等待重建完成（约46秒）
kubectl get pods -w | grep jiuwenclaw-2

步骤4：验证持久化效果

# 验证测试文件存在
kubectl exec -it jiuwenclaw-2 -- ls -la /app/.JiuwenClaw/test-persist.txt
# -rw-r--r-- 1 app app 0 May  9 08:17 /app/.JiuwenClaw/test-persist.txt

# 验证技能变更
kubectl exec -it jiuwenclaw-2 -- ls /app/.JiuwenClaw/agent/skills/
# 显示: <技能名称A> (已安装), <技能名称B> (已卸载)

# 验证会话历史
kubectl exec -it jiuwenclaw-2 -- ls /app/.JiuwenClaw/sessions/
# 显示两个会话文件

1.3 验证结果汇总

验证项	操作	预期	实际结果
文件持久化	创建→删Pod→重建→检查	文件存在	✅ 通过
技能安装	安装<技能名称A>→删Pod→检查	技能目录存在	✅ 通过
技能卸载	卸载<技能名称B>→删Pod→检查	原技能<技能名称B>目录不再存在	✅ 通过
会话历史	产生对话→删Pod→检查	历史记录完整	✅ 通过
业务功能	前端完整操作	功能正常	✅ 通过

---

二、踩坑实录：那些让我们深夜debug的坑

🕳️ 坑1：StatefulSet 不支持动态添加 volumeClaimTemplates

现象 ：尝试通过 kubectl apply 修改已存在的 StatefulSet，添加 volumeClaimTemplates，被 API Server 拒绝。

Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy'... are forbidden

原因 ：volumeClaimTemplates 属于 StatefulSet 的不可变字段。

解决方案：

# 低峰期删除并重建（保留Service）
kubectl delete statefulset jiuwenclaw
kubectl apply -f jiuwenclaw-statefulset-with-pvc.yaml

教训：有状态应用的存储设计必须在项目初期就纳入规划。

🕳️ 坑2：StorageClass 绑定模式导致跨可用区挂载失败

现象 ：Pod 创建后一直卡在 ContainerCreating 状态。

排查：

kubectl describe pod jiuwenclaw-0
# Events显示: 云硬盘在可用区A，但Pod调度到了可用区B

原因 ：默认 StorageClass 使用 volumeBindingMode: Immediate，PVC 创建后立即绑定云硬盘（此时 Pod 尚未调度），若 Pod 后续调度到不同可用区，则挂载失败。

解决方案 ：自定义 StorageClass，设置 WaitForFirstConsumer：

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: <SSD存储类名称>
provisioner: <CSI驱动名称>
parameters:
  type: SSD
reclaimPolicy: Retain
volumeBindingMode: WaitForFirstConsumer  
# 关键配置：延迟PVC绑定，直到Pod调度完成后再创建云硬盘，确保在同一可用区

🕳️ 坑3：应用数据路径不匹配

现象：Pod 启动成功，但应用无法写入数据。

原因 ：JiuwenClaw 默认数据目录是 /app/jiuwenclaw，而 PVC 挂载在 /app/.JiuwenClaw。

解决方案：通过环境变量覆盖（无需修改代码）：

env:
- name: JIUWEN_CLAW_ROOT
  value: /app/.JiuwenClaw
- name: JIUWEN_CLAW_LOGS
  value: /app/.JiuwenClaw/logs
- name: JIUWEN_CLAW_AGENT
  value: /app/.JiuwenClaw/agent

---

三、优化方向：从能用走向好用

3.1 当前遗留问题

问题	影响	优先级	计划方案
缩容残留 PVC	StatefulSet 缩容后PVC不自动删除，占用配额	高	编写定时清理脚本
无自动备份	误删PVC将导致数据丢失	高	接入Velero备份
成本较高	50块50Gi SSD费用不低	中	冷数据迁移至OBS
数据采集困难	无法直接访问PVC内容分析	中	临时Pod方案待验证

3.2 PVC 生命周期管理脚本

#!/bin/bash
# 清理孤儿PVC（StatefulSet已缩容但PVC仍存在）

NAMESPACE="<业务命名空间>"
APP_NAME="jiuwenclaw"

# 获取当前StatefulSet副本数
REPLICAS=$(kubectl get statefulset $APP_NAME -n $NAMESPACE -o jsonpath='{.spec.replicas}')

# 删除超出副本数的PVC
for i in $(seq $REPLICAS 49); do
  PVC_NAME="${APP_NAME}-users-data-${APP_NAME}-${i}"
  if kubectl get pvc $PVC_NAME -n $NAMESPACE &>/dev/null; then
    echo "Deleting orphan PVC: $PVC_NAME"
    kubectl delete pvc $PVC_NAME -n $NAMESPACE
  fi
done

3.3 监控告警配置

监控项	告警阈值	通知方式
PVC 使用率	>80%	企业微信 + 邮件
Pod 重启次数	>5次/小时	企业微信
PVC 绑定状态	未Bound超过5分钟	企业微信

---

四、核心经验总结

4.1 技术选型心得

方案	评估	适用场景
EmptyDir	仅适合无状态或临时数据	开发测试环境
NFS	性能差，不适合高频读写	共享配置文件
OBS + obsfs	POSIX兼容层性能极差	冷数据归档
EVS SSD	高性能，低延迟	生产级有状态应用

4.2 实践经验

1. 存储设计要前置：有状态应用从第一天就要考虑持久化方案
2. 验证要全面：不仅验证技术指标，更要验证真实业务场景
3. 环境变量是神器：通过环境变量覆盖路径，实现零代码改动迁移
4. 备份不可少：PVC持久化不是备份，必须配置独立备份策略
5. 监控要到位：PVC使用率、Pod重启、存储IO都需要监控

4.3 给后来者的建议

• 不要迷信对象存储：OBS这类存储适合归档，不适合数据库或高频读写场景
• 了解K8s设计限制 ：StatefulSet的volumeClaimTemplates不可变，设计时要考虑清楚
• 做好回滚预案：升级前备份旧配置，确保能快速回滚

---

附录：PVC 数据采集方案（临时 Pod 方式）

由于 Kubernetes 没有直接访问 PVC 文件内容的 API，数据采集需通过临时 Pod 挂载方式实现：

#!/bin/bash
NAMESPACE="<业务命名空间>"
PVC_NAME="jiuwenclaw-users-data-jiuwenclaw-0"
OUTPUT_DIR="./user_data_backup"

# 创建临时Pod挂载PVC
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: tmp-extract
  namespace: $NAMESPACE
spec:
  containers:
  - name: extractor
    image: alpine:latest
    command: ["sleep", "300"]
    volumeMounts:
    - name: data
      mountPath: /mnt/data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: $PVC_NAME
  restartPolicy: Never
EOF

# 等待Pod就绪并提取数据
kubectl wait --for=condition=Ready pod/tmp-extract -n $NAMESPACE --timeout=60s
kubectl exec -n $NAMESPACE tmp-extract -- tar -czf /tmp/data.tar.gz -C /mnt/data .
kubectl cp $NAMESPACE/tmp-extract:/tmp/data.tar.gz $OUTPUT_DIR/data.tar.gz

# 清理临时Pod
kubectl delete pod tmp-extract -n $NAMESPACE

---

五、后续计划

基于本次持久化存储落地实践，我们计划在以下方向继续优化：

1. 备份体系：接入 Velero 实现自动化 PVC 备份和恢复
2. 弹性存储：探索 CSI 快照功能，支持按需创建数据快照
3. 成本优化：实施冷热数据分离策略，降低存储成本

---

技术标签 ：#JiuwenClaw #Kubernetes #StatefulSet #PVC #存储持久化 #生产实践

本文是《JiuwenClaw 企业级部署实战》专栏第三篇，上一篇介绍了方案设计和核心配置，欢迎阅读。