《游戏服务端编程实践》18.3 行为分析与外挂防控

// file: ch18/behavior/behavior.go
// tier: L1
// verify: go test ./ch18/behavior/

// Package behavior 演示服务端行为统计的滑窗实现与分级判定。
//
// 统计值由服务端自己观测，例如单位时间位移、攻击次数、资源增量，
// 不接受客户端上报的“我移动了多远”。滑窗只负责算数：在
// [now-window, now] 内对样本求和并按阈值分级；证据留存与人工
// 复核属于上层流程。
package behavior

import (
	"sort"
	"sync"
	"time"
)

// Sample 是一条带时间戳的观测值。
type Sample struct {
	At    time.Time
	Value float64
}

// Snapshot 是一次滑窗查询的结果。
type Snapshot struct {
	Sum   float64
	Count int
}

// SlidingWindow 是按时间排序的样本集合。
//
// 样本量应与窗口长度和事件频率同阶。它适合每秒几十到几百条
// 的行为事件；如果频率高到十万级，应改成按秒预聚合的桶，
// 而不是在查询时遍历全部原始样本。
type SlidingWindow struct {
	mu      sync.Mutex
	span    time.Duration
	samples []Sample
}

// NewSlidingWindow 创建滑窗，span 小于等于 0 时按 1 秒处理。
func NewSlidingWindow(span time.Duration) *SlidingWindow {
	if span <= 0 {
		span = time.Second
	}
	return &SlidingWindow{span: span}
}

// Add 插入一条样本。时间戳不要求单调，内部按时间有序插入，
// 因此乱序到达的事件也能被正确统计。
func (w *SlidingWindow) Add(at time.Time, value float64) {
	w.mu.Lock()
	defer w.mu.Unlock()
	i := sort.Search(len(w.samples), func(i int) bool {
		return !w.samples[i].At.Before(at)
	})
	w.samples = append(w.samples, Sample{})
	copy(w.samples[i+1:], w.samples[i:])
	w.samples[i] = Sample{At: at, Value: value}
}

// Snapshot 返回 [now-span, now] 内的样本和与样本数。
//
// 早于窗口的样本会被永久移除；晚于 now 的样本保留但暂不参与
// 计算，避免客户端时钟或乱序事件把未来样本算进当前窗口。
func (w *SlidingWindow) Snapshot(now time.Time) Snapshot {
	w.mu.Lock()
	defer w.mu.Unlock()
	w.pruneLocked(now)
	start := 0
	end := len(w.samples)
	for end > start && w.samples[end-1].At.After(now) {
		end--
	}
	snap := Snapshot{Count: end - start}
	for _, s := range w.samples[start:end] {
		snap.Sum += s.Value
	}
	return snap
}

func (w *SlidingWindow) pruneLocked(now time.Time) {
	cutoff := now.Add(-w.span)
	i := sort.Search(len(w.samples), func(i int) bool {
		return w.samples[i].At.After(cutoff)
	})
	if i > 0 {
		w.samples = append(w.samples[:0], w.samples[i:]...)
	}
}

// Len 返回当前窗口内的样本数。
func (w *SlidingWindow) Len(now time.Time) int {
	return w.Snapshot(now).Count
}

// Reset 清空全部样本，用于处置结束后重新观察。
func (w *SlidingWindow) Reset() {
	w.mu.Lock()
	defer w.mu.Unlock()
	w.samples = w.samples[:0]
}

// Action 是分级处置结果。
type Action int

const (
	// ActionNone 表示未达到任何阈值。
	ActionNone Action = iota
	// ActionObserve 表示接近阈值，记录证据但不限制玩家。
	ActionObserve
	// ActionThrottle 表示超过限额，降低操作频率或进入审核队列。
	ActionThrottle
	// ActionBan 表示严重超过限额，进入封禁与人工复核流程。
	ActionBan
)

// String 返回稳定的日志名称，避免日志里出现裸整数。
func (a Action) String() string {
	switch a {
	case ActionObserve:
		return "observe"
	case ActionThrottle:
		return "throttle"
	case ActionBan:
		return "ban"
	default:
		return "none"
	}
}

// Policy 是行为判定阈值。
//
// Limit 是窗口内允许的累计值，例如 10 秒内最多 6000 单位位移。
// ObserveRatio 与 BanRatio 都是相对 Limit 的比例：达到 0.7 开始
// 观察，达到 1 限流，达到 2 封禁。阈值必须来自正常行为分布，
// 不能凭感觉拍一个整数。
type Policy struct {
	Window       time.Duration
	Limit        float64
	ObserveRatio float64
	BanRatio     float64
}

func (p Policy) normalized() Policy {
	if p.Window <= 0 {
		p.Window = 10 * time.Second
	}
	if p.Limit <= 0 {
		p.Limit = 1
	}
	if p.ObserveRatio <= 0 || p.ObserveRatio >= 1 {
		p.ObserveRatio = 0.7
	}
	if p.BanRatio <= 1 {
		p.BanRatio = 2
	}
	return p
}

// Verdict 是一次判定的完整结果，可直接写入审计日志。
type Verdict struct {
	Action  Action
	Sum     float64
	Rate    float64
	Ratio   float64
	Samples int
}

// Monitor 把滑窗与阈值策略组合起来。
type Monitor struct {
	mu     sync.Mutex
	policy Policy
	window *SlidingWindow
}

// NewMonitor 创建监控器；非法或缺失的字段会使用保守默认值。
func NewMonitor(p Policy) *Monitor {
	p = p.normalized()
	return &Monitor{policy: p, window: NewSlidingWindow(p.Window)}
}

// Observe 记录一次行为并返回分级结果。
//
// 负值按 0 处理：位移、伤害、资源增量都不应为负，若允许负值，
// 作弊者可以用负样本抵消前面的异常，把累计值压回阈值以下。
func (m *Monitor) Observe(at time.Time, value float64) Verdict {
	if value < 0 {
		value = 0
	}
	m.mu.Lock()
	defer m.mu.Unlock()
	m.window.Add(at, value)
	snap := m.window.Snapshot(at)
	ratio := snap.Sum / m.policy.Limit
	v := Verdict{
		Sum:     snap.Sum,
		Rate:    snap.Sum / m.policy.Window.Seconds(),
		Ratio:   ratio,
		Samples: snap.Count,
	}
	switch {
	case ratio >= m.policy.BanRatio:
		v.Action = ActionBan
	case ratio >= 1:
		v.Action = ActionThrottle
	case ratio >= m.policy.ObserveRatio:
		v.Action = ActionObserve
	default:
		v.Action = ActionNone
	}
	return v
}

// Policy 返回生效的策略副本，便于日志记录与排查。
func (m *Monitor) Policy() Policy {
	m.mu.Lock()
	defer m.mu.Unlock()
	return m.policy
}

// Reset 清空滑窗，通常在人工复核确认误报后调用。
func (m *Monitor) Reset() {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.window.Reset()
}

cd .local/checks/gs-practice-lab
gofmt -l ch18/behavior
go vet ./ch18/behavior/
go test ./ch18/behavior/ -count=1