juwan/juwan-backend
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

normalize line endings to LF and add envoy dockerfile in deploy/dev

Browse Source
This commit is contained in:
wwweww
2026-04-06 05:26:41 +08:00
parent 7ec8b2a8f0
commit c7a33d4174
39 changed files with 12916 additions and 12246 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/secrets/FLOWCHART.md
+415 -415
View File
@@ -1,415 +1,415 @@
# 部署流程图和时间线
## 部署架构流程图
```
┌──────────────────────────────────────────────────────────────────┐
│ 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)
# 部署流程图和时间线
## 部署架构流程图
```
┌──────────────────────────────────────────────────────────────────┐
│ 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)