juwan-backend/docs/deployment-troubleshooting.md

Kubernetes 部署问题排查与解决记录

日期: 2026年2月23日
问题: user-rpc 和 Redis 部署失败
状态: 已诊断，解决中

---

📋 问题描述

执行 kubectl apply -f test.yaml 后，资源虽然创建成功，但实际的应用 pods 并未正常运行：

kubectl apply -f ..\test.yaml
✓ deployment.apps/user-rpc created
✓ service/user-rpc-svc created
✓ horizontalpodautoscaler.autoscaling/user-rpc-hpa-c created
✓ horizontalpodautoscaler.autoscaling/user-rpc-hpa-m created
✓ redisreplication.redis.redis.opstreelabs.in/user-redis created
✓ redissentinel.redis.redis.opstreelabs.in/user-redis-sentinel created
✓ cluster.postgresql.cnpg.io/user-db created

但执行 kubectl get all 后，发现：

• ❌ user-rpc pods 未创建（Deployment 0/3 replicas ready）
• ❌ Redis pods 未创建（RedisReplication 资源存在但无 pods）
• ✅ user-db pods 正常运行（3/3）

---

🔍 排查过程

第一步：检查 Deployment 状态

kubectl describe deployment user-rpc

发现：

Conditions:
  Type             Status  Reason
  ----             ------  ------
  Progressing      True    NewReplicaSetCreated
  Available        False   MinimumReplicasUnavailable
  ReplicaFailure   True    FailedCreate

第二步：检查 ReplicaSet 详情

kubectl describe replicaset user-rpc-6bf77fbcd9

发现关键错误：

Events:
  Type     Reason        Age        From                   Message
  ----     ------        ----       ----                   -------
  Warning  FailedCreate  3m53s      replicaset-controller  Error creating: 
           pods "user-rpc-6bf77fbcd9-" is forbidden: error looking up service 
           account default/find-endpoints: serviceaccount "find-endpoints" not found

问题 #1 诊断完成：❌ 缺失 ServiceAccount "find-endpoints"

第三步：检查现有 ServiceAccounts

kubectl get serviceaccount

结果：

NAME              AGE
cluster-example   4d10h
default           13d
redis-operator    9h
user-db           4m9s

确认 find-endpoints 不存在。

第四步：检查 Secrets

kubectl get secrets

结果：默认 secrets 都存在，包括：

• ✅ user-db-app
• ✅ user-redis
• ✅ user-db-ca, user-db-replication, user-db-server

第五步：检查 Redis 部署

kubectl get redisreplication
kubectl get pods | grep redis

发现：

• ✅ RedisReplication 资源存在
• ❌ Redis pods 完全没有被创建

问题 #2 诊断：❌ Redis Operator 未响应 RedisReplication 资源

---

🔧 第一次修复尝试

创建缺失的 ServiceAccount

kubectl create serviceaccount find-endpoints

结果：✅ ServiceAccount 创建成功

重启 Deployment

kubectl rollout restart deployment user-rpc

等待 5-10 秒后重新检查：

kubectl get pods -o wide

新的发现：

NAME                        READY   STATUS             RESTARTS       AGE
user-rpc-66f97fbdcc-ws7rc   0/1     ErrImagePull       0              26s
user-rpc-6bf77fbcd9-njm2z   0/1     ErrImagePull       0              29s
user-rpc-6bf77fbcd9-nwjtw   0/1     ImagePullBackOff   0              29s
user-rpc-6bf77fbcd9-wjrf8   0/1     ErrImagePull       0              29s

✅ 好消息：Pods 现在被创建了！（说明 ServiceAccount 问题已解决）
❌ 新问题：镜像拉取失败

---

🐛 根因分析

问题 #1：缺失 ServiceAccount ✅ 已解决

根本原因：test.yaml 的 Deployment manifest 指定了：

spec:
  template:
    spec:
      serviceAccountName: find-endpoints  # 这个 ServiceAccount 不存在

但没有在 test.yaml 中创建 ServiceAccount 资源。

解决方案：

kubectl create serviceaccount find-endpoints

或在 test.yaml 中添加：

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: find-endpoints
  namespace: default

---

问题 #2：镜像拉取失败 ❌ 需要修复

kubectl describe pod user-rpc-6bf77fbcd9-njm2z

详细错误日志：

Events:
  Warning  Failed     38s     kubelet  Failed to pull image 
    "103.236.53.208:4418/library/user-rpc@sha256:76b27d3eb4d5d44e...": 
    Error response from daemon: Get "https://103.236.53.208:4418/v2/": 
    context deadline exceeded (Client.Timeout exceeded while awaiting headers)
    
  Warning  Failed     23s     kubelet  Failed to pull image 
    "103.236.53.208:4418/library/user-rpc@sha256:76b27d3eb4d5d44e...": 
    http: server gave HTTP response to HTTPS client

根本原因分析：

1. 网络连接失败：context deadline exceeded - 无法连接到镜像仓库
2. 协议不匹配：http: server gave HTTP response to HTTPS client -
   • 地址 103.236.53.208:4418 应该是 HTTP 而不是 HTTPS
   • Docker daemon 尝试用 HTTPS 连接，但服务器使用 HTTP

可能原因：

• 镜像仓库地址错误或不可访问
• 镜像仓库需要特定的网络配置
• 仓库服务器离线或配置不当

---

问题 #3：Redis 部署失败 ❌ 需要诊断

现象：

• RedisReplication 和 RedisSentinel CRD 资源创建成功
• 但没有对应的 Redis pods 被创建
• kubectl get pods | grep redis 返回空

可能原因：

1. Redis Operator 未正常工作

   • Operator pod 可能存在问题
   • Operator 未能监听到新的 RedisReplication 资源

2. CRD 或 API 版本问题

   • manifest 中使用的 API 版本 v1beta2 可能不匹配 Operator 版本

3. 资源限制或权限问题

   • Operator 无权限创建 pods
   • 集群资源限制阻止了 pod 创建

---

✅ 已执行的修复

#	问题	修复方法	状态
1	缺失 ServiceAccount	kubectl create serviceaccount find-endpoints	✅ 完成
2	镜像拉取失败	需要更新镜像地址或修复网络	⏳ 待处理
3	Redis pods 未创建	需要诊断 Operator 日志	⏳ 待诊断

---

🚀 下一步解决方案

优先级 1：修复 user-rpc 镜像拉取

选项 A：使用本地/内部镜像

# 修改 test.yaml 中的镜像地址
image: localhost:5000/user-rpc:latest  # 本地私有仓库
# 或
image: user-rpc:latest  # 本地镜像（如果已通过 docker load 导入）

选项 B：修复仓库地址

# 如果 103.236.53.208:4418 确实是正确仓库
image: http://103.236.53.208:4418/library/user-rpc:latest  # 显式使用 HTTP

验证步骤：

# 检查镜像仓库连接性
curl -v http://103.236.53.208:4418/v2/

优先级 2：诊断 Redis Operator

# 查看 Operator 日志
kubectl logs -l app.kubernetes.io/name=redis-operator -f

# 查看 Operator pod
kubectl get pods -A | grep redis-operator

# 查看 RedisReplication 详细信息
kubectl describe redisreplication user-redis

# 检查 Operator 权限（RBAC）
kubectl get role,rolebinding,clusterrole,clusterrolebinding | grep redis

优先级 3：增强 test.yaml

建议在 test.yaml 中添加缺失的资源定义：

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: find-endpoints
  namespace: default

---
apiVersion: v1
kind: Secret
metadata:
  name: registry-credentials
  namespace: default
type: kubernetes.io/dockercfg
data:
  .dockercfg: <base64-encoded-credentials>  # 如果需要私有仓库认证

---

📊 当前集群状态

Pods 状态总结

应用	期望副本	实际运行	状态
user-db	3	3	✅ 正常
user-rpc	3	0	❌ 镜像拉取失败
Redis	3	0	❌ Operator 未创建
Sentinel	3	0	❌ Operator 未创建

Services 状态

✅ kubernetes (内置)
✅ user-rpc-svc:9001
✅ user-db-r:5432 (只读副本)
✅ user-db-ro:5432 (只读副本)
✅ user-db-rw:5432 (读写主副本)

HPA 配置

✅ user-rpc-hpa-c (CPU 目标: 80%)  - 无法工作（pods 未运行）
✅ user-rpc-hpa-m (Memory 目标: 80%)  - 无法工作（pods 未运行）

---

📝 关键命令速查表

# 查看 Deployment 状态
kubectl describe deployment user-rpc

# 查看 ReplicaSet 错误事件
kubectl describe replicaset user-rpc-6bf77fbcd9

# 查看 Pod 详细错误
kubectl describe pod user-rpc-6bf77fbcd9-njm2z

# 查看 Pod 日志
kubectl logs user-rpc-6bf77fbcd9-njm2z

# 查看所有事件（按时间排序）
kubectl get events --sort-by='.lastTimestamp'

# 查看特定命名空间的所有资源
kubectl get all -n default

# 重新启动 deployment（强制重新创建 pods）
kubectl rollout restart deployment user-rpc

# 查看 Operator 日志
kubectl logs -l app.kubernetes.io/name=redis-operator

# 检查 CRD 注册状态
kubectl api-resources | grep redis

---

🎯 总结

问题	原因	解决状态
ServiceAccount 缺失	manifest 中声明但未创建	✅ 已解决
镜像拉取失败	仓库地址不可达或协议不匹配	⏳ 待处理
Redis 未部署	Operator 未响应 CRD	⏳ 待诊断

建议行动：

1. 确认/修复 user-rpc 镜像地址
2. 诊断 Redis Operator 状态
3. 验证所有依赖的 ServiceAccounts 和 Secrets 是否存在
4. 考虑在 test.yaml 中添加完整的资源定义，避免手工创建