normalize line endings to LF and add envoy dockerfile in deploy/dev
This commit is contained in:
wwweww
+366
-366
@@ -1,366 +1,366 @@
|
||||
# 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 双令牌验证
|
||||
|
||||
现在可以部署并集成到应用中了！
|
||||
# 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 双令牌验证
|
||||
|
||||
现在可以部署并集成到应用中了！
|
||||
|
||||
Reference in New Issue
Block a user