Super Dock错误码体系设计与容器运维实践

1. Super Dock错误码体系解析

在开发运维过程中，错误码系统是快速定位问题的第一道防线。Super Dock作为企业级容器管理平台，其错误码设计遵循"分类明确、信息完整、便于排查"的原则。整套体系采用HTTP状态码+业务码的复合编码方式，通过6位数字实现精准错误定位。

1.1 错误码结构说明

标准错误码格式为：XXYYZZ

• XX：主分类码（10-99）
• YY：子模块码（00-99）
• ZZ：具体错误序号（00-99）

例如错误码401203表示：

• 40：资源操作类错误
• 12：存储卷模块
• 03：具体为存储配额不足错误

1.2 核心错误分类

1.2.1 系统级错误（10-19）

• 100001：Docker引擎连接失败
• 100002：Kubernetes API不可用
• 100003：节点资源耗尽

1.2.2 认证授权错误（20-29）

• 200101：无效的API密钥
• 200205：RBAC权限不足
• 200307：证书过期

1.2.3 网络通信错误（30-39）

• 300102：容器端口冲突
• 300204：Ingress配置错误
• 300306：网络策略冲突

2. 典型错误场景处理指南

2.1 存储类错误（40-49）

2.1.1 错误码401203处理流程

1. 检查存储配额：

bash复制kubectl describe quota -n <namespace>

2. 清理无用PV：

bash复制kubectl get pv | grep Released | awk '{print $1}' | xargs kubectl delete pv

3. 扩容存储方案：

yaml复制apiVersion: storage.k8s.io/v1
kind: StorageClass
parameters:
  size: "500Gi"

关键点：存储配额计算包含PVC和临时存储，扩容后需等待5分钟生效

2.2 调度失败错误（50-59）

2.2.1 错误码501107排查步骤

1. 查看事件详情：

bash复制kubectl describe pod <pod-name> | grep -A 10 Events

2. 检查节点标签匹配：

bash复制kubectl get nodes --show-labels | grep <label-key>

3. 资源请求调整建议：

yaml复制resources:
  requests:
    cpu: "1"
    memory: "2Gi"
  limits:
    cpu: "2" 
    memory: "4Gi"

3. 错误码扩展开发规范

3.1 自定义错误码实现

推荐采用错误码生成器：

go复制func NewErrorCode(module int, sequence int) int {
    base := 40 * 10000 // 模块基础码
    return base + module*100 + sequence
}

// 使用示例
const (
    ErrVolumeMountFailed = NewErrorCode(12, 15) // 401215
)

3.2 错误信息国际化

错误模板配置示例：

json复制{
  "401203": {
    "en": "Storage quota exhausted",
    "zh": "存储配额不足",
    "solution": {
      "doc": "https://docs.superdock.io/storage/quota",
      "steps": ["check_quota", "clean_pv"]
    }
  }
}

4. 监控与告警集成

4.1 Prometheus告警规则

示例关键指标监控：

yaml复制groups:
- name: superdock-errors
  rules:
  - alert: HighErrorRate
    expr: rate(superdock_errors_total{code=~"5.."}[5m]) > 10
    labels:
      severity: critical
    annotations:
      summary: "High error rate ({{ $value }})"

4.2 错误追踪建议

1. 日志关联字段：

log复制{"error_code":401203,"trace_id":"abc123","timestamp":"2023-07-20T08:00:00Z"}

2. ELK过滤查询：

json复制{
  "query": {
    "term": {
      "error_code": 401203
    }
  }
}

5. 故障排查实战案例

5.1 网络超时问题(300508)

现象：容器间通信间歇性失败
排查工具：

bash复制# 容器网络诊断
kubectl run -it --rm debug --image=nicolaka/netshoot --restart=Never -- bash

# 在诊断容器中执行
mtr -rw <目标IP>

解决方案：

1. 检查Calico网络策略重叠
2. 调整kube-proxy的conntrack参数
3. 升级CNI插件版本

5.2 镜像拉取失败(600302)

典型处理流程：

1. 检查镜像仓库凭证：

bash复制kubectl get secret <secret-name> -o yaml | grep "\.dockerconfigjson"

2. 测试直接拉取：

bash复制docker pull <image>:<tag> --creds=<user>:<pass>

3. 备用方案配置：

yaml复制imagePullSecrets:
- name: regcred
imagePullPolicy: IfNotPresent

6. 错误码管理最佳实践

6.1 版本兼容性策略

1. 已废弃错误码保留至少两个版本周期
2. 新增错误码需更新API文档
3. 重大变更通过HTTP 409 Conflict返回

6.2 文档自动化方案

结合Swagger生成错误码文档：

yaml复制responses:
  400:
    description: |
      Error Code:
      - 401203: Storage quota exhausted
      - 501107: Pod scheduling failed
    schema:
      $ref: '#/definitions/ErrorResponse'

6.3 客户端处理建议

实现错误码分类处理器：

javascript复制class ErrorHandler {
  static handle(code) {
    switch(Math.floor(code/10000)) {
      case 40: return this._handleStorageError(code);
      case 50: return this._handleSchedulingError(code);
      // ...
    }
  }
  
  static _handleStorageError(code) {
    const subCode = Math.floor((code%10000)/100)
    switch(subCode) {
      case 12: return alert('存储卷操作失败');
      // ...
    }
  }
}