Merge pull request #49 from yyyCode/feat/gateway-access-log

feat(gateway): 网关增加访问日志，记录来源 IP / 接口 / 状态码 / 耗时

Author: yyyCode

OpenBlog-gateway/src/main/java/com/yqz/openblog/gateway/config/GatewayProperties.java

@@ -11,6 +11,7 @@ public class GatewayProperties {
 
     private Auth auth = new Auth();
     private RateLimit rateLimit = new RateLimit();
+    private AccessLog accessLog = new AccessLog();
 
     public Auth getAuth() {
         return auth;
@@ -28,6 +29,27 @@ public void setRateLimit(RateLimit rateLimit) {
         this.rateLimit = rateLimit;
     }
 
+    public AccessLog getAccessLog() {
+        return accessLog;
+    }
+
+    public void setAccessLog(AccessLog accessLog) {
+        this.accessLog = accessLog;
+    }
+
+    /** 访问日志开关（openblog.gateway.access-log.*）。 */
+    public static class AccessLog {
+        private boolean enabled = true;
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+
+        public void setEnabled(boolean enabled) {
+            this.enabled = enabled;
+        }
+    }
+
     public static class Auth {
         private List<String> skipPaths = new ArrayList<>();
 

OpenBlog-gateway/src/main/java/com/yqz/openblog/gateway/filter/AccessLogFilter.java

@@ -0,0 +1,84 @@
+package com.yqz.openblog.gateway.filter;
+
+import com.yqz.openblog.gateway.config.GatewayProperties;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.cloud.gateway.filter.GatewayFilterChain;
+import org.springframework.cloud.gateway.filter.GlobalFilter;
+import org.springframework.core.Ordered;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.HttpStatusCode;
+import org.springframework.stereotype.Component;
+import org.springframework.web.server.ServerWebExchange;
+import reactor.core.publisher.Mono;
+import reactor.core.publisher.SignalType;
+
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * 访问日志（order=-4，最外层）：请求结束后打印来源 IP、方法、路径、状态码、耗时与 traceId。
+ * <p>
+ * 排在 {@link TraceIdFilter}（-3）之外，故记录发生在整条链（限流 / JWT / 下游调用）全部结束之后，
+ * 状态码与耗时都是最终值。traceId 在此刻已写入 exchange 属性，直接取出显式打印——
+ * 日志 pattern 里的 {@code %X{traceId}} 依赖 MDC，而 WebFlux 下 MDC 不跨线程，网关这里取不到值。
+ * <p>
+ * 只记录 path、<b>不记录 query string</b>：部分端点的查询参数可能带一次性令牌/邮箱等敏感值，
+ * 一旦落盘难以回收。确需排查时再显式放开，并自行做脱敏。
+ * <p>
+ * 关闭开关：{@code openblog.gateway.access-log.enabled=false}。
+ */
+@Component
+public class AccessLogFilter implements GlobalFilter, Ordered {
+
+    private static final Logger log = LoggerFactory.getLogger(AccessLogFilter.class);
+
+    private final GatewayProperties props;
+
+    public AccessLogFilter(GatewayProperties props) {
+        this.props = props;
+    }
+
+    @Override
+    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
+        if (!props.getAccessLog().isEnabled()) {
+            return chain.filter(exchange);
+        }
+        long startNanos = System.nanoTime();
+        // doFinally 只给终止信号、拿不到异常对象，用 holder 记下异常供统一出口打印
+        AtomicReference<Throwable> error = new AtomicReference<>();
+
+        return chain.filter(exchange)
+                .doOnError(error::set)
+                .doFinally(signal -> logAccess(exchange, startNanos, signal, error.get()));
+    }
+
+    private void logAccess(ServerWebExchange exchange, long startNanos, SignalType signal, Throwable error) {
+        String ip = ClientIpResolver.resolve(exchange);
+        HttpMethod method = exchange.getRequest().getMethod();
+        String path = exchange.getRequest().getPath().value();
+        long costMs = (System.nanoTime() - startNanos) / 1_000_000;
+        String traceId = TraceIdFilter.traceIdOf(exchange);
+
+        if (signal == SignalType.ON_ERROR) {
+            // 此时响应码可能尚未由 GatewayErrorHandler 写入（异常处理器在过滤器链之外），故只报异常本身
+            log.warn("gateway access failed: ip={} method={} path={} cost={}ms traceId={} err={}",
+                    ip, method, path, costMs, traceId, error != null ? error.toString() : signal);
+            return;
+        }
+        if (signal == SignalType.CANCEL) {
+            // 客户端提前断开：前端切路由 / 关页面都会触发，属日常流量而非故障，
+            // 故记 INFO。若记 WARN，正常浏览就会持续刷 WARN，把真正的 ON_ERROR 淹掉。
+            log.info("gateway access cancelled: ip={} method={} path={} cost={}ms traceId={}",
+                    ip, method, path, costMs, traceId);
+            return;
+        }
+        HttpStatusCode status = exchange.getResponse().getStatusCode();
+        log.info("gateway access: ip={} method={} path={} status={} cost={}ms traceId={}",
+                ip, method, path, status != null ? status.value() : "-", costMs, traceId);
+    }
+
+    @Override
+    public int getOrder() {
+        return -4;
+    }
+}

OpenBlog-gateway/src/main/java/com/yqz/openblog/gateway/filter/ClientIpResolver.java

@@ -0,0 +1,43 @@
+package com.yqz.openblog.gateway.filter;
+
+import org.springframework.web.server.ServerWebExchange;
+
+/**
+ * 客户端真实 IP 解析（网关各过滤器共用）。
+ * <p>
+ * 抽成独立工具类而非各自实现：IP 是限流分桶与访问审计的共同口径，两份实现一旦漂移，
+ * 会出现「限流按 A 计、日志按 B 记」的排查黑洞。
+ * <p>
+ * 优先级：X-Real-IP → X-Forwarded-For 首跳 → TCP 对端地址 → "unknown"。
+ * nginx 用 {@code $remote_addr} 覆写 X-Real-IP（不可伪造）故优先；
+ * X-Forwarded-For 首跳由客户端自报、可伪造，仅作回退。
+ */
+final class ClientIpResolver {
+
+    private ClientIpResolver() {
+    }
+
+    static String resolve(ServerWebExchange exchange) {
+        // 一律 trim：该返回值既是审计口径也是限流分桶 key，带空格的头会让 "1.2.3.4" 与 "1.2.3.4 "
+        // 落进不同桶，等于每请求换个后缀就能绕过 IP 限流。
+        String realIp = exchange.getRequest().getHeaders().getFirst("X-Real-IP");
+        if (realIp != null && !realIp.isBlank()) {
+            return realIp.trim();
+        }
+        String xff = exchange.getRequest().getHeaders().getFirst("X-Forwarded-For");
+        if (xff != null && !xff.isBlank()) {
+            // 用 indexOf/substring 而非 split：",".split(",") 返回长度 0 的数组（Java 丢弃尾随空串），
+            // 取 [0] 抛 AIOOBE。该异常在 AccessLogFilter 的 doFinally 回调里会被 Reactor 吞掉，
+            // 于是请求方只要发一个畸形头就能让自己的访问日志整条消失——审计日志不能有这种后门。
+            int comma = xff.indexOf(',');
+            String first = (comma >= 0 ? xff.substring(0, comma) : xff).trim();
+            if (!first.isEmpty()) {
+                return first;
+            }
+        }
+        if (exchange.getRequest().getRemoteAddress() != null) {
+            return exchange.getRequest().getRemoteAddress().getAddress().getHostAddress();
+        }
+        return "unknown";
+    }
+}

OpenBlog-gateway/src/main/java/com/yqz/openblog/gateway/filter/RateLimitFilter.java

@@ -76,7 +76,7 @@ public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
     private Mono<Void> applyRule(ServerWebExchange exchange, GatewayFilterChain chain,
                                  GatewayProperties.Rule rule) {
         return Mono.fromCallable(() -> {
-            String ip = clientIp(exchange);
+            String ip = ClientIpResolver.resolve(exchange);
             // 第 1 层防构造预检：指纹是自报 header，脚本可每请求伪造新指纹。同一 IP 窗口内新指纹超预算
             // → 判定轮换，直接拒绝（不计数、guard 内不落库）。仅 FP_IP 规则需要携带指纹信号。
             String fp = rule.getScope() == GatewayProperties.Scope.FP_IP
@@ -151,22 +151,6 @@ private String bearerToken(ServerWebExchange exchange) {
         return (auth != null && auth.startsWith("Bearer ")) ? auth.substring(7) : null;
     }
 
-    private String clientIp(ServerWebExchange exchange) {
-        // nginx 用 $remote_addr 覆写 X-Real-IP（不可伪造），优先使用；X-Forwarded-For 首跳是客户端可控的，仅作回退。
-        String realIp = exchange.getRequest().getHeaders().getFirst("X-Real-IP");
-        if (realIp != null && !realIp.isBlank()) {
-            return realIp;
-        }
-        String xff = exchange.getRequest().getHeaders().getFirst("X-Forwarded-For");
-        if (xff != null && !xff.isBlank()) {
-            return xff.split(",")[0].trim();
-        }
-        if (exchange.getRequest().getRemoteAddress() != null) {
-            return exchange.getRequest().getRemoteAddress().getAddress().getHostAddress();
-        }
-        return "unknown";
-    }
-
     @Override
     public int getOrder() {
         return -1;

OpenBlog-gateway/src/main/resources/application.yaml

@@ -50,6 +50,10 @@ openblog:
     secret: ${OPENBLOG_DEVICE_TOKEN_SECRET:}
     ttl-seconds: 604800
   gateway:
+    access-log:
+      # 每请求一条 INFO 访问日志：来源 IP / 方法 / 路径 / 状态码 / 耗时 / traceId。
+      # 只记 path 不记 query（防敏感参数落盘）。日志量敏感或压测时可置 false 关闭。
+      enabled: true
     auth:
       skip-paths:
         - /api/v1/auth/login

OpenBlog-gateway/src/test/java/com/yqz/openblog/gateway/filter/AccessLogFilterTest.java

@@ -0,0 +1,168 @@
+package com.yqz.openblog.gateway.filter;
+
+import ch.qos.logback.classic.Level;
+import ch.qos.logback.classic.Logger;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
+import com.yqz.openblog.gateway.config.GatewayProperties;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.mock.http.server.reactive.MockServerHttpRequest;
+import org.springframework.mock.web.server.MockServerWebExchange;
+import org.springframework.web.server.ServerWebExchange;
+import reactor.core.Disposable;
+import reactor.core.publisher.Mono;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class AccessLogFilterTest {
+
+    private final GatewayProperties props = new GatewayProperties();
+    private final AccessLogFilter filter = new AccessLogFilter(props);
+
+    private Logger filterLogger;
+    private ListAppender<ILoggingEvent> appender;
+
+    @BeforeEach
+    void attachAppender() {
+        filterLogger = (Logger) LoggerFactory.getLogger(AccessLogFilter.class);
+        appender = new ListAppender<>();
+        appender.start();
+        filterLogger.addAppender(appender);
+    }
+
+    @AfterEach
+    void detachAppender() {
+        filterLogger.detachAppender(appender);
+    }
+
+    @Test
+    void logsIpMethodPathStatusAndTraceId() {
+        ServerWebExchange exchange = MockServerWebExchange.from(
+                MockServerHttpRequest.get("/api/v1/articles?keyword=spring")
+                        .header("X-Real-IP", "203.0.113.7")
+                        .build());
+        // 单测直接调本过滤器，链上没有 TraceIdFilter：手动写入它本该留下的属性。
+        // 生产环境两者都是 GlobalFilter，TraceIdFilter(-3) 先于本过滤器(-4) 收尾，属性必然已就位。
+        exchange.getAttributes().put(TraceIdFilter.TRACE_ID_ATTR, "t-abc");
+        exchange.getResponse().setStatusCode(HttpStatus.OK);
+
+        filter.filter(exchange, ex -> Mono.empty()).block();
+
+        ILoggingEvent event = onlyEvent();
+        assertThat(event.getLevel()).isEqualTo(Level.INFO);
+        assertThat(event.getFormattedMessage())
+                .contains("ip=203.0.113.7")
+                .contains("method=GET")
+                .contains("path=/api/v1/articles")
+                .contains("status=200")
+                .contains("traceId=t-abc")
+                .contains("cost=");
+        // query string 刻意不入日志（防一次性令牌/邮箱等敏感参数落盘）
+        assertThat(event.getFormattedMessage()).doesNotContain("keyword=spring");
+    }
+
+    @Test
+    void prefersRealIpOverForwardedFor() {
+        // 与限流共用 ClientIpResolver：nginx 覆写的 X-Real-IP 优先于客户端可伪造的 XFF
+        ServerWebExchange exchange = MockServerWebExchange.from(
+                MockServerHttpRequest.get("/api/v1/x")
+                        .header("X-Forwarded-For", "1.2.3.4")
+                        .header("X-Real-IP", "9.9.9.9")
+                        .build());
+
+        filter.filter(exchange, ex -> Mono.empty()).block();
+
+        assertThat(onlyEvent().getFormattedMessage()).contains("ip=9.9.9.9");
+    }
+
+    @Test
+    void logsFailureAsWarningWhenChainErrors() {
+        ServerWebExchange exchange = MockServerWebExchange.from(
+                MockServerHttpRequest.get("/api/v1/x").header("X-Real-IP", "1.2.3.4").build());
+
+        filter.filter(exchange, ex -> Mono.error(new IllegalStateException("boom")))
+                .onErrorResume(e -> Mono.empty())
+                .block();
+
+        ILoggingEvent event = onlyEvent();
+        assertThat(event.getLevel()).isEqualTo(Level.WARN);
+        assertThat(event.getFormattedMessage())
+                .contains("gateway access failed")
+                .contains("ip=1.2.3.4")
+                .contains("boom");
+    }
+
+    @Test
+    void logsCancelledRequestAtInfo() {
+        ServerWebExchange exchange = MockServerWebExchange.from(
+                MockServerHttpRequest.get("/api/v1/x").header("X-Real-IP", "1.2.3.4").build());
+
+        // 模拟客户端提前断开：订阅后立即 dispose，链路以 ON_CANCEL 终止
+        Disposable subscription = filter.filter(exchange, ex -> Mono.never()).subscribe();
+        subscription.dispose();
+
+        ILoggingEvent event = onlyEvent();
+        // 取消属日常流量（前端切路由/关页面），记 INFO 以免刷屏淹没真正的失败
+        assertThat(event.getLevel()).isEqualTo(Level.INFO);
+        assertThat(event.getFormattedMessage())
+                .contains("gateway access cancelled")
+                .contains("ip=1.2.3.4");
+    }
+
+    @Test
+    void stillLogsWhenForwardedForIsCommaOnly() {
+        // 回归防线：",".split(",") 得到长度 0 的数组，老写法取 [0] 会抛 AIOOBE；
+        // 该异常在 doFinally 里被 Reactor 吞掉，请求方用畸形头就让自己的访问日志整条消失。
+        ServerWebExchange exchange = MockServerWebExchange.from(
+                MockServerHttpRequest.get("/api/v1/x").header("X-Forwarded-For", ",").build());
+
+        filter.filter(exchange, ex -> Mono.empty()).block();
+
+        assertThat(onlyEvent().getFormattedMessage()).contains("ip=");
+    }
+
+    @Test
+    void trimsWhitespaceSoRateLimitBucketsCannotBeRotated() {
+        // 带空格的头若原样入 key，"1.2.3.4 " 与 "1.2.3.4" 会落进不同限流桶
+        ServerWebExchange exchange = MockServerWebExchange.from(
+                MockServerHttpRequest.get("/api/v1/x").header("X-Real-IP", " 1.2.3.4 ").build());
+
+        filter.filter(exchange, ex -> Mono.empty()).block();
+
+        // 断言到下一个字段的边界，才能证明首尾空格真的被去掉了
+        assertThat(onlyEvent().getFormattedMessage()).contains("ip=1.2.3.4 method=");
+    }
+
+    @Test
+    void forwardsWithoutLoggingWhenDisabled() {
+        props.getAccessLog().setEnabled(false);
+        ServerWebExchange exchange = MockServerWebExchange.from(
+                MockServerHttpRequest.get("/api/v1/x").build());
+        AtomicBoolean forwarded = new AtomicBoolean(false);
+
+        filter.filter(exchange, ex -> {
+            forwarded.set(true);
+            return Mono.empty();
+        }).block();
+
+        assertThat(forwarded).isTrue();
+        assertThat(appender.list).isEmpty();
+    }
+
+    @Test
+    void runsOutsideTraceIdFilterSoTraceIdIsAvailable() {
+        // 顺序是契约的一部分：必须在 TraceIdFilter 外层，否则记录时 traceId 还没写入 exchange
+        assertThat(filter.getOrder()).isLessThan(new TraceIdFilter().getOrder());
+    }
+
+    private ILoggingEvent onlyEvent() {
+        assertThat(appender.list).hasSize(1);
+        return appender.list.get(0);
+    }
+}