环境隔离

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 环境隔离, 多环境, 环境配置, 隔离
---

# 环境隔离和灰度发布

本文档定义了企业管理数字化中台的环境隔离策略和灰度发布机制，确保系统稳定性和可靠性。

---

## &#127919; 核心原则

1. **环境隔离**: 不同环境完全独立，避免相互影响
2. **渐进式发布**: 小步快跑，降低风险
3. **快速回滚**: 出问题立即回滚，最小化影响
4. **数据隔离**: 测试数据和生产数据完全分离

---

## &#127760; 环境架构

### 环境层次

```
┌─────────────────────────────────────┐
│   本地开发环境 (Local Dev)           │  .env.local
│   - 开发者电脑                       │
│   - 快速迭代                         │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   开发环境 (Development)             │  .env.development
│   - dev.example.com                 │
│   - 持续集成                         │
│   - 自动化测试                       │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   测试环境 (Test)                    │  .env.test
│   - test.example.com                │
│   - QA 测试                          │
│   - 性能测试                         │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   预发布环境 (Staging)               │  .env.staging
│   - staging.example.com             │
│   - 生产环境镜像                     │
│   - 完整功能验证                     │
│   - 灰度发布                         │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   生产环境 (Production)              │  .env.production
│   - example.com                     │
│   - 正式环境                         │
│   - 真实数据                         │
│   - 高可用部署                       │
└─────────────────────────────────────┘
```

### 环境对比

| 特性 | 本地开发 | 开发环境 | 测试环境 | 预发布 | 生产 |
|------|---------|---------|---------|--------|------|
| **用途** | 开发调试 | CI/CD | QA 测试 | 验证 | 正式运行 |
| **访问** | 本地 | 内网 | 内网 | 外网 | 外网 |
| **数据** | Mock | 测试数据 | 测试数据 | 生产镜像 | 真实数据 |
| **性能** | 低 | 中 | 中 | 高 | 高 |
| **监控** | 无 | 基础 | 基础 | 完整 | 完整 |
| **备份** | 无 | 无 | 无 | 有 | 有 |
| **日志** | 控制台 | 文件 | 文件 | 收集 | 收集 |
| **用户** | 开发者 | 开发者 | QA | 产品/运营 | 真实用户 |

---

## &#128221; 环境配置

### 环境变量配置

#### 本地开发环境 (.env.local)

```bash
# 应用配置
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:5000

# 数据库配置
DATABASE_URL=postgresql://dev:dev@localhost:5432/payroll_dev?sslmode=disable

# JWT 配置
JWT_SECRET=development-secret-key-change-in-production
JWT_EXPIRES_IN=24h

# 日志配置
LOG_LEVEL=debug

# 对象存储（本地模拟）
OSS_ENDPOINT=http://localhost:9000
OSS_ACCESS_KEY_ID=minioadmin
OSS_SECRET_KEY=minioadmin
OSS_BUCKET=payroll-dev

# 短信服务（模拟）
SMS_ACCESS_KEY_ID=
SMS_SECRET_KEY=
SMS_SIGN_NAME=
SMS_TEMPLATE_CODE=

# 微信集成（测试）
WECHAT_APP_ID=your_test_app_id
WECHAT_APP_SECRET=your_test_app_secret
```

#### 开发环境 (.env.development)

```bash
# 应用配置
NODE_ENV=development
NEXT_PUBLIC_APP_URL=https://dev.example.com

# 数据库配置
DATABASE_URL=postgresql://dev:dev@dev-db.example.com:5432/payroll_dev?sslmode=require

# JWT 配置
JWT_SECRET=dev-jwt-secret-at-least-32-characters-long
JWT_EXPIRES_IN=24h

# 日志配置
LOG_LEVEL=info

# 对象存储
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
OSS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OSS_BUCKET=payroll-dev

# 短信服务
SMS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
SMS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SMS_SIGN_NAME=企业管理数字化中台
SMS_TEMPLATE_CODE=SMS_123456789

# 微信集成
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=1234567890abcdefghijklmnopqrstuvwxyz

# 监控配置
SENTRY_DSN=https://xxxxxxxxxxxxxxxxxxxxxxxxx@sentry.io/123456
```

#### 测试环境 (.env.test)

```bash
# 应用配置
NODE_ENV=test
NEXT_PUBLIC_APP_URL=https://test.example.com

# 数据库配置
DATABASE_URL=postgresql://test:test@test-db.example.com:5432/payroll_test?sslmode=require

# JWT 配置
JWT_SECRET=test-jwt-secret-at-least-32-characters-long
JWT_EXPIRES_IN=8h

# 日志配置
LOG_LEVEL=warn

# 对象存储
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
OSS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OSS_BUCKET=payroll-test

# 短信服务
SMS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
SMS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SMS_SIGN_NAME=工资表测试
SMS_TEMPLATE_CODE=SMS_123456789

# 微信集成
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=1234567890abcdefghijklmnopqrstuvwxyz
```

#### 预发布环境 (.env.staging)

```bash
# 应用配置
NODE_ENV=staging
NEXT_PUBLIC_APP_URL=https://staging.example.com

# 数据库配置
DATABASE_URL=postgresql://staging:staging@staging-db.example.com:5432/payroll_staging?sslmode=require

# JWT 配置
JWT_SECRET=staging-jwt-secret-at-least-32-characters-long
JWT_EXPIRES_IN=8h

# 日志配置
LOG_LEVEL=info

# 对象存储
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
OSS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OSS_BUCKET=payroll-staging

# 短信服务
SMS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
SMS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SMS_SIGN_NAME=工资表预发布
SMS_TEMPLATE_CODE=SMS_123456789

# 微信集成
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=1234567890abcdefghijklmnopqrstuvwxyz

# 监控配置
SENTRY_DSN=https://xxxxxxxxxxxxxxxxxxxxxxxxx@sentry.io/123457
```

#### 生产环境 (.env.production)

```bash
# 应用配置
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://example.com

# 数据库配置
DATABASE_URL=postgresql://prod:prod@prod-db.example.com:5432/payroll?sslmode=require&sslrootcert=/path/to/cert.pem

# JWT 配置
JWT_SECRET=$(openssl rand -base64 32)
JWT_EXPIRES_IN=8h

# 日志配置
LOG_LEVEL=error

# 对象存储
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
OSS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OSS_BUCKET=payroll-prod

# 短信服务
SMS_ACCESS_KEY_ID=LTAI5txxxxxxxxxxxxxxxx
SMS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SMS_SIGN_NAME=企业管理数字化中台
SMS_TEMPLATE_CODE=SMS_123456789

# 微信集成
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=1234567890abcdefghijklmnopqrstuvwxyz

# 监控配置
SENTRY_DSN=https://xxxxxxxxxxxxxxxxxxxxxxxxx@sentry.io/123458

# Redis 缓存
REDIS_URL=redis://redis-prod.example.com:6379
REDIS_PASSWORD=redis-password

# CDN 配置
CDN_DOMAIN=cdn.example.com
```

---

## &#128640; 灰度发布策略

### 1. 金丝雀发布（Canary Release）

**适用场景**: 小范围测试新功能

**步骤**:

```bash
# 步骤 1: 部署新版本到金丝雀环境（5% 流量）
kubectl apply -f deployment-canary.yaml
kubectl scale deployment payroll-canary --replicas=1

# 步骤 2: 配置流量路由（5% 到新版本）
# 使用 Istio 或 Nginx 分流
```

```nginx
# Nginx 配置示例
upstream payroll {
    server payroll-v1:5000 weight=95;    # 95% 流量
    server payroll-canary:5000 weight=5;  # 5% 流量
}
```

```bash
# 步骤 3: 观察 24 小时
# - 检查错误日志
# - 检查性能指标
# - 收集用户反馈

# 步骤 4: 如果正常，逐步扩大流量
kubectl scale deployment payroll-canary --replicas=2  # 10% 流量
kubectl scale deployment payroll-canary --replicas=3  # 20% 流量

# 步骤 5: 如果一切正常，全量发布
kubectl apply -f deployment-v2.yaml
kubectl delete deployment payroll-v1
```

**监控指标**:
- 错误率
- 响应时间
- 用户满意度
- 功能使用率

### 2. 蓝绿部署（Blue-Green Deployment）

**适用场景**: 重要更新，需要快速回滚

**步骤**:

```bash
# 步骤 1: 准备蓝环境（当前版本）
kubectl apply -f deployment-blue.yaml
kubectl set service deployment payroll --selector=version=blue

# 步骤 2: 部署绿环境（新版本）
kubectl apply -f deployment-green.yaml

# 步骤 3: 验证绿环境
kubectl port-forward deployment/green 5000:5000
curl http://localhost:5000/health

# 步骤 4: 切换流量到绿环境
kubectl patch service payroll -p '{"spec":{"selector":{"version":"green"}}}'

# 步骤 5: 观察 24 小时

# 步骤 6: 如果正常，保留绿环境，删除蓝环境
kubectl delete deployment payroll-blue

# 步骤 7: 如果有问题，快速切回蓝环境
kubectl patch service payroll -p '{"spec":{"selector":{"version":"blue"}}}'
```

**优势**:
- ✅ 快速回滚（< 1 分钟）
- ✅ 零停机时间
- ✅ 完整的环境隔离

**缺点**:
- ❌ 需要双倍资源
- ❌ 数据库迁移需要特殊处理

### 3. A/B 测试

**适用场景**: 对比不同方案的效果

**步骤**:

```bash
# 步骤 1: 部署两个版本
kubectl apply -f deployment-a.yaml  # 版本 A
kubectl apply -f deployment-b.yaml  # 版本 B

# 步骤 2: 配置流量路由（50/50）
upstream payroll {
    server payroll-a:5000 weight=50;
    server payroll-b:5000 weight=50;
}

# 步骤 3: 收集数据
# - 用户行为
# - 转化率
# - 性能指标

# 步骤 4: 分析数据，选择更好的版本
kubectl delete deployment payroll-b
kubectl patch service payroll -p '{"spec":{"selector":{"version":"a"}}}'
```

**适用场景**:
- UI 改版
- 功能优化
- 性能优化

---

## &#128202; 灰度发布配置

### Istio 流量管理

```yaml
# virtualservice.yaml
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: payroll
spec:
  hosts:
    - payroll.example.com
  http:
    - route:
        - destination:
            host: payroll
            subset: v1
          weight: 90
        - destination:
            host: payroll
            subset: v2
          weight: 10
```

```yaml
# destinationrule.yaml
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: payroll
spec:
  host: payroll
  subsets:
    - name: v1
      labels:
        version: v1
    - name: v2
      labels:
        version: v2
```

### Nginx 灰度配置

```nginx
# nginx.conf
http {
    upstream payroll {
        # 90% 流量到 v1
        server payroll-v1:5000 weight=90;
        # 10% 流量到 v2
        server payroll-v2:5000 weight=10;
    }

server {
        listen 80;
        server_name payroll.example.com;

location / {
            proxy_pass http://payroll;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}
```

---

## &#128260; 回滚机制

### 快速回滚策略

#### 1. 代码回滚

```bash
# 回滚到上一个版本
git revert HEAD
git push origin main

# 回滚到指定版本
git revert <commit-hash>
git push origin main

# 或直接切回旧版本
git checkout v2.0.0
pnpm build
pnpm deploy:production
```

#### 2. 容器回滚

```bash
# 回滚到上一个镜像
kubectl rollout undo deployment payroll

# 回滚到指定版本
kubectl rollout undo deployment payroll --to-revision=3

# 查看回滚历史
kubectl rollout history deployment payroll

# 查看当前版本
kubectl rollout status deployment payroll
```

#### 3. 数据库回滚

```bash
# 回滚最后一个迁移
pnpm db:migrate:rollback

# 回滚到指定版本
pnpm db:migrate:rollback --to=<migration-name>

# 恢复数据库备份
psql -U postgres -d payroll < backup/payroll_20240101.sql

# 恢复快照（云数据库）
# AWS RDS
aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier payroll \
  --db-snapshot-identifier payroll-snapshot-20240101

# 阿里云 RDS
rds RestoreDBInstance \
  --DBInstanceId payrolldb \
  --BackupId backupId
```

#### 4. 配置回滚

```bash
# 回滚环境变量
git checkout HEAD~1 .env.production
git push origin main

# 回滚配置文件
kubectl rollout undo configmap payroll-config
kubectl rollout undo secret payroll-secret
```

---

## &#128200; 监控和告警

### 关键指标

| 指标 | 警告阈值 | 严重阈值 |
|------|---------|---------|
| **错误率** | > 1% | > 5% |
| **响应时间 (P95)** | > 1s | > 3s |
| **CPU 使用率** | > 70% | > 90% |
| **内存使用率** | > 80% | > 95% |
| **磁盘使用率** | > 70% | > 90% |
| **数据库连接数** | > 80% | > 95% |

### 告警规则

```yaml
# Prometheus 告警规则
groups:
  - name: payroll
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
        for: 5m
        annotations:
          summary: "错误率过高"
          description: "错误率超过 5%，当前: {{ $value }}"

- alert: HighResponseTime
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 3
        for: 5m
        annotations:
          summary: "响应时间过长"
          description: "P95 响应时间超过 3s，当前: {{ $value }}s"

- alert: HighCPUUsage
        expr: cpu_usage_percent > 90
        for: 10m
        annotations:
          summary: "CPU 使用率过高"
          description: "CPU 使用率超过 90%，当前: {{ $value }}%"

- alert: HighMemoryUsage
        expr: memory_usage_percent > 95
        for: 10m
        annotations:
          summary: "内存使用率过高"
          description: "内存使用率超过 95%，当前: {{ $value }}%"
```

---

## &#127919; 最佳实践

### 1. 环境隔离最佳实践

- ✅ 每个环境使用独立的数据库
- ✅ 测试数据定期清理
- ✅ 环境变量文件不提交到 Git
- ✅ 生产环境配置专人管理
- ✅ 使用 CI/CD 自动化部署

### 2. 灰度发布最佳实践

- ✅ 从小范围开始（5%）
- ✅ 逐步扩大（5% → 10% → 20% → 50% → 100%）
- ✅ 每个阶段观察至少 24 小时
- ✅ 设置明确的回滚触发条件
- ✅ 准备详细的回滚方案

### 3. 回滚最佳实践

- ✅ 每次发布前创建快照
- ✅ 回滚脚本提前测试
- ✅ 回滚时间 < 5 分钟
- ✅ 回滚后立即通知相关人员
- ✅ 分析问题原因，制定改进措施

---

## &#128218; 参考资源

- [Istio 流量管理](https://istio.io/latest/docs/concepts/traffic-management/)
- [Kubernetes 部署策略](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
- [蓝绿部署最佳实践](https://martinfowler.com/bliki/BlueGreenDeployment.html)
- [金丝雀发布最佳实践](https://martinfowler.com/bliki/CanaryRelease.html)

---

## &#127881; 总结

通过环境隔离和灰度发布，你可以：

1. **降低风险**: 小步快跑，快速发现问题
2. **快速回滚**: 出问题立即回滚，最小化影响
3. **稳定发布**: 渐进式发布，保证系统稳定
4. **数据安全**: 环境隔离，避免数据污染

记住：**宁可慢一点，也不要出事故**。