juwan/juwan-backend
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Files
529139893baadfaefb94b2559c242f6ee547510d
juwan-backend/docs/secrets/INDEX.md
T
wwweww fdbcde13b2 add:
2026-02-23 20:36:21 +08:00

12 KiB
Raw Blame History

JWT + ETCD 加密系统文档索引

📚 文档完整导航

快速入门 (5-15分钟)

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

  1. SUMMARY.md ⭐ 从这里开始

    • 📋 项目概览和架构图
    • 🎯 核心特性一览
    • ✅ 生产就绪检查清单
    • 🚀 下一步行动计划

  2. README.md

    • 🏃 4个快速部署步骤
    • 🔐 安全考虑事项
    • 🔄 密钥轮换程序
    • 🆘 故障排查

  3. QUICK_REFERENCE.md

    • ⚡ 一页速查表
    • 📝 常见命令复制粘贴
    • 🗺️ 文档地图
    • 🎓 关键参数速知

部署实施 (30-60分钟)

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

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

  1. 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分钟

高级话题

  1. ENCRYPTION.md - ETCD 加密完整指南

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

  2. 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 - 项目概览（5分钟）
  2. SUMMARY.md 中的架构图和特性说明

关键信息：

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

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

推荐阅读顺序：

  1. README.md - 快速参考（2分钟）
  2. QUICK_REFERENCE.md - 复制粘贴命令（3分钟）
  3. 运行部署命令（5分钟）
  4. VERIFICATION.md 第1-7部分 - 验证（10分钟）

快速命令：

# 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：部署后验证一切正常

推荐阅读：

预计时间： 30-40分钟

验证触发点：

  • ✅ Secrets 和 RBAC 已创建
  • ✅ Pods 已启动运行
  • ✅ 权限验证通过
  • ✅ Redis 连接成功

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

推荐阅读顺序：

  1. ENCRYPTION.md - 完整加密指南
  2. 按照 8 个步骤逐一执行
  3. VERIFICATION.md 第9部分 - 加密验证

需要的权限：

  • Control Plane 节点的 root/sudo 权限
  • Kubernetes 集群管理员权限

预计时间： 15-20分钟

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

推荐阅读顺序：

  1. 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 第11部分
权限被拒绝 VERIFICATION.md 第2部分 + README.md 故障排查
Redis 连接失败 VERIFICATION.md 第4部分
ETCD 加密失败 ENCRYPTION.md 第5-6部分
配置不清楚 QUICK_REFERENCE.md 配置文件位置

场景 7：定期维护任务

任务：轮换 JWT 秘钥

阅读： DEPLOYMENT.md 安全最佳实践 > 密钥轮换 或： QUICK_REFERENCE.md 密钥轮换步骤

频率： 季度（3个月）

任务：轮换 ETCD 加密密钥

阅读： ENCRYPTION.md 第5部分 或： QUICK_REFERENCE.md ETCD 加密系统

频率： 年度（12个月）

任务：备份密钥

阅读： DEPLOYMENT.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 的 "故障排查" 部分

第四步：检查日志

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

或根据您的角色选择：

角色 开始文档 预计时间
DevOps/运维 DEPLOYMENT.md 1-2 小时
应用开发 INTEGRATION.md 2-3 小时
安全审查 ENCRYPTION.md 30 分钟
项目经理 SUMMARY.md 15 分钟
新手 README.md → SUMMARY.md 15-20 分钟
Reference in New Issue View Git Blame Copy Permalink