Skip to content

About

交通违法处理全栈工程:Spring Boot 单体为主线,Flutter Web 为联调入口,集成 JWT/RBAC、Kafka + Debezium CDC、Elasticsearch、Ollama RAG、敏感数据加密与幂等账本;另含 Spring Cloud / Go / Quarkus 多架构实现与 k6 压测。

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

952 Commits

Folders and files

Repository files navigation

交通违法行为处理管理系统

CI License: Educational

面向交通违法处理、驾驶员服务和后台监管的全栈工程项目。项目最初来自毕业设计,当前已经按更工程化的方向持续演进:后端以 Spring Boot 单体为主线,同时保留 Spring Cloud、Go、Quarkus 等实现作为架构实验;前端以 Flutter Web 为主要联调入口。

当前主线关注点不再只是 CRUD 展示,而是围绕真实业务链路补齐权限、幂等、消息、检索、RAG、敏感数据保护和本地一键启动能力。

快速导航

入口 说明
一键启动 启动 Docker 依赖、后端、Flutter Web 和本地 AI 环境
后端包结构 Spring Boot 主后端的分层、领域包和命名规则
数据库设计 MySQL 表、角色、业务关联、敏感字段和 RAG 表设计
压测报告 2026-11-01 四后端 k6 / wrk(Spring / Cloud / Go / Quarkus);全 API 四端全过,Cloud 分段仅 ai_http_orchestration_ms 未达严格阈值
版本标签 v0.1.0 ~ v0.7.0 能力里程碑标签与对应文档
RAG 评测报告 Spring / Cloud / Go / Quarkus 四后端的 RAGAS 答案质量评测结果
脚本说明 启动、Debezium、AI 链路测试等脚本参数

完整目录

当前主线

模块 路径 状态
Spring Boot 主后端 finalAssignmentBackend 主线实现,承载认证、业务、审计、AI、RAG、CDC、ES
Flutter 前端 final_assignment_front 当前主要目检与联调入口,管理员端和驾驶员端共用
React 前端 final_assignment_front_react 保留的管理端实现
Spring Cloud 版本 finalAssignmentCloud 微服务拆分实验
Go 版本 final_assignment_backend_go Go 后端实验
Quarkus 版本 final_assignment_backend_quarkus Quarkus 后端实验

角色入口

角色 前端入口 主要职责
驾驶员 Flutter Web 驾驶员端 查看个人资料、违法详情、缴费、申诉、车辆登记、进度消息和地图
普通管理员 ADMIN Flutter Web 管理端 处理驾驶员、车辆、违法、罚款、扣分、申诉等业务
超级管理员 SUPER_ADMIN Flutter Web 管理端的技术治理入口 审查操作日志/登录日志、管理 RAG 资料、执行索引/回填等高风险操作

核心业务

  • 管理员端:驾驶员、车辆、违法行为、罚款、扣分、申诉、日志、系统配置管理
  • 驾驶员端:个人资料、违法详情、罚款缴纳、用户申诉、车辆登记、进度消息、地图入口
  • 超级管理员端:操作日志审查、RAG 资料录入、知识库索引与回填管理
  • AI 助手:驾驶员常见问题、管理员业务辅助、RAG 检索增强问答、前端页面跳转/填单能力探索
  • 实时链路:WebSocket/SSE、Kafka 异步消息、死信监听、业务进度推送

工程化能力

  • Spring Security + JWT + BCrypt 认证授权
  • ADMIN 与 SUPER_ADMIN 角色边界,普通管理员负责业务处理,超级管理员负责日志与 RAG 管理
  • MyBatis Plus + MySQL 核心数据访问
  • Redis + Caffeine 多级缓存
  • Kafka / Redpanda 异步事件、审计与幂等处理
  • Debezium + Kafka Connect 捕获 MySQL binlog,异步同步到 Elasticsearch
  • Elasticsearch 作为搜索读模型,避免将敏感明文直接写入搜索索引
  • Ollama + Spring AI / LangChain4j + GraalPy 支持本地 AI、联网搜索和 Python 脚本能力
  • RAG 支持手工录入、文档上传、表格上传、PDF 文本解析、分块、索引任务和检索
  • 敏感字段支持 AES-GCM 密文列与 HMAC blind-index 查询列
  • 统一 Kafka Listener 幂等处理器,减少重复反序列化、重复请求判断、成功/失败历史标记代码

近期工程化加固

2026-10 完成了一轮契约、并发/事务、安全和构建配置审查,主要变化:

  • 幂等账本统一:Cloud 共享 HistoryReserve / LedgerIdempotencyDecider,创建请求先落 PROCESSING 再执行副作用;重放返回 208,同键异内容或处理中返回 409,失败标记只允许从 PROCESSING 降级。
  • 实时链路:Cloud 网关改用 Redis 一次性 WebSocket 票据(POST /api/ws-ticket),付款状态变更在事务提交后仅推送给记录归属人,缺少归属人时跳过广播。
  • 认证与审计:公开注册固定授予 USER;内部服务经专用 DTO 传递密码哈希;password / salt 不再进入响应;审计日志的调用者由服务端绑定;Quarkus 启动时校验 JWT 签名与验签密钥一致。
  • 进度与用户契约:各后端 /api/progress 统一归属校验与幂等语义;用户更新改为部分字段合并,密码留空不会清空凭据;React 用户管理页补齐检索、创建、编辑、删除和字段校验。
  • 多后端契约对齐:Cloud RAG 文档列表支持分页;Go 端 RAG、违法与日志接口对齐共享契约;Quarkus 在 GraalPy 不可用时安全降级;本地启动脚本兼容 Windows 路径并重试网关端口。
  • 数据与前端健壮性:统一填充 createdAt / updatedAt,避免 MyBatis-Plus 显式写入 NULL;RAG 响应按 success/data 解包;表格行 key 去重;Flutter 页面正确释放滚动控制器。

云端专项加固(2026-10 第二轮)

  • 服务边界收敛:下线独立的搜索服务模块,Elasticsearch 索引设置随实体迁入共享库(设置文件与实体需同处一个 classpath);Nacos 配置按服务名隔离,清理搜索服务遗留的发现项。
  • 服务间鉴权收紧:内部调用统一携带 X-Internal-Service-Token,服务端校验后只授予 ROLE_INTERNAL;网关剥离客户端自带的该请求头,外部无法伪造内部身份;内部端点不再依赖管理员角色。
  • 幂等并发修复:幂等键唯一键冲突时改用加锁读(当前读)回读,避免在可重复读隔离级别下拿到过期快照而把并发请求误判为“首次请求”。
  • AI 链路加固:联网检索的查询词以变量绑定进 GraalPy 上下文,不再拼接进 Python 源码;推理超时改为可配置(ai.chat.timeout-millis,默认 30s),并区分超时、空响应、熔断拒绝等原因。
  • CI 覆盖:GitHub Actions 的 Cloud 作业接入 MySQL 8.0 并灌入 database/traffic.sql,对全部 Cloud 模块执行编译与测试;各模块补齐独立的测试配置。
  • 前端会话与角色:Flutter Web 端令牌改存 SharedPreferences(secure storage 在非安全上下文不可用);超管在管理端按角色集合语义判定为 ADMIN 的超集;外壳重定向参数带 requestId,同一页面连续跳转不再被当作重复消费;React 刷新令牌按 ApiResponse.data 解包。

双前端深度审查加固(2026-10 第三轮)

  • 认证续期:React 与 Flutter 都将刷新结果区分为成功、拒绝、瞬时失败;网络抖动或后端短暂不可用时保留本地会话并提示重试,只有服务端明确拒绝才清空令牌。React 刷新成功后同步 axios 默认头、AuthContext 角色与 WebSocket 票据;登出先清本地缓存与 React Query 数据,再异步吊销 refresh token。
  • 时间语义:React 统一按本地墙钟时间发送 YYYY-MM-DDTHH:mm:ss,不再把 LocalDateTime 当成 UTC 实例;请求历史、进度、日志等时间范围检索补齐起止时间,避免 UTC 容器下的整体偏移与恒空结果。
  • 列表完整性:React 抽出 listAllPages 自动翻页(用户、备份、仪表盘);Flutter 生成层新增 requestAllPages,车辆、违法、驾驶员、用户与备份列表不再静默截断在首页 20 条;申诉列表改为按页拉取全量数据,不再只扫描前 20 条违法记录。
  • 申诉工作流:驳回原因随工作流事件落库到 rejection_reason;APPEAL_REVIEWER 可正常进入申诉管理并执行审批;管理端与移动端共用同一状态机与幂等账本。
  • 低危收尾:Flutter 调试日志对 Authorization / Cookie 脱敏且默认不打印响应体;RAG 资料详情按请求序号丢弃过期响应并显示加载状态;AI 预填参数只消费一次;业务事件去重后按前缀失效 React Query 缓存。

四端契约对齐(2026-10 第四轮)

  • 申诉驳回原因:Cloud / Quarkus / Go 的 /api/workflow/appeals/{id}/events/{event} 统一接收可选 {reason},仅在目标状态为 Rejected 时写入 rejection_reason;Quarkus 与 Go 同步补齐 500 字上限校验。
  • 审核员与端点准入:Quarkus 工作流端点补入 APPEAL_REVIEWER;Go 申诉读写新增独立的 appeal_read / appeal_write 能力,并给 /api/workflow/* 补上类级角色门禁,普通用户不再能触发状态机。

架构速览

Flutter Web
  -> Spring Security + JWT
  -> Spring Boot 业务 API
  -> MyBatis Plus + MySQL
  -> Redis / Caffeine
  -> Redpanda(Kafka API) + Debezium
  -> Elasticsearch 搜索读模型
  -> Ollama / GraalPy / RAG

主线后端按“领域归属优先、框架分层其次”的方式组织:认证、业务、审计、管理、AI/RAG、CDC、搜索和共享基础设施各自收口。详细包结构见 finalAssignmentBackend/PACKAGE_LAYOUT.md。

压测与性能基线

全栈容器化与监控

compose.app.yml 在 docker-compose.yml(基础设施)之上加入应用与监控层,一条命令从零拉起完整系统:

cp compose.env.example .env   # 填入本地凭据(仅本地开发用)
docker compose -f compose.app.yml up -d --build
  • Spring 主后端(多阶段 Dockerfile,9080)与 Go 后端(18080)随 MySQL/Redis/ES/Kafka 一起启动
  • Prometheus(9091)按 observability/prometheus.yml 抓取两个后端的 /actuator/prometheus
  • Grafana(3301)自动装载 observability/grafana/dashboards/ 中的 SLO 看板与告警规则(observability/alerts.yml),指标口径与 docs/reliability/slo.md 对齐

CI(.github/workflows/ci.yml)覆盖四后端构建与测试、React typecheck+build、Flutter analyze+test,以及两个应用镜像的构建验证。

仓库中出现的所有密码/密钥(docker-compose.yml、k6 配置等)均为本地开发默认值,可通过 .env / PERF_* 环境变量覆盖,请勿在任何真实环境复用。

一键启动

推荐从仓库根目录使用脚本启动。

Windows:

scripts\start-all.bat

Linux / macOS:

sh scripts/start-all.sh

默认会尝试启动:

  1. Docker Desktop / Docker 服务
  2. scripts/dev-compose.yml 中的本地依赖
  3. Ollama
  4. Spring Boot 后端
  5. 交互选择的前端;Flutter Web 默认访问 http://127.0.0.1:3000,React Vite 默认访问 http://127.0.0.1:5173

如只启动前后端,可跳过 Docker/Ollama:

set START_LOCAL_SERVICES=false
scripts\start-all.bat

更多启动参数见 scripts/README.md。启动失败时脚本会打印最近日志、端口占用和 Docker Compose 状态;按 Ctrl-C 会停止前后端,并默认停止本项目 Docker Compose 依赖和本次脚本启动的 Ollama;完整日志位于 artifacts/startup/<timestamp>/。

React 前端通过 start-all -f react 启动时会自动把 VITE_API_BASE_URL 和 VITE_WS_BASE_URL 指向所选后端的对外地址;Spring Boot / Quarkus / Go / Spring Cloud 默认都走 8080(REST + WebSocket),Spring/Quarkus 的内部 REST 仍在 9080。脚本同时会把后端允许的 FRONTEND_URL 默认设置为所选前端 origin。

Go 后端默认使用 BACKEND_PORT=8080;如果 Windows 报告 8080 没有监听进程但不可绑定,脚本会自动回退到 18080、18081、18082,并同步 React / Flutter 的 API/WebSocket 目标。显式设置 BACKEND_PORT 时不会自动回退,候选端口可通过 GO_BACKEND_FALLBACK_PORTS 调整。Go runner 会默认把 GOCACHE 放到 artifacts/go-build-cache,并先构建到本次 artifacts/startup/<timestamp>/go-backend.exe 后再运行,避免系统 build cache 权限或旧 go run 残留进程影响一键启动。

Windows 下 start-dev.ps1 会在启动 Flutter 前清理仍占用 Web 端口(默认 3000)的残留 flutter run -d web-server 进程,避免上一次未停干净的开发服务器导致本次 Flutter 端口绑定失败;只会按命令行特征识别 Flutter 残留,其它占用端口的进程只会被提示、不会被误杀。前端就绪后默认会在浏览器中打开,可用环境变量 OPEN_BROWSER=false 关闭。

本地依赖

主线开发建议准备:

  • JDK 23 或 25
  • Maven 3.9+
  • Flutter 3+
  • Docker Desktop
  • 本地 MySQL 8.0+
  • Ollama

scripts/dev-compose.yml 提供:

  • Redis
  • Redpanda
  • Elasticsearch 9.4.1
  • Debezium Connect

Redpanda Kafka 默认暴露到本机 9092。Windows 的 Hyper-V/WSL 可能会保留该端口段,导致 Docker 报 ports are not available;start-all / start-env 会在 9092 不可绑定时自动回退到 19092,并同步后端 Kafka bootstrap 变量。手动运行 docker compose 时可显式设置 REDPANDA_KAFKA_HOST_PORT=19092,或用 REDPANDA_KAFKA_FALLBACK_PORTS 调整候选端口。

Elasticsearch 默认使用 Elastic 官方 GA 9.4.1。后端 Java client 由 Spring Boot 4.0.1 管理为 elasticsearch-java 9.2.2,可连接同主版本更高 minor 的服务端;如果需要调用 9.4 专属强类型 API,再单独升级客户端依赖。需要验证其他版本时,可用 ELASTICSEARCH_IMAGE=docker.elastic.co/elasticsearch/elasticsearch:<version> 覆盖本地镜像。

MySQL 默认按本机服务使用,连接库名为 traffic。密码、JWT、AI、加密密钥等通过环境变量注入。

关键环境变量

后端常用配置:

DB_USERNAME=root
DB_PASSWORD=your_password
BACKEND_URL=http://localhost:8080
JWT_SECRET=replace_with_a_real_secret

AI/RAG:

OLLAMA_ENABLED=true
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2
RAG_ENABLED=true
RAG_INDEXING_ENABLED=true
RAG_EMBEDDING_ENABLED=true
RAG_EMBEDDING_PROVIDER=ollama
RAG_EMBEDDING_MODEL=nomic-embed-text
RAG_EMBEDDING_DIMENSIONS=768
RAG_RETRIEVAL_ENABLED=true

敏感字段加密与 blind-index:

SENSITIVE_DATA_ENCRYPTION_ENABLED=true
SENSITIVE_DATA_ENCRYPTION_KEY=<base64-32-byte-key-or-strong-secret>
SENSITIVE_DATA_BLIND_INDEX_KEY=<separate-base64-32-byte-key-or-strong-secret>

后量子认证(可选,默认 HS256,不影响既有行为):

# 切 ML-DSA-65 启用后量子 JWT 签名;留空则仍为 HS256
JWT_ALGORITHM=ML-DSA-65
# ML-DSA 密钥(PEM,PKCS#8 私钥 / SPKI 公钥)。留空则启动生成临时密钥(重启失效,仅演示)
JWT_ML_DSA_PRIVATE_KEY=
JWT_ML_DSA_PUBLIC_KEY=
# 仅单体后端:refresh token 静态加密用的 ML-KEM-768 密钥(PEM)。留空则启动生成临时密钥
JWT_ML_KEM_PRIVATE_KEY=
JWT_ML_KEM_PUBLIC_KEY=

说明:JDK 25 自带 SunEC 不提供 ML-KEM/ML-DSA,已引入 Bouncy Castle。ML-DSA 签 JWT 因 jjwt 暂不支持,走自建 signing input + BC Signature;refresh token 由 ML-KEM 信封 + AES-256-GCM 静态加密存储。切换算法后既有 refresh token 失效,用户需重新登录;refresh_tokens.token 列已扩为 TEXT(见 finalAssignmentBackend/src/main/resources/db/refresh_tokens_alter_token_text.sql)。

CDC 到 Elasticsearch:

CDC_ELASTICSEARCH_ENABLED=true
CDC_ELASTICSEARCH_TOPIC_PATTERN=traffic\.traffic\.(driver_information|vehicle_information|sys_user)

MySQL CDC 到 Elasticsearch

当前搜索同步链路:

MySQL binlog
  -> Debezium Connect
  -> Redpanda(Kafka API)
  -> Spring Boot CDC Consumer
  -> Elasticsearch

本地 MySQL 需要开启 row-based binlog:

[mysqld]
server-id=223344
log-bin=mysql-bin
binlog_format=ROW
binlog_row_image=FULL

CDC 账号示例:

CREATE USER 'debezium'@'%' IDENTIFIED BY 'change_this_password';
GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'debezium'@'%';
FLUSH PRIVILEGES;

启动依赖并注册连接器:

docker compose -f scripts\dev-compose.yml up -d redpanda elasticsearch debezium-connect
$env:MYSQL_CDC_PASSWORD='change_this_password'
powershell -ExecutionPolicy Bypass -File scripts\debezium\register-mysql-cdc.ps1

敏感数据治理

身份证号、手机号、银行卡号等敏感数据采用三层处理:

  • MySQL 原业务列保留兼容旧逻辑
  • 新增 *_ciphertext 列保存密文
  • 新增 *_blind_index 列用于精确查询

后端启动时会通过 SensitiveDataSchemaMigration 检查并补齐密文字段、blind-index 字段和索引,然后对历史明文数据回填密文与 blind-index。查询层优先使用 blind-index 精确匹配,避免继续依赖明文等值查询。

Elasticsearch 文档只写入脱敏展示值或低风险字段,不写入完整身份证号、手机号和银行卡号。

Go 后端的 Gin access log 保留请求路径和状态信息,但省略 query string,避免聊天动作参数中的个人信息进入应用日志。不要把敏感信息放进 URL;浏览器、网关或反向代理可能有各自的访问日志。

RAG 资料录入

超级管理员可以通过 RAG 管理接口录入资料:

  • 手工文本
  • Markdown / TXT
  • CSV / TSV / JSON
  • DOCX
  • XLSX
  • PDF 文本型文件

当前 PDF 解析基于 PDFBox,只支持可提取文本的 PDF;扫描版图片 PDF 需要先 OCR。

资料入库后会写入 rag_document 和 rag_chunk,同时为每个 chunk 创建 rag_embedding_task。默认 embedding provider 为 Ollama nomic-embed-text,后台定时任务会把待处理 chunk 转为向量并写入 Elasticsearch rag_chunk_current alias,MySQL 侧只记录 embedding_model、embedding_hash 和处理状态。首次使用前需要先准备模型:

ollama pull nomic-embed-text

如需手动触发一批向量化任务,可由超级管理员调用:

POST /api/rag/admin/embedding/run?limit=25

RAG 数据表定义见:

  • finalAssignmentBackend/src/main/resources/rag/rag_schema.sql

Quarkus 后端的 RAG 与 Elasticsearch

final_assignment_backend_quarkus 与 Spring 主后端共用同一套 RAG 数据表,但拥有独立的 ES 索引与别名,避免不同后端的向量互相覆盖。四个后端的 API 档统一使用 768 维 nomic-embed-text,索引按后端隔离:

后端 物理索引 写别名
Spring 单体 rag_chunk_v1 rag_chunk_current
Spring Cloud rag_chunk_cloud_v1 rag_chunk_cloud_current
Go rag_chunk_go_768_v1 rag_chunk_go_current
Quarkus rag_chunk_quarkus_v1 rag_chunk_quarkus_current

project/etc/gozero-rag-live.yaml 是本地压测专用档,故意保留 deterministic-384 嵌入与 rag_chunk_go_live_* 索引,不计入上面的 768 维口径。 scripts/check-rag-config-parity.py 会校验上述权重、维度与索引隔离,配置漂移时退出码为 1。

Quarkus 的配置项如下:

项 值
物理索引 rag_chunk_quarkus_v1(rag.index.name)
写别名 rag_chunk_quarkus_current(rag.index.alias)
ES 地址 ELASTICSEARCH_HOST,默认 http://localhost:9200
向量 Ollama nomic-embed-text,768 维,dense_vector + cosine

检索链路为 BM25 + kNN 混合:ES 侧做粗过滤(PUBLIC / 角色 / 用户 / 部门),命中后回读 MySQL 执行严格收敛(分块必须是 EMBEDDED、文档必须是 READY、必须是知识库来源、ACL 必须放行)。 ACL 身份只来自服务端,POST /api/rag/query 请求体里的 roles / asRole 会被忽略。

嵌入队列的后台轮询默认关闭(rag.embedding.scheduler-enabled=false),由管理端显式驱动:

POST /api/rag/admin/index/migrate?indexName=rag_chunk_quarkus_v1   # 准备索引与别名
POST /api/rag/admin/embedding/run?limit=50                          # 消费一批嵌入任务
POST /api/rag/admin/embedding/requeue?limit=100                     # 重新排队失败/未嵌入的分块
POST /api/rag/admin/backfill?page=1&size=200                        # 知识文档回填

rag_embedding_task 表由 Spring / Go / Quarkus 共用,多后端同时跑嵌入 worker 会互相抢任务, 评测期间需停用其他后端的 worker。细节见 docs/ai/ragas/quarkus-rag-elasticsearch-2026-10-29.md。

RAG 答案质量评估

scripts/ragas 提供离线的 RAGAS 答案质量评估,与 CI 中的检索排序门禁互补:检索上下文来自真实 POST /api/rag/query,答案来自真实 POST /api/ai/chat/stream,由本地裁判模型打分。Spring 单体、Spring Cloud、Go、Quarkus 四个后端跑的是同一套脚本与同一份数据,下面是四者的统一评测报告。

评测方法

  • 数据集:30 道可回答题(覆盖全部 22 个 PUBLIC 语料块,含 4 道多跳)、3 道不可回答题、3 个 ACL 探针
  • 依赖:uv + CPython 3.12、ES / MySQL / Redis、Ollama(产品嵌入 nomic-embed-text、裁判 qwen2.5:7b、评测嵌入 bge-m3、答案模型 llama3.2)
  • 运行:后端以 AI_AGENT_ENABLED=false RAG_RETRIEVAL_ENABLED=true AI_GUARDRAIL_TOPIC_MODEL=qwen2.5:7b 启动,再执行 uv run ragas-eval all(默认 top-k=10,与四端交互式聊天默认值一致)
  • 可比性:四个后端共用同一份数据集与 golden 语料(dataset 292298fd…、golden d8d8659a…、corpus 42a579af…),模型指纹一致;混合检索统一为 BM25 0.8 / 向量 0.2、词法 rerank 0.15、候选深度倍率 3
  • 护栏口径:引用强制开启;生成后主题校验由 AI_GUARDRAIL_TOPIC_MODEL=qwen2.5:7b 显式开启,未配置时校验关闭
  • RAGAS_TARGET_LABEL 会写入 manifest 与报告环境表,用于区分同一数据集在不同后端的运行

四后端评测结果

质量指标(均值,列标题为 targets.json 阈值;原始产物在 artifacts/ragas/<run-id>/,已 gitignore):

后端 运行 ID topK Faithfulness ≥0.75 Relevancy ≥0.75 Context Precision ≥0.60 Context Recall ≥0.85 Answer Correctness ≥0.55 引用合规 ≥0.90 引用合规(含拒答,旧口径)
Spring 单体 baseline-20261029-topk10-verifier 10 0.9036 0.8900 0.9468 1.0000 0.7770 1.0000 0.9333
Spring 单体 20261029-refusal-verifier 5 0.9907 0.8521 0.9949 0.9815 0.7713 1.0000 0.9000
Spring Cloud cloud-ragas-20261029 5 0.9658 0.8435 0.9536 0.9821 0.7451 1.0000 0.9333
Go 20261029-go-parity-fixed 5 0.9667 0.8891 1.0000 1.0000 0.8108 1.0000 0.9000
Quarkus 20261029T054721Z-3b26af06 5 0.9315 0.8378 0.9889 0.9815 0.7902 1.0000 0.9000

Spring 单体给出两种 topK 口径:10 是当前默认值(与四端交互式聊天一致,DEFAULT_TOP_K=10),5 是历史基线。topK 决定候选深度(topK × 3)与 RRF 分数,两种口径的最终列表不是嵌套关系,不能逐题对照;Cloud / Go / Quarkus 三行本轮仍是 topK=5,跨口径同样不可直接比。要复现旧数必须显式传 --top-k 5。

「引用合规」的分母是已交付答案(剔除 provider 错误与护栏拒答);「含拒答(旧口径)」把拒答也计为不合规,等于 1 − 拒答率,只用于对齐 2026-10-30 之前的基线。引用强制生效时交付答案必然带引用,所以前者的 1.0000 表示「引用强制在四个后端都生效」,本身没有区分度;判断引用质量要看「含拒答」列与被拦下的题数。docs/ai/ragas/ 下的历史报告已按新口径重述,旧值在括号内保留;历史 artifacts/*/metrics.json 未回溯改写。

护栏与安全:

后端 topK 可评分覆盖 ≥0.90 不可答拒答 ≥0.80 ACL 泄漏 ≤0 上下文漂移 provider 错误 fallback ≤0.10 硬失败 被排除的题目
Spring 单体 10 28/30 (0.93) 3/3 (1.00) 0 0 0 0 无 a16 主题未覆盖;a19 无引用
Spring 单体 5 27/30 (0.90) 3/3 (1.00) 0 0 0 0 无 a10 无引用;a16、a28 主题未覆盖
Spring Cloud 5 28/30 (0.93) 3/3 (1.00) 0 0 0 0 无 a10、a20 无引用
Go 5 27/30 (0.90) 3/3 (1.00) 0 0 0 0 无 a24、a25、a28 主题未覆盖
Quarkus 5 27/30 (0.90) 3/3 (1.00) 0 0 0 0 无 a10 无引用;a28、a30 主题未覆盖

结论

  • 四个后端在纯 RAG 模式下五项 RAGAS 指标全部达标,引用强制在四端都生效(交付答案 100% 带引用,含拒答的旧口径均 ≥ 0.90);ACL 泄漏、上下文漂移、provider 错误与 fallback 全为 0,无硬失败。
  • 拒答是这一轮改造的重点:开启生成后主题校验后,四个后端对 3 道不可答题全部拒答(此前各后端都是 0/3);代价是可答题误拒 2~3 道(6%~10%),主题校验在多跳题上本就是边缘判定。
  • topK 从 5 提到 10 补上了检索侧的最后一处块级缺口:相关块召回 100%(topK=5 对照运行 20261029-refusal-verifier 为 98.33%,唯一缺口是 a02 的 c-fine-payment-guide),Context Recall 1.0000(5 时为 0.9815);top-10 命中数两种口径都是 30/30。代价是单题上下文从 379 token 涨到 763 token(预算 1200)、延迟中位数 692 ms → 811 ms。
  • 配对比较(两次都评分的 26 题)显示 Faithfulness −0.0750,但其中 −1.0(a17 漏「警告」)与 −0.5(a27 漏「拖移」)是模型缩答、−0.5(a11)是裁判假阴性——正确块在两种 topK 下都排第 1,检索没变。topK=10 不影响检索质量,只让上下文变长、模型更容易压缩答案。
  • 检索层等价,差异只在并列名次:Cloud 与 Spring 基线 36/36 同集合、35/36 同顺序(仅 a19 第 3/4 位互换);Go 与自身上一轮 36/36 完全一致、与 Spring 33/36 同集合、29/36 同顺序;Quarkus 两次运行 36/36 完全一致、与 Spring 35/36 同集合、31/36 同顺序。
  • 生成层存在采样噪声:同一构建两次运行的 Faithfulness 配对差可达 −0.0370(单题最大 −1.0),因此「与基线偏差 ≤ 0.03」只对检索侧指标(Context Precision / Context Recall)成立,判定回归要靠检索侧指标或多次运行的均值。
  • 答案过短是当前最稳定的质量短板:a07/a26/a09/a04 都是「忠实但不全」(Faithfulness ≥ 0.83,Answer Correctness 0.46~0.60)。另有裁判假阴性需人工兜底:a14 的答案与参考答案逐字等价,Answer Correctness 仍只有 0.4874。

护栏实现口径

  • RAG 提示词只向模型暴露 [n] 与正文;Ollama 默认 temperature=0.2;检索命中但答案无引用时先做一次引用修复重试,仍无引用才拒答(Agent 路径不重试)。纯 RAG 检索为空或失败仍会拒答;Agent 回合只有实际提供了 RAG 来源时才要求引用,工具回答不会因空引用集被误拒
  • 生成后主题校验由 AI_GUARDRAIL_TOPIC_MODEL 显式开启(例如 qwen2.5:7b):答案通过引用护栏后,再判断检索资料是否覆盖所问主题,未覆盖时拒答;未配置时校验关闭。AI_GUARDRAIL_TOPIC_TIMEOUT 默认 PT12S,超时或输出无法解析时放行
  • RAG 回合会清理模型输出中的检索内部标签;AI_GUARDRAIL_CITATION_ENFORCEMENT=false 只关闭引用强制,不关闭标签清洗。若清洗移除全部非空回答,会返回安全提示;清洗替换原答时会保留各 token 的 SSE payload metadata
  • Go 后端已移植同一套答案层防护(清洗 → 引用护栏与一次修复 → 主题校验),并新增同名 AI_AGENT_ENABLED / AI_GUARDRAIL_* 环境变量;与 Spring 的差异是 Go 的纯 RAG 引用护栏默认开启,检索为空或失败时会拒答,可显式关闭回退
  • Quarkus 后端已具备纯 RAG 对话链路与同一套答案层防护(清洗 → 引用护栏与一次修复 → 主题校验),裁判模型复用 OLLAMA_BASE_URL 下独立配置的 Ollama 模型;引用强制在 Quarkus 默认关闭(AI_GUARDRAIL_CITATION_ENFORCEMENT=false),评测时必须显式打开才能与基线可比

已知限制

  • DEPARTMENT 作用域语料当前对任何身份都不可见:Spring / Cloud 把部门身份折叠成字符串 "DEPARTMENT",而 ACL 按真实部门名(如 finance)匹配;这是 fail-closed(不泄漏),但 ACL 探针因此只覆盖 ROLE / USER
  • 主题校验判断的是「检索资料是否覆盖所问主题」,不是「资料是否蕴含答案中的具体事实」,两者不等价
  • 引用合规只检查格式与编号范围,不验证引用是否真的支持结论
  • 评测固定纯 RAG 模式(AI_AGENT_ENABLED=false),不代表默认 Agent 模式的表现
  • 端到端 RAGAS 需要 ES + MySQL + Redis + Ollama,不适合放进 CI;CI 里跑的是工具链自身的单元测试与跨后端配置一致性检查(job ai-quality-gates),检索排序门禁仍由 Java 侧承担

操作步骤与已知限制见 scripts/ragas/README.md。各轮报告:基线 baseline-2026-10-23.md 与默认 topK=10 重跑 baseline-2026-10-30-topk10.md,检索与答案质量改进 improvement-2026-10-23.md 与 improvement-2026-10-28.md,拒答改造 refusal-2026-10-29.md;Cloud 后端的移植与对齐 cloud-parity-2026-10-28.md 与本轮评测 cloud-ragas-2026-10-29.md;Go 后端的移植 go-parity-2026-10-29.md 与评测 go-ragas-2026-10-29.md;Quarkus 后端的纯 RAG 与拒答移植 quarkus-refusal-2026-10-29.md 与 ES 兼容、混合检索 quarkus-rag-elasticsearch-2026-10-29.md。

版本标签

仓库按能力里程碑打版本标签(语义化版本,均为附注标签),可直接检出任意里程碑:

标签 日期 里程碑 对应文档
v0.1.0 2026-10-16 RAG 检索门禁与接地护栏 docs/ai/ai-quality-gates.md
v0.2.0 2026-10-23 RAGAS 答案质量评测工具链与基线 docs/ai/ragas/baseline-2026-10-23.md
v0.3.0 2026-10-28 检索与答案质量改进(第二轮) docs/ai/ragas/improvement-2026-10-28.md
v0.4.0 2026-10-28 Spring Cloud 多后端拆分与 RAG 对齐 docs/ai/ragas/cloud-parity-2026-10-28.md
v0.5.0 2026-10-29 四后端拒答能力移植 docs/ai/ragas/refusal-2026-10-29.md
v0.6.0 2026-10-29 Quarkus Elasticsearch 兼容与混合检索 docs/ai/ragas/quarkus-rag-elasticsearch-2026-10-29.md
v0.7.0 2026-10-29 四后端 RAGAS 评测基线与评测报告 docs/ai/ragas/cloud-ragas-2026-10-29.md
git checkout v0.7.0            # 检出里程碑
git tag -n99 -l                # 查看全部标签及其说明

后端包结构

后端已经从单纯的平铺包逐步拆成按领域归属组织的结构。详细说明见:

数据库设计

数据库设计文档已按当前业务域重新整理:

重点关系:

  • sys_user 统一承载驾驶员用户、普通管理员、超级管理员账号
  • 驾驶员账号通过 driver_information.user_id 关联司机档案
  • 车辆通过 driver_vehicle 与驾驶员建立多对多绑定
  • 违法、罚款、扣分、申诉围绕 offense_record 串联
  • RAG 使用独立的 rag_document、rag_chunk、rag_embedding_task,向量写入 Elasticsearch;每个后端有自己的索引与别名(见上文「Quarkus 后端的 RAG 与 Elasticsearch」的表)

Spring Cloud 微服务版本

finalAssignmentCloud 是基于 Spring Cloud 的微服务拆分实验版本,将单体应用按业务域和技术职责拆分为 9 个独立服务。该版本保持与主线相同的业务能力,同时演示了云原生架构下的服务治理、分布式链路、配置中心和性能优化实践。

架构概览

Flutter Web / React
  ↓
API Gateway (Spring Cloud Gateway)
  ↓
├─ Auth Service (认证授权 JWT)
├─ User Service (用户角色权限)
├─ Traffic Service (违章罚款扣分申诉 + ShardingSphere 分库分表)
├─ Audit Service (审计日志)
├─ System Service (系统配置)
├─ RAG Service (文档检索问答)
  ↓
Common Library (共享基础设施)
  ↓
Nacos (服务注册与配置中心)
MySQL / Redis / Elasticsearch / Kafka

服务列表

服务 端口 职责 状态
Gateway 8080 API 网关、路由、限流、认证前置 ✅ 生产就绪
Auth 8081 JWT 签发、刷新、用户认证 ✅ 生产就绪
User 8082 用户管理、角色权限、驾驶员档案 ✅ 生产就绪
Traffic 8083 违章、罚款、扣分、申诉、车辆(含分库分表) ✅ 生产就绪
Audit 8084 操作日志、登录日志、审计查询 ✅ 生产就绪
System 18085 系统配置、字典管理 ✅ 生产就绪
AI 18086 对话编排、联网检索、模型推理 ✅ 生产就绪
Common - 共享库:安全、缓存、消息、工具 ✅ 生产就绪
RAG 18088 文档上传、分块、向量化、语义检索 ✅ 生产就绪

技术栈

Spring Cloud 生态

  • Spring Cloud Gateway - API 网关
  • Nacos Discovery - 服务注册与发现
  • Nacos Config - 分布式配置中心
  • OpenFeign - 声明式服务调用
  • Spring Cloud LoadBalancer - 客户端负载均衡

数据访问与存储

  • MyBatis Plus - ORM 框架
  • ShardingSphere JDBC 5.5.1 - 分库分表中间件(Traffic 服务)
  • MySQL 8.0 - 关系型数据库
  • Redis 7 - 分布式缓存
  • Elasticsearch 8.11 - 搜索引擎

消息与事件

  • Kafka / Redpanda - 异步消息队列
  • Debezium - CDC 数据变更捕获

安全与认证

  • Spring Security - 安全框架
  • JWT - 无状态认证
  • BCrypt - 密码加密

AI 与 RAG

  • Spring AI - AI 应用框架
  • Ollama - 本地 LLM 推理
  • Vector Embeddings - 语义向量化

分库分表设计

Traffic 服务使用 ShardingSphere JDBC 对高频表实现水平分片:

分片策略

  • offense_record - 按 record_id 哈希分 4 表
  • fine_record - 按 fine_id 哈希分 4 表
  • offense_payment - 按 payment_id 哈希分 4 表
  • appeal_acceptance - 按 acceptance_id 哈希分 4 表

优势

  • 单表数据量降低 75%,查询性能提升
  • 支持水平扩展到多个数据库实例
  • 业务代码无感知,完全由 ShardingSphere 路由

服务间通信

同步调用

  • OpenFeign - 声明式 REST 客户端
  • 服务发现 - 通过 Nacos 自动路由
  • 负载均衡 - 客户端负载均衡策略
  • 熔断降级 - 可选集成 Sentinel

异步消息

  • Kafka Topic - 按业务域拆分
  • 事件驱动 - 审计日志、状态变更、通知推送
  • 幂等处理 - 统一消息去重机制

配置中心

所有服务通过 Nacos Config 集中管理配置:

# 服务发现
spring:
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        namespace: ${NACOS_NAMESPACE:}
        group: ${NACOS_GROUP:DEFAULT_GROUP}
      config:
        server-addr: localhost:8848
        file-extension: yaml

配置优先级

  1. Nacos 动态配置(最高优先级,支持热更新)
  2. 本地 application.yml
  3. 环境变量覆盖

一键启动

方式 1:Docker Compose(推荐)

启动所有基础设施:

cd finalAssignmentCloud
docker compose up -d

包含服务:

  • MySQL 8.0 (3306)
  • Redis 7 (6379)
  • Elasticsearch 8.11 (9200)
  • Kafka + Zookeeper (9092)
  • Nacos 2.3 (8848)

等待所有服务健康检查通过(约 2-3 分钟):

docker compose ps

方式 2:IDEA 多服务启动

  1. 在 IntelliJ IDEA 中打开 finalAssignmentCloud 模块

  2. 按顺序启动(推荐启动顺序):

    • Common(无需启动,作为依赖)
    • Gateway
    • Auth
    • User
    • Traffic
    • Audit
    • System
    • AI
    • RAG(可选)
  3. 验证服务注册:访问 http://localhost:8848/nacos(用户名/密码:nacos/nacos)

方式 3:Maven 命令行启动

# 编译所有模块
mvn clean install -DskipTests -f finalAssignmentCloud/pom.xml

# 启动各服务(每个命令在独立终端)
cd finalAssignmentCloud/finalassignmentcloud-gateway && mvn spring-boot:run
cd finalAssignmentCloud/finalassignmentcloud-auth && mvn spring-boot:run
cd finalAssignmentCloud/finalassignmentcloud-user && mvn spring-boot:run
cd finalAssignmentCloud/finalassignmentcloud-traffic && mvn spring-boot:run
cd finalAssignmentCloud/finalassignmentcloud-audit && mvn spring-boot:run
cd finalAssignmentCloud/finalassignmentcloud-system && mvn spring-boot:run
cd finalAssignmentCloud/finalassignmentcloud-ai && mvn spring-boot:run
cd finalAssignmentCloud/finalassignmentcloud-rag && mvn spring-boot:run

性能测试

Spring Cloud 版本提供完整的 k6 性能测试套件,覆盖所有 9 个微服务的 25+ 个端点。

快速验证

cd k6-tests

# 烟雾测试(30秒,验证所有端点可用)
k6 run 01-smoke-test.js

# 负载测试(9分钟,50-100 并发用户)
k6 run 02-load-test.js

# 压力测试(15分钟,100-300 并发用户)
k6 run 03-stress-test.js

完整测试套件

cd k6-tests
./run-tests.sh

包含测试:

  • 烟雾测试 - 验证所有服务健康状态
  • 负载测试 - 模拟正常运营负载
  • 压力测试 - 测试系统极限
  • 关键流程测试 - 端到端业务流程
  • RAG 专项测试 - 文档检索性能
  • 分库分表测试 - ShardingSphere 性能验证

性能目标

指标 目标 可接受
P95 响应时间 < 500ms < 1s
P99 响应时间 < 1s < 2s
错误率 < 0.1% < 1%
吞吐量 > 500 req/s > 200 req/s

详细测试指南见 k6-tests/README.md。

环境变量

Spring Cloud 版本的关键配置:

# Nacos 服务发现与配置
NACOS_SERVER=localhost:8848
NACOS_NAMESPACE=
NACOS_GROUP=DEFAULT_GROUP
NACOS_USERNAME=
NACOS_PASSWORD=

# 数据库(各服务独立数据库,auth/user/traffic 共用 traffic 库)
AUTH_DB_URL=jdbc:mysql://localhost:3306/traffic_management?useSSL=false&serverTimezone=Asia/Shanghai
AUTH_DB_USERNAME=root
AUTH_DB_PASSWORD=your_password

# Redis
SPRING_DATA_REDIS_HOST=localhost
SPRING_DATA_REDIS_PORT=6379

# Elasticsearch
ELASTICSEARCH_URIS=http://localhost:9200

# Kafka
SPRING_KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# JWT(HS256 的密钥需为 Base64 编码;留空或弱值启动即失败)
JWT_SECRET_KEY=base64_encoded_secret
JWT_ACCESS_TOKEN_EXPIRATION=3600
JWT_REFRESH_TOKEN_EXPIRATION=604800

# 内部服务间鉴权(auth 与 user 服务必填,启动时 fail-fast 校验非空/非弱值)
# auth 经 feign 调用 user 的 /api/users/internal/** 端点时带 X-Internal-Service-Token 头
INTERNAL_SERVICE_TOKEN=replace_with_a_strong_internal_token

# 注册幂等指纹的 HMAC 密钥,缺省复用 INTERNAL_SERVICE_TOKEN;轮换会让历史幂等键失效
AUTH_FINGERPRINT_SECRET=

# 后量子 JWT 签名(可选,默认 HS256)
# 切 ML-DSA-65 时,在 jwt.ml-dsa.rotation.keys 配置版本化密钥环(含 kid 与 PEM 公私钥),
# auth 与所有下游服务需配置同一密钥环以验签
JWT_ALGORITHM=HS256

# RAG(可选)
RAG_ENABLED=true
RAG_DB_URL=jdbc:mysql://localhost:3309/rag?useSSL=false
OLLAMA_URL=http://localhost:11434

监控与运维

所有服务默认启用 Spring Boot Actuator:

# 健康检查
curl http://localhost:8080/actuator/health

# 服务信息
curl http://localhost:8080/actuator/info

# 查看注册的服务
curl http://localhost:8848/nacos/v1/ns/instance/list?serviceName=gateway-service

Docker 部署

完整的 Docker Compose 配置见 DOCKER_GUIDE.md,包含:

  • 所有基础设施服务的配置
  • 健康检查与依赖管理
  • 网络配置与端口映射
  • 数据卷管理
  • 故障排查指南

与单体版本对比

维度 Spring Boot 单体 Spring Cloud 微服务
架构 单一应用,所有功能在一个进程 9 个独立服务,按业务域拆分
部署 单个 JAR,简单直接 需要编排多个服务,复杂度高
扩展性 垂直扩展(加机器配置) 水平扩展(按服务独立扩展)
开发调试 简单,本地启动一个应用 需要启动多个服务,依赖复杂
技术栈 Spring Boot Spring Cloud + Nacos + ShardingSphere
分库分表 无 Traffic 服务实现 4 表分片
适用场景 中小型项目,快速迭代 大型项目,团队协作,高可用
性能 单进程调用,延迟低 跨服务调用,有网络开销
运维成本 低 高(需要服务编排、监控、配置管理)

项目状态

代码质量:     A+ (Perfect)
编译成功率:   100% (9/9 模块)
测试覆盖:     25+ 端点
测试代码:     1,350+ 行
部署配置:     Docker Compose 就绪
文档完整性:   100%
生产就绪:     是

技术文档

注意事项

  • Spring Cloud 版本适合学习微服务架构和分布式系统设计
  • 生产环境建议增加 Sentinel 熔断降级、Skywalking 链路追踪
  • 分库分表需要根据实际数据量和访问模式调整分片策略
  • RAG 服务依赖独立的 MySQL 数据库(端口 3309)
  • 所有服务需要正确配置 Nacos 地址才能完成服务注册

Go 高性能后端版本

final_assignment_backend_go 是基于 Go + Gin + go-zero 的高性能后端实验版本,保持与主线相同的业务能力,同时演示了 Go 生态下的高并发处理、AI 聊天流式响应、RAG 检索增强和轻量级微服务架构。

架构概览

Flutter Web / React
  ↓
Gin HTTP Router + JWT + Redis
  ↓
├─ 业务 API (Gin handlers)
│  ├─ 用户管理
│  ├─ 违法处理
│  ├─ 罚款扣分
│  ├─ 申诉审核
│  └─ 审计日志
├─ AI Chat 流式响应 (Server-Sent Events)
├─ WebSocket Ticket 认证
└─ RAG 语义检索 (go-zero RAG runtime)
  ↓
GORM + MySQL
Redis 多级缓存
Kafka 异步消息
Elasticsearch 向量检索
Ollama / OpenAI AI 提供商

技术栈

核心框架

  • Gin - 高性能 HTTP 框架
  • go-zero - 微服务工具包(配置、RAG runtime)
  • GORM - ORM 框架
  • Go 1.23+

数据访问与存储

  • MySQL 8.0 - 关系型数据库
  • Redis 7 - 分布式缓存与会话
  • Elasticsearch 9.4 - 向量检索与全文搜索

消息与容器

  • Kafka / Redpanda - 异步消息队列
  • Testcontainers - 集成测试容器编排
  • Docker - 本地依赖管理

AI 与 RAG

  • Ollama - 本地 LLM 推理
  • OpenAI API - 云端 AI 提供商
  • Elasticsearch Vector Search - 混合检索(BM25 + 向量 + 重排序)
  • gocolly - 网页爬取增强

安全与认证

  • JWT - 无状态认证
  • BCrypt - 密码加密
  • WebSocket Ticket - 一次性连接凭证

核心特性

1. AI 聊天流式响应

支持 Server-Sent Events (SSE) 流式输出,实时推送 AI 生成内容:

// POST /api/ai/chat/stream
{
  "message": "什么是闯红灯?",
  "role": "driver",
  "conversationId": "conv-123",
  "enableRag": true
}

// 响应流
data: {"type":"chunk","content":"闯红灯"}
data: {"type":"chunk","content":"是指"}
data: {"type":"done"}

特性:

  • 支持角色上下文(driver/admin/super_admin)
  • RAG 检索增强问答
  • 会话历史管理
  • 多 AI 提供商切换(Ollama/OpenAI)
  • 心跳保活机制

2. WebSocket 票据认证

一次性票据机制,用于 WebSocket 连接的安全认证:

// 1. 申请票据
POST /api/ws-ticket
Authorization: Bearer <jwt-token>
→ {"ticket": "wst_xxxxx", "expiresIn": 30}

// 2. 使用票据连接 WebSocket
ws://localhost:8080/eventbus?ticket=wst_xxxxx

特性:

  • 30 秒过期时间
  • 一次性使用
  • 票据状态追踪
  • 防重放攻击

3. RAG 检索增强

基于 go-zero RAG runtime 的混合检索:

// POST /api/rag/query
{
  "query": "如何缴纳罚款",
  "topK": 5
}

// 响应
{
  "results": [
    {
      "chunkId": "c-fine-payment-methods",
      "documentId": "doc-fine-payment",
      "title": "罚款缴纳方式",
      "sourceType": "MANUAL",
      "sourceId": "c-fine-payment-methods",
      "content": "罚款缴纳流程...",
      "bm25Score": 0.72,
      "vectorScore": 0.81,
      "finalScore": 0.85,
      "metadata": {}
    }
  ]
}

检索策略:

  • BM25 关键词匹配(权重 0.8)
  • 向量语义检索(权重 0.2),向量来自 Ollama nomic-embed-text(768 维)
  • RRF 融合 + 词法重排(重排词法权重 0.15)
  • 多源融合(手工录入/文档上传/网页爬取)

索引与身份:

  • Elasticsearch 索引 rag_chunk_go_768_v1 / 别名 rag_chunk_go_current,与 Spring 的 rag_chunk_current 隔离,避免两端向量互相覆盖
  • 检索身份只来自服务端 JWT:请求体里的 roles / asRole / userId / department 一律忽略; ACL 按 acl_scope + metadata 明细(角色 / 用户 / 部门)严格放行
  • 权重、候选倍率、RRF 常数与重排权重可用 RAG_RETRIEVAL_BM25_WEIGHT、 RAG_RETRIEVAL_VECTOR_WEIGHT、RAG_RETRIEVAL_CANDIDATE_MULTIPLIER、 RAG_RETRIEVAL_RRF_RANK_CONSTANT、RAG_RERANK_LEXICAL_WEIGHT 覆盖

4. 容器化依赖管理

使用 Testcontainers 自动管理本地依赖:

runner := docker.NewRunDocker()
runner.Init()  // 启动 Redis, Kafka, Elasticsearch
defer runner.StopContainers()

优势:

  • 无需手动安装依赖
  • 开发环境一致性
  • 集成测试隔离
  • 优雅启停管理

性能测试

Go 版本提供完整的 k6 性能测试套件,覆盖业务 API 和 AI/RAG 专项测试。

快速验证

cd final_assignment_backend_go/k6

# 基础测试(60秒,验证核心端点)
k6 run basic-test.js

# 负载测试(5分钟,模拟 10-50 并发用户)
k6 run load-test.js

# 压力测试(10分钟,100-300 并发)
k6 run stress-test.js

# 尖峰测试(验证突发流量)
k6 run spike-test.js

性能基线

指标 业务 API AI Chat 流式 RAG 检索
P95 响应时间 < 50ms < 2s < 500ms
P99 响应时间 < 100ms < 3s < 800ms
吞吐量 > 1000 req/s > 50 req/s > 200 req/s
错误率 < 0.1% < 1% < 0.5%

一键启动

方式 1:直接运行(自动启动容器)

cd final_assignment_backend_go
go run project/cmd/app/main.go

应用会自动:

  1. 启动 Docker 容器(Redis, Kafka, Elasticsearch)
  2. 初始化数据库连接
  3. 加载 AI 配置(Ollama/OpenAI)
  4. 启动 HTTP 服务(默认端口 8080)
  5. 优雅关闭时自动停止容器

方式 2:独立容器启动

# 仅启动依赖容器
cd final_assignment_backend_go
go test -v -run TestDockerInit ./project/configs/docker/...

# 然后启动应用
go run project/cmd/app/main.go

环境变量

Go 版本的关键配置:

# 数据库
DB_HOST=localhost
DB_PORT=3306
DB_NAME=traffic
DB_USERNAME=root
DB_PASSWORD=your_password

# Redis(容器自动管理,无需手动配置)
REDIS_HOST=localhost
REDIS_PORT=6379

# Kafka(容器自动管理)
KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# Elasticsearch(容器自动管理)
ELASTICSEARCH_URL=http://localhost:9200

# JWT
JWT_SECRET=replace_with_a_real_secret

# AI Provider(二选一)
AI_PROVIDER_TYPE=ollama  # 或 openai
AI_PROVIDER_URL=http://localhost:11434
AI_PROVIDER_MODEL=llama3.2

# OpenAI 配置(如果使用)
AI_PROVIDER_API_KEY=sk-xxxxx
AI_PROVIDER_MODEL=gpt-4

# RAG
RAG_ENABLED=true
RAG_EMBEDDING_MODEL=nomic-embed-text
RAG_EMBEDDING_DIMENSIONS=768
RAG_TOKEN_BUDGET=4000

# 流式响应
STREAM_KEEPALIVE_INTERVAL=15s

项目结构

final_assignment_backend_go/
├── project/
│   ├── cmd/app/          # 应用入口
│   ├── configs/          # 配置管理
│   │   ├── docker/       # Testcontainers 编排
│   │   ├── redis/        # Redis 配置
│   │   └── auth/         # JWT 认证
│   ├── internal/
│   │   ├── ai/           # AI 聊天管道
│   │   │   ├── chat_pipeline.go
│   │   │   ├── prompt_assembler.go
│   │   │   ├── role_resolver.go
│   │   │   └── web_search_service.go
│   │   ├── auth/         # WebSocket 票据
│   │   ├── config/       # AI 配置加载
│   │   ├── provider/     # AI 提供商工厂
│   │   ├── handler/      # HTTP 处理器
│   │   ├── service/      # 业务服务
│   │   ├── repo/         # 数据访问
│   │   ├── domain/       # 领域模型
│   │   ├── idempotency/  # 幂等处理
│   │   ├── middleware/   # 中间件
│   │   └── gozero/       # go-zero 集成
│   │       ├── config/   # go-zero 配置
│   │       ├── rag/      # RAG runtime
│   │       └── routes/   # go-zero 路由
│   ├── etc/              # 配置文件
│   │   └── gozero-api.yaml
│   └── deploy/rag/       # RAG 部署配置
├── k6/                   # k6 性能测试
├── database/             # 数据库迁移
├── constraints/          # 角色约束文档
└── go.mod

测试覆盖

# 单元测试
go test ./...

# 集成测试(自动启动容器)
go test -v ./project/internal/handler/...

# 测试覆盖率
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

当前测试覆盖:

  • AI 聊天管道测试
  • WebSocket 票据服务测试
  • RAG 检索测试
  • HTTP 处理器测试
  • 幂等执行器测试

与 Spring Boot / Spring Cloud 对比

维度 Spring Boot 单体 Spring Cloud 微服务 Go 高性能版本
启动时间 ~15-20s ~30s(单服务) ~2-3s
内存占用 ~500MB ~300MB/服务 ~50-100MB
并发性能 中(线程池) 中(分布式) 高(goroutine)
AI 流式响应 WebFlux WebFlux SSE 原生支持
部署复杂度 低 高 低
开发调试 简单 复杂 简单
生态成熟度 高 高 中
类型安全 中(反射) 中 高(编译时检查)
适用场景 全功能业务 大规模分布式 高并发、实时通信

项目状态

代码质量:     A (Good)
编译成功率:   100%
测试覆盖:     核心模块已覆盖
容器编排:     Testcontainers 就绪
文档完整性:   90%
生产就绪:     实验阶段

技术文档

注意事项

  • Go 版本适合学习 Go 生态和高并发编程
  • AI 提供商需要预先配置(Ollama 或 OpenAI)
  • Testcontainers 需要 Docker Desktop 运行
  • RAG 功能依赖 Elasticsearch 9.4+ 和向量化模型
  • 优雅关闭会自动停止由应用启动的容器
  • 生产环境建议使用独立的 Docker Compose 管理依赖

验证命令

后端编译:

cd finalAssignmentBackend
mvn -q -DskipTests test

后端测试默认使用本地 MySQL traffic_test,可通过 TEST_DB_URL、TEST_DB_USERNAME、TEST_DB_PASSWORD 覆盖连接信息:

cd finalAssignmentBackend
mvn -q test

Flutter 静态检查:

cd final_assignment_front
$env:DART_SUPPRESS_ANALYTICS='true'
C:\Users\tutic\Flutter\flutter\bin\flutter.bat analyze

Flutter Web 构建:

cd final_assignment_front
$env:DART_SUPPRESS_ANALYTICS='true'
C:\Users\tutic\Flutter\flutter\bin\flutter.bat build web

AI 链路冒烟测试:

powershell -ExecutionPolicy Bypass -File scripts\test-ai-chain.ps1

Go 后端编译与测试:

cd final_assignment_backend_go
go build ./...
go test ./...

Quarkus 后端编译与测试:

cd final_assignment_backend_quarkus
./gradlew --console=plain test

Go 后端性能测试:

cd final_assignment_backend_go\k6
k6 run basic-test.js

当前工程状态

  • 主展示链路:finalAssignmentBackend + final_assignment_front
  • 普通管理员与驾驶员端 UI 已统一暗色/亮色主题、侧边栏、AI 助手入口和业务页面样式
  • 司机档案、用户账户、车辆、违法、罚款、扣分、申诉的多表关联已经补齐主线查询
  • Kafka Listener 幂等样板已集中到公共处理器
  • 复杂治理监听器保留原业务审计语义后完成收口
  • RAG 已支持手工录入、多格式文件解析、chunk 向量化和 Elasticsearch 混合检索
  • 敏感字段密文列、blind-index 字段、查询改造和历史回填已经落地
  • Spring Cloud 微服务版本已完成 9 个服务拆分,支持 ShardingSphere 分库分表
  • Go 高性能版本已集成 AI 聊天流式响应、WebSocket 票据认证和 RAG 检索增强,支持 Testcontainers 自动容器管理

注意事项

  • 不要提交真实数据库密码、JWT 密钥、AI API Key 或加密密钥
  • 本地开发可用弱密钥,演示或生产必须使用独立强密钥
  • PDF RAG 当前不支持加密 PDF 和纯图片扫描 PDF
  • CDC 同步依赖 MySQL binlog 配置,未开启时不会有增量同步

About

交通违法处理全栈工程:Spring Boot 单体为主线,Flutter Web 为联调入口,集成 JWT/RBAC、Kafka + Debezium CDC、Elasticsearch、Ollama RAG、敏感数据加密与幂等账本;另含 Spring Cloud / Go / Quarkus 多架构实现与 k6 压测。

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages