add:

ENVOY_GATEWAY_GUIDE.md

@@ -0,0 +1,617 @@
+# Envoy Gateway 配置指南（带 JWT 认证）
+
+## 📋 目录
+
+1. [快速开始](#快速开始)
+2. [添加新服务](#添加新服务)
+3. [JWT 认证配置](#jwt-认证配置)
+4. [分级访问控制](#分级访问控制)
+5. [故障排查](#故障排查)
+
+---
+
+## 快速开始
+
+### 前置条件
+
+- K8s 集群正在运行（已验证 ✅）
+- Envoy Gateway Pod 处于 Running 状态
+- 所有后端服务已部署
+
+### 当前网关状态
+
+```bash
+# 查看 Envoy Pod
+kubectl get pods -n juwan -l app=envoy-gateway
+
+# 查看网关 Service
+kubectl get svc -n juwan envoy-gateway
+
+# 查看 ConfigMap
+kubectl get cm -n juwan envoy-config
+```
+
+### 访问网关
+
+```bash
+# 通过 kubectl 端口转发（本地测试）
+kubectl port-forward -n juwan svc/envoy-gateway 8080:80 &
+
+# 测试
+curl http://localhost:8080/api/users/login
+```
+
+---
+
+## 添加新服务
+
+### 场景：添加 Product 服务
+
+#### 1. 创建服务的 K8s 部署清单
+
+编辑或创建 `deploy/k8s/service/product/product-api.yaml`：
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: juwan
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: product-api-config
+  namespace: juwan
+data:
+  product-api.yaml: |
+    Name: product-api
+    Host: 0.0.0.0
+    Port: 8890
+    Database:
+      DataSource: postgres://user:pass@pg-dx:5432/juwan
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: product-api
+  namespace: juwan
+  labels:
+    app: product-api
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: product-api
+  template:
+    metadata:
+      labels:
+        app: product-api
+    spec:
+      containers:
+      - name: api
+        image: your-registry/product-api:latest
+        imagePullPolicy: IfNotPresent
+        ports:
+        - containerPort: 8890
+          name: http
+        volumeMounts:
+        - name: config
+          mountPath: /etc/product-api
+        env:
+        - name: TZ
+          value: "Asia/Shanghai"
+        resources:
+          requests:
+            cpu: 100m
+            memory: 128Mi
+          limits:
+            cpu: 500m
+            memory: 512Mi
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8890
+          initialDelaySeconds: 10
+          periodSeconds: 10
+      volumes:
+      - name: config
+        configMap:
+          name: product-api-config
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: product-api-svc
+  namespace: juwan
+spec:
+  selector:
+    app: product-api
+  ports:
+  - port: 8890
+    targetPort: 8890
+    name: http
+  type: ClusterIP
+```
+
+#### 2. 在 Envoy 网关中添加路由
+
+编辑 `deploy/k8s/envoy-gateway.yaml`，在 `route_config` 的 `routes` 部分添加：
+
+```yaml
+# ... 在现有路由下方添加：
+- match:
+    prefix: /api/products
+  route:
+    cluster: product_api_cluster
+    timeout: 30s
+```
+
+#### 3. 在 Envoy 网关中添加上游集群
+
+编辑 `deploy/k8s/envoy-gateway.yaml`，在 `clusters` 部分添加：
+
+```yaml
+- name: product_api_cluster
+  connect_timeout: 5s
+  type: STRICT_DNS
+  dns_lookup_family: V4_ONLY
+  lb_policy: ROUND_ROBIN
+  load_assignment:
+    cluster_name: product_api_cluster
+    endpoints:
+      - lb_endpoints:
+          - endpoint:
+              address:
+                socket_address:
+                  address: product-api-svc.juwan.svc.cluster.local
+                  port_value: 8890
+  health_checks:
+    - timeout: 3s
+      interval: 10s
+      unhealthy_threshold: 2
+      healthy_threshold: 2
+      http_health_check:
+        path: /health
+```
+
+#### 4. 部署到集群
+
+```bash
+# 部署 Product API
+kubectl apply -f deploy/k8s/service/product/product-api.yaml
+
+# 更新 Envoy 配置
+kubectl apply -f deploy/k8s/envoy-gateway.yaml
+
+# 重启 Envoy Pod 以加载新配置
+kubectl delete pods -n juwan -l app=envoy-gateway
+
+# 验证
+kubectl get pods -n juwan
+
+# 测试新接口
+curl http://localhost:8080/api/products
+```
+
+---
+
+## JWT 认证配置
+
+### 1. 生成 JWT 密钥并存储
+
+```bash
+# 执行设置脚本
+bash deploy/envoy/setup-jwt-auth.sh
+
+# 或手动执行
+JWT_SECRET=$(openssl rand -hex 32)
+echo "保存这个密钥: $JWT_SECRET"
+
+# 创建 K8s Secret
+kubectl create secret generic jwt-secret \
+  --from-literal=key=$JWT_SECRET \
+  -n juwan
+```
+
+### 2. 配置 Envoy JWT 认证
+
+编辑 `deploy/k8s/envoy-gateway.yaml`，更新 `http_filters` 部分：
+
+```yaml
+http_filters:
+  # JWT 认证过滤器（必须在 router 之前）
+  - name: envoy.filters.http.jwt_authn
+    typed_config:
+      "@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
+      
+      providers:
+        default:
+          issuer: "juwan"
+          audiences: "api"
+          # 使用 ConfigMap 中的 JWKS（已通过 volumeMount 挂载）
+          local_jwks:
+            filename: /etc/envoy/jwks.json
+      
+      rules:
+        # 规则1: 登录端点不需要认证
+        - match:
+            prefix: /api/users/login
+          allow_missing_or_failed: true
+        
+        # 规则2: 注册端点不需要认证
+        - match:
+            prefix: /api/users/register
+          allow_missing_or_failed: true
+        
+        # 规则3: 获取公开商品列表不需要认证
+        - match:
+            prefix: /api/products
+            case_sensitive: false
+          methods: ["GET"]  # 仅 GET 不需要认证
+          allow_missing_or_failed: true
+        
+        # 规则4: 其他所有路由需要认证
+        - match:
+            prefix: "/"
+          requires:
+            provider_name: "default"
+  
+  # 路由过滤器（在 JWT 认证之后）
+  - name: envoy.filters.http.router
+    typed_config:
+      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+```
+
+### 3. 在 Envoy Deployment 中挂载 JWKS
+
+编辑 `deploy/k8s/envoy-gateway.yaml` 的 Deployment 部分：
+
+```yaml
+spec:
+  # ... 其他配置 ...
+  template:
+    spec:
+      containers:
+      - name: envoy
+        # ... 其他配置 ...
+        volumeMounts:
+        - name: envoy-config
+          mountPath: /etc/envoy
+        - name: jwks-config      # ← 新增
+          mountPath: /etc/envoy
+      
+      volumes:
+      - name: envoy-config
+        configMap:
+          name: envoy-config
+      - name: jwks-config        # ← 新增
+        configMap:
+          name: jwks-config
+          items:
+          - key: jwks.json
+            path: jwks.json
+```
+
+### 4. 在 API 服务中生成 JWT Token
+
+在 User API 的 login 端点（`app/users/api/internal/logic/user/loginlogic.go`）：
+
+```go
+package user
+
+import (
+    "context"
+    "time"
+    "github.com/golang-jwt/jwt/v4"
+    "app/users/api/internal/svc"
+    "app/users/api/internal/types"
+)
+
+type LoginLogic struct {
+    ctx    context.Context
+    svcCtx *svc.ServiceContext
+}
+
+func (l *LoginLogic) Login(req *types.LoginReq) (*types.LoginResp, error) {
+    // TODO: 验证用户名和密码
+    
+    // 从配置中获取 JWT 密钥
+    jwtSecret := l.svcCtx.Config.JwtSecret
+    if jwtSecret == "" {
+        jwtSecret = "default-secret"  // 开发环境默认值
+    }
+    
+    // 生成 JWT Token
+    claims := jwt.MapClaims{
+        "userId":   1,  // 实际应从数据库获取
+        "username": req.Username,
+        "exp":      time.Now().Add(24 * time.Hour).Unix(),
+        "iat":      time.Now().Unix(),
+    }
+    
+    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+    tokenString, err := token.SignedString([]byte(jwtSecret))
+    if err != nil {
+        return nil, err
+    }
+    
+    return &types.LoginResp{
+        Token:   tokenString,
+        Expires: time.Now().Add(24 * time.Hour).Unix(),
+        UserId:  1,
+        Username: req.Username,
+        Email:   "user@example.com",
+    }, nil
+}
+```
+
+### 5. 在 API 配置中设置 JWT 密钥
+
+编辑 `app/users/api/etc/user-api.yaml`：
+
+```yaml
+Name: user-api
+Host: 0.0.0.0
+Port: 8888
+
+JwtSecret: "${JWT_SECRET}"  # 环境变量
+
+Database:
+  DataSource: postgres://...
+
+UserRpc:
+  Endpoints:
+    - user-rpc-svc.juwan.svc.cluster.local:50051
+```
+
+编辑 `app/users/api/internal/config/config.go`：
+
+```go
+package config
+
+import "github.com/zeromicro/go-zero/rest"
+
+type Config struct {
+    rest.RestConf
+    JwtSecret string `json:"jwtSecret"`
+}
+```
+
+在 K8s Deployment 中设置环境变量：
+
+```yaml
+spec:
+  template:
+    spec:
+      containers:
+      - name: api
+        env:
+        - name: JWT_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: jwt-secret
+              key: key
+```
+
+---
+
+## 分级访问控制
+
+### 场景1: 获取用户信息（有权限区分）
+
+如果用户查看自己的信息 → 返回完整数据  
+如果用户查看他人信息 → 返回部分数据
+
+#### 在 RPC 服务中实现
+
+编辑 `app/users/rpc/internal/logic/getUsersByIdLogic.go`：
+
+```go
+func (l *GetUsersByIdLogic) GetUsersById(ctx context.Context, in *pb.GetUsersByIdReq) (*pb.GetUsersByIdResp, error) {
+    // 获取请求者的 userId（由 API 层通过 context 传递）
+    requesterID, ok := ctx.Value("userId").(int64)
+    if !ok {
+        requesterID = 0  // 未认证用户
+    }
+    
+    targetID := in.Id
+    
+    // 查询数据库
+    user := l.svcCtx.UserModel.FindOne(ctx, targetID)
+    if user == nil {
+        return nil, status.Error(codes.NotFound, "user not found")
+    }
+    
+    resp := &pb.GetUsersByIdResp{
+        Users: &pb.Users{
+            UserId:    user.UserId,
+            Username:  user.Username,
+            CreatedAt: user.CreatedAt,
+        },
+    }
+    
+    // 权限检查：自己可以看全部，别人只能看部分
+    if requesterID == targetID {
+        resp.Users.Email = user.Email      // ✅ 自己可见
+        resp.Users.Phone = user.Phone      // ✅ 自己可见
+        resp.Users.Passwd = ""             // ❌ 密码永远不返回
+    }
+    // else: 只返回基本信息（username, userId）
+    
+    return resp, nil
+}
+```
+
+#### 在 API 层调用时传递 userId
+
+编辑 `app/users/api/internal/logic/user/getUserInfoLogic.go`：
+
+```go
+func (l *GetUserInfoLogic) GetUserInfo(req *types.GetUserInfoReq) (*types.UserInfo, error) {
+    // 从 context 获取当前认证用户
+    currentUserID, ok := l.ctx.Value("userId").(int64)
+    if !ok {
+        // 未认证 → 只能查看公开信息
+        currentUserID = 0
+    }
+    
+    // 调用 RPC，传递 userId
+    ctx := context.WithValue(l.ctx, "userId", currentUserID)
+    rpcResp, err := l.svcCtx.UserRpc.GetUsersById(ctx, &pb.GetUsersByIdReq{
+        Id: req.UserId,
+    })
+    if err != nil {
+        return nil, err
+    }
+    
+    return &types.UserInfo{
+        UserId:   rpcResp.Users.UserId,
+        Username: rpcResp.Users.Username,
+        Email:    rpcResp.Users.Email,
+        Phone:    rpcResp.Users.Phone,
+        CreateAt: rpcResp.Users.CreatedAt,
+    }, nil
+}
+```
+
+### 场景2: 修改用户信息（只能修改自己）
+
+```go
+func (l *UpdateUserInfoLogic) UpdateUserInfo(req *types.UpdateUserInfoReq) (*types.UpdateUserInfoResp, error) {
+    // 获取当前认证用户
+    currentUserID, ok := l.ctx.Value("userId").(int64)
+    if !ok {
+        return nil, errors.New("unauthorized")
+    }
+    
+    // 权限检查：只能修改自己的信息
+    if currentUserID != req.UserId {
+        return nil, errors.New("forbidden: can only update your own info")
+    }
+    
+    // 更新用户信息
+    // ...
+    
+    return &types.UpdateUserInfoResp{
+        Message: "更新成功",
+    }, nil
+}
+```
+
+---
+
+## 故障排查
+
+### 问题1: Envoy Pod 启动失败
+
+```bash
+# 查看日志
+kubectl logs -n juwan -l app=envoy-gateway --tail=100
+
+# 常见错误及解决
+# Error: "no such field"
+#   → YAML 字段名拼写错误或与 Envoy 版本不兼容
+#   → 检查 Envoy 版本并查看官方文档
+
+# Error: "unknown cluster"
+#   → envoy-gateway.yaml 中缺少 cluster 定义
+#   → 确保添加了所有需要的 cluster 部分
+
+# Error: "unknown extension type"
+#   → 使用了 Envoy 不支持的扩展类型
+#   → 检查 "@type" 字段是否正确
+```
+
+### 问题2: JWT 认证失败
+
+```bash
+# 验证 JWKS ConfigMap 是否存在
+kubectl get cm -n juwan jwks-config
+
+# 查看 JWKS 内容
+kubectl get cm jwks-config -n juwan -o jsonpath='{.data.jwks\.json}'
+
+# 验证 Envoy 能否读取 JWKS
+kubectl exec -it {envoy-pod-name} -n juwan -- ls -la /etc/envoy/
+
+# 测试没有 Token 的请求（应返回 401）
+curl -v http://localhost/api/users/1
+
+# 测试有效 Token 的请求
+TOKEN="your-jwt-token"
+curl -H "Authorization: Bearer $TOKEN" http://localhost/api/users/1
+```
+
+### 问题3: 后端服务无法访问
+
+```bash
+# 查看 Service 是否存在
+kubectl get svc -n juwan
+
+# 测试 DNS 解析
+kubectl exec -it {pod-name} -n juwan -- \
+  nslookup product-api-svc.juwan.svc.cluster.local
+
+# 查看 Pod 是否正确运行
+kubectl get pods -n juwan -l app=product-api
+
+# 查看后端服务日志
+kubectl logs -n juwan -l app=product-api --tail=50
+
+# Envoy 检查上游集群状态
+kubectl exec -it {envoy-pod-name} -n juwan -- \
+  curl localhost:9901/clusters | grep -A5 product_api_cluster
+```
+
+### 问题4: 跨域请求失败
+
+如果前端遇到 CORS 问题：
+
+```yaml
+# 在 Envoy 配置中添加 CORS 过滤器
+http_filters:
+  - name: envoy.filters.http.cors
+    typed_config:
+      "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors
+  
+  # JWT 认证过滤器（在 CORS 之后）
+  - name: envoy.filters.http.jwt_authn
+    # ...
+```
+
+---
+
+## 配置更新流程
+
+每次修改 `envoy-gateway.yaml` 后的完整更新步骤：
+
+```bash
+# 1. 验证 YAML 语法
+kubectl apply -f deploy/k8s/envoy-gateway.yaml --dry-run=client
+
+# 2. 应用配置
+kubectl apply -f deploy/k8s/envoy-gateway.yaml
+
+# 3. 监控 Pod 重启（应该自动重新加载）
+kubectl get pods -n juwan -l app=envoy-gateway -w
+
+# 4. 查看最新日志确认无错误
+kubectl logs -n juwan -l app=envoy-gateway --tail=50
+
+# 5. 测试新配置
+curl http://localhost/api/your-new-endpoint
+```
+
+---
+
+## 总结
+
+| 任务 | 文件 | 说明 |
+|-----|------|------|
+| 添加新 API | `desc/api/`, `app/*/api/` | 定义接口并实现业务逻辑 |
+| 添加新 RPC | `desc/rpc/`, `app/*/rpc/` | 内部服务通信（不通过网关） |
+| 更新网关路由 | `deploy/k8s/envoy-gateway.yaml` | 添加路由、集群、认证规则 |
+| 配置认证 | `deploy/envoy/setup-jwt-auth.sh` | 生成和管理 JWT 密钥 |
+| 部署到 K8s | `deploy/k8s/service/` | 创建服务的 Deployment 和 Service |
+
+需要更多帮助？查看 `PROJECT_GUIDE.md` 了解完整的项目架构和工作流！

app/users/api/INTEGRATION.md

@@ -0,0 +1,601 @@
+# JWT 集成指南
+
+指导如何将 JWT Manager 集成到 RPC Handlers 和业务逻辑中。
+
+## 1. gRPC Unary Interceptor 实现
+
+在 RPC 服务中添加 JWT 验证拦截器。
+
+### 创建拦截器
+
+创建文件 [app/users/rpc/internal/interceptor/jwt_interceptor.go](../../../app/users/rpc/internal/interceptor/jwt_interceptor.go)：
+
+```go
+package interceptor
+
+import (
+	"context"
+	"log"
+	
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/metadata"
+	"google.golang.org/grpc/status"
+	
+	"yourmodule/app/users/rpc/internal/svc"
+)
+
+// JwtUnaryInterceptor 验证 gRPC 请求中的 JWT 令牌
+func JwtUnaryInterceptor(svcCtx *svc.ServiceContext) grpc.UnaryServerInterceptor {
+	return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
+		// 获取请求元数据
+		md, ok := metadata.FromIncomingContext(ctx)
+		if !ok {
+			return nil, status.Error(codes.Unauthenticated, "missing metadata")
+		}
+
+		// 从 Authorization 头提取令牌
+		tokens := md.Get("authorization")
+		if len(tokens) == 0 {
+			return nil, status.Error(codes.Unauthenticated, "missing authorization header")
+		}
+
+		token := tokens[0]
+		
+		// 验证令牌
+		claims, err := svcCtx.JwtManager.Valid(ctx, token)
+		if err != nil {
+			log.Printf("Token validation failed: %v", err)
+			
+			// 尝试刷新令牌（如果过期但仍在 Redis 中）
+			newToken, refreshErr := svcCtx.JwtManager.Renew(ctx, token)
+			if refreshErr == nil && newToken != "" {
+				// 在响应头中返回新令牌
+				grpc.SetHeader(ctx, metadata.Pairs("authorization", newToken))
+				// 继续处理请求，使用原令牌的声明
+				// 注意：实际应用中需要重新验证新令牌
+				newClaims, err := svcCtx.JwtManager.Valid(ctx, newToken)
+				if err != nil {
+					return nil, status.Error(codes.Unauthenticated, "token refresh failed")
+				}
+				claims = newClaims
+			} else {
+				return nil, status.Error(codes.Unauthenticated, "invalid or expired token")
+			}
+		}
+
+		// 将声明附加到上下文，供处理器使用
+		newCtx := context.WithValue(ctx, "claims", claims)
+		
+		return handler(newCtx, req)
+	}
+}
+
+// JwtStreamInterceptor 验证流式 gRPC 请求中的 JWT 令牌
+func JwtStreamInterceptor(svcCtx *svc.ServiceContext) grpc.StreamServerInterceptor {
+	return func(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
+		md, ok := metadata.FromIncomingContext(ss.Context())
+		if !ok {
+			return status.Error(codes.Unauthenticated, "missing metadata")
+		}
+
+		tokens := md.Get("authorization")
+		if len(tokens) == 0 {
+			return status.Error(codes.Unauthenticated, "missing authorization header")
+		}
+
+		token := tokens[0]
+		claims, err := svcCtx.JwtManager.Valid(ss.Context(), token)
+		if err != nil {
+			return status.Error(codes.Unauthenticated, "invalid token")
+		}
+
+		// 创建包装流以注入上下文
+		wrappedStream := &WrappedStream{
+			ServerStream: ss,
+			ctx:          context.WithValue(ss.Context(), "claims", claims),
+		}
+
+		return handler(srv, wrappedStream)
+	}
+}
+
+// WrappedStream 包装 grpc.ServerStream 以注入新的上下文
+type WrappedStream struct {
+	grpc.ServerStream
+	ctx context.Context
+}
+
+func (w *WrappedStream) Context() context.Context {
+	return w.ctx
+}
+```
+
+### 在 Server 中注册拦截器
+
+修改 [app/users/rpc/usercenter/usercenter.go](../../../app/users/rpc/usercenter/usercenter.go)：
+
+```go
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	
+	"yourmodule/app/users/rpc/internal/config"
+	"yourmodule/app/users/rpc/internal/interceptor"
+	"yourmodule/app/users/rpc/internal/server"
+	"yourmodule/app/users/rpc/internal/svc"
+	"yourmodule/app/users/rpc/pb"
+	
+	"github.com/zeromicro/go-zero/core/conf"
+	"github.com/zeromicro/go-zero/core/logx"
+	"google.golang.org/grpc"
+)
+
+var configFile = flag.String("f", "etc/pb.yaml", "the config file")
+
+func main() {
+	flag.Parse()
+
+	var c config.Config
+	conf.MustLoad(*configFile, &c)
+	ctx := svc.NewServiceContext(c)
+
+	logx.DisableStat()
+
+	s := grpc.NewServer(
+		grpc.UnaryInterceptor(interceptor.JwtUnaryInterceptor(ctx)),
+		grpc.StreamInterceptor(interceptor.JwtStreamInterceptor(ctx)),
+	)
+	
+	pb.RegisterUsercenterServer(s, server.NewUsercenterServer(ctx))
+
+	logx.Infof("Starting gRPC server on %s:%d", c.Host, c.Port)
+	if err := s.Serve(net.Listen("tcp", "0.0.0.0:"+fmt.Sprintf("%d", c.Port))); err != nil {
+		logx.Error(err)
+	}
+}
+```
+
+## 2. 登录 Handler 实现
+
+实现 [app/users/api/internal/handler/user/loginHandler.go](../../../app/users/api/internal/handler/user/loginHandler.go)：
+
+```go
+package user
+
+import (
+	"context"
+	"log"
+	"net/http"
+	
+	"yourmodule/app/users/api/internal/logic/user"
+	"yourmodule/app/users/api/internal/svc"
+	"yourmodule/app/users/api/internal/types"
+)
+
+// LoginHandler 处理用户登录
+func LoginHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var req types.LoginRequest
+		
+		// 解析请求体...
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(w, "Invalid request", http.StatusBadRequest)
+			return
+		}
+
+		// 调用业务逻辑
+		resp, err := user.NewLoginLogic(r.Context(), svcCtx).Login(&req)
+		if err != nil {
+			log.Printf("Login failed: %v", err)
+			http.Error(w, "Login failed", http.StatusUnauthorized)
+			return
+		}
+
+		// 返回令牌
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}
+}
+```
+
+实现 [app/users/api/internal/logic/user/loginLogic.go](../../../app/users/api/internal/logic/user/loginLogic.go)：
+
+```go
+package user
+
+import (
+	"context"
+	"errors"
+	
+	"yourmodule/app/users/api/internal/svc"
+	"yourmodule/app/users/api/internal/types"
+)
+
+type LoginLogic struct {
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewLoginLogic(ctx context.Context, svcCtx *svc.ServiceContext) *LoginLogic {
+	return &LoginLogic{
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *LoginLogic) Login(req *types.LoginRequest) (*types.LoginResponse, error) {
+	// 1. 验证用户凭证（密码等）
+	user, err := l.svcCtx.UserModel.FindByEmail(l.ctx, req.Email)
+	if err != nil {
+		return nil, errors.New("user not found")
+	}
+
+	// 2. 验证密码
+	if !user.VerifyPassword(req.Password) {
+		return nil, errors.New("invalid password")
+	}
+
+	// 3. 生成 JWT 令牌
+	token, err := l.svcCtx.JwtManager.New(
+		l.ctx,
+		user.ID,
+		user.Email,
+		user.Name,
+	)
+	if err != nil {
+		return nil, errors.New("failed to generate token")
+	}
+
+	// 4. 返回令牌
+	return &types.LoginResponse{
+		Token: token,
+		User: types.User{
+			ID:    user.ID,
+			Email: user.Email,
+			Name:  user.Name,
+		},
+	}, nil
+}
+```
+
+## 3. 在 Handlers 中使用声明
+
+在 Protected Handlers 中提取并使用声明：
+
+```go
+package user
+
+import (
+	"context"
+	"log"
+	"net/http"
+	
+	"yourmodule/app/users/api/internal/svc"
+	"yourmodule/app/users/api/internal/types"
+	"github.com/golang-jwt/jwt/v4"
+)
+
+// GetUserInfoHandler 获取当前用户信息
+func GetUserInfoHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		// 从上下文提取声明（由拦截器设置）
+		claims, ok := r.Context().Value("claims").(*jwt.RegisteredClaims)
+		if !ok {
+			http.Error(w, "Unauthorized", http.StatusUnauthorized)
+			return
+		}
+
+		// 使用声明中的用户信息
+		userID := claims.Subject // 用户 ID 存储在 Subject 中
+		log.Printf("User %s requested their info", userID)
+
+		// 查询用户信息
+		user, err := svcCtx.UserModel.FindByID(r.Context(), userID)
+		if err != nil {
+			http.Error(w, "User not found", http.StatusNotFound)
+			return
+		}
+
+		// 返回用户信息
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(user)
+	}
+}
+```
+
+## 4. 令牌刷新端点
+
+实现令牌刷新端点：
+
+```go
+package user
+
+import (
+	"net/http"
+	
+	"yourmodule/app/users/api/internal/svc"
+	"yourmodule/app/users/api/internal/types"
+)
+
+// RefreshTokenHandler 刷新过期的 JWT 令牌
+func RefreshTokenHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var req types.RefreshTokenRequest
+		
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(w, "Invalid request", http.StatusBadRequest)
+			return
+		}
+
+		// 提取旧令牌
+		oldToken := req.Token
+
+		// 尝试刷新令牌
+		newToken, err := svcCtx.JwtManager.Renew(r.Context(), oldToken)
+		if err != nil {
+			http.Error(w, "Token refresh failed", http.StatusUnauthorized)
+			return
+		}
+
+		// 返回新令牌
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(types.RefreshTokenResponse{
+			Token: newToken,
+		})
+	}
+}
+```
+
+## 5. 登出处理
+
+实现登出端点以撤销令牌：
+
+```go
+package user
+
+import (
+	"net/http"
+	
+	"yourmodule/app/users/api/internal/svc"
+)
+
+// LogoutHandler 登出用户（撤销令牌）
+func LogoutHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		// 从上下文提取声明
+		claims, ok := r.Context().Value("claims").(*jwt.RegisteredClaims)
+		if !ok {
+			http.Error(w, "Unauthorized", http.StatusUnauthorized)
+			return
+		}
+
+		userID := claims.Subject
+
+		// 获取用户当前令牌
+		currentToken := r.Header.Get("Authorization")
+		
+		// 撤销令牌
+		err := svcCtx.JwtManager.Revoke(r.Context(), userID, currentToken)
+		if err != nil {
+			http.Error(w, "Logout failed", http.StatusInternalServerError)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"message": "logged out successfully"})
+	}
+}
+```
+
+## 6. 特定端点的 JWT 验证
+
+对于 REST API，在需要的 handlers 中手动验证令牌：
+
+### 在 Routes 中配置
+
+修改 [app/users/api/internal/handler/routes.go](../../../app/users/api/internal/handler/routes.go)：
+
+```go
+package handler
+
+import (
+	"net/http"
+	
+	"yourmodule/app/users/api/internal/middleware"
+	"yourmodule/app/users/api/internal/svc"
+	"yourmodule/app/users/api/internal/handler/user"
+)
+
+// RegisterRoutes 注册所有路由
+func RegisterRoutes(router *http.ServeMux, svcCtx *svc.ServiceContext) {
+	// 公开路由
+	router.HandleFunc("POST /api/v1/auth/login", user.LoginHandler(svcCtx))
+	router.HandleFunc("POST /api/v1/auth/refresh", user.RefreshTokenHandler(svcCtx))
+	
+	// 受保护的路由（需要 JWT 验证）
+	protected := middleware.JwtMiddleware(svcCtx)
+	router.HandleFunc("GET /api/v1/users/me", protected(user.GetUserInfoHandler(svcCtx)))
+	router.HandleFunc("POST /api/v1/users/logout", protected(user.LogoutHandler(svcCtx)))
+	router.HandleFunc("PUT /api/v1/users/me", protected(user.UpdateUserInfoHandler(svcCtx)))
+}
+```
+
+### 创建 JWT 中间件
+
+创建 [app/users/api/internal/middleware/jwt.go](../../../app/users/api/internal/middleware/jwt.go)：
+
+```go
+package middleware
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	
+	"yourmodule/app/users/api/internal/svc"
+)
+
+// JwtMiddleware 为 HTTP 处理器添加 JWT 验证
+func JwtMiddleware(svcCtx *svc.ServiceContext) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// 从 Authorization 头提取令牌
+			authHeader := r.Header.Get("Authorization")
+			if authHeader == "" {
+				http.Error(w, "Missing authorization header", http.StatusUnauthorized)
+				return
+			}
+
+			// 期望格式: "Bearer <token>"
+			parts := strings.SplitN(authHeader, " ", 2)
+			if len(parts) != 2 || parts[0] != "Bearer" {
+				http.Error(w, "Invalid authorization header", http.StatusUnauthorized)
+				return
+			}
+
+			token := parts[1]
+
+			// 验证令牌
+			claims, err := svcCtx.JwtManager.Valid(r.Context(), token)
+			if err != nil {
+				// 尝试刷新
+				newToken, refreshErr := svcCtx.JwtManager.Renew(r.Context(), token)
+				if refreshErr != nil {
+					http.Error(w, "Invalid or expired token", http.StatusUnauthorized)
+					return
+				}
+				
+				// 在响应头返回新令牌
+				w.Header().Set("X-New-Token", newToken)
+				
+				// 重新验证新令牌
+				claims, err = svcCtx.JwtManager.Valid(r.Context(), newToken)
+				if err != nil {
+					http.Error(w, "Token refresh failed", http.StatusUnauthorized)
+					return
+				}
+			}
+
+			// 将声明附加到上下文
+			newCtx := context.WithValue(r.Context(), "claims", claims)
+			next.ServeHTTP(w, r.WithContext(newCtx))
+		})
+	}
+}
+```
+
+## 7. 错误处理最佳实践
+
+```go
+package logic
+
+import (
+	"errors"
+	"log"
+	
+	"yourmodule/app/users/rpc/internal/utils"
+)
+
+// HandleJwtError 处理 JWT 相关错误
+func HandleJwtError(err error) error {
+	if errors.Is(err, utils.ErrTokenExpired) {
+		log.Println("Token has expired, user needs to refresh")
+		return errors.New("token expired - use refresh endpoint")
+	}
+	
+	if errors.Is(err, utils.ErrTokenInvalid) {
+		log.Println("Token is invalid or malformed")
+		return errors.New("invalid token")
+	}
+	
+	if errors.Is(err, utils.ErrTokenNotFound) {
+		log.Println("Token not found in Redis (revoked or expired)")
+		return errors.New("token revoked or expired")
+	}
+	
+	return err
+}
+```
+
+## 8. 测试 JWT 集成
+
+### 单元测试示例
+
+```go
+package interceptor
+
+import (
+	"context"
+	"testing"
+	
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/metadata"
+	"google.golang.org/grpc/status"
+)
+
+func TestJwtUnaryInterceptor_ValidToken(t *testing.T) {
+	// 1. 创建有效的令牌
+	token, err := svcCtx.JwtManager.New(context.Background(), "user123", "user@example.com", "John")
+	if err != nil {
+		t.Fatalf("Failed to create token: %v", err)
+	}
+
+	// 2. 创建包含令牌的上下文
+	md := metadata.Pairs("authorization", token)
+	ctx := metadata.NewIncomingContext(context.Background(), md)
+
+	// 3. 调用拦截器
+	_, err = JwtUnaryInterceptor(svcCtx)(ctx, nil, nil, func(ctx context.Context, req interface{}) (interface{}, error) {
+		return "success", nil
+	})
+
+	if err != nil {
+		t.Errorf("Unexpected error: %v", err)
+	}
+}
+
+func TestJwtUnaryInterceptor_ExpiredToken(t *testing.T) {
+	// 1. 创建过期的令牌或使用无效令牌
+	token := "invalid.token.here"
+
+	// 2. 创建包含令牌的上下文
+	md := metadata.Pairs("authorization", token)
+	ctx := metadata.NewIncomingContext(context.Background(), md)
+
+	// 3. 调用拦截器
+	_, err := JwtUnaryInterceptor(svcCtx)(ctx, nil, nil, func(ctx context.Context, req interface{}) (interface{}, error) {
+		return "success", nil
+	})
+
+	// 4. 验证错误
+	st, ok := status.FromError(err)
+	if !ok || st.Code() != codes.Unauthenticated {
+		t.Errorf("Expected Unauthenticated error, got: %v", err)
+	}
+}
+```
+
+## 9. 生产部署清单
+
+在将 JWT 集成部署到生产环境前：
+
+- [ ] 所有令牌端点都进行了压力测试
+- [ ] 令牌刷新逻辑已验证
+- [ ] 错误处理覆盖了所有 JWT 失败情况
+- [ ] 审计日志记录了所有认证尝试
+- [ ] 密钥轮换计划已确定
+- [ ] 监控和告警已配置
+- [ ] 灾难恢复流程已文档化
+- [ ] 所有依赖于 JWT 的服务都已更新
+
+## 相关文件
+
+- [app/users/rpc/internal/utils/jwt.go](../../../app/users/rpc/internal/utils/jwt.go) - JWT Manager 实现
+- [app/users/rpc/internal/config/config.go](../../../app/users/rpc/internal/config/config.go) - JWT 配置
+- [app/users/rpc/internal/svc/serviceContext.go](../../../app/users/rpc/internal/svc/serviceContext.go) - 依赖注入
+- [deploy/k8s/secrets/jwt-secret.yaml](./jwt-secret.yaml) - Secret 和 RBAC
+- [deploy/k8s/secrets/DEPLOYMENT.md](./DEPLOYMENT.md) - 部署指南

app/users/api/internal/logic/user/loginLogic.go

@@ -28,7 +28,6 @@ func NewLoginLogic(ctx context.Context, svcCtx *svc.ServiceContext) *LoginLogic
 }
 
 func (l *LoginLogic) Login(req *types.LoginReq) (resp *types.LoginResp, err error) {
-	// todo: add your logic here and delete this line
 
-	return
+	return &types.LoginResp{}, nil
 }

app/users/api/internal/logic/user/registerLogic.go

@@ -10,6 +10,7 @@ import (
 	"juwan-backend/app/users/api/internal/svc"
 	"juwan-backend/app/users/api/internal/types"
 	"juwan-backend/app/users/rpc/pb"
+	"juwan-backend/common/utils"
 
 	"github.com/google/uuid"
 	"github.com/zeromicro/go-zero/core/logx"
@@ -31,25 +32,44 @@ func NewRegisterLogic(ctx context.Context, svcCtx *svc.ServiceContext) *Register
 }
 
 func (l *RegisterLogic) Register(req *types.RegisterReq) (resp *types.RegisterResp, err error) {
-	// todo: add your logic here and delete this line
+	// 检查用户是否已存在
-	user, err := l.svcCtx.UserRpc.GetUserByUsername(l.ctx, &pb.GetUserByUsernameReq{
+	existingUser, err := l.svcCtx.UserRpc.GetUserByUsername(l.ctx, &pb.GetUserByUsernameReq{
 		Username: req.Username,
 	})
-	if err == nil || user != nil {
+	if err == nil && existingUser != nil {
-		return nil, errors.New("User is exisit")
+		return nil, errors.New("用户已存在")
-	}
-	id, err := uuid.NewRandom()
-	if err != nil {
-		return nil, errors.New("Register is failed")
 	}
 
-	_, err = l.svcCtx.UserRpc.AddUsers(l.ctx, &pb.AddUsersReq{
+	// 生成用户ID
-		UserId:   id.String(),
+	userId, err := uuid.NewRandom()
+	if err != nil {
+		return nil, errors.New("注册失败：无法生成用户ID")
+	}
+
+	// 加密密码
+	hashedPassword, err := utils.HashPassword(req.Password)
+	if err != nil {
+		return nil, errors.New("注册失败：密码加密失败")
+	}
+
+	// 创建新用户
+	newUser, err := l.svcCtx.UserRpc.AddUsers(l.ctx, &pb.AddUsersReq{
+		UserId:   userId.String(),
 		Username: req.Username,
-		Passwd:   req.Password,
+		Passwd:   hashedPassword,
 		Phone:    req.Phone,
 		State:    true,
 	})
+	if err != nil {
+		l.Errorf("AddUsers failed: %v", err)
+		return nil, errors.New("注册失败：创建用户失败")
+	}
 
-	return
+	// 返回响应
+	return &types.RegisterResp{
+		UserId:   int64(newUser.), // RPC 返回的可能是用户信息，这里简化处理
+		Username: req.Username,
+		Email:    req.Email,
+		Message:  "注册成功",
+	}, nil
 }

app/users/rpc/etc/pb.yaml

@@ -3,7 +3,7 @@ ListenOn: 0.0.0.0:9001
 
 Prometheus:
   Host: 0.0.0.0
-  Port: 9001
+  Port: 4001
   Path: /metrics
 
 DataSource: "${DB_URI}?sslmode=disable"
@@ -13,3 +13,7 @@ CacheConf:
     Type: cluster
     Pass: "${REDIS_PASSWORD}"
     User: "default"
+
+Jwt:
+  SecretKey: "${JWT_SECRET_KEY}"
+  Issuer: "juwan-user-rpc"

app/users/rpc/internal/config/config.go

@@ -5,8 +5,14 @@ import (
 	"github.com/zeromicro/go-zero/zrpc"
 )
 
+type JwtConfig struct {
+	SecretKey string `json:"secretKey"`
+	Issuer    string `json:"issuer"`
+}
+
 type Config struct {
 	zrpc.RpcServerConf
 	DataSource string `json:"dataSource"`
 	CacheConf  cache.CacheConf
+	Jwt        JwtConfig `json:"jwt"`
 }

app/users/rpc/internal/logic/checkPermissionLogic.go

@@ -0,0 +1,30 @@
+package logic
+
+import (
+	"context"
+
+	"juwan-backend/app/users/rpc/internal/svc"
+	"juwan-backend/app/users/rpc/pb"
+
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type CheckPermissionLogic struct {
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+	logx.Logger
+}
+
+func NewCheckPermissionLogic(ctx context.Context, svcCtx *svc.ServiceContext) *CheckPermissionLogic {
+	return &CheckPermissionLogic{
+		ctx:    ctx,
+		svcCtx: svcCtx,
+		Logger: logx.WithContext(ctx),
+	}
+}
+
+func (l *CheckPermissionLogic) CheckPermission(in *pb.CheckPermissionReq) (*pb.CheckPermissionResp, error) {
+	// todo: add your logic here and delete this line
+
+	return &pb.CheckPermissionResp{}, nil
+}

app/users/rpc/internal/logic/getUserByUsernameLogic.go

@@ -5,6 +5,7 @@ import (
 
 	"juwan-backend/app/users/rpc/internal/svc"
 	"juwan-backend/app/users/rpc/pb"
+	"juwan-backend/common/converter"
 
 	"github.com/zeromicro/go-zero/core/logx"
 )
@@ -23,8 +24,19 @@ func NewGetUserByUsernameLogic(ctx context.Context, svcCtx *svc.ServiceContext)
 	}
 }
 
-func (l *GetUserByUsernameLogic) GetUserByUsername(in *pb.GetUsersByIdReq) (*pb.GetUsersByIdResp, error) {
+func (l *GetUserByUsernameLogic) GetUserByUsername(in *pb.GetUserByUsernameReq) (*pb.GetUserByUsernameResp, error) {
 	// todo: add your logic here and delete this line
 
-	return &pb.GetUsersByIdResp{}, nil
+	user, err := l.svcCtx.UsersModel.FindOneByUsername(l.ctx, in.Username)
+	pbUsers := &pb.Users{}
+	converter.StructToStruct(user, pbUsers)
+	if err == nil || user != nil {
+		return &pb.GetUserByUsernameResp{
+			Users: pbUsers,
+		}, nil
+	}
+	if err.Error() != "not found" {
+		return nil, err
+	}
+	return &pb.GetUserByUsernameResp{}, nil
 }

app/users/rpc/internal/logic/loginLogic.go

@@ -0,0 +1,30 @@
+package logic
+
+import (
+	"context"
+
+	"juwan-backend/app/users/rpc/internal/svc"
+	"juwan-backend/app/users/rpc/pb"
+
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type LoginLogic struct {
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+	logx.Logger
+}
+
+func NewLoginLogic(ctx context.Context, svcCtx *svc.ServiceContext) *LoginLogic {
+	return &LoginLogic{
+		ctx:    ctx,
+		svcCtx: svcCtx,
+		Logger: logx.WithContext(ctx),
+	}
+}
+
+func (l *LoginLogic) Login(in *pb.LoginReq) (*pb.LoginResp, error) {
+	// todo: add your logic here and delete this line
+
+	return &pb.LoginResp{}, nil
+}

app/users/rpc/internal/logic/validateTokenLogic.go

@@ -0,0 +1,30 @@
+package logic
+
+import (
+	"context"
+
+	"juwan-backend/app/users/rpc/internal/svc"
+	"juwan-backend/app/users/rpc/pb"
+
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type ValidateTokenLogic struct {
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+	logx.Logger
+}
+
+func NewValidateTokenLogic(ctx context.Context, svcCtx *svc.ServiceContext) *ValidateTokenLogic {
+	return &ValidateTokenLogic{
+		ctx:    ctx,
+		svcCtx: svcCtx,
+		Logger: logx.WithContext(ctx),
+	}
+}
+
+func (l *ValidateTokenLogic) ValidateToken(in *pb.ValidateTokenReq) (*pb.ValidateTokenResp, error) {
+	// todo: add your logic here and delete this line
+
+	return &pb.ValidateTokenResp{}, nil
+}

app/users/rpc/internal/server/usercenterServer.go

@@ -53,3 +53,18 @@ func (s *UsercenterServer) SearchUsers(ctx context.Context, in *pb.SearchUsersRe
 	l := logic.NewSearchUsersLogic(ctx, s.svcCtx)
 	return l.SearchUsers(in)
 }
+
+func (s *UsercenterServer) Login(ctx context.Context, in *pb.LoginReq) (*pb.LoginResp, error) {
+	l := logic.NewLoginLogic(ctx, s.svcCtx)
+	return l.Login(in)
+}
+
+func (s *UsercenterServer) ValidateToken(ctx context.Context, in *pb.ValidateTokenReq) (*pb.ValidateTokenResp, error) {
+	l := logic.NewValidateTokenLogic(ctx, s.svcCtx)
+	return l.ValidateToken(in)
+}
+
+func (s *UsercenterServer) CheckPermission(ctx context.Context, in *pb.CheckPermissionReq) (*pb.CheckPermissionResp, error) {
+	l := logic.NewCheckPermissionLogic(ctx, s.svcCtx)
+	return l.CheckPermission(in)
+}

app/users/rpc/internal/svc/serviceContext.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"juwan-backend/app/users/rpc/internal/config"
 	"juwan-backend/app/users/rpc/internal/models"
+	"juwan-backend/app/users/rpc/internal/utils"
 	"time"
 
 	"github.com/redis/go-redis/v9"
@@ -15,6 +16,7 @@ type ServiceContext struct {
 	Config       config.Config
 	UsersModel   models.UsersModel
 	RedisCluster *redis.ClusterClient
+	JwtManager   *utils.JwtManager
 }
 
 func NewServiceContext(c config.Config) *ServiceContext {
@@ -39,9 +41,13 @@ func NewServiceContext(c config.Config) *ServiceContext {
 		}
 	}
 
+	// Initialize JWT Manager
+	jwtManager := utils.NewJwtManager(redisCluster, c.Jwt.SecretKey, c.Jwt.Issuer)
+
 	return &ServiceContext{
 		Config:       c,
 		UsersModel:   models.NewUsersModel(conn, c.CacheConf),
 		RedisCluster: redisCluster,
+		JwtManager:   jwtManager,
 	}
 }

app/users/rpc/internal/utils/jwks.go

@@ -0,0 +1,90 @@
+package utils
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/golang-jwt/jwt/v4"
+)
+
+// JWKS (JSON Web Key Set) 结构
+type JWKSKey struct {
+	Kty string `json:"kty"`
+	Use string `json:"use"`
+	Kid string `json:"kid"`
+	N   string `json:"n,omitempty"`
+	E   string `json:"e,omitempty"`
+	K   string `json:"k,omitempty"`      // 对称密钥
+	Alg string `json:"alg"`
+}
+
+type JWKS struct {
+	Keys []JWKSKey `json:"keys"`
+}
+
+// GenerateJWKSFromSecret 从密钥生成 JWKS（用于对称加密 HS256）
+func GenerateJWKSFromSecret(secretKey string, keyID string) *JWKS {
+	// 对于 HS256，将密钥进行 base64 编码
+	encodedSecret := base64.RawURLEncoding.EncodeToString([]byte(secretKey))
+
+	return &JWKS{
+		Keys: []JWKSKey{
+			{
+				Kty: "oct",
+				Use: "sig",
+				Kid: keyID,
+				K:   encodedSecret,
+				Alg: "HS256",
+			},
+		},
+	}
+}
+
+// GenerateJWKSEndpoint 生成可以被 Envoy 使用的 JWKS JSON
+// 此端点应在 user-rpc 中暴露，URL 为 /.well-known/jwks.json
+func GenerateJWKSEndpoint(secretKey string, keyID string) (string, error) {
+	if secretKey == "" {
+		return "", fmt.Errorf("secret key cannot be empty")
+	}
+
+	jwks := GenerateJWKSFromSecret(secretKey, keyID)
+
+	jsonData, err := json.MarshalIndent(jwks, "", "  ")
+	if err != nil {
+		return "", err
+	}
+
+	return string(jsonData), nil
+}
+
+// TokenPayload 令牌负载
+type TokenMetadata struct {
+	IssuedAt  time.Time
+	ExpiresAt time.Time
+	Subject   string // userId
+	Issuer    string
+	Audience  string
+}
+
+// ExtractTokenMetadata 从 token 中提取元数据（不验证签名）
+func ExtractTokenMetadata(tokenString string) (*TokenMetadata, error) {
+	token, _, err := new(jwt.Parser).ParseUnverified(tokenString, &Claims{})
+	if err != nil {
+		return nil, err
+	}
+
+	claims, ok := token.Claims.(*Claims)
+	if !ok {
+		return nil, fmt.Errorf("invalid token claims type")
+	}
+
+	return &TokenMetadata{
+		IssuedAt:  claims.IssuedAt.Time,
+		ExpiresAt: claims.ExpiresAt.Time,
+		Subject:   claims.UserId,
+		Issuer:    claims.Issuer,
+		Audience:  "", // 如果需要，可以增加到 Claims 中
+	}, nil
+}

app/users/rpc/internal/utils/jwt.go

@@ -1,8 +1,14 @@
 package utils
 
 import (
+	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"time"
+
+	"github.com/golang-jwt/jwt/v4"
+	"github.com/redis/go-redis/v9"
 )
 
 type TokenPayload struct {
@@ -10,11 +16,16 @@ type TokenPayload struct {
 	IsAdmin bool
 }
 
+type Claims struct {
+	TokenPayload
+	jwt.RegisteredClaims
+}
+
 const (
 	tokenCachePrefixUser  = "jwt:user:"
 	tokenCachePrefixToken = "jwt:token:"
-	tokenCacheTTL         = 60 * 24 * time.Hour
+	tokenCacheTTL         = 30 * 24 * time.Hour
-	tokenLifetime         = 5 * 24 * time.Hour
+	tokenLifetime         = 7 * 24 * time.Hour
 )
 
 var (
@@ -22,9 +33,211 @@ var (
 	errInvalidToken    = errors.New("invalid token claims")
 	errTokenNotInCache = errors.New("token not found in cache")
 	errNoRedisClient   = errors.New("redis client not configured")
+	// errExpiredToken    = errors.New("token expired")
 )
 
-func NewToken(payload TokenPayload) (string, error) {
+type JwtManager struct {
-
+	redisCluster *redis.ClusterClient
-	return "", nil
+	secretKey    string
+	issuer       string
+}
+
+func NewJwtManager(redisCluster *redis.ClusterClient, secretKey, issuer string) *JwtManager {
+	return &JwtManager{
+		redisCluster: redisCluster,
+		secretKey:    secretKey,
+		issuer:       issuer,
+	}
+}
+
+// New 生成新的 JWT token
+func (m *JwtManager) New(ctx context.Context, payload *TokenPayload) (string, error) {
+	if m.redisCluster == nil {
+		return "", errNoRedisClient
+	}
+
+	now := time.Now()
+	expiresAt := now.Add(tokenLifetime)
+
+	claims := &Claims{
+		TokenPayload: *payload,
+		RegisteredClaims: jwt.RegisteredClaims{
+			ExpiresAt: jwt.NewNumericDate(expiresAt),
+			IssuedAt:  jwt.NewNumericDate(now),
+			Issuer:    m.issuer,
+		},
+	}
+
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	tokenString, err := token.SignedString([]byte(m.secretKey))
+	if err != nil {
+		return "", err
+	}
+
+	// 存储 token 到 Redis，TTL 为 30 天
+	userKey := tokenCachePrefixUser + payload.UserId
+	tokenKey := tokenCachePrefixToken + tokenString
+
+	tokenData, _ := json.Marshal(payload)
+
+	// 同时存储两个 key：用户 -> token 和 token -> payload
+	pipe := m.redisCluster.Pipeline()
+	pipe.Set(ctx, userKey, tokenString, tokenCacheTTL)
+	pipe.Set(ctx, tokenKey, string(tokenData), tokenCacheTTL)
+	_, err = pipe.Exec(ctx)
+	if err != nil {
+		return "", err
+	}
+
+	return tokenString, nil
+}
+
+// Valid 验证 token 有效性，支持自动换票
+func (m *JwtManager) Valid(ctx context.Context, tokenString string) (*TokenPayload, error) {
+	if m.redisCluster == nil {
+		return nil, errNoRedisClient
+	}
+
+	if tokenString == "" {
+		return nil, errMissingToken
+	}
+
+	// 检查 token 是否在 Redis 中
+	tokenKey := tokenCachePrefixToken + tokenString
+	tokenData, err := m.redisCluster.Get(ctx, tokenKey).Result()
+	if err != nil && err != redis.Nil {
+		return nil, err
+	}
+
+	var payload TokenPayload
+	if err == redis.Nil {
+		return nil, errTokenNotInCache
+	}
+
+	err = json.Unmarshal([]byte(tokenData), &payload)
+	if err != nil {
+		return nil, errInvalidToken
+	}
+
+	// 解析 JWT 并验证签名和过期时间
+	token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
+		return []byte(m.secretKey), nil
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	claims, ok := token.Claims.(*Claims)
+	if !ok || !token.Valid {
+		return nil, errInvalidToken
+	}
+
+	return &claims.TokenPayload, nil
+}
+
+// Renew 换票逻辑：如果 token 过期但 Redis 中还存在，则生成新 token
+func (m *JwtManager) Renew(ctx context.Context, tokenString string) (string, error) {
+	if m.redisCluster == nil {
+		return "", errNoRedisClient
+	}
+
+	// 检查 token 是否在 Redis 中（不检查过期时间）
+	tokenKey := tokenCachePrefixToken + tokenString
+	tokenData, err := m.redisCluster.Get(ctx, tokenKey).Result()
+	if err != nil {
+		if err == redis.Nil {
+			return "", errTokenNotInCache
+		}
+		return "", err
+	}
+
+	var payload TokenPayload
+	err = json.Unmarshal([]byte(tokenData), &payload)
+	if err != nil {
+		return "", errInvalidToken
+	}
+
+	// 删除旧 token 记录
+	userKey := tokenCachePrefixUser + payload.UserId
+	m.redisCluster.Del(ctx, tokenKey, userKey)
+
+	// 生成新 token
+	return m.New(ctx, &payload)
+}
+
+// extract payload from token without validating expiration (used for auto-renewal)
+func (m *JwtManager) Extract(ctx context.Context, tokenString string) (*TokenPayload, error) {
+	token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
+		return []byte(m.secretKey), nil
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	claims, ok := token.Claims.(*Claims)
+	if !ok {
+		return nil, errInvalidToken
+	}
+
+	return &claims.TokenPayload, nil
+}
+
+// check if token exists in Redis (i.e. is valid and not revoked)
+func (m *JwtManager) Exists(ctx context.Context, tokenString string) (bool, error) {
+	if m.redisCluster == nil {
+		return false, errNoRedisClient
+	}
+
+	tokenKey := tokenCachePrefixToken + tokenString
+	exists, err := m.redisCluster.Exists(ctx, tokenKey).Result()
+	if err != nil {
+		return false, err
+	}
+
+	return exists > 0, nil
+}
+
+// extract payload from JWT claims
+func (m *JwtManager) ClaimsToPayload(claims *Claims) *TokenPayload {
+	return &claims.TokenPayload
+}
+
+// revoke token by deleting both user -> token and token -> payload keys from Redis
+func (m *JwtManager) Revoke(ctx context.Context, tokenString string) error {
+	if m.redisCluster == nil {
+		return errNoRedisClient
+	}
+
+	payload, err := m.Extract(ctx, tokenString)
+	if err != nil {
+		return err
+	}
+
+	userKey := tokenCachePrefixUser + payload.UserId
+	tokenKey := tokenCachePrefixToken + tokenString
+
+	pipe := m.redisCluster.Pipeline()
+	pipe.Del(ctx, userKey)
+	pipe.Del(ctx, tokenKey)
+	_, err = pipe.Exec(ctx)
+	return err
+}
+
+func (m *JwtManager) GetUserToken(ctx context.Context, userID string) (string, error) {
+	if m.redisCluster == nil {
+		return "", errNoRedisClient
+	}
+
+	userKey := tokenCachePrefixUser + userID
+	token, err := m.redisCluster.Get(ctx, userKey).Result()
+	if err != nil {
+		if err == redis.Nil {
+			return "", fmt.Errorf("user %s has no token", userID)
+		}
+		return "", err
+	}
+
+	return token, nil
 }

app/users/rpc/pb/users.pb.go

@@ -906,6 +906,334 @@ func (x *GetUserByUsernameResp) GetUsers() *Users {
 	return nil
 }
 
+type LoginReq struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Username      string                 `protobuf:"bytes,1,opt,name=username,proto3" json:"username,omitempty"`
+	Passwd        string                 `protobuf:"bytes,2,opt,name=passwd,proto3" json:"passwd,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *LoginReq) Reset() {
+	*x = LoginReq{}
+	mi := &file_users_proto_msgTypes[13]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *LoginReq) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*LoginReq) ProtoMessage() {}
+
+func (x *LoginReq) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[13]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use LoginReq.ProtoReflect.Descriptor instead.
+func (*LoginReq) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{13}
+}
+
+func (x *LoginReq) GetUsername() string {
+	if x != nil {
+		return x.Username
+	}
+	return ""
+}
+
+func (x *LoginReq) GetPasswd() string {
+	if x != nil {
+		return x.Passwd
+	}
+	return ""
+}
+
+type LoginResp struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Token         string                 `protobuf:"bytes,1,opt,name=token,proto3" json:"token,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *LoginResp) Reset() {
+	*x = LoginResp{}
+	mi := &file_users_proto_msgTypes[14]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *LoginResp) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*LoginResp) ProtoMessage() {}
+
+func (x *LoginResp) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[14]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use LoginResp.ProtoReflect.Descriptor instead.
+func (*LoginResp) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{14}
+}
+
+func (x *LoginResp) GetToken() string {
+	if x != nil {
+		return x.Token
+	}
+	return ""
+}
+
+type ValidateTokenReq struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Token         string                 `protobuf:"bytes,1,opt,name=token,proto3" json:"token,omitempty"`   // JWT token
+	UserId        string                 `protobuf:"bytes,2,opt,name=userId,proto3" json:"userId,omitempty"` // 用户ID
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ValidateTokenReq) Reset() {
+	*x = ValidateTokenReq{}
+	mi := &file_users_proto_msgTypes[15]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ValidateTokenReq) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ValidateTokenReq) ProtoMessage() {}
+
+func (x *ValidateTokenReq) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[15]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ValidateTokenReq.ProtoReflect.Descriptor instead.
+func (*ValidateTokenReq) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{15}
+}
+
+func (x *ValidateTokenReq) GetToken() string {
+	if x != nil {
+		return x.Token
+	}
+	return ""
+}
+
+func (x *ValidateTokenReq) GetUserId() string {
+	if x != nil {
+		return x.UserId
+	}
+	return ""
+}
+
+type ValidateTokenResp struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Valid         bool                   `protobuf:"varint,1,opt,name=valid,proto3" json:"valid,omitempty"`       // token 是否有效（不在黑名单中）
+	Message       string                 `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`    // 验证失败原因
+	UserId        string                 `protobuf:"bytes,3,opt,name=userId,proto3" json:"userId,omitempty"`      // 用户ID
+	RoleType      int64                  `protobuf:"varint,4,opt,name=roleType,proto3" json:"roleType,omitempty"` // 用户角色
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ValidateTokenResp) Reset() {
+	*x = ValidateTokenResp{}
+	mi := &file_users_proto_msgTypes[16]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ValidateTokenResp) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ValidateTokenResp) ProtoMessage() {}
+
+func (x *ValidateTokenResp) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[16]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ValidateTokenResp.ProtoReflect.Descriptor instead.
+func (*ValidateTokenResp) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{16}
+}
+
+func (x *ValidateTokenResp) GetValid() bool {
+	if x != nil {
+		return x.Valid
+	}
+	return false
+}
+
+func (x *ValidateTokenResp) GetMessage() string {
+	if x != nil {
+		return x.Message
+	}
+	return ""
+}
+
+func (x *ValidateTokenResp) GetUserId() string {
+	if x != nil {
+		return x.UserId
+	}
+	return ""
+}
+
+func (x *ValidateTokenResp) GetRoleType() int64 {
+	if x != nil {
+		return x.RoleType
+	}
+	return 0
+}
+
+type CheckPermissionReq struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	UserId        string                 `protobuf:"bytes,1,opt,name=userId,proto3" json:"userId,omitempty"`     // 用户ID
+	Resource      string                 `protobuf:"bytes,2,opt,name=resource,proto3" json:"resource,omitempty"` // 资源 ID
+	Action        string                 `protobuf:"bytes,3,opt,name=action,proto3" json:"action,omitempty"`     // 操作类型: read/write/delete
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *CheckPermissionReq) Reset() {
+	*x = CheckPermissionReq{}
+	mi := &file_users_proto_msgTypes[17]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *CheckPermissionReq) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*CheckPermissionReq) ProtoMessage() {}
+
+func (x *CheckPermissionReq) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[17]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use CheckPermissionReq.ProtoReflect.Descriptor instead.
+func (*CheckPermissionReq) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{17}
+}
+
+func (x *CheckPermissionReq) GetUserId() string {
+	if x != nil {
+		return x.UserId
+	}
+	return ""
+}
+
+func (x *CheckPermissionReq) GetResource() string {
+	if x != nil {
+		return x.Resource
+	}
+	return ""
+}
+
+func (x *CheckPermissionReq) GetAction() string {
+	if x != nil {
+		return x.Action
+	}
+	return ""
+}
+
+type CheckPermissionResp struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Allowed       bool                   `protobuf:"varint,1,opt,name=allowed,proto3" json:"allowed,omitempty"` // 是否有权限
+	Message       string                 `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`  // 拒绝原因
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *CheckPermissionResp) Reset() {
+	*x = CheckPermissionResp{}
+	mi := &file_users_proto_msgTypes[18]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *CheckPermissionResp) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*CheckPermissionResp) ProtoMessage() {}
+
+func (x *CheckPermissionResp) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[18]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use CheckPermissionResp.ProtoReflect.Descriptor instead.
+func (*CheckPermissionResp) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{18}
+}
+
+func (x *CheckPermissionResp) GetAllowed() bool {
+	if x != nil {
+		return x.Allowed
+	}
+	return false
+}
+
+func (x *CheckPermissionResp) GetMessage() string {
+	if x != nil {
+		return x.Message
+	}
+	return ""
+}
+
 var File_users_proto protoreflect.FileDescriptor
 
 const file_users_proto_rawDesc = "" +
@@ -987,7 +1315,27 @@ const file_users_proto_rawDesc = "" +
 	"\x14GetUserByUsernameReq\x12\x1a\n" +
 	"\busername\x18\x01 \x01(\tR\busername\"8\n" +
 	"\x15GetUserByUsernameResp\x12\x1f\n" +
-	"\x05users\x18\x01 \x01(\v2\t.pb.UsersR\x05users2\xdf\x02\n" +
+	"\x05users\x18\x01 \x01(\v2\t.pb.UsersR\x05users\">\n" +
+	"\bLoginReq\x12\x1a\n" +
+	"\busername\x18\x01 \x01(\tR\busername\x12\x16\n" +
+	"\x06passwd\x18\x02 \x01(\tR\x06passwd\"!\n" +
+	"\tLoginResp\x12\x14\n" +
+	"\x05token\x18\x01 \x01(\tR\x05token\"@\n" +
+	"\x10ValidateTokenReq\x12\x14\n" +
+	"\x05token\x18\x01 \x01(\tR\x05token\x12\x16\n" +
+	"\x06userId\x18\x02 \x01(\tR\x06userId\"w\n" +
+	"\x11ValidateTokenResp\x12\x14\n" +
+	"\x05valid\x18\x01 \x01(\bR\x05valid\x12\x18\n" +
+	"\amessage\x18\x02 \x01(\tR\amessage\x12\x16\n" +
+	"\x06userId\x18\x03 \x01(\tR\x06userId\x12\x1a\n" +
+	"\broleType\x18\x04 \x01(\x03R\broleType\"`\n" +
+	"\x12CheckPermissionReq\x12\x16\n" +
+	"\x06userId\x18\x01 \x01(\tR\x06userId\x12\x1a\n" +
+	"\bresource\x18\x02 \x01(\tR\bresource\x12\x16\n" +
+	"\x06action\x18\x03 \x01(\tR\x06action\"I\n" +
+	"\x13CheckPermissionResp\x12\x18\n" +
+	"\aallowed\x18\x01 \x01(\bR\aallowed\x12\x18\n" +
+	"\amessage\x18\x02 \x01(\tR\amessage2\x87\x04\n" +
 	"\n" +
 	"usercenter\x12-\n" +
 	"\bAddUsers\x12\x0f.pb.AddUsersReq\x1a\x10.pb.AddUsersResp\x126\n" +
@@ -995,7 +1343,10 @@ const file_users_proto_rawDesc = "" +
 	"\bDelUsers\x12\x0f.pb.DelUsersReq\x1a\x10.pb.DelUsersResp\x129\n" +
 	"\fGetUsersById\x12\x13.pb.GetUsersByIdReq\x1a\x14.pb.GetUsersByIdResp\x12H\n" +
 	"\x11GetUserByUsername\x12\x18.pb.GetUserByUsernameReq\x1a\x19.pb.GetUserByUsernameResp\x126\n" +
-	"\vSearchUsers\x12\x12.pb.SearchUsersReq\x1a\x13.pb.SearchUsersRespB\x06Z\x04./pbb\x06proto3"
+	"\vSearchUsers\x12\x12.pb.SearchUsersReq\x1a\x13.pb.SearchUsersResp\x12$\n" +
+	"\x05Login\x12\f.pb.LoginReq\x1a\r.pb.LoginResp\x12<\n" +
+	"\rValidateToken\x12\x14.pb.ValidateTokenReq\x1a\x15.pb.ValidateTokenResp\x12B\n" +
+	"\x0fCheckPermission\x12\x16.pb.CheckPermissionReq\x1a\x17.pb.CheckPermissionRespB\x06Z\x04./pbb\x06proto3"
 
 var (
 	file_users_proto_rawDescOnce sync.Once
@@ -1009,7 +1360,7 @@ func file_users_proto_rawDescGZIP() []byte {
 	return file_users_proto_rawDescData
 }
 
-var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
+var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 19)
 var file_users_proto_goTypes = []any{
 	(*Users)(nil),                 // 0: pb.Users
 	(*AddUsersReq)(nil),           // 1: pb.AddUsersReq
@@ -1024,6 +1375,12 @@ var file_users_proto_goTypes = []any{
 	(*SearchUsersResp)(nil),       // 10: pb.SearchUsersResp
 	(*GetUserByUsernameReq)(nil),  // 11: pb.GetUserByUsernameReq
 	(*GetUserByUsernameResp)(nil), // 12: pb.GetUserByUsernameResp
+	(*LoginReq)(nil),              // 13: pb.LoginReq
+	(*LoginResp)(nil),             // 14: pb.LoginResp
+	(*ValidateTokenReq)(nil),      // 15: pb.ValidateTokenReq
+	(*ValidateTokenResp)(nil),     // 16: pb.ValidateTokenResp
+	(*CheckPermissionReq)(nil),    // 17: pb.CheckPermissionReq
+	(*CheckPermissionResp)(nil),   // 18: pb.CheckPermissionResp
 }
 var file_users_proto_depIdxs = []int32{
 	0,  // 0: pb.GetUsersByIdResp.users:type_name -> pb.Users
@@ -1035,14 +1392,20 @@ var file_users_proto_depIdxs = []int32{
 	7,  // 6: pb.usercenter.GetUsersById:input_type -> pb.GetUsersByIdReq
 	11, // 7: pb.usercenter.GetUserByUsername:input_type -> pb.GetUserByUsernameReq
 	9,  // 8: pb.usercenter.SearchUsers:input_type -> pb.SearchUsersReq
-	2,  // 9: pb.usercenter.AddUsers:output_type -> pb.AddUsersResp
+	13, // 9: pb.usercenter.Login:input_type -> pb.LoginReq
-	4,  // 10: pb.usercenter.UpdateUsers:output_type -> pb.UpdateUsersResp
+	15, // 10: pb.usercenter.ValidateToken:input_type -> pb.ValidateTokenReq
-	6,  // 11: pb.usercenter.DelUsers:output_type -> pb.DelUsersResp
+	17, // 11: pb.usercenter.CheckPermission:input_type -> pb.CheckPermissionReq
-	8,  // 12: pb.usercenter.GetUsersById:output_type -> pb.GetUsersByIdResp
+	2,  // 12: pb.usercenter.AddUsers:output_type -> pb.AddUsersResp
-	12, // 13: pb.usercenter.GetUserByUsername:output_type -> pb.GetUserByUsernameResp
+	4,  // 13: pb.usercenter.UpdateUsers:output_type -> pb.UpdateUsersResp
-	10, // 14: pb.usercenter.SearchUsers:output_type -> pb.SearchUsersResp
+	6,  // 14: pb.usercenter.DelUsers:output_type -> pb.DelUsersResp
-	9,  // [9:15] is the sub-list for method output_type
+	8,  // 15: pb.usercenter.GetUsersById:output_type -> pb.GetUsersByIdResp
-	3,  // [3:9] is the sub-list for method input_type
+	12, // 16: pb.usercenter.GetUserByUsername:output_type -> pb.GetUserByUsernameResp
+	10, // 17: pb.usercenter.SearchUsers:output_type -> pb.SearchUsersResp
+	14, // 18: pb.usercenter.Login:output_type -> pb.LoginResp
+	16, // 19: pb.usercenter.ValidateToken:output_type -> pb.ValidateTokenResp
+	18, // 20: pb.usercenter.CheckPermission:output_type -> pb.CheckPermissionResp
+	12, // [12:21] is the sub-list for method output_type
+	3,  // [3:12] is the sub-list for method input_type
 	3,  // [3:3] is the sub-list for extension type_name
 	3,  // [3:3] is the sub-list for extension extendee
 	0,  // [0:3] is the sub-list for field type_name
@@ -1059,7 +1422,7 @@ func file_users_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_users_proto_rawDesc), len(file_users_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   13,
+			NumMessages:   19,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

app/users/rpc/pb/users_grpc.pb.go

@@ -25,6 +25,9 @@ const (
 	Usercenter_GetUsersById_FullMethodName      = "/pb.usercenter/GetUsersById"
 	Usercenter_GetUserByUsername_FullMethodName = "/pb.usercenter/GetUserByUsername"
 	Usercenter_SearchUsers_FullMethodName       = "/pb.usercenter/SearchUsers"
+	Usercenter_Login_FullMethodName             = "/pb.usercenter/Login"
+	Usercenter_ValidateToken_FullMethodName     = "/pb.usercenter/ValidateToken"
+	Usercenter_CheckPermission_FullMethodName   = "/pb.usercenter/CheckPermission"
 )
 
 // UsercenterClient is the client API for Usercenter service.
@@ -38,6 +41,9 @@ type UsercenterClient interface {
 	GetUsersById(ctx context.Context, in *GetUsersByIdReq, opts ...grpc.CallOption) (*GetUsersByIdResp, error)
 	GetUserByUsername(ctx context.Context, in *GetUserByUsernameReq, opts ...grpc.CallOption) (*GetUserByUsernameResp, error)
 	SearchUsers(ctx context.Context, in *SearchUsersReq, opts ...grpc.CallOption) (*SearchUsersResp, error)
+	Login(ctx context.Context, in *LoginReq, opts ...grpc.CallOption) (*LoginResp, error)
+	ValidateToken(ctx context.Context, in *ValidateTokenReq, opts ...grpc.CallOption) (*ValidateTokenResp, error)
+	CheckPermission(ctx context.Context, in *CheckPermissionReq, opts ...grpc.CallOption) (*CheckPermissionResp, error)
 }
 
 type usercenterClient struct {
@@ -108,6 +114,36 @@ func (c *usercenterClient) SearchUsers(ctx context.Context, in *SearchUsersReq,
 	return out, nil
 }
 
+func (c *usercenterClient) Login(ctx context.Context, in *LoginReq, opts ...grpc.CallOption) (*LoginResp, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(LoginResp)
+	err := c.cc.Invoke(ctx, Usercenter_Login_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *usercenterClient) ValidateToken(ctx context.Context, in *ValidateTokenReq, opts ...grpc.CallOption) (*ValidateTokenResp, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(ValidateTokenResp)
+	err := c.cc.Invoke(ctx, Usercenter_ValidateToken_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *usercenterClient) CheckPermission(ctx context.Context, in *CheckPermissionReq, opts ...grpc.CallOption) (*CheckPermissionResp, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(CheckPermissionResp)
+	err := c.cc.Invoke(ctx, Usercenter_CheckPermission_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // UsercenterServer is the server API for Usercenter service.
 // All implementations must embed UnimplementedUsercenterServer
 // for forward compatibility.
@@ -119,6 +155,9 @@ type UsercenterServer interface {
 	GetUsersById(context.Context, *GetUsersByIdReq) (*GetUsersByIdResp, error)
 	GetUserByUsername(context.Context, *GetUserByUsernameReq) (*GetUserByUsernameResp, error)
 	SearchUsers(context.Context, *SearchUsersReq) (*SearchUsersResp, error)
+	Login(context.Context, *LoginReq) (*LoginResp, error)
+	ValidateToken(context.Context, *ValidateTokenReq) (*ValidateTokenResp, error)
+	CheckPermission(context.Context, *CheckPermissionReq) (*CheckPermissionResp, error)
 	mustEmbedUnimplementedUsercenterServer()
 }
 
@@ -147,6 +186,15 @@ func (UnimplementedUsercenterServer) GetUserByUsername(context.Context, *GetUser
 func (UnimplementedUsercenterServer) SearchUsers(context.Context, *SearchUsersReq) (*SearchUsersResp, error) {
 	return nil, status.Errorf(codes.Unimplemented, "method SearchUsers not implemented")
 }
+func (UnimplementedUsercenterServer) Login(context.Context, *LoginReq) (*LoginResp, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Login not implemented")
+}
+func (UnimplementedUsercenterServer) ValidateToken(context.Context, *ValidateTokenReq) (*ValidateTokenResp, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ValidateToken not implemented")
+}
+func (UnimplementedUsercenterServer) CheckPermission(context.Context, *CheckPermissionReq) (*CheckPermissionResp, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method CheckPermission not implemented")
+}
 func (UnimplementedUsercenterServer) mustEmbedUnimplementedUsercenterServer() {}
 func (UnimplementedUsercenterServer) testEmbeddedByValue()                    {}
 
@@ -276,6 +324,60 @@ func _Usercenter_SearchUsers_Handler(srv interface{}, ctx context.Context, dec f
 	return interceptor(ctx, in, info, handler)
 }
 
+func _Usercenter_Login_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(LoginReq)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(UsercenterServer).Login(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: Usercenter_Login_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(UsercenterServer).Login(ctx, req.(*LoginReq))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Usercenter_ValidateToken_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ValidateTokenReq)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(UsercenterServer).ValidateToken(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: Usercenter_ValidateToken_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(UsercenterServer).ValidateToken(ctx, req.(*ValidateTokenReq))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Usercenter_CheckPermission_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(CheckPermissionReq)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(UsercenterServer).CheckPermission(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: Usercenter_CheckPermission_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(UsercenterServer).CheckPermission(ctx, req.(*CheckPermissionReq))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // Usercenter_ServiceDesc is the grpc.ServiceDesc for Usercenter service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -307,6 +409,18 @@ var Usercenter_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "SearchUsers",
 			Handler:    _Usercenter_SearchUsers_Handler,
 		},
+		{
+			MethodName: "Login",
+			Handler:    _Usercenter_Login_Handler,
+		},
+		{
+			MethodName: "ValidateToken",
+			Handler:    _Usercenter_ValidateToken_Handler,
+		},
+		{
+			MethodName: "CheckPermission",
+			Handler:    _Usercenter_CheckPermission_Handler,
+		},
 	},
 	Streams:  []grpc.StreamDesc{},
 	Metadata: "users.proto",

app/users/rpc/usercenter/usercenter.go

@@ -16,17 +16,23 @@ import (
 type (
 	AddUsersReq           = pb.AddUsersReq
 	AddUsersResp          = pb.AddUsersResp
+	CheckPermissionReq    = pb.CheckPermissionReq
+	CheckPermissionResp   = pb.CheckPermissionResp
 	DelUsersReq           = pb.DelUsersReq
 	DelUsersResp          = pb.DelUsersResp
 	GetUserByUsernameReq  = pb.GetUserByUsernameReq
 	GetUserByUsernameResp = pb.GetUserByUsernameResp
 	GetUsersByIdReq       = pb.GetUsersByIdReq
 	GetUsersByIdResp      = pb.GetUsersByIdResp
+	LoginReq              = pb.LoginReq
+	LoginResp             = pb.LoginResp
 	SearchUsersReq        = pb.SearchUsersReq
 	SearchUsersResp       = pb.SearchUsersResp
 	UpdateUsersReq        = pb.UpdateUsersReq
 	UpdateUsersResp       = pb.UpdateUsersResp
 	Users                 = pb.Users
+	ValidateTokenReq      = pb.ValidateTokenReq
+	ValidateTokenResp     = pb.ValidateTokenResp
 
 	Usercenter interface {
 		// -----------------------users-----------------------
@@ -36,6 +42,9 @@ type (
 		GetUsersById(ctx context.Context, in *GetUsersByIdReq, opts ...grpc.CallOption) (*GetUsersByIdResp, error)
 		GetUserByUsername(ctx context.Context, in *GetUserByUsernameReq, opts ...grpc.CallOption) (*GetUserByUsernameResp, error)
 		SearchUsers(ctx context.Context, in *SearchUsersReq, opts ...grpc.CallOption) (*SearchUsersResp, error)
+		Login(ctx context.Context, in *LoginReq, opts ...grpc.CallOption) (*LoginResp, error)
+		ValidateToken(ctx context.Context, in *ValidateTokenReq, opts ...grpc.CallOption) (*ValidateTokenResp, error)
+		CheckPermission(ctx context.Context, in *CheckPermissionReq, opts ...grpc.CallOption) (*CheckPermissionResp, error)
 	}
 
 	defaultUsercenter struct {
@@ -79,3 +88,18 @@ func (m *defaultUsercenter) SearchUsers(ctx context.Context, in *SearchUsersReq,
 	client := pb.NewUsercenterClient(m.cli.Conn())
 	return client.SearchUsers(ctx, in, opts...)
 }
+
+func (m *defaultUsercenter) Login(ctx context.Context, in *LoginReq, opts ...grpc.CallOption) (*LoginResp, error) {
+	client := pb.NewUsercenterClient(m.cli.Conn())
+	return client.Login(ctx, in, opts...)
+}
+
+func (m *defaultUsercenter) ValidateToken(ctx context.Context, in *ValidateTokenReq, opts ...grpc.CallOption) (*ValidateTokenResp, error) {
+	client := pb.NewUsercenterClient(m.cli.Conn())
+	return client.ValidateToken(ctx, in, opts...)
+}
+
+func (m *defaultUsercenter) CheckPermission(ctx context.Context, in *CheckPermissionReq, opts ...grpc.CallOption) (*CheckPermissionResp, error) {
+	client := pb.NewUsercenterClient(m.cli.Conn())
+	return client.CheckPermission(ctx, in, opts...)
+}

common/converter/README.md

@@ -0,0 +1,260 @@
+# Converter - 通用结构体转换工具
+
+利用 Go 反射机制，实现自动的 model 到 protobuf 结构体转换。
+
+## 功能特性
+
+✅ **自动字段映射** - 自动匹配同名字段并赋值  
+✅ **智能类型转换** - 自动处理常见类型转换  
+✅ **通用设计** - 支持任何 model 和 pb 结构体，无需手动编写  
+✅ **灵活扩展** - 支持自定义类型转换规则  
+
+## 支持的类型转换
+
+| 源类型 | 目标类型 | 说明 |
+|-------|---------|------|
+| `time.Time` | `int64` | 转换为 Unix 时间戳 |
+| `sql.NullTime` | `int64` | 有效时自动转换，无效则为 0 |
+| `sql.NullTime` | `time.Time` | 有效时自动转换，无效则为零值 |
+| `sql.NullInt64` | `int64` | 有效时自动转换，无效则为 0 |
+| `sql.NullString` | `string` | 有效时自动转换，无效则为空字符串 |
+| `sql.NullBool` | `bool` | 有效时自动转换，无效则为 false |
+| `int` | `int64` | 自动转换 |
+| `int64` | `int` | 自动转换 |
+| 相同类型 | 相同类型 | 直接复制 |
+
+## 核心函数
+
+### 1. StructToStruct - 单个结构体转换
+
+```go
+func StructToStruct(src, dst interface{}) error
+```
+
+**参数：**
+- `src` - 源结构体（可以是指针或值类型）
+- `dst` - 目标结构体（必须是指针）
+
+**示例：**
+
+```go
+import "app/common/converter"
+
+// 单个 model 转 pb
+user, _ := m.FindOne(ctx, userId)
+pbUser := &pb.Users{}
+converter.StructToStruct(user, pbUser)
+
+// 或直接点对点转换
+pbUser := &pb.Users{}
+_ = converter.StructToStruct(user, pbUser)
+```
+
+### 2. SliceToSlice - 切片转换
+
+```go
+func SliceToSlice(src interface{}, dstSliceType interface{}) (interface{}, error)
+```
+
+**参数：**
+- `src` - 源切片
+- `dstSliceType` - 目标切片类型（用于推导元素类型）
+
+**示例：**
+
+```go
+// 多个 model 转 pb
+users := []*models.Users{user1, user2, user3}
+pbUsersIface, _ := converter.SliceToSlice(users, []*pb.Users{})
+pbUsers := pbUsersIface.([]*pb.Users)
+```
+
+### 3. UserModelToPb - Users 专用转换（推荐）
+
+```go
+func UserModelToPb(user *models.Users) *pb.Users
+```
+
+简化的 Users model 转 pb 的快捷函数。
+
+**示例：**
+
+```go
+user, _ := m.FindOne(ctx, userId)
+pbUser := converter.UserModelToPb(user)
+```
+
+### 4. UserModelsToPb - Users 批量转换（推荐）
+
+```go
+func UserModelsToPb(users []*models.Users) []*pb.Users
+```
+
+简化的批量转换快捷函数。
+
+**示例：**
+
+```go
+users, _ := m.FindAll(ctx)
+pbUsers := converter.UserModelsToPb(users)
+```
+
+## 使用场景
+
+### 场景 1：在 Logic 层直接转换
+
+```go
+package logic
+
+import (
+	"context"
+	"app/common/converter"
+	"app/users/rpc/internal/models"
+	"app/users/rpc/pb"
+)
+
+type GetUserByIdLogic struct {
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func (l *GetUserByIdLogic) GetUserById(req *pb.GetUserByIdReq) (*pb.Users, error) {
+	// 查询数据库
+	user, err := l.svcCtx.UsersModel.FindOne(l.ctx, req.UserId)
+	if err != nil {
+		return nil, err
+	}
+
+	// 直接转换，无需手动赋值每个字段
+	pbUser := converter.UserModelToPb(user)
+	
+	return pbUser, nil
+}
+```
+
+### 场景 2：批量操作
+
+```go
+func (l *ListUsersLogic) ListUsers(req *pb.ListUsersReq) (*pb.ListUsersResp, error) {
+	users, err := l.svcCtx.UsersModel.FindAll(l.ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	// 批量转换
+	pbUsers := converter.UserModelsToPb(users)
+	
+	return &pb.ListUsersResp{
+		Users: pbUsers,
+	}, nil
+}
+```
+
+### 场景 3：搜索/过滤结果
+
+```go
+func (l *SearchUsersLogic) SearchUsers(req *pb.SearchReq) (*pb.SearchResp, error) {
+	// 搜索数据库
+	results, err := l.svcCtx.UsersModel.SearchByKeyword(l.ctx, req.Keyword)
+	if err != nil {
+		return nil, err
+	}
+
+	pbUsers := converter.UserModelsToPb(results)
+	
+	return &pb.SearchResp{
+		Results: pbUsers,
+	}, nil
+}
+```
+
+## 处理特殊字段
+
+### NULLable 字段
+
+当源字段是 `sql.NullTime` 或其他 `sql.Null*` 类型时，转换器会自动处理：
+
+```go
+// sql.NullTime -> int64（有效情况）
+user.DeletedAt = sql.NullTime{
+	Time: time.Now(),
+	Valid: true,
+}
+// 转换后 pb.Users.DeletedAt 会包含 Unix 时间戳
+
+// sql.NullTime -> int64（无效情况）
+user.DeletedAt = sql.NullTime{
+	Valid: false,
+}
+// 转换后 pb.Users.DeletedAt 为 0
+```
+
+### 时间戳字段
+
+数据库中的 `time.Time` 字段会自动转换为 protobuf 中的 `int64` Unix 时间戳：
+
+```go
+// Model
+type Users struct {
+	CreatedAt  time.Time    `db:"created_at"`
+	UpdatedAt  time.Time    `db:"updated_at"`
+	DeletedAt  sql.NullTime `db:"deleted_at"`
+}
+
+// Protobuf
+type Users struct {
+	CreatedAt  int64  // 自动转换为 Unix 时间戳
+	UpdatedAt  int64  // 自动转换为 Unix 时间戳
+	DeletedAt  int64  // 有效时转换，无效时为 0
+}
+```
+
+## 扩展 - 添加自定义类型转换
+
+如果需要支持新的类型转换，可以在 `generic.go` 的 `assignValue` 函数中添加：
+
+```go
+// 处理自定义类型 MyType -> int32 的转换
+if srcType == reflect.TypeOf(MyType{}) && dstType.Kind() == reflect.Int32 {
+	mt := srcField.Interface().(MyType)
+	dstField.SetInt(int64(mt.SomeIntField))
+	return nil
+}
+```
+
+## 性能考虑
+
+- 反射操作相对于直接赋值会有性能开销（通常很小）
+- 如果需要转换大量数据（>10000 条），考虑性能测试
+- 对于热点代码路径，可以写针对性的转换函数
+
+## 错误处理
+
+```go
+err := converter.StructToStruct(src, dst)
+if err != nil {
+	log.Printf("转换失败: %v", err)
+	// 处理错误
+}
+```
+
+大多数字段级别的转换错误会被忽略（自动跳过），但结构化错误（如 dst 不是指针）会返回。
+
+## 常见问题
+
+**Q: 字段名必须完全相同吗？**  
+A: 是的，转换器通过反射按字段名匹配。如果 model 字段名是 `UserId`，pb 字段也必须是 `UserId`。
+
+**Q: 如果某个字段转换失败怎么办？**  
+A: 单个字段的转换失败会被忽略，继续处理其他字段。确保其他字段正确设置。
+
+**Q: 能否自定义字段映射规则（比如 `db_name` -> `pbName`）？**  
+A: 当前不支持。如果需要，应该在 protobuf 定义中使用与 model 相同的字段名。
+
+**Q: 转换速度快吗？**  
+A: 反射会有性能开销，但对于大多数应用场景是可接受的。如果有极端性能要求，可以手写转换函数。
+
+## 相关文件
+
+- `generic.go` - 通用转换函数核心实现
+- `user_converter.go` - Users model 专用转换函数（示例）

common/converter/generic.go

@@ -0,0 +1,207 @@
+package converter
+
+import (
+	"database/sql"
+	"reflect"
+	"time"
+)
+
+// StructToStruct 通用结构体转换函数，利用反射将源结构体的字段值复制到目标结构体
+// src: 源结构体（通常是 model）
+// dst: 目标结构体（通常是 pb），必须是指针
+// 支持的自动转换：
+//   - time.Time -> int64 (Unix 时间戳)
+//   - sql.NullTime -> int64 (如果有效)
+//   - sql.NullInt64 -> int64
+//   - sql.NullString -> string
+//   - 相同名称和兼容类型的字段
+func StructToStruct(src, dst interface{}) error {
+	if src == nil {
+		return nil
+	}
+
+	srcVal := reflect.ValueOf(src)
+	dstVal := reflect.ValueOf(dst)
+
+	// 确保 dst 是指针
+	if dstVal.Kind() != reflect.Ptr {
+		return newError("destination must be a pointer")
+	}
+
+	dstVal = dstVal.Elem()
+
+	// 如果 src 是指针，解引用
+	if srcVal.Kind() == reflect.Ptr {
+		srcVal = srcVal.Elem()
+	}
+
+	// 都必须是结构体
+	if srcVal.Kind() != reflect.Struct || dstVal.Kind() != reflect.Struct {
+		return newError("both source and destination must be structs")
+	}
+
+	srcType := srcVal.Type()
+
+	// 遍历源结构体的所有字段
+	for i := 0; i < srcVal.NumField(); i++ {
+		srcField := srcVal.Field(i)
+		srcFieldName := srcType.Field(i).Name
+
+		// 在目标结构体中查找同名字段
+		dstField := dstVal.FieldByName(srcFieldName)
+		if !dstField.IsValid() || !dstField.CanSet() {
+			continue
+		}
+
+		// 进行类型转换和赋值
+		if err := assignValue(srcField, dstField); err != nil {
+			continue // 如果单个字段转换失败，继续处理其他字段
+		}
+	}
+
+	return nil
+}
+
+// assignValue 尝试将源字段值赋给目标字段
+func assignValue(srcField, dstField reflect.Value) error {
+	// 如果是可直接赋值的类型
+	if srcField.Type() == dstField.Type() {
+		dstField.Set(srcField)
+		return nil
+	}
+
+	srcType := srcField.Type()
+	dstType := dstField.Type()
+
+	// 处理 time.Time -> int64 的转换
+	if srcType == reflect.TypeOf(time.Time{}) && dstType.Kind() == reflect.Int64 {
+		t := srcField.Interface().(time.Time)
+		dstField.SetInt(t.Unix())
+		return nil
+	}
+
+	// 处理 sql.NullTime -> int64 的转换
+	if srcType == reflect.TypeOf(sql.NullTime{}) && dstType.Kind() == reflect.Int64 {
+		nt := srcField.Interface().(sql.NullTime)
+		if nt.Valid {
+			dstField.SetInt(nt.Time.Unix())
+		}
+		return nil
+	}
+
+	// 处理 sql.NullTime -> time.Time 的转换
+	if srcType == reflect.TypeOf(sql.NullTime{}) && dstType == reflect.TypeOf(time.Time{}) {
+		nt := srcField.Interface().(sql.NullTime)
+		if nt.Valid {
+			dstField.Set(reflect.ValueOf(nt.Time))
+		}
+		return nil
+	}
+
+	// 处理 sql.NullInt64 -> int64 的转换
+	if srcType == reflect.TypeOf(sql.NullInt64{}) && dstType.Kind() == reflect.Int64 {
+		ni := srcField.Interface().(sql.NullInt64)
+		if ni.Valid {
+			dstField.SetInt(ni.Int64)
+		}
+		return nil
+	}
+
+	// 处理 sql.NullString -> string 的转换
+	if srcType == reflect.TypeOf(sql.NullString{}) && dstType.Kind() == reflect.String {
+		ns := srcField.Interface().(sql.NullString)
+		if ns.Valid {
+			dstField.SetString(ns.String)
+		}
+		return nil
+	}
+
+	// 处理 sql.NullBool -> bool 的转换
+	if srcType == reflect.TypeOf(sql.NullBool{}) && dstType.Kind() == reflect.Bool {
+		nb := srcField.Interface().(sql.NullBool)
+		if nb.Valid {
+			dstField.SetBool(nb.Bool)
+		}
+		return nil
+	}
+
+	// 处理 int -> int64 的转换
+	if srcType.Kind() == reflect.Int && dstType.Kind() == reflect.Int64 {
+		dstField.SetInt(int64(srcField.Int()))
+		return nil
+	}
+
+	// 处理 int64 -> int 的转换
+	if srcType.Kind() == reflect.Int64 && dstType.Kind() == reflect.Int {
+		dstField.SetInt(srcField.Int())
+		return nil
+	}
+
+	// 处理 string -> string（某些情况下可能存在复制）
+	if srcType.Kind() == reflect.String && dstType.Kind() == reflect.String {
+		dstField.SetString(srcField.String())
+		return nil
+	}
+
+	// 处理 bool -> bool
+	if srcType.Kind() == reflect.Bool && dstType.Kind() == reflect.Bool {
+		dstField.SetBool(srcField.Bool())
+		return nil
+	}
+
+	return newError("unsupported type conversion from " + srcType.String() + " to " + dstType.String())
+}
+
+// SliceToSlice 通用切片转换函数，使用 StructToStruct 转换每个元素
+func SliceToSlice(src interface{}, dstSliceType interface{}) (interface{}, error) {
+	srcVal := reflect.ValueOf(src)
+
+	// src 必须是切片
+	if srcVal.Kind() != reflect.Slice {
+		return nil, newError("source must be a slice")
+	}
+
+	// 获取原始 dst slice type
+	dstSliceVal := reflect.ValueOf(dstSliceType)
+	if dstSliceVal.Kind() != reflect.Slice {
+		return nil, newError("dstSliceType must be a slice type")
+	}
+
+	dstSliceElemType := dstSliceVal.Type().Elem()
+
+	// 创建新的目标切片
+	dstSlice := reflect.MakeSlice(dstSliceVal.Type(), srcVal.Len(), srcVal.Len())
+
+	// 逐个转换元素
+	for i := 0; i < srcVal.Len(); i++ {
+		srcElem := srcVal.Index(i)
+		dstElem := reflect.New(dstSliceElemType)
+
+		// 如果 src 元素是指针，需要解引用
+		if srcElem.Kind() == reflect.Ptr {
+			srcElem = srcElem.Elem()
+		}
+
+		// 转换单个元素
+		dstElemIface := dstElem.Interface()
+		if err := StructToStruct(srcElem.Interface(), dstElemIface); err != nil {
+			return nil, err
+		}
+
+		dstSlice.Index(i).Set(dstElem.Elem())
+	}
+
+	return dstSlice.Interface(), nil
+}
+
+type Error struct {
+	msg string
+}
+
+func (e *Error) Error() string {
+	return e.msg
+}
+
+func newError(msg string) error {
+	return &Error{msg: msg}
+}

common/converter/user_converter.go

@@ -0,0 +1,29 @@
+package converter
+
+import (
+	"app/users/rpc/internal/models"
+	"app/users/rpc/pb"
+)
+
+// UserModelToPb 将 Users Model 转换为 protobuf Users
+// 使用通用转换函数，自动处理所有字段
+func UserModelToPb(user *models.Users) *pb.Users {
+	if user == nil {
+		return nil
+	}
+
+	pbUser := &pb.Users{}
+	_ = StructToStruct(user, pbUser)
+	return pbUser
+}
+
+// UserModelsToPb 将多个 Users Model 转换为 protobuf Users
+// 使用通用转换函数，自动处理所有元素
+func UserModelsToPb(users []*models.Users) []*pb.Users {
+	if len(users) == 0 {
+		return []*pb.Users{}
+	}
+
+	result, _ := SliceToSlice(users, []*pb.Users{})
+	return result.([]*pb.Users)
+}

common/utils/password.go

@@ -0,0 +1,25 @@
+package utils
+
+import (
+	"golang.org/x/crypto/bcrypt"
+)
+
+const (
+	// bcrypt 密钥成本
+	bcryptCost = bcrypt.DefaultCost
+)
+
+// HashPassword 对密码进行哈希加密
+func HashPassword(password string) (string, error) {
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcryptCost)
+	if err != nil {
+		return "", err
+	}
+	return string(hash), nil
+}
+
+// VerifyPassword 验证密码是否正确
+func VerifyPassword(hashedPassword, password string) bool {
+	err := bcrypt.CompareHashAndPassword([]byte(hashedPassword), []byte(password))
+	return err == nil
+}

deploy/certs/tls.crt

@@ -0,0 +1,30 @@
+-----BEGIN CERTIFICATE-----
+MIIFFTCCAv2gAwIBAgIUXj+1vyqKDhTsubwSmcHY61+YvmQwDQYJKoZIhvcNAQEL
+BQAwGjEYMBYGA1UEAwwPYXBpLmp1d2FuLmxvY2FsMB4XDTI2MDIyMzExNTYxNloX
+DTI3MDIyMzExNTYxNlowGjEYMBYGA1UEAwwPYXBpLmp1d2FuLmxvY2FsMIICIjAN
+BgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAkn7Jw5f0awGFbGL3ZHEPJanZO9Yk
+JDUklLF3kABiXqawSFpM6pXfKMa4VHE6/MfpREQeX2lkvtBseOf/vhC4DLACui8g
+yslUObv77xGSXmIwjFcXZzLPQ/gEs2lxikxeoI4Su9qpsUQNzUD10rvWMx0iea8Z
+47Z4RI6fIlA5xC5N4VfUFQdE/VN670HdiTZ7YAFIg9F/ZJQMH+hPVNSLgY6J0RdU
+3gqKAkAvmCQZyQKWG1eRqKauw4CIvk6d7N+nOzmwDb6clueFj7Kx4h4IAFHCQthn
+eXrf21uBCVwVjs64ilnTVwFfklr79euYRHPmRqR5eswbIGpDEFOaf1smu4hrkK9s
+tQ8YWey8TICymBaXr1hI+WjSVEQFN8xPoVQwiKJRdu7lIosDjbH8V/ooKGMhCHgl
+5C995L3sKsMyCMkw90viYNy2jUuSNu2X3eK+QJip2D2smfSM2tBsFtiXyEk+WeyY
+cRDlwB7+6vvVwCHqz0+4lr0HHBEky43m3NgUtZoulfRwv4znGXcMqvxVUm4pwoBf
+lo7zVuXh+cXrEzzCksQiCBzBM115itb3la8RX8A4bRUs38XG6Bz+Qfr6RQspppV1
+vNd5mUOyBYNeVfErf59PnFsdMI3kD0UgwpLkkGdSGdzDKykdt7vffNRpV8jOYuuO
+LxH+2WlebCv1N90CAwEAAaNTMFEwHQYDVR0OBBYEFF80R0EZORGRXrZTVrAfaatK
+eNi9MB8GA1UdIwQYMBaAFF80R0EZORGRXrZTVrAfaatKeNi9MA8GA1UdEwEB/wQF
+MAMBAf8wDQYJKoZIhvcNAQELBQADggIBAHFZUflyNOCJqV+RghOAaVFDc7wqtZJ1
+d2dpIs28kKd43Nd+xjSZLmSmVhcntQNwqC8AHIuJKKNDmM5BRnzls1ZO+OLc+YcC
+kXzO2aBrNz8a0S0nYGzgR+CoTPvd61RGGHbqQNvZiroWsC4NaR+7NYPzsORNaN+1
+p/xqZygOYLOcD5tP5iNlgBugD+nPEHL0cylE0XpoZ059MIITdlvsrdPgHhFn9Nvv
+McPZp4nzpJvyUmVjkbT7ZbKIJFrOQ6qJ9U2y55F4xuHzvnaAsOGnGx1tyBHtvkA1
+IIovrku4su3TmMsBs/6ikT8XSR20gcsDq3N2RcFtgU5LONsWvUL9CTp7P7lMlIfg
+v1RelzXDE2mESlZEbzbFyVVGAoEPZA4t6kgBV4zObxxp4YmimqGWmVs3qQ/A6wbV
+OO4rLYW7NZeJLLvsGOabVK+jyFCMyB3YOS6nZ9q48SaWCHlFTZveluP5n/8Y5LGc
+ppjaZbsG2/apCqlown6jKT7hkP84eu3a+HyQ6ZXpCa6P9c9OZ8bVlP8dXi4mRuhU
+lINwIKA0HbFAzwhyArMkLFWsw26ImusLZH1KUjHabzbfxnDgb9hwIlSGyPrcHcYY
+lXTlThSXL0ERoqafQTE9tpPFXC+LCneytAKUgM2TZ1KhRlisA9Tb3i0X4y/yJba7
+T2Eqz8rRnaIe
+-----END CERTIFICATE-----

deploy/certs/tls.key

@@ -0,0 +1,52 @@
+-----BEGIN PRIVATE KEY-----
+MIIJQQIBADANBgkqhkiG9w0BAQEFAASCCSswggknAgEAAoICAQCSfsnDl/RrAYVs
+YvdkcQ8lqdk71iQkNSSUsXeQAGJeprBIWkzqld8oxrhUcTr8x+lERB5faWS+0Gx4
+5/++ELgMsAK6LyDKyVQ5u/vvEZJeYjCMVxdnMs9D+ASzaXGKTF6gjhK72qmxRA3N
+QPXSu9YzHSJ5rxnjtnhEjp8iUDnELk3hV9QVB0T9U3rvQd2JNntgAUiD0X9klAwf
+6E9U1IuBjonRF1TeCooCQC+YJBnJApYbV5Gopq7DgIi+Tp3s36c7ObANvpyW54WP
+srHiHggAUcJC2Gd5et/bW4EJXBWOzriKWdNXAV+SWvv165hEc+ZGpHl6zBsgakMQ
+U5p/Wya7iGuQr2y1DxhZ7LxMgLKYFpevWEj5aNJURAU3zE+hVDCIolF27uUiiwON
+sfxX+igoYyEIeCXkL33kvewqwzIIyTD3S+Jg3LaNS5I27Zfd4r5AmKnYPayZ9Iza
+0GwW2JfIST5Z7JhxEOXAHv7q+9XAIerPT7iWvQccESTLjebc2BS1mi6V9HC/jOcZ
+dwyq/FVSbinCgF+WjvNW5eH5xesTPMKSxCIIHMEzXXmK1veVrxFfwDhtFSzfxcbo
+HP5B+vpFCymmlXW813mZQ7IFg15V8St/n0+cWx0wjeQPRSDCkuSQZ1IZ3MMrKR23
+u9981GlXyM5i644vEf7ZaV5sK/U33QIDAQABAoICAA34ohDxm8mdxEYFPT9ayf1H
+UNS0VE+QsuusbjDxXHBW+N55oDbKMtV+eENzZhMIFM7iKTxjvow1L/cq9xi/GvJ4
+0dXEW14Dq/DypPEUra8rMaKcxrpcnehHTdl3f7DXHjo1OoOoc8EYcrGF1bvylpfa
+2jgdMzykoR02teYNnSjA2sQYPn1/6zw2uzV4xGJK7CLIlIwfzYS/2tUrMG+wcpqZ
+R7sFfN5NRoK28OMTZFMnmD3E0Psy5F14U3JE6KpX3SjYlFoHOQNqUrJU8kKUpyIy
+qfJ6lYnAJnvS4wBLxDGRtQda0D1Ov/jjDP8T6Dp1DDvmAUDtGNQzVjCHLKejP5MD
+ltUjTDiFqSXzcRmEV2Jq8y/DjqWieM3BGGl77W6W8eksYqLSo2Ik4fJLqoTm5TSw
+QY6d8/9gZAP+0E64MWnu0cxpMEXikPPrcjhcTFASxNBoxVhxKseRt+tgkgP4krPu
+hG2WsWY7n5B0iuO5Dxi0yttT5LfpKcrmRlQXqs0Jdn6nxA7us62WgegxBCXPHCpE
+rMHlsbrmJECkvnQ11P7eRnpD56b5uD7Kg4uMcUVdY+EKESjm2SwK0FrSBJRvQ/mg
+JKC7rf2tx7XB3tiKPrmygtLzwyU18+drCMI7fpcrf7wgwyuSdH3klkqnjF/xchQ9
+RkT3ZDR6mpxhv/ytoXrhAoIBAQDISEKgj/Z+2bNLhryvRfQACzvLHVp59oyI5Xa6
+MxLIVtozpq05wJxUgY4iPVXLx1Vm9/osHhXQtsFwMQTG2RI0tcz4N7YXrH4acmlm
+ErdoORtcRX15mEVAl7Mwac4LVyllOZ1D9woKboHDmlBO2L8FUXy8RiLdUT0jgK7k
+ShWb35twbqwQDLezLEiMnxKFCarVFVBTxVn2bhRA5jcPU+9S2oK9Qx/Mei7QlKKE
+uTXLOTtNGSvY/7h0dExzS8nXwRDvsVCrWCT5pca1KfmR/JPOPbM6I/vwziSIqMNk
+GfZWe5IlsQRtyZ49DpA+eDQxzMhxjZhWQ6JR5iQFWUCtXKIhAoIBAQC7P+pPEf9l
+KOhdPJu6p9NPQu6+hMTi5rTyCDsH5VggvoLKDZTJ1BSqWtW1K09UafRWP5vOxm7u
+fBYcnqu0W5RSUuoQTZiu03ZhYLBV5vbR+Icx0Hc2BDl8eEIyevyqsmm8+w5i28Ar
+knep4sP7/n+q2EAK1B2ZlNXXz6f47CMQMkVvZp3FR0F7R6yJoS32tTL5wDOxuOFG
+LYQOG/yI5JWXwBXov83zrpc+C7kl4gV3xAOk7fZ0exoRdmuvdLS96Ans85L7J8RW
+ELSfhmGahM+SQ1oJMcV/wYqF2qeLL2F8DZbjR5izLZgkNz4a/VMl/A6YHtuTBXAY
++5PXXUOX+9Y9AoIBACI+II4dLxLPG9WM6tO4zRf407dNhHuXyL1bJip9svdnyhTM
+qY9XPCNCp095VyLpKNPbD/3dAvPVW0tYRi3NTUyPzMSfmdWAW2sgJp8aEhuSr/fd
+ta9Fdomtpihf3qeXtm8lI5tMMH5KGIud5Z8ldbtuDDqQb0ORsTdRuBU2CW3GFGhr
+s6Vm1z2eE6VfSSZP2dJmu34nHtOATJwwADfxrNhonbPINzaZqUlmMEcq92SQm2/6
+HsISLrJSdAO+cHsf+kpQ8a7p+iBo1ImC7LWmDotTh0IohtnMFPj8ibOisLhmlj01
+f8FZmGFuDQFxQdNF5PttLx+InscL5xq3ANTjIqECggEADpdtd9nsMALfEJzveb0o
+P0308s2/1fqqcQ3pI7Vgh7Sw1nP2ez/WmGvZqXOFjAtxqeLtDlDyRg1PX82Rjc1x
+InUpnjmdw0nhOLdjJl6IL1aRmnUnRQNRQ3zPk8V3uQmMKdjahyOetwaD4q40HYf4
+hOSzIOTkpZoui9G3wjMMjG+Ob57sfnoOBUBRlqwDu+zk2wd6P8grbd+QIdVWeYhu
+i9PBIVEJCIs7Z+9b7zLMwEd7DTgp82vAXUoAHD0Y9I+HbnqQope3ugk1OhUrt/HP
+hxNOidbiEBGR7NpcIgGAND2O24kxwgy0hWX0pf/FofkhXgNRkwRidt/r5mVzJf3O
+9QKCAQAcPXczJY1gynUA8uD/1ODmjpDjWAk0EKBEWY5X2oULv2+xGMNTbT8pwE3f
+1rszdtF3ckDPoBn7XS9OJwHnVHfXZNJHBtq9utLu0ccE+29HRG0pLCzATsvtoBWi
+MEwZ2mPqhVpktfqEnL27l/QHkP7dNOyh+halVCHMfy1aNMY6hsKrOcmVmYHVARX0
+Np2sG9zQszE0+t2mf8Pfd7cEvVuSTIfYZnW+77+PaVkICXXX0rrvwXVh/DVXwmWH
+kYbDIdiNs9NEFwCmIvzLVsCp0qGUuq9txYo/ML5PMzJhN6X3U+rV42GkkT7KxwH2
+Izss0+mp4ijKEFQuCGCkxjFmxUEq
+-----END PRIVATE KEY-----

deploy/envoy/ENVOY_CONFIG_GUIDE.md

@@ -0,0 +1,320 @@
+# Envoy Gateway 配置指南
+
+## 概述
+
+Envoy Gateway 作为 API 统一入口，提供以下功能：
+- **JWT 身份验证**：所有 API 请求（除登录/注册）都需要有效的 JWT token
+- **CSRF 防护**：防止跨站点请求伪造攻击
+- **速率限制**：防止 DDoS 攻击
+- **TLS 加密**：所有通信都加密
+- **负载均衡**：分担后端服务的流量
+
+## 架构
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │ HTTP/HTTPS (Port 80/443)
+       │
+┌──────▼────────────────┐
+│   Envoy Gateway       │
+│  ┌────────────────┐   │
+│  │ JWT Validator  │   │ ◄─── JWT Verification (offline)
+│  │ CSRF Filter    │   │
+│  │ Rate Limiter   │   │
+│  │ Router         │   │
+│  └────────────────┘   │
+└────────┬─────────────┘
+         │ gRPC/HTTP
+    ┌────┴────┬──────────┐
+    │          │          │
+┌───▼──┐   ┌──▼────┐  ┌──▼─────┐
+│User  │   │Order  │  │User    │
+│API   │   │API    │  │RPC     │
+└──────┘   └───────┘  └────────┘
+```
+
+## 部署步骤
+
+### 1. 生成 TLS 证书
+
+```bash
+# 为 Envoy 生成自签名证书（生产环境应使用正式证书）
+kubectl create secret tls envoy-tls \
+  --cert=path/to/tls.crt \
+  --key=path/to/tls.key \
+  -n juwan
+
+# 或生成自签名证书（仅用于测试）
+openssl req -x509 -newkey rsa:4096 -keyout tls.key -out tls.crt \
+  -days 365 -nodes -subj "/CN=api.juwan.local"
+
+kubectl create secret tls envoy-tls \
+  --cert=tls.crt \
+  --key=tls.key \
+  -n juwan
+```
+
+### 2. 部署 Envoy Gateway
+
+```bash
+# 应用 Envoy 配置
+kubectl apply -f deploy/k8s/envoy-gateway.yaml
+
+# 查看部署状态
+kubectl get pods -n juwan -l app=envoy-gateway
+kubectl get svc -n juwan envoy-gateway
+```
+
+### 3. 配置 JWKS 端点
+
+在 user-rpc 中暴露 JWKS 端点，供 Envoy 验证 JWT：
+
+#### 在 `app/users/rpc` 中添加 HTTP 路由（go-zero）
+
+编辑 `app/users/rpc/internal/handler/` 或在 `main.go` 中：
+
+```go
+// 在 rpc server 启动时，添加 HTTP 端点用于暴露 JWKS
+import (
+    "net/http"
+    "juwan-backend/app/users/rpc/internal/utils"
+)
+
+// 在 main 函数中
+http.HandleFunc("/.well-known/jwks.json", func(w http.ResponseWriter, r *http.Request) {
+    secretKey := os.Getenv("JWT_SECRET_KEY")
+    if secretKey == "" {
+        secretKey = "your-default-secret-key"
+    }
+    
+    jwksJSON, err := utils.GenerateJWKSEndpoint(secretKey, "default-key-id")
+    if err != nil {
+        http.Error(w, "Failed to generate JWKS", http.StatusInternalServerError)
+        return
+    }
+    
+    w.Header().Set("Content-Type", "application/json")
+    w.Write([]byte(jwksJSON))
+})
+
+// 在单独的 goroutine 中启动 HTTP 服务器
+go func() {
+    http.ListenAndServe(":8080", nil)
+}()
+```
+
+**或使用 Echo 框架（更推荐）**：
+
+```go
+// 在 main.go 中
+import "github.com/labstack/echo/v4"
+
+e := echo.New()
+e.GET("/.well-known/jwks.json", func(c echo.Context) error {
+    secretKey := os.Getenv("JWT_SECRET_KEY")
+    jwksJSON, _ := utils.GenerateJWKSEndpoint(secretKey, "default-key-id")
+    return c.JSONBlob(http.StatusOK, []byte(jwksJSON))
+})
+
+go func() {
+    e.Start(":8080")
+}()
+```
+
+### 4. 更新环境变量
+
+在 K8s Secret 中配置 JWT_SECRET_KEY：
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: jwt-secret
+  namespace: juwan
+type: Opaque
+data:
+  JWT_SECRET_KEY: "$(echo -n 'your-secret-key-change-this' | base64)"
+```
+
+### 5. 验证 JWKS 端点
+
+```bash
+# 端口转发
+kubectl port-forward -n juwan svc/user-rpc-svc 9001:9001
+
+# 验证 JWKS 端点可访问
+curl http://localhost:9001/.well-known/jwks.json
+```
+
+## JWT 验证流程
+
+### 1. 登录获取 Token
+
+```bash
+curl -X POST http://api.juwan.local/api/v1/users/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "testuser",
+    "password": "password123"
+  }'
+
+# 响应：
+# {
+#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+#   "expires": 1708780800
+# }
+```
+
+### 2. 使用 Token 访问受保护资源
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  https://api.juwan.local/api/v1/users/123
+
+# Envoy 验证步骤：
+# 1. 从 Authorization header 提取 token
+# 2. 从 JWKS 端点获取公钥（缓存 5 分钟）
+# 3. 验证 token 签名
+# 4. 检查 token 过期时间
+# 5. 将验证后的用户信息添加到请求头（X-USER-ID）
+# 6. 转发请求到 user-api
+```
+
+## CSRF 防护
+
+### 配置说明
+
+Envoy 的 CSRF 过滤器检查：
+- 只对 POST/PUT/DELETE/PATCH 请求进行检查
+- 检查 `Origin` 和 `Referer` header
+- 验证请求来自已知域名
+
+### 跨域请求配置
+
+```yaml
+# Envoy 配置中允许的来源
+additional_origins:
+  - exact: "https://admin.juwan.local"
+  - exact: "https://web.juwan.local"
+```
+
+## Token 黑名单检查（可选）
+
+如果需要验证 token 未被撤销，可启用额外的 RPC 验证：
+
+```yaml
+# envoy-gateway.yaml 中取消注释
+- name: envoy.filters.http.ext_authz
+  typed_config:
+    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
+    grpc_service:
+      envoy_grpc:
+        cluster_name: user_rpc_cluster
+    failure_mode_allow: false
+```
+
+然后在 user-rpc 中实现 ValidateToken RPC：
+
+```protobuf
+rpc ValidateToken(ValidateTokenReq) returns(ValidateTokenResp);
+```
+
+## 故障排查
+
+### 1. JWT 验证失败
+
+```bash
+# 查看 Envoy 日志
+kubectl logs -n juwan -l app=envoy-gateway -f
+
+# 验证 JWKS 端点是否可访问
+kubectl exec -it -n juwan <envoy-pod> -- \
+  curl http://user-rpc-svc:9001/.well-known/jwks.json
+```
+
+### 2. 无法连接到后端服务
+
+```bash
+# 验证服务发现
+kubectl get endpoints -n juwan
+
+# 验证网络策略
+kubectl get networkpolicy -n juwan
+
+# 测试连接
+kubectl exec -it -n juwan <envoy-pod> -- \
+  curl http://user-api-svc:8888/health
+```
+
+### 3. CSRF 错误
+
+- 确保设置了 `Origin` 和 `Referer` header
+- 检查 `additional_origins` 配置是否包含你的域名
+
+## 性能优化
+
+### 1. JWKS 缓存
+
+```yaml
+cache_ttl:
+  seconds: 300  # 缓存 5 分钟，减少 RPC 调用
+```
+
+### 2. 连接池
+
+```yaml
+http2_protocol_options: {}  # 启用 HTTP/2 多路复用
+```
+
+### 3. 速率限制调整
+
+根据实际流量调整令牌桶参数：
+
+```yaml
+token_bucket:
+  max_tokens: 10000        # 最大令牌数
+  tokens_per_fill: 10000   # 每次填充的令牌数
+  fill_interval: 1s        # 填充间隔
+```
+
+## 监控和日志
+
+### 访问日志
+
+```bash
+# 查看访问日志
+kubectl logs -n juwan -l app=envoy-gateway --follow
+
+# 格式包含：
+# - 请求时间、方法、路径
+# - 响应状态码、字节数
+# - 上游服务信息
+```
+
+### Prometheus 指标
+
+Envoy 在 `:9901/stats` 暴露 Prometheus 指标：
+
+```bash
+kubectl port-forward -n juwan svc/envoy-gateway 9901:9901
+curl localhost:9901/stats | grep jwt
+```
+
+## 生产环境检查清单
+
+- [ ] 使用正式 TLS 证书（不是自签名）
+- [ ] 配置正确的 JWT_SECRET_KEY（强密码）
+- [ ] 启用 HTTPS（关闭 HTTP）
+- [ ] 配置网络策略限制访问
+- [ ] 启用访问日志和监控
+- [ ] 设置合理的速率限制
+- [ ] 测试 token 过期和刷新流程
+- [ ] 配置告警规则
+
+## 参考文档
+
+- [Envoy JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto)
+- [Envoy CSRF Protection](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/csrf/v3/csrf.proto)
+- [JWT RFC 7519](https://tools.ietf.org/html/rfc7519)

deploy/envoy/QUICK_REFERENCE.md

@@ -0,0 +1,371 @@
+# Envoy 配置完整清单
+
+## 📋 配置文件清单
+
+### 1. Proto 更新
+- **文件**: [desc/rpc/users.proto](../../desc/rpc/users.proto)
+- **更改**: 添加了两个 RPC 方法
+  - `ValidateToken()`: 验证 token 是否有效（检查黑名单）
+  - `CheckPermission()`: 检查用户权限
+
+### 2. Envoy 部署
+- **配置文件**: [envoy.yaml](./envoy.yaml)
+  - HTTP 监听器（端口 8080）
+  - HTTPS 监听器（端口 8443）
+  - JWT 验证过滤器
+  - CSRF 防护过滤器
+  - 速率限制（DDoS 防护）
+  - 路由配置
+
+- **K8s 部署**: [../k8s/envoy-gateway.yaml](../k8s/envoy-gateway.yaml)
+  - 2 个副本
+  - 负载均衡器服务
+  - Service Account 和 RBAC
+  - Network Policy
+  - ConfigMap 用于配置管理
+
+### 3. 工具代码
+- **JWKS 生成**: [app/users/rpc/internal/utils/jwks.go](../../app/users/rpc/internal/utils/jwks.go)
+  - `GenerateJWKSFromSecret()`: 从 JWT 密钥生成 JWKS
+  - `GenerateJWKSEndpoint()`: 生成 JSON 输出供 Envoy 使用
+  - `ExtractTokenMetadata()`: 提取 token 元数据
+
+### 4. Dockerfile
+- **文件**: [Dockerfile](./Dockerfile)
+- **用途**: 构建 Envoy 容器镜像
+
+### 5. 脚本
+- **文件**: [generate-jwks.sh](./generate-jwks.sh)
+- **用途**: 快速生成 JWKS JSON 文件
+
+### 6. 文档
+- **文件**: [ENVOY_CONFIG_GUIDE.md](./ENVOY_CONFIG_GUIDE.md)
+- **内容**: 详细的配置和部署指南
+
+---
+
+## 🚀 快速部署步骤
+
+### 步骤 1: 生成 TLS 证书
+
+```bash
+# 测试环境：生成自签名证书
+openssl req -x509 -newkey rsa:4096 -keyout tls.key -out tls.crt \
+  -days 365 -nodes -subj "/CN=api.juwan.local"
+
+# 创建 K8s Secret
+kubectl create secret tls envoy-tls \
+  --cert=tls.crt \
+  --key=tls.key \
+  -n juwan
+```
+
+### 步骤 2: 部署 Envoy Gateway
+
+```bash
+# 应用部署文件
+kubectl apply -f deploy/k8s/envoy-gateway.yaml
+
+# 验证部署
+kubectl get pods -n juwan -l app=envoy-gateway
+kubectl get svc -n juwan envoy-gateway
+
+# 等待 LoadBalancer 获取外部 IP
+kubectl get svc -n juwan envoy-gateway -w
+```
+
+### 步骤 3: 在 User RPC 中暴露 JWKS 端点
+
+编辑 `app/users/rpc/rpcserver.go` 或 `main.go`：
+
+```go
+package main
+
+import (
+	"http"
+	"os"
+	"juwan-backend/app/users/rpc/internal/utils"
+)
+
+// 在启动 RPC server 前，添加 HTTP 端点
+func setupJWKSEndpoint() {
+	secretKey := os.Getenv("JWT_SECRET_KEY")
+	if secretKey == "" {
+		secretKey = "your-default-secret-key"
+	}
+	
+	http.HandleFunc("/.well-known/jwks.json", func(w http.ResponseWriter, r *http.Request) {
+		jwksJSON, err := utils.GenerateJWKSEndpoint(secretKey, "default-key-id")
+		if err != nil {
+			http.Error(w, "Failed to generate JWKS", http.StatusInternalServerError)
+			return
+		}
+		
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Cache-Control", "public, max-age=300") // 缓存 5 分钟
+		w.Write([]byte(jwksJSON))
+	})
+	
+	// 在独立的 goroutine 中启动 HTTP 服务器
+	go func() {
+		http.ListenAndServe(":8080", nil)
+	}()
+}
+
+func main() {
+	setupJWKSEndpoint()
+	
+	// ... 其他 RPC 启动代码 ...
+}
+```
+
+### 步骤 4: 更新 User RPC 配置
+
+编辑 `app/users/rpc/etc/pb.yaml`：
+
+```yaml
+Name: pb.rpc
+ListenOn: 0.0.0.0:9001
+
+Prometheus:
+  Host: 0.0.0.0
+  Port: 4001
+  Path: /metrics
+
+# ... 其他配置 ...
+
+Jwt:
+  SecretKey: "${JWT_SECRET_KEY:your-secret-jwt-key-change-this-in-production}"
+  Issuer: "juwan-user-rpc"
+```
+
+### 步骤 5: 构建并推送容器镜像
+
+```bash
+# 构建 User API 镜像
+docker build -t your-registry/user-api:latest ./app/users/api/
+docker push your-registry/user-api:latest
+
+# 构建 User RPC 镜像
+docker build -t your-registry/user-rpc:latest ./app/users/rpc/
+docker push your-registry/user-rpc:latest
+
+# 构建 Envoy 镜像
+docker build -f deploy/envoy/Dockerfile -t your-registry/envoy-gateway:latest .
+docker push your-registry/envoy-gateway:latest
+```
+
+### 步骤 6: 更新 K8s 部署
+
+更新 `deploy/k8s/service/user/user-api.yaml` 和 `user-rpc.yaml`，确保使用正确的镜像和环境变量。
+
+---
+
+## 🧪 测试流程
+
+### 1. 登录获取 Token
+
+```bash
+# 获取 Envoy 外部 IP
+ENVOY_IP=$(kubectl get svc -n juwan envoy-gateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
+
+# 登录
+curl -k -X POST "https://$ENVOY_IP:443/api/v1/users/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "testuser",
+    "password": "password123"
+  }' | jq .
+
+# 示例响应：
+# {
+#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+#   "expires": 1708780800
+# }
+```
+
+### 2. 使用 Token 访问受保护资源
+
+```bash
+TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+
+curl -k -X GET "https://$ENVOY_IP:443/api/v1/users/123" \
+  -H "Authorization: Bearer $TOKEN" | jq .
+```
+
+### 3. 验证 CSRF 防护
+
+```bash
+# POST 请求必须有正确的 Origin/Referer
+curl -k -X POST "https://$ENVOY_IP:443/api/v1/users/logout" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Origin: https://api.juwan.local" \
+  -H "Referer: https://api.juwan.local/" \
+  -H "Content-Type: application/json" \
+  -d '{"userId": 123}'
+```
+
+---
+
+## 📊 验证检查清单
+
+- [ ] Envoy 容器运行正常
+  ```bash
+  kubectl logs -n juwan -l app=envoy-gateway
+  ```
+
+- [ ] JWKS 端点可访问
+  ```bash
+  kubectl exec -it -n juwan <envoy-pod> -- \
+    curl http://user-rpc-svc:9001/.well-known/jwks.json
+  ```
+
+- [ ] 后端服务健康
+  ```bash
+  kubectl exec -it -n juwan <envoy-pod> -- \
+    curl http://user-api-svc:8888/health
+  ```
+
+- [ ] JWT 验证工作
+  ```bash
+  # 不带 token 访问受保护资源应返回 401
+  curl -k https://api.juwan.local/api/v1/users/123
+  ```
+
+- [ ] CSRF 防护生效
+  ```bash
+  # 缺少 Origin header 的 POST 应被拒绝
+  curl -k -X POST https://api.juwan.local/api/v1/users/logout \
+    -H "Authorization: Bearer $TOKEN"
+  ```
+
+---
+
+## 🔧 配置调整
+
+### 修改 JWT 密钥
+
+```bash
+# 1. 更新 K8s Secret
+kubectl patch secret jwt-secret -n juwan \
+  -p '{"data":{"JWT_SECRET_KEY":"'$(echo -n 'new-secret-key' | base64)'"}}'
+
+# 2. 重启 User RPC 和 Envoy
+kubectl rollout restart deployment/user-rpc-svc -n juwan
+kubectl rollout restart deployment/envoy-gateway -n juwan
+```
+
+### 调整 Envoy 速率限制
+
+编辑 ConfigMap：
+```bash
+kubectl edit cm envoy-config -n juwan
+```
+
+修改 `token_bucket` 参数：
+```yaml
+token_bucket:
+  max_tokens: 5000       # 降低限制
+  tokens_per_fill: 5000
+  fill_interval: 1s
+```
+
+### 添加信任的 CSRF 来源
+
+编辑 ConfigMap：
+```yaml
+additional_origins:
+  - exact: "https://admin.juwan.local"
+  - exact: "https://web.juwan.local"
+  - prefix: "https://app.juwan.local"  # 支持前缀匹配
+```
+
+---
+
+## 📈 监控和日志
+
+### 查看 Envoy 统计
+
+```bash
+kubectl port-forward -n juwan svc/envoy-gateway 9901:9901
+curl localhost:9901/stats | grep -E "(jwt_authn|csrf|http_ratelimit)"
+```
+
+### 实时日志
+
+```bash
+kubectl logs -n juwan -l app=envoy-gateway -f
+
+# 查看特定日志行
+kubectl logs -n juwan -l app=envoy-gateway | grep "401\|403"
+```
+
+### 监控指标（集成 Prometheus）
+
+```yaml
+# prometheus-scrape-config.yaml
+- job_name: 'envoy-gateway'
+  static_configs:
+    - targets: ['envoy-gateway.juwan.svc.cluster.local:9901']
+  metrics_path: '/stats/prometheus'
+```
+
+---
+
+## 📚 相关文件位置
+
+```
+deploy/
+├── envoy/
+│   ├── envoy.yaml                    ← Envoy 核心配置
+│   ├── ENVOY_CONFIG_GUIDE.md         ← 详细指南
+│   ├── generate-jwks.sh              ← JWKS 生成脚本
+│   ├── Dockerfile                     ← Envoy 镜像
+│   └── QUICK_REFERENCE.md            ← 本文件
+├── k8s/
+│   ├── envoy-gateway.yaml            ← K8s 部署清单
+│   └── secrets/jwt-secret.yaml        ← JWT 密钥配置
+└── script/
+    └── init-secrets.sh               ← 初始化脚本
+
+app/users/
+├── rpc/
+│   ├── internal/utils/
+│   │   ├── jwks.go                   ← JWKS 生成工具
+│   │   └── jwt.go                    ← JWT 管理器
+│   └── etc/pb.yaml                   ← RPC 配置
+└── api/
+    └── etc/user-api.yaml             ← API 配置
+
+desc/
+└── rpc/users.proto                   ← Proto 定义（已更新）
+```
+
+---
+
+## 🤔 常见问题
+
+1. **Envoy 无法连接到后端服务**
+   - 检查 K8s Service DNS: `user-api-svc.juwan.svc.cluster.local`
+   - 验证 NetworkPolicy 允许流量
+
+2. **JWT 验证失败**
+   - 确保 JWT_SECRET_KEY 一致
+   - 检查 JWKS 端点是否可访问
+   - 查看 Envoy 日志: `grep "jwt_authn" envoy.log`
+
+3. **CSRF 防护过于严格**
+   - 在 `additional_origins` 中添加允许的来源
+   - 对于单页应用，确保发送 `Origin` header
+
+4. **速率限制阻止正常流量**
+   - 增加 `max_tokens` 和 `tokens_per_fill`
+   - 针对特定客户端配置不同的限制
+
+---
+
+## 📞 获取帮助
+
+- 查看 [Envoy 官方文档](https://www.envoyproxy.io/docs)
+- 查看 [JWT 规范](https://tools.ietf.org/html/rfc7519)
+- 检查 [CSRF 防护最佳实践](https://owasp.org/www-community/attacks/csrf)

deploy/envoy/deploy.sh

@@ -0,0 +1,331 @@
+#!/bin/bash
+
+# Envoy 快速部署脚本
+# 用途：自动化部署 Envoy Gateway 到 Kubernetes
+
+set -e
+
+# 配置
+NAMESPACE="${NAMESPACE:-juwan}"
+RELEASE_NAME="${RELEASE_NAME:-envoy-gateway}"
+TIMEOUT="${TIMEOUT:-300s}"
+CONTEXT="${CONTEXT:-}"
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# 日志函数
+log_info() {
+    echo -e "${BLUE}ℹ${NC}  $1"
+}
+
+log_success() {
+    echo -e "${GREEN}✓${NC}  $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}⚠${NC}  $1"
+}
+
+log_error() {
+    echo -e "${RED}✗${NC}  $1"
+}
+
+# 检查依赖
+check_dependencies() {
+    log_info "检查依赖..."
+    
+    local missing_deps=()
+    
+    if ! command -v kubectl &> /dev/null; then
+        missing_deps+=("kubectl")
+    fi
+    
+    if ! command -v openssl &> /dev/null; then
+        missing_deps+=("openssl")
+    fi
+    
+    if [ ${#missing_deps[@]} -gt 0 ]; then
+        log_error "缺少以下依赖: ${missing_deps[*]}"
+        return 1
+    fi
+    
+    log_success "所有依赖已安装"
+    return 0
+}
+
+# 生成 TLS 证书
+generate_tls_cert() {
+    log_info "生成 TLS 证书..."
+    
+    local cert_dir="certs"
+    local key_file="$cert_dir/tls.key"
+    local cert_file="$cert_dir/tls.crt"
+    
+    # 创建 certs 目录
+    mkdir -p "$cert_dir"
+    
+    # 检查是否已存在证书
+    if [ -f "$cert_file" ] && [ -f "$key_file" ]; then
+        log_warn "证书已存在: $cert_file, $key_file"
+        read -p "是否要重新生成? (y/n) " -t 10 -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            log_success "使用现有证书"
+            return 0
+        fi
+    fi
+    
+    # 生成自签名证书（仅用于测试）
+    openssl req -x509 -newkey rsa:4096 \
+        -keyout "$key_file" \
+        -out "$cert_file" \
+        -days 365 -nodes \
+        -subj "/CN=api.juwan.local" \
+        -addext "subjectAltName=DNS:api.juwan.local,DNS:*.juwan.local" \
+        > /dev/null 2>&1
+    
+    log_success "TLS 证书已生成"
+    log_warn "警告: 这是自签名证书，仅用于测试环境"
+    log_warn "生产环境应使用正式的 CA 签发证书"
+    
+    return 0
+}
+
+# 创建命名空间
+create_namespace() {
+    log_info "创建 Kubernetes 命名空间..."
+    
+    if kubectl get namespace "$NAMESPACE" &> /dev/null; then
+        log_warn "命名空间已存在: $NAMESPACE"
+        return 0
+    fi
+    
+    kubectl create namespace "$NAMESPACE"
+    log_success "命名空间已创建: $NAMESPACE"
+    
+    return 0
+}
+
+# 创建 TLS Secret
+create_tls_secret() {
+    log_info "创建 TLS Secret..."
+    
+    local cert_dir="certs"
+    local key_file="$cert_dir/tls.key"
+    local cert_file="$cert_dir/tls.crt"
+    
+    # 检查证书文件
+    if [ ! -f "$cert_file" ] || [ ! -f "$key_file" ]; then
+        log_error "证书文件不存在"
+        return 1
+    fi
+    
+    # 检查 Secret 是否已存在
+    if kubectl get secret envoy-tls -n "$NAMESPACE" &> /dev/null; then
+        log_warn "Secret 已存在，删除后重建"
+        kubectl delete secret envoy-tls -n "$NAMESPACE"
+    fi
+    
+    # 创建 Secret
+    kubectl create secret tls envoy-tls \
+        -n "$NAMESPACE" \
+        --cert="$cert_file" \
+        --key="$key_file"
+    
+    log_success "TLS Secret 已创建: envoy-tls"
+    
+    return 0
+}
+
+# 部署 Envoy Gateway
+deploy_envoy() {
+    log_info "部署 Envoy Gateway..."
+    
+    local manifest_file="deploy/k8s/envoy-gateway.yaml"
+    
+    if [ ! -f "$manifest_file" ]; then
+        log_error "找不到部署清单: $manifest_file"
+        return 1
+    fi
+    
+    # 应用部署
+    if [ -n "$CONTEXT" ]; then
+        kubectl apply -f "$manifest_file" --context="$CONTEXT"
+    else
+        kubectl apply -f "$manifest_file"
+    fi
+    
+    log_success "Envoy Gateway 部署清单已应用"
+    
+    return 0
+}
+
+# 等待部署完成
+wait_deployment() {
+    log_info "等待部署完成（超时: $TIMEOUT）..."
+    
+    kubectl rollout status deployment/envoy-gateway \
+        -n "$NAMESPACE" \
+        --timeout="$TIMEOUT" || {
+        log_error "部署超时"
+        return 1
+    }
+    
+    log_success "部署已完成"
+    
+    return 0
+}
+
+# 验证部署
+verify_deployment() {
+    log_info "验证部署..."
+    
+    # 检查 Pod
+    local pod_count=$(kubectl get pods -n "$NAMESPACE" \
+        -l app=envoy-gateway \
+        -o jsonpath='{.items | length}')
+    
+    if [ "$pod_count" -eq 0 ]; then
+        log_error "未找到 Envoy 容器"
+        return 1
+    fi
+    
+    log_success "找到 $pod_count 个 Envoy 容器"
+    
+    # 检查 Service
+    local svc_status=$(kubectl get svc -n "$NAMESPACE" |
+        grep envoy-gateway || echo "")
+    
+    if [ -z "$svc_status" ]; then
+        log_error "未找到 Service"
+        return 1
+    fi
+    
+    log_success "Service 已创建"
+    
+    # 显示 LoadBalancer IP
+    log_info "等待 LoadBalancer IP..."
+    local lb_ip=""
+    for i in {1..30}; do
+        lb_ip=$(kubectl get svc envoy-gateway -n "$NAMESPACE" \
+            -o jsonpath='{.status.loadBalancer.ingress[0].ip}' 2>/dev/null || echo "")
+        
+        if [ -n "$lb_ip" ] && [ "$lb_ip" != "null" ]; then
+            log_success "LoadBalancer IP: $lb_ip"
+            break
+        fi
+        
+        if [ $i -eq 30 ]; then
+            log_warn "未获得 LoadBalancer IP（可能在内网环境或使用 NodePort）"
+            kubectl get svc -n "$NAMESPACE" envoy-gateway
+            break
+        fi
+        
+        sleep 2
+    done
+    
+    return 0
+}
+
+# 显示部署信息
+show_summary() {
+    log_info "部署摘要"
+    echo ""
+    echo "  Namespace:       $NAMESPACE"
+    echo "  Release:         $RELEASE_NAME"
+    echo ""
+    echo "  Pods:"
+    kubectl get pods -n "$NAMESPACE" -l app=envoy-gateway \
+        -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,IP:.status.podIP \
+        | sed 's/^/    /'
+    
+    echo ""
+    echo "  Service:"
+    kubectl get svc -n "$NAMESPACE" envoy-gateway \
+        -o custom-columns=NAME:.metadata.name,TYPE:.spec.type,IP:.spec.clusterIP,EXTERNAL_IP:.status.loadBalancer.ingress[0].ip \
+        | sed 's/^/    /'
+    
+    echo ""
+    echo "  后续步骤:"
+    echo "    1. 在 User RPC 中暴露 JWKS 端点 (/.well-known/jwks.json)"
+    echo "    2. 配置 JWT_SECRET_KEY 环境变量"
+    echo "    3. 测试 JWT 验证: curl -k https://<ENVOY_IP>/api/v1/users/login"
+    echo ""
+    echo "  文档:"
+    echo "    - 配置指南: deploy/envoy/ENVOY_CONFIG_GUIDE.md"
+    echo "    - 快速参考: deploy/envoy/QUICK_REFERENCE.md"
+    echo ""
+}
+
+# 清理部署
+cleanup() {
+    log_warn "清理 Envoy Gateway..."
+    
+    kubectl delete -f deploy/k8s/envoy-gateway.yaml -n "$NAMESPACE" || true
+    kubectl delete secret envoy-tls -n "$NAMESPACE" || true
+    
+    log_success "清理完成"
+}
+
+# 主函数
+main() {
+    echo ""
+    echo -e "${BLUE}╔════════════════════════════════════════╗${NC}"
+    echo -e "${BLUE}║  Envoy Gateway 快速部署脚本            ║${NC}"
+    echo -e "${BLUE}╚════════════════════════════════════════╝${NC}"
+    echo ""
+    
+    # 解析命令行参数
+    local cmd="${1:-deploy}"
+    
+    case "$cmd" in
+        deploy)
+            check_dependencies || exit 1
+            generate_tls_cert || exit 1
+            create_namespace || exit 1
+            create_tls_secret || exit 1
+            deploy_envoy || exit 1
+            wait_deployment || exit 1
+            verify_deployment || exit 1
+            show_summary
+            log_success "Envoy Gateway 已成功部署！"
+            ;;
+        cleanup)
+            cleanup
+            ;;
+        status)
+            log_info "部署状态"
+            kubectl get all -n "$NAMESPACE" -l app=envoy-gateway
+            ;;
+        logs)
+            log_info "Envoy 日志"
+            kubectl logs -n "$NAMESPACE" -l app=envoy-gateway -f
+            ;;
+        *)
+            echo "用法: $0 <命令>"
+            echo ""
+            echo "命令:"
+            echo "  deploy      部署 Envoy Gateway（默认）"
+            echo "  cleanup     移除部署"
+            echo "  status      查看部署状态"
+            echo "  logs        查看 Envoy 日志"
+            echo ""
+            echo "环境变量:"
+            echo "  NAMESPACE   K8s 命名空间（默认: juwan）"
+            echo "  RELEASE_NAME 发布名称（默认: envoy-gateway）"
+            echo "  TIMEOUT     部署超时（默认: 300s）"
+            echo "  CONTEXT     K8s 上下文（可选）"
+            echo ""
+            exit 1
+            ;;
+    esac
+    
+    echo ""
+}
+
+main "$@"

deploy/envoy/envoy.yaml

@@ -0,0 +1,385 @@
+static_resources:
+  listeners:
+    # HTTP 监听器（重定向到 HTTPS）
+    - name: listener_http
+      address:
+        socket_address:
+          address: 0.0.0.0
+          port_number: 8080
+      filter_chains:
+        - filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                stat_prefix: ingress_http
+                http_filters:
+                  # CSRF 防护过滤器
+                  - name: envoy.filters.http.local_ratelimit
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
+                      stat_prefix: http_local_rate_limiter
+                      token_bucket:
+                        max_tokens: 1000
+                        tokens_per_fill: 1000
+                        fill_interval: 1s
+                      filter_enabled:
+                        runtime_key: local_rate_limit_enabled
+                        default_value:
+                          numerator: 100
+                          denominator: HUNDRED
+                      filter_enforced:
+                        runtime_key: local_rate_limit_enforced
+                        default_value:
+                          numerator: 100
+                          denominator: HUNDRED
+
+                  # 路由过滤器
+                  - name: envoy.filters.http.router
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+                route_config:
+                  name: local_route
+                  virtual_hosts:
+                    - name: backend
+                      domains: ["*"]
+                      routes:
+                        # 登录端点 - 不需要 JWT
+                        - match:
+                            path: /api/v1/users/login
+                            headers:
+                              - name: ":method"
+                                string_match:
+                                  exact: "POST"
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 30s
+
+                        # 注册端点 - 不需要 JWT
+                        - match:
+                            path: /api/v1/users/register
+                            headers:
+                              - name: ":method"
+                                string_match:
+                                  exact: "POST"
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 30s
+
+                        # 其他所有用户 API 端点 - 需要 JWT
+                        - match:
+                            prefix: /api/v1/users
+                            headers:
+                              - name: ":method"
+                                string_match:
+                                  exact: "GET"
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 30s
+                          request_headers_to_add:
+                            - header:
+                                key: "x-verified-user"
+                                value: "%REQ(X-USER-ID)%"
+
+                        # 订单 API - 需要 JWT
+                        - match:
+                            prefix: /api/v1/orders
+                          route:
+                            cluster: order_api_cluster
+                            timeout: 30s
+                          request_headers_to_add:
+                            - header:
+                                key: "x-verified-user"
+                                value: "%REQ(X-USER-ID)%"
+
+                        # 健康检查端点
+                        - match:
+                            path: /health
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 10s
+
+                        # 默认路由
+                        - match:
+                            prefix: /
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 30s
+                          direct_response:
+                            status: 404
+                            body:
+                              inline_string: "Not Found"
+
+    # HTTPS 监听器（需要配置 TLS 证书）
+    - name: listener_https
+      address:
+        socket_address:
+          address: 0.0.0.0
+          port_number: 8443
+      filter_chains:
+        - transport_socket:
+            name: envoy.transport_sockets.tls
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
+              common_tls_context:
+                tls_certificates:
+                  - certificate_chain:
+                      filename: /etc/envoy/certs/tls.crt
+                    private_key:
+                      filename: /etc/envoy/certs/tls.key
+          filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                stat_prefix: ingress_https
+                access_log:
+                  - name: envoy.access_loggers.file
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
+                      path: /var/log/envoy/access.log
+                      format: |
+                        [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"
+                        %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT%
+                        "%DURATION%" "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%"
+                        "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
+
+                http_filters:
+                  # JWT 验证过滤器
+                  - name: envoy.filters.http.jwt_authn
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
+                      providers:
+                        jwt_provider:
+                          issuer: "juwan-user-rpc"
+                          audiences: "api.juwan.local"
+                          # 本地验证（离线模式）- 需要在 ConfigMap 中配置公钥
+                          local_jwks:
+                            inline_string: |
+                              {
+                                "keys": [
+                                  {
+                                    "kty": "oct",
+                                    "k": "YOUR-BASE64-ENCODED-SECRET-KEY"
+                                  }
+                                ]
+                              }
+                          # 也可以使用远程 JWKS（更推荐）
+                          # remote_jwks:
+                          #   http_uri:
+                          #     uri: "http://user-rpc-svc:9001/.well-known/jwks.json"
+                          #     cluster: user_rpc_cluster
+                          #     timeout: 5s
+                          #   cache_ttl:
+                          #     seconds: 300
+                          # payload_in_metadata: "JWT_PAYLOAD"
+                      rules:
+                        # 不需要验证的路由
+                        - match:
+                            prefix: /api/v1/users/login
+                          allow_missing_or_failed: true
+
+                        - match:
+                            prefix: /api/v1/users/register
+                          allow_missing_or_failed: true
+
+                        - match:
+                            path: /health
+                          allow_missing_or_failed: true
+
+                        # 所有其他路由都需要有效的 JWT
+                        - match:
+                            prefix: /
+                          requires:
+                            provider_name: jwt_provider
+
+                  # CSRF 防护过滤器
+                  - name: envoy.filters.http.csrf
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.csrf.v3.CsrfPolicy
+                      filter_enabled:
+                        default_value:
+                          numerator: 100
+                          denominator: HUNDRED
+                        runtime_key: csrf_filter_enabled
+                      shadow_enabled:
+                        default_value:
+                          numerator: 0
+                          denominator: HUNDRED
+                        runtime_key: csrf_filter_shadow_enabled
+                      additional_origins:
+                        - exact: "https://admin.juwan.local"
+                      ignore_method_matches:
+                        - google_re2:
+                            regex: "^(GET|HEAD|OPTIONS|TRACE)$"
+
+                  # 代理验证过滤器（可选 - 调用 RPC 验证 token 黑名单）
+                  # - name: envoy.filters.http.ext_authz
+                  #   typed_config:
+                  #     "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
+                  #     grpc_service:
+                  #       envoy_grpc:
+                  #         cluster_name: user_rpc_cluster
+                  #     failure_mode_allow: false
+                  #     with_request_body:
+                  #       max_request_bytes: 8192
+                  #       allow_partial_message: false
+
+                  # 本地速率限制（DDOS 防护）
+                  - name: envoy.filters.http.local_ratelimit
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
+                      stat_prefix: https_local_rate_limiter
+                      token_bucket:
+                        max_tokens: 10000
+                        tokens_per_fill: 10000
+                        fill_interval: 1s
+                      filter_enabled:
+                        runtime_key: local_rate_limit_enabled
+                        default_value:
+                          numerator: 100
+                          denominator: HUNDRED
+
+                  # 路由过滤器
+                  - name: envoy.filters.http.router
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+                route_config:
+                  name: https_route
+                  virtual_hosts:
+                    - name: backend
+                      domains: ["*"]
+                      routes:
+                        # 登录和注册不需要 JWT
+                        - match:
+                            path: /api/v1/users/login
+                            headers:
+                              - name: ":method"
+                                string_match:
+                                  exact: "POST"
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 30s
+
+                        - match:
+                            path: /api/v1/users/register
+                            headers:
+                              - name: ":method"
+                                string_match:
+                                  exact: "POST"
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 30s
+
+                        # 用户 API（带 JWT 验证）
+                        - match:
+                            prefix: /api/v1/users
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 30s
+                          request_headers_to_add:
+                            - header:
+                                key: "x-verified-user"
+                                value: "%REQ(X-USER-ID)%"
+
+                        # 订单 API（带 JWT 验证）
+                        - match:
+                            prefix: /api/v1/orders
+                          route:
+                            cluster: order_api_cluster
+                            timeout: 30s
+                          request_headers_to_add:
+                            - header:
+                                key: "x-verified-user"
+                                value: "%REQ(X-USER-ID)%"
+
+                        # 健康检查
+                        - match:
+                            path: /health
+                          route:
+                            cluster: user_api_cluster
+                            timeout: 10s
+
+                        # 默认路由
+                        - match:
+                            prefix: /
+                          direct_response:
+                            status: 404
+                            body:
+                              inline_string: "Not Found"
+
+  clusters:
+    # User API 集群
+    - name: user_api_cluster
+      connect_timeout: 10s
+      type: STRICT_DNS
+      dns_lookup_family: V4_ONLY
+      lb_policy: ROUND_ROBIN
+      load_assignment:
+        cluster_name: user_api_cluster
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: user-api-svc
+                      port_number: 8888
+      health_checks:
+        - timeout: 5s
+          interval: 10s
+          unhealthy_threshold: 2
+          healthy_threshold: 2
+          http_health_check:
+            path: /health
+            expected_statuses:
+              - start: 200
+                end: 299
+
+    # Order API 集群
+    - name: order_api_cluster
+      connect_timeout: 10s
+      type: STRICT_DNS
+      dns_lookup_family: V4_ONLY
+      lb_policy: ROUND_ROBIN
+      load_assignment:
+        cluster_name: order_api_cluster
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: order-api-svc
+                      port_number: 8889
+      health_checks:
+        - timeout: 5s
+          interval: 10s
+          unhealthy_threshold: 2
+          healthy_threshold: 2
+          http_health_check:
+            path: /health
+            expected_statuses:
+              - start: 200
+                end: 299
+
+    # User RPC 集群（用于 ext_authz 调用）
+    - name: user_rpc_cluster
+      connect_timeout: 10s
+      type: STRICT_DNS
+      dns_lookup_family: V4_ONLY
+      lb_policy: ROUND_ROBIN
+      load_assignment:
+        cluster_name: user_rpc_cluster
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: user-rpc-svc
+                      port_number: 9001
+      http2_protocol_options: {}
+
+admin:
+  address:
+    socket_address:
+      address: 0.0.0.0
+      port_number: 9901

deploy/envoy/generate-jwks.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# 生成 JWKS JSON 文件的脚本
+# 用于 Envoy JWT 验证
+
+set -e
+
+# 参数
+JWT_SECRET_KEY="${1:-your-secret-key-change-this-in-production}"
+OUTPUT_FILE="${2:-jwks.json}"
+KEY_ID="${3:-default-key-id}"
+
+echo "生成 JWKS JSON..."
+echo "- Secret Key: ${JWT_SECRET_KEY:0:10}..."
+echo "- Key ID: $KEY_ID"
+echo "- Output: $OUTPUT_FILE"
+
+# 对密钥进行 base64 编码（URL-safe 无填充）
+ENCODED_KEY=$(echo -n "$JWT_SECRET_KEY" | base64 | tr '+/' '-_' | sed 's/=//g')
+
+# 生成 JWKS JSON
+cat > "$OUTPUT_FILE" <<EOF
+{
+  "keys": [
+    {
+      "kty": "oct",
+      "use": "sig",
+      "kid": "$KEY_ID",
+      "k": "$ENCODED_KEY",
+      "alg": "HS256"
+    }
+  ]
+}
+EOF
+
+echo "✓ JWKS 文件已生成: $OUTPUT_FILE"
+echo ""
+echo "内容预览:"
+cat "$OUTPUT_FILE"
+echo ""
+echo ""
+echo "配置说明:"
+echo "1. 在 user-rpc 的 .well-known/jwks.json 端点暴露此文件"
+echo "2. 在 Envoy 中配置远程 JWKS URI:"
+echo "   remote_jwks:"
+echo "     http_uri:"
+echo "       uri: http://user-rpc-svc:9001/.well-known/jwks.json"
+echo ""

deploy/envoy/setup-jwt-auth.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# JWT 和认证配置完整设置脚本
+
+set -e
+
+echo "🔐 Juwan JWT 认证配置脚本"
+echo "===================================="
+
+NAMESPACE="juwan"
+JWT_SECRET=$(openssl rand -hex 32)
+JWKS_KEY_ID="juwan-key-2026"
+
+echo "✅ 生成 JWT 密钥..."
+echo "   Secret: $JWT_SECRET"
+
+# Step 1: 创建 JWT Secret
+echo ""
+echo "📝 创建 K8s Secret..."
+kubectl create secret generic jwt-secret \
+  --from-literal=key=$JWT_SECRET \
+  -n $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -
+
+# Step 2: 生成 JWKS JSON（包含公钥）
+# 注意：对于 HMAC 算法，JWKS 包含密钥本身
+JWKS_JSON=$(cat <<EOF
+{
+  "keys": [
+    {
+      "kty": "oct",
+      "kid": "$JWKS_KEY_ID",
+      "k": "$(echo -n $JWT_SECRET | base64 -w 0)",
+      "alg": "HS256",
+      "use": "sig"
+    }
+  ]
+}
+EOF
+)
+
+echo "📝 创建 JWKS ConfigMap..."
+kubectl create configmap jwks-config \
+  --from-literal=jwks.json="$JWKS_JSON" \
+  -n $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -
+
+echo ""
+echo "✅ JWT 认证配置完成！"
+echo ""
+echo "后续步骤："
+echo "1. 更新 Envoy ConfigMap，挂载 JWKS 文件"
+echo "2. 在各 API 服务中配置 JWT_SECRET 环境变量"
+echo "3. 登录端点使用此密钥签名 Token"
+echo ""
+echo "JWT 密钥已保存到 K8s Secret: jwt-secret"
+echo "JWKS 已保存到 K8s ConfigMap: jwks-config"

deploy/k8s/envoy-gateway.yaml

@@ -0,0 +1,262 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: juwan
+
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: envoy-config
+  namespace: juwan
+data:
+  envoy.yaml: |
+    static_resources:
+      listeners:
+        - name: listener_http
+          address:
+            socket_address:
+              address: 0.0.0.0
+              port_value: 8080
+          filter_chains:
+            - filters:
+                - name: envoy.filters.network.http_connection_manager
+                  typed_config:
+                    "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                    stat_prefix: ingress_http
+                    access_log:
+                      - name: envoy.access_loggers.stdout
+                        typed_config:
+                          "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
+                    http_filters:
+                      - name: envoy.filters.http.router
+                        typed_config:
+                          "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+                    route_config:
+                      name: local_route
+                      virtual_hosts:
+                        - name: backend
+                          domains: ["*"]
+                          routes:
+                            - match:
+                                prefix: /api/v1/users
+                              route:
+                                cluster: user_api_cluster
+                                timeout: 30s
+                            - match:
+                                prefix: /api/v1/orders
+                              route:
+                                cluster: order_api_cluster
+                                timeout: 30s
+                            - match:
+                                prefix: /health
+                              route:
+                                cluster: user_api_cluster
+                                timeout: 10s
+                            - match:
+                                prefix: /
+                              route:
+                                cluster: user_api_cluster
+                                timeout: 30s
+
+      clusters:
+        - name: user_api_cluster
+          connect_timeout: 5s
+          type: STRICT_DNS
+          dns_lookup_family: V4_ONLY
+          lb_policy: ROUND_ROBIN
+          load_assignment:
+            cluster_name: user_api_cluster
+            endpoints:
+              - lb_endpoints:
+                  - endpoint:
+                      address:
+                        socket_address:
+                          address: user-api-svc.juwan.svc.cluster.local
+                          port_value: 8888
+          health_checks:
+            - timeout: 3s
+              interval: 10s
+              unhealthy_threshold: 2
+              healthy_threshold: 2
+              http_health_check:
+                path: /health
+
+        - name: order_api_cluster
+          connect_timeout: 5s
+          type: STRICT_DNS
+          dns_lookup_family: V4_ONLY
+          lb_policy: ROUND_ROBIN
+          load_assignment:
+            cluster_name: order_api_cluster
+            endpoints:
+              - lb_endpoints:
+                  - endpoint:
+                      address:
+                        socket_address:
+                          address: order-api-svc.juwan.svc.cluster.local
+                          port_value: 8889
+          health_checks:
+            - timeout: 3s
+              interval: 10s
+              unhealthy_threshold: 2
+              healthy_threshold: 2
+              http_health_check:
+                path: /health
+
+    admin:
+      access_log_path: /tmp/admin_access.log
+      address:
+        socket_address:
+          address: 0.0.0.0
+          port_value: 9901
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: envoy-gateway
+  namespace: juwan
+spec:
+  type: LoadBalancer
+  ports:
+    - name: http
+      port: 80
+      targetPort: 8080
+      protocol: TCP
+    - name: admin
+      port: 9901
+      targetPort: 9901
+      protocol: TCP
+  selector:
+    app: envoy-gateway
+
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: envoy-gateway
+  namespace: juwan
+  labels:
+    app: envoy-gateway
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: envoy-gateway
+  template:
+    metadata:
+      labels:
+        app: envoy-gateway
+    spec:
+      serviceAccountName: envoy-gateway
+      containers:
+        - name: envoy
+          image: envoyproxy/envoy:v1.27-latest
+          ports:
+            - name: http
+              containerPort: 8080
+            - name: admin
+              containerPort: 9901
+          volumeMounts:
+            - name: envoy-config
+              mountPath: /etc/envoy
+          readinessProbe:
+            httpGet:
+              path: /stats
+              port: 9901
+            initialDelaySeconds: 10
+            periodSeconds: 5
+          livenessProbe:
+            httpGet:
+              path: /stats
+              port: 9901
+            initialDelaySeconds: 10
+            periodSeconds: 10
+          resources:
+            requests:
+              cpu: 100m
+              memory: 128Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+
+      volumes:
+        - name: envoy-config
+          configMap:
+            name: envoy-config
+
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: envoy-gateway
+  namespace: juwan
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: envoy-gateway
+rules:
+  - apiGroups: [""]
+    resources: ["endpoints"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["discovery.k8s.io"]
+    resources: ["endpointslices"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: [""]
+    resources: ["services"]
+    verbs: ["get", "list", "watch"]
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: envoy-gateway
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: envoy-gateway
+subjects:
+  - kind: ServiceAccount
+    name: envoy-gateway
+    namespace: juwan
+
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: envoy-gateway-network-policy
+  namespace: juwan
+spec:
+  podSelector:
+    matchLabels:
+      app: envoy-gateway
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+        - namespaceSelector: {}
+      ports:
+        - protocol: TCP
+          port: 8080
+  egress:
+    - to:
+        - namespaceSelector: {}
+      ports:
+        - protocol: UDP
+          port: 53
+    - to:
+        - podSelector:
+            matchLabels:
+              app: user-api
+        - podSelector:
+            matchLabels:
+              app: order-api
+      ports:
+        - protocol: TCP
+          port: 8888
+        - protocol: TCP
+          port: 8889

deploy/k8s/envoy/envoy.yaml

@@ -1,157 +0,0 @@
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: envoy-config
-  namespace: juwan
-data:
-  envoy.yaml: |
-    static_resources:
-      listeners:
-        - name: http_listener
-          address:
-            socket_address:
-              address: 0.0.0.0
-              port_value: 8080
-          filter_chains:
-            - filters:
-                - name: envoy.filters.network.http_connection_manager
-                  typed_config:
-                    "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
-                    stat_prefix: ingress_http
-                    codec_type: AUTO
-                    route_config:
-                      name: local_route
-                      virtual_hosts:
-                        - name: gozero_services
-                          domains: ["*"]
-                          routes:
-                            - match:
-                                prefix: "/"
-                              route:
-                                cluster: user-api
-                    http_filters:
-                      - name: envoy.filters.http.lua
-                        typed_config:
-                          "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
-                          inline_code: |
-                            math.randomseed(os.time())
-
-                            local function is_safe(method)
-                              return method == "GET" or method == "HEAD" or method == "OPTIONS"
-                            end
-
-                            local function parse_cookie(cookie_header)
-                              if not cookie_header then
-                                return nil
-                              end
-                              for cookie in string.gmatch(cookie_header, "([^;]+)") do
-                                local k, v = cookie:match("^%s*([^=]+)=?(.*)$")
-                                if k == "csrf_token" then
-                                  return v
-                                end
-                              end
-                              return nil
-                            end
-
-                            local function random_token()
-                              local t = {}
-                              for i = 1, 32 do
-                                t[i] = string.format("%x", math.random(0, 15))
-                              end
-                              return table.concat(t)
-                            end
-
-                            function envoy_on_request(request_handle)
-                              local headers = request_handle:headers()
-                              local method = headers:get(":method") or ""
-                              local cookie = parse_cookie(headers:get("cookie"))
-                              local csrf_header = headers:get("x-csrf-token")
-
-                              if is_safe(method) then
-                                if not cookie then
-                                  local token = random_token()
-                                  request_handle:streamInfo():dynamicMetadata():set("csrf", "token", token)
-                                end
-                                return
-                              end
-
-                              if not cookie or not csrf_header or cookie ~= csrf_header then
-                                request_handle:respond({[":status"] = "403"}, "CSRF validation failed")
-                                return
-                              end
-                            end
-
-                            function envoy_on_response(response_handle)
-                              local md = response_handle:streamInfo():dynamicMetadata():get("csrf") or {}
-                              local token = md["token"]
-                              if token then
-                                response_handle:headers():add("set-cookie", "csrf_token=" .. token .. "; Path=/; SameSite=Strict")
-                              end
-                            end
-                      - name: envoy.filters.http.router
-                        typed_config:
-                          "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
-      clusters:
-        - name: user-api
-          connect_timeout: 2s
-          type: STRICT_DNS
-          lb_policy: ROUND_ROBIN
-          load_assignment:
-            cluster_name: user-api
-            endpoints:
-              - lb_endpoints:
-                  - endpoint:
-                      address:
-                        socket_address:
-                          address: user-api-svc.juwan.svc.cluster.local
-                          port_value: 8888
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: envoy-gateway
-  namespace: juwan
-  labels:
-    app: envoy-gateway
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: envoy-gateway
-  template:
-    metadata:
-      labels:
-        app: envoy-gateway
-    spec:
-      containers:
-        - name: envoy
-          image: envoyproxy/envoy:v1.32.2
-          args:
-            - "-c"
-            - "/etc/envoy/envoy.yaml"
-            - "--log-level"
-            - "info"
-          ports:
-            - name: http
-              containerPort: 8080
-          volumeMounts:
-            - name: config
-              mountPath: /etc/envoy
-      volumes:
-        - name: config
-          configMap:
-            name: envoy-config
----
-apiVersion: v1
-kind: Service
-metadata:
-  name: envoy-gateway
-  namespace: juwan
-spec:
-  type: ClusterIP
-  selector:
-    app: envoy-gateway
-  ports:
-    - name: http
-      port: 80
-      targetPort: 8080

deploy/k8s/secrets/DEPLOYMENT.md

@@ -0,0 +1,424 @@
+# JWT Secret + ETCD Encryption Deployment Guide
+
+完整的 JWT 认证系统部署指南，包括密钥管理、RBAC 权限控制和 ETCD 加密。
+
+## 部署顺序
+
+### 第1步：创建 Secret 和 RBAC（必需）
+
+创建 JWT 秘钥和服务账户权限：
+
+```bash
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
+```
+
+验证创建成功：
+
+```bash
+# 检查 Secret
+kubectl get secret jwt-secret -n juwan
+kubectl get secret jwt-secret -n juwan -o yaml
+
+# 检查 ServiceAccounts
+kubectl get sa user-rpc -n juwan
+kubectl get sa envoy-gateway -n juwan
+
+# 检查 RBAC 权限
+kubectl get role jwt-secret-reader -n juwan
+kubectl get rolebinding -n juwan -l app=jwt-secret-reader
+```
+
+### 第2步：更新 user-rpc 部署（依赖第1步）
+
+已自动更新 `deploy/k8s/service/user/user-rpc.yaml`：
+
+- ✅ 更新 `serviceAccountName` 从 `find-endpoints` → `user-rpc`
+- ✅ 添加环境变量 `JWT_SECRET_KEY` 从 Secret `jwt-secret` 读取
+
+应用更新：
+
+```bash
+kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
+```
+
+验证部署：
+
+```bash
+# 检查 ServiceAccount 已正确绑定
+kubectl get deployment user-rpc -n juwan -o yaml | grep -A 5 serviceAccountName
+
+# 查看 Pod 是否以 user-rpc ServiceAccount 身份运行
+kubectl get pod -n juwan -l app=user-rpc -o yaml | grep serviceAccount
+
+# 验证环境变量已注入
+kubectl exec -it POD_NAME -n juwan -- env | grep JWT_SECRET_KEY
+```
+
+### 第3步：更新 Envoy 网关部署（依赖第1步）
+
+已自动更新 `deploy/k8s/envoy/envoy.yaml`：
+
+- ✅ 添加 `serviceAccountName: envoy-gateway` 到 Deployment spec
+
+应用更新：
+
+```bash
+kubectl apply -f deploy/k8s/envoy/envoy.yaml
+```
+
+验证部署：
+
+```bash
+# 检查 ServiceAccount 已正确绑定
+kubectl get deployment envoy-gateway -n juwan -o yaml | grep -A 2 serviceAccountName
+
+# 检查 Pod 状态
+kubectl get pod -n juwan -l app=envoy-gateway
+```
+
+### 第4步：启用 ETCD 加密（强烈推荐用于生产环境）
+
+这是一个集群级别的配置，需要在 Kubernetes 控制平面节点上执行。
+
+**前提条件：**
+- 具有 Kubernetes 集群管理员权限
+- 可以访问控制平面节点
+- 备份 ETCD 数据库
+
+**步骤：**
+
+1. **生成加密密钥**
+   ```bash
+   head -c 32 /dev/urandom | base64
+   ```
+   记录输出的 Base64 密钥。
+
+2. **创建加密配置文件**
+   
+   在控制平面节点上，创建 `/etc/kubernetes/encryption-config.yaml`：
+
+   ```yaml
+   apiVersion: apiserver.config.k8s.io/v1
+   kind: EncryptionConfiguration
+   resources:
+     - resources:
+         - secrets
+       providers:
+         - aescbc:
+             keys:
+               - name: key1
+                 secret: <BASE64_ENCODED_32_BYTE_KEY>
+         - identity: {}
+   ```
+
+   替换 `<BASE64_ENCODED_32_BYTE_KEY>` 为第1步生成的密钥。
+
+3. **修改 kube-apiserver 配置**
+   
+   在控制平面节点上，编辑 `/etc/kubernetes/manifests/kube-apiserver.yaml`：
+
+   **添加参数：**
+   ```yaml
+   spec:
+     containers:
+     - name: kube-apiserver
+       command:
+         - kube-apiserver
+         - --encryption-provider-config=/etc/kubernetes/encryption-config.yaml
+   ```
+
+   **添加卷挂载：**
+   ```yaml
+   spec:
+     containers:
+     - name: kube-apiserver
+       volumeMounts:
+       - name: encryption-config
+         mountPath: /etc/kubernetes
+         readOnly: true
+   
+   volumes:
+   - name: encryption-config
+     hostPath:
+       path: /etc/kubernetes
+       type: DirectoryOrCreate
+   ```
+
+4. **重启 kube-apiserver**
+   
+   修改清单后，kubelet 会自动重启 kube-apiserver。检查状态：
+   
+   ```bash
+   # 在控制平面节点
+   kubectl get pods -n kube-system | grep kube-apiserver
+   
+   # 监控重启过程
+   kubectl logs -n kube-system -l component=kube-apiserver -f
+   ```
+
+5. **验证加密是否启用**
+   
+   创建一个新 Secret 并检查它在 ETCD 中是否加密：
+   
+   ```bash
+   # 创建测试 Secret
+   kubectl create secret generic test-secret -n juwan --from-literal=key=value
+   
+   # 从 control plane 节点检查 ETCD 数据
+   # 如果数据不可读并包含加密标记，说明加密已启用
+   ```
+
+6. **保存加密密钥**
+   
+   ⚠️ **关键：将加密密钥安全地保存在离线存储中**
+   - 密钥丢失后，无法解密 ETCD 中的数据
+   - 无法恢复任何 Secrets
+   - 建议用密码管理工具（如 HashiCorp Vault）或 HSM 存储密钥
+
+### 第5步：验证整个系统
+
+完整的验证清单：
+
+```bash
+# 检查所有 Secrets 已创建
+kubectl get secret -n juwan
+kubectl get secret jwt-secret -n juwan -o jsonpath='{.data.secret-key}' | base64 -d
+
+# 检查 ServiceAccounts 已创建
+kubectl get sa -n juwan
+kubectl describe sa user-rpc -n juwan
+kubectl describe sa envoy-gateway -n juwan
+
+# 检查 RBAC 权限
+kubectl get role -n juwan
+kubectl get rolebinding -n juwan
+kubectl describe role jwt-secret-reader -n juwan
+
+# 测试权限：user-rpc 可以读 jwt-secret
+kubectl auth can-i get secrets --as=system:serviceaccount:juwan:user-rpc --resource-name=jwt-secret -n juwan
+
+# 测试权限：envoy-gateway 可以读 jwt-secret
+kubectl auth can-i get secrets --as=system:serviceaccount:juwan:envoy-gateway --resource-name=jwt-secret -n juwan
+
+# 测试权限：其他 ServiceAccount 无法读取
+kubectl auth can-i get secrets --as=system:serviceaccount:juwan:other-service -n juwan
+
+# 检查 Deployments 已正确配置
+kubectl get deployment user-rpc -n juwan -o yaml | grep -A 2 serviceAccountName
+kubectl get deployment envoy-gateway -n juwan -o yaml | grep -A 2 serviceAccountName
+
+# 检查 Pods 是否已启动并运行
+kubectl get pods -n juwan -l app=user-rpc
+kubectl get pods -n juwan -l app=envoy-gateway
+
+# 查看 JWT Secret 是否已挂载到 Pod
+kubectl exec -it $(kubectl get pod -n juwan -l app=user-rpc -o name | head -1) -n juwan -- env | grep JWT_SECRET_KEY
+```
+
+## 监控和日志
+
+### 查看 Pod 日志
+
+```bash
+# user-rpc 日志
+kubectl logs -n juwan -l app=user-rpc -f --all-containers=true
+
+# Envoy 日志
+kubectl logs -n juwan -l app=envoy-gateway -f
+```
+
+### 检查 Pod 事件
+
+```bash
+# 查看 Pod 创建和启动事件
+kubectl describe pod -n juwan -l app=user-rpc
+kubectl describe pod -n juwan -l app=envoy-gateway
+```
+
+### 权限问题排查
+
+如果 Pod 无法读取 Secret：
+
+```bash
+# 检查 Pod 使用的 ServiceAccount
+kubectl get pod POD_NAME -n juwan -o yaml | grep serviceAccountName
+
+# 检查 RBAC 绑定
+kubectl get rolebinding -n juwan -o wide
+
+# 检查 Role 权限定义
+kubectl get role jwt-secret-reader -n juwan -o yaml
+
+# 尝试用 Pod 的身份读取 Secret（需要 kubectl-user-impersonate 或类似工具）
+kubectl get secret jwt-secret --as=system:serviceaccount:juwan:user-rpc -n juwan
+```
+
+## 安全最佳实践
+
+### 1. 密钥轮换
+
+周期性更换 JWT 秘钥（建议每季度）：
+
+```bash
+# 1. 生成新密钥
+NEW_KEY=$(head -c 32 /dev/urandom | base64)
+
+# 2. 更新 Secret
+kubectl create secret generic jwt-secret \
+  --from-literal=secret-key=$NEW_KEY \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+# 3. 重启 Pods 以加载新密钥（滚动更新）
+kubectl rollout restart deployment/user-rpc -n juwan
+kubectl rollout restart deployment/envoy-gateway -n juwan
+
+# 4. 验证新 Pods 已启动并运行
+kubectl rollout status deployment/user-rpc -n juwan
+kubectl rollout status deployment/envoy-gateway -n juwan
+
+# 5. 已颁发的旧令牌将变为无效
+# 需要用户重新登录获取新令牌
+```
+
+### 2. 审计和监控
+
+在生产环境中启用 Kubernetes 审计日志来跟踪 Secret 访问：
+
+```yaml
+# kube-apiserver 审计策略示例
+apiVersion: audit.k8s.io/v1
+kind: Policy
+rules:
+  # 记录 secret 资源的访问
+  - level: RequestResponse
+    verbs: ["get", "list", "watch"]
+    resources: ["secrets"]
+  # 记录所有认证失败
+  - level: RequestResponse
+    omitStages:
+      - RequestReceived
+    userGroups: ["system:unauthenticated"]
+  - level: Metadata
+    omitStages:
+      - RequestReceived
+```
+
+### 3. 网络策略
+
+使用 NetworkPolicy 限制 Pods 之间的通信：
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: jwt-secret-access
+  namespace: juwan
+spec:
+  podSelector:
+    matchLabels:
+      app: jwt-secret-reader
+  policyTypes:
+    - Ingress
+  ingress:
+    - from:
+        - podSelector:
+            matchLabels:
+              app: user-rpc
+        - podSelector:
+            matchLabels:
+              app: envoy-gateway
+      ports:
+        - protocol: TCP
+          port: 443  # API Server
+```
+
+## 灾难恢复
+
+### 备份 Secret 和 RBAC 配置
+
+```bash
+# 备份 JWT Secret
+kubectl get secret jwt-secret -n juwan -o yaml > jwt-secret-backup.yaml
+
+# 备份 RBAC 配置
+kubectl get role jwt-secret-reader -n juwan -o yaml > jwt-role-backup.yaml
+kubectl get rolebinding -n juwan -l app=jwt-secret-reader -o yaml > jwt-rolebinding-backup.yaml
+
+# 加密备份文件
+gpg --symmetric jwt-secret-backup.yaml
+```
+
+### 恢复步骤
+
+如果 Secret 被意外删除：
+
+```bash
+# 从备份恢复
+kubectl apply -f jwt-secret-backup.yaml
+
+# 重启 Pods 以重新加载 Secret
+kubectl rollout restart deployment/user-rpc -n juwan
+kubectl rollout restart deployment/envoy-gateway -n juwan
+```
+
+## 常见问题
+
+### Q: Pod 无法启动，显示 "failed to pull secret"
+
+A: 检查：
+1. Secret 是否存在：`kubectl get secret jwt-secret -n juwan`
+2. ServiceAccount 是否绑定了 RBAC：`kubectl describe rolebinding -n juwan`
+3. Secret 名称和命名空间是否正确
+
+### Q: 加密后如何验证 ETCD 中的数据已加密？
+
+A: 从 control plane 节点：
+```bash
+# 直接读取 ETCD（如果配置了加密，数据应该不可读）
+sudo strings /var/lib/etcd/member/snap/db | grep -i secret
+```
+
+### Q: 能否更改加密密钥而不重新创建 ETCD？
+
+A: 可以，但流程复杂：
+1. 更新 encryption-config.yaml 中的新密钥
+2. 将新密钥添加到提供程序列表（保持旧密钥）
+3. 重启 kube-apiserver
+4. 触发重新加密：`kubectl get all --all-namespaces -o json | kubectl apply -f -`
+
+### Q: 如何在 Minikube 中启用 ETCD 加密？
+
+A: 参考 `ENCRYPTION.md` 中的 Minikube 特定说明部分。
+
+## 相关文件
+
+- `jwt-secret.yaml` - Secret 和 RBAC 配置
+- `ENCRYPTION.md` - ETCD 加密详细文档
+- `README.md` - 快速参考指南
+- `/deploy/k8s/service/user/user-rpc.yaml` - user-rpc Deployment 配置
+- `/deploy/k8s/envoy/envoy.yaml` - Envoy 网关 Deployment 配置
+
+## 下一步
+
+部署完成后：
+
+1. **集成 JWT 验证到 RPC Handlers**
+   - 实现 gRPC unary interceptor
+   - 验证令牌有效性
+   - 处理令牌刷新逻辑
+
+2. **集成 JWT 验证到 Envoy**
+   - 扩展 Lua filter 进行令牌验证
+   - 返回 401（无效令牌）或 200（有效令牌）
+
+3. **端到端测试**
+   - 创建用户和登录
+   - 生成和验证 JWT
+   - 测试令牌刷新和撤销
+   - 验证 ETCD 加密
+
+4. **生产部署**
+   - 启用审计日志
+   - 配置密钥轮换计划
+   - 建立备份和恢复流程
+   - 监控 Secret 访问

deploy/k8s/secrets/ENCRYPTION.md

@@ -0,0 +1,129 @@
+# ETCD Encryption Configuration for Kubernetes
+
+To enable static encryption at rest for Kubernetes secrets in ETCD, you need to configure the API Server with an EncryptionConfiguration.
+
+## 1. Generate an Encryption Key
+
+```bash
+# Generate a 32-byte base64-encoded key
+head -c 32 /dev/urandom | base64
+# Example output: sxFdbKYquCe3EbRWVV+pFe2lS8K8hbiv3V8ExQZ0fD4=
+```
+
+## 2. Create EncryptionConfiguration File
+
+Create `/etc/kubernetes/encryption-config.yaml` on the control plane node:
+
+```yaml
+apiVersion: apiserver.config.k8s.io/v1
+kind: EncryptionConfiguration
+resources:
+  - resources:
+      - secrets
+    providers:
+      - aescbc:
+          keys:
+            - name: key1
+              secret: sxFdbKYquCe3EbRWVV+pFe2lS8K8hbiv3V8ExQZ0fD4=
+      - identity: {}
+```
+
+## 3. Update kube-apiserver Static Pod Manifest
+
+Edit `/etc/kubernetes/manifests/kube-apiserver.yaml` on the control plane node:
+
+```yaml
+spec:
+  containers:
+  - name: kube-apiserver
+    command:
+    - kube-apiserver
+    # ... existing flags ...
+    - --encryption-provider-config=/etc/kubernetes/encryption-config.yaml
+    volumeMounts:
+    - name: encryption-config
+      mountPath: /etc/kubernetes
+      readOnly: true
+  volumes:
+  - name: encryption-config
+    hostPath:
+      path: /etc/kubernetes
+      type: DirectoryOrCreate
+```
+
+## 4. Verify Encryption is Working
+
+```bash
+# After restarting the API server, create a secret and verify it's encrypted
+kubectl create secret generic test-secret --from-literal=key=value -n juwan
+
+# Check if the secret is encrypted in etcd
+kubectl get secret test-secret -o yaml
+
+# You can also check raw etcd data (requires etcd access):
+# etcdctl --endpoints=https://127.0.0.1:2379 get /kubernetes.io/secrets/juwan/test-secret
+# The data should be encrypted (not human-readable)
+```
+
+## 5. Important Notes
+
+- **Backup your encryption key** in a secure location
+- **Never commit encryption keys** to version control
+- If you lose the key, all encrypted secrets will be unrecoverable
+- After enabling encryption, existing unencrypted secrets will not be automatically encrypted
+  - To encrypt existing secrets, you can use: `kubectl delete secret <name> && kubectl create secret ...`
+  - Or use: `kubectl patch secret <name> -p '{}' --type=merge` (triggers re-encryption)
+
+## 6. RBAC Configuration for JWT Secret
+
+The `jwt-secret.yaml` includes RBAC rules that:
+- Create a `jwt-secret` Secret in the `juwan` namespace
+- Create ServiceAccounts for `user-rpc` and `envoy-gateway`
+- Create a Role `jwt-secret-reader` that allows reading only the `jwt-secret` Secret
+- Bind this Role to both ServiceAccounts via RoleBindings
+
+This ensures:
+- Only `user-rpc` and `envoy-gateway` Pods can read the JWT secret
+- Other services and users cannot access the JWT secret
+- Least privilege access principle is enforced
+
+## 7. Update Deployment to Use ServiceAccount
+
+Make sure your Deployment references the ServiceAccount:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: user-rpc
+  namespace: juwan
+spec:
+  template:
+    spec:
+      serviceAccountName: user-rpc  # This is important!
+      containers:
+      - name: user-rpc
+        env:
+        - name: JWT_SECRET_KEY
+          valueFrom:
+            secretKeyRef:
+              name: jwt-secret
+              key: secret-key
+```
+
+## 8. For Minikube Users
+
+If using Minikube, you can enable encryption with:
+
+```bash
+minikube config set apiserver.encryption-provider-config /path/to/encryption-config.yaml
+minikube start
+```
+
+Or manually edit the kube-apiserver manifest after starting Minikube:
+
+```bash
+minikube ssh
+sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml
+# Add the flags and volume mounts as shown above
+```

deploy/k8s/secrets/FLOWCHART.md

@@ -0,0 +1,415 @@
+# 部署流程图和时间线
+
+## 部署架构流程图
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│        JWT 认证系统部署流程                                       │
+└──────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 1: 前置检查 (5分钟)                                           │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  ✓ Kubernetes 集群版本 >= 1.24                                     │
+│  ✓ kubectl 已配置，可访问集群                                       │
+│  ✓ juwan namespace 已存在                                          │
+│  ✓ redis-operator CRD 已安装                                       │
+│  ✓ 集群管理员权限（用于 ETCD 加密）                                 │
+│                                                                     │
+│  命令检查:                                                          │
+│  $ kubectl cluster-info                                            │
+│  $ kubectl get ns juwan                                            │
+│  $ kubectl get crd redisclusters.redis.redis.opstreelabs.in       │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 2: 创建 Secret 和 RBAC (5分钟)  ⚡ 必需                       │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  执行:                                                              │
+│  $ kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml             │
+│                                                                     │
+│  创建的资源:                                                        │
+│  ✓ 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                    │
+│                                                                     │
+│  验证:                                                              │
+│  $ kubectl get secret jwt-secret -n juwan                          │
+│  $ kubectl get sa -n juwan | grep -E "user-rpc|envoy"              │
+│  $ kubectl get role -n juwan                                       │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 3: 更新 Deployments (10分钟) ⚡ 必需                         │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Step 3a: 更新 user-rpc Deployment                                 │
+│  执行:                                                              │
+│  $ kubectl apply -f deploy/k8s/service/user/user-rpc.yaml          │
+│                                                                     │
+│  变更:                                                              │
+│  - serviceAccountName: user-rpc (绑定权限)                         │
+│  - env.JWT_SECRET_KEY (从 Secret 挂载)                             │
+│  - 保持 Redis Cluster 配置                                         │
+│                                                                     │
+│  等待 Pods 启动:                                                    │
+│  $ kubectl rollout status deployment/user-rpc -n juwan             │
+│                                                                     │
+│  ---                                                               │
+│                                                                     │
+│  Step 3b: 更新 Envoy Gateway Deployment                            │
+│  执行:                                                              │
+│  $ kubectl apply -f deploy/k8s/envoy/envoy.yaml                    │
+│                                                                     │
+│  变更:                                                              │
+│  - serviceAccountName: envoy-gateway (绑定权限)                    │
+│  - 保持 CSRF Lua 防护配置                                          │
+│                                                                     │
+│  等待 Pods 启动:                                                    │
+│  $ kubectl rollout status deployment/envoy-gateway -n juwan        │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 4: 验证部署 (15分钟) ⚡ 必需                                  │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  检查清单:                                                          │
+│                                                                     │
+│  1️⃣  Secret 和权限验证                                             │
+│  $ kubectl get secret jwt-secret -n juwan                          │
+│  $ kubectl get role jwt-secret-reader -n juwan                     │
+│  $ kubectl get rolebinding -n juwan | grep jwt-secret              │
+│                                                                     │
+│  2️⃣  权限测试                                                      │
+│  $ kubectl auth can-i get secrets \                                │
+│    --as=system:serviceaccount:juwan:user-rpc \                     │
+│    --resource-name=jwt-secret -n juwan                             │
+│  预期: yes                                                         │
+│                                                                     │
+│  3️⃣  Pods 运行状态                                                │
+│  $ kubectl get pods -n juwan -l app=user-rpc                       │
+│  $ kubectl get pods -n juwan -l app=envoy-gateway                  │
+│  预期: 3 个 user-rpc Pods + 1 个 envoy-gateway Pod 都在 Running   │
+│                                                                     │
+│  4️⃣  环境变量验证                                                  │
+│  $ kubectl exec -it <user-rpc-pod> -n juwan -- env | grep JWT      │
+│  预期: JWT_SECRET_KEY=...                                          │
+│                                                                     │
+│  5️⃣  Redis 连接验证                                               │
+│  $ kubectl run redis-cli --image=redis:latest --rm -it \           │
+│    -- redis-cli -h user-redis.juwan:6379 PING                     │
+│  预期: PONG                                                        │
+│                                                                     │
+│  详见: VERIFICATION.md 第1-8部分                                    │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ├─────────── 生产环境额外步骤 ──────────────┐
+        │                                          │
+        ▼                                          ▼
+┌──────────────────────────┐   ┌─────────────────────────────────────┐
+│ Phase 5a: 应用集成       │   │ Phase 5b: 启用 ETCD 加密 (30分钟)  │
+│ (2-3 小时) ⚠️  推荐      │   │ ⚠️ 生产推荐，需集群管理员权限       │
+├──────────────────────────┤   ├─────────────────────────────────────┤
+│                          │   │                                     │
+│ 实施内容:                │   │ 前提条件:                          │
+│ ✓ gRPC Interceptor       │   │ ✓ Control Plane 节点访问权限       │
+│ ✓ Login/Logout Handler   │   │ ✓ ETCD 备份已创建                  │
+│ ✓ JWT Middleware         │   │ ✓ 加密密钥已生成                  │
+│ ✓ Token Refresh Logic    │   │                                     │
+│ ✓ Error Handling         │   │ 步骤:                              │
+│ ✓ Unit Tests             │   │ 1. 生成 32 字节密钥                │
+│                          │   │    $ head -c 32 /dev/urandom | base64
+│ 参考:                     │   │                                     │
+│ INTEGRATION.md           │   │ 2. 创建加密配置文件                │
+│                          │   │    /etc/kubernetes/encryption-config.yaml
+│ 时间估计:                │   │                                     │
+│ - gRPC 拦截器: 30分钟   │   │ 3. 修改 kube-apiserver manifest    │
+│ - Handlers: 60分钟       │   │    添加密钥路径和卷挂载             │
+│ - Middleware: 30分钟     │   │                                     │
+│ - 测试: 60分钟           │   │ 4. 重启 kube-apiserver             │
+│                          │   │    kubelet 自动重启                 │
+│                          │   │                                     │
+│                          │   │ 5. 验证加密已启用                  │
+│                          │   │    kubectl create secret generic ... │
+│                          │   │    检查 ETCD 中的数据是否加密       │
+│                          │   │                                     │
+│                          │   │ 详见: ENCRYPTION.md (8个部分)      │
+│                          │   │ 验证: VERIFICATION.md 第9部分       │
+│                          │   │                                     │
+└──────────────────────────┘   └─────────────────────────────────────┘
+        │                                          │
+        └───────────────────┬─────────────────────┘
+                            │
+                            ▼
+        ┌──────────────────────────────────────────┐
+        │ Phase 6: 完成 ✅                          │
+        ├──────────────────────────────────────────┤
+        │                                          │
+        │ 最终检查:                                │
+        │ ✓ 所有 Pods 运行正常                     │
+        │ ✓ RBAC 权限已验证                        │
+        │ ✓ JWT 功能已集成                         │
+        │ ✓ 日志和监控已配置                       │
+        │ ✓ (可选) ETCD 加密已启用                 │
+        │                                          │
+        │ 生产推荐:                                │
+        │ ✓ 启用审计日志                           │
+        │ ✓ 配置密钥轮换计划（季度）              │
+        │ ✓ 备份密钥到安全位置                     │
+        │ ✓ 配置告警和监控                         │
+        │                                          │
+        └──────────────────────────────────────────┘
+```
+
+## 时间估计和路径
+
+```
+推荐部署路径
+═════════════════════════════════════════════════════════════════
+
+🚀 最快路径 (30 分钟) - 开发环境
+────────────────────────────────────────────────────────────────
+Phase 1: 前置检查                        ⏱️ 5 分钟
+Phase 2: 创建 Secret 和 RBAC              ⏱️ 5 分钟  
+Phase 3: 更新 Deployments                ⏱️ 10 分钟
+Phase 4: 验证部署                        ⏱️ 10 分钟
+────────────────────────────────────────────────────────────────
+                                         总计: 30 分钟
+
+
+📊 默认路径 (75 分钟) - 测试环境
+────────────────────────────────────────────────────────────────
+Phase 1-4: 如上                          ⏱️ 30 分钟
+Phase 5a: 应用集成（简单版）             ⏱️ 45 分钟
+────────────────────────────────────────────────────────────────
+                                         总计: 75 分钟
+
+
+🏆 完整路径 (3.5-4 小时) - 生产环境
+────────────────────────────────────────────────────────────────
+Phase 1-4: 如上                          ⏱️ 30 分钟
+Phase 5a: 应用集成（完整版）             ⏱️ 2-3 小时
+Phase 5b: ETCD 加密配置                  ⏱️ 30 分钟
+────────────────────────────────────────────────────────────────
+                                         总计: 3.5-4 小时
+
+
+📚 学习路径 (6-8 小时) - 从零开始理解
+────────────────────────────────────────────────────────────────
+文档阅读 (SUMMARY + DEPLOYMENT + INTEGRATION)  ⏱️ 1-2 小时
+完整路径部署                             ⏱️ 3.5-4 小时
+验证和测试                                ⏱️ 1-2 小时
+────────────────────────────────────────────────────────────────
+                                         总计: 6-8 小时
+```
+
+## 并行和串行步骤
+
+```
+可以并行执行的任务
+═════════════════════════════════════════════════════════════════
+
+┌─────────────────────────────────┐
+│ 应用集成 (Phase 5a)             │ ────┐
+├─────────────────────────────────┤    │ 可选，独立
+│ • gRPC interceptor               │    │ 进行
+│ • REST middleware                │    │
+│ • Handler 实现                   │    │
+│ • 单元测试                       │    │
+└─────────────────────────────────┘    │
+                                      ├─ 与 Phase 2-4 并行
+                                      │
+┌─────────────────────────────────┐    │
+│ ETCD 加密 (Phase 5b)            │ ────┘
+├─────────────────────────────────┤    │ 需要集群管理员
+│ • 生成密钥（可单独进行）         │    │ 权限，在
+│ • 创建配置文件                  │    │ Control Plane
+│ • 修改 kube-apiserver           │    │ 节点执行
+│ • 重启 API server               │    │
+└─────────────────────────────────┘────┘
+
+
+必须串行执行的步骤
+═════════════════════════════════════════════════════════════════
+
+Phase 1 → Phase 2 → Phase 3 → Phase 4 → (Phase 5a + Phase 5b)
+  
+  ↓       ↓        ↓        ↓
+前置检查  创建资源  部署应用  验证完整  可选扩展功能
+  
+• Phase 2 必须在 Phase 1 之后（需要 namespace）
+• Phase 3 必须在 Phase 2 之后（需要 RoleBinding）
+• Phase 4 必须在 Phase 3 之后（需要 Pods 启动）
+• Phase 5a/5b 可在 Phase 4 完成后并行进行
+```
+
+## 关键时间点
+
+```
+事件时间线
+═════════════════════════════════════════════════════════════════
+
+T+0      Phase 1: 验证前置条件
+         └─ 预计 5 分钟
+         
+T+5      Phase 2: kubectl apply jwt-secret.yaml
+         └─ 预计 1 分钟执行，5 分钟验证
+         
+T+11     Phase 3a: kubectl apply user-rpc.yaml
+         └─ 3 个 Pods 启动（滚动更新）
+         └─ 预计 ~3 分钟（取决于镜像拉取）
+         
+T+14     Phase 3b: kubectl apply envoy.yaml
+         └─ 1 个 Pod 启动
+         └─ 预计 ~2 分钟
+         
+T+16     Phase 4: 执行完整验证检查
+         └─ 12 个验证部分，共 ~15 分钟
+
+T+31     ✅ 基础部署完成
+
+T+31     (可选) Phase 5a: 应用代码集成
+到       └─ 2-3 小时编码和测试
+T+211    
+
+T+31     (可选) Phase 5b: ETCD 加密
+到       └─ 30 分钟配置
+T+61     
+
+T+211 或 T+61  🎉 全部完成
+(取决于是否执行 Phase 5)
+```
+
+## 推荐的部署顺序
+
+### 对于 DevOps/SRE
+
+```
+优先级顺序:
+
+1️⃣ Phase 1-4 (核心部署)  [必需]
+   └─ 时间: 30 分钟
+   
+2️⃣ Phase 5b (ETCD 加密)  [生产强烈推荐]
+   └─ 时间: 30 分钟
+   └─ 开始时间: T+16 之前 (与 Phase 4 并行)
+   
+3️⃣ 密钥备份和恢复计划    [重要]
+   └─ 时间: 15 分钟
+   └─ 参考: DEPLOYMENT.md 灾难恢复
+   
+4️⃣ Phase 5a 支持          [当开发完成时]
+   └─ 协助开发团队集成 JWT
+   └─ 参考: INTEGRATION.md
+```
+
+### 对于应用开发者
+
+```
+优先级顺序:
+
+1️⃣ 了解系统架构           [了解背景]
+   └─ 文档: SUMMARY.md
+   └─ 时间: 10 分钟
+   
+2️⃣ Phase 5a: 代码集成     [并行进行]
+   └─ 参考: INTEGRATION.md
+   └─ 时间: 2-3 小时
+   
+3️⃣ 单元测试                [在开发中]
+   └─ 参考: INTEGRATION.md 第 9 部分
+   └─ 时间: 1 小时
+   
+4️⃣ 集成测试                [与运维协调]
+   └─ 测试完整流程
+   └─ 时间: 1-2 小时
+```
+
+## 回滚应急步骤
+
+如果部署失败，可以快速回滚：
+
+```
+紧急回滚
+═════════════════════════════════════════════════════════════════
+
+如果 Phase 2 (Secret) 失败:
+→ kubectl delete secret jwt-secret -n juwan
+→ kubectl delete sa user-rpc envoy-gateway -n juwan
+→ kubectl delete role jwt-secret-reader -n juwan
+→ 修正配置后重新应用
+
+如果 Phase 3 (Deployment) 失败:
+→ kubectl rollout undo deployment/user-rpc -n juwan
+→ kubectl rollout undo deployment/envoy-gateway -n juwan
+→ 或删除部署并使用稳定的旧版本重新部署
+
+如果 Phase 5b (ETCD 加密) 失败:
+→ 从 kube-apiserver 清单中移除加密参数
+→ 重启 kube-apiserver
+→ 删除 /etc/kubernetes/encryption-config.yaml
+→ 从最近的 ETCD 备份恢复（如果需要）
+
+注意: 备份是关键！每次重大操作前都应备份。
+```
+
+## 部署检查点 (Go/No-Go)
+
+```
+关键检查点
+═════════════════════════════════════════════════════════════════
+
+✅ Checkpoint 1 (Phase 2 后)
+   - Secret 已创建
+   - ServiceAccounts 已创建
+   - Go → 继续 Phase 3
+   - No-Go → 检查 kubectl 权限
+
+✅ Checkpoint 2 (Phase 3 后)
+   - Pods 已启动 (Running)
+   - No PodSchedulingFailure
+   - Go → 继续 Phase 4
+   - No-Go → 检查资源限制和镜像拉取
+
+✅ Checkpoint 3 (Phase 4 权限测试)
+   - user-rpc 可以读 jwt-secret
+   - envoy-gateway 可以读 jwt-secret
+   - 其他 SA 无法读取
+   - Go → 继续 Phase 5
+   - No-Go → 检查 RBAC 配置
+
+✅ Checkpoint 4 (Phase 4 Redis 连接)
+   - Redis Cluster 健康 (3/3 nodes)
+   - PING 返回 PONG
+   - Go → 继续应用集成
+   - No-Go → 检查 Redis Pods 和网络
+
+✅ Checkpoint 5 (Phase 5b - ETCD 加密)
+   - 新创建的 Secret 在 ETCD 中已加密
+   - Go → 生产就绪
+   - No-Go → 检查 kube-apiserver 配置参数
+```
+
+---
+
+## 使用这个流程图
+
+1. **首次部署** → 从 "推荐部署路径" 选择合适的版本
+2. **卡在某一步** → 查看对应的 Phase 描述和命令
+3. **估算时间** → 查看 "时间估计和路径" 部分
+4. **需要回滚** → 参考 "回滚应急步骤"
+5. **检查进度** → 使用 "部署检查点"
+
+详细的部署步骤见：[DEPLOYMENT.md](./DEPLOYMENT.md)

deploy/k8s/secrets/INDEX.md

@@ -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 分钟 |

deploy/k8s/secrets/QUICK_REFERENCE.md

@@ -0,0 +1,350 @@
+# JWT + ETCD 加密系统 - 快速参考卡片
+
+## 一页速查表
+
+### 部署命令
+
+```bash
+# 创建 Secret 和 RBAC
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
+
+# 更新 Deployments
+kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
+kubectl apply -f deploy/k8s/envoy/envoy.yaml
+
+# 验证部署
+kubectl get secret jwt-secret -n juwan
+kubectl get sa user-rpc envoy-gateway -n juwan
+kubectl get role jwt-secret-reader -n juwan
+kubectl get pods -n juwan -l app=user-rpc
+kubectl get pods -n juwan -l app=envoy-gateway
+```
+
+### 权限验证
+
+```bash
+# user-rpc 可以读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  --resource-name=jwt-secret -n juwan
+# 预期: yes
+
+# 其他 SA 无法读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:default \
+  --resource-name=jwt-secret -n juwan
+# 预期: no
+```
+
+### 日志查看
+
+```bash
+# user-rpc 日志
+kubectl logs -n juwan -l app=user-rpc -f
+
+# Envoy 日志
+kubectl logs -n juwan -l app=envoy-gateway -f
+
+# 特定 Pod 日志
+kubectl logs -n juwan <pod-name> --all-containers=true -f
+```
+
+### 环境变量验证
+
+```bash
+# 检查 JWT_SECRET_KEY 已注入
+kubectl exec -it $(kubectl get pod -n juwan -l app=user-rpc -o name | head -1) \
+  -n juwan -- env | grep JWT_SECRET_KEY
+```
+
+### Redis 验证
+
+```bash
+# 连接到 Redis Cluster
+kubectl run redis-cli --image=redis:latest --rm -it --restart=Never -- \
+  redis-cli -h user-redis.juwan:6379 -c CLUSTER INFO
+
+# 测试键操作
+kubectl run redis-cli --image=redis:latest --rm -it --restart=Never -- \
+  redis-cli -h user-redis.juwan:6379 -c GET jwt:user:test-user-id
+```
+
+### ETCD 加密配置
+
+```bash
+# 1. 在 Control Plane 节点生成密钥
+head -c 32 /dev/urandom | base64
+
+# 2. 编辑 kube-apiserver 清单
+sudo nano /etc/kubernetes/manifests/kube-apiserver.yaml
+
+# 添加参数:
+--encryption-provider-config=/etc/kubernetes/encryption-config.yaml
+
+# 3. 创建加密配置文件
+cat <<EOF | sudo tee /etc/kubernetes/encryption-config.yaml
+apiVersion: apiserver.config.k8s.io/v1
+kind: EncryptionConfiguration
+resources:
+  - resources:
+      - secrets
+    providers:
+      - aescbc:
+          keys:
+            - name: key1
+              secret: <BASE64_KEY>
+      - identity: {}
+EOF
+
+# 4. 验证加密
+kubectl create secret generic test-encryption -n juwan --from-literal=key=value
+sudo ETCDCTL_API=3 etcdctl --cert=/etc/kubernetes/pki/etcd/server.crt \
+  --key=/etc/kubernetes/pki/etcd/server.key \
+  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
+  --endpoints=127.0.0.1:2379 \
+  get /registry/secrets/juwan/test-encryption | od -A x -t x1z
+```
+
+### 故障排查
+
+```bash
+# Pod 无法启动？查看事件
+kubectl describe pod <pod-name> -n juwan
+
+# 权限被拒绝？检查 RBAC
+kubectl get rolebinding -n juwan -o wide
+kubectl describe rolebinding jwt-secret-reader-user-rpc -n juwan
+
+# 无法挂载 Secret？检查 Secret 存在性
+kubectl get secret jwt-secret -n juwan -o yaml
+
+# Redis 连接错误？测试连通性
+kubectl exec -it <user-rpc-pod> -n juwan -- \
+  redis-cli -h user-redis.juwan:6379 PING
+```
+
+## JWT Manager API 速查
+
+### JwtManager 方法
+
+```go
+// 生成新令牌
+token, err := svcCtx.JwtManager.New(ctx, userID, email, name)
+
+// 验证令牌
+claims, err := svcCtx.JwtManager.Valid(ctx, token)
+
+// 刷新令牌（如果过期但 Redis 仍有数据）
+newToken, err := svcCtx.JwtManager.Renew(ctx, token)
+
+// 提取声明（不验证签名）
+claims, err := svcCtx.JwtManager.Extract(ctx, token)
+
+// 检查令牌是否存在于 Redis
+exists, err := svcCtx.JwtManager.Exists(ctx, token)
+
+// 撤销令牌（登出）
+err := svcCtx.JwtManager.Revoke(ctx, userID, token)
+
+// 获取用户当前令牌
+token, err := svcCtx.JwtManager.GetUserToken(ctx, userID)
+
+// 将声明转换为载荷
+payload := svcCtx.JwtManager.ClaimsToPayload(claims)
+```
+
+## 配置文件位置
+
+| 配置 | 位置 | 关键参数 |
+|-----|------|--------|
+| JWT Secret | `deploy/k8s/secrets/jwt-secret.yaml` | `secret-key` |
+| user-rpc 配置 | `app/users/rpc/etc/pb.yaml` | `JWT.SecretKey`, `REDIS_HOST` |
+| Envoy 配置 | `deploy/k8s/envoy/envoy.yaml` | CSRF 验证 Lua 代码 |
+| ETCD 加密 | `/etc/kubernetes/encryption-config.yaml`（Control Plane） | `secret` (32字节密钥) |
+
+## 关键参数速查
+
+```yaml
+# JWT 令牌有效期
+Token Exp: 7 days
+
+# Redis 存储 TTL
+Redis TTL: 30 days
+
+# 可刷新时间窗口
+Refresh Window: 30 days - 7 days = 23 days
+
+# CSRF Token 位置
+Cookie: csrf_token=...
+Header: X-CSRF-Token: ...
+
+# ETCD 加密算法
+Algorithm: AES-CBC
+Key Size: 256 bits (32 bytes)
+Encoding: Base64
+
+# Secret 挂载方式
+Method: volumeMount (read-only)
+或
+Method: valueFrom.secretKeyRef
+```
+
+## 常见问题速查
+
+| 问题 | 排查命令 | 解决方案 |
+|-----|--------|--------|
+| Pod 无法启动 | `kubectl describe pod` | 检查 Secret/RBAC |
+| 权限被拒绝 | `kubectl auth can-i get secrets` | 验证 RBAC 绑定 |
+| Redis 连接失败 | `redis-cli PING` | 检查 Redis Pods |
+| JWT 验证失败 | 查看 Pod 日志 | 检查 Redis 中的令牌 |
+| CSRF 验证失败 | 查看 Envoy 日志 | 检查 Cookie/Header 匹配 |
+| ETCD 加密失败 | `kubectl get secret` | 检查 kube-apiserver 启动参数 |
+
+## 部署检查清单 (5分钟版)
+
+```bash
+# 第1步: 部署 Secret (10秒)
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml && sleep 5
+
+# 第2步: 验证 Secret (10秒)
+kubectl get secret jwt-secret -n juwan && echo "✓ Secret 已创建"
+
+# 第3步: 验证 RBAC (10秒)
+kubectl get role jwt-secret-reader -n juwan && echo "✓ RBAC 已配置"
+
+# 第4步: 更新 Deployments (20秒)
+kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
+kubectl apply -f deploy/k8s/envoy/envoy.yaml
+
+# 第5步: 等待 Pods 启动 (30秒)
+kubectl rollout status deployment/user-rpc -n juwan
+kubectl rollout status deployment/envoy-gateway -n juwan
+
+# 第6步: 快速功能测试 (2分钟)
+# 创建一个令牌并验证可读取
+REDIS_POD=$(kubectl get pod -n juwan -l redis=user-redis -o name | head -1)
+kubectl exec -it $REDIS_POD -n juwan -- redis-cli KEYS "jwt:*"
+```
+
+## 密钥轮换步骤
+
+```bash
+# 1. 生成新密钥
+NEW_KEY=$(head -c 32 /dev/urandom | base64)
+
+# 2. 更新 Secret
+kubectl create secret generic jwt-secret \
+  --from-literal=secret-key=$NEW_KEY \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+# 3. 重启 Pods（自动挂载新 Secret）
+kubectl rollout restart deployment/user-rpc -n juwan
+kubectl rollout restart deployment/envoy-gateway -n juwan
+
+# 4. 等待 Pods 启动
+kubectl rollout status deployment/user-rpc -n juwan
+kubectl rollout status deployment/envoy-gateway -n juwan
+
+# 5. 旧令牌现在需要刷新或重新登录
+```
+
+## 文档地图
+
+```
+deploy/k8s/secrets/
+├── jwt-secret.yaml          ← Secrets + RBAC 配置
+├── README.md                ← 开始阅读（快速指南）
+├── SUMMARY.md               ← 本文件（系统概览）
+├── DEPLOYMENT.md            ← 详细部署步骤（12步）
+├── ENCRYPTION.md            ← ETCD 加密详细指南
+├── VERIFICATION.md          ← 完整验证清单（12部分）
+└── QUICK_REFERENCE.md       ← 本快速参考卡片
+
+app/users/api/
+└── INTEGRATION.md           ← JWT 代码集成指南
+
+app/users/rpc/
+├── internal/utils/jwt.go                    ← JwtManager 实现
+├── internal/config/config.go                ← JWT 配置
+├── internal/svc/serviceContext.go           ← 依赖注入
+└── etc/pb.yaml                              ← 运行时配置
+```
+
+## 关键时间点
+
+| 阶段 | 时间 | 操作 |
+|-----|------|------|
+| 令牌签发 | T0 | 生成 JWT，过期时间 = T0 + 7天 |
+| | | 在 Redis 存储，TTL = 30天 |
+| Token 过期 | T0 + 7天 | JWT 验证失败 |
+| 令牌刷新 | T0 + 7天到T0 + 30天 | 如果 Redis 仍有数据，生成新令牌 |
+| 完全失效 | T0 + 30天 | Redis 删除，无法再刷新 |
+| 重新登录 | T0 + 30天+ | 用户需要重新登录 |
+
+## 性能提示
+
+```bash
+# 高并发下优化 Redis 连接
+# 在 pb.yaml 中调整:
+CacheConf:
+  - Host: "user-redis.juwan:6379"
+    Type: "cluster"
+    MaxConnections: 100
+    ConnectionPoolSize: 50
+
+# 监控 JWT 验证吞吐量
+# 在 Prometheus 查询:
+rate(jwt_validations_total[5m])
+rate(jwt_refresh_total[5m])
+```
+
+## 安全提示
+
+✅ **必做**
+- [ ] 定期轮换 JWT 秘钥（季度）
+- [ ] 定期轮换 ETCD 加密密钥（年度）
+- [ ] 备份加密密钥到安全位置
+- [ ] 启用审计日志
+- [ ] 监控异常的令牌验证失败
+
+❌ **禁止**
+- [ ] 不要在日志中输出 JWT 秘钥
+- [ ] 不要在代码库中存储密钥
+- [ ] 不要发送明文密钥到 Slack/Email
+- [ ] 不要在多个环境间共享密钥
+
+## 版本信息
+
+```
+Kubernetes: 1.24+
+Go-zero: v1.10.0+
+Redis: 7.0+
+ETCD: 3.5+
+Envoy: v1.32.2+
+```
+
+## 支持和反馈
+
+遇到问题？按优先级检查：
+
+1. **运行验证脚本**
+   ```bash
+   chmod +x deploy/k8s/secrets/verify-jwt-setup.sh
+   ./deploy/k8s/secrets/verify-jwt-setup.sh
+   ```
+
+2. **查看日志**
+   ```bash
+   kubectl logs -n juwan -l app=user-rpc -f
+   ```
+
+3. **阅读 VERIFICATION.md**
+   - 第1-5部分: 基础配置
+   - 第6-8部分: 网络和监控
+   - 第9部分: ETCD 加密
+   - 第11部分: 故障排查
+
+4. **详细指南**
+   - DEPLOYMENT.md - 完整步骤
+   - INTEGRATION.md - 代码集成
+   - ENCRYPTION.md - 加密配置

deploy/k8s/secrets/README.md

@@ -0,0 +1,148 @@
+# JWT Secret Management
+
+This directory contains secure configuration for JWT secret key management.
+
+## Files
+
+- `jwt-secret.yaml`: Kubernetes Secret + ServiceAccount + RBAC rules
+- `ENCRYPTION.md`: Guide for enabling ETCD static encryption at rest
+
+## Quick Start
+
+### 1. Create the Secret and RBAC
+
+```bash
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
+```
+
+This will create:
+- Secret `jwt-secret` in namespace `juwan` containing the JWT secret key
+- ServiceAccount `user-rpc` in namespace `juwan`
+- ServiceAccount `envoy-gateway` in namespace `juwan`
+- Role `jwt-secret-reader` that allows reading only `jwt-secret`
+- RoleBindings to grant both ServiceAccounts read permission on the secret
+
+### 2. Update user-rpc Deployment
+
+Update `deploy/k8s/service/user/user-rpc.yaml` to:
+
+1. Set the serviceAccountName:
+```yaml
+spec:
+  template:
+    spec:
+      serviceAccountName: user-rpc
+```
+
+2. Add environment variable to load JWT secret:
+```yaml
+spec:
+  template:
+    spec:
+      containers:
+      - name: user-rpc
+        env:
+        - name: JWT_SECRET_KEY
+          valueFrom:
+            secretKeyRef:
+              name: jwt-secret
+              key: secret-key
+```
+
+### 3. Update envoy-gateway Deployment
+
+Update `deploy/k8s/envoy/envoy.yaml` to:
+
+1. Set the serviceAccountName:
+```yaml
+spec:
+  template:
+    spec:
+      serviceAccountName: envoy-gateway
+```
+
+2. Add environment variable or mount Secret:
+```yaml
+volumeMounts:
+- name: jwt-secret
+  mountPath: /etc/jwt
+  readOnly: true
+
+volumes:
+- name: jwt-secret
+  secret:
+    secretName: jwt-secret
+    defaultMode: 0400
+```
+
+Then reference it in the Envoy config:
+```yaml
+data:
+  envoy.yaml: |
+    # Read JWT secret from /etc/jwt/secret-key
+```
+
+### 4. Enable ETCD Encryption
+
+Follow the guide in `ENCRYPTION.md` to enable static encryption at rest for all secrets in ETCD.
+
+## Security Considerations
+
+### Least Privilege
+
+- Only `user-rpc` and `envoy-gateway` can read the JWT secret
+- No other services or users have access
+- The Role allows reading **only** the `jwt-secret`, not other secrets
+
+### Encryption at Rest
+
+- With ETCD encryption enabled, the secret is encrypted when stored on disk
+- Even if someone gains access to the ETCD database files, they cannot read the secret without the encryption key
+
+### Secret Rotation
+
+To rotate the JWT secret key:
+
+1. Generate a new key
+2. Update the Secret:
+   ```bash
+   kubectl create secret generic jwt-secret --from-literal=secret-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
+   ```
+3. Pod mounts/env vars will be updated automatically within a few minutes
+4. Old tokens will become invalid (you may need to log users out)
+
+## Production Checklist
+
+- [ ] ETCD encryption enabled (see ENCRYPTION.md)
+- [ ] JWT secret key changed from default
+- [ ] Both user-rpc and envoy-gateway Deployments use correct serviceAccountName
+- [ ] Both Deployments load the secret via environment variable or volume mount
+- [ ] Regular secret rotation policy implemented
+- [ ] Secret backup stored in secure location (encrypted)
+- [ ] RBAC audit logging enabled to track secret access
+
+## Troubleshooting
+
+### Cannot read jwt-secret
+Check if the Pod is using the correct ServiceAccount:
+```bash
+kubectl get deployment user-rpc -o yaml | grep serviceAccountName
+```
+
+### Secret not being mounted
+Verify the Secret exists:
+```bash
+kubectl get secret jwt-secret -n juwan
+```
+
+Check Pod logs for mounting errors:
+```bash
+kubectl logs -l app=user-rpc -n juwan
+```
+
+### Permission denied error
+Verify RBAC binding:
+```bash
+kubectl get rolebinding -n juwan
+kubectl get role jwt-secret-reader -n juwan
+```

deploy/k8s/secrets/SUMMARY.md

@@ -0,0 +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 双令牌验证
+
+现在可以部署并集成到应用中了！

deploy/k8s/secrets/VERIFICATION.md

@@ -0,0 +1,507 @@
+# 完整部署验证清单
+
+完成所有部署后使用此清单验证系统是否正确配置和运行。
+
+## 第一部分：基础设施验证
+
+### Secret 和 RBAC 创建
+
+```bash
+# 检查 Secret 已创建
+kubectl get secret -n juwan | grep jwt-secret
+# 预期输出: jwt-secret Created
+
+# 查看 Secret 详情（不显示敏感数据）
+kubectl describe secret jwt-secret -n juwan
+# 应该看到:
+# Name:         jwt-secret
+# Namespace:    juwan
+# Type:         Opaque
+# Data
+# ====
+# secret-key:  <encrypted>
+
+# 验证 Secret 内容已正确加载
+kubectl get secret jwt-secret -n juwan -o jsonpath='{.data.secret-key}' | base64 -d | wc -c
+# 预期输出: 应该是 32 个字符（32 字节密钥的 Base64 解码）
+```
+
+### ServiceAccount 验证
+
+```bash
+# 检查 user-rpc ServiceAccount
+kubectl get sa user-rpc -n juwan
+kubectl describe sa user-rpc -n juwan
+# 应该显示正确的 Secrets 挂载
+
+# 检查 envoy-gateway ServiceAccount
+kubectl get sa envoy-gateway -n juwan
+kubectl describe sa envoy-gateway -n juwan
+```
+
+### RBAC 权限验证
+
+```bash
+# 检查 Role 定义
+kubectl get role -n juwan -l app=jwt-secret-reader
+kubectl describe role jwt-secret-reader -n juwan
+# 应该显示:
+# PolicyRule:
+#   Resources        Non-Resource URLs  Resource Names      Verbs
+#   ---------        -----------------  --------------      -----
+#   secrets          []                 [jwt-secret]        [get]
+
+# 检查 RoleBindings
+kubectl get rolebinding -n juwan | grep jwt-secret-reader
+# 应该显示两个绑定: jwt-secret-reader-user-rpc 和 jwt-secret-reader-envoy-gateway
+
+# 验证每个 RoleBinding
+kubectl describe rolebinding jwt-secret-reader-user-rpc -n juwan
+kubectl describe rolebinding jwt-secret-reader-envoy-gateway -n juwan
+```
+
+## 第二部分：权限测试
+
+### 权限允许测试
+
+```bash
+# 测试 user-rpc 可以读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  --resource-name=jwt-secret \
+  -n juwan
+# 预期输出: yes
+
+# 测试 envoy-gateway 可以读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:envoy-gateway \
+  --resource-name=jwt-secret \
+  -n juwan
+# 预期输出: yes
+
+# 测试 user-rpc 无法读其他 Secrets
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  -n juwan
+# 预期输出: no
+
+# 测试其他 ServiceAccount 无法读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:default \
+  --resource-name=jwt-secret \
+  -n juwan
+# 预期输出: no
+```
+
+## 第三部分：Deployment 配置验证
+
+### user-rpc Deployment 验证
+
+```bash
+# 检查 ServiceAccountName 是否正确设置
+kubectl get deployment user-rpc -n juwan -o jsonpath='{.spec.template.spec.serviceAccountName}'
+# 预期输出: user-rpc
+
+# 检查是否包含所有必需的环境变量
+kubectl get deployment user-rpc -n juwan -o yaml | grep -A 20 "env:"
+# 应该包括:
+# - name: JWT_SECRET_KEY
+#   valueFrom:
+#     secretKeyRef:
+#       name: jwt-secret
+#       key: secret-key
+
+# 检查 Pod 是否正在运行
+kubectl get pods -n juwan -l app=user-rpc
+# 应该显示至少 3 个 Running 的 Pod
+
+# 验证 Pod 已加载 Secret（在 Pod 中执行）
+kubectl exec -it $(kubectl get pod -n juwan -l app=user-rpc -o name | head -1) -n juwan -- env | grep -i jwt
+# 应该输出环境变量，例如:
+# JWT_SECRET_KEY=your-secret-jwt-key-change-this-in-production
+```
+
+### Envoy Gateway Deployment 验证
+
+```bash
+# 检查 ServiceAccountName 是否正确设置
+kubectl get deployment envoy-gateway -n juwan -o jsonpath='{.spec.template.spec.serviceAccountName}'
+# 预期输出: envoy-gateway
+
+# 检查 Pod 是否正在运行
+kubectl get pods -n juwan -l app=envoy-gateway
+# 应该显示 Running 的 Pod
+
+# 检查 Envoy 日志
+kubectl logs -n juwan -l app=envoy-gateway
+# 应该看到启动日志，没有权限相关错误
+```
+
+## 第四部分：Redis 连接验证
+
+### Redis Cluster 验证
+
+```bash
+# 检查 RedisCluster CRD 状态
+kubectl get rediscluster -n juwan
+# 应该显示 user-redis，Status 应该是 Healthy
+
+# 详细查看 RedisCluster 状态
+kubectl describe rediscluster user-redis -n juwan
+# 应该显示:
+# Status:
+#   Cluster Status: Healthy
+#   Nodes Ready: 3/3
+#   Master: 1
+#   Replicas: 2
+
+# 检查 Redis Pods
+kubectl get pods -n juwan | grep redis
+# 应该显示 3 个 Redis Pod，都在 Running 状态
+
+# 测试 Redis 连接
+kubectl run redis-cli --image=redis:latest --rm -it --restart=Never -- \
+  redis-cli -h user-redis.juwan -c CLUSTER INFO
+# 应该看到集群信息，cluster_state:ok 表示集群健康
+```
+
+## 第五部分：应用启动日志检查
+
+### user-rpc 启动日志
+
+```bash
+# 查看 user-rpc Pods 的启动日志
+kubectl logs -n juwan -l app=user-rpc --all-containers=true
+
+# 应该包含类似以下消息:
+# - "Starting gRPC server on 0.0.0.0:9001"
+# - "Redis Cluster connected successfully" 或 JWT Manager 初始化成功
+# - "Listening on metrics port 4001"
+
+# 如果有错误，查看详细日志
+kubectl logs -n juwan -l app=user-rpc -f --all-containers=true
+```
+
+### Envoy 启动日志
+
+```bash
+# 查看 Envoy 启动日志
+kubectl logs -n juwan -l app=envoy-gateway
+
+# 应该包含:
+# - "[info] Configuration: /etc/envoy/envoy.yaml"
+# - "[info] listener listening on 0.0.0.0:8080"
+# - 没有权限相关错误
+```
+
+## 第六部分：网络和服务发现验证
+
+### Service 验证
+
+```bash
+# 检查 user-rpc-svc
+kubectl get svc user-rpc-svc -n juwan
+# 应该显示 ClusterIP 和两个端口 (9001/rpc 和 4001/metrics)
+
+# 检查 Envoy Gateway Service
+kubectl get svc envoy-gateway -n juwan
+# 应该显示 ClusterIP 和端口 80
+
+# 检查 Redis Service
+kubectl get svc -n juwan | grep redis
+# 应该显示 user-redis（ClusterIP）服务
+```
+
+### DNS 解析验证
+
+```bash
+# 测试服务名称解析
+kubectl run -it --rm debug --image=busybox --restart=Never -- \
+  nslookup user-rpc-svc.juwan.svc.cluster.local
+# 应该返回 ClusterIP 地址
+
+kubectl run -it --rm debug --image=busybox --restart=Never -- \
+  nslookup user-redis.juwan.svc.cluster.local
+# 应该返回 ClusterIP 地址
+```
+
+## 第七部分：监控和指标验证
+
+### Prometheus 指标收集
+
+```bash
+# 检查 Prometheus 是否在收集指标
+kubectl port-forward -n monitoring svc/prometheus 9090:9090 &
+
+# 打开浏览器访问 http://localhost:9090
+# 查看 Status > Targets
+# 应该看到 user-rpc-svc:4001  目标显示为 UP
+
+# 查询一个指标
+curl 'http://localhost:9090/api/v1/query?query=up{job="kubernetes-pods"}'
+# 应该返回 user-rpc 的指标数据
+
+# 关闭端口转发
+kill %1
+```
+
+### 测试源代码级指标端点
+
+```bash
+# 从 user-rpc Pod 直接访问指标端点
+kubectl port-forward -n juwan svc/user-rpc-svc 4001:4001 &
+
+# 测试指标端点
+curl http://localhost:4001/metrics
+
+# 应该看到 Prometheus 格式的指标，例如:
+# # HELP go_goroutines Number of goroutines that currently exist.
+# # TYPE go_goroutines gauge
+# go_goroutines 25
+
+# 关闭端口转发
+kill %1
+```
+
+## 第八部分：日志聚合验证（Loki）
+
+```bash
+# 检查 Loki 是否正确接收日志
+kubectl port-forward -n monitoring svc/loki 3100:3100 &
+
+# 查询日志
+curl 'http://localhost:3100/loki/api/v1/query_range?query={job="kubernetes-pods"}&start=0&end=9999999999'
+
+# 应该返回最近的日志条目
+
+# 检查特定应用的日志
+curl 'http://localhost:3100/loki/api/v1/query_range?query={app="user-rpc"}&start=0&end=9999999999'
+
+kill %1
+```
+
+## 第九部分：ETCD 加密验证
+
+如果已启用 ETCD 加密，执行以下验证：
+
+```bash
+# 从 control plane 节点
+ssh <control-plane-node>
+
+# 检查 ETCD 配置
+sudo cat /etc/kubernetes/encryption-config.yaml | head -20
+
+# 验证 kube-apiserver 正在使用加密配置
+sudo ps aux | grep kube-apiserver | grep encryption-provider
+
+# 创建新 Secret 进行测试
+kubectl create secret generic test-encryption -n juwan --from-literal=key=value
+
+# 检查 ETCD 中的数据是否加密
+# 注意：如果加密正确，数据应该不可读
+sudo ETCDCTL_API=3 etcdctl \
+  --cert=/etc/kubernetes/pki/etcd/server.crt \
+  --key=/etc/kubernetes/pki/etcd/server.key \
+  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
+  --endpoints=127.0.0.1:2379 \
+  get /registry/secrets/juwan/test-encryption
+
+# 输出应该是二进制数据，不可读（表示已加密）
+# 或者使用十六进制 dump
+sudo ETCDCTL_API=3 etcdctl \
+  --cert=/etc/kubernetes/pki/etcd/server.crt \
+  --key=/etc/kubernetes/pki/etcd/server.key \
+  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
+  --endpoints=127.0.0.1:2379 \
+  get /registry/secrets/juwan/test-encryption | od -A x -t x1z -v
+```
+
+## 第十部分：功能测试
+
+### JWT 令牌生成和验证测试
+
+如果已实现 JWT handlers，测试完整流程：
+
+```bash
+# 1. 前向 user-api 服务
+kubectl port-forward -n juwan svc/user-api-svc 8888:8888 &
+
+# 2. 调用登录端点获取令牌
+TOKEN=$(curl -X POST http://localhost:8888/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"password"}' \
+  | jq -r '.token')
+
+echo "Token: $TOKEN"
+
+# 3. 使用令牌访问受保护的端点
+curl -H "Authorization: Bearer $TOKEN" http://localhost:8888/api/v1/users/me
+
+# 4. 测试令牌刷新
+curl -X POST http://localhost:8888/api/v1/auth/refresh \
+  -H "Content-Type: application/json" \
+  -d "{\"token\":\"$TOKEN\"}"
+
+# 5. 测试无效令牌
+curl -H "Authorization: Bearer invalid-token" http://localhost:8888/api/v1/users/me
+# 应该返回 401 Unauthorized
+
+kill %1
+```
+
+### CSRF 保护测试
+
+```bash
+# 1. 前向 Envoy Gateway
+kubectl port-forward -n juwan svc/envoy-gateway 8080:80 &
+
+# 2. 获取 CSRF 令牌（安全方法）
+curl -i http://localhost:8080/
+
+# 查看响应头中的 Set-Cookie，应该包含 csrf_token
+
+# 3. 提取 CSRF 令牌
+CSRF_TOKEN=$(curl -i http://localhost:8080/ 2>/dev/null | grep -i csrf_token | sed 's/.*csrf_token=//;s/;.*//')
+
+# 4. 使用 CSRF 令牌进行 POST 请求
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -H "Cookie: csrf_token=$CSRF_TOKEN" \
+  -H "X-CSRF-Token: $CSRF_TOKEN" \
+  -d '{"email":"user@example.com","password":"password"}'
+
+# 5. 测试无效 CSRF 令牌（应该返回 403）
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Cookie: csrf_token=valid_token" \
+  -H "X-CSRF-Token: invalid_token" \
+  -d '{"email":"user@example.com","password":"password"}'
+# 应该返回 403 Forbidden
+
+kill %1
+```
+
+## 第十一部分：故障排查
+
+如果任何验证失败，运行以下诊断：
+
+### Pod 无法启动
+
+```bash
+# 显示 Pod 事件
+kubectl describe pod <pod-name> -n juwan
+
+# 查看完整日志（包括初始化容器）
+kubectl logs <pod-name> -n juwan --all-containers=true --previous
+
+# 检查 Pod 资源限制是否导致 OOMKilled
+kubectl get event -n juwan --sort-by='.lastTimestamp'
+```
+
+### 权限被拒绝错误
+
+```bash
+# 验证 ServiceAccount 是否正确
+kubectl get pod <pod-name> -n juwan -o jsonpath='{.spec.serviceAccountName}'
+
+# 检查 RBAC 绑定
+kubectl get rolebinding -n juwan -o wide
+
+# 手动测试权限
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  -n juwan
+```
+
+### Redis 连接错误
+
+```bash
+# 检查 Redis Pods 状态
+kubectl get pods -n juwan -l redis=user-redis
+
+# 查看 Redis 日志
+kubectl logs -n juwan -l redis=user-redis
+
+# 测试 Redis 连接（从 user-rpc Pod）
+kubectl exec -it <user-rpc-pod> -n juwan -- \
+  redis-cli -h user-redis.juwan:6379 PING
+# 应该返回 PONG
+```
+
+### ETCD 加密问题
+
+```bash
+# 验证加密配置
+kubectl get secret jwt-secret -n juwan -o json | jq '.data'
+
+# 如果 ETCD 加密启用，直接读取 ETCD 的数据应该是二进制的
+# 如果看到明文，说明加密未启用或配置不正确
+```
+
+## 第十二部分：清理测试资源
+
+```bash
+# 删除测试 Secrets
+kubectl delete secret test-encryption test-secret -n juwan --ignore-not-found
+
+# 清理前转发的端口
+lsof -i :9090 :3100 :8888 :8080 | grep LISTEN | awk '{print $2}' | xargs kill -9
+```
+
+## 快速检查脚本
+
+创建 `verify-jwt-setup.sh` 进行自动化验证：
+
+```bash
+#!/bin/bash
+
+namespace="juwan"
+echo "=== JWT Setup Verification ==="
+
+# 检查 Secret
+echo -n "✓ JWT Secret存在: "
+kubectl get secret jwt-secret -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 ServiceAccounts
+echo -n "✓ user-rpc ServiceAccount: "
+kubectl get sa user-rpc -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+echo -n "✓ envoy-gateway ServiceAccount: "
+kubectl get sa envoy-gateway -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 RBAC
+echo -n "✓ JWT RBAC Role: "
+kubectl get role jwt-secret-reader -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 Deployments
+echo -n "✓ user-rpc Deployment: "
+kubectl get deployment user-rpc -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+echo -n "✓ envoy-gateway Deployment: "
+kubectl get deployment envoy-gateway -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 Pods
+echo -n "✓ user-rpc Pods运行中: "
+[ $(kubectl get pods -n $namespace -l app=user-rpc --field-selector=status.phase=Running --no-headers | wc -l) -ge 1 ] && echo "✓" || echo "✗"
+
+echo -n "✓ envoy-gateway 运行中: "
+kubectl get pods -n $namespace -l app=envoy-gateway --field-selector=status.phase=Running &>/dev/null && echo "✓" || echo "✗"
+
+echo "=== Verification Complete ==="
+```
+
+运行脚本：
+
+```bash
+chmod +x verify-jwt-setup.sh
+./verify-jwt-setup.sh
+```
+
+## 总结
+
+所有检查项都通过后，JWT + ETCD 加密系统已准备就绪。下一步可以：
+
+1. 集成 JWT 验证到 RPC handlers
+2. 实现令牌刷新端点
+3. 部署应用代码时启用 JWT 认证
+4. 监控令牌生成和验证指标
+5. 定期轮换加密密钥和 JWT 秘钥

deploy/k8s/secrets/jwt-secret.yaml

@@ -0,0 +1,68 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: jwt-secret
+  namespace: juwan
+type: Opaque
+data:
+  # base64 encoded: your-secret-jwt-key-change-this-in-production
+  secret-key: MGUyMWE3ZDhjMTQ5ZDg1MWViOWU0MGM3OTE2NWVkYTBlOTE5ZWRkZDU1YjYzOGJjOWRiNzM0NTc4NDIyMjlkZQ==
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: user-rpc
+  namespace: juwan
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: envoy-gateway
+  namespace: juwan
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: jwt-secret-reader
+  namespace: juwan
+rules:
+  # JWT Secret 读取权限
+  - apiGroups: [""]
+    resources: ["secrets"]
+    resourceNames: ["jwt-secret"]
+    verbs: ["get"]
+  # 服务发现权限 (go-zero 框架需要)
+  - apiGroups: [""]
+    resources: ["endpoints"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["discovery.k8s.io"]
+    resources: ["endpointslices"]
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: user-rpc-jwt-secret-reader
+  namespace: juwan
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: jwt-secret-reader
+subjects:
+  - kind: ServiceAccount
+    name: user-rpc
+    namespace: juwan
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: envoy-gateway-jwt-secret-reader
+  namespace: juwan
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: jwt-secret-reader
+subjects:
+  - kind: ServiceAccount
+    name: envoy-gateway
+    namespace: juwan

deploy/k8s/service/user/user-rpc.yaml

@@ -16,7 +16,8 @@ spec:
       labels:
         app: user-rpc
     spec:
-      serviceAccountName: find-endpoints
+      # serviceAccountName: find-endpoints
+      serviceAccountName: user-rpc
       initContainers: # 等待数据库就绪的 Init Container 不影响资源使用但是影响调度策略(也可以忽略不计)
         - name: wait-for-db
           image: busybox:1.36
@@ -45,6 +46,11 @@ spec:
                 secretKeyRef:
                   name: user-redis
                   key: password
+            - name: JWT_SECRET_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: jwt-secret
+                  key: secret-key
           readinessProbe:
             tcpSocket:
               port: 9001

desc/rpc/users.proto

@@ -100,11 +100,43 @@ message GetUserByUsernameResp {
   Users users = 1; //users
 }
 
+message LoginReq {
+  string username = 1; 
+  string passwd = 2; 
+}
+
+message LoginResp {
+  string token = 1; 
+}
+
+message ValidateTokenReq {
+  string token = 1;         // JWT token
+  string userId = 2;        // 用户ID
+}
+
+message ValidateTokenResp {
+  bool valid = 1;           // token 是否有效（不在黑名单中）
+  string message = 2;       // 验证失败原因
+  string userId = 3;        // 用户ID
+  int64 roleType = 4;       // 用户角色
+}
+
+message CheckPermissionReq {
+  string userId = 1;        // 用户ID
+  string resource = 2;      // 资源 ID
+  string action = 3;        // 操作类型: read/write/delete
+}
+
+message CheckPermissionResp {
+  bool allowed = 1;         // 是否有权限
+  string message = 2;       // 拒绝原因
+}
+
 // ------------------------------------ 
 // Rpc Func
 // ------------------------------------ 
 
-service usercenter{ 
+service usercenter { 
 
 	 //-----------------------users----------------------- 
 	 rpc AddUsers(AddUsersReq) returns (AddUsersResp); 
@@ -113,4 +145,7 @@ service usercenter{
 	 rpc GetUsersById(GetUsersByIdReq) returns (GetUsersByIdResp); 
    rpc GetUserByUsername(GetUserByUsernameReq) returns (GetUserByUsernameResp);
 	 rpc SearchUsers(SearchUsersReq) returns (SearchUsersResp); 
+   rpc Login(LoginReq) returns (LoginResp);
+   rpc ValidateToken(ValidateTokenReq) returns (ValidateTokenResp);
+   rpc CheckPermission(CheckPermissionReq) returns (CheckPermissionResp);
 }

docs/secrets/DEPLOYMENT.md

@@ -0,0 +1,424 @@
+# JWT Secret + ETCD Encryption Deployment Guide
+
+完整的 JWT 认证系统部署指南，包括密钥管理、RBAC 权限控制和 ETCD 加密。
+
+## 部署顺序
+
+### 第1步：创建 Secret 和 RBAC（必需）
+
+创建 JWT 秘钥和服务账户权限：
+
+```bash
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
+```
+
+验证创建成功：
+
+```bash
+# 检查 Secret
+kubectl get secret jwt-secret -n juwan
+kubectl get secret jwt-secret -n juwan -o yaml
+
+# 检查 ServiceAccounts
+kubectl get sa user-rpc -n juwan
+kubectl get sa envoy-gateway -n juwan
+
+# 检查 RBAC 权限
+kubectl get role jwt-secret-reader -n juwan
+kubectl get rolebinding -n juwan -l app=jwt-secret-reader
+```
+
+### 第2步：更新 user-rpc 部署（依赖第1步）
+
+已自动更新 `deploy/k8s/service/user/user-rpc.yaml`：
+
+- ✅ 更新 `serviceAccountName` 从 `find-endpoints` → `user-rpc`
+- ✅ 添加环境变量 `JWT_SECRET_KEY` 从 Secret `jwt-secret` 读取
+
+应用更新：
+
+```bash
+kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
+```
+
+验证部署：
+
+```bash
+# 检查 ServiceAccount 已正确绑定
+kubectl get deployment user-rpc -n juwan -o yaml | grep -A 5 serviceAccountName
+
+# 查看 Pod 是否以 user-rpc ServiceAccount 身份运行
+kubectl get pod -n juwan -l app=user-rpc -o yaml | grep serviceAccount
+
+# 验证环境变量已注入
+kubectl exec -it POD_NAME -n juwan -- env | grep JWT_SECRET_KEY
+```
+
+### 第3步：更新 Envoy 网关部署（依赖第1步）
+
+已自动更新 `deploy/k8s/envoy/envoy.yaml`：
+
+- ✅ 添加 `serviceAccountName: envoy-gateway` 到 Deployment spec
+
+应用更新：
+
+```bash
+kubectl apply -f deploy/k8s/envoy/envoy.yaml
+```
+
+验证部署：
+
+```bash
+# 检查 ServiceAccount 已正确绑定
+kubectl get deployment envoy-gateway -n juwan -o yaml | grep -A 2 serviceAccountName
+
+# 检查 Pod 状态
+kubectl get pod -n juwan -l app=envoy-gateway
+```
+
+### 第4步：启用 ETCD 加密（强烈推荐用于生产环境）
+
+这是一个集群级别的配置，需要在 Kubernetes 控制平面节点上执行。
+
+**前提条件：**
+- 具有 Kubernetes 集群管理员权限
+- 可以访问控制平面节点
+- 备份 ETCD 数据库
+
+**步骤：**
+
+1. **生成加密密钥**
+   ```bash
+   head -c 32 /dev/urandom | base64
+   ```
+   记录输出的 Base64 密钥。
+
+2. **创建加密配置文件**
+   
+   在控制平面节点上，创建 `/etc/kubernetes/encryption-config.yaml`：
+
+   ```yaml
+   apiVersion: apiserver.config.k8s.io/v1
+   kind: EncryptionConfiguration
+   resources:
+     - resources:
+         - secrets
+       providers:
+         - aescbc:
+             keys:
+               - name: key1
+                 secret: <BASE64_ENCODED_32_BYTE_KEY>
+         - identity: {}
+   ```
+
+   替换 `<BASE64_ENCODED_32_BYTE_KEY>` 为第1步生成的密钥。
+
+3. **修改 kube-apiserver 配置**
+   
+   在控制平面节点上，编辑 `/etc/kubernetes/manifests/kube-apiserver.yaml`：
+
+   **添加参数：**
+   ```yaml
+   spec:
+     containers:
+     - name: kube-apiserver
+       command:
+         - kube-apiserver
+         - --encryption-provider-config=/etc/kubernetes/encryption-config.yaml
+   ```
+
+   **添加卷挂载：**
+   ```yaml
+   spec:
+     containers:
+     - name: kube-apiserver
+       volumeMounts:
+       - name: encryption-config
+         mountPath: /etc/kubernetes
+         readOnly: true
+   
+   volumes:
+   - name: encryption-config
+     hostPath:
+       path: /etc/kubernetes
+       type: DirectoryOrCreate
+   ```
+
+4. **重启 kube-apiserver**
+   
+   修改清单后，kubelet 会自动重启 kube-apiserver。检查状态：
+   
+   ```bash
+   # 在控制平面节点
+   kubectl get pods -n kube-system | grep kube-apiserver
+   
+   # 监控重启过程
+   kubectl logs -n kube-system -l component=kube-apiserver -f
+   ```
+
+5. **验证加密是否启用**
+   
+   创建一个新 Secret 并检查它在 ETCD 中是否加密：
+   
+   ```bash
+   # 创建测试 Secret
+   kubectl create secret generic test-secret -n juwan --from-literal=key=value
+   
+   # 从 control plane 节点检查 ETCD 数据
+   # 如果数据不可读并包含加密标记，说明加密已启用
+   ```
+
+6. **保存加密密钥**
+   
+   ⚠️ **关键：将加密密钥安全地保存在离线存储中**
+   - 密钥丢失后，无法解密 ETCD 中的数据
+   - 无法恢复任何 Secrets
+   - 建议用密码管理工具（如 HashiCorp Vault）或 HSM 存储密钥
+
+### 第5步：验证整个系统
+
+完整的验证清单：
+
+```bash
+# 检查所有 Secrets 已创建
+kubectl get secret -n juwan
+kubectl get secret jwt-secret -n juwan -o jsonpath='{.data.secret-key}' | base64 -d
+
+# 检查 ServiceAccounts 已创建
+kubectl get sa -n juwan
+kubectl describe sa user-rpc -n juwan
+kubectl describe sa envoy-gateway -n juwan
+
+# 检查 RBAC 权限
+kubectl get role -n juwan
+kubectl get rolebinding -n juwan
+kubectl describe role jwt-secret-reader -n juwan
+
+# 测试权限：user-rpc 可以读 jwt-secret
+kubectl auth can-i get secrets --as=system:serviceaccount:juwan:user-rpc --resource-name=jwt-secret -n juwan
+
+# 测试权限：envoy-gateway 可以读 jwt-secret
+kubectl auth can-i get secrets --as=system:serviceaccount:juwan:envoy-gateway --resource-name=jwt-secret -n juwan
+
+# 测试权限：其他 ServiceAccount 无法读取
+kubectl auth can-i get secrets --as=system:serviceaccount:juwan:other-service -n juwan
+
+# 检查 Deployments 已正确配置
+kubectl get deployment user-rpc -n juwan -o yaml | grep -A 2 serviceAccountName
+kubectl get deployment envoy-gateway -n juwan -o yaml | grep -A 2 serviceAccountName
+
+# 检查 Pods 是否已启动并运行
+kubectl get pods -n juwan -l app=user-rpc
+kubectl get pods -n juwan -l app=envoy-gateway
+
+# 查看 JWT Secret 是否已挂载到 Pod
+kubectl exec -it $(kubectl get pod -n juwan -l app=user-rpc -o name | head -1) -n juwan -- env | grep JWT_SECRET_KEY
+```
+
+## 监控和日志
+
+### 查看 Pod 日志
+
+```bash
+# user-rpc 日志
+kubectl logs -n juwan -l app=user-rpc -f --all-containers=true
+
+# Envoy 日志
+kubectl logs -n juwan -l app=envoy-gateway -f
+```
+
+### 检查 Pod 事件
+
+```bash
+# 查看 Pod 创建和启动事件
+kubectl describe pod -n juwan -l app=user-rpc
+kubectl describe pod -n juwan -l app=envoy-gateway
+```
+
+### 权限问题排查
+
+如果 Pod 无法读取 Secret：
+
+```bash
+# 检查 Pod 使用的 ServiceAccount
+kubectl get pod POD_NAME -n juwan -o yaml | grep serviceAccountName
+
+# 检查 RBAC 绑定
+kubectl get rolebinding -n juwan -o wide
+
+# 检查 Role 权限定义
+kubectl get role jwt-secret-reader -n juwan -o yaml
+
+# 尝试用 Pod 的身份读取 Secret（需要 kubectl-user-impersonate 或类似工具）
+kubectl get secret jwt-secret --as=system:serviceaccount:juwan:user-rpc -n juwan
+```
+
+## 安全最佳实践
+
+### 1. 密钥轮换
+
+周期性更换 JWT 秘钥（建议每季度）：
+
+```bash
+# 1. 生成新密钥
+NEW_KEY=$(head -c 32 /dev/urandom | base64)
+
+# 2. 更新 Secret
+kubectl create secret generic jwt-secret \
+  --from-literal=secret-key=$NEW_KEY \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+# 3. 重启 Pods 以加载新密钥（滚动更新）
+kubectl rollout restart deployment/user-rpc -n juwan
+kubectl rollout restart deployment/envoy-gateway -n juwan
+
+# 4. 验证新 Pods 已启动并运行
+kubectl rollout status deployment/user-rpc -n juwan
+kubectl rollout status deployment/envoy-gateway -n juwan
+
+# 5. 已颁发的旧令牌将变为无效
+# 需要用户重新登录获取新令牌
+```
+
+### 2. 审计和监控
+
+在生产环境中启用 Kubernetes 审计日志来跟踪 Secret 访问：
+
+```yaml
+# kube-apiserver 审计策略示例
+apiVersion: audit.k8s.io/v1
+kind: Policy
+rules:
+  # 记录 secret 资源的访问
+  - level: RequestResponse
+    verbs: ["get", "list", "watch"]
+    resources: ["secrets"]
+  # 记录所有认证失败
+  - level: RequestResponse
+    omitStages:
+      - RequestReceived
+    userGroups: ["system:unauthenticated"]
+  - level: Metadata
+    omitStages:
+      - RequestReceived
+```
+
+### 3. 网络策略
+
+使用 NetworkPolicy 限制 Pods 之间的通信：
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: jwt-secret-access
+  namespace: juwan
+spec:
+  podSelector:
+    matchLabels:
+      app: jwt-secret-reader
+  policyTypes:
+    - Ingress
+  ingress:
+    - from:
+        - podSelector:
+            matchLabels:
+              app: user-rpc
+        - podSelector:
+            matchLabels:
+              app: envoy-gateway
+      ports:
+        - protocol: TCP
+          port: 443  # API Server
+```
+
+## 灾难恢复
+
+### 备份 Secret 和 RBAC 配置
+
+```bash
+# 备份 JWT Secret
+kubectl get secret jwt-secret -n juwan -o yaml > jwt-secret-backup.yaml
+
+# 备份 RBAC 配置
+kubectl get role jwt-secret-reader -n juwan -o yaml > jwt-role-backup.yaml
+kubectl get rolebinding -n juwan -l app=jwt-secret-reader -o yaml > jwt-rolebinding-backup.yaml
+
+# 加密备份文件
+gpg --symmetric jwt-secret-backup.yaml
+```
+
+### 恢复步骤
+
+如果 Secret 被意外删除：
+
+```bash
+# 从备份恢复
+kubectl apply -f jwt-secret-backup.yaml
+
+# 重启 Pods 以重新加载 Secret
+kubectl rollout restart deployment/user-rpc -n juwan
+kubectl rollout restart deployment/envoy-gateway -n juwan
+```
+
+## 常见问题
+
+### Q: Pod 无法启动，显示 "failed to pull secret"
+
+A: 检查：
+1. Secret 是否存在：`kubectl get secret jwt-secret -n juwan`
+2. ServiceAccount 是否绑定了 RBAC：`kubectl describe rolebinding -n juwan`
+3. Secret 名称和命名空间是否正确
+
+### Q: 加密后如何验证 ETCD 中的数据已加密？
+
+A: 从 control plane 节点：
+```bash
+# 直接读取 ETCD（如果配置了加密，数据应该不可读）
+sudo strings /var/lib/etcd/member/snap/db | grep -i secret
+```
+
+### Q: 能否更改加密密钥而不重新创建 ETCD？
+
+A: 可以，但流程复杂：
+1. 更新 encryption-config.yaml 中的新密钥
+2. 将新密钥添加到提供程序列表（保持旧密钥）
+3. 重启 kube-apiserver
+4. 触发重新加密：`kubectl get all --all-namespaces -o json | kubectl apply -f -`
+
+### Q: 如何在 Minikube 中启用 ETCD 加密？
+
+A: 参考 `ENCRYPTION.md` 中的 Minikube 特定说明部分。
+
+## 相关文件
+
+- `jwt-secret.yaml` - Secret 和 RBAC 配置
+- `ENCRYPTION.md` - ETCD 加密详细文档
+- `README.md` - 快速参考指南
+- `/deploy/k8s/service/user/user-rpc.yaml` - user-rpc Deployment 配置
+- `/deploy/k8s/envoy/envoy.yaml` - Envoy 网关 Deployment 配置
+
+## 下一步
+
+部署完成后：
+
+1. **集成 JWT 验证到 RPC Handlers**
+   - 实现 gRPC unary interceptor
+   - 验证令牌有效性
+   - 处理令牌刷新逻辑
+
+2. **集成 JWT 验证到 Envoy**
+   - 扩展 Lua filter 进行令牌验证
+   - 返回 401（无效令牌）或 200（有效令牌）
+
+3. **端到端测试**
+   - 创建用户和登录
+   - 生成和验证 JWT
+   - 测试令牌刷新和撤销
+   - 验证 ETCD 加密
+
+4. **生产部署**
+   - 启用审计日志
+   - 配置密钥轮换计划
+   - 建立备份和恢复流程
+   - 监控 Secret 访问

docs/secrets/ENCRYPTION.md

@@ -0,0 +1,129 @@
+# ETCD Encryption Configuration for Kubernetes
+
+To enable static encryption at rest for Kubernetes secrets in ETCD, you need to configure the API Server with an EncryptionConfiguration.
+
+## 1. Generate an Encryption Key
+
+```bash
+# Generate a 32-byte base64-encoded key
+head -c 32 /dev/urandom | base64
+# Example output: sxFdbKYquCe3EbRWVV+pFe2lS8K8hbiv3V8ExQZ0fD4=
+```
+
+## 2. Create EncryptionConfiguration File
+
+Create `/etc/kubernetes/encryption-config.yaml` on the control plane node:
+
+```yaml
+apiVersion: apiserver.config.k8s.io/v1
+kind: EncryptionConfiguration
+resources:
+  - resources:
+      - secrets
+    providers:
+      - aescbc:
+          keys:
+            - name: key1
+              secret: sxFdbKYquCe3EbRWVV+pFe2lS8K8hbiv3V8ExQZ0fD4=
+      - identity: {}
+```
+
+## 3. Update kube-apiserver Static Pod Manifest
+
+Edit `/etc/kubernetes/manifests/kube-apiserver.yaml` on the control plane node:
+
+```yaml
+spec:
+  containers:
+  - name: kube-apiserver
+    command:
+    - kube-apiserver
+    # ... existing flags ...
+    - --encryption-provider-config=/etc/kubernetes/encryption-config.yaml
+    volumeMounts:
+    - name: encryption-config
+      mountPath: /etc/kubernetes
+      readOnly: true
+  volumes:
+  - name: encryption-config
+    hostPath:
+      path: /etc/kubernetes
+      type: DirectoryOrCreate
+```
+
+## 4. Verify Encryption is Working
+
+```bash
+# After restarting the API server, create a secret and verify it's encrypted
+kubectl create secret generic test-secret --from-literal=key=value -n juwan
+
+# Check if the secret is encrypted in etcd
+kubectl get secret test-secret -o yaml
+
+# You can also check raw etcd data (requires etcd access):
+# etcdctl --endpoints=https://127.0.0.1:2379 get /kubernetes.io/secrets/juwan/test-secret
+# The data should be encrypted (not human-readable)
+```
+
+## 5. Important Notes
+
+- **Backup your encryption key** in a secure location
+- **Never commit encryption keys** to version control
+- If you lose the key, all encrypted secrets will be unrecoverable
+- After enabling encryption, existing unencrypted secrets will not be automatically encrypted
+  - To encrypt existing secrets, you can use: `kubectl delete secret <name> && kubectl create secret ...`
+  - Or use: `kubectl patch secret <name> -p '{}' --type=merge` (triggers re-encryption)
+
+## 6. RBAC Configuration for JWT Secret
+
+The `jwt-secret.yaml` includes RBAC rules that:
+- Create a `jwt-secret` Secret in the `juwan` namespace
+- Create ServiceAccounts for `user-rpc` and `envoy-gateway`
+- Create a Role `jwt-secret-reader` that allows reading only the `jwt-secret` Secret
+- Bind this Role to both ServiceAccounts via RoleBindings
+
+This ensures:
+- Only `user-rpc` and `envoy-gateway` Pods can read the JWT secret
+- Other services and users cannot access the JWT secret
+- Least privilege access principle is enforced
+
+## 7. Update Deployment to Use ServiceAccount
+
+Make sure your Deployment references the ServiceAccount:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: user-rpc
+  namespace: juwan
+spec:
+  template:
+    spec:
+      serviceAccountName: user-rpc  # This is important!
+      containers:
+      - name: user-rpc
+        env:
+        - name: JWT_SECRET_KEY
+          valueFrom:
+            secretKeyRef:
+              name: jwt-secret
+              key: secret-key
+```
+
+## 8. For Minikube Users
+
+If using Minikube, you can enable encryption with:
+
+```bash
+minikube config set apiserver.encryption-provider-config /path/to/encryption-config.yaml
+minikube start
+```
+
+Or manually edit the kube-apiserver manifest after starting Minikube:
+
+```bash
+minikube ssh
+sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml
+# Add the flags and volume mounts as shown above
+```

docs/secrets/FLOWCHART.md

@@ -0,0 +1,415 @@
+# 部署流程图和时间线
+
+## 部署架构流程图
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│        JWT 认证系统部署流程                                       │
+└──────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 1: 前置检查 (5分钟)                                           │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  ✓ Kubernetes 集群版本 >= 1.24                                     │
+│  ✓ kubectl 已配置，可访问集群                                       │
+│  ✓ juwan namespace 已存在                                          │
+│  ✓ redis-operator CRD 已安装                                       │
+│  ✓ 集群管理员权限（用于 ETCD 加密）                                 │
+│                                                                     │
+│  命令检查:                                                          │
+│  $ kubectl cluster-info                                            │
+│  $ kubectl get ns juwan                                            │
+│  $ kubectl get crd redisclusters.redis.redis.opstreelabs.in       │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 2: 创建 Secret 和 RBAC (5分钟)  ⚡ 必需                       │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  执行:                                                              │
+│  $ kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml             │
+│                                                                     │
+│  创建的资源:                                                        │
+│  ✓ 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                    │
+│                                                                     │
+│  验证:                                                              │
+│  $ kubectl get secret jwt-secret -n juwan                          │
+│  $ kubectl get sa -n juwan | grep -E "user-rpc|envoy"              │
+│  $ kubectl get role -n juwan                                       │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 3: 更新 Deployments (10分钟) ⚡ 必需                         │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Step 3a: 更新 user-rpc Deployment                                 │
+│  执行:                                                              │
+│  $ kubectl apply -f deploy/k8s/service/user/user-rpc.yaml          │
+│                                                                     │
+│  变更:                                                              │
+│  - serviceAccountName: user-rpc (绑定权限)                         │
+│  - env.JWT_SECRET_KEY (从 Secret 挂载)                             │
+│  - 保持 Redis Cluster 配置                                         │
+│                                                                     │
+│  等待 Pods 启动:                                                    │
+│  $ kubectl rollout status deployment/user-rpc -n juwan             │
+│                                                                     │
+│  ---                                                               │
+│                                                                     │
+│  Step 3b: 更新 Envoy Gateway Deployment                            │
+│  执行:                                                              │
+│  $ kubectl apply -f deploy/k8s/envoy/envoy.yaml                    │
+│                                                                     │
+│  变更:                                                              │
+│  - serviceAccountName: envoy-gateway (绑定权限)                    │
+│  - 保持 CSRF Lua 防护配置                                          │
+│                                                                     │
+│  等待 Pods 启动:                                                    │
+│  $ kubectl rollout status deployment/envoy-gateway -n juwan        │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Phase 4: 验证部署 (15分钟) ⚡ 必需                                  │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  检查清单:                                                          │
+│                                                                     │
+│  1️⃣  Secret 和权限验证                                             │
+│  $ kubectl get secret jwt-secret -n juwan                          │
+│  $ kubectl get role jwt-secret-reader -n juwan                     │
+│  $ kubectl get rolebinding -n juwan | grep jwt-secret              │
+│                                                                     │
+│  2️⃣  权限测试                                                      │
+│  $ kubectl auth can-i get secrets \                                │
+│    --as=system:serviceaccount:juwan:user-rpc \                     │
+│    --resource-name=jwt-secret -n juwan                             │
+│  预期: yes                                                         │
+│                                                                     │
+│  3️⃣  Pods 运行状态                                                │
+│  $ kubectl get pods -n juwan -l app=user-rpc                       │
+│  $ kubectl get pods -n juwan -l app=envoy-gateway                  │
+│  预期: 3 个 user-rpc Pods + 1 个 envoy-gateway Pod 都在 Running   │
+│                                                                     │
+│  4️⃣  环境变量验证                                                  │
+│  $ kubectl exec -it <user-rpc-pod> -n juwan -- env | grep JWT      │
+│  预期: JWT_SECRET_KEY=...                                          │
+│                                                                     │
+│  5️⃣  Redis 连接验证                                               │
+│  $ kubectl run redis-cli --image=redis:latest --rm -it \           │
+│    -- redis-cli -h user-redis.juwan:6379 PING                     │
+│  预期: PONG                                                        │
+│                                                                     │
+│  详见: VERIFICATION.md 第1-8部分                                    │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+        │
+        ├─────────── 生产环境额外步骤 ──────────────┐
+        │                                          │
+        ▼                                          ▼
+┌──────────────────────────┐   ┌─────────────────────────────────────┐
+│ Phase 5a: 应用集成       │   │ Phase 5b: 启用 ETCD 加密 (30分钟)  │
+│ (2-3 小时) ⚠️  推荐      │   │ ⚠️ 生产推荐，需集群管理员权限       │
+├──────────────────────────┤   ├─────────────────────────────────────┤
+│                          │   │                                     │
+│ 实施内容:                │   │ 前提条件:                          │
+│ ✓ gRPC Interceptor       │   │ ✓ Control Plane 节点访问权限       │
+│ ✓ Login/Logout Handler   │   │ ✓ ETCD 备份已创建                  │
+│ ✓ JWT Middleware         │   │ ✓ 加密密钥已生成                  │
+│ ✓ Token Refresh Logic    │   │                                     │
+│ ✓ Error Handling         │   │ 步骤:                              │
+│ ✓ Unit Tests             │   │ 1. 生成 32 字节密钥                │
+│                          │   │    $ head -c 32 /dev/urandom | base64
+│ 参考:                     │   │                                     │
+│ INTEGRATION.md           │   │ 2. 创建加密配置文件                │
+│                          │   │    /etc/kubernetes/encryption-config.yaml
+│ 时间估计:                │   │                                     │
+│ - gRPC 拦截器: 30分钟   │   │ 3. 修改 kube-apiserver manifest    │
+│ - Handlers: 60分钟       │   │    添加密钥路径和卷挂载             │
+│ - Middleware: 30分钟     │   │                                     │
+│ - 测试: 60分钟           │   │ 4. 重启 kube-apiserver             │
+│                          │   │    kubelet 自动重启                 │
+│                          │   │                                     │
+│                          │   │ 5. 验证加密已启用                  │
+│                          │   │    kubectl create secret generic ... │
+│                          │   │    检查 ETCD 中的数据是否加密       │
+│                          │   │                                     │
+│                          │   │ 详见: ENCRYPTION.md (8个部分)      │
+│                          │   │ 验证: VERIFICATION.md 第9部分       │
+│                          │   │                                     │
+└──────────────────────────┘   └─────────────────────────────────────┘
+        │                                          │
+        └───────────────────┬─────────────────────┘
+                            │
+                            ▼
+        ┌──────────────────────────────────────────┐
+        │ Phase 6: 完成 ✅                          │
+        ├──────────────────────────────────────────┤
+        │                                          │
+        │ 最终检查:                                │
+        │ ✓ 所有 Pods 运行正常                     │
+        │ ✓ RBAC 权限已验证                        │
+        │ ✓ JWT 功能已集成                         │
+        │ ✓ 日志和监控已配置                       │
+        │ ✓ (可选) ETCD 加密已启用                 │
+        │                                          │
+        │ 生产推荐:                                │
+        │ ✓ 启用审计日志                           │
+        │ ✓ 配置密钥轮换计划（季度）              │
+        │ ✓ 备份密钥到安全位置                     │
+        │ ✓ 配置告警和监控                         │
+        │                                          │
+        └──────────────────────────────────────────┘
+```
+
+## 时间估计和路径
+
+```
+推荐部署路径
+═════════════════════════════════════════════════════════════════
+
+🚀 最快路径 (30 分钟) - 开发环境
+────────────────────────────────────────────────────────────────
+Phase 1: 前置检查                        ⏱️ 5 分钟
+Phase 2: 创建 Secret 和 RBAC              ⏱️ 5 分钟  
+Phase 3: 更新 Deployments                ⏱️ 10 分钟
+Phase 4: 验证部署                        ⏱️ 10 分钟
+────────────────────────────────────────────────────────────────
+                                         总计: 30 分钟
+
+
+📊 默认路径 (75 分钟) - 测试环境
+────────────────────────────────────────────────────────────────
+Phase 1-4: 如上                          ⏱️ 30 分钟
+Phase 5a: 应用集成（简单版）             ⏱️ 45 分钟
+────────────────────────────────────────────────────────────────
+                                         总计: 75 分钟
+
+
+🏆 完整路径 (3.5-4 小时) - 生产环境
+────────────────────────────────────────────────────────────────
+Phase 1-4: 如上                          ⏱️ 30 分钟
+Phase 5a: 应用集成（完整版）             ⏱️ 2-3 小时
+Phase 5b: ETCD 加密配置                  ⏱️ 30 分钟
+────────────────────────────────────────────────────────────────
+                                         总计: 3.5-4 小时
+
+
+📚 学习路径 (6-8 小时) - 从零开始理解
+────────────────────────────────────────────────────────────────
+文档阅读 (SUMMARY + DEPLOYMENT + INTEGRATION)  ⏱️ 1-2 小时
+完整路径部署                             ⏱️ 3.5-4 小时
+验证和测试                                ⏱️ 1-2 小时
+────────────────────────────────────────────────────────────────
+                                         总计: 6-8 小时
+```
+
+## 并行和串行步骤
+
+```
+可以并行执行的任务
+═════════════════════════════════════════════════════════════════
+
+┌─────────────────────────────────┐
+│ 应用集成 (Phase 5a)             │ ────┐
+├─────────────────────────────────┤    │ 可选，独立
+│ • gRPC interceptor               │    │ 进行
+│ • REST middleware                │    │
+│ • Handler 实现                   │    │
+│ • 单元测试                       │    │
+└─────────────────────────────────┘    │
+                                      ├─ 与 Phase 2-4 并行
+                                      │
+┌─────────────────────────────────┐    │
+│ ETCD 加密 (Phase 5b)            │ ────┘
+├─────────────────────────────────┤    │ 需要集群管理员
+│ • 生成密钥（可单独进行）         │    │ 权限，在
+│ • 创建配置文件                  │    │ Control Plane
+│ • 修改 kube-apiserver           │    │ 节点执行
+│ • 重启 API server               │    │
+└─────────────────────────────────┘────┘
+
+
+必须串行执行的步骤
+═════════════════════════════════════════════════════════════════
+
+Phase 1 → Phase 2 → Phase 3 → Phase 4 → (Phase 5a + Phase 5b)
+  
+  ↓       ↓        ↓        ↓
+前置检查  创建资源  部署应用  验证完整  可选扩展功能
+  
+• Phase 2 必须在 Phase 1 之后（需要 namespace）
+• Phase 3 必须在 Phase 2 之后（需要 RoleBinding）
+• Phase 4 必须在 Phase 3 之后（需要 Pods 启动）
+• Phase 5a/5b 可在 Phase 4 完成后并行进行
+```
+
+## 关键时间点
+
+```
+事件时间线
+═════════════════════════════════════════════════════════════════
+
+T+0      Phase 1: 验证前置条件
+         └─ 预计 5 分钟
+         
+T+5      Phase 2: kubectl apply jwt-secret.yaml
+         └─ 预计 1 分钟执行，5 分钟验证
+         
+T+11     Phase 3a: kubectl apply user-rpc.yaml
+         └─ 3 个 Pods 启动（滚动更新）
+         └─ 预计 ~3 分钟（取决于镜像拉取）
+         
+T+14     Phase 3b: kubectl apply envoy.yaml
+         └─ 1 个 Pod 启动
+         └─ 预计 ~2 分钟
+         
+T+16     Phase 4: 执行完整验证检查
+         └─ 12 个验证部分，共 ~15 分钟
+
+T+31     ✅ 基础部署完成
+
+T+31     (可选) Phase 5a: 应用代码集成
+到       └─ 2-3 小时编码和测试
+T+211    
+
+T+31     (可选) Phase 5b: ETCD 加密
+到       └─ 30 分钟配置
+T+61     
+
+T+211 或 T+61  🎉 全部完成
+(取决于是否执行 Phase 5)
+```
+
+## 推荐的部署顺序
+
+### 对于 DevOps/SRE
+
+```
+优先级顺序:
+
+1️⃣ Phase 1-4 (核心部署)  [必需]
+   └─ 时间: 30 分钟
+   
+2️⃣ Phase 5b (ETCD 加密)  [生产强烈推荐]
+   └─ 时间: 30 分钟
+   └─ 开始时间: T+16 之前 (与 Phase 4 并行)
+   
+3️⃣ 密钥备份和恢复计划    [重要]
+   └─ 时间: 15 分钟
+   └─ 参考: DEPLOYMENT.md 灾难恢复
+   
+4️⃣ Phase 5a 支持          [当开发完成时]
+   └─ 协助开发团队集成 JWT
+   └─ 参考: INTEGRATION.md
+```
+
+### 对于应用开发者
+
+```
+优先级顺序:
+
+1️⃣ 了解系统架构           [了解背景]
+   └─ 文档: SUMMARY.md
+   └─ 时间: 10 分钟
+   
+2️⃣ Phase 5a: 代码集成     [并行进行]
+   └─ 参考: INTEGRATION.md
+   └─ 时间: 2-3 小时
+   
+3️⃣ 单元测试                [在开发中]
+   └─ 参考: INTEGRATION.md 第 9 部分
+   └─ 时间: 1 小时
+   
+4️⃣ 集成测试                [与运维协调]
+   └─ 测试完整流程
+   └─ 时间: 1-2 小时
+```
+
+## 回滚应急步骤
+
+如果部署失败，可以快速回滚：
+
+```
+紧急回滚
+═════════════════════════════════════════════════════════════════
+
+如果 Phase 2 (Secret) 失败:
+→ kubectl delete secret jwt-secret -n juwan
+→ kubectl delete sa user-rpc envoy-gateway -n juwan
+→ kubectl delete role jwt-secret-reader -n juwan
+→ 修正配置后重新应用
+
+如果 Phase 3 (Deployment) 失败:
+→ kubectl rollout undo deployment/user-rpc -n juwan
+→ kubectl rollout undo deployment/envoy-gateway -n juwan
+→ 或删除部署并使用稳定的旧版本重新部署
+
+如果 Phase 5b (ETCD 加密) 失败:
+→ 从 kube-apiserver 清单中移除加密参数
+→ 重启 kube-apiserver
+→ 删除 /etc/kubernetes/encryption-config.yaml
+→ 从最近的 ETCD 备份恢复（如果需要）
+
+注意: 备份是关键！每次重大操作前都应备份。
+```
+
+## 部署检查点 (Go/No-Go)
+
+```
+关键检查点
+═════════════════════════════════════════════════════════════════
+
+✅ Checkpoint 1 (Phase 2 后)
+   - Secret 已创建
+   - ServiceAccounts 已创建
+   - Go → 继续 Phase 3
+   - No-Go → 检查 kubectl 权限
+
+✅ Checkpoint 2 (Phase 3 后)
+   - Pods 已启动 (Running)
+   - No PodSchedulingFailure
+   - Go → 继续 Phase 4
+   - No-Go → 检查资源限制和镜像拉取
+
+✅ Checkpoint 3 (Phase 4 权限测试)
+   - user-rpc 可以读 jwt-secret
+   - envoy-gateway 可以读 jwt-secret
+   - 其他 SA 无法读取
+   - Go → 继续 Phase 5
+   - No-Go → 检查 RBAC 配置
+
+✅ Checkpoint 4 (Phase 4 Redis 连接)
+   - Redis Cluster 健康 (3/3 nodes)
+   - PING 返回 PONG
+   - Go → 继续应用集成
+   - No-Go → 检查 Redis Pods 和网络
+
+✅ Checkpoint 5 (Phase 5b - ETCD 加密)
+   - 新创建的 Secret 在 ETCD 中已加密
+   - Go → 生产就绪
+   - No-Go → 检查 kube-apiserver 配置参数
+```
+
+---
+
+## 使用这个流程图
+
+1. **首次部署** → 从 "推荐部署路径" 选择合适的版本
+2. **卡在某一步** → 查看对应的 Phase 描述和命令
+3. **估算时间** → 查看 "时间估计和路径" 部分
+4. **需要回滚** → 参考 "回滚应急步骤"
+5. **检查进度** → 使用 "部署检查点"
+
+详细的部署步骤见：[DEPLOYMENT.md](./DEPLOYMENT.md)

docs/secrets/INDEX.md

@@ -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 分钟 |

docs/secrets/QUICK_REFERENCE.md

@@ -0,0 +1,350 @@
+# JWT + ETCD 加密系统 - 快速参考卡片
+
+## 一页速查表
+
+### 部署命令
+
+```bash
+# 创建 Secret 和 RBAC
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
+
+# 更新 Deployments
+kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
+kubectl apply -f deploy/k8s/envoy/envoy.yaml
+
+# 验证部署
+kubectl get secret jwt-secret -n juwan
+kubectl get sa user-rpc envoy-gateway -n juwan
+kubectl get role jwt-secret-reader -n juwan
+kubectl get pods -n juwan -l app=user-rpc
+kubectl get pods -n juwan -l app=envoy-gateway
+```
+
+### 权限验证
+
+```bash
+# user-rpc 可以读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  --resource-name=jwt-secret -n juwan
+# 预期: yes
+
+# 其他 SA 无法读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:default \
+  --resource-name=jwt-secret -n juwan
+# 预期: no
+```
+
+### 日志查看
+
+```bash
+# user-rpc 日志
+kubectl logs -n juwan -l app=user-rpc -f
+
+# Envoy 日志
+kubectl logs -n juwan -l app=envoy-gateway -f
+
+# 特定 Pod 日志
+kubectl logs -n juwan <pod-name> --all-containers=true -f
+```
+
+### 环境变量验证
+
+```bash
+# 检查 JWT_SECRET_KEY 已注入
+kubectl exec -it $(kubectl get pod -n juwan -l app=user-rpc -o name | head -1) \
+  -n juwan -- env | grep JWT_SECRET_KEY
+```
+
+### Redis 验证
+
+```bash
+# 连接到 Redis Cluster
+kubectl run redis-cli --image=redis:latest --rm -it --restart=Never -- \
+  redis-cli -h user-redis.juwan:6379 -c CLUSTER INFO
+
+# 测试键操作
+kubectl run redis-cli --image=redis:latest --rm -it --restart=Never -- \
+  redis-cli -h user-redis.juwan:6379 -c GET jwt:user:test-user-id
+```
+
+### ETCD 加密配置
+
+```bash
+# 1. 在 Control Plane 节点生成密钥
+head -c 32 /dev/urandom | base64
+
+# 2. 编辑 kube-apiserver 清单
+sudo nano /etc/kubernetes/manifests/kube-apiserver.yaml
+
+# 添加参数:
+--encryption-provider-config=/etc/kubernetes/encryption-config.yaml
+
+# 3. 创建加密配置文件
+cat <<EOF | sudo tee /etc/kubernetes/encryption-config.yaml
+apiVersion: apiserver.config.k8s.io/v1
+kind: EncryptionConfiguration
+resources:
+  - resources:
+      - secrets
+    providers:
+      - aescbc:
+          keys:
+            - name: key1
+              secret: <BASE64_KEY>
+      - identity: {}
+EOF
+
+# 4. 验证加密
+kubectl create secret generic test-encryption -n juwan --from-literal=key=value
+sudo ETCDCTL_API=3 etcdctl --cert=/etc/kubernetes/pki/etcd/server.crt \
+  --key=/etc/kubernetes/pki/etcd/server.key \
+  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
+  --endpoints=127.0.0.1:2379 \
+  get /registry/secrets/juwan/test-encryption | od -A x -t x1z
+```
+
+### 故障排查
+
+```bash
+# Pod 无法启动？查看事件
+kubectl describe pod <pod-name> -n juwan
+
+# 权限被拒绝？检查 RBAC
+kubectl get rolebinding -n juwan -o wide
+kubectl describe rolebinding jwt-secret-reader-user-rpc -n juwan
+
+# 无法挂载 Secret？检查 Secret 存在性
+kubectl get secret jwt-secret -n juwan -o yaml
+
+# Redis 连接错误？测试连通性
+kubectl exec -it <user-rpc-pod> -n juwan -- \
+  redis-cli -h user-redis.juwan:6379 PING
+```
+
+## JWT Manager API 速查
+
+### JwtManager 方法
+
+```go
+// 生成新令牌
+token, err := svcCtx.JwtManager.New(ctx, userID, email, name)
+
+// 验证令牌
+claims, err := svcCtx.JwtManager.Valid(ctx, token)
+
+// 刷新令牌（如果过期但 Redis 仍有数据）
+newToken, err := svcCtx.JwtManager.Renew(ctx, token)
+
+// 提取声明（不验证签名）
+claims, err := svcCtx.JwtManager.Extract(ctx, token)
+
+// 检查令牌是否存在于 Redis
+exists, err := svcCtx.JwtManager.Exists(ctx, token)
+
+// 撤销令牌（登出）
+err := svcCtx.JwtManager.Revoke(ctx, userID, token)
+
+// 获取用户当前令牌
+token, err := svcCtx.JwtManager.GetUserToken(ctx, userID)
+
+// 将声明转换为载荷
+payload := svcCtx.JwtManager.ClaimsToPayload(claims)
+```
+
+## 配置文件位置
+
+| 配置 | 位置 | 关键参数 |
+|-----|------|--------|
+| JWT Secret | `deploy/k8s/secrets/jwt-secret.yaml` | `secret-key` |
+| user-rpc 配置 | `app/users/rpc/etc/pb.yaml` | `JWT.SecretKey`, `REDIS_HOST` |
+| Envoy 配置 | `deploy/k8s/envoy/envoy.yaml` | CSRF 验证 Lua 代码 |
+| ETCD 加密 | `/etc/kubernetes/encryption-config.yaml`（Control Plane） | `secret` (32字节密钥) |
+
+## 关键参数速查
+
+```yaml
+# JWT 令牌有效期
+Token Exp: 7 days
+
+# Redis 存储 TTL
+Redis TTL: 30 days
+
+# 可刷新时间窗口
+Refresh Window: 30 days - 7 days = 23 days
+
+# CSRF Token 位置
+Cookie: csrf_token=...
+Header: X-CSRF-Token: ...
+
+# ETCD 加密算法
+Algorithm: AES-CBC
+Key Size: 256 bits (32 bytes)
+Encoding: Base64
+
+# Secret 挂载方式
+Method: volumeMount (read-only)
+或
+Method: valueFrom.secretKeyRef
+```
+
+## 常见问题速查
+
+| 问题 | 排查命令 | 解决方案 |
+|-----|--------|--------|
+| Pod 无法启动 | `kubectl describe pod` | 检查 Secret/RBAC |
+| 权限被拒绝 | `kubectl auth can-i get secrets` | 验证 RBAC 绑定 |
+| Redis 连接失败 | `redis-cli PING` | 检查 Redis Pods |
+| JWT 验证失败 | 查看 Pod 日志 | 检查 Redis 中的令牌 |
+| CSRF 验证失败 | 查看 Envoy 日志 | 检查 Cookie/Header 匹配 |
+| ETCD 加密失败 | `kubectl get secret` | 检查 kube-apiserver 启动参数 |
+
+## 部署检查清单 (5分钟版)
+
+```bash
+# 第1步: 部署 Secret (10秒)
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml && sleep 5
+
+# 第2步: 验证 Secret (10秒)
+kubectl get secret jwt-secret -n juwan && echo "✓ Secret 已创建"
+
+# 第3步: 验证 RBAC (10秒)
+kubectl get role jwt-secret-reader -n juwan && echo "✓ RBAC 已配置"
+
+# 第4步: 更新 Deployments (20秒)
+kubectl apply -f deploy/k8s/service/user/user-rpc.yaml
+kubectl apply -f deploy/k8s/envoy/envoy.yaml
+
+# 第5步: 等待 Pods 启动 (30秒)
+kubectl rollout status deployment/user-rpc -n juwan
+kubectl rollout status deployment/envoy-gateway -n juwan
+
+# 第6步: 快速功能测试 (2分钟)
+# 创建一个令牌并验证可读取
+REDIS_POD=$(kubectl get pod -n juwan -l redis=user-redis -o name | head -1)
+kubectl exec -it $REDIS_POD -n juwan -- redis-cli KEYS "jwt:*"
+```
+
+## 密钥轮换步骤
+
+```bash
+# 1. 生成新密钥
+NEW_KEY=$(head -c 32 /dev/urandom | base64)
+
+# 2. 更新 Secret
+kubectl create secret generic jwt-secret \
+  --from-literal=secret-key=$NEW_KEY \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+# 3. 重启 Pods（自动挂载新 Secret）
+kubectl rollout restart deployment/user-rpc -n juwan
+kubectl rollout restart deployment/envoy-gateway -n juwan
+
+# 4. 等待 Pods 启动
+kubectl rollout status deployment/user-rpc -n juwan
+kubectl rollout status deployment/envoy-gateway -n juwan
+
+# 5. 旧令牌现在需要刷新或重新登录
+```
+
+## 文档地图
+
+```
+deploy/k8s/secrets/
+├── jwt-secret.yaml          ← Secrets + RBAC 配置
+├── README.md                ← 开始阅读（快速指南）
+├── SUMMARY.md               ← 本文件（系统概览）
+├── DEPLOYMENT.md            ← 详细部署步骤（12步）
+├── ENCRYPTION.md            ← ETCD 加密详细指南
+├── VERIFICATION.md          ← 完整验证清单（12部分）
+└── QUICK_REFERENCE.md       ← 本快速参考卡片
+
+app/users/api/
+└── INTEGRATION.md           ← JWT 代码集成指南
+
+app/users/rpc/
+├── internal/utils/jwt.go                    ← JwtManager 实现
+├── internal/config/config.go                ← JWT 配置
+├── internal/svc/serviceContext.go           ← 依赖注入
+└── etc/pb.yaml                              ← 运行时配置
+```
+
+## 关键时间点
+
+| 阶段 | 时间 | 操作 |
+|-----|------|------|
+| 令牌签发 | T0 | 生成 JWT，过期时间 = T0 + 7天 |
+| | | 在 Redis 存储，TTL = 30天 |
+| Token 过期 | T0 + 7天 | JWT 验证失败 |
+| 令牌刷新 | T0 + 7天到T0 + 30天 | 如果 Redis 仍有数据，生成新令牌 |
+| 完全失效 | T0 + 30天 | Redis 删除，无法再刷新 |
+| 重新登录 | T0 + 30天+ | 用户需要重新登录 |
+
+## 性能提示
+
+```bash
+# 高并发下优化 Redis 连接
+# 在 pb.yaml 中调整:
+CacheConf:
+  - Host: "user-redis.juwan:6379"
+    Type: "cluster"
+    MaxConnections: 100
+    ConnectionPoolSize: 50
+
+# 监控 JWT 验证吞吐量
+# 在 Prometheus 查询:
+rate(jwt_validations_total[5m])
+rate(jwt_refresh_total[5m])
+```
+
+## 安全提示
+
+✅ **必做**
+- [ ] 定期轮换 JWT 秘钥（季度）
+- [ ] 定期轮换 ETCD 加密密钥（年度）
+- [ ] 备份加密密钥到安全位置
+- [ ] 启用审计日志
+- [ ] 监控异常的令牌验证失败
+
+❌ **禁止**
+- [ ] 不要在日志中输出 JWT 秘钥
+- [ ] 不要在代码库中存储密钥
+- [ ] 不要发送明文密钥到 Slack/Email
+- [ ] 不要在多个环境间共享密钥
+
+## 版本信息
+
+```
+Kubernetes: 1.24+
+Go-zero: v1.10.0+
+Redis: 7.0+
+ETCD: 3.5+
+Envoy: v1.32.2+
+```
+
+## 支持和反馈
+
+遇到问题？按优先级检查：
+
+1. **运行验证脚本**
+   ```bash
+   chmod +x deploy/k8s/secrets/verify-jwt-setup.sh
+   ./deploy/k8s/secrets/verify-jwt-setup.sh
+   ```
+
+2. **查看日志**
+   ```bash
+   kubectl logs -n juwan -l app=user-rpc -f
+   ```
+
+3. **阅读 VERIFICATION.md**
+   - 第1-5部分: 基础配置
+   - 第6-8部分: 网络和监控
+   - 第9部分: ETCD 加密
+   - 第11部分: 故障排查
+
+4. **详细指南**
+   - DEPLOYMENT.md - 完整步骤
+   - INTEGRATION.md - 代码集成
+   - ENCRYPTION.md - 加密配置

docs/secrets/README.md

@@ -0,0 +1,148 @@
+# JWT Secret Management
+
+This directory contains secure configuration for JWT secret key management.
+
+## Files
+
+- `jwt-secret.yaml`: Kubernetes Secret + ServiceAccount + RBAC rules
+- `ENCRYPTION.md`: Guide for enabling ETCD static encryption at rest
+
+## Quick Start
+
+### 1. Create the Secret and RBAC
+
+```bash
+kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml
+```
+
+This will create:
+- Secret `jwt-secret` in namespace `juwan` containing the JWT secret key
+- ServiceAccount `user-rpc` in namespace `juwan`
+- ServiceAccount `envoy-gateway` in namespace `juwan`
+- Role `jwt-secret-reader` that allows reading only `jwt-secret`
+- RoleBindings to grant both ServiceAccounts read permission on the secret
+
+### 2. Update user-rpc Deployment
+
+Update `deploy/k8s/service/user/user-rpc.yaml` to:
+
+1. Set the serviceAccountName:
+```yaml
+spec:
+  template:
+    spec:
+      serviceAccountName: user-rpc
+```
+
+2. Add environment variable to load JWT secret:
+```yaml
+spec:
+  template:
+    spec:
+      containers:
+      - name: user-rpc
+        env:
+        - name: JWT_SECRET_KEY
+          valueFrom:
+            secretKeyRef:
+              name: jwt-secret
+              key: secret-key
+```
+
+### 3. Update envoy-gateway Deployment
+
+Update `deploy/k8s/envoy/envoy.yaml` to:
+
+1. Set the serviceAccountName:
+```yaml
+spec:
+  template:
+    spec:
+      serviceAccountName: envoy-gateway
+```
+
+2. Add environment variable or mount Secret:
+```yaml
+volumeMounts:
+- name: jwt-secret
+  mountPath: /etc/jwt
+  readOnly: true
+
+volumes:
+- name: jwt-secret
+  secret:
+    secretName: jwt-secret
+    defaultMode: 0400
+```
+
+Then reference it in the Envoy config:
+```yaml
+data:
+  envoy.yaml: |
+    # Read JWT secret from /etc/jwt/secret-key
+```
+
+### 4. Enable ETCD Encryption
+
+Follow the guide in `ENCRYPTION.md` to enable static encryption at rest for all secrets in ETCD.
+
+## Security Considerations
+
+### Least Privilege
+
+- Only `user-rpc` and `envoy-gateway` can read the JWT secret
+- No other services or users have access
+- The Role allows reading **only** the `jwt-secret`, not other secrets
+
+### Encryption at Rest
+
+- With ETCD encryption enabled, the secret is encrypted when stored on disk
+- Even if someone gains access to the ETCD database files, they cannot read the secret without the encryption key
+
+### Secret Rotation
+
+To rotate the JWT secret key:
+
+1. Generate a new key
+2. Update the Secret:
+   ```bash
+   kubectl create secret generic jwt-secret --from-literal=secret-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
+   ```
+3. Pod mounts/env vars will be updated automatically within a few minutes
+4. Old tokens will become invalid (you may need to log users out)
+
+## Production Checklist
+
+- [ ] ETCD encryption enabled (see ENCRYPTION.md)
+- [ ] JWT secret key changed from default
+- [ ] Both user-rpc and envoy-gateway Deployments use correct serviceAccountName
+- [ ] Both Deployments load the secret via environment variable or volume mount
+- [ ] Regular secret rotation policy implemented
+- [ ] Secret backup stored in secure location (encrypted)
+- [ ] RBAC audit logging enabled to track secret access
+
+## Troubleshooting
+
+### Cannot read jwt-secret
+Check if the Pod is using the correct ServiceAccount:
+```bash
+kubectl get deployment user-rpc -o yaml | grep serviceAccountName
+```
+
+### Secret not being mounted
+Verify the Secret exists:
+```bash
+kubectl get secret jwt-secret -n juwan
+```
+
+Check Pod logs for mounting errors:
+```bash
+kubectl logs -l app=user-rpc -n juwan
+```
+
+### Permission denied error
+Verify RBAC binding:
+```bash
+kubectl get rolebinding -n juwan
+kubectl get role jwt-secret-reader -n juwan
+```

docs/secrets/SUMMARY.md

@@ -0,0 +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 双令牌验证
+
+现在可以部署并集成到应用中了！

docs/secrets/VERIFICATION.md

@@ -0,0 +1,507 @@
+# 完整部署验证清单
+
+完成所有部署后使用此清单验证系统是否正确配置和运行。
+
+## 第一部分：基础设施验证
+
+### Secret 和 RBAC 创建
+
+```bash
+# 检查 Secret 已创建
+kubectl get secret -n juwan | grep jwt-secret
+# 预期输出: jwt-secret Created
+
+# 查看 Secret 详情（不显示敏感数据）
+kubectl describe secret jwt-secret -n juwan
+# 应该看到:
+# Name:         jwt-secret
+# Namespace:    juwan
+# Type:         Opaque
+# Data
+# ====
+# secret-key:  <encrypted>
+
+# 验证 Secret 内容已正确加载
+kubectl get secret jwt-secret -n juwan -o jsonpath='{.data.secret-key}' | base64 -d | wc -c
+# 预期输出: 应该是 32 个字符（32 字节密钥的 Base64 解码）
+```
+
+### ServiceAccount 验证
+
+```bash
+# 检查 user-rpc ServiceAccount
+kubectl get sa user-rpc -n juwan
+kubectl describe sa user-rpc -n juwan
+# 应该显示正确的 Secrets 挂载
+
+# 检查 envoy-gateway ServiceAccount
+kubectl get sa envoy-gateway -n juwan
+kubectl describe sa envoy-gateway -n juwan
+```
+
+### RBAC 权限验证
+
+```bash
+# 检查 Role 定义
+kubectl get role -n juwan -l app=jwt-secret-reader
+kubectl describe role jwt-secret-reader -n juwan
+# 应该显示:
+# PolicyRule:
+#   Resources        Non-Resource URLs  Resource Names      Verbs
+#   ---------        -----------------  --------------      -----
+#   secrets          []                 [jwt-secret]        [get]
+
+# 检查 RoleBindings
+kubectl get rolebinding -n juwan | grep jwt-secret-reader
+# 应该显示两个绑定: jwt-secret-reader-user-rpc 和 jwt-secret-reader-envoy-gateway
+
+# 验证每个 RoleBinding
+kubectl describe rolebinding jwt-secret-reader-user-rpc -n juwan
+kubectl describe rolebinding jwt-secret-reader-envoy-gateway -n juwan
+```
+
+## 第二部分：权限测试
+
+### 权限允许测试
+
+```bash
+# 测试 user-rpc 可以读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  --resource-name=jwt-secret \
+  -n juwan
+# 预期输出: yes
+
+# 测试 envoy-gateway 可以读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:envoy-gateway \
+  --resource-name=jwt-secret \
+  -n juwan
+# 预期输出: yes
+
+# 测试 user-rpc 无法读其他 Secrets
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  -n juwan
+# 预期输出: no
+
+# 测试其他 ServiceAccount 无法读 jwt-secret
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:default \
+  --resource-name=jwt-secret \
+  -n juwan
+# 预期输出: no
+```
+
+## 第三部分：Deployment 配置验证
+
+### user-rpc Deployment 验证
+
+```bash
+# 检查 ServiceAccountName 是否正确设置
+kubectl get deployment user-rpc -n juwan -o jsonpath='{.spec.template.spec.serviceAccountName}'
+# 预期输出: user-rpc
+
+# 检查是否包含所有必需的环境变量
+kubectl get deployment user-rpc -n juwan -o yaml | grep -A 20 "env:"
+# 应该包括:
+# - name: JWT_SECRET_KEY
+#   valueFrom:
+#     secretKeyRef:
+#       name: jwt-secret
+#       key: secret-key
+
+# 检查 Pod 是否正在运行
+kubectl get pods -n juwan -l app=user-rpc
+# 应该显示至少 3 个 Running 的 Pod
+
+# 验证 Pod 已加载 Secret（在 Pod 中执行）
+kubectl exec -it $(kubectl get pod -n juwan -l app=user-rpc -o name | head -1) -n juwan -- env | grep -i jwt
+# 应该输出环境变量，例如:
+# JWT_SECRET_KEY=your-secret-jwt-key-change-this-in-production
+```
+
+### Envoy Gateway Deployment 验证
+
+```bash
+# 检查 ServiceAccountName 是否正确设置
+kubectl get deployment envoy-gateway -n juwan -o jsonpath='{.spec.template.spec.serviceAccountName}'
+# 预期输出: envoy-gateway
+
+# 检查 Pod 是否正在运行
+kubectl get pods -n juwan -l app=envoy-gateway
+# 应该显示 Running 的 Pod
+
+# 检查 Envoy 日志
+kubectl logs -n juwan -l app=envoy-gateway
+# 应该看到启动日志，没有权限相关错误
+```
+
+## 第四部分：Redis 连接验证
+
+### Redis Cluster 验证
+
+```bash
+# 检查 RedisCluster CRD 状态
+kubectl get rediscluster -n juwan
+# 应该显示 user-redis，Status 应该是 Healthy
+
+# 详细查看 RedisCluster 状态
+kubectl describe rediscluster user-redis -n juwan
+# 应该显示:
+# Status:
+#   Cluster Status: Healthy
+#   Nodes Ready: 3/3
+#   Master: 1
+#   Replicas: 2
+
+# 检查 Redis Pods
+kubectl get pods -n juwan | grep redis
+# 应该显示 3 个 Redis Pod，都在 Running 状态
+
+# 测试 Redis 连接
+kubectl run redis-cli --image=redis:latest --rm -it --restart=Never -- \
+  redis-cli -h user-redis.juwan -c CLUSTER INFO
+# 应该看到集群信息，cluster_state:ok 表示集群健康
+```
+
+## 第五部分：应用启动日志检查
+
+### user-rpc 启动日志
+
+```bash
+# 查看 user-rpc Pods 的启动日志
+kubectl logs -n juwan -l app=user-rpc --all-containers=true
+
+# 应该包含类似以下消息:
+# - "Starting gRPC server on 0.0.0.0:9001"
+# - "Redis Cluster connected successfully" 或 JWT Manager 初始化成功
+# - "Listening on metrics port 4001"
+
+# 如果有错误，查看详细日志
+kubectl logs -n juwan -l app=user-rpc -f --all-containers=true
+```
+
+### Envoy 启动日志
+
+```bash
+# 查看 Envoy 启动日志
+kubectl logs -n juwan -l app=envoy-gateway
+
+# 应该包含:
+# - "[info] Configuration: /etc/envoy/envoy.yaml"
+# - "[info] listener listening on 0.0.0.0:8080"
+# - 没有权限相关错误
+```
+
+## 第六部分：网络和服务发现验证
+
+### Service 验证
+
+```bash
+# 检查 user-rpc-svc
+kubectl get svc user-rpc-svc -n juwan
+# 应该显示 ClusterIP 和两个端口 (9001/rpc 和 4001/metrics)
+
+# 检查 Envoy Gateway Service
+kubectl get svc envoy-gateway -n juwan
+# 应该显示 ClusterIP 和端口 80
+
+# 检查 Redis Service
+kubectl get svc -n juwan | grep redis
+# 应该显示 user-redis（ClusterIP）服务
+```
+
+### DNS 解析验证
+
+```bash
+# 测试服务名称解析
+kubectl run -it --rm debug --image=busybox --restart=Never -- \
+  nslookup user-rpc-svc.juwan.svc.cluster.local
+# 应该返回 ClusterIP 地址
+
+kubectl run -it --rm debug --image=busybox --restart=Never -- \
+  nslookup user-redis.juwan.svc.cluster.local
+# 应该返回 ClusterIP 地址
+```
+
+## 第七部分：监控和指标验证
+
+### Prometheus 指标收集
+
+```bash
+# 检查 Prometheus 是否在收集指标
+kubectl port-forward -n monitoring svc/prometheus 9090:9090 &
+
+# 打开浏览器访问 http://localhost:9090
+# 查看 Status > Targets
+# 应该看到 user-rpc-svc:4001  目标显示为 UP
+
+# 查询一个指标
+curl 'http://localhost:9090/api/v1/query?query=up{job="kubernetes-pods"}'
+# 应该返回 user-rpc 的指标数据
+
+# 关闭端口转发
+kill %1
+```
+
+### 测试源代码级指标端点
+
+```bash
+# 从 user-rpc Pod 直接访问指标端点
+kubectl port-forward -n juwan svc/user-rpc-svc 4001:4001 &
+
+# 测试指标端点
+curl http://localhost:4001/metrics
+
+# 应该看到 Prometheus 格式的指标，例如:
+# # HELP go_goroutines Number of goroutines that currently exist.
+# # TYPE go_goroutines gauge
+# go_goroutines 25
+
+# 关闭端口转发
+kill %1
+```
+
+## 第八部分：日志聚合验证（Loki）
+
+```bash
+# 检查 Loki 是否正确接收日志
+kubectl port-forward -n monitoring svc/loki 3100:3100 &
+
+# 查询日志
+curl 'http://localhost:3100/loki/api/v1/query_range?query={job="kubernetes-pods"}&start=0&end=9999999999'
+
+# 应该返回最近的日志条目
+
+# 检查特定应用的日志
+curl 'http://localhost:3100/loki/api/v1/query_range?query={app="user-rpc"}&start=0&end=9999999999'
+
+kill %1
+```
+
+## 第九部分：ETCD 加密验证
+
+如果已启用 ETCD 加密，执行以下验证：
+
+```bash
+# 从 control plane 节点
+ssh <control-plane-node>
+
+# 检查 ETCD 配置
+sudo cat /etc/kubernetes/encryption-config.yaml | head -20
+
+# 验证 kube-apiserver 正在使用加密配置
+sudo ps aux | grep kube-apiserver | grep encryption-provider
+
+# 创建新 Secret 进行测试
+kubectl create secret generic test-encryption -n juwan --from-literal=key=value
+
+# 检查 ETCD 中的数据是否加密
+# 注意：如果加密正确，数据应该不可读
+sudo ETCDCTL_API=3 etcdctl \
+  --cert=/etc/kubernetes/pki/etcd/server.crt \
+  --key=/etc/kubernetes/pki/etcd/server.key \
+  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
+  --endpoints=127.0.0.1:2379 \
+  get /registry/secrets/juwan/test-encryption
+
+# 输出应该是二进制数据，不可读（表示已加密）
+# 或者使用十六进制 dump
+sudo ETCDCTL_API=3 etcdctl \
+  --cert=/etc/kubernetes/pki/etcd/server.crt \
+  --key=/etc/kubernetes/pki/etcd/server.key \
+  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
+  --endpoints=127.0.0.1:2379 \
+  get /registry/secrets/juwan/test-encryption | od -A x -t x1z -v
+```
+
+## 第十部分：功能测试
+
+### JWT 令牌生成和验证测试
+
+如果已实现 JWT handlers，测试完整流程：
+
+```bash
+# 1. 前向 user-api 服务
+kubectl port-forward -n juwan svc/user-api-svc 8888:8888 &
+
+# 2. 调用登录端点获取令牌
+TOKEN=$(curl -X POST http://localhost:8888/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"password"}' \
+  | jq -r '.token')
+
+echo "Token: $TOKEN"
+
+# 3. 使用令牌访问受保护的端点
+curl -H "Authorization: Bearer $TOKEN" http://localhost:8888/api/v1/users/me
+
+# 4. 测试令牌刷新
+curl -X POST http://localhost:8888/api/v1/auth/refresh \
+  -H "Content-Type: application/json" \
+  -d "{\"token\":\"$TOKEN\"}"
+
+# 5. 测试无效令牌
+curl -H "Authorization: Bearer invalid-token" http://localhost:8888/api/v1/users/me
+# 应该返回 401 Unauthorized
+
+kill %1
+```
+
+### CSRF 保护测试
+
+```bash
+# 1. 前向 Envoy Gateway
+kubectl port-forward -n juwan svc/envoy-gateway 8080:80 &
+
+# 2. 获取 CSRF 令牌（安全方法）
+curl -i http://localhost:8080/
+
+# 查看响应头中的 Set-Cookie，应该包含 csrf_token
+
+# 3. 提取 CSRF 令牌
+CSRF_TOKEN=$(curl -i http://localhost:8080/ 2>/dev/null | grep -i csrf_token | sed 's/.*csrf_token=//;s/;.*//')
+
+# 4. 使用 CSRF 令牌进行 POST 请求
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -H "Cookie: csrf_token=$CSRF_TOKEN" \
+  -H "X-CSRF-Token: $CSRF_TOKEN" \
+  -d '{"email":"user@example.com","password":"password"}'
+
+# 5. 测试无效 CSRF 令牌（应该返回 403）
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Cookie: csrf_token=valid_token" \
+  -H "X-CSRF-Token: invalid_token" \
+  -d '{"email":"user@example.com","password":"password"}'
+# 应该返回 403 Forbidden
+
+kill %1
+```
+
+## 第十一部分：故障排查
+
+如果任何验证失败，运行以下诊断：
+
+### Pod 无法启动
+
+```bash
+# 显示 Pod 事件
+kubectl describe pod <pod-name> -n juwan
+
+# 查看完整日志（包括初始化容器）
+kubectl logs <pod-name> -n juwan --all-containers=true --previous
+
+# 检查 Pod 资源限制是否导致 OOMKilled
+kubectl get event -n juwan --sort-by='.lastTimestamp'
+```
+
+### 权限被拒绝错误
+
+```bash
+# 验证 ServiceAccount 是否正确
+kubectl get pod <pod-name> -n juwan -o jsonpath='{.spec.serviceAccountName}'
+
+# 检查 RBAC 绑定
+kubectl get rolebinding -n juwan -o wide
+
+# 手动测试权限
+kubectl auth can-i get secrets \
+  --as=system:serviceaccount:juwan:user-rpc \
+  -n juwan
+```
+
+### Redis 连接错误
+
+```bash
+# 检查 Redis Pods 状态
+kubectl get pods -n juwan -l redis=user-redis
+
+# 查看 Redis 日志
+kubectl logs -n juwan -l redis=user-redis
+
+# 测试 Redis 连接（从 user-rpc Pod）
+kubectl exec -it <user-rpc-pod> -n juwan -- \
+  redis-cli -h user-redis.juwan:6379 PING
+# 应该返回 PONG
+```
+
+### ETCD 加密问题
+
+```bash
+# 验证加密配置
+kubectl get secret jwt-secret -n juwan -o json | jq '.data'
+
+# 如果 ETCD 加密启用，直接读取 ETCD 的数据应该是二进制的
+# 如果看到明文，说明加密未启用或配置不正确
+```
+
+## 第十二部分：清理测试资源
+
+```bash
+# 删除测试 Secrets
+kubectl delete secret test-encryption test-secret -n juwan --ignore-not-found
+
+# 清理前转发的端口
+lsof -i :9090 :3100 :8888 :8080 | grep LISTEN | awk '{print $2}' | xargs kill -9
+```
+
+## 快速检查脚本
+
+创建 `verify-jwt-setup.sh` 进行自动化验证：
+
+```bash
+#!/bin/bash
+
+namespace="juwan"
+echo "=== JWT Setup Verification ==="
+
+# 检查 Secret
+echo -n "✓ JWT Secret存在: "
+kubectl get secret jwt-secret -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 ServiceAccounts
+echo -n "✓ user-rpc ServiceAccount: "
+kubectl get sa user-rpc -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+echo -n "✓ envoy-gateway ServiceAccount: "
+kubectl get sa envoy-gateway -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 RBAC
+echo -n "✓ JWT RBAC Role: "
+kubectl get role jwt-secret-reader -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 Deployments
+echo -n "✓ user-rpc Deployment: "
+kubectl get deployment user-rpc -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+echo -n "✓ envoy-gateway Deployment: "
+kubectl get deployment envoy-gateway -n $namespace &>/dev/null && echo "✓" || echo "✗"
+
+# 检查 Pods
+echo -n "✓ user-rpc Pods运行中: "
+[ $(kubectl get pods -n $namespace -l app=user-rpc --field-selector=status.phase=Running --no-headers | wc -l) -ge 1 ] && echo "✓" || echo "✗"
+
+echo -n "✓ envoy-gateway 运行中: "
+kubectl get pods -n $namespace -l app=envoy-gateway --field-selector=status.phase=Running &>/dev/null && echo "✓" || echo "✗"
+
+echo "=== Verification Complete ==="
+```
+
+运行脚本：
+
+```bash
+chmod +x verify-jwt-setup.sh
+./verify-jwt-setup.sh
+```
+
+## 总结
+
+所有检查项都通过后，JWT + ETCD 加密系统已准备就绪。下一步可以：
+
+1. 集成 JWT 验证到 RPC handlers
+2. 实现令牌刷新端点
+3. 部署应用代码时启用 JWT 认证
+4. 监控令牌生成和验证指标
+5. 定期轮换加密密钥和 JWT 秘钥

docs/secrets/jwt-secret.yaml

@@ -0,0 +1,60 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: jwt-secret
+  namespace: juwan
+type: Opaque
+data:
+  # base64 encoded: your-secret-jwt-key-change-this-in-production
+  secret-key: eW91ci1zZWNyZXQtand0LWtleS1jaGFuZ2UtdGhpcy1pbi1wcm9kdWN0aW9u
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: user-rpc
+  namespace: juwan
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: envoy-gateway
+  namespace: juwan
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: jwt-secret-reader
+  namespace: juwan
+rules:
+  - apiGroups: [""]
+    resources: ["secrets"]
+    resourceNames: ["jwt-secret"]
+    verbs: ["get"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: user-rpc-jwt-secret-reader
+  namespace: juwan
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: jwt-secret-reader
+subjects:
+  - kind: ServiceAccount
+    name: user-rpc
+    namespace: juwan
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: envoy-gateway-jwt-secret-reader
+  namespace: juwan
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: jwt-secret-reader
+subjects:
+  - kind: ServiceAccount
+    name: envoy-gateway
+    namespace: juwan