SwissQL

SwissQL 是 Mopheus 的数据库访问层组件。它不直接处理工单或调度智能体，而是解决一个更基础的问题：让 AI 智能体安全地访问和操作数据库。

在没有 SwissQL 的情况下，智能体需要使用各种原生数据库客户端：用 psql 连接 PostgreSQL，用 sqlplus 连接 Oracle，用 mysql 连接 MySQL，用 gsql 连接 openGauss……每个数据库一套工具、一套语法、一套权限配置。这对人类 DBA 来说已经够麻烦了，对 AI 智能体来说更是灾难：

• 权限完全不可控 — 原生客户端的权限就是数据库用户的权限，智能体一旦拿到连接串，理论上可以执行任何 SQL
• 无法审计 — 谁执行了什么 SQL、是否被拦截，无从追踪
• 跨数据库成本极高 — 每新增一种数据库类型，智能体就要学习新的 CLI 和方言

SwissQL 用一个统一的 CLI 和 REST API 覆盖所有数据库类型，同时提供连接 profile 管理、SQL 规则引擎和审计日志，让 AI 管理数据库这件事变得可控、可审计、可扩展。

核心能力

统一数据库访问

SwissQL 通过 JDBC 支持 PostgreSQL、Oracle、MySQL、SQL Server、openGauss 等多种数据库。智能体仍然需要知道它正在操作的是哪种数据库（因为诊断方法、系统表和 SQL 方言各不相同），但不需要为每种数据库学习不同的连接工具和参数格式——无论底层是什么数据库，都通过相同的 swissql exec --profile-id <id> 接口连接，profile 已经封装了驱动、地址、凭据等连接细节。

SwissQL 内置支持 PostgreSQL、Oracle、MySQL（含 MariaDB）三种数据库。更重要的是：只要数据库提供 JDBC 驱动并支持 SQL 操作，SwissQL 就能支持——包括但不限于 SQL Server、SQLite、openGauss、达梦、人大金仓、H2 等数据库。

扩展支持任何 JDBC 数据库非常简单：将数据库厂商提供的 JDBC 驱动 JAR 和一个描述文件 driver.json 放入 SwissQL 后端的 jdbc_drivers/<dbType>/ 目录，无需重启服务即可生效。

连接 Profile 管理

连接信息不以明文连接串散落在各处，而是以 profile 的形式集中管理在 SwissQL 后端。每个 profile 包含：

• 数据库类型（postgres、oracle、mysql 等）
• 连接地址（DSN 或 JDBC URL）
• 凭据（支持环境变量引用、本地文件存储或内联）
• 标签（如 env:production、cluster:pg-prod、role:primary）

智能体在执行 SQL 时只需引用 profile ID（如 --profile-id prod-pg-primary），无需接触真实的密码和连接地址。profile 可以在 SwissQL 后端统一测试连通性、启用/禁用、批量导入（支持从 DBeaver 项目导入）。

SQL 规则引擎

SwissQL 内置 YAML 驱动的 SQL 规则引擎，在 SQL 执行前进行拦截检查。支持：

• 白名单/黑名单 — 按语句类型（SELECT/INSERT/UPDATE/DELETE/DROP 等）允许或拒绝
• 正则匹配 — 对 SQL 文本进行正则匹配，拦截危险模式
• 按标签过滤 — 不同 profile 可以应用不同的规则集
• 写操作控制 — 默认只读，智能体必须显式声明 --allow-write 才能执行写入操作

规则引擎和写操作控制是两个独立的层面。规则一旦配置，就会被强制执行，不存在绕过的方式。例如，你可以在规则中配置：所有标记为 env:production 的 profile，禁止执行 DROP TABLE 和 DELETE（不带 WHERE）。即使智能体请求了写权限（--allow-write），违反规则的 SQL 仍然会被拦截。

这种分层设计的好处：写操作控制让你决定智能体是否可以修改数据，规则引擎让你决定哪些 SQL 绝对不可执行。

SQL 审计日志

每条通过 SwissQL 执行的 SQL 都会被记录：执行时间、profile、SQL 内容、执行结果、是否被规则拦截。

更关键的是，审计日志还支持两项关联追踪：

• 执行者身份 — 通过 X-Executor header 标记是谁执行的（智能体名称、人类工程师、CI 脚本等）。未标记时默认显示 anonymous
• 工单关联 — 通过 X-Ticket-Id header 将多个 SQL 请求关联到同一个工单。结合 Mopheus 的工单系统，可以在审计日志中追溯"工单 MO-123 触发了哪些 SQL"

审计日志可以输出到：

• 标准输出（带 [AUDIT] 前缀）
• 独立日志目录（持久化文件）
• 完全关闭（通过环境变量）

审计日志是排查"智能体做了什么"的第一现场，也是安全合规的必备数据。

架构

Mopheus 智能体 / CLI 用户
        │
        ▼
┌─────────────────────┐
│   SwissQL CLI       │  ← 统一命令行入口
│   swissql exec ...  │
└─────────────────────┘
        │
        ▼
┌─────────────────────┐
│  SwissQL Core API   │  ← REST 服务 (Java/Spring Boot)
│  /v1/sql/execute    │
└─────────────────────┘
        │
   ┌────┴────┐
   ▼         ▼
连接管理    SQL 规则引擎
   │         │
   ▼         ▼
HikariCP   审计日志
连接池      │
   │         ▼
   ▼      数据库
┌─────────┐
│  JDBC   │
└─────────┘

SwissQL 采用前后端分离架构：

• SwissQL Core（后端）— 独立的 REST 服务，负责连接管理、SQL 执行、规则引擎和审计
• SwissQL CLI（前端）— 命令行工具，向后端发起请求，提供人类友好的交互界面

这种分离意味着 SwissQL Core 可以独立部署在 Mopheus 网络内，而 CLI 可以在任意机器上使用（包括智能体所在的机器）。

安装

在标准的 Docker Compose 部署中，SwissQL Core 已随 Mopheus 一起打包并自动启动，无需单独部署。安装脚本（mopheus.sh）也会为你安装 swissql CLI。

SwissQL Core 监听主机端口 18080（由容器内部 8080 端口映射而来）。CLI 连接时请使用 http://<主机>:18080——不要使用 http://<主机>:8080，那是 Mopheus 后端端口。

与 Mopheus 的集成

在 Mopheus 中，智能体通过 SwissQL 访问数据库：

1. 技能层 — 智能体的数据库操作技能（如 SQL 分析、巡检）内部调用 swissql exec
2. Profile 绑定 — 每个工作区或项目可以绑定一个或多个 SwissQL profile，智能体在执行任务时引用这些 profile
3. 规则继承 — 工作区级别的 SQL 规则自动应用到该工作区下所有 profile，形成统一的执行边界
4. 审计贯通 — SwissQL 的审计日志与 Mopheus 的工单系统打通，可以在工单详情页查看"该工单触发了哪些 SQL"