xiaoxia-saas/docs/HEALTH-CHECKS.md

# 健康检查和探针指南

## 📋 概述

小虾 SaaS 提供三种健康检查端点，用于不同的监控场景。

---

## 🔍 健康检查端点

### 1. /health - 存活检查（Liveness）

**用途：** 检查应用是否存活

**特点：**
- 快速响应（<10ms）
- 不检查依赖服务
- 始终返回 200（除非崩溃）

**请求：**
```bash
curl http://localhost:8000/health
```

**响应：**
```json
{
  "status": "healthy",
  "timestamp": "2026-06-17T08:41:00Z",
  "version": "1.0.0"
}
```

**使用场景：**
- Kubernetes liveness probe
- Docker health check
- 负载均衡器健康检查

---

### 2. /ready - 就绪检查（Readiness）

**用途：** 检查应用是否就绪接收流量

**特点：**
- 检查所有依赖服务
- 数据库连接
- Redis 连接
- 失败返回 503

**请求：**
```bash
curl http://localhost:8000/ready
```

**成功响应（200）：**
```json
{
  "status": "ready",
  "timestamp": "2026-06-17T08:41:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "type": "postgresql",
      "message": "Database connection successful"
    },
    "redis": {
      "status": "healthy",
      "type": "redis",
      "message": "Redis connection successful"
    }
  }
}
```

**失败响应（503）：**
```json
{
  "status": "not_ready",
  "timestamp": "2026-06-17T08:41:00Z",
  "checks": {
    "database": {
      "status": "unhealthy",
      "type": "postgresql",
      "message": "Database connection failed: timeout"
    },
    "redis": {
      "status": "healthy",
      "type": "redis",
      "message": "Redis connection successful"
    }
  }
}
```

**使用场景：**
- Kubernetes readiness probe
- 负载均衡器流量切换
- 灰度发布健康检查

---

### 3. /startup - 启动检查（Startup）

**用途：** 检查应用是否完成启动

**特点：**
- 检查数据库迁移
- 检查初始化状态
- 失败返回 503

**请求：**
```bash
curl http://localhost:8000/startup
```

**响应：**
```json
{
  "status": "started",
  "timestamp": "2026-06-17T08:41:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "type": "postgresql",
      "message": "Database connection successful"
    },
    "migrations": {
      "status": "healthy",
      "message": "Database migrations applied"
    }
  }
}
```

**使用场景：**
- Kubernetes startup probe
- 应用启动验证
- 部署后检查

---

## 🐳 Docker 配置

### Dockerfile

```dockerfile
# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
```

### docker-compose.yml

```yaml
services:
  api:
    image: xiaoxia-saas:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 40s
```

---

## ☸️ Kubernetes 配置

### Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: xiaoxia-api
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: xiaoxia-saas:latest
        ports:
        - containerPort: 8000
        
        # 存活探针（应用崩溃时重启）
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 15
          periodSeconds: 10
          timeoutSeconds: 3
          failureThreshold: 3
        
        # 就绪探针（依赖服务未就绪时不接收流量）
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 2
        
        # 启动探针（启动慢的应用）
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
          initialDelaySeconds: 0
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 30  # 30 * 5s = 150s 最大启动时间
```

---

## 🔧 负载均衡器配置

### Nginx

```nginx
upstream xiaoxia_api {
    server 10.0.0.1:8000 max_fails=3 fail_timeout=30s;
    server 10.0.0.2:8000 max_fails=3 fail_timeout=30s;
}

server {
    location / {
        proxy_pass http://xiaoxia_api;
        
        # 健康检查
        health_check uri=/health interval=10s fails=3 passes=2;
    }
}
```

### AWS ALB

```yaml
TargetGroup:
  HealthCheckEnabled: true
  HealthCheckPath: /health
  HealthCheckIntervalSeconds: 30
  HealthCheckTimeoutSeconds: 5
  HealthyThresholdCount: 2
  UnhealthyThresholdCount: 3
  Matcher:
    HttpCode: '200'
```

---

## 📊 监控告警

### Prometheus 配置

```yaml
scrape_configs:
  - job_name: 'xiaoxia-health'
    metrics_path: '/health'
    scrape_interval: 30s
    static_configs:
      - targets: ['api-1:8000', 'api-2:8000']
```

### 告警规则

```yaml
groups:
- name: xiaoxia_health
  rules:
  - alert: APINotHealthy
    expr: up{job="xiaoxia-health"} == 0
    for: 1m
    annotations:
      summary: "小虾 API 不健康"
      description: "{{ $labels.instance }} 连续 1 分钟不健康"
  
  - alert: APINotReady
    expr: probe_success{job="xiaoxia-ready"} == 0
    for: 2m
    annotations:
      summary: "小虾 API 未就绪"
      description: "{{ $labels.instance }} 连续 2 分钟未就绪"
```

---

## 🎯 最佳实践

### 1. 探针超时配置

```
liveness: 较长超时（10s），避免误杀
readiness: 较短超时（5s），快速摘除异常实例
startup: 最长超时（150s），给足启动时间
```

### 2. 失败阈值

```
liveness: 较高阈值（3次），避免频繁重启
readiness: 较低阈值（2次），快速摘除
startup: 很高阈值（30次），容忍启动慢
```

### 3. 检查间隔

```
liveness: 10-30s
readiness: 5-10s
startup: 5s
```

### 4. 依赖检查

- **liveness:** 不检查依赖（避免雪崩）
- **readiness:** 检查所有依赖
- **startup:** 只检查必需依赖

---

## 🐛 故障排查

### 健康检查失败

```bash
# 1. 手动测试端点
curl -v http://localhost:8000/health
curl -v http://localhost:8000/ready
curl -v http://localhost:8000/startup

# 2. 查看日志
docker logs xiaoxia-api

# 3. 检查数据库连接
docker exec xiaoxia-api psql $DATABASE_URL -c "SELECT 1"

# 4. 检查 Redis 连接
docker exec xiaoxia-api redis-cli -u $REDIS_URL ping
```

### Pod 频繁重启

```bash
# 查看 Pod 事件
kubectl describe pod xiaoxia-api-xxx

# 查看探针配置
kubectl get pod xiaoxia-api-xxx -o yaml | grep -A 10 livenessProbe

# 调整探针参数
kubectl patch deployment xiaoxia-api -p '
spec:
  template:
    spec:
      containers:
      - name: api
        livenessProbe:
          failureThreshold: 5
          timeoutSeconds: 5
'
```

---

**最后更新:** 2026-06-17