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

add:

Browse Source
This commit is contained in:
wwweww
2026-02-23 20:36:21 +08:00
parent 4898aecd3b
commit fdbcde13b2
52 changed files with 11263 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files
deploy/k8s/secrets/INDEX.md
+399
View File
@@ -0,0 +1,399 @@
# 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 分钟 |