[新增] 添加自动 IP 组规则测试功能，支持在保存前验证 Expr 规则命中情况

docs/guide/usage.md

@@ -82,7 +82,7 @@ HTTPS 按域名绑定证书，而不是按整个网站统一强制启用。
 
 * WAF 页面维护全局规则组和自定义规则组。全局规则组始终应用到全部网站；自定义规则组可以在规则组内一键选择网站，也可以在网站详情的 `WAF` 分区绑定。
 * 点击 WAF 页面中的 **管理 IP 组** 可以进入独立 IP 组页面。手动 IP 组直接维护 IP/IP 段；自动 IP 组使用 Expr 规则按单个 IP 聚合请求日志并定时更新名单；订阅 IP 组可从远程文本或 JSON 源定时同步。
-* 自动 IP 组页面提供两个预设：单个 IP 请求数大于 100 且 404 占比不低于 80%；单个 IP 通过 IP 地址访问次数大于 50 且该访问占比大于 50%。保存后可点击 **立即执行** 验证规则效果，语法见 [WAF 自动 IP 组规则语法](./waf-ip-group-expr.md)。
+* 自动 IP 组页面提供两个预设：单个 IP 请求数大于 100 且 404 占比不低于 80%；单个 IP 通过 IP 地址访问次数大于 50 且该访问占比大于 50%。保存前可点击 **测试规则** 查看当前日志窗口命中的 IP，保存后可点击 **立即执行** 更新组内名单，语法见 [WAF 自动 IP 组规则语法](./waf-ip-group-expr.md)。
 * 在 WAF 规则组的黑白名单中，IP 维度既可以直接添加 IP/IP 段，也可以引用已有 IP 组。发布时 Server 会把启用 IP 组展开到 WAF 运行时配置。
 * `PoW` 是规则组内的一个配置 Tab，位于 `黑白名单` 与 `拦截返回` 之间，复用站点已有 PoW 执行逻辑，可将当前 PoW 配置应用到全部网站或当前规则组绑定的网站。
 * 网站详情页不再单独编辑 PoW 规则，只展示全局 WAF 规则组并绑定自定义 WAF 规则组。PoW 的启用范围和规则内容应回到 WAF 页面统一维护。

docs/guide/waf-ip-group-expr.md

@@ -156,6 +156,6 @@ IP 直连访问异常：
 
 ## 使用建议
 
-先用较短的回看窗口和较高阈值观察命中结果，再逐步调整阈值。自动 IP 组执行后会覆盖该组的 IP 列表；如果要长期保留某些地址，建议放入手动 IP 组，并在 WAF 规则组中同时引用手动组和自动组。
+先用较短的回看窗口和较高阈值观察命中结果，再逐步调整阈值。管理端 IP 组页面支持在保存前点击 **测试规则**，直接查看当前回看窗口内命中的 IP；自动 IP 组真正执行后会覆盖该组的 IP 列表。如果要长期保留某些地址，建议放入手动 IP 组，并在 WAF 规则组中同时引用手动组和自动组。
 
 自动 IP 组更新后不会立即改变 Agent 上的运行时配置。需要重新发布并激活配置版本，Agent 才会拉取新的 `waf_config.json`。

docs/reference/api.md

@@ -34,6 +34,7 @@ OpenFlare 的管理端 API 与 Agent API 都使用 JSON。
 | `GET` | `/api/waf/ip-groups` | 查询 IP 组列表 |
 | `GET` | `/api/waf/ip-groups/:id` | 查询单个 IP 组 |
 | `POST` | `/api/waf/ip-groups` | 创建 IP 组 |
+| `POST` | `/api/waf/ip-groups/test` | 测试自动 IP 组 Expr 规则，不保存配置，返回当前日志窗口内命中的 IP 列表 |
 | `POST` | `/api/waf/ip-groups/:id/update` | 更新 IP 组 |
 | `POST` | `/api/waf/ip-groups/:id/delete` | 删除 IP 组；已被规则组引用时会拒绝 |
 | `POST` | `/api/waf/ip-groups/:id/sync` | 立即同步订阅型 IP 组或立即执行自动型 IP 组 |

openflare_server/controller/waf.go

@@ -199,6 +199,19 @@ func SyncWAFIPGroup(c *gin.Context) {
 	respondSuccess(c, result)
 }
 
+func TestWAFIPGroupAutoConfig(c *gin.Context) {
+	var input service.WAFIPGroupAutoTestInput
+	if !bindJSON(c, &input) {
+		return
+	}
+	result, err := service.TestWAFIPGroupAutoConfig(input)
+	if err != nil {
+		respondFailure(c, err.Error())
+		return
+	}
+	respondSuccess(c, result)
+}
+
 func parseUintPathParam(c *gin.Context, name string) (uint, bool) {
 	id, err := strconv.ParseUint(c.Param(name), 10, 64)
 	if err != nil || id == 0 {

openflare_server/router/api-router.go

@@ -100,6 +100,7 @@ func SetApiRouter(router *gin.Engine) {
 			wafRoute.GET("/ip-groups", controller.ListWAFIPGroups)
 			wafRoute.GET("/ip-groups/:id", controller.GetWAFIPGroup)
 			wafRoute.POST("/ip-groups", controller.CreateWAFIPGroup)
+			wafRoute.POST("/ip-groups/test", controller.TestWAFIPGroupAutoConfig)
 			wafRoute.POST("/ip-groups/:id/update", controller.UpdateWAFIPGroup)
 			wafRoute.POST("/ip-groups/:id/delete", controller.DeleteWAFIPGroup)
 			wafRoute.POST("/ip-groups/:id/sync", controller.SyncWAFIPGroup)

openflare_server/service/waf_ip_group.go

@@ -110,6 +110,18 @@ type WAFIPGroupSyncResult struct {
 	Message    string         `json:"message"`
 }
 
+type WAFIPGroupAutoTestInput struct {
+	AutoConfig json.RawMessage `json:"auto_config"`
+}
+
+type WAFIPGroupAutoTestResult struct {
+	MatchedIPs      []string `json:"matched_ips"`
+	MatchedCount    int      `json:"matched_count"`
+	LookbackMinutes int      `json:"lookback_minutes"`
+	RuleCount       int      `json:"rule_count"`
+	TestedAt        string   `json:"tested_at"`
+}
+
 func ListWAFIPGroups() ([]WAFIPGroupView, error) {
 	groups, err := model.ListWAFIPGroups()
 	if err != nil {
@@ -195,6 +207,25 @@ func SyncWAFIPGroup(id uint) (*WAFIPGroupSyncResult, error) {
 	return syncWAFIPGroup(group, time.Now().UTC())
 }
 
+func TestWAFIPGroupAutoConfig(input WAFIPGroupAutoTestInput) (*WAFIPGroupAutoTestResult, error) {
+	config, err := parseWAFIPGroupAutoConfig(input.AutoConfig)
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now().UTC()
+	ips, err := evaluateParsedWAFIPGroupAutoConfig(config, now)
+	if err != nil {
+		return nil, err
+	}
+	return &WAFIPGroupAutoTestResult{
+		MatchedIPs:      ips,
+		MatchedCount:    len(ips),
+		LookbackMinutes: config.LookbackMinutes,
+		RuleCount:       len(config.Rules),
+		TestedAt:        now.Format(time.RFC3339),
+	}, nil
+}
+
 func SyncDueWAFIPGroups() error {
 	now := time.Now().UTC()
 	groups, err := model.ListDueWAFIPGroups(now)
@@ -397,17 +428,38 @@ func recordWAFIPGroupSyncFailure(group *model.WAFIPGroup, now time.Time, syncErr
 }
 
 func normalizeWAFIPGroupAutoConfig(raw json.RawMessage) (string, error) {
+	text := strings.TrimSpace(string(raw))
+	if text == "" {
+		text = "{}"
+	}
+	config, err := parseWAFIPGroupAutoConfig(json.RawMessage(text))
+	if err != nil {
+		return "", err
+	}
+	normalized, _ := json.Marshal(config)
+	return string(normalized), nil
+}
+
+func evaluateWAFIPGroupAutoConfig(raw string, now time.Time) ([]string, error) {
+	config, err := parseWAFIPGroupAutoConfig(json.RawMessage(raw))
+	if err != nil {
+		return nil, err
+	}
+	return evaluateParsedWAFIPGroupAutoConfig(config, now)
+}
+
+func parseWAFIPGroupAutoConfig(raw json.RawMessage) (wafIPGroupAutoConfig, error) {
 	text := strings.TrimSpace(string(raw))
 	if text == "" {
 		text = "{}"
 	}
 	var config wafIPGroupAutoConfig
 	if err := json.Unmarshal([]byte(text), &config); err != nil {
-		return "", errors.New("自动 IP 组配置必须是 JSON 对象")
+		return wafIPGroupAutoConfig{}, errors.New("自动 IP 组配置必须是 JSON 对象")
 	}
 	var object map[string]any
 	if err := json.Unmarshal([]byte(text), &object); err != nil || object == nil {
-		return "", errors.New("自动 IP 组配置必须是 JSON 对象")
+		return wafIPGroupAutoConfig{}, errors.New("自动 IP 组配置必须是 JSON 对象")
 	}
 	if config.LookbackMinutes <= 0 {
 		config.LookbackMinutes = defaultWAFIPGroupAutoLookbackMinutes
@@ -425,26 +477,17 @@ func normalizeWAFIPGroupAutoConfig(raw json.RawMessage) (string, error) {
 		rule.Name = strings.TrimSpace(rule.Name)
 		rule.Expr = strings.TrimSpace(rule.Expr)
 		if rule.Expr == "" {
-			return "", fmt.Errorf("自动规则 %d 的 Expr 表达式不能为空", i+1)
+			return wafIPGroupAutoConfig{}, fmt.Errorf("自动规则 %d 的 Expr 表达式不能为空", i+1)
 		}
 		if _, err := exprlang.Compile(rule.Expr, exprlang.Env(wafIPGroupAutoRuleEnv{}), exprlang.AsBool()); err != nil {
-			return "", fmt.Errorf("自动规则 %s Expr 无效: %w", displayWAFIPGroupAutoRuleName(rule, i), err)
+			return wafIPGroupAutoConfig{}, fmt.Errorf("自动规则 %s Expr 无效: %w", displayWAFIPGroupAutoRuleName(rule, i), err)
 		}
 		config.Rules[i] = rule
 	}
-	normalized, _ := json.Marshal(config)
-	return string(normalized), nil
+	return config, nil
 }
 
-func evaluateWAFIPGroupAutoConfig(raw string, now time.Time) ([]string, error) {
-	normalized, err := normalizeWAFIPGroupAutoConfig(json.RawMessage(raw))
-	if err != nil {
-		return nil, err
-	}
-	var config wafIPGroupAutoConfig
-	if err := json.Unmarshal([]byte(normalized), &config); err != nil {
-		return nil, err
-	}
+func evaluateParsedWAFIPGroupAutoConfig(config wafIPGroupAutoConfig, now time.Time) ([]string, error) {
 	if len(config.Rules) == 0 {
 		return []string{}, nil
 	}

openflare_server/service/waf_test.go

@@ -255,6 +255,41 @@ func TestSyncWAFIPGroupAutomaticExprRules(t *testing.T) {
 	}
 }
 
+func TestWAFIPGroupAutoConfigReturnsMatchedIPs(t *testing.T) {
+	setupServiceTestDB(t)
+
+	now := time.Now().UTC()
+	seedWAFNodeAccessLogs(t, now, "203.0.113.10", "app.example.com", 101, 81)
+	seedWAFNodeAccessLogs(t, now, "203.0.113.11", "198.51.100.10", 60, 0)
+	seedWAFNodeAccessLogs(t, now, "203.0.113.12", "app.example.com", 120, 10)
+
+	result, err := TestWAFIPGroupAutoConfig(WAFIPGroupAutoTestInput{
+		AutoConfig: json.RawMessage(`{
+			"lookback_minutes": 60,
+			"rules": [
+				{"name":"单 IP 404 高频扫描","expr":"request_count > 100 && status_404_ratio >= 0.8"},
+				{"name":"单 IP 直连访问异常","expr":"ip_host_count > 50 && ip_host_ratio > 0.5"}
+			]
+		}`),
+	})
+	if err != nil {
+		t.Fatalf("TestWAFIPGroupAutoConfig failed: %v", err)
+	}
+	if result.MatchedCount != 2 || result.RuleCount != 2 || result.LookbackMinutes != 60 {
+		t.Fatalf("unexpected test result: %+v", result)
+	}
+	want := map[string]bool{"203.0.113.10": true, "203.0.113.11": true}
+	for _, item := range result.MatchedIPs {
+		if !want[item] {
+			t.Fatalf("unexpected matched IP %s in %#v", item, result.MatchedIPs)
+		}
+		delete(want, item)
+	}
+	if len(want) != 0 {
+		t.Fatalf("missing matched IPs: %#v", want)
+	}
+}
+
 func TestWAFIPGroupAutomaticRejectsInvalidExpr(t *testing.T) {
 	setupServiceTestDB(t)
 

openflare_server/web/features/waf/api/waf.ts

@@ -4,6 +4,8 @@ import type {
   WAFRuleGroup,
   WAFRuleGroupPayload,
   WAFIPGroup,
+  WAFIPGroupAutoTestPayload,
+  WAFIPGroupAutoTestResult,
   WAFIPGroupPayload,
   WAFIPGroupSyncResult,
   WAFSiteRuleGroups,
@@ -84,3 +86,10 @@ export function syncWAFIPGroup(id: number) {
     method: 'POST',
   });
 }
+
+export function testWAFIPGroupAutoConfig(payload: WAFIPGroupAutoTestPayload) {
+  return apiRequest<WAFIPGroupAutoTestResult>('/waf/ip-groups/test', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+}

openflare_server/web/features/waf/components/ip-groups-page.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { ArrowLeft, Download, Plus, Save, Trash2 } from 'lucide-react';
+import { ArrowLeft, Download, Play, Plus, Save, Trash2 } from 'lucide-react';
 import { useRouter } from 'next/navigation';
 import { useEffect, useMemo, useState } from 'react';
 
@@ -16,10 +16,12 @@ import {
   deleteWAFIPGroup,
   getWAFIPGroups,
   syncWAFIPGroup,
+  testWAFIPGroupAutoConfig,
   updateWAFIPGroup,
 } from '@/features/waf/api/waf';
 import type {
   WAFIPGroup,
+  WAFIPGroupAutoTestResult,
   WAFIPGroupPayload,
   WAFIPGroupSubscriptionFormat,
   WAFIPGroupType,
@@ -101,14 +103,10 @@ function buildDraft(group: WAFIPGroup | null): IPGroupDraft {
 }
 
 function buildPayload(draft: IPGroupDraft): WAFIPGroupPayload {
-  let autoConfig: Record<string, unknown> = {};
-  if (draft.type === 'automatic') {
-    const parsed = JSON.parse(draft.auto_config_text || '{}') as unknown;
-    if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
-      throw new Error('自动配置必须是 JSON 对象。');
-    }
-    autoConfig = parsed as Record<string, unknown>;
-  }
+  const autoConfig =
+    draft.type === 'automatic'
+      ? parseAutomaticConfig(draft.auto_config_text)
+      : {};
   return {
     name: draft.name,
     type: draft.type,
@@ -123,6 +121,14 @@ function buildPayload(draft: IPGroupDraft): WAFIPGroupPayload {
   };
 }
 
+function parseAutomaticConfig(text: string): Record<string, unknown> {
+  const parsed = JSON.parse(text || '{}') as unknown;
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
+    throw new Error('自动配置必须是 JSON 对象。');
+  }
+  return parsed as Record<string, unknown>;
+}
+
 function appendAutomaticPresetRule(
   autoConfigText: string,
   rule: (typeof automaticPresetRules)[number],
@@ -161,6 +167,8 @@ export function WAFIPGroupsPage() {
   const [selectedID, setSelectedID] = useState<number | null>(null);
   const [draft, setDraft] = useState<IPGroupDraft>(emptyIPGroupDraft);
   const [feedback, setFeedback] = useState<FeedbackState | null>(null);
+  const [autoTestResult, setAutoTestResult] =
+    useState<WAFIPGroupAutoTestResult | null>(null);
 
   const groupsQuery = useQuery({
     queryKey: ['waf', 'ip-groups'],
@@ -234,6 +242,28 @@ export function WAFIPGroupsPage() {
     },
   });
 
+  const testMutation = useMutation({
+    mutationFn: testWAFIPGroupAutoConfig,
+    onSuccess: (result) => {
+      setAutoTestResult(result);
+      setFeedback({
+        tone: result.matched_count > 0 ? 'success' : 'info',
+        message:
+          result.matched_count > 0
+            ? `规则测试完成，命中 ${result.matched_count} 个 IP。`
+            : '规则测试完成，当前未命中任何 IP。',
+      });
+    },
+    onError: (error) => {
+      setAutoTestResult(null);
+      setFeedback({ tone: 'danger', message: getErrorMessage(error) });
+    },
+  });
+
+  useEffect(() => {
+    setAutoTestResult(null);
+  }, [draft.type, draft.auto_config_text, selectedID]);
+
   if (groupsQuery.isLoading) {
     return <LoadingState />;
   }
@@ -254,6 +284,17 @@ export function WAFIPGroupsPage() {
     }
   };
 
+  const testDraft = () => {
+    try {
+      testMutation.mutate({
+        auto_config: parseAutomaticConfig(draft.auto_config_text),
+      });
+    } catch (error) {
+      setAutoTestResult(null);
+      setFeedback({ tone: 'danger', message: getErrorMessage(error) });
+    }
+  };
+
   return (
     <div className="space-y-6">
       <PageHeader
@@ -328,6 +369,16 @@ export function WAFIPGroupsPage() {
           }
           action={
             <div className="flex flex-wrap gap-3">
+              {draft.type === 'automatic' ? (
+                <SecondaryButton
+                  type="button"
+                  disabled={testMutation.isPending}
+                  onClick={testDraft}
+                >
+                  <Play className="mr-2 h-4 w-4" />
+                  {testMutation.isPending ? '测试中...' : '测试规则'}
+                </SecondaryButton>
+              ) : null}
               {selectedGroup?.type === 'subscription' ||
               selectedGroup?.type === 'automatic' ? (
                 <SecondaryButton
@@ -516,6 +567,39 @@ export function WAFIPGroupsPage() {
                     }
                   />
                 </ResourceField>
+                {autoTestResult ? (
+                  <div className="space-y-3 rounded-2xl border border-[var(--border-default)] bg-[var(--surface-muted)] p-4">
+                    <div className="flex flex-wrap items-center justify-between gap-2">
+                      <div className="text-sm font-semibold text-[var(--foreground-primary)]">
+                        测试结果
+                      </div>
+                      <div className="text-xs text-[var(--foreground-secondary)]">
+                        回看 {autoTestResult.lookback_minutes} 分钟 · 规则{' '}
+                        {autoTestResult.rule_count} 条
+                      </div>
+                    </div>
+                    <InlineMessage
+                      tone={
+                        autoTestResult.matched_count > 0 ? 'success' : 'info'
+                      }
+                      message={
+                        autoTestResult.matched_count > 0
+                          ? `命中 ${autoTestResult.matched_count} 个 IP。`
+                          : '当前没有匹配到任何 IP。'
+                      }
+                    />
+                    {autoTestResult.matched_count > 0 ? (
+                      <div className="rounded-2xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-3">
+                        <div className="mb-2 text-xs font-medium text-[var(--foreground-secondary)]">
+                          命中 IP 列表
+                        </div>
+                        <pre className="overflow-x-auto whitespace-pre-wrap break-all text-sm text-[var(--foreground-primary)]">
+                          {autoTestResult.matched_ips.join('\n')}
+                        </pre>
+                      </div>
+                    ) : null}
+                  </div>
+                ) : null}
               </div>
             ) : (
               <ResourceField

openflare_server/web/features/waf/types.ts

@@ -95,3 +95,15 @@ export interface WAFIPGroupSyncResult {
   status: string;
   message: string;
 }
+
+export interface WAFIPGroupAutoTestPayload {
+  auto_config: Record<string, unknown>;
+}
+
+export interface WAFIPGroupAutoTestResult {
+  matched_ips: string[];
+  matched_count: number;
+  lookback_minutes: number;
+  rule_count: number;
+  tested_at: string;
+}

openflare_server/web/tests/unit/waf-ip-groups-page.test.tsx

@@ -204,6 +204,69 @@ describe('WAF IP groups', () => {
     expect(value).toContain('ip_host_count > 50 && ip_host_ratio > 0.5');
   });
 
+  it('tests automatic Expr rules before saving', async () => {
+    const testMock = vi.fn();
+
+    vi.stubGlobal(
+      'fetch',
+      vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input);
+        const method = init?.method?.toUpperCase() ?? 'GET';
+
+        if (url.includes('/waf/ip-groups/test') && method === 'POST') {
+          testMock(JSON.parse(String(init?.body)));
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                success: true,
+                message: '',
+                data: {
+                  matched_ips: ['203.0.113.10', '203.0.113.11'],
+                  matched_count: 2,
+                  lookback_minutes: 60,
+                  rule_count: 1,
+                  tested_at: '2026-06-01T00:00:00Z',
+                },
+              }),
+            ),
+          );
+        }
+
+        if (url.includes('/waf/ip-groups')) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({ success: true, message: '', data: [] }),
+            ),
+          );
+        }
+
+        return Promise.reject(new Error(`Unhandled fetch: ${url}`));
+      }),
+    );
+
+    renderWithProviders(<WAFIPGroupsPage />);
+
+    await screen.findByText('暂无 IP 组');
+    await userEvent.click(screen.getByRole('button', { name: /新建 IP 组/ }));
+    await userEvent.selectOptions(screen.getByLabelText('类型'), 'automatic');
+    await userEvent.click(screen.getByText('单 IP 404 高频扫描'));
+    await userEvent.click(screen.getByRole('button', { name: /测试规则/ }));
+
+    expect(await screen.findByText('命中 2 个 IP。')).toBeInTheDocument();
+    expect(screen.getByText('203.0.113.10')).toBeInTheDocument();
+    expect(screen.getByText('203.0.113.11')).toBeInTheDocument();
+    expect(testMock).toHaveBeenCalledWith({
+      auto_config: expect.objectContaining({
+        lookback_minutes: 60,
+        rules: [
+          expect.objectContaining({
+            expr: 'request_count > 100 && status_404_ratio >= 0.8',
+          }),
+        ],
+      }),
+    });
+  });
+
   it('opens IP group management from WAF page and references an IP group', async () => {
     vi.stubGlobal(
       'fetch',