# 部署流程图和时间线 ## 部署架构流程图 ``` ┌──────────────────────────────────────────────────────────────────┐ │ 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 -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)