feat(gateway): 护栏拦截事件落库 + 安全事件流（T4.B）

- store.GuardrailEvent 表(sundynix_guardrail_event) + AppendGuardrailEvent/ListGuardrailEvents - middleware.Guardrail(db)：命中 blocked/suspect 时 best-effort 落库 (actor/kind/reason/signals/method/path/ip，独立超时 ctx) - GET /api/v1/admin/guardrail-events：安全事件流(倒序，翻页) - store.clampPage 抽出分页归一(audit/guardrail 共用) - live：注入 "ignore all previous instructions" → 422 硬拦 + 事件留痕(kind=blocked) - DEPTH_ROADMAP T4.B 护栏事件打勾 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-02 09:31:31 +08:00
parent 16c67dcb4f
commit 9e43d07428
7 changed files with 104 additions and 8 deletions
@@ -168,7 +168,7 @@ RBAC 未做，暂以单管理员账号代理；概览口径必须是**系统级*
 ### [~] 🔴 T4.B 审计 / 可溯源 + 管理端聚合（推荐先做，内聚且喂管理端）
 - [x] `GET /api/v1/admin/overview`(RequireAdmin) 系统级聚合 ✅ —— 全平台用户/KB/任务/评测/模型态/prompt 覆盖/健康；概览页已切过去(5调用→2)，live 验证 users=7/kb 22/50 全平台口径。
 - [x] `audit_log` 表 + 中间件 ✅ —— `store.AuditLog` + `middleware.Audit(db)` 挂管理组 + prompt 激活/撤销 + HITL 审批；只审计变更类(POST/PUT/DELETE/PATCH)，best-effort 落库不拖垮主流程；`GET /admin/audit` 列表(倒序翻页)。live：PUT pricing / POST deactivate 留痕，GET 不记。
- [ ] 护栏拦截事件落库 `guardrail_event`（middleware/guardrail.go:29 现只打日志，无法复盘"谁触发多少次")| M
+- [x] 护栏拦截事件落库 `guardrail_event` ✅ —— Guardrail 中间件命中(blocked/suspect)best-effort 落库(actor/kind/reason/signals/path/ip) + `GET /admin/guardrail-events`；live：注入 payload→422 硬拦+事件留痕。
 - [ ] HITL 审批决定明细落库（现审批已进 audit_log 但只有 who/when/status，无 approve/reject 决定与理由；可 enrich audit Detail 或单独表）| S
 - [ ] 前端：管理端加「审计流 / 安全事件」页或概览接 /admin/audit（把留痕可视化）| S

@@ -45,6 +45,34 @@ func (h *Handler) AuditList(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"logs": out})
 }

+// GuardrailEvents: GET /api/v1/admin/guardrail-events?limit=&offset= —— 护栏命中安全事件流（倒序）。
+func (h *Handler) GuardrailEvents(c *gin.Context) {
+	limit, offset := 50, 0
+	if v := c.Query("limit"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			limit = n
+		}
+	}
+	if v := c.Query("offset"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			offset = n
+		}
+	}
+	rows, err := h.db.ListGuardrailEvents(c.Request.Context(), limit, offset)
+	if err != nil {
+		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+		return
+	}
+	out := make([]gin.H, 0, len(rows))
+	for _, e := range rows {
+		out = append(out, gin.H{
+			"id": e.ID, "actor": e.Actor, "kind": e.Kind, "reason": e.Reason,
+			"signals": e.Signals, "method": e.Method, "path": e.Path, "ip": e.IP, "at": e.CreatedAt,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"events": out})
+}
+
 // AdminOverview: GET /api/v1/admin/overview —— 管理端系统级聚合（控制塔口径）。
 // 区别于 stats/overview（桌面端个人工作台）：这里一律系统级——全平台用户/任务/评测/
 // 模型配置态/提示词控制面态/服务健康。Task/Eval 表无 owner 即全量；用户/KB/Doc 走全局计数。
@@ -3,6 +3,8 @@ package middleware

 import (
 	"bytes"
+	"context"
+	"encoding/json"
 	"io"
 	"log"
 	"net/http"
@@ -19,7 +21,8 @@ import (
 // 只检查带 JSON 体的写请求（POST/PUT）；文件上传(multipart)与 GET/SSE 不经此。
 // 输出护栏不在此做 —— Token 流为 SSE 实时流，网关缓冲会破坏流式，输出过滤应在
 // dispatcher 的 token 发射层（见 PROGRESS 路线图）。
-func Guardrail() gin.HandlerFunc {
+// 命中（blocked/suspect）除打日志外，best-effort 落库 guardrail_event 供安全溯源。
+func Guardrail(db *store.Postgres) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		if m := c.Request.Method; (m == http.MethodPost || m == http.MethodPut) &&
 			strings.HasPrefix(c.GetHeader("Content-Type"), "application/json") {
@@ -28,12 +31,14 @@ func Guardrail() gin.HandlerFunc {
 			res := guardrail.Inspect(body)
 			if res.Blocked {
 				log.Printf("[guardrail] 拦截 %s %s：%s", c.Request.Method, c.Request.URL.Path, res.Reason)
+				recordGuardrail(c, db, "blocked", res.Reason, res.Signals)
 				c.AbortWithStatusJSON(http.StatusUnprocessableEntity, gin.H{"error": "输入护栏拦截：" + res.Reason})
 				return
 			}
 			if res.Suspect { // 灰区：放行但打标，交 Dispatcher 的 LLM 分类器(Tier2)裁决
 				log.Printf("[guardrail] 灰区放行 %s %s：软信号 %v", c.Request.Method, c.Request.URL.Path, res.Signals)
 				c.Set("guardrail_suspect", true)
+				recordGuardrail(c, db, "suspect", res.Reason, res.Signals)
 			}
 			c.Request.Body = io.NopCloser(bytes.NewReader(body)) // 还原请求体供后续 handler 读取
 		}
@@ -41,6 +46,28 @@ func Guardrail() gin.HandlerFunc {
 	}
 }

+// recordGuardrail best-effort 落库一条护栏事件（独立超时 ctx，失败静默）。
+func recordGuardrail(c *gin.Context, db *store.Postgres, kind, reason string, signals []string) {
+	if db == nil {
+		return
+	}
+	uid, _ := c.Get(CtxUserID)
+	actor, _ := uid.(string)
+	sig := ""
+	if len(signals) > 0 {
+		if b, err := json.Marshal(signals); err == nil {
+			sig = string(b)
+		}
+	}
+	e := &store.GuardrailEvent{
+		Actor: actor, Kind: kind, Reason: reason, Signals: sig,
+		Method: c.Request.Method, Path: c.Request.URL.Path, IP: c.ClientIP(),
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	_ = db.AppendGuardrailEvent(ctx, e)
+}
+
 // RateLimit 基于 Redis 的会话级限流（按客户端 IP，每分钟上限）。
 // 上限经 RATE_LIMIT_PER_MIN 配置（缺省 120）；压测可调高。Redis 降级时始终放行，不阻断业务。
 func RateLimit(cache *store.Redis) gin.HandlerFunc {
@@ -25,7 +25,7 @@ func New(db *store.Postgres, cache *store.Redis, bus *nats.Bus, blobStore *blob.
 	r.Use(cors())                                 // 桌面端/浏览器跨源访问
 	r.Use(middleware.RateLimit(cache))
 	r.Use(middleware.Auth())      // 解析 Bearer JWT，注入已验证 userID（非阻断）
-	r.Use(middleware.Guardrail()) // Harness: Input Guardrail
+	r.Use(middleware.Guardrail(db)) // Harness: Input Guardrail（命中落库 guardrail_event）

 	h := handler.New(db, cache, bus, blobStore)

@@ -96,7 +96,8 @@ func New(db *store.Postgres, cache *store.Redis, bus *nats.Bus, blobStore *blob.
 			admin.PUT("/pricing", h.SavePricing) // 设置某模型输入/输出单价
 			admin.GET("/status", h.AdminStatus)      // 服务状态：基建/服务探活 + MCP 工具注册
 			admin.GET("/overview", h.AdminOverview)  // 系统级聚合：全平台用户/任务/评测/模型态/提示词态/健康
-			admin.GET("/audit", h.AuditList)         // 敏感操作审计流（倒序，翻页）
+			admin.GET("/audit", h.AuditList)                  // 敏感操作审计流（倒序，翻页）
+			admin.GET("/guardrail-events", h.GuardrailEvents) // 护栏命中安全事件流（倒序，翻页）
 		}
 	}
 	return r
@@ -15,13 +15,38 @@ func (p *Postgres) ListAudit(ctx context.Context, limit, offset int) ([]AuditLog
 	if p.db == nil {
 		return nil, errStoreDisabled
 	}
+	limit, offset = clampPage(limit, offset)
+	var out []AuditLog
+	err := p.db.WithContext(ctx).Order("created_at desc").Limit(limit).Offset(offset).Find(&out).Error
+	return out, err
+}
+
+// AppendGuardrailEvent 追加一条护栏命中（best-effort）。
+func (p *Postgres) AppendGuardrailEvent(ctx context.Context, e *GuardrailEvent) error {
+	if p.db == nil || e == nil {
+		return errStoreDisabled
+	}
+	return p.db.WithContext(ctx).Create(e).Error
+}
+
+// ListGuardrailEvents 倒序列出护栏事件（管理端安全事件流）。
+func (p *Postgres) ListGuardrailEvents(ctx context.Context, limit, offset int) ([]GuardrailEvent, error) {
+	if p.db == nil {
+		return nil, errStoreDisabled
+	}
+	limit, offset = clampPage(limit, offset)
+	var out []GuardrailEvent
+	err := p.db.WithContext(ctx).Order("created_at desc").Limit(limit).Offset(offset).Find(&out).Error
+	return out, err
+}
+
+// clampPage 归一分页参数：limit ∈ [1,200]（默认 50），offset ≥ 0。
+func clampPage(limit, offset int) (int, int) {
 	if limit <= 0 || limit > 200 {
 		limit = 50
 	}
 	if offset < 0 {
 		offset = 0
 	}
-	var out []AuditLog
-	err := p.db.WithContext(ctx).Order("created_at desc").Limit(limit).Offset(offset).Find(&out).Error
-	return out, err
+	return limit, offset
 }
@@ -57,3 +57,18 @@ type AuditLog struct {
 }

 func (AuditLog) TableName() string { return "sundynix_audit_log" }
+
+// GuardrailEvent 是一次输入护栏命中（硬拦截 blocked / 灰区 suspect）。
+// 由 Guardrail 中间件命中时 best-effort 写入；供安全溯源"谁触发多少次护栏"。
+type GuardrailEvent struct {
+	BaseModel
+	Actor   string `gorm:"size:64;index"` // 操作者 uid（未登录留空）
+	Kind    string `gorm:"size:16;index"` // blocked（硬拦）/ suspect（灰区放行）
+	Reason  string `gorm:"size:256"`      // 拦截原因（blocked）
+	Signals string `gorm:"type:text"`     // 命中软信号 JSON 数组（suspect）
+	Method  string `gorm:"size:8"`
+	Path    string `gorm:"size:256"`
+	IP      string `gorm:"size:64"`
+}
+
+func (GuardrailEvent) TableName() string { return "sundynix_guardrail_event" }
@@ -66,7 +66,7 @@ func OpenPostgres(dsn string) *Postgres {
 	migrateLegacyIntIDs(db)
 	migrateDocLinkToID(db)

-	if err := db.AutoMigrate(&User{}, &Task{}, &Eval{}, &LLMModel{}, &KB{}, &Doc{}, &Agent{}, &DocLink{}, &Pricing{}, &Prompt{}, &AuditLog{}); err != nil {
+	if err := db.AutoMigrate(&User{}, &Task{}, &Eval{}, &LLMModel{}, &KB{}, &Doc{}, &Agent{}, &DocLink{}, &Pricing{}, &Prompt{}, &AuditLog{}, &GuardrailEvent{}); err != nil {
 		log.Printf("[store] postgres AutoMigrate 失败，降级运行: %v", err)
 		return &Postgres{}
 	}