juwan-backend/docs/secrets/INDEX.md

# JWT + ETCD 加密系统文档索引

## 📚 文档完整导航

### 快速入门 (5-15分钟)

**推荐路径：** 从上到下顺序阅读

1. **[SUMMARY.md](./SUMMARY.md)** ⭐ 从这里开始
   - 📋 项目概览和架构图
   - 🎯 核心特性一览
   - ✅ 生产就绪检查清单
   - 🚀 下一步行动计划
   
2. **[README.md](./README.md)**
   - 🏃 4个快速部署步骤
   - 🔐 安全考虑事项
   - 🔄 密钥轮换程序
   - 🆘 故障排查

3. **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)**
   - ⚡ 一页速查表
   - 📝 常见命令复制粘贴
   - 🗺️ 文档地图
   - 🎓 关键参数速知

### 部署实施 (30-60分钟)

4. **[DEPLOYMENT.md](./DEPLOYMENT.md)** - 最详细的部署指南
   - 📦 第1步：创建 Secret 和 RBAC（必需）
   - 🔄 第2步：更新 user-rpc Deployment
   - 🌐 第3步：更新 Envoy Gateway Deployment
   - 🔐 第4步：启用 ETCD 加密（生产推荐）
   - ✔️ 第5步：验证整个系统
   - 📊 监控和日志配置
   - 🛠️ 安全最佳实践
   - 🆘 故障排查指南
   - 💾 灾难恢复流程

### 验证和监控 (20-30分钟)

5. **[VERIFICATION.md](./VERIFICATION.md)** - 完整验证清单
   
   **12个验证部分：**
   
   | 部分 | 用途 | 时间 |
   |-----|------|------|
   | 第1部分 | Secret/RBAC 基础验证 | 2分钟 |
   | 第2部分 | 权限测试（allow/deny） | 3分钟 |
   | 第3部分 | Deployment 配置检查 | 2分钟 |
   | 第4部分 | Redis 连接测试 | 2分钟 |
   | 第5部分 | 应用启动日志 | 3分钟 |
   | 第6部分 | 网络和服务发现 | 3分钟 |
   | 第7部分 | Prometheus 指标 | 3分钟 |
   | 第8部分 | Loki 日志聚合 | 2分钟 |
   | 第9部分 | ETCD 加密验证 | 5分钟 |
   | 第10部分 | JWT 功能测试 | 10分钟 |
   | 第11部分 | 故障排查诊断 | 5分钟 |
   | 第12部分 | 清理和总结 | 2分钟 |

### 高级话题

6. **[ENCRYPTION.md](./ENCRYPTION.md)** - ETCD 加密完整指南
   - 🔑 第1部分：密钥生成
   - 📋 第2部分：配置格式
   - 🔧 第3部分：kube-apiserver 修改
   - ✅第4部分：验证加密
   - ⚠️ 第5部分：关键警告（数据不可恢复）
   - 🔐 第6部分：RBAC 解释
   - 📦 第7部分：Deployment 示例
   - 🍎 第8部分：Minikube 特定说明

7. **[INTEGRATION.md](../api/INTEGRATION.md)** - 代码集成指南
   - 🔗 第1部分：gRPC Unary Interceptor
   - 🔗 第2部分：gRPC Stream Interceptor
   - 👤 第3部分：登录 Handler 实现
   - 🔐 第4部分：受保护 Handler 中的声明提取
   - 🔄 第5部分：令牌刷新端点
   - 🚪 第6部分：登出处理
   - 🛣️ 第7部分：REST Routes 配置
   - 🔎 第8部分：错误处理最佳实践
   - 🧪 第9部分：单元测试示例

---

## 📁 文件结构详解

```
deploy/k8s/
├── secrets/
│   ├── jwt-secret.yaml              ✅ Kubernetes 清单文件
│   │   ├── 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
│   │
│   ├── README.md                    📖 快速参考指南（5分钟入门）
│   ├── SUMMARY.md                   📊 系统概览（10分钟了解全貌）
│   ├── QUICK_REFERENCE.md           ⚡ 速查表（查找命令和参数）
│   ├── DEPLOYMENT.md                📦 详细部署指南（60分钟完整部署）
│   ├── ENCRYPTION.md                🔐 ETCD 加密指南（Control Plane 配置）
│   ├── VERIFICATION.md              ✅ 验证清单（部署后验证）
│   └── INDEX.md                     🗺️ 本文件（文档导航）
│
└── envoy/
│   └── envoy.yaml                   ✅ Envoy 网关配置
│       └── 已更新: serviceAccountName: envoy-gateway
│
service/user/
├── user-api.yaml                    ✅ user-api Service
├── user-rpc.yaml                    ✅ user-rpc Deployment（已更新）
│   ├── serviceAccountName: user-rpc (已更新)
│   ├── JWT_SECRET_KEY env var (已更新)
│   └── Redis Cluster configuration
└── ...

app/users/
├── api/
│   └── INTEGRATION.md               📝 REST/gRPC 集成指南
│
└── rpc/
    ├── internal/utils/jwt.go        ✅ JwtManager 实现（已存在）
    ├── internal/config/config.go    ✅ JWT 配置（已存在）
    ├── internal/svc/
    │   └── serviceContext.go        ✅ 依赖注入（已存在）
    └── etc/pb.yaml                  ✅ 运行时配置（已存在）
```

---

## 🎯 按场景查找文档

### 场景 1：我想快速了解这个系统是什么

**推荐阅读顺序：**
1. [SUMMARY.md](./SUMMARY.md) - 项目概览（5分钟）
2. [SUMMARY.md](./SUMMARY.md) 中的架构图和特性说明

**关键信息：**
- JWT 令牌系统 + Redis 存储 + RBAC 权限 + ETCD 加密
- 支持 7 天有效期、30 天可刷新
- Envoy 网关 CSRF 防护

---

### 场景 2：我想立即部署到 Kubernetes

**推荐阅读顺序：**
1. [README.md](./README.md) - 快速参考（2分钟）
2. [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) - 复制粘贴命令（3分钟）
3. 运行部署命令（5分钟）
4. [VERIFICATION.md](./VERIFICATION.md) 第1-7部分 - 验证（10分钟）

**快速命令：**
```bash
# Copy from QUICK_REFERENCE.md "部署命令" 部分
kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
kubectl apply -f deploy/k8s/envoy/envoy.yaml
```

---

### 场景 3：部署后验证一切正常

**推荐阅读：**
- [VERIFICATION.md](./VERIFICATION.md) - 12部分完整验证清单
- 逐部分执行验证命令

**预计时间：** 30-40分钟

**验证触发点：**
- ✅ Secrets 和 RBAC 已创建
- ✅ Pods 已启动运行
- ✅ 权限验证通过
- ✅ Redis 连接成功

---

### 场景 4：启用 ETCD 加密（生产推荐）

**推荐阅读顺序：**
1. [ENCRYPTION.md](./ENCRYPTION.md) - 完整加密指南
2. 按照 8 个步骤逐一执行
3. [VERIFICATION.md](./VERIFICATION.md) 第9部分 - 加密验证

**需要的权限：**
- Control Plane 节点的 root/sudo 权限
- Kubernetes 集群管理员权限

**预计时间：** 15-20分钟

---

### 场景 5：集成 JWT 到我的应用代码中

**推荐阅读顺序：**
1. [INTEGRATION.md](../api/INTEGRATION.md) 第1-2部分 - gRPC 拦截器
2. 第3-4部分 - 登录和受保护 Handlers
3. 第7-8部分 - REST API 中间件
4. 第9部分 - 单元测试

**需要实现：**
- ✅ gRPC Unary/Stream Interceptors
- ✅ 登录/登出端点
- ✅ JWT Middleware for REST
- ✅ 错误处理

**预计时间：** 2-3 小时

---

### 场景 6：部署后遇到问题

**根据错误类型选择：**

| 错误类型 | 查看文档 |
|---------|--------|
| Pod 无法启动 | [VERIFICATION.md](./VERIFICATION.md) 第11部分 |
| 权限被拒绝 | [VERIFICATION.md](./VERIFICATION.md) 第2部分 + [README.md](./README.md) 故障排查 |
| Redis 连接失败 | [VERIFICATION.md](./VERIFICATION.md) 第4部分 |
| ETCD 加密失败 | [ENCRYPTION.md](./ENCRYPTION.md) 第5-6部分 |
| 配置不清楚 | [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) 配置文件位置 |

---

### 场景 7：定期维护任务

#### 任务：轮换 JWT 秘钥

**阅读：** [DEPLOYMENT.md](./DEPLOYMENT.md) 安全最佳实践 > 密钥轮换
**或：** [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) 密钥轮换步骤

**频率：** 季度（3个月）

#### 任务：轮换 ETCD 加密密钥

**阅读：** [ENCRYPTION.md](./ENCRYPTION.md) 第5部分
**或：** [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) ETCD 加密系统

**频率：** 年度（12个月）

#### 任务：备份密钥

**阅读：** [DEPLOYMENT.md](./DEPLOYMENT.md) 灾难恢复
**或：** [ENCRYPTION.md](./ENCRYPTION.md) 关键警告

**频率：** 立即 + 每次轮换后

---

## 📊 文档深度对比

| 文档 | 深度 | 丰富度 | 代码 | 适合角色 |
|-----|------|--------|------|---------|
| README | 浅 | 概览 | - | PM/初学者 |
| SUMMARY | 浅 | 概览 | - | 决策者 |
| QUICK_REFERENCE | 中 | 速查 | 命令 | DevOps/SRE |
| DEPLOYMENT | 深 | 详细 | 示例 | DevOps/运维 |
| VERIFICATION | 深 | 详细 | 脚本 | QA/DevOps |
| ENCRYPTION | 非常深 | 极详细 | YAML | 安全/运维 |
| INTEGRATION | 非常深 | 代码级 | 完整 | 开发者 |

---

## 🔄 学习路径建议

### 对于 DevOps/SRE

1. SUMMARY.md (5 分钟)
2. DEPLOYMENT.md (30 分钟)
3. VERIFICATION.md (30 分钟)
4. ENCRYPTION.md (20 分钟)
5. 实践部署 (60 分钟)

**总计：** ~3 小时

### 对于应用开发者

1. SUMMARY.md > "集成点" 部分 (5 分钟)
2. INTEGRATION.md (60 分钟)
3. QUICK_REFERENCE.md > "JWT Manager API" (10 分钟)
4. 代码实现 (2-3 小时)
5. 单元测试 (INTEGRATION.md 第9部分)

**总计：** ~4 小时

### 对于安全/合规人员

1. SUMMARY.md (5 分钟)
2. ENCRYPTION.md (30 分钟)
3. DEPLOYMENT.md > 安全最佳实践 (15 分钟)
4. VERIFICATION.md 第9部分 (10 分钟)

**总计：** ~1 小时

### 对于项目经理

1. SUMMARY.md (5 分钟)
2. DEPLOYMENT.md > "部署状态示意图" (5 分钟)
3. DEPLOYMENT.md > "快速部署" (2 分钟)

**总计：** ~15 分钟

---

## 🎓 学习成果预期

### 完成后，您将能够：

✅ 在 Kubernetes 中部署 JWT 认证系统  
✅ 配置 RBAC 权限控制  
✅ 启用 ETCD 加密保护敏感数据  
✅ 在 Go-zero 应用中集成 JWT  
✅ 实现令牌刷新和撤销  
✅ 诊断和排查常见问题  
✅ 执行密钥轮换和灾难恢复  

---

## 🆘 求助指南

### 第一步：找到相关文档
- 浏览本索引找到相关章节
- 或用 Ctrl+F 搜索关键词

### 第二步：查看文档中的相关部分
- DEPLOYMENT.md 的相关章节
- 或 VERIFICATION.md 的故障排查部分

### 第三步：运行诊断命令
- QUICK_REFERENCE.md 的 "故障排查" 部分
- 或 VERIFICATION.md 的 "故障排查" 部分

### 第四步：检查日志
```bash
kubectl logs -n juwan -l app=user-rpc -f
kubectl logs -n juwan -l app=envoy-gateway -f
```

### 第五步：查看详细文档
如果上述步骤未能解决，查看对应的详细文档：
- 配置问题 → DEPLOYMENT.md
- 权限问题 → VERIFICATION.md 第2/11部分
- 集成问题 → INTEGRATION.md
- 加密问题 → ENCRYPTION.md

---

## 📞 文档反馈

如果您发现：
- ❌ 文档不清楚
- ❌ 命令不工作
- ❌ 信息缺失或过时
- ❌ 错别字或格式问题

请在相应的 `.md` 文件中标记，或提交更新建议。

---

## 📌 关键概念快速链接

| 概念 | 详见 |
|-----|------|
| JWT 令牌生命周期 | SUMMARY.md "关键特性" |
| Redis 双键结构 | SUMMARY.md "关键特性" |
| RBAC 权限隔离 | SUMMARY.md "关键特性" |
| CSRF 防护 | SUMMARY.md "关键特性" |
| ETCD 加密 | ENCRYPTION.md |
| 错误处理 | INTEGRATION.md 第8部分 |
| 密钥轮换 | DEPLOYMENT.md "安全最佳实践" |
| 灾难恢复 | DEPLOYMENT.md "灾难恢复" |

---

## ✨ 文档特性

✅ **模块化** - 每个文档独立，但相互链接  
✅ **分层** - 从快速概览到深度细节  
✅ **实践导向** - 包含实际命令和代码示例  
✅ **完整性** - 覆盖部署、验证、维护、故障排查  
✅ **易查找** - 目录、索引、速查表  

---

**开始阅读：** 👉 [SUMMARY.md](./SUMMARY.md)

或根据您的角色选择：

| 角色 | 开始文档 | 预计时间 |
|-----|--------|--------|
| DevOps/运维 | [DEPLOYMENT.md](./DEPLOYMENT.md) | 1-2 小时 |
| 应用开发 | [INTEGRATION.md](../api/INTEGRATION.md) | 2-3 小时 |
| 安全审查 | [ENCRYPTION.md](./ENCRYPTION.md) | 30 分钟 |
| 项目经理 | [SUMMARY.md](./SUMMARY.md) | 15 分钟 |
| 新手 | [README.md](./README.md) → [SUMMARY.md](./SUMMARY.md) | 15-20 分钟 |