# 部署流程图和时间线

## 部署架构流程图

```
┌──────────────────────────────────────────────────────────────────┐
│        JWT 认证系统部署流程                                       │
└──────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│ Phase 1: 前置检查 (5分钟)                                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ✓ Kubernetes 集群版本 >= 1.24                                     │
│  ✓ kubectl 已配置，可访问集群                                       │
│  ✓ juwan namespace 已存在                                          │
│  ✓ redis-operator CRD 已安装                                       │
│  ✓ 集群管理员权限（用于 ETCD 加密）                                 │
│                                                                     │
│  命令检查:                                                          │
│  $ kubectl cluster-info                                            │
│  $ kubectl get ns juwan                                            │
│  $ kubectl get crd redisclusters.redis.redis.opstreelabs.in       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Phase 2: 创建 Secret 和 RBAC (5分钟)  ⚡ 必需                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  执行:                                                              │
│  $ kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml             │
│                                                                     │
│  创建的资源:                                                        │
│  ✓ Secret: jwt-secret (包含 JWT 秘钥)                              │
│  ✓ ServiceAccount: user-rpc                                        │
│  ✓ ServiceAccount: envoy-gateway                                   │
│  ✓ Role: jwt-secret-reader (只读权限)                              │
│  ✓ RoleBinding: jwt-secret-reader-user-rpc                         │
│  ✓ RoleBinding: jwt-secret-reader-envoy-gateway                    │
│                                                                     │
│  验证:                                                              │
│  $ kubectl get secret jwt-secret -n juwan                          │
│  $ kubectl get sa -n juwan | grep -E "user-rpc|envoy"              │
│  $ kubectl get role -n juwan                                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Phase 3: 更新 Deployments (10分钟) ⚡ 必需                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Step 3a: 更新 user-rpc Deployment                                 │
│  执行:                                                              │
│  $ kubectl apply -f deploy/k8s/service/user/user-rpc.yaml          │
│                                                                     │
│  变更:                                                              │
│  - serviceAccountName: user-rpc (绑定权限)                         │
│  - env.JWT_SECRET_KEY (从 Secret 挂载)                             │
│  - 保持 Redis Cluster 配置                                         │
│                                                                     │
│  等待 Pods 启动:                                                    │
│  $ kubectl rollout status deployment/user-rpc -n juwan             │
│                                                                     │
│  ---                                                               │
│                                                                     │
│  Step 3b: 更新 Envoy Gateway Deployment                            │
│  执行:                                                              │
│  $ kubectl apply -f deploy/k8s/envoy/envoy.yaml                    │
│                                                                     │
│  变更:                                                              │
│  - serviceAccountName: envoy-gateway (绑定权限)                    │
│  - 保持 CSRF Lua 防护配置                                          │
│                                                                     │
│  等待 Pods 启动:                                                    │
│  $ kubectl rollout status deployment/envoy-gateway -n juwan        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Phase 4: 验证部署 (15分钟) ⚡ 必需                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  检查清单:                                                          │
│                                                                     │
│  1️⃣  Secret 和权限验证                                             │
│  $ kubectl get secret jwt-secret -n juwan                          │
│  $ kubectl get role jwt-secret-reader -n juwan                     │
│  $ kubectl get rolebinding -n juwan | grep jwt-secret              │
│                                                                     │
│  2️⃣  权限测试                                                      │
│  $ kubectl auth can-i get secrets \                                │
│    --as=system:serviceaccount:juwan:user-rpc \                     │
│    --resource-name=jwt-secret -n juwan                             │
│  预期: yes                                                         │
│                                                                     │
│  3️⃣  Pods 运行状态                                                │
│  $ kubectl get pods -n juwan -l app=user-rpc                       │
│  $ kubectl get pods -n juwan -l app=envoy-gateway                  │
│  预期: 3 个 user-rpc Pods + 1 个 envoy-gateway Pod 都在 Running   │
│                                                                     │
│  4️⃣  环境变量验证                                                  │
│  $ kubectl exec -it <user-rpc-pod> -n juwan -- env | grep JWT      │
│  预期: JWT_SECRET_KEY=...                                          │
│                                                                     │
│  5️⃣  Redis 连接验证                                               │
│  $ kubectl run redis-cli --image=redis:latest --rm -it \           │
│    -- redis-cli -h user-redis.juwan:6379 PING                     │
│  预期: PONG                                                        │
│                                                                     │
│  详见: VERIFICATION.md 第1-8部分                                    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
        │
        ├─────────── 生产环境额外步骤 ──────────────┐
        │                                          │
        ▼                                          ▼
┌──────────────────────────┐   ┌─────────────────────────────────────┐
│ Phase 5a: 应用集成       │   │ Phase 5b: 启用 ETCD 加密 (30分钟)  │
│ (2-3 小时) ⚠️  推荐      │   │ ⚠️ 生产推荐，需集群管理员权限       │
├──────────────────────────┤   ├─────────────────────────────────────┤
│                          │   │                                     │
│ 实施内容:                │   │ 前提条件:                          │
│ ✓ gRPC Interceptor       │   │ ✓ Control Plane 节点访问权限       │
│ ✓ Login/Logout Handler   │   │ ✓ ETCD 备份已创建                  │
│ ✓ JWT Middleware         │   │ ✓ 加密密钥已生成                  │
│ ✓ Token Refresh Logic    │   │                                     │
│ ✓ Error Handling         │   │ 步骤:                              │
│ ✓ Unit Tests             │   │ 1. 生成 32 字节密钥                │
│                          │   │    $ head -c 32 /dev/urandom | base64
│ 参考:                     │   │                                     │
│ INTEGRATION.md           │   │ 2. 创建加密配置文件                │
│                          │   │    /etc/kubernetes/encryption-config.yaml
│ 时间估计:                │   │                                     │
│ - gRPC 拦截器: 30分钟   │   │ 3. 修改 kube-apiserver manifest    │
│ - Handlers: 60分钟       │   │    添加密钥路径和卷挂载             │
│ - Middleware: 30分钟     │   │                                     │
│ - 测试: 60分钟           │   │ 4. 重启 kube-apiserver             │
│                          │   │    kubelet 自动重启                 │
│                          │   │                                     │
│                          │   │ 5. 验证加密已启用                  │
│                          │   │    kubectl create secret generic ... │
│                          │   │    检查 ETCD 中的数据是否加密       │
│                          │   │                                     │
│                          │   │ 详见: ENCRYPTION.md (8个部分)      │
│                          │   │ 验证: VERIFICATION.md 第9部分       │
│                          │   │                                     │
└──────────────────────────┘   └─────────────────────────────────────┘
        │                                          │
        └───────────────────┬─────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────────┐
        │ Phase 6: 完成 ✅                          │
        ├──────────────────────────────────────────┤
        │                                          │
        │ 最终检查:                                │
        │ ✓ 所有 Pods 运行正常                     │
        │ ✓ RBAC 权限已验证                        │
        │ ✓ JWT 功能已集成                         │
        │ ✓ 日志和监控已配置                       │
        │ ✓ (可选) ETCD 加密已启用                 │
        │                                          │
        │ 生产推荐:                                │
        │ ✓ 启用审计日志                           │
        │ ✓ 配置密钥轮换计划（季度）              │
        │ ✓ 备份密钥到安全位置                     │
        │ ✓ 配置告警和监控                         │
        │                                          │
        └──────────────────────────────────────────┘
```

## 时间估计和路径

```
推荐部署路径
═════════════════════════════════════════════════════════════════

🚀 最快路径 (30 分钟) - 开发环境
────────────────────────────────────────────────────────────────
Phase 1: 前置检查                        ⏱️ 5 分钟
Phase 2: 创建 Secret 和 RBAC              ⏱️ 5 分钟  
Phase 3: 更新 Deployments                ⏱️ 10 分钟
Phase 4: 验证部署                        ⏱️ 10 分钟
────────────────────────────────────────────────────────────────
                                         总计: 30 分钟


📊 默认路径 (75 分钟) - 测试环境
────────────────────────────────────────────────────────────────
Phase 1-4: 如上                          ⏱️ 30 分钟
Phase 5a: 应用集成（简单版）             ⏱️ 45 分钟
────────────────────────────────────────────────────────────────
                                         总计: 75 分钟


🏆 完整路径 (3.5-4 小时) - 生产环境
────────────────────────────────────────────────────────────────
Phase 1-4: 如上                          ⏱️ 30 分钟
Phase 5a: 应用集成（完整版）             ⏱️ 2-3 小时
Phase 5b: ETCD 加密配置                  ⏱️ 30 分钟
────────────────────────────────────────────────────────────────
                                         总计: 3.5-4 小时


📚 学习路径 (6-8 小时) - 从零开始理解
────────────────────────────────────────────────────────────────
文档阅读 (SUMMARY + DEPLOYMENT + INTEGRATION)  ⏱️ 1-2 小时
完整路径部署                             ⏱️ 3.5-4 小时
验证和测试                                ⏱️ 1-2 小时
────────────────────────────────────────────────────────────────
                                         总计: 6-8 小时
```

## 并行和串行步骤

```
可以并行执行的任务
═════════════════════════════════════════════════════════════════

┌─────────────────────────────────┐
│ 应用集成 (Phase 5a)             │ ────┐
├─────────────────────────────────┤    │ 可选，独立
│ • gRPC interceptor               │    │ 进行
│ • REST middleware                │    │
│ • Handler 实现                   │    │
│ • 单元测试                       │    │
└─────────────────────────────────┘    │
                                      ├─ 与 Phase 2-4 并行
                                      │
┌─────────────────────────────────┐    │
│ ETCD 加密 (Phase 5b)            │ ────┘
├─────────────────────────────────┤    │ 需要集群管理员
│ • 生成密钥（可单独进行）         │    │ 权限，在
│ • 创建配置文件                  │    │ Control Plane
│ • 修改 kube-apiserver           │    │ 节点执行
│ • 重启 API server               │    │
└─────────────────────────────────┘────┘


必须串行执行的步骤
═════════════════════════════════════════════════════════════════

Phase 1 → Phase 2 → Phase 3 → Phase 4 → (Phase 5a + Phase 5b)
  
  ↓       ↓        ↓        ↓
前置检查  创建资源  部署应用  验证完整  可选扩展功能
  
• Phase 2 必须在 Phase 1 之后（需要 namespace）
• Phase 3 必须在 Phase 2 之后（需要 RoleBinding）
• Phase 4 必须在 Phase 3 之后（需要 Pods 启动）
• Phase 5a/5b 可在 Phase 4 完成后并行进行
```

## 关键时间点

```
事件时间线
═════════════════════════════════════════════════════════════════

T+0      Phase 1: 验证前置条件
         └─ 预计 5 分钟
         
T+5      Phase 2: kubectl apply jwt-secret.yaml
         └─ 预计 1 分钟执行，5 分钟验证
         
T+11     Phase 3a: kubectl apply user-rpc.yaml
         └─ 3 个 Pods 启动（滚动更新）
         └─ 预计 ~3 分钟（取决于镜像拉取）
         
T+14     Phase 3b: kubectl apply envoy.yaml
         └─ 1 个 Pod 启动
         └─ 预计 ~2 分钟
         
T+16     Phase 4: 执行完整验证检查
         └─ 12 个验证部分，共 ~15 分钟

T+31     ✅ 基础部署完成

T+31     (可选) Phase 5a: 应用代码集成
到       └─ 2-3 小时编码和测试
T+211    

T+31     (可选) Phase 5b: ETCD 加密
到       └─ 30 分钟配置
T+61     

T+211 或 T+61  🎉 全部完成
(取决于是否执行 Phase 5)
```

## 推荐的部署顺序

### 对于 DevOps/SRE

```
优先级顺序:

1️⃣ Phase 1-4 (核心部署)  [必需]
   └─ 时间: 30 分钟
   
2️⃣ Phase 5b (ETCD 加密)  [生产强烈推荐]
   └─ 时间: 30 分钟
   └─ 开始时间: T+16 之前 (与 Phase 4 并行)
   
3️⃣ 密钥备份和恢复计划    [重要]
   └─ 时间: 15 分钟
   └─ 参考: DEPLOYMENT.md 灾难恢复
   
4️⃣ Phase 5a 支持          [当开发完成时]
   └─ 协助开发团队集成 JWT
   └─ 参考: INTEGRATION.md
```

### 对于应用开发者

```
优先级顺序:

1️⃣ 了解系统架构           [了解背景]
   └─ 文档: SUMMARY.md
   └─ 时间: 10 分钟
   
2️⃣ Phase 5a: 代码集成     [并行进行]
   └─ 参考: INTEGRATION.md
   └─ 时间: 2-3 小时
   
3️⃣ 单元测试                [在开发中]
   └─ 参考: INTEGRATION.md 第 9 部分
   └─ 时间: 1 小时
   
4️⃣ 集成测试                [与运维协调]
   └─ 测试完整流程
   └─ 时间: 1-2 小时
```

## 回滚应急步骤

如果部署失败，可以快速回滚：

```
紧急回滚
═════════════════════════════════════════════════════════════════

如果 Phase 2 (Secret) 失败:
→ kubectl delete secret jwt-secret -n juwan
→ kubectl delete sa user-rpc envoy-gateway -n juwan
→ kubectl delete role jwt-secret-reader -n juwan
→ 修正配置后重新应用

如果 Phase 3 (Deployment) 失败:
→ kubectl rollout undo deployment/user-rpc -n juwan
→ kubectl rollout undo deployment/envoy-gateway -n juwan
→ 或删除部署并使用稳定的旧版本重新部署

如果 Phase 5b (ETCD 加密) 失败:
→ 从 kube-apiserver 清单中移除加密参数
→ 重启 kube-apiserver
→ 删除 /etc/kubernetes/encryption-config.yaml
→ 从最近的 ETCD 备份恢复（如果需要）

注意: 备份是关键！每次重大操作前都应备份。
```

## 部署检查点 (Go/No-Go)

```
关键检查点
═════════════════════════════════════════════════════════════════

✅ Checkpoint 1 (Phase 2 后)
   - Secret 已创建
   - ServiceAccounts 已创建
   - Go → 继续 Phase 3
   - No-Go → 检查 kubectl 权限

✅ Checkpoint 2 (Phase 3 后)
   - Pods 已启动 (Running)
   - No PodSchedulingFailure
   - Go → 继续 Phase 4
   - No-Go → 检查资源限制和镜像拉取

✅ Checkpoint 3 (Phase 4 权限测试)
   - user-rpc 可以读 jwt-secret
   - envoy-gateway 可以读 jwt-secret
   - 其他 SA 无法读取
   - Go → 继续 Phase 5
   - No-Go → 检查 RBAC 配置

✅ Checkpoint 4 (Phase 4 Redis 连接)
   - Redis Cluster 健康 (3/3 nodes)
   - PING 返回 PONG
   - Go → 继续应用集成
   - No-Go → 检查 Redis Pods 和网络

✅ Checkpoint 5 (Phase 5b - ETCD 加密)
   - 新创建的 Secret 在 ETCD 中已加密
   - Go → 生产就绪
   - No-Go → 检查 kube-apiserver 配置参数
```

---

## 使用这个流程图

1. **首次部署** → 从 "推荐部署路径" 选择合适的版本
2. **卡在某一步** → 查看对应的 Phase 描述和命令
3. **估算时间** → 查看 "时间估计和路径" 部分
4. **需要回滚** → 参考 "回滚应急步骤"
5. **检查进度** → 使用 "部署检查点"

详细的部署步骤见：[DEPLOYMENT.md](./DEPLOYMENT.md)
