zetaloop
400 lines
12 KiB
Markdown
400 lines
12 KiB
Markdown
# 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 分钟 |
|