deployment-guide

部署指南创建器

用于创建适合生产环境的部署文档的专家。

核心原则

结构与组织

• 首先列出先决条件
• 提供特定环境的说明
• 在每个阶段之后进行验证
• 记录回滚流程
• 涵盖运营就绪情况

文档标准

• 指令使用祈使语气
• 提供准确的命令和预期输出
• 指明所有工具的版本
• 说明每个步骤的重要性
• 估算每个阶段的执行时间

标准指南结构

# Deployment Guide: [Application Name]

## Overview
- Application description
- Deployment strategy (blue-green, rolling, canary)
- Architecture diagram
- Key contacts

## Prerequisites

### System Requirements
- OS: Ubuntu 22.04 LTS
- RAM: 8GB minimum
- Disk: 50GB SSD
- Network: 100Mbps

### Required Tools
| Tool | Version | Purpose |
|------|---------|---------|
| Docker | 24.0+ | Containerization |
| kubectl | 1.28+ | Kubernetes CLI |
| Helm | 3.12+ | Package management |

### Access Requirements
- [ ] SSH access to jump server
- [ ] Kubernetes cluster credentials
- [ ] Container registry credentials
- [ ] Secrets management access

### Security Checklist
- [ ] VPN connection established
- [ ] MFA configured
- [ ] SSH keys rotated (< 90 days)

部署前检查清单

## Pre-Deployment Checklist

### Code Readiness
- [ ] All tests passing in CI
- [ ] Code review approved
- [ ] Security scan completed
- [ ] Documentation updated

### Environment Checks
- [ ] Target cluster healthy
- [ ] Database backups verified
- [ ] Monitoring alerts silenced
- [ ] Maintenance window scheduled

### Rollback Preparation
- [ ] Previous version tagged
- [ ] Rollback procedure tested
- [ ] Data migration reversible
- [ ] Communication plan ready

部署阶段

阶段 1：基础设施准备

# Estimated time: 10 minutes

# 1. Verify cluster connectivity
kubectl cluster-info
# Expected: Kubernetes control plane is running

# 2. Check node readiness
kubectl get nodes
# Expected: All nodes in "Ready" state

# 3. Verify namespace exists
kubectl get namespace production
# If not exists:
kubectl create namespace production

阶段 2：应用部署

# Estimated time: 15 minutes

# 1. Pull latest configuration
git pull origin main
cd deployment/kubernetes

# 2. Update image tag in values
export IMAGE_TAG=v1.2.3
sed -i "s/tag: .*/tag: ${IMAGE_TAG}/" values.yaml

# 3. Deploy with Helm
helm upgrade --install myapp ./charts/myapp \
  --namespace production \
  --values values.yaml \
  --wait \
  --timeout 10m

# Expected output:
# Release "myapp" has been upgraded. Happy Helming!

阶段 3：数据库迁移

# Estimated time: 5-30 minutes (depends on data size)

# 1. Create backup before migration
kubectl exec -n production deploy/myapp -- \
  pg_dump -Fc > backup_$(date +%Y%m%d_%H%M%S).dump

# 2. Run migrations
kubectl exec -n production deploy/myapp -- \
  npm run migrate

# 3. Verify migration status
kubectl exec -n production deploy/myapp -- \
  npm run migrate:status

Kubernetes 部署示例

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: production
  labels:
    app: myapp
    version: v1.2.3
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: registry.example.com/myapp:v1.2.3
          ports:
            - containerPort: 8080
          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "500m"
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5
          env:
            - name: NODE_ENV
              value: "production"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: myapp-secrets
                  key: database-url

部署后验证

## Verification Checklist

### Health Checks
- [ ] All pods running: `kubectl get pods -n production`
- [ ] Endpoints healthy: `curl -s https://api.example.com/health`
- [ ] Database connected: Check application logs

### Performance Validation
- [ ] Response time < 200ms (p95)
- [ ] Error rate < 0.1%
- [ ] Memory usage stable

### Security Checks
- [ ] TLS certificates valid
- [ ] No sensitive data in logs
- [ ] Rate limiting active

验证脚本

#!/bin/bash
# verify-deployment.sh

echo "=== Deployment Verification ==="

# Check pod status
echo "Checking pods..."
READY_PODS=$(kubectl get pods -n production -l app=myapp \
  -o jsonpath='{.items[*].status.containerStatuses[0].ready}' | tr ' ' '\n' | grep -c true)
TOTAL_PODS=$(kubectl get pods -n production -l app=myapp --no-headers | wc -l)

if [ "$READY_PODS" -eq "$TOTAL_PODS" ]; then
  echo "✅ All $TOTAL_PODS pods ready"
else
  echo "❌ Only $READY_PODS of $TOTAL_PODS pods ready"
  exit 1
fi

# Check endpoints
echo "Checking health endpoint..."
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health)
if [ "$HTTP_CODE" -eq 200 ]; then
  echo "✅ Health endpoint returning 200"
else
  echo "❌ Health endpoint returning $HTTP_CODE"
  exit 1
fi

# Check logs for errors
echo "Checking for errors in logs..."
ERROR_COUNT=$(kubectl logs -n production -l app=myapp --since=5m | grep -c "ERROR")
if [ "$ERROR_COUNT" -lt 5 ]; then
  echo "✅ Error count acceptable: $ERROR_COUNT"
else
  echo "⚠️ High error count: $ERROR_COUNT"
fi

echo "=== Verification Complete ==="

回滚流程

自动回滚触发条件

• 健康检查连续失败超过 3 次
• 错误率在 5 分钟内超过 5%
• P99 延迟在 5 分钟内超过 2 秒

手动回滚步骤

# Estimated time: 5 minutes

# 1. Identify previous release
helm history myapp -n production

# 2. Rollback to previous version
helm rollback myapp [REVISION] -n production --wait

# 3. Verify rollback
kubectl get pods -n production -l app=myapp
curl -s https://api.example.com/health

# 4. If database migration needs reversal
kubectl exec -n production deploy/myapp -- \
  npm run migrate:down

数据恢复

# Restore from backup if needed
kubectl exec -n production deploy/myapp -- \
  pg_restore -d myapp_production backup_20240101_120000.dump

故障排查

常见问题

## Issue: Pods stuck in ImagePullBackOff

**Symptoms:**
- Pods show ImagePullBackOff status
- Events show "Failed to pull image"

**Resolution:**
1. Verify image exists: `docker pull registry.example.com/myapp:v1.2.3`
2. Check registry credentials: `kubectl get secret regcred -n production`
3. Recreate secret if needed:
   ```bash
   kubectl create secret docker-registry regcred \
     --docker-server=registry.example.com \
     --docker-username=user \
     --docker-password=pass \
     -n production

问题：健康检查失败

症状：

• Pod 频繁重启
• 事件中出现就绪探针失败

解决方法：

1. 检查应用日志：kubectl logs -n production deploy/myapp
2. 验证环境变量：kubectl exec -n production deploy/myapp -- env
3. 手动测试健康端点：kubectl port-forward deploy/myapp 8080:8080
4. 如果启动较慢，请增加探针超时时间

### Log Locations

```markdown
| Log Type | Location | Command |
|----------|----------|---------|
| Application | Pod stdout | `kubectl logs deploy/myapp` |
| Ingress | Ingress controller | `kubectl logs -n ingress deploy/nginx` |
| Events | Kubernetes events | `kubectl get events -n production` |
| Audit | Cluster audit logs | `/var/log/kubernetes/audit.log` |

紧急联系人

| Role | Name | Contact |
|------|------|---------|
| On-call Engineer | PagerDuty | #ops-escalation |
| Database Admin | DBA Team | [email protected] |
| Security | Security Team | [email protected] |

CI/CD 集成

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    steps:
      - uses: actions/checkout@v4

      - name: Configure kubectl
        uses: azure/k8s-set-context@v3
        with:
          kubeconfig: ${{ secrets.KUBE_CONFIG }}

      - name: Deploy with Helm
        run: |
          helm upgrade --install myapp ./charts/myapp \
            --namespace production \
            --set image.tag=${{ github.ref_name }} \
            --wait \
            --timeout 10m

      - name: Verify deployment
        run: ./scripts/verify-deployment.sh

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {"text": "⚠️ Deployment failed for ${{ github.ref_name }}"}

最佳实践

1. 测试回滚 — 定期测试回滚流程
2. 增量部署 — 从少量流量开始
3. 功能标志 — 将部署与发布分离
4. 优先监控 — 在部署前配置监控
5. 记录一切 — 所有步骤都必须可复现
6. 自动化验证 — 使用脚本代替手动检查