shortlink：智能短链接与安全风控 Agent 平台

最准确的技术定位#

本项目的 Agent 实现不是自由运行的 ReAct 循环，也不是将业务控制权直接交给大模型，而是：

1
Java 业务事实
2
  + 受控 Tool Facade
3
  + Spring AI Alibaba StateGraph 显式节点编排
4
  + 确定性规则与指标计算
5
  + DeepSeek 解释与归纳
6
  + Checkpoint / Trace / PendingAction
7
  + Gateway 确定性策略执行

核心原则：

1. 业务事实由 Java 服务和数据库维护，LLM 不直接拥有数据库访问权。
2. Agent 只通过受控 Tool 查询业务数据，每次查询重新校验用户与分组归属。
3. 指标和风险分数由确定性逻辑计算，LLM 负责解释，不负责改写事实。
4. 短链跳转热路径不依赖 LLM，即使模型不可用，核心短链服务仍可独立运行。
5. 高风险动作受确定性规则和人工审核约束，禁止模型直接执行不可逆操作。

短链接业务#

• 单条短链接创建与批量创建
• Base62 短码生成与重复检测
• 短链接更新、有效期管理和分组迁移
• 短链接分页查询与分组内数量统计
• 短链接跳转与失效页处理
• 回收站移入、查询、恢复和移除
• 原始页面标题与站点图标提取

高并发与数据能力#

• Redis 短链映射缓存
• Redisson 分布式锁和读写锁
• 布隆过滤器防缓存穿透
• 空值缓存防止无效请求反复回源
• 缓存 TTL 与短链有效期对齐
• Redisson 延迟队列承接统计补偿
• ShardingSphere-JDBC 数据分片
• Sentinel 限流与流量治理

统计分析#

• PV、UV、UIP
• 日期、小时和星期分布
• 地域、省市和行政区统计
• 操作系统、浏览器、设备和网络统计
• Top IP 与访问明细
• 单条短链和分组级聚合统计
• 当日指标与历史累计指标

Agent 与风控#

• 基于 Spring AI Alibaba Graph 的投放分析工作流
• 基于 Spring AI Alibaba Graph 的安全风控工作流
• 受控 Tool Registry 与业务 Tool Facade
• Graph Checkpoint MySQL 持久化
• 节点级 Trace、耗时、数据来源和告警
• 风险画像批处理、分组画像和风险趋势
• 风险事件、快照、人工审核和动作审计
• Redis 风险策略发布
• Gateway 热路径限流、禁用、时间窗和 IP 拦截

五层架构#

服务边界#

短码生成#

创建短链时，系统将原始 URL 与随机 UUID 组合，计算哈希后转换为 Base62 短码。

生成阶段通过布隆过滤器检查候选短链是否可能已存在；若连续多次发生冲突，则主动失败，避免无界重试。

创建与缓存预热#

一次创建会同时完成：

1. 写入短链主体数据；
2. 写入完整短链到分组的跳转映射；
3. 将完整短链到原始 URL 的映射写入 Redis；
4. 将短链写入布隆过滤器；
5. 根据业务有效期设置缓存 TTL。

因此，新创建的短链在首次访问时即可直接命中缓存。

批量创建#

批量创建复用单条创建能力，并对每个原始 URL 独立处理：

• 单条失败不会中断整批任务；
• 成功结果统一汇总；
• 失败项记录日志，便于排查与补偿。

更新与分组迁移#

更新能力覆盖：

• 原始 URL
• 描述
• 永久有效或自定义有效期
• 所属分组
• 缓存失效与重建
• 历史统计归属迁移

当短链跨分组迁移时，系统通过 Redisson 读写锁协调跳转统计和归属变更，避免访问过程中产生跨分组数据错位。

回收站#

回收站提供：

• 移入回收站
• 分页查询
• 恢复短链
• 移除短链

业务停用与直接删除被拆分，降低管理误操作风险。

缓存治理策略#

跳转与统计解耦#

跳转是用户可感知的主链路，统计是内部附加链路。

当统计写入无法立即获得读锁时，系统将统计记录送入 Redisson 延迟队列，稍后重试，而不是持续阻塞用户重定向。

Harness 能力#

• 为每次 Run 生成独立 traceId
• 使用 sessionId 作为 Graph Thread ID
• 统一 Tool Registry
• 统一结构化响应
• 记录节点状态、耗时和数据来源
• 保存 Graph Checkpoint
• Tool、LLM 或 Checkpoint 异常时返回明确告警
• 内部接口 Token 校验
• 支持高风险动作进入 pendingActions

节点职责#

受控只读 Tool#

Tool 调用边界#

Agent Service 不直接读取业务数据库，而是：

1
Agent Graph
2
  -> Java Tool
3
  -> ShortLinkBusinessGateway
4
  -> Admin Internal Tool API
5
  -> Project 业务服务

Admin Internal Tool API 会：

1. 校验内部调用 Token；
2. 从可信请求头恢复当前用户上下文；
3. 重新校验目标 gid 是否属于当前用户；
4. 调用既有业务服务；
5. 将结构化结果返回 Agent。

事实与解释分离#

投放分析不是“把原始数据扔给模型自由计算”。

系统先基于 Tool 结果生成结构化卡片和派生洞察，再向 LLM 提交经过裁剪的事实上下文。Prompt 明确限制模型：

• 不重新计算或覆盖卡片指标；
• 不修改阈值、证据和原因码；
• 只解释可能原因、风险等级和建议；
• 对异常流量不输出确定性安全结论；
• 建议保持只读或低风险。

节点职责#

风险画像信号#

风险画像从多个时间窗口和访问维度构造指标：

检测器默认参考阈值：

风险分数和原因码由 Java 规则计算，LLM 不参与评分。

敏感信息治理#

进入 LLM、响应和 Checkpoint 前，安全风控链路会统一处理：

• 原始用户标识移除
• Token、密码、Secret 和 API Key 掩码
• JDBC 地址掩码
• IPv4 地址脱敏为前两段
• 嵌套 Map 和 List 递归清洗

风险画像批处理#

默认配置下：

• 每 2 小时执行一轮画像；
• 扫描近 7 天有访问的短链；
• 生成短链画像；
• 聚合同一批次的分组画像；
• 保存风险趋势和异常候选；
• 风险分析任务采用租约、重试和失败隔离配置。

自动动作边界#

自动执行仅开放 LIMIT_RATE，并且需要同时满足：

• 自动限流开关开启；
• 风险等级为 HIGH；
• 风险分数不低于默认阈值 80；
• 至少命中两个强风险原因；
• 当前目标不存在要求人工处理的策略建议。

默认限流参数：

1
60 requests / 60 seconds

以下动作必须经过人工确认：

• DISABLE_SHORT_LINK
• BLOCK_IP
• LIMIT_TIME_WINDOW

风险策略类型#

策略一致性#

Risk Policy Service 按以下顺序激活策略：

1. 将策略持久化为生效状态；
2. 发布到 Redis；
3. 保存动作审计。

若 Redis 发布失败，服务会将策略标记为失效并记录审计，避免数据库显示“已生效”，但 Gateway 实际没有执行。

A. 短链跳转链路#

1
Client
2
  -> Gateway
3
  -> Redis 风险策略
4
  -> Project
5
  -> Redis 短链映射
6
  -> MySQL 回源
7
  -> 访问统计
8
  -> 302 Redirect

B. Agent 分析链路#

1
Admin UI / Agent Console
2
  -> Admin 正式入口
3
  -> Agent Service
4
  -> Agent Harness
5
  -> Spring AI Alibaba Graph
6
  -> Tool Registry
7
  -> Admin Internal Tool API
8
  -> Project 业务事实
9
  -> DeepSeek 解释
10
  -> MySQL Checkpoint

C. 风控拦截链路#

1
Risk Profile / SecurityRisk Graph
2
  -> Risk Policy Service
3
  -> MySQL 策略与审计
4
  -> Redis 策略发布
5
  -> Gateway 热路径读取
6
  -> 确定性拦截

1. 传统业务与 Agent 能力解耦#

短链创建、跳转、统计和后台管理不依赖 LLM。Agent Service 可以独立部署、扩缩容或降级，不会成为公开跳转链路的单点依赖。

2. 两条显式 Graph，而不是自由循环#

投放分析和安全风控使用独立 StateGraph：

• 节点职责清晰；
• 状态流转可测试；
• Tool 调用可记录；
• 每个节点可追踪耗时；
• 执行结果可保存 Checkpoint；
• 异常可返回告警和降级结果。

3. 规则计算与 LLM 解释分层#

风险分数、指标卡、阈值和原因码由 Java 确定性逻辑计算。LLM 只负责解释和归纳，避免模型重新计算导致指标漂移。

4. Agent 不直连数据库#

Agent 通过 Admin Internal Tool API 获取业务事实，并复用现有用户上下文和分组归属校验，避免绕过权限体系。

5. 风险判断与热路径执行分离#

复杂画像和解释在后台链路完成，Gateway 只读取 Redis 并执行常数级判断，保证风险治理不会显著放大短链跳转延迟。

6. 多层缓存防护#

Redis、布隆过滤器、空值缓存、分布式锁和锁后二次检查共同保护 MySQL，应对缓存穿透和击穿。

7. 统计更新不阻塞主跳转#

短链跳转优先完成。统计写入遇到锁竞争时进入延迟队列，降低内部一致性竞争对用户体验的影响。

8. 风险动作可审计、可撤销#

策略、风险事件、人工审核和动作审计均持久化；Gateway 执行的是可查询、可停用的正式策略，而不是模型输出的一次性文本。

9. 敏感数据统一脱敏#

安全风控链路在 LLM、响应和 Checkpoint 三个出口使用同一清洗逻辑，减少某个出口遗漏造成的数据泄露风险。

10. 微服务与聚合部署并存#

生产环境可将 Admin、Project、Gateway 和 Agent Service 独立部署；本地和演示环境可通过 Aggregation 聚合 Admin 与 Project，降低启动复杂度。

Project API#

Agent API#

Internal Tool API#

Internal API 不应通过公网 Gateway 直接暴露。

微服务模式#

1
Client / Admin UI / Agent Console
2
                 |
3
                 v
4
             Gateway :8000
5
            /             \
6
           v               v
7
     Project :8001      Admin :8002
8
                            |
9
                            v
10
                      Agent Service :8010
11
                            |
12
              MySQL / Redis / DeepSeek

默认端口：

聚合模式#

aggregation 依赖 admin 与 project，用于将两者运行在同一 Spring Boot 进程中。

适用场景：

• 本地开发
• 演示环境
• 资源受限环境
• 希望减少服务数量但保留代码模块边界的部署方式

环境要求#

• JDK 17+
• Maven 3.8+
• MySQL 8+
• Redis 7+
• Nacos 2.x（完整微服务模式）
• PowerShell 7+（运行仓库 E2E 脚本）
• Docker（可选，用于脚本临时启动 Redis）

1. 获取代码#

1
git clone https://github.com/Jupiter363/shortlink.git
2
cd shortlink

2. 构建#

构建全部模块：

1
mvn clean package -DskipTests

运行全部测试：

1
mvn test

按模块构建：

1
mvn -pl project -DskipTests package
2
mvn -pl admin -DskipTests package
3
mvn -pl gateway -DskipTests package
4
mvn -pl agent-service -DskipTests package
5
mvn -pl aggregation -DskipTests package

3. 配置环境#

运行时至少需要配置：

• MySQL 数据源
• Redis 地址
• Nacos 地址与命名空间
• 短链默认域名
• 地域统计第三方 Key
• DeepSeek API Key
• Agent 内部调用 Token
• Agent Service 数据源
• Gateway 风险哈希盐

本地 Agent E2E 所需环境变量：

1
$env:DEEPSEEK_API_KEY = "..."
2
$env:AGENT_INTERNAL_TOKEN = "..."
3
$env:AGENT_DATASOURCE_URL = "jdbc:mysql://127.0.0.1:3306/short_link"
4
$env:AGENT_DATASOURCE_USERNAME = "..."
5
$env:AGENT_DATASOURCE_PASSWORD = "..."

4. 本地 Agent E2E#

仓库提供：

1
https://github.com/Jupiter363/shortlink/blob/cb24cd2968f0a78e34ac22056012b4156bf39fef/scripts/local-agent-e2e.ps1

脚本会：

1. 可选启动 Redis Docker 容器；
2. 构建 Project、Admin 和 Agent Service；
3. 启动三个服务；
4. 等待端口就绪；
5. 可选执行真实 DeepSeek Agent Smoke Test；
6. 将日志写入 target/e2e-logs。

执行：

1
.\scripts\local-agent-e2e.ps1 -StartRedis -RunSmoke -KeepRunning `
2
  -Username "demo" `
3
  -UserId "1" `
4
  -RealName "Demo User" `
5
  -Gid "default"

该脚本用于 Agent 联调，默认启动 Project、Admin 和 Agent Service，不负责启动完整 Gateway/Nacos 微服务环境。

5. 风险画像与策略拦截 E2E#

1
.\scripts\risk-profile-policy-e2e.ps1

该脚本用于验证：

• 风险画像生成
• 风险策略落库
• Redis 策略发布
• Gateway 策略读取与拦截

密钥管理#

以下内容不得提交到仓库：

• MySQL / Redis / Nacos 凭据
• DEEPSEEK_API_KEY
• AGENT_INTERNAL_TOKEN
• Agent 数据源配置
• 风险哈希盐
• 生产环境配置文件

推荐通过以下方式注入：

• Nacos 配置中心
• 环境变量
• Kubernetes Secret
• 云厂商 KMS / Secret Manager

内部接口安全#

Agent Service 和 Admin Internal Tool API 均使用：

1
X-Agent-Internal-Token

同时传递可信用户上下文：

1
X-Agent-Username
2
X-Agent-UserId
3
X-Agent-RealName

Admin 会重新构建 UserContext，并对 Tool 请求中的 gid 再次执行归属校验。

Gateway 可信代理#

只有在反向代理链受控时才应启用可信代理 IP 解析。否则伪造的转发 Header 可能影响 UIP、IP 限流和 IP 阻断判断。

LLM 故障边界#

模型未配置或调用失败时：

• Agent 返回明确告警或降级结果；
• 不伪造业务数据；
• 不影响短链创建和跳转；
• 不影响 Gateway 已发布风险策略的执行。