From 239f8f9877c1d554cd424c696973e82d80255263 Mon Sep 17 00:00:00 2001
From: hhs <386998068@qq.com>
Date: Sun, 21 Jun 2026 23:19:11 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E9=99=90=E6=B5=81?=
 =?UTF-8?q?=E5=92=8C=E9=89=B4=E6=9D=83=E6=96=87=E6=A1=A3=E7=9A=84=E6=97=A5?=
 =?UTF-8?q?=E5=BF=97=E5=AE=9E=E7=8E=B0=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 更新限流文档：limiter 内部使用 trace.FromContext 自动记录日志
- 更新鉴权文档：Redis 降级策略使用 trace-aware 日志
- 引用 13-日志追踪.md 作为详细说明
- 移除过时的手动 logger.Log 调用示例
---
 docs/10-鉴权体系.md   | 3 ++-
 docs/11-令牌桶限流.md | 8 ++++----
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/10-鉴权体系.md b/docs/10-鉴权体系.md
index db0feb9..be0f034 100644
--- a/docs/10-鉴权体系.md
+++ b/docs/10-鉴权体系.md
@@ -805,8 +805,9 @@ func (r *CachedUserRepository) DeleteRefreshToken(ctx, tokenHash) error {
 ```
 
 **降级策略**：
-- Redis 操作失败时记录日志，但不阻断主流程
+- Redis 操作失败时使用 `trace.FromContext(ctx)` 记录 Warn 日志（带 trace_id），但不阻断主流程
 - DB 是唯一真实数据源，Redis 仅用于加速
+- 详见 `docs/13-日志追踪.md` — 存储层日志实现
 
 ### 6. Gin 中间件实现
 
diff --git a/docs/11-令牌桶限流.md b/docs/11-令牌桶限流.md
index 608dcc0..b2e44c6 100644
--- a/docs/11-令牌桶限流.md
+++ b/docs/11-令牌桶限流.md
@@ -360,7 +360,7 @@ if cfg.RateLimit.Enabled {
         logger.Log.Info("rate limiter initialized with Redis backend")
     } else {
         // 单实例：使用内存令牌桶
-        limiter = ratelimit.NewLimiter(cfg.RateLimit)
+        limiter = ratelimit.NewMemoryLimiter(cfg.RateLimit)
         logger.Log.Info("rate limiter initialized with in-memory backend")
     }
     defer limiter.Stop()
@@ -590,9 +590,9 @@ case "query":
     // 限流检查
     if limiter != nil {
         key := fmt.Sprintf("%s:query", userID)
-        allowed, retryAfter := limiter.Allow(context.Background(), key)
+        allowed, retryAfter := limiter.Allow(ctx, key)
         if !allowed {
-            logger.Log.Warnw("rate limited", "user_id", userID, "retry_after", retryAfter)
+            // 限流触发时自动记录 Warn 日志（在 limiter 内部使用 trace.FromContext）
             errors.SendWSError(client, errors.CodeRateLimited, msg.RequestID,
                 fmt.Errorf("rate limited, retry after %s", retryAfter.Round(time.Second)))
             continue
@@ -605,7 +605,7 @@ case "query":
 **设计要点**：
 - key 格式：`userID:query`（用户级限流）
 - 拒绝时发送 `RATE_LIMITED` 错误到客户端
-- 记录警告日志（便于监控告警）
+- 限流触发时 `RedisLimiter.Allow` 内部自动记录 Warn 日志（带 trace_id，详见 `docs/13-日志追踪.md`）
 - 不阻塞其他消息类型（`ping`/`config`/`interrupt` 不限流）
 
 ### 配置加载与依赖注入