zetaloop
367 lines
13 KiB
Markdown
367 lines
13 KiB
Markdown
# JWT 认证系统 + ETCD 加密 - 完整部署总结
|
||
|
||
## 项目概览
|
||
|
||
这个项目为微服务提供了一个完整的 JWT 认证系统，包括：
|
||
|
||
1. **JWT 令牌管理** - 令牌生成、验证、刷新和撤销
|
||
2. **Redis Cluster 存储** - 令牌交换缓存（30天TTL）和用户会话管理
|
||
3. **RBAC 权限控制** - 限制只有 user-rpc 和 envoy-gateway 服务可以访问 JWT 秘钥
|
||
4. **ETCD 加密** - 在 Kubernetes 集群中对所有 Secrets 进行加密
|
||
5. **网关保护** - Envoy 网关处理 CSRF 防护和请求路由
|
||
|
||
## 创建的文件清单
|
||
|
||
### 部署配置文件
|
||
|
||
#### `/deploy/k8s/secrets/`
|
||
|
||
| 文件 | 说明 | 关键内容 |
|
||
|-----|------|--------|
|
||
| `jwt-secret.yaml` | Secret + RBAC 配置 | 包含JWT秘钥、ServiceAccounts、Role、RoleBindings |
|
||
| `README.md` | 快速参考指南 | Secret 创建和 Deployment 更新说明 |
|
||
| `DEPLOYMENT.md` | 详细部署步骤 | 12个部署步骤，包括ETCD加密配置 |
|
||
| `ENCRYPTION.md` | ETCD加密完整指南 | 密钥生成、配置修改、验证流程 |
|
||
| `VERIFICATION.md` | 验证清单 | 12个部分的完整验证脚本和检查项 |
|
||
|
||
### 应用代码更新
|
||
|
||
| 文件路径 | 修改内容 |
|
||
|---------|--------|
|
||
| `/app/users/rpc/internal/utils/jwt.go` | JwtManager 实现（已存在） |
|
||
| `/app/users/rpc/internal/config/config.go` | JwtConfig 结构体（已存在） |
|
||
| `/app/users/rpc/internal/svc/serviceContext.go` | Redis Cluster + JwtManager 依赖注入（已存在） |
|
||
| `/app/users/rpc/etc/pb.yaml` | JWT 和 Redis Cluster 配置（已存在） |
|
||
| `/deploy/k8s/service/user/user-rpc.yaml` | ✅ **已更新** - 添加 serviceAccountName + JWT_SECRET_KEY 环境变量 |
|
||
| `/deploy/k8s/envoy/envoy.yaml` | ✅ **已更新** - 添加 serviceAccountName: envoy-gateway |
|
||
| `/app/users/api/INTEGRATION.md` | 🆕 **新建** - JWT 集成指南（interceptors, handlers, middleware） |
|
||
|
||
## 部署状态示意图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ Kubernetes Cluster │
|
||
├─────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||
│ │ juwan Namespace │ │
|
||
│ ├─────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ ┌────────────────────────────────────────────────────┐ │ │
|
||
│ │ │ Secret: jwt-secret │ │ │
|
||
│ │ │ ├─ secret-key: <encrypted in ETCD> │ │ │
|
||
│ │ │ └─ Protected by RBAC Role + RoleBindings │ │ │
|
||
│ │ └────────────────────────────────────────────────────┘ │ │
|
||
│ │ △ │ │
|
||
│ │ │ (mounted via serviceAccountName) │ │
|
||
│ │ │ │ │
|
||
│ │ ┌─────────────────┐ ┌──────────────────────┐ │ │
|
||
│ │ │ user-rpc │ │ envoy-gateway │ │ │
|
||
│ │ │ Deployment │ │ Deployment │ │ │
|
||
│ │ ├─────────────────┤ ├──────────────────────┤ │ │
|
||
│ │ │ SA: user-rpc │ │ SA: envoy-gateway │ │ │
|
||
│ │ │ Replicas: 3 │ │ Replicas: 1 │ │ │
|
||
│ │ │ Port: 9001(RPC) │ │ Port: 8080(HTTP) │ │ │
|
||
│ │ │ 4001(Met) │ │ │ │ │
|
||
│ │ └─────────────────┘ └──────────────────────┘ │ │
|
||
│ │ │ JWT Manager │ CSRF Filter │ │
|
||
│ │ │ (HS256 signing) │ (X-CSRF-Token) │ │
|
||
│ │ │ │ │ │
|
||
│ │ ┌──────▼──────────────────────────▼─────┐ │ │
|
||
│ │ │ user-redis (RedisCluster) │ │ │
|
||
│ │ │ 3-node cluster │ │ │
|
||
│ │ │ - Token exchange cache (30d TTL) │ │ │
|
||
│ │ │ - User session management │ │ │
|
||
│ │ └────────────────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||
│ │ Control Plane (kube-apiserver) │ │
|
||
│ │ • ETCD 加密: AES-CBC 32-byte key │ │
|
||
│ │ • Secrets 自动加密存储 │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 核心配置参数
|
||
|
||
### JWT 配置
|
||
|
||
```yaml
|
||
JWT:
|
||
SecretKey: "your-secret-jwt-key-change-this-in-production"
|
||
Issuer: "your-app-name"
|
||
# Token 有效期: 7 天
|
||
# Redis TTL: 30 天（支持令牌刷新）
|
||
```
|
||
|
||
### Redis Cluster
|
||
|
||
```yaml
|
||
RedisCluster:
|
||
ClusterSize: 3 🔴 主服务器 + 2 🔵 从服务器
|
||
Address: "user-redis.juwan:6379"
|
||
HighAvailability: 自动故障转移
|
||
```
|
||
|
||
### RBAC 权限
|
||
|
||
```yaml
|
||
Role: jwt-secret-reader
|
||
Resources: [secrets]
|
||
ResourceNames: [jwt-secret]
|
||
Verbs: [get] # 只读，无列表/创建/删除
|
||
Subjects:
|
||
- user-rpc (ServiceAccount)
|
||
- envoy-gateway (ServiceAccount)
|
||
```
|
||
|
||
## 部署流程
|
||
|
||
### 快速部署（5分钟）
|
||
|
||
```bash
|
||
# 第1步：创建 Secret 和 RBAC
|
||
kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
|
||
|
||
# 第2步：更新 Deployments
|
||
kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
|
||
kubectl apply -f deploy/k8s/envoy/envoy.yaml
|
||
|
||
# 第3步：验证
|
||
./verify-jwt-setup.sh
|
||
```
|
||
|
||
### ETCD 加密部署（需要集群管理员权限）
|
||
|
||
```bash
|
||
# 在 Control Plane 节点执行
|
||
1. 生成 32 字节密钥
|
||
2. 创建 /etc/kubernetes/encryption-config.yaml
|
||
3. 修改 /etc/kubernetes/manifests/kube-apiserver.yaml
|
||
4. 重启 kube-apiserver
|
||
5. 验证加密已启用
|
||
```
|
||
|
||
详见：`deploy/k8s/secrets/ENCRYPTION.md`
|
||
|
||
## 关键特性
|
||
|
||
### 1. JWT 令牌生命周期
|
||
|
||
```
|
||
登录 → 生成 JWT
|
||
├─ 有效期: 7 天（exp claim）
|
||
└─ 存储到 Redis: 30 天（TTL）
|
||
|
||
Token 过期（7天+）
|
||
├─ JWT 签名验证失败
|
||
└─ 检查 Redis 是否仍有数据
|
||
├─ 有 → 生成新 Token（刷新）✅
|
||
└─ 无 → 令牌已过期，需要重新登录 ❌
|
||
```
|
||
|
||
### 2. Redis 双键结构
|
||
|
||
```
|
||
jwt:user:{userId} → {token}
|
||
用途: 快速查询用户当前令牌
|
||
TTL: 30 天
|
||
|
||
jwt:token:{token} → {payload}
|
||
用途: 令牌验证和刷新
|
||
TTL: 30 天
|
||
```
|
||
|
||
### 3. CSRF 防护（Envoy 网关）
|
||
|
||
```
|
||
安全方法 (GET/HEAD/OPTIONS)
|
||
→ 自动生成 csrf_token
|
||
→ 返回 Set-Cookie: csrf_token=...
|
||
|
||
不安全方法 (POST/PUT/DELETE/PATCH)
|
||
→ 检查 Cookie csrf_token
|
||
→ 检查 X-CSRF-Token 头
|
||
→ 两者必须相等，否则 403
|
||
```
|
||
|
||
### 4. 权限隔离
|
||
|
||
```
|
||
Only user-rpc + envoy-gateway 可以:
|
||
✅ 读 jwt-secret
|
||
|
||
Other services 无法:
|
||
❌ 列出 secrets
|
||
❌ 获取 jwt-secret（RBAC 拒绝）
|
||
❌ 删除 secrets
|
||
```
|
||
|
||
### 5. ETCD 加密
|
||
|
||
```
|
||
未加密:
|
||
etcdctl get /registry/seca/...
|
||
→ secret-key: "plaintext-value"
|
||
|
||
已加密 (AES-CBC):
|
||
etcdctl get /registry/secrets/...
|
||
→ 二进制数据，无法读取
|
||
```
|
||
|
||
## 集成点
|
||
|
||
### 1. RPC Handler（需要实现）
|
||
|
||
```go
|
||
// 在 gRPC server 中注册拦截器
|
||
s := grpc.NewServer(
|
||
grpc.UnaryInterceptor(interceptor.JwtUnaryInterceptor(ctx)),
|
||
)
|
||
|
||
// 拦截器会:
|
||
// 1. 提取 Authorization 头中的 Token
|
||
// 2. 调用 JwtManager.Valid()
|
||
// 3. 如果过期，尝试 JwtManager.Renew()
|
||
// 4. 将声明注入 context
|
||
```
|
||
|
||
参考：`app/users/api/INTEGRATION.md` 第1-2章
|
||
|
||
### 2. REST Endpoint（需要实现）
|
||
|
||
```go
|
||
// 创建 JWT Middleware
|
||
protected := middleware.JwtMiddleware(svcCtx)
|
||
|
||
// 应用到受保护的路由
|
||
router.HandleFunc("GET /api/v1/users/me",
|
||
protected(user.GetUserInfoHandler(svcCtx)))
|
||
|
||
// Middleware 会验证 Authorization: Bearer {token}
|
||
```
|
||
|
||
参考：`app/users/api/INTEGRATION.md` 第3-4章
|
||
|
||
### 3. 登录/登出流程（需要实现）
|
||
|
||
```
|
||
登录:
|
||
1. 验证用户凭证（DB 查询）
|
||
2. JwtManager.New() → 生成令牌
|
||
3. 返回令牌给客户端
|
||
|
||
登出:
|
||
1. 从上下文提取 userId
|
||
2. JwtManager.Revoke() → 删除 Redis 中的令牌
|
||
3. 用户需要重新登录获取新令牌
|
||
```
|
||
|
||
参考：`app/users/api/INTEGRATION.md` 第5-6章
|
||
|
||
## 文档导航
|
||
|
||
| 场景 | 推荐阅读 |
|
||
|-----|--------|
|
||
| 第一次部署 | `README.md` → `DEPLOYMENT.md` |
|
||
| 部署遇到问题 | `VERIFICATION.md` + `DEPLOYMENT.md` 故障排查部分 |
|
||
| 代码集成 | `app/users/api/INTEGRATION.md` |
|
||
| ETCD 加密配置 | `ENCRYPTION.md` |
|
||
| ETCD 加密验证 | `VERIFICATION.md` 第9部分 |
|
||
| 安全最佳实践 | `DEPLOYMENT.md` 安全最佳实践部分 |
|
||
| 灾难恢复 | `DEPLOYMENT.md` 灾难恢复部分 |
|
||
|
||
## 生产就绪检查清单
|
||
|
||
- [ ] 所有 Pods 都在 Running 状态
|
||
- [ ] JWT Secret 已创建并正确挂载
|
||
- [ ] RBAC 权限验证通过
|
||
- [ ] Redis Cluster 健康（3/3 节点）
|
||
- [ ] ETCD 加密已启用（如需要）
|
||
- [ ] 监控和日志聚合正常工作
|
||
- [ ] 密钥轮换计划已制定
|
||
- [ ] 备份和恢复流程已文档化
|
||
- [ ] 安全审计日志已启用
|
||
- [ ] 端到端测试已通过
|
||
|
||
## 下一步行动
|
||
|
||
### 短期（本周）
|
||
|
||
1. **部署 Secret 和 RBAC**
|
||
```bash
|
||
kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
|
||
```
|
||
|
||
2. **更新 Deployments**
|
||
```bash
|
||
kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
|
||
kubectl apply -f deploy/k8s/envoy/envoy.yaml
|
||
```
|
||
|
||
3. **验证部署**
|
||
```bash
|
||
./verify-jwt-setup.sh
|
||
```
|
||
|
||
### 中期（本月）
|
||
|
||
1. **实现 JWT 集成**
|
||
- 创建 gRPC 拦截器
|
||
- 实现登录/登出端点
|
||
- 添加 JWT 中间件到 REST API
|
||
|
||
2. **端到端测试**
|
||
- 测试令牌生成和验证
|
||
- 测试令牌刷新
|
||
- 测试 CSRF 防护
|
||
|
||
### 长期（本季度）
|
||
|
||
1. **启用 ETCD 加密**
|
||
- 按照 `ENCRYPTION.md` 配置
|
||
- 验证所有 Secrets 都已加密
|
||
|
||
2. **生产部署**
|
||
- 启用审计日志
|
||
- 配置监控和告警
|
||
- 制定密钥轮换政策
|
||
|
||
## 支持
|
||
|
||
如遇到问题：
|
||
|
||
1. **检查日志**
|
||
```bash
|
||
kubectl logs -n juwan -l app=user-rpc -f
|
||
kubectl logs -n juwan -l app=envoy-gateway -f
|
||
```
|
||
|
||
2. **运行验证脚本**
|
||
```bash
|
||
chmod +x deploy/k8s/secrets/verify-jwt-setup.sh
|
||
./deploy/k8s/secrets/verify-jwt-setup.sh
|
||
```
|
||
|
||
3. **查看详细文档**
|
||
- 部署问题 → `DEPLOYMENT.md`
|
||
- 代码集成 → `INTEGRATION.md`
|
||
- ETCD 加密 → `ENCRYPTION.md`
|
||
- 诊断 → `VERIFICATION.md`
|
||
|
||
## 总结
|
||
|
||
这个系统为微服务提供了：
|
||
|
||
✅ **安全的身份验证** - JWT 令牌 + HS256 签名
|
||
✅ **灵活的令牌管理** - 7天有效期，30天可刷新
|
||
✅ **高可用性** - Redis Cluster 自动故障转移
|
||
✅ **权限隔离** - RBAC 限制密钥访问
|
||
✅ **数据加密** - ETCD 加密保护敏感信息
|
||
✅ **请求保护** - Envoy CSRF 双令牌验证
|
||
|
||
现在可以部署并集成到应用中了！
|