missingTables = new java.util.ArrayList<>();
@@ -296,6 +316,7 @@ public class DatabaseInitConfig {
source_name VARCHAR(500),
file_type VARCHAR(20) NOT NULL,
file_size BIGINT DEFAULT 0 NOT NULL,
+ file_path VARCHAR(500),
content TEXT,
category_id BIGINT DEFAULT 0 NOT NULL,
tags JSONB DEFAULT '{}' NOT NULL,
@@ -328,7 +349,6 @@ public class DatabaseInitConfig {
name VARCHAR(100) NOT NULL,
description TEXT,
prompt TEXT,
- sort_order INTEGER DEFAULT 0 NOT NULL,
enabled BOOLEAN DEFAULT TRUE NOT NULL,
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
@@ -336,7 +356,7 @@ public class DatabaseInitConfig {
)
""";
jdbcTemplate.execute(sql);
- jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_customer_service_role_enabled ON customer_service_role (enabled, sort_order)");
+ jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_customer_service_role_enabled ON customer_service_role (enabled)");
}
private void createCustomerServiceRoleCategoryTable() {
@@ -430,22 +450,40 @@ public class DatabaseInitConfig {
log.warn("add conversation_session.external_account_id failed: {}", e.getMessage());
}
}
+
+ /**
+ * 为 customer_service_role 表添加 allowed_mcp_tools 列（角色 MCP 工具权限控制）
+ * 幂等：已有列则跳过
+ */
+ private void addRoleAllowedMcpToolsColumn() {
+ try {
+ String checkSql = "SELECT COUNT(*) FROM information_schema.columns WHERE table_name = 'customer_service_role' AND column_name = 'allowed_mcp_tools'";
+ Integer count = jdbcTemplate.queryForObject(checkSql, Integer.class);
+ if (count != null && count == 0) {
+ log.info("添加 customer_service_role.allowed_mcp_tools 列");
+ jdbcTemplate.execute("ALTER TABLE customer_service_role ADD COLUMN allowed_mcp_tools JSONB DEFAULT '[]'");
+ }
+ } catch (Exception e) {
+ log.error("添加 customer_service_role.allowed_mcp_tools 列失败", e);
+ }
+ }
+
private void syncDefaultCustomerServiceRoles() {
upsertDefaultRole("general", "客服", "用户咨询、业务办理、常见问题、问题受理与进度说明",
"""
职责：回答用户关于业务办理、服务流程、常见问题、问题受理和进度说明的问题。
要求：优先依据知识库回答；资料不足时说明无法确认，并引导用户补充必要信息；涉及财务、行政制度细节时不要猜测，应提示转对应角色处理。
- """, 10);
+ """);
upsertDefaultRole("finance", "财务", "付款、退款、发票、对账、报销、结算与费用规则",
"""
职责：回答付款、退款、发票、对账、报销、结算、费用规则相关问题。
要求：金额、账户、票据、时间节点必须严谨；知识库没有依据时不得编造政策；需要用户提供单号、金额、日期、发票抬头等关键信息。
- """, 20);
+ """);
upsertDefaultRole("administration", "行政", "办公制度、行政流程、资产、会议、考勤、用章、采购与后勤",
"""
职责：回答办公制度、行政流程、资产、会议、考勤、入职、用章、采购、后勤等问题。
要求：优先依据公司制度和流程文件回答；涉及审批权限、特殊例外或未覆盖场景时提示按制度提交申请或联系行政负责人。
- """, 30);
+ """);
retireObsoleteDefaultRoles();
}
@@ -456,19 +494,13 @@ public class DatabaseInitConfig {
upsertDefaultAccount("administration", "行政账号", "默认行政账号", "administration");
}
- private void upsertDefaultRole(String roleKey, String name, String description, String prompt, int sortOrder) {
+ private void upsertDefaultRole(String roleKey, String name, String description, String prompt) {
jdbcTemplate.update("""
- INSERT INTO customer_service_role (role_key, name, description, prompt, sort_order)
- VALUES (?, ?, ?, ?, ?)
+ INSERT INTO customer_service_role (role_key, name, description, prompt)
+ VALUES (?, ?, ?, ?)
ON CONFLICT (role_key)
- DO UPDATE SET name = EXCLUDED.name,
- description = EXCLUDED.description,
- prompt = EXCLUDED.prompt,
- sort_order = EXCLUDED.sort_order,
- enabled = true,
- is_delete = false,
- update_time = CURRENT_TIMESTAMP
- """, roleKey, name, description, prompt, sortOrder);
+ DO NOTHING
+ """, roleKey, name, description, prompt);
}
private void upsertDefaultAccount(String accountKey, String name, String description, String roleKey) {
@@ -586,6 +618,22 @@ public class DatabaseInitConfig {
}
}
+ /**
+ * 为 knowledge_document 表添加 file_path 列（存储原始文件路径）
+ */
+ private void addDocumentFilePathColumn() {
+ try {
+ String checkSql = "SELECT COUNT(*) FROM information_schema.columns WHERE table_name = 'knowledge_document' AND column_name = 'file_path'";
+ Integer count = jdbcTemplate.queryForObject(checkSql, Integer.class);
+ if (count != null && count == 0) {
+ log.info("添加 knowledge_document.file_path 列");
+ jdbcTemplate.execute("ALTER TABLE knowledge_document ADD COLUMN file_path VARCHAR(500)");
+ }
+ } catch (Exception e) {
+ log.error("添加 knowledge_document.file_path 列失败，请手动执行: ALTER TABLE knowledge_document ADD COLUMN file_path VARCHAR(500)", e);
+ }
+ }
+
// ==================== P0-004: 内容安全过滤 ====================
private void createSensitiveWordTable() {
@@ -1017,6 +1065,27 @@ public class DatabaseInitConfig {
jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_webhook_enabled ON webhook_config (enabled) WHERE is_delete = false");
}
+ private void createMcpServerConfigTable() {
+ String sql = """
+ CREATE TABLE IF NOT EXISTS mcp_server_config (
+ id BIGINT PRIMARY KEY,
+ name VARCHAR(100) NOT NULL,
+ transport_type VARCHAR(20) NOT NULL DEFAULT 'sse',
+ server_url VARCHAR(500),
+ command VARCHAR(500),
+ args VARCHAR(1000),
+ env_vars JSONB DEFAULT '{}' NOT NULL,
+ description VARCHAR(500),
+ is_active BOOLEAN DEFAULT TRUE NOT NULL,
+ create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ is_delete BOOLEAN NOT NULL DEFAULT FALSE
+ )
+ """;
+ jdbcTemplate.execute(sql);
+ jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_mcp_server_config_active ON mcp_server_config (is_active) WHERE is_delete = FALSE");
+ }
+
/**
* 为所有自动创建的表添加注释（COMMENT ON）。
* 所有语句均为幂等操作，可安全重复执行。
@@ -1027,7 +1096,7 @@ public class DatabaseInitConfig {
executeComment("TABLE chat_message", "聊天消息表（存储用户与 AI 助手的对话历史）");
executeComment("COLUMN chat_message.id", "主键（雪花算法生成）");
executeComment("COLUMN chat_message.conversation_id", "会话 ID（标识同一次对话）");
- executeComment("COLUMN chat_message.message_type", "消息类型: USER(用户消息) / ASSISTANT(AI回复) / SYSTEM(系统消息)");
+ executeComment("COLUMN chat_message.message_type", "消息类型: USER(用户消息) / ASSISTANT(AI回复,可能含toolCalls) / SYSTEM(系统消息) / TOOL(MCP工具调用响应)");
executeComment("COLUMN chat_message.content", "消息内容（实际对话文本）");
executeComment("COLUMN chat_message.metadata", "元数据（JSON 格式，存储额外信息）");
executeComment("COLUMN chat_message.create_time", "创建时间");
@@ -1061,6 +1130,7 @@ public class DatabaseInitConfig {
executeComment("COLUMN knowledge_document.content_hash", "内容 SHA-256 哈希值（用于文档去重）");
executeComment("COLUMN knowledge_document.enabled", "是否启用: TRUE=参与RAG检索, FALSE=禁用(不参与检索但保留数据)");
executeComment("COLUMN knowledge_document.extra_config", "分块参数配置（JSONB），存储 per-doc 的 chunkSize/overlap 等");
+ executeComment("COLUMN knowledge_document.file_path", "原始文件存储路径（相对于存储根目录的相对路径）");
executeComment("COLUMN knowledge_document.create_time", "创建时间");
executeComment("COLUMN knowledge_document.update_time", "更新时间");
executeComment("COLUMN knowledge_document.is_delete", "逻辑删除: FALSE=正常 TRUE=已删除");
@@ -1072,11 +1142,11 @@ public class DatabaseInitConfig {
executeComment("COLUMN customer_service_role.name", "角色名称");
executeComment("COLUMN customer_service_role.description", "角色描述");
executeComment("COLUMN customer_service_role.prompt", "系统提示词（角色人设与行为规范）");
- executeComment("COLUMN customer_service_role.sort_order", "排序权重");
executeComment("COLUMN customer_service_role.enabled", "是否启用");
executeComment("COLUMN customer_service_role.create_time", "创建时间");
executeComment("COLUMN customer_service_role.update_time", "更新时间");
executeComment("COLUMN customer_service_role.is_delete", "逻辑删除: FALSE=正常 TRUE=已删除");
+ executeComment("COLUMN customer_service_role.allowed_mcp_tools", "允许使用的 MCP 工具列表（JSONB 数组，空=不允许，[\"*\"]=全部允许）");
// ===== customer_service_role_category =====
executeComment("TABLE customer_service_role_category", "客服角色知识库关联表（角色与知识库分类的多对多关系）");
@@ -1208,6 +1278,21 @@ public class DatabaseInitConfig {
// ===== webhook_config =====
executeComment("TABLE webhook_config", "Webhook 配置表（事件推送订阅）");
+ // ===== mcp_server_config =====
+ executeComment("TABLE mcp_server_config", "MCP Server 配置表（管理外部 MCP Server 连接配置）");
+ executeComment("COLUMN mcp_server_config.id", "主键（雪花算法生成）");
+ executeComment("COLUMN mcp_server_config.name", "配置名称");
+ executeComment("COLUMN mcp_server_config.transport_type", "传输类型: stdio(标准输入输出) / sse(Server-Sent Events)");
+ executeComment("COLUMN mcp_server_config.server_url", "SSE 模式的 MCP Server URL");
+ executeComment("COLUMN mcp_server_config.command", "stdio 模式的启动命令");
+ executeComment("COLUMN mcp_server_config.args", "stdio 模式的命令参数（多个用逗号分隔）");
+ executeComment("COLUMN mcp_server_config.env_vars", "环境变量（JSONB 键值对）");
+ executeComment("COLUMN mcp_server_config.description", "描述说明");
+ executeComment("COLUMN mcp_server_config.is_active", "是否启用");
+ executeComment("COLUMN mcp_server_config.create_time", "创建时间");
+ executeComment("COLUMN mcp_server_config.update_time", "更新时间");
+ executeComment("COLUMN mcp_server_config.is_delete", "逻辑删除: FALSE=正常 TRUE=已删除");
+
// ===== ai_model_config =====
executeComment("TABLE ai_model_config", "AI 大模型配置表（管理多套模型配置，按应用类型绑定）");
executeComment("COLUMN ai_model_config.id", "主键（雪花算法生成）");
@@ -1230,6 +1315,9 @@ public class DatabaseInitConfig {
// ===== chat_message.user_id =====
executeComment("COLUMN chat_message.user_id", "所属系统用户ID（数据隔离，SDK调用时为null）");
+ // ===== api_key.role_ids =====
+ executeComment("COLUMN api_key.role_ids", "绑定的客服角色 ID 列表（JSONB 数组，空数组=不限制，返回所有启用角色）");
+
log.info("数据库表注释已应用");
} catch (Exception e) {
log.warn("应用数据库表注释时出错", e);
@@ -1243,4 +1331,81 @@ public class DatabaseInitConfig {
jdbcTemplate.execute(String.format("COMMENT ON %s IS '%s'", target, comment.replace("'", "''")));
}
+ // ==================== 清理租户相关数据 ====================
+
+ /**
+ * 清理租户相关数据：删除 tenant 表、移除各表的 tenant_id 列和索引
+ */
+ private void cleanupTenantData() {
+ // 1. 删除 tenant 表
+ if (checkTableExists("tenant")) {
+ jdbcTemplate.execute("DROP TABLE IF EXISTS tenant CASCADE");
+ log.info("已删除 tenant 表");
+ }
+
+ // 2. 清理 api_key.tenant_id
+ if (checkTableExists("api_key")) {
+ try {
+ jdbcTemplate.execute("DROP INDEX IF EXISTS idx_api_key_tenant_id");
+ jdbcTemplate.execute("ALTER TABLE api_key DROP COLUMN IF EXISTS tenant_id");
+ } catch (Exception e) {
+ log.debug("清理 api_key.tenant_id 跳过: {}", e.getMessage());
+ }
+ }
+
+ // 3. 清理 customer_service_role.tenant_id
+ if (checkTableExists("customer_service_role")) {
+ try {
+ jdbcTemplate.execute("DROP INDEX IF EXISTS idx_csr_tenant_id");
+ jdbcTemplate.execute("ALTER TABLE customer_service_role DROP COLUMN IF EXISTS tenant_id");
+ } catch (Exception e) {
+ log.debug("清理 customer_service_role.tenant_id 跳过: {}", e.getMessage());
+ }
+ }
+
+ // 4. 清理 knowledge_category.tenant_id
+ if (checkTableExists("knowledge_category")) {
+ try {
+ jdbcTemplate.execute("DROP INDEX IF EXISTS idx_kc_tenant_id");
+ jdbcTemplate.execute("ALTER TABLE knowledge_category DROP COLUMN IF EXISTS tenant_id");
+ } catch (Exception e) {
+ log.debug("清理 knowledge_category.tenant_id 跳过: {}", e.getMessage());
+ }
+ }
+
+ // 5. 清理 knowledge_faq.tenant_id
+ if (checkTableExists("knowledge_faq")) {
+ try {
+ jdbcTemplate.execute("DROP INDEX IF EXISTS idx_faq_tenant_id");
+ jdbcTemplate.execute("ALTER TABLE knowledge_faq DROP COLUMN IF EXISTS tenant_id");
+ } catch (Exception e) {
+ log.debug("清理 knowledge_faq.tenant_id 跳过: {}", e.getMessage());
+ }
+ }
+
+ log.info("租户相关数据清理完成");
+ }
+
+ // ==================== API Key 角色绑定 ====================
+
+ /**
+ * 为 api_key 表添加 role_ids 列（JSONB 数组，存储绑定的客服角色 ID）
+ */
+ private void addApiKeyRoleIdsColumn() {
+ if (!checkTableExists("api_key")) {
+ log.debug("api_key 表尚未创建，跳过 role_ids 迁移");
+ return;
+ }
+ try {
+ String checkSql = "SELECT COUNT(*) FROM information_schema.columns WHERE table_name = 'api_key' AND column_name = 'role_ids'";
+ Integer count = jdbcTemplate.queryForObject(checkSql, Integer.class);
+ if (count != null && count == 0) {
+ log.info("添加 api_key.role_ids 列");
+ jdbcTemplate.execute("ALTER TABLE api_key ADD COLUMN role_ids JSONB DEFAULT '[]' NOT NULL");
+ }
+ } catch (Exception e) {
+ log.error("添加 api_key.role_ids 列失败", e);
+ }
+ }
+
}
diff --git a/src/main/java/com/wok/supportbot/config/FileStorageConfig.java b/src/main/java/com/wok/supportbot/config/FileStorageConfig.java
new file mode 100644
index 0000000..b83dac7
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/config/FileStorageConfig.java
@@ -0,0 +1,80 @@
+package com.wok.supportbot.config;
+
+import jakarta.annotation.PostConstruct;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.io.File;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+/**
+ * 文件存储配置
+ * 管理上传文件的本地存储路径
+ */
+@Component
+@Slf4j
+public class FileStorageConfig {
+
+ @Value("${knowledge.storage.local-path:./uploads}")
+ private String localPath;
+
+ private Path storageRootPath;
+
+ @PostConstruct
+ public void init() {
+ storageRootPath = Paths.get(localPath).toAbsolutePath().normalize();
+ File rootDir = storageRootPath.toFile();
+ if (!rootDir.exists()) {
+ boolean created = rootDir.mkdirs();
+ if (created) {
+ log.info("创建文件存储根目录: {}", storageRootPath);
+ } else {
+ log.warn("创建文件存储根目录失败: {}", storageRootPath);
+ }
+ }
+ log.info("文件存储路径: {}", storageRootPath);
+ }
+
+ /**
+ * 获取存储根路径
+ */
+ public Path getStorageRootPath() {
+ return storageRootPath;
+ }
+
+ /**
+ * 获取指定文件的完整路径
+ *
+ * @param relativePath 相对路径（如 "2024/01/xxx.docx"）
+ */
+ public Path getFilePath(String relativePath) {
+ return storageRootPath.resolve(relativePath).normalize();
+ }
+
+ /**
+ * 生成按年月组织的相对路径
+ *
+ * @param originalFilename 原始文件名
+ * @return 相对路径，如 "2024/01/uuid.docx"
+ */
+ public String generateRelativePath(String originalFilename) {
+ String extension = getExtension(originalFilename);
+ String uniqueName = java.util.UUID.randomUUID().toString() + extension;
+
+ // 按年月分目录
+ java.time.LocalDate now = java.time.LocalDate.now();
+ return String.format("%d/%02d/%s", now.getYear(), now.getMonthValue(), uniqueName);
+ }
+
+ /**
+ * 获取文件扩展名（含点号）
+ */
+ private String getExtension(String filename) {
+ if (filename == null || !filename.contains(".")) {
+ return "";
+ }
+ return filename.substring(filename.lastIndexOf(".")).toLowerCase();
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/config/McpClientManager.java b/src/main/java/com/wok/supportbot/config/McpClientManager.java
new file mode 100644
index 0000000..7041d8a
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/config/McpClientManager.java
@@ -0,0 +1,660 @@
+package com.wok.supportbot.config;
+
+import com.wok.supportbot.entity.McpServerConfig;
+import com.wok.supportbot.service.McpServerConfigService;
+import io.modelcontextprotocol.client.McpSyncClient;
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.client.transport.ServerParameters;
+import io.modelcontextprotocol.client.transport.StdioClientTransport;
+import io.modelcontextprotocol.spec.McpSchema;
+import jakarta.annotation.PostConstruct;
+import jakarta.annotation.PreDestroy;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.ai.model.ModelOptionsUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * MCP 客户端生命周期管理器
+ * 负责 MCP Client 的创建、缓存、刷新和销毁。
+ *
+ * 支持两种传输模式：
+ * - SSE（Server-Sent Events）：通过 HttpClientSseClientTransport 连接远程 MCP Server
+ * - stdio（标准输入输出）：通过 StdioClientTransport 启动本地 MCP Server 进程
+ */
+@Component
+@Slf4j
+public class McpClientManager {
+
+ @Autowired
+ private McpServerConfigService mcpServerConfigService;
+
+ /**
+ * 客户端缓存：key = 配置ID 的字符串形式，value = MCP Client 实例
+ * volatile 保证 refreshAll() 双缓冲切换时的可见性
+ */
+ private volatile ConcurrentHashMap clientCache = new ConcurrentHashMap<>();
+
+ /**
+ * 不可用配置集合：记录已知不存在或未启用的配置ID，避免重复查询 DB
+ * 配置被启用或新建时需同步移除此集合中的对应条目
+ */
+ private final Set unavailableConfigs = ConcurrentHashMap.newKeySet();
+
+ /**
+ * 健康状态缓存：key = 配置ID 的字符串形式，value = 健康检查结果
+ */
+ private final ConcurrentHashMap healthCache = new ConcurrentHashMap<>();
+
+ /**
+ * MCP Server 健康状态记录
+ */
+ public record HealthStatus(
+ /** 状态：ONLINE / OFFLINE / UNKNOWN */
+ String status,
+ /** 响应延迟（毫秒） */
+ long latencyMs,
+ /** 最后检查时间 */
+ Instant lastCheckTime,
+ /** 错误信息（健康时为 null） */
+ String errorMessage
+ ) {
+ public static HealthStatus online(long latencyMs) {
+ return new HealthStatus("ONLINE", latencyMs, Instant.now(), null);
+ }
+
+ public static HealthStatus offline(long latencyMs, String errorMessage) {
+ return new HealthStatus("OFFLINE", latencyMs, Instant.now(), errorMessage);
+ }
+
+ public static HealthStatus unknown(String errorMessage) {
+ return new HealthStatus("UNKNOWN", 0, Instant.now(), errorMessage);
+ }
+ }
+
+ /**
+ * MCP 客户端请求超时时间，支持 Duration 格式（如 30s、PT30S、60s）
+ */
+ @Value("${mcp.client.request-timeout:30s}")
+ private String requestTimeoutStr;
+
+ /**
+ * MCP 客户端初始化超时时间，支持 Duration 格式（如 15s、PT15S、30s）
+ */
+ @Value("${mcp.client.init-timeout:15s}")
+ private String initTimeoutStr;
+
+ /**
+ * 应用启动时自动加载所有已启用的 MCP Server 配置并建立连接
+ * 确保第一次对话请求时 clientCache 已就绪，MCP 工具可以被注册到 ChatClient
+ */
+ @PostConstruct
+ public void init() {
+ log.info("McpClientManager 初始化，开始加载已启用的 MCP Server 配置...");
+ refreshAll();
+ }
+
+ /**
+ * 刷新所有 MCP 客户端连接（双缓冲策略）
+ * 先在新 Map 中构建所有客户端，再原子切换引用，最后关闭旧客户端。
+ * 避免清空与重建之间的请求全部失败。
+ */
+ public void refreshAll() {
+ log.info("开始刷新所有 MCP 客户端连接...");
+
+ // 获取所有启用的配置（一次查询代替两次按类型过滤）
+ List allActiveConfigs = mcpServerConfigService.listAllActiveConfigs();
+
+ // 第一步：在全新 Map 中构建所有客户端（不影响现有缓存）
+ ConcurrentHashMap newCache = new ConcurrentHashMap<>();
+ for (McpServerConfig config : allActiveConfigs) {
+ try {
+ McpSyncClient client = createClientDirectly(config);
+ if (client != null) {
+ newCache.put(config.getId().toString(), client);
+ }
+ } catch (Exception e) {
+ log.error("创建客户端失败: id={}, name={}, transportType={}, error={}",
+ config.getId(), config.getName(), config.getTransportType(), e.getMessage());
+ }
+ }
+
+ // 第二步：原子切换引用（volatile 保证其他线程立即可见）
+ ConcurrentHashMap oldCache = clientCache;
+ clientCache = newCache;
+ unavailableConfigs.clear();
+
+ // 第三步：关闭旧缓存中的客户端（不影响新请求）
+ for (Map.Entry entry : oldCache.entrySet()) {
+ try {
+ McpSyncClient client = entry.getValue();
+ if (client != null) {
+ client.close();
+ log.debug("已关闭旧 MCP 客户端: configId={}", entry.getKey());
+ }
+ } catch (Exception e) {
+ log.error("关闭旧 MCP 客户端失败: configId={}, error={}", entry.getKey(), e.getMessage());
+ }
+ }
+
+ log.info("MCP 客户端刷新完成，当前缓存数量: {}", clientCache.size());
+ }
+
+ /**
+ * 获取指定配置的客户端（懒加载）
+ * 使用 computeIfAbsent 保证同一配置只创建一次客户端，避免并发竞态。
+ * 如果缓存中不存在且不在不可用集合中，从 DB 读取配置后原子创建并缓存。
+ *
+ * @param configId 配置ID
+ * @return MCP Client 实例，不存在或未启用返回 null
+ */
+ public McpSyncClient getClient(Long configId) {
+ String key = configId.toString();
+
+ // 快速路径：缓存命中
+ McpSyncClient cached = clientCache.get(key);
+ if (cached != null) {
+ return cached;
+ }
+
+ // 快速路径：已知不可用的配置，直接跳过
+ if (unavailableConfigs.contains(key)) {
+ return null;
+ }
+
+ // 缓存未命中，使用 computeIfAbsent 保证同一 key 只创建一次客户端
+ // ConcurrentHashMap.computeIfAbsent 对同一 key 加锁，避免并发线程重复创建
+ // 注意：mapping function 不能返回 null（会抛 NPE），因此不可用的情况记录到 unavailableConfigs
+ McpServerConfig config = mcpServerConfigService.getConfigById(configId);
+ if (config == null) {
+ log.warn("MCP 配置不存在: id={}", configId);
+ unavailableConfigs.add(key);
+ return null;
+ }
+ if (!Boolean.TRUE.equals(config.getIsActive())) {
+ log.warn("MCP 配置未启用，跳过创建客户端: id={}, name={}", configId, config.getName());
+ unavailableConfigs.add(key);
+ return null;
+ }
+
+ // 配置存在且启用，通过 computeIfAbsent 原子创建（防止并发重复创建）
+ return clientCache.computeIfAbsent(key, k -> createClientDirectly(config));
+ }
+
+ /**
+ * 获取所有已启用的 MCP 工具描述
+ * 遍历所有已缓存的客户端，调用 listTools() 获取真实的工具列表
+ *
+ * @return 工具描述列表，每个元素包含 config_id、name、transport_type、description、tools
+ */
+ public List> listAvailableTools() {
+ List> tools = new ArrayList<>();
+
+ log.info("🔍 listAvailableTools: clientCache 大小 = {}", clientCache.size());
+
+ if (clientCache.isEmpty()) {
+ log.warn("⚠️ clientCache 为空！MCP Server 可能未配置或连接失败。");
+ log.warn(" 请检查：1) 是否添加了 MCP Server 配置 2) 配置是否已启用 3) 启动日志是否有连接错误");
+ return tools;
+ }
+
+ for (Map.Entry entry : clientCache.entrySet()) {
+ Long configId;
+ try {
+ configId = Long.parseLong(entry.getKey());
+ } catch (NumberFormatException e) {
+ log.warn("缓存 key 格式异常: {}", entry.getKey());
+ continue;
+ }
+
+ McpServerConfig config = mcpServerConfigService.getConfigById(configId);
+ if (config == null || !Boolean.TRUE.equals(config.getIsActive())) {
+ continue;
+ }
+
+ Map toolInfo = new LinkedHashMap<>();
+ toolInfo.put("config_id", config.getId().toString());
+ toolInfo.put("name", config.getName());
+ toolInfo.put("transport_type", config.getTransportType());
+ toolInfo.put("description", config.getDescription());
+
+ // 从 MCP Client 获取真实的工具列表
+ List> toolList = new ArrayList<>();
+ try {
+ McpSyncClient client = entry.getValue();
+ McpSchema.ListToolsResult listToolsResult = client.listTools();
+ if (listToolsResult != null && listToolsResult.tools() != null) {
+ log.info(" 📦 MCP Server [{}] 暴露了 {} 个工具", config.getName(), listToolsResult.tools().size());
+ for (McpSchema.Tool tool : listToolsResult.tools()) {
+ Map toolMeta = new LinkedHashMap<>();
+ toolMeta.put("name", tool.name());
+ toolMeta.put("description", tool.description());
+ // JsonSchema 对象序列化为 JSON 字符串，供 McpToolCallback 构建 ToolDefinition 使用
+ if (tool.inputSchema() != null) {
+ toolMeta.put("inputSchema", ModelOptionsUtils.toJsonString(tool.inputSchema()));
+ } else {
+ toolMeta.put("inputSchema", "{}");
+ }
+ toolList.add(toolMeta);
+ }
+ }
+ log.info(" 📦 MCP Server [{}] 获取到 {} 个工具", config.getName(), toolList.size());
+ if (toolList.isEmpty()) {
+ log.warn(" ⚠️ MCP Server [{}] 未暴露任何工具，AI 模型将无法调用", config.getName());
+ }
+ } catch (Exception e) {
+ log.error("获取 MCP 工具列表失败: serverId={}, name={}, error={}",
+ configId, config.getName(), e.getMessage());
+ }
+
+ toolInfo.put("tools", toolList);
+ tools.add(toolInfo);
+ }
+
+ return tools;
+ }
+
+ /**
+ * 定时健康检查：每 5 分钟执行一次
+ * 遍历所有缓存的客户端，尝试 listTools() 探测连通性，记录状态到 healthCache
+ */
+ @Scheduled(fixedDelay = 300000)
+ public void healthCheck() {
+ log.info("开始 MCP Server 定时健康检查，当前缓存数量: {}", clientCache.size());
+ for (Map.Entry entry : clientCache.entrySet()) {
+ String key = entry.getKey();
+ checkSingleClient(key, entry.getValue());
+ }
+ log.info("MCP Server 定时健康检查完成");
+ }
+
+ /**
+ * 手动触发单个配置的健康检查
+ *
+ * @param configId 配置ID
+ * @return 该配置的最新健康状态
+ */
+ public HealthStatus checkHealthForConfig(Long configId) {
+ String key = configId.toString();
+ McpSyncClient client = clientCache.get(key);
+ if (client == null) {
+ HealthStatus status = HealthStatus.unknown("客户端未缓存或配置不存在");
+ healthCache.put(key, status);
+ return status;
+ }
+ return checkSingleClient(key, client);
+ }
+
+ /**
+ * 对单个客户端执行健康探测
+ * 通过调用 listTools() 判断服务端是否存活
+ *
+ * @param key 缓存 key（配置ID 字符串）
+ * @param client MCP 客户端实例
+ * @return 健康状态
+ */
+ private HealthStatus checkSingleClient(String key, McpSyncClient client) {
+ long startTime = System.currentTimeMillis();
+ try {
+ McpSchema.ListToolsResult result = client.listTools();
+ long latencyMs = System.currentTimeMillis() - startTime;
+ int toolsCount = (result != null && result.tools() != null) ? result.tools().size() : 0;
+ HealthStatus status = HealthStatus.online(latencyMs);
+ healthCache.put(key, status);
+ log.debug("MCP Server 健康检查通过: configId={}, latencyMs={}, toolsCount={}", key, latencyMs, toolsCount);
+ return status;
+ } catch (Exception e) {
+ long latencyMs = System.currentTimeMillis() - startTime;
+ HealthStatus status = HealthStatus.offline(latencyMs, e.getMessage());
+ healthCache.put(key, status);
+ log.warn("MCP Server 健康检查失败: configId={}, latencyMs={}, error={}", key, latencyMs, e.getMessage());
+ return status;
+ }
+ }
+
+ /**
+ * 获取指定配置的健康状态
+ *
+ * @param configId 配置ID
+ * @return 健康状态，未检查过返回 UNKNOWN
+ */
+ public HealthStatus getHealthStatus(Long configId) {
+ HealthStatus status = healthCache.get(configId.toString());
+ if (status == null) {
+ return HealthStatus.unknown("尚未执行健康检查");
+ }
+ return status;
+ }
+
+ /**
+ * 获取所有已缓存配置的健康状态
+ *
+ * @return Map：key = 配置ID 字符串，value = 健康状态
+ */
+ public Map getAllHealthStatus() {
+ Map result = new LinkedHashMap<>();
+ // 遍历所有缓存的客户端，未在 healthCache 中的标记为 UNKNOWN
+ for (String key : clientCache.keySet()) {
+ HealthStatus status = healthCache.get(key);
+ if (status == null) {
+ status = HealthStatus.unknown("尚未执行健康检查");
+ }
+ result.put(key, status);
+ }
+ return result;
+ }
+
+ /**
+ * 关闭所有 MCP 客户端连接
+ * 在应用关闭或手动刷新时调用
+ */
+ @PreDestroy
+ public void shutdown() {
+ log.info("关闭所有 MCP 客户端连接，当前数量: {}", clientCache.size());
+ for (Map.Entry entry : clientCache.entrySet()) {
+ try {
+ McpSyncClient client = entry.getValue();
+ if (client != null) {
+ client.close();
+ log.debug("已关闭 MCP 客户端: configId={}", entry.getKey());
+ }
+ } catch (Exception e) {
+ log.error("关闭 MCP 客户端失败: configId={}, error={}", entry.getKey(), e.getMessage());
+ }
+ }
+ clientCache.clear();
+ unavailableConfigs.clear();
+ healthCache.clear();
+ log.info("所有 MCP 客户端连接已关闭");
+ }
+
+ /**
+ * 根据配置创建 MCP 客户端（不负责缓存，由调用方决定是否缓存）
+ *
+ * SSE 模式：使用 HttpClientSseClientTransport 连接远程 MCP Server
+ * stdio 模式：使用 StdioClientTransport 启动本地 MCP Server 进程
+ *
+ * @param config MCP Server 配置
+ * @return 创建并初始化后的客户端实例，失败返回 null
+ */
+ private McpSyncClient createClientDirectly(McpServerConfig config) {
+ try {
+ McpSyncClient client;
+
+ if ("sse".equals(config.getTransportType())) {
+ // 创建 SSE 传输层：连接远程 MCP Server
+ // HttpClientSseClientTransport 会自动将 /sse 作为 SSE 端点附加到 baseUri
+ String serverUrl = config.getServerUrl().trim();
+ // 如果 URL 以 /sse 结尾，去掉后缀作为 baseUri（transport 层会自动附加）
+ String baseUri = serverUrl.replaceAll("/sse/?$", "");
+ HttpClientSseClientTransport transport = HttpClientSseClientTransport.builder(baseUri).build();
+
+ client = buildSyncClient(transport);
+ log.info("正在初始化 SSE MCP 客户端: id={}, url={}", config.getId(), baseUri);
+
+ } else if ("stdio".equals(config.getTransportType())) {
+ // 创建 stdio 传输层：启动本地 MCP Server 进程
+ String command = config.getCommand().trim();
+
+ // 解析参数列表（逗号分隔）
+ List argsList = new ArrayList<>();
+ if (config.getArgs() != null && !config.getArgs().trim().isEmpty()) {
+ argsList = Arrays.asList(config.getArgs().split("\\s*,\\s*"));
+ }
+
+ // 构建 ServerParameters
+ ServerParameters.Builder paramsBuilder = ServerParameters.builder(command);
+ if (!argsList.isEmpty()) {
+ paramsBuilder.args(argsList);
+ }
+
+ // 环境变量（Map -> Map）
+ if (config.getEnvVars() != null && !config.getEnvVars().isEmpty()) {
+ Map envStr = new HashMap<>();
+ config.getEnvVars().forEach((k, v) -> envStr.put(k, v != null ? v.toString() : ""));
+ paramsBuilder.env(envStr);
+ }
+
+ StdioClientTransport transport = new StdioClientTransport(paramsBuilder.build());
+ client = buildSyncClient(transport);
+ log.info("正在初始化 stdio MCP 客户端: id={}, command={}", config.getId(), command);
+
+ } else {
+ log.error("不支持的传输类型: {}", config.getTransportType());
+ return null;
+ }
+
+ // 初始化连接（握手协议）
+ client.initialize();
+ log.info("MCP 客户端初始化成功: id={}, name={}, transportType={}",
+ config.getId(), config.getName(), config.getTransportType());
+
+ return client;
+
+ } catch (Exception e) {
+ log.error("创建 MCP 客户端失败: id={}, name={}, transportType={}, error={}",
+ config.getId(), config.getName(), config.getTransportType(), e.getMessage(), e);
+ return null;
+ }
+ }
+
+ /**
+ * 构建 McpSyncClient 实例
+ * 统一设置客户端信息和超时参数，超时时间从配置文件读取
+ *
+ * @param transport 传输层实例（SSE 或 stdio）
+ * @return 构建的 McpSyncClient
+ */
+ private McpSyncClient buildSyncClient(io.modelcontextprotocol.spec.McpClientTransport transport) {
+ Duration requestTimeout = parseDuration(requestTimeoutStr, Duration.ofSeconds(30));
+ Duration initTimeout = parseDuration(initTimeoutStr, Duration.ofSeconds(15));
+
+ return io.modelcontextprotocol.client.McpClient.sync(transport)
+ .clientInfo(new McpSchema.Implementation("supportbot-mcp-client", "1.0.0"))
+ .requestTimeout(requestTimeout)
+ .initializationTimeout(initTimeout)
+ .build();
+ }
+
+ /**
+ * 解析 Duration 字符串，兼容 ISO-8601 格式（PT30S）和简化格式（30s、60s）
+ * 解析失败时返回默认值
+ *
+ * @param durationStr Duration 字符串
+ * @param defaultValue 解析失败时的默认值
+ * @return 解析后的 Duration
+ */
+ private Duration parseDuration(String durationStr, Duration defaultValue) {
+ if (durationStr == null || durationStr.isBlank()) {
+ return defaultValue;
+ }
+ try {
+ // 先尝试 ISO-8601 格式（如 PT30S、PT1M30S）
+ return Duration.parse(durationStr.trim());
+ } catch (Exception e) {
+ // 尝试简化格式：纯数字秒（如 "30"）或带 "s" 后缀（如 "30s"）
+ String trimmed = durationStr.trim().toLowerCase();
+ String numStr = trimmed.replaceAll("[^0-9.]+$", "");
+ if (!numStr.isEmpty()) {
+ try {
+ long seconds = Long.parseLong(numStr);
+ return Duration.ofSeconds(seconds);
+ } catch (NumberFormatException ignored) {
+ // 继续尝试小数
+ }
+ }
+ log.warn("无法解析 Duration 配置 '{}'，使用默认值: {}", durationStr, defaultValue);
+ return defaultValue;
+ }
+ }
+
+ // ==================== 增量缓存管理（供 Controller 层 CRUD 操作使用） ====================
+
+ /**
+ * 新增配置时：创建客户端并加入缓存
+ * 仅对新建的单个配置创建连接，不影响其他已有连接。
+ *
+ * @param configId 新建配置的ID
+ */
+ public void addClient(Long configId) {
+ String key = configId.toString();
+ // 从不可用集合中移除（新建的配置可能之前被标记为不可用）
+ unavailableConfigs.remove(key);
+
+ McpServerConfig config = mcpServerConfigService.getConfigById(configId);
+ if (config == null || !Boolean.TRUE.equals(config.getIsActive())) {
+ return;
+ }
+ McpSyncClient client = createClientDirectly(config);
+ if (client != null) {
+ clientCache.put(key, client);
+ log.info("增量添加 MCP 客户端: id={}, name={}", configId, config.getName());
+ }
+ }
+
+ /**
+ * 更新配置时：关闭旧客户端，重建新客户端
+ * 仅对更新的单个配置重建连接，不影响其他已有连接。
+ *
+ * @param configId 更新的配置ID
+ */
+ public void rebuildClient(Long configId) {
+ String key = configId.toString();
+ // 先移除旧客户端
+ removeClient(configId);
+
+ McpServerConfig config = mcpServerConfigService.getConfigById(configId);
+ if (config == null) {
+ unavailableConfigs.add(key);
+ return;
+ }
+ if (!Boolean.TRUE.equals(config.getIsActive())) {
+ unavailableConfigs.add(key);
+ return;
+ }
+
+ unavailableConfigs.remove(key);
+ McpSyncClient client = createClientDirectly(config);
+ if (client != null) {
+ clientCache.put(key, client);
+ log.info("增量重建 MCP 客户端: id={}, name={}", configId, config.getName());
+ }
+ }
+
+ /**
+ * 禁用配置时：关闭并移除客户端，标记为不可用
+ *
+ * @param configId 禁用的配置ID
+ */
+ public void disableClient(Long configId) {
+ removeClient(configId);
+ unavailableConfigs.add(configId.toString());
+ }
+
+ /**
+ * 移除指定配置的客户端缓存
+ * 配置删除或禁用时调用
+ *
+ * @param configId 配置ID
+ */
+ public void removeClient(Long configId) {
+ String key = configId.toString();
+ McpSyncClient removed = clientCache.remove(key);
+ if (removed != null) {
+ try {
+ removed.close();
+ } catch (Exception e) {
+ log.error("关闭被移除的 MCP 客户端失败: configId={}, error={}", configId, e.getMessage());
+ }
+ log.info("已移除并关闭 MCP 客户端缓存: configId={}", configId);
+ }
+ }
+
+ /**
+ * 测试指定配置的 MCP Server 连接
+ * 创建临时客户端 -> initialize -> listTools -> close，不影响正常缓存
+ *
+ * @param configId 配置ID
+ * @return 测试结果 Map：success / latencyMs / toolsCount / errorMessage
+ */
+ public Map testConnection(Long configId) {
+ McpServerConfig config = mcpServerConfigService.getConfigById(configId);
+ if (config == null) {
+ Map result = new LinkedHashMap<>();
+ result.put("success", false);
+ result.put("latencyMs", 0);
+ result.put("toolsCount", 0);
+ result.put("errorMessage", "配置不存在: id=" + configId);
+ return result;
+ }
+
+ McpSyncClient tempClient = null;
+ long startTime = System.currentTimeMillis();
+ try {
+ // 创建临时客户端（不加入缓存），复用 createClientDirectly 的传输层构建逻辑
+ tempClient = createClientDirectly(config);
+ if (tempClient == null) {
+ Map result = new LinkedHashMap<>();
+ result.put("success", false);
+ result.put("latencyMs", System.currentTimeMillis() - startTime);
+ result.put("toolsCount", 0);
+ result.put("errorMessage", "客户端创建失败，请检查配置");
+ return result;
+ }
+
+ // 获取工具列表
+ McpSchema.ListToolsResult listToolsResult = tempClient.listTools();
+ int toolsCount = (listToolsResult != null && listToolsResult.tools() != null)
+ ? listToolsResult.tools().size() : 0;
+
+ long latencyMs = System.currentTimeMillis() - startTime;
+ log.info("MCP 连接测试成功: id={}, name={}, latencyMs={}, toolsCount={}",
+ configId, config.getName(), latencyMs, toolsCount);
+
+ Map result = new LinkedHashMap<>();
+ result.put("success", true);
+ result.put("latencyMs", latencyMs);
+ result.put("toolsCount", toolsCount);
+ result.put("errorMessage", null);
+ return result;
+
+ } catch (Exception e) {
+ long latencyMs = System.currentTimeMillis() - startTime;
+ log.warn("MCP 连接测试失败: id={}, name={}, latencyMs={}, error={}",
+ configId, config.getName(), latencyMs, e.getMessage());
+
+ Map result = new LinkedHashMap<>();
+ result.put("success", false);
+ result.put("latencyMs", latencyMs);
+ result.put("toolsCount", 0);
+ result.put("errorMessage", e.getMessage());
+ return result;
+
+ } finally {
+ // 确保关闭临时客户端
+ if (tempClient != null) {
+ try {
+ tempClient.close();
+ } catch (Exception e) {
+ log.debug("关闭临时测试客户端失败: configId={}, error={}", configId, e.getMessage());
+ }
+ }
+ }
+ }
+
+ /**
+ * 获取当前缓存的客户端数量
+ *
+ * @return 缓存数量
+ */
+ public int getCacheSize() {
+ return clientCache.size();
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/config/McpRequestInterceptor.java b/src/main/java/com/wok/supportbot/config/McpRequestInterceptor.java
new file mode 100644
index 0000000..c482c3c
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/config/McpRequestInterceptor.java
@@ -0,0 +1,24 @@
+package com.wok.supportbot.config;
+
+import com.wok.supportbot.mcp.McpToolCallback;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+/**
+ * MCP 请求拦截器
+ * 在每个 HTTP 请求开始时重置 McpToolCallback 的 ThreadLocal 调用轮次计数器，
+ * 防止 Tomcat 线程池复用导致计数器累积，避免内存泄漏和限流失效。
+ */
+@Component
+@Slf4j
+public class McpRequestInterceptor implements HandlerInterceptor {
+
+ @Override
+ public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
+ McpToolCallback.resetCallRounds();
+ return true;
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/config/McpWebMvcConfig.java b/src/main/java/com/wok/supportbot/config/McpWebMvcConfig.java
new file mode 100644
index 0000000..95b7bfc
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/config/McpWebMvcConfig.java
@@ -0,0 +1,24 @@
+package com.wok.supportbot.config;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+/**
+ * MCP 拦截器注册配置
+ * 将 McpRequestInterceptor 注册到所有请求路径，
+ * 确保每次请求开始时重置 MCP 工具调用轮次计数器。
+ */
+@Configuration
+public class McpWebMvcConfig implements WebMvcConfigurer {
+
+ @Autowired
+ private McpRequestInterceptor mcpRequestInterceptor;
+
+ @Override
+ public void addInterceptors(InterceptorRegistry registry) {
+ registry.addInterceptor(mcpRequestInterceptor)
+ .addPathPatterns("/**");
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/controller/AiController.java b/src/main/java/com/wok/supportbot/controller/AiController.java
index f8cbf0b..e1aece0 100644
--- a/src/main/java/com/wok/supportbot/controller/AiController.java
+++ b/src/main/java/com/wok/supportbot/controller/AiController.java
@@ -61,7 +61,8 @@ public class AiController {
AccountRoleContext context = resolveAccountRole(accountId, roleId);
bindConversation(chatId, context);
RoleScope scope = customerServiceRoleService.getRoleScope(context.roleId());
- return assistantApp.doChat(message, chatId, resolveSystemPrompt(scope, systemPrompt));
+ String result = assistantApp.doChat(message, chatId, resolveSystemPrompt(scope, systemPrompt), scope.allowedMcpTools());
+ return result;
}
/**
@@ -77,7 +78,7 @@ public class AiController {
AccountRoleContext context = resolveAccountRole(accountId, roleId);
bindConversation(chatId, context);
RoleScope scope = customerServiceRoleService.getRoleScope(context.roleId());
- return assistantApp.doChatByStream(message, chatId, resolveSystemPrompt(scope, systemPrompt));
+ return assistantApp.doChatByStream(message, chatId, resolveSystemPrompt(scope, systemPrompt), scope.allowedMcpTools());
}
/**
@@ -93,7 +94,7 @@ public class AiController {
AccountRoleContext context = resolveAccountRole(accountId, roleId);
bindConversation(chatId, context);
RoleScope scope = customerServiceRoleService.getRoleScope(context.roleId());
- return assistantApp.doChatByStream(message, chatId, resolveSystemPrompt(scope, systemPrompt))
+ return assistantApp.doChatByStream(message, chatId, resolveSystemPrompt(scope, systemPrompt), scope.allowedMcpTools())
.map(chunk -> ServerSentEvent.builder()
.data(chunk)
.build());
@@ -115,7 +116,7 @@ public class AiController {
// 创建一个超时时间较长的 SseEmitter
SseEmitter sseEmitter = new SseEmitter(180000L); // 3 分钟超时
// 获取 Flux 响应式数据流并且直接通过订阅推送给 SseEmitter
- assistantApp.doChatByStream(message, chatId, resolveSystemPrompt(scope, systemPrompt))
+ assistantApp.doChatByStream(message, chatId, resolveSystemPrompt(scope, systemPrompt), scope.allowedMcpTools())
.subscribe(chunk -> {
try {
sseEmitter.send(chunk);
@@ -147,12 +148,12 @@ public class AiController {
String sys = resolveSystemPrompt(scope, systemPrompt);
// 严格隔离：未授权任何知识库的角色退回普通对话，绝不检索 KB
if (isKbDenied(scope) || shouldBypassKnowledgeRetrieval(message)) {
- return assistantApp.doChat(message, chatId, sys);
+ return assistantApp.doChat(message, chatId, sys, scope.allowedMcpTools());
}
try {
return assistantApp.doChatWithRagStrategy(
message, chatId, normalizeStrategy(rewriteStrategy),
- resolveCategoryIds(scope, categoryId, categoryIds), sys);
+ resolveCategoryIds(scope, categoryId, categoryIds), sys, scope.allowedMcpTools());
} catch (Exception e) {
log.error("RAG 对话失败 [strategy={}, chatId={}]: {}", rewriteStrategy, chatId, e.getMessage(), e);
return "抱歉，知识库检索出现异常，请稍后重试。";
@@ -179,11 +180,11 @@ public class AiController {
String sys = resolveSystemPrompt(scope, systemPrompt);
// 严格隔离：未授权任何知识库的角色退回普通流式对话，绝不检索 KB
if (isKbDenied(scope) || shouldBypassKnowledgeRetrieval(message)) {
- return assistantApp.doChatByStream(message, chatId, sys);
+ return assistantApp.doChatByStream(message, chatId, sys, scope.allowedMcpTools());
}
return assistantApp.doChatWithRagStrategyByStream(
message, chatId, normalizeStrategy(rewriteStrategy),
- resolveCategoryIds(scope, categoryId, categoryIds), sys);
+ resolveCategoryIds(scope, categoryId, categoryIds), sys, scope.allowedMcpTools());
}
/**
diff --git a/src/main/java/com/wok/supportbot/controller/ApiKeyController.java b/src/main/java/com/wok/supportbot/controller/ApiKeyController.java
index 6fa8d73..1c8eee0 100644
--- a/src/main/java/com/wok/supportbot/controller/ApiKeyController.java
+++ b/src/main/java/com/wok/supportbot/controller/ApiKeyController.java
@@ -13,11 +13,13 @@ import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.*;
import java.util.Date;
+import java.util.List;
import java.util.Map;
+import java.util.Objects;
/**
* API Key 管理接口
- * 提供 API Key 的创建、吊销、启用、删除、分页查询等操作。
+ * 提供 API Key 的创建、吊销、启用、删除、分页查询、角色绑定等操作。
*/
@Slf4j
@RestController
@@ -61,7 +63,7 @@ public class ApiKeyController {
/**
* 创建 API Key
*
- * @param body 请求体，包含 name, description, rateLimit, maxCalls, expireTime
+ * @param body 请求体，包含 name, description, rateLimit, maxCalls, expireTime, roleIds(可选)
*/
@PostMapping
@PreAuthorize("hasRole('admin')")
@@ -102,6 +104,13 @@ public class ApiKeyController {
Long userId = (currentUser != null) ? currentUser.getId() : null;
ApiKey apiKey = apiKeyService.generateKey(userId, name, description, rateLimit, maxCalls, expireTime);
+
+ // 绑定角色（可选）
+ if (body.containsKey("roleIds")) {
+ List roleIds = parseRoleIds(body.get("roleIds"));
+ apiKeyService.updateKeyRoles(apiKey.getId(), roleIds);
+ }
+
return ResponseEntity.ok(Map.of(
"success", true,
"message", "创建成功",
@@ -198,4 +207,50 @@ public class ApiKeyController {
));
}
}
+
+ /**
+ * 更新 API Key 绑定的客服角色
+ * 空数组表示不限制（返回所有启用角色）
+ */
+ @PutMapping("/{id}/roles")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> updateRoles(
+ @PathVariable Long id,
+ @RequestBody Map body) {
+ try {
+ List roleIds = parseRoleIds(body.get("roleIds"));
+ apiKeyService.updateKeyRoles(id, roleIds);
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "message", "角色绑定更新成功"
+ ));
+ } catch (IllegalArgumentException e) {
+ return ResponseEntity.badRequest().body(Map.of(
+ "success", false,
+ "message", e.getMessage()
+ ));
+ } catch (Exception e) {
+ log.error("更新 API Key 角色绑定失败", e);
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "更新失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ /**
+ * 解析请求体中的 roleIds 列表
+ */
+ @SuppressWarnings("unchecked")
+ private List parseRoleIds(Object raw) {
+ if (!(raw instanceof List list)) {
+ return List.of();
+ }
+ return list.stream()
+ .filter(Objects::nonNull)
+ .map(item -> item instanceof Number n ? n.longValue() : Long.parseLong(item.toString()))
+ .filter(id -> id > 0)
+ .distinct()
+ .toList();
+ }
}
diff --git a/src/main/java/com/wok/supportbot/controller/AuthController.java b/src/main/java/com/wok/supportbot/controller/AuthController.java
new file mode 100644
index 0000000..e20f60e
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/controller/AuthController.java
@@ -0,0 +1,127 @@
+package com.wok.supportbot.controller;
+
+import com.wok.supportbot.entity.ApiKey;
+import com.wok.supportbot.security.SdkJwtTokenProvider;
+import com.wok.supportbot.service.ApiKeyService;
+import com.wok.supportbot.service.CustomerServiceRoleService;
+import com.wok.supportbot.service.CustomerServiceRoleService.RoleBrief;
+import jakarta.servlet.http.HttpServletRequest;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * SDK 认证控制器
+ * 提供 Token 换取接口，客户后端用 API Key 换取 SDK JWT Token + 角色列表。
+ *
+ * 路径在 /open-api/ 下，请求首先由 ApiKeyAuthFilter 校验 X-API-Key，
+ * 校验通过后 ApiKey 信息存入 request.attribute("apiKey")，本控制器直接使用。
+ *
+ * 角色来源: 优先使用 API Key 绑定的角色列表（role_ids），
+ * 未绑定时返回所有启用角色（向后兼容）。
+ */
+@Slf4j
+@RestController("sdkAuthController")
+@RequestMapping("/open-api/auth")
+public class AuthController {
+
+ private final CustomerServiceRoleService roleService;
+ private final SdkJwtTokenProvider sdkJwtTokenProvider;
+ private final ApiKeyService apiKeyService;
+
+ public AuthController(CustomerServiceRoleService roleService,
+ SdkJwtTokenProvider sdkJwtTokenProvider,
+ ApiKeyService apiKeyService) {
+ this.roleService = roleService;
+ this.sdkJwtTokenProvider = sdkJwtTokenProvider;
+ this.apiKeyService = apiKeyService;
+ }
+
+ /**
+ * Token 换取接口
+ *
+ * 前置条件: ApiKeyAuthFilter 已校验 X-API-Key，存入 request.attribute("apiKey")
+ *
+ * 返回: SDK JWT Token、过期时间（秒）、可用角色列表
+ *
+ * @param request HTTP 请求（含已鉴权的 API Key 信息）
+ * @param body 请求体（可选，支持自定义 ttl 秒数）
+ * @return {token, expiresIn, roles[]}
+ */
+ @PostMapping("/token")
+ public ResponseEntity getToken(HttpServletRequest request,
+ @RequestBody(required = false) TokenRequest body) {
+ // 1. 获取已鉴权的 API Key（由 ApiKeyAuthFilter 注入）
+ ApiKey apiKey = (ApiKey) request.getAttribute("apiKey");
+ if (apiKey == null) {
+ return ResponseEntity.status(401).body(Map.of(
+ "success", false,
+ "message", "API Key 鉴权失败"
+ ));
+ }
+
+ // 2. 读取 API Key 绑定的角色列表
+ List boundRoleIds = apiKeyService.parseRoleIds(apiKey);
+
+ // 3. 查询角色：有绑定则用绑定列表，否则返回所有启用角色（向后兼容）
+ List roles;
+ if (!boundRoleIds.isEmpty()) {
+ roles = roleService.listRolesByIds(boundRoleIds);
+ } else {
+ roles = roleService.listEnabledRolesBrief();
+ }
+ if (roles.isEmpty()) {
+ return ResponseEntity.status(403).body(Map.of(
+ "success", false,
+ "message", "无可用客服角色"
+ ));
+ }
+
+ List roleIds = roles.stream()
+ .map(RoleBrief::id)
+ .collect(Collectors.toList());
+
+ // 4. 计算过期时间（默认 2 小时，钳制到 [5min, 24h]）
+ long ttlMs = 7200000L;
+ if (body != null && body.ttl() != null) {
+ ttlMs = Math.max(body.ttl() * 1000L, 300000L);
+ ttlMs = Math.min(ttlMs, 86400000L);
+ }
+
+ // 5. 签发 SDK JWT（subject = apiKeyId）
+ String token = sdkJwtTokenProvider.generateToken(
+ apiKey.getId().toString(),
+ SdkJwtTokenProvider.maskApiKey(apiKey.getKeyValue()),
+ roleIds,
+ ttlMs
+ );
+
+ // 6. 返回 Token + 角色列表
+ log.info("SDK Token 签发成功: apiKeyId={}, roleCount={}", apiKey.getId(), roles.size());
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "token", token,
+ "expiresIn", ttlMs / 1000,
+ "roles", roles.stream().map(r -> Map.of(
+ "id", r.id().toString(),
+ "key", r.roleKey(),
+ "name", r.name()
+ )).collect(Collectors.toList())
+ ));
+ }
+
+ /**
+ * 请求体 DTO
+ *
+ * @param ttl 期望的 Token 有效期（秒），会被钳制到 [300, 86400]
+ */
+ public record TokenRequest(Long ttl) {
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/controller/CustomerServiceRoleController.java b/src/main/java/com/wok/supportbot/controller/CustomerServiceRoleController.java
index abc8439..51bcf31 100644
--- a/src/main/java/com/wok/supportbot/controller/CustomerServiceRoleController.java
+++ b/src/main/java/com/wok/supportbot/controller/CustomerServiceRoleController.java
@@ -10,6 +10,7 @@ import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@@ -27,7 +28,7 @@ public class CustomerServiceRoleController {
public ResponseEntity> listRoles() {
return ResponseEntity.ok(Map.of(
"success", true,
- "data", customerServiceRoleService.listRoles()
+ "data", customerServiceRoleService.listRoles(false)
));
}
@@ -49,7 +50,7 @@ public class CustomerServiceRoleController {
try {
customerServiceRoleService.createRole(
str(body.get("roleKey")), str(body.get("name")), str(body.get("description")),
- str(body.get("prompt")), intOrNull(body.get("sortOrder")), boolOrNull(body.get("enabled")));
+ str(body.get("prompt")), boolOrNull(body.get("enabled")));
return ResponseEntity.ok(Map.of("success", true, "message", "角色创建成功"));
} catch (Exception e) {
return ResponseEntity.status(500).body(Map.of("success", false, "message", "创建角色失败：" + e.getMessage()));
@@ -62,7 +63,7 @@ public class CustomerServiceRoleController {
try {
customerServiceRoleService.updateRole(roleId,
str(body.get("name")), str(body.get("description")), str(body.get("prompt")),
- intOrNull(body.get("sortOrder")), boolOrNull(body.get("enabled")));
+ boolOrNull(body.get("enabled")));
return ResponseEntity.ok(Map.of("success", true, "message", "角色更新成功"));
} catch (Exception e) {
return ResponseEntity.status(500).body(Map.of("success", false, "message", "更新角色失败：" + e.getMessage()));
@@ -93,6 +94,35 @@ public class CustomerServiceRoleController {
));
}
+ /**
+ * 更新角色的 MCP 工具权限。
+ * body: { "allowedMcpTools": ["*"] } 或 { "allowedMcpTools": ["mcp_get_weather", "mcp_query_db"] }
+ */
+ @SuppressWarnings("unchecked")
+ @PutMapping("/role/{id}/mcp-tools")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> updateRoleMcpTools(
+ @PathVariable("id") Long roleId,
+ @RequestBody Map body) {
+ try {
+ Object raw = body.get("allowedMcpTools");
+ List allowedMcpTools;
+ if (raw instanceof List list) {
+ allowedMcpTools = list.stream()
+ .filter(Objects::nonNull)
+ .map(Objects::toString)
+ .distinct()
+ .toList();
+ } else {
+ allowedMcpTools = List.of();
+ }
+ customerServiceRoleService.updateRoleMcpTools(roleId, allowedMcpTools);
+ return ResponseEntity.ok(Map.of("success", true, "message", "MCP 工具权限更新成功"));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of("success", false, "message", "更新失败：" + e.getMessage()));
+ }
+ }
+
private List parseCategoryIds(Object rawCategoryIds) {
if (!(rawCategoryIds instanceof List list)) {
return List.of();
diff --git a/src/main/java/com/wok/supportbot/controller/DocumentController.java b/src/main/java/com/wok/supportbot/controller/DocumentController.java
index f20c301..96bba92 100644
--- a/src/main/java/com/wok/supportbot/controller/DocumentController.java
+++ b/src/main/java/com/wok/supportbot/controller/DocumentController.java
@@ -250,6 +250,42 @@ public class DocumentController {
// ==================== 文档管理 ====================
+ /**
+ * 下载文档的原始文件
+ *
+ * @param id 文档ID
+ */
+ @GetMapping("/document/download/{id}")
+ @PreAuthorize("hasAnyRole('admin','kb_operator')")
+ public ResponseEntity downloadDocument(@PathVariable("id") Long id) {
+ try {
+ var entry = documentService.getDocumentFile(id);
+ java.io.File file = entry.getKey();
+ String originalFilename = entry.getValue();
+
+ // 使用 RFC 5987 编码中文文件名，兼容所有浏览器
+ String encodedFilename = java.net.URLEncoder.encode(
+ originalFilename, java.nio.charset.StandardCharsets.UTF_8)
+ .replace("+", "%20");
+
+ // 设置响应头
+ org.springframework.http.HttpHeaders headers = new org.springframework.http.HttpHeaders();
+ headers.setContentType(org.springframework.http.MediaType.APPLICATION_OCTET_STREAM);
+ headers.set(org.springframework.http.HttpHeaders.CONTENT_DISPOSITION,
+ "attachment; filename=\"" + encodedFilename + "\"; filename*=UTF-8''" + encodedFilename);
+ headers.setContentLength(file.length());
+
+ return ResponseEntity.ok()
+ .headers(headers)
+ .body(new org.springframework.core.io.FileSystemResource(file));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "下载失败：" + e.getMessage()
+ ));
+ }
+ }
+
/**
* 查询文档列表（分页 + 过滤 + 关键词搜索 + 标签筛选）
*
diff --git a/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
new file mode 100644
index 0000000..cb717bd
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
@@ -0,0 +1,348 @@
+package com.wok.supportbot.controller;
+
+import com.wok.supportbot.config.McpClientManager;
+import com.wok.supportbot.entity.McpServerConfig;
+import com.wok.supportbot.service.McpServerConfigService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * MCP Server 配置管理控制器
+ * 提供 MCP Server 配置的增删改查、启用/禁用、连接测试、缓存刷新等 API
+ */
+@RestController
+@Slf4j
+public class McpServerConfigController {
+
+ @Autowired
+ private McpServerConfigService mcpServerConfigService;
+
+ @Autowired
+ private McpClientManager mcpClientManager;
+
+ // ==================== 分页列表 ====================
+
+ /**
+ * 获取 MCP Server 配置列表（分页）
+ *
+ * @param page 页码（默认1）
+ * @param size 每页大小（默认10）
+ * @return 分页配置列表
+ */
+ @GetMapping("/mcp-server/list")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> listConfigs(
+ @RequestParam(defaultValue = "1") int page,
+ @RequestParam(defaultValue = "10") int size) {
+ try {
+ Map result = mcpServerConfigService.listConfigs(page, size);
+ Map data = new LinkedHashMap<>();
+ data.put("success", true);
+ data.put("data", result.get("records"));
+ data.put("total", result.get("total"));
+ data.put("page", result.get("page"));
+ data.put("size", result.get("size"));
+ data.put("pages", result.get("pages"));
+ return ResponseEntity.ok(data);
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "查询失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 单条详情 ====================
+
+ /**
+ * 获取单条 MCP Server 配置详情
+ *
+ * @param id 配置ID
+ * @return 配置详情
+ */
+ @GetMapping("/mcp-server/{id}")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> getConfigDetail(@PathVariable("id") Long id) {
+ try {
+ Map config = mcpServerConfigService.getConfigDetail(id);
+ if (config == null) {
+ return ResponseEntity.status(404).body(Map.of(
+ "success", false,
+ "message", "配置不存在"
+ ));
+ }
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "data", config
+ ));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "查询失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 新建配置 ====================
+
+ /**
+ * 新建 MCP Server 配置
+ *
+ * @param config 配置对象
+ * @return 创建结果
+ */
+ @PostMapping("/mcp-server")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> createConfig(@RequestBody McpServerConfig config) {
+ try {
+ Map created = mcpServerConfigService.createConfig(config);
+ // 增量操作：仅为新建配置创建客户端，不影响其他已有连接
+ Object idObj = created.get("id");
+ if (idObj != null) {
+ try {
+ mcpClientManager.addClient(Long.parseLong(idObj.toString()));
+ } catch (Exception e) {
+ log.warn("新建配置后创建客户端失败（不影响配置保存）: {}", e.getMessage());
+ }
+ }
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "data", created,
+ "message", "配置创建成功"
+ ));
+ } catch (IllegalArgumentException e) {
+ return ResponseEntity.badRequest().body(Map.of(
+ "success", false,
+ "message", e.getMessage()
+ ));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "创建失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 更新配置 ====================
+
+ /**
+ * 更新 MCP Server 配置
+ *
+ * @param id 配置ID
+ * @param config 更新内容
+ * @return 更新结果
+ */
+ @PutMapping("/mcp-server/{id}")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> updateConfig(
+ @PathVariable("id") Long id,
+ @RequestBody McpServerConfig config) {
+ try {
+ Map updated = mcpServerConfigService.updateConfig(id, config);
+ // 增量操作：仅重建更新的配置客户端，不影响其他已有连接
+ mcpClientManager.rebuildClient(id);
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "data", updated,
+ "message", "配置更新成功"
+ ));
+ } catch (RuntimeException e) {
+ return ResponseEntity.badRequest().body(Map.of(
+ "success", false,
+ "message", e.getMessage()
+ ));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "更新失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 删除配置 ====================
+
+ /**
+ * 删除 MCP Server 配置（逻辑删除）
+ *
+ * @param id 配置ID
+ * @return 删除结果
+ */
+ @DeleteMapping("/mcp-server/{id}")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> deleteConfig(@PathVariable("id") Long id) {
+ try {
+ mcpServerConfigService.deleteConfig(id);
+ // 增量操作：仅移除被删除的配置客户端，不影响其他已有连接
+ mcpClientManager.removeClient(id);
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "message", "配置删除成功"
+ ));
+ } catch (RuntimeException e) {
+ return ResponseEntity.badRequest().body(Map.of(
+ "success", false,
+ "message", e.getMessage()
+ ));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "删除失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 启用/禁用 ====================
+
+ /**
+ * 切换配置启用/禁用状态
+ *
+ * @param id 配置ID
+ * @param body 请求体：{active: true/false}
+ * @return 操作结果
+ */
+ @PutMapping("/mcp-server/{id}/toggle")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> toggleActive(
+ @PathVariable("id") Long id,
+ @RequestBody Map body) {
+ try {
+ Boolean active = body.get("active");
+ if (active == null) {
+ return ResponseEntity.badRequest().body(Map.of(
+ "success", false,
+ "message", "active 参数不能为空"
+ ));
+ }
+ mcpServerConfigService.toggleActive(id, active);
+ // 增量操作：启用时重建客户端，禁用时移除客户端
+ if (active) {
+ mcpClientManager.rebuildClient(id);
+ } else {
+ mcpClientManager.disableClient(id);
+ }
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "message", active ? "配置已启用" : "配置已禁用"
+ ));
+ } catch (RuntimeException e) {
+ return ResponseEntity.badRequest().body(Map.of(
+ "success", false,
+ "message", e.getMessage()
+ ));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "操作失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 测试连接 ====================
+
+ /**
+ * 测试 MCP Server 连接
+ * 创建临时客户端进行握手 + 工具列表查询，不影响正常缓存
+ *
+ * @param id 配置ID
+ * @return 测试结果（success / latencyMs / toolsCount / errorMessage）
+ */
+ @PostMapping("/mcp-server/{id}/test")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> testConnection(@PathVariable("id") Long id) {
+ try {
+ Map result = mcpClientManager.testConnection(id);
+ return ResponseEntity.ok(result);
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "测试失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 刷新连接 ====================
+
+ /**
+ * 刷新所有 MCP 客户端连接
+ * 清空现有缓存并重新建立所有已启用配置的客户端连接
+ *
+ * @return 刷新结果
+ */
+ @PostMapping("/mcp-server/refresh")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> refreshAll() {
+ try {
+ mcpClientManager.refreshAll();
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "message", "MCP 客户端连接已刷新"
+ ));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "刷新失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ // ==================== 健康检查 ====================
+
+ /**
+ * 获取所有 MCP Server 的健康状态
+ * 返回各配置的在线/离线状态、延迟、最后检查时间等信息
+ *
+ * @return 所有 MCP Server 的健康状态
+ */
+ @GetMapping("/mcp-server/health")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> getAllHealthStatus() {
+ try {
+ Map healthMap = mcpClientManager.getAllHealthStatus();
+ Map data = new LinkedHashMap<>();
+ data.put("success", true);
+ data.put("data", healthMap);
+ return ResponseEntity.ok(data);
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "获取健康状态失败：" + e.getMessage()
+ ));
+ }
+ }
+
+ /**
+ * 手动触发单个 MCP Server 的健康检查
+ * 对指定配置的客户端执行 listTools 探测，返回最新健康状态
+ *
+ * @param id 配置ID
+ * @return 该配置的健康状态
+ */
+ @PostMapping("/mcp-server/{id}/health-check")
+ @PreAuthorize("hasRole('admin')")
+ public ResponseEntity> checkSingleHealth(@PathVariable("id") Long id) {
+ try {
+ McpClientManager.HealthStatus status = mcpClientManager.checkHealthForConfig(id);
+ return ResponseEntity.ok(Map.of(
+ "success", true,
+ "data", Map.of(
+ "configId", id.toString(),
+ "status", status.status(),
+ "latencyMs", status.latencyMs(),
+ "lastCheckTime", status.lastCheckTime().toString(),
+ "errorMessage", status.errorMessage() != null ? status.errorMessage() : ""
+ )
+ ));
+ } catch (Exception e) {
+ return ResponseEntity.status(500).body(Map.of(
+ "success", false,
+ "message", "健康检查失败：" + e.getMessage()
+ ));
+ }
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/converter/MessageConverter.java b/src/main/java/com/wok/supportbot/converter/MessageConverter.java
index 84e3a22..d4b93b8 100644
--- a/src/main/java/com/wok/supportbot/converter/MessageConverter.java
+++ b/src/main/java/com/wok/supportbot/converter/MessageConverter.java
@@ -3,42 +3,136 @@ package com.wok.supportbot.converter;
import com.wok.supportbot.entity.ChatMessage;
import org.springframework.ai.chat.messages.*;
-import java.util.List;
-import java.util.Map;
+import java.util.*;
/**
- * @Classname MessageConverter
- * @Description
- * @Version 1.0.0
- * @Date 2025/06/28 13:30
- * @Author lyx
+ * 消息转换器：Message <-> ChatMessage
+ * 支持 USER / ASSISTANT / SYSTEM / TOOL 四种消息类型
+ * 其中 ASSISTANT 的 toolCalls 和 TOOL 的 responses 通过 metadata JSONB 字段持久化
*/
public class MessageConverter {
+ /** metadata 中存储 toolCalls 的内部键名 */
+ private static final String META_KEY_TOOL_CALLS = "_toolCalls";
+ /** metadata 中存储 toolResponses 的内部键名 */
+ private static final String META_KEY_TOOL_RESPONSES = "_toolResponses";
+
/**
- * 将 Message 转换为 ChatMessage
+ * 将 Spring AI Message 转换为数据库实体 ChatMessage
+ * 对于 ASSISTANT 消息，如果包含 toolCalls 则序列化到 metadata
+ * 对于 TOOL 消息，将 responses 序列化到 metadata
*/
public static ChatMessage toChatMessage(Message message, String conversationId) {
+ Map metadata = message.getMetadata() != null
+ ? new HashMap<>(message.getMetadata())
+ : new HashMap<>();
+
+ // 处理 AssistantMessage 的 toolCalls
+ if (message instanceof AssistantMessage assistant && assistant.hasToolCalls()) {
+ List> toolCallsJson = new ArrayList<>();
+ for (AssistantMessage.ToolCall tc : assistant.getToolCalls()) {
+ Map tcMap = new LinkedHashMap<>();
+ tcMap.put("id", tc.id());
+ tcMap.put("type", tc.type());
+ tcMap.put("name", tc.name());
+ tcMap.put("arguments", tc.arguments());
+ toolCallsJson.add(tcMap);
+ }
+ metadata.put(META_KEY_TOOL_CALLS, toolCallsJson);
+ }
+
+ // 处理 ToolResponseMessage 的 responses
+ if (message instanceof ToolResponseMessage trm) {
+ List> responsesJson = new ArrayList<>();
+ for (ToolResponseMessage.ToolResponse tr : trm.getResponses()) {
+ Map trMap = new LinkedHashMap<>();
+ trMap.put("id", tr.id());
+ trMap.put("name", tr.name());
+ trMap.put("responseData", tr.responseData());
+ responsesJson.add(trMap);
+ }
+ metadata.put(META_KEY_TOOL_RESPONSES, responsesJson);
+ }
+
return ChatMessage.builder()
.conversationId(conversationId)
.messageType(message.getMessageType())
.content(message.getText())
- .metadata(message.getMetadata())
+ .metadata(metadata)
.build();
}
/**
- * 将 ChatMessage 转换为 Message
+ * 将数据库实体 ChatMessage 转换为 Spring AI Message
+ * 根据 messageType 分发到具体子类，反序列化 toolCalls / responses
*/
+ @SuppressWarnings("unchecked")
public static Message toMessage(ChatMessage chatMessage) {
MessageType messageType = chatMessage.getMessageType();
String text = chatMessage.getContent();
Map metadata = chatMessage.getMetadata();
+
+ // 构建不含内部键的干净 metadata（供 Message 对象使用）
+ Map cleanMetadata = metadata != null
+ ? new HashMap<>(metadata)
+ : new HashMap<>();
+
return switch (messageType) {
case USER -> new UserMessage(text);
- case ASSISTANT -> new AssistantMessage(text, metadata);
+ case ASSISTANT -> {
+ List toolCalls = extractToolCalls(cleanMetadata);
+ yield new AssistantMessage(text, cleanMetadata, toolCalls);
+ }
case SYSTEM -> new SystemMessage(text);
- case TOOL -> new ToolResponseMessage(List.of(), metadata);
+ case TOOL -> {
+ List responses = extractToolResponses(cleanMetadata);
+ yield new ToolResponseMessage(responses, cleanMetadata);
+ }
};
}
+
+ /**
+ * 从 metadata 中提取并移除 _toolCalls 键，反序列化为 ToolCall 列表
+ */
+ @SuppressWarnings("unchecked")
+ private static List extractToolCalls(Map metadata) {
+ Object raw = metadata.remove(META_KEY_TOOL_CALLS);
+ if (!(raw instanceof List list) || list.isEmpty()) {
+ return List.of();
+ }
+ List result = new ArrayList<>();
+ for (Object item : list) {
+ if (item instanceof Map) {
+ Map map = (Map) item;
+ String id = String.valueOf(map.getOrDefault("id", ""));
+ String type = String.valueOf(map.getOrDefault("type", "function"));
+ String name = String.valueOf(map.getOrDefault("name", ""));
+ String arguments = String.valueOf(map.getOrDefault("arguments", "{}"));
+ result.add(new AssistantMessage.ToolCall(id, type, name, arguments));
+ }
+ }
+ return result;
+ }
+
+ /**
+ * 从 metadata 中提取并移除 _toolResponses 键，反序列化为 ToolResponse 列表
+ */
+ @SuppressWarnings("unchecked")
+ private static List extractToolResponses(Map metadata) {
+ Object raw = metadata.remove(META_KEY_TOOL_RESPONSES);
+ if (!(raw instanceof List list) || list.isEmpty()) {
+ return List.of();
+ }
+ List result = new ArrayList<>();
+ for (Object item : list) {
+ if (item instanceof Map) {
+ Map map = (Map) item;
+ String id = String.valueOf(map.getOrDefault("id", ""));
+ String name = String.valueOf(map.getOrDefault("name", ""));
+ String responseData = String.valueOf(map.getOrDefault("responseData", ""));
+ result.add(new ToolResponseMessage.ToolResponse(id, name, responseData));
+ }
+ }
+ return result;
+ }
}
diff --git a/src/main/java/com/wok/supportbot/dao/McpServerConfigMapper.java b/src/main/java/com/wok/supportbot/dao/McpServerConfigMapper.java
new file mode 100644
index 0000000..da2c003
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/dao/McpServerConfigMapper.java
@@ -0,0 +1,12 @@
+package com.wok.supportbot.dao;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.wok.supportbot.entity.McpServerConfig;
+import org.apache.ibatis.annotations.Mapper;
+
+/**
+ * MCP Server 配置 Mapper - 继承 MyBatis Plus BaseMapper，自带 CRUD
+ */
+@Mapper
+public interface McpServerConfigMapper extends BaseMapper {
+}
diff --git a/src/main/java/com/wok/supportbot/document/extract/JsonDocumentLoader.java b/src/main/java/com/wok/supportbot/document/extract/JsonDocumentLoader.java
index 3fcdcd7..a9712aa 100644
--- a/src/main/java/com/wok/supportbot/document/extract/JsonDocumentLoader.java
+++ b/src/main/java/com/wok/supportbot/document/extract/JsonDocumentLoader.java
@@ -16,6 +16,37 @@ import java.util.List;
@Slf4j
public class JsonDocumentLoader {
+ // ==================== 从已保存的 File 加载 ====================
+
+ /**
+ * 基本读取方式（从文件）
+ */
+ public List loadBasicJsonFromFile(File file) {
+ Resource resource = new FileSystemResource(file);
+ JsonReader reader = new JsonReader(resource);
+ return reader.get();
+ }
+
+ /**
+ * 指定字段读取方式（从文件）
+ */
+ public List loadJsonByFieldsFromFile(File file, String... fields) {
+ Resource resource = new FileSystemResource(file);
+ JsonReader reader = new JsonReader(resource, fields);
+ return reader.get();
+ }
+
+ /**
+ * 使用 JSON Pointer 提取数组路径内容（从文件）
+ */
+ public List loadJsonByPointerFromFile(File file, String pointer) {
+ Resource resource = new FileSystemResource(file);
+ JsonReader reader = new JsonReader(resource);
+ return reader.get(pointer);
+ }
+
+ // ==================== 从 MultipartFile 加载（兼容旧接口） ====================
+
/**
* 基本读取方式
*/
@@ -26,7 +57,7 @@ public class JsonDocumentLoader {
}
/**
- * 指定字段读取方式（例如 description、features 字段）
+ * 指定字段读取方式
*/
public List loadJsonByFields(MultipartFile file, String... fields) {
Resource resource = toResource(file);
@@ -35,7 +66,7 @@ public class JsonDocumentLoader {
}
/**
- * 使用 JSON Pointer 提取数组路径内容（如 /items）
+ * 使用 JSON Pointer 提取数组路径内容
*/
public List loadJsonByPointer(MultipartFile file, String pointer) {
Resource resource = toResource(file);
diff --git a/src/main/java/com/wok/supportbot/document/extract/MarkdownDocumentLoader.java b/src/main/java/com/wok/supportbot/document/extract/MarkdownDocumentLoader.java
index e981088..707c6db 100644
--- a/src/main/java/com/wok/supportbot/document/extract/MarkdownDocumentLoader.java
+++ b/src/main/java/com/wok/supportbot/document/extract/MarkdownDocumentLoader.java
@@ -20,14 +20,38 @@ import java.util.List;
@Slf4j
public class MarkdownDocumentLoader {
- public List loadMarkdownFromFile(MultipartFile file) {
+ /**
+ * 从已保存的文件加载 Markdown
+ */
+ public List loadMarkdownFromFile(File file) {
+ try {
+ Resource resource = new FileSystemResource(file);
+
+ MarkdownDocumentReaderConfig config = MarkdownDocumentReaderConfig.builder()
+ .withHorizontalRuleCreateDocument(true)
+ .withIncludeCodeBlock(false)
+ .withIncludeBlockquote(false)
+ .withAdditionalMetadata("filename", file.getName())
+ .build();
+
+ MarkdownDocumentReader reader = new MarkdownDocumentReader(resource, config);
+ return reader.get();
+
+ } catch (Exception e) {
+ log.error("Markdown 文件解析失败", e);
+ throw new RuntimeException("Markdown 文件解析失败", e);
+ }
+ }
+
+ /**
+ * 从 MultipartFile 加载 Markdown（兼容旧接口）
+ */
+ public List loadMarkdownFromMultipartFile(MultipartFile file) {
try {
- // 将 MultipartFile 保存为临时文件
File temp = File.createTempFile("upload-", file.getOriginalFilename());
file.transferTo(temp);
Resource resource = new FileSystemResource(temp);
- // 配置文档解析
MarkdownDocumentReaderConfig config = MarkdownDocumentReaderConfig.builder()
.withHorizontalRuleCreateDocument(true)
.withIncludeCodeBlock(false)
@@ -35,9 +59,12 @@ public class MarkdownDocumentLoader {
.withAdditionalMetadata("filename", file.getOriginalFilename())
.build();
- // 读取文档内容
MarkdownDocumentReader reader = new MarkdownDocumentReader(resource, config);
- return reader.get();
+ List docs = reader.get();
+
+ // 清理临时文件
+ temp.delete();
+ return docs;
} catch (IOException e) {
log.error("Markdown 文件解析失败", e);
diff --git a/src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java b/src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java
index 7ee7d2c..d1ff34c 100644
--- a/src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java
+++ b/src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java
@@ -19,15 +19,34 @@ import java.util.UUID;
@Slf4j
public class TikaDocumentReader {
- public List read(MultipartFile file) {
+ /**
+ * 从已保存的文件解析内容
+ */
+ public List readFromFile(File file) {
try {
- // MultipartFile 转 Resource
- File tempFile = File.createTempFile("upload-", file.getOriginalFilename());
- file.transferTo(tempFile);
- Resource resource = new FileSystemResource(tempFile);
+ Tika tika = new Tika();
+ String text = tika.parseToString(new java.io.FileInputStream(file));
+
+ Document doc = Document.builder()
+ .id(UUID.randomUUID().toString())
+ .text(text)
+ .build();
+
+ return Collections.singletonList(doc);
+
+ } catch (IOException | TikaException e) {
+ log.error("Tika 文件解析失败", e);
+ throw new RuntimeException("Tika 文件解析失败", e);
+ }
+ }
+ /**
+ * 从 MultipartFile 解析内容（兼容旧接口）
+ */
+ public List read(MultipartFile file) {
+ try {
Tika tika = new Tika();
- String text = tika.parseToString(resource.getInputStream());
+ String text = tika.parseToString(file.getInputStream());
Document doc = Document.builder()
.id(UUID.randomUUID().toString())
@@ -41,4 +60,14 @@ public class TikaDocumentReader {
throw new RuntimeException("Tika 文件解析失败", e);
}
}
+
+ /**
+ * 获取文件扩展名（含点号），如 ".pptx"。无扩展名时返回 ".tmp"
+ */
+ private String getExtension(String filename) {
+ if (filename == null || !filename.contains(".")) {
+ return ".tmp";
+ }
+ return filename.substring(filename.lastIndexOf("."));
+ }
}
diff --git a/src/main/java/com/wok/supportbot/entity/ApiKey.java b/src/main/java/com/wok/supportbot/entity/ApiKey.java
index e97f9b4..9ea2c04 100644
--- a/src/main/java/com/wok/supportbot/entity/ApiKey.java
+++ b/src/main/java/com/wok/supportbot/entity/ApiKey.java
@@ -60,6 +60,10 @@ public class ApiKey implements Serializable {
@TableField("current_calls")
private Long currentCalls;
+ /** 绑定的客服角色 ID 列表（JSON 字符串，如 "[1,2,3]"；空数组 "[]" 表示不限制） */
+ @TableField("role_ids")
+ private String roleIds;
+
/** 过期时间（null 表示永不过期） */
@TableField("expire_time")
private Date expireTime;
diff --git a/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java b/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
index a889a93..e927c12 100644
--- a/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
+++ b/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
@@ -56,6 +56,12 @@ public class KnowledgeDocument implements Serializable {
@TableField("file_size")
private Long fileSize;
+ /**
+ * 原始文件存储路径（相对路径）
+ */
+ @TableField("file_path")
+ private String filePath;
+
/**
* 原文内容(截断预览)
*/
diff --git a/src/main/java/com/wok/supportbot/entity/McpServerConfig.java b/src/main/java/com/wok/supportbot/entity/McpServerConfig.java
new file mode 100644
index 0000000..6abf8c9
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/entity/McpServerConfig.java
@@ -0,0 +1,104 @@
+package com.wok.supportbot.entity;
+
+import com.baomidou.mybatisplus.annotation.*;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
+import com.wok.supportbot.handler.PostgresJsonTypeHandler;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+import java.util.Map;
+
+/**
+ * MCP Server 配置表 - 管理外部 MCP Server 连接，支持 stdio 和 sse 两种传输模式
+ */
+@Data
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+@TableName(value = "mcp_server_config", autoResultMap = true)
+public class McpServerConfig implements Serializable {
+
+ @Serial
+ @TableField(exist = false)
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * 主键ID（雪花算法）
+ */
+ @TableId(value = "id", type = IdType.ASSIGN_ID)
+ @JsonSerialize(using = ToStringSerializer.class)
+ private Long id;
+
+ /**
+ * 配置名称（如"天气查询服务"）
+ */
+ @TableField("name")
+ private String name;
+
+ /**
+ * 传输类型: stdio（标准输入输出）/ sse（Server-Sent Events）
+ */
+ @TableField("transport_type")
+ private String transportType;
+
+ /**
+ * SSE 模式的 MCP Server URL
+ */
+ @TableField("server_url")
+ private String serverUrl;
+
+ /**
+ * stdio 模式的启动命令
+ */
+ @TableField("command")
+ private String command;
+
+ /**
+ * stdio 模式的命令参数（多个用逗号分隔）
+ */
+ @TableField("args")
+ private String args;
+
+ /**
+ * 环境变量（JSONB，键值对形式）
+ */
+ @TableField(value = "env_vars", typeHandler = PostgresJsonTypeHandler.class)
+ private Map envVars;
+
+ /**
+ * 描述说明
+ */
+ @TableField("description")
+ private String description;
+
+ /**
+ * 是否启用
+ */
+ @TableField("is_active")
+ private Boolean isActive;
+
+ /**
+ * 创建时间
+ */
+ @TableField(value = "create_time", fill = FieldFill.INSERT)
+ private Date createTime;
+
+ /**
+ * 更新时间
+ */
+ @TableField(value = "update_time", fill = FieldFill.INSERT_UPDATE)
+ private Date updateTime;
+
+ /**
+ * 删除标志 - false:未删除, true:已删除(逻辑删除)
+ */
+ @TableField("is_delete")
+ @TableLogic
+ private boolean isDelete;
+}
diff --git a/src/main/java/com/wok/supportbot/mcp/McpToolCallback.java b/src/main/java/com/wok/supportbot/mcp/McpToolCallback.java
new file mode 100644
index 0000000..2351c40
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/mcp/McpToolCallback.java
@@ -0,0 +1,265 @@
+package com.wok.supportbot.mcp;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.wok.supportbot.config.McpClientManager;
+import io.modelcontextprotocol.client.McpSyncClient;
+import io.modelcontextprotocol.spec.McpSchema;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.ai.model.ModelOptionsUtils;
+import org.springframework.ai.tool.ToolCallback;
+import org.springframework.ai.tool.definition.DefaultToolDefinition;
+import org.springframework.ai.tool.definition.ToolDefinition;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * MCP Tool -> Spring AI ToolCallback 适配器
+ * 将单个 MCP Server 暴露的工具适配为 Spring AI 可调用的 ToolCallback。
+ *
+ * 工作流程：
+ * 1. ChatClient 在对话时通过 getToolDefinition() 获取工具元数据（名称、描述、参数 Schema）
+ * 2. 当 AI 模型决定调用该工具时，Spring AI 框架自动调用 call() 方法
+ * 3. call() 内部通过 McpClientManager 获取对应的 MCP Client，转发调用到远程 MCP Server
+ * 4. 工具调用事件通过 ThreadLocal 收集器记录，供 SSE 流式输出使用
+ */
+@Slf4j
+public class McpToolCallback implements ToolCallback {
+
+ private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+ // ==================== 工具调用事件收集 ====================
+
+ /**
+ * 工具调用事件记录
+ */
+ public record ToolCallEvent(String tool, String input, String result, long latencyMs, boolean error) {}
+
+ /**
+ * 线程级事件收集器：在同一请求线程中收集所有工具调用事件
+ * SSE 流式输出完成后，从这里取出事件发送给前端
+ */
+ private static final ThreadLocal> EVENTS = ThreadLocal.withInitial(ArrayList::new);
+
+ /**
+ * 获取当前线程收集的所有工具调用事件，并清空收集器
+ */
+ public static List drainEvents() {
+ List events = EVENTS.get();
+ List copy = new ArrayList<>(events);
+ events.clear();
+ return copy;
+ }
+
+ /**
+ * 重置事件收集器（每个新请求开始时调用）
+ */
+ public static void resetEvents() {
+ EVENTS.remove();
+ }
+
+ /**
+ * MCP Server 配置 ID（用于路由调用到正确的 MCP Client）
+ */
+ private final Long mcpServerConfigId;
+
+ /**
+ * MCP Client Manager（用于获取实际的 MCP Client 实例）
+ */
+ private final McpClientManager mcpClientManager;
+
+ /**
+ * 工具名称（已加 mcp_ 前缀，避免与内置工具冲突）
+ */
+ private final String toolName;
+
+ /**
+ * MCP Server 上的原始工具名称（无前缀，用于发送给 MCP Server 调用）
+ */
+ private final String originalToolName;
+
+ /**
+ * 工具描述（供 AI 模型理解工具用途）
+ */
+ private final String toolDescription;
+
+ /**
+ * 工具输入参数的 JSON Schema（供 AI 模型生成合法的调用参数）
+ */
+ private final String inputSchema;
+
+ /**
+ * 单次对话请求中最大允许的调用轮次，防止无限循环调用
+ */
+ private final int maxCallRounds;
+
+ /**
+ * 线程级调用轮次计数器，每个请求线程独立计数
+ */
+ private static final ThreadLocal CALL_ROUNDS = ThreadLocal.withInitial(() -> 0);
+
+ /**
+ * 构造 MCP 工具适配器（含最大调用轮次限制）
+ *
+ * @param mcpServerConfigId MCP Server 配置 ID
+ * @param toolName 工具名称（含 mcp_ 前缀，用于 Spring AI 注册）
+ * @param originalToolName MCP Server 上的原始工具名称（无前缀，用于实际调用）
+ * @param toolDescription 工具描述
+ * @param inputSchema 输入参数的 JSON Schema
+ * @param mcpClientManager MCP 客户端管理器
+ * @param maxCallRounds 单次请求中最大允许的调用轮次
+ */
+ public McpToolCallback(Long mcpServerConfigId, String toolName, String originalToolName,
+ String toolDescription, String inputSchema, McpClientManager mcpClientManager,
+ int maxCallRounds) {
+ this.mcpServerConfigId = mcpServerConfigId;
+ this.toolName = toolName;
+ this.originalToolName = originalToolName;
+ this.toolDescription = toolDescription;
+ this.inputSchema = inputSchema;
+ this.mcpClientManager = mcpClientManager;
+ this.maxCallRounds = maxCallRounds;
+ }
+
+ /**
+ * 构造 MCP 工具适配器（使用默认最大调用轮次 5）
+ */
+ public McpToolCallback(Long mcpServerConfigId, String toolName, String originalToolName,
+ String toolDescription, String inputSchema, McpClientManager mcpClientManager) {
+ this(mcpServerConfigId, toolName, originalToolName, toolDescription, inputSchema, mcpClientManager, 5);
+ }
+
+ /**
+ * 兼容旧构造方式（toolName 直接用于调用，不加前缀区分）
+ */
+ public McpToolCallback(Long mcpServerConfigId, String toolName, String toolDescription,
+ String inputSchema, McpClientManager mcpClientManager) {
+ this(mcpServerConfigId, toolName, toolName, toolDescription, inputSchema, mcpClientManager, 5);
+ }
+
+ /**
+ * 返回工具定义，供 Spring AI 框架注册到 ChatClient
+ * AI 模型通过此定义了解工具的名称、用途和参数格式
+ */
+ @Override
+ public ToolDefinition getToolDefinition() {
+ return DefaultToolDefinition.builder()
+ .name(toolName)
+ .description(toolDescription)
+ .inputSchema(inputSchema)
+ .build();
+ }
+
+ /**
+ * 执行工具调用
+ * 当 AI 模型决定调用此工具时，Spring AI 框架自动调用此方法。
+ * 内部通过 McpClientManager 获取对应的 MCP Client 实例，
+ * 将调用转发到远程 MCP Server 并返回结果。
+ *
+ * 包含调用轮次限制：同一请求线程中，所有 MCP 工具的累计调用次数
+ * 超过 maxCallRounds 时，返回错误 JSON 防止无限循环。
+ *
+ * @param toolInput JSON 格式的工具输入参数
+ * @return 工具执行结果（JSON 字符串形式）
+ */
+ @Override
+ public String call(String toolInput) {
+ // 检查调用轮次是否超限
+ int currentRound = CALL_ROUNDS.get();
+ if (currentRound >= maxCallRounds) {
+ log.warn("MCP 工具调用轮次超限: tool={}, currentRound={}, maxRounds={}",
+ originalToolName, currentRound, maxCallRounds);
+ return "{\"error\": \"工具调用轮次已达上限 (" + maxCallRounds + " 次)，已终止调用以防止无限循环。请优化提示词减少工具调用次数。\"}";
+ }
+ CALL_ROUNDS.set(currentRound + 1);
+
+ log.info("MCP 工具调用: serverId={}, tool={}, input={}, round={}/{}",
+ mcpServerConfigId, originalToolName, toolInput, currentRound + 1, maxCallRounds);
+ long startTime = System.currentTimeMillis();
+
+ try {
+ // 获取 MCP Client 实例
+ McpSyncClient client = mcpClientManager.getClient(mcpServerConfigId);
+ if (client == null) {
+ log.error("MCP 客户端不可用: serverId={}, tool={}", mcpServerConfigId, originalToolName);
+ return "{\"error\": \"MCP Server (id=" + mcpServerConfigId + ") 客户端未就绪，请检查配置\"}";
+ }
+
+ // 解析工具输入参数：JSON 字符串 -> Map
+ Map arguments = OBJECT_MAPPER.readValue(toolInput, new TypeReference<>() {});
+
+ // 构建 MCP 调用请求并执行
+ McpSchema.CallToolRequest request = new McpSchema.CallToolRequest(originalToolName, arguments);
+ McpSchema.CallToolResult result = client.callTool(request);
+
+ long latency = System.currentTimeMillis() - startTime;
+ log.info("MCP 工具调用完成: tool={}, latency={}ms, isError={}",
+ originalToolName, latency, result.isError());
+
+ // 收集工具调用事件（供 SSE 流式输出使用）
+ String resultStr = result.content() != null ? String.valueOf(result.content()) : "";
+ boolean isError = result.isError() != null && result.isError();
+ EVENTS.get().add(new ToolCallEvent(originalToolName, toolInput, resultStr, latency, isError));
+
+ // 检查是否为错误结果
+ if (result.isError() != null && result.isError()) {
+ log.error("MCP 工具返回错误: tool={}, content={}", originalToolName, result.content());
+ return "{\"error\": \"工具执行返回错误: " +
+ escapeJson(String.valueOf(result.content())) + "\"}";
+ }
+
+ // 将 MCP Content 列表序列化为 JSON 字符串返回给 AI 模型
+ // 与官方 SyncMcpToolCallback 保持一致，使用 ModelOptionsUtils 序列化
+ String resultJson = ModelOptionsUtils.toJsonString(result.content());
+ log.debug("MCP 工具调用结果: tool={}, result={}", originalToolName, resultJson);
+ return resultJson;
+
+ } catch (Exception e) {
+ long latency = System.currentTimeMillis() - startTime;
+ log.error("MCP 工具调用失败: tool={}, latency={}ms, error={}", originalToolName, latency, e.getMessage());
+ // 记录失败事件
+ EVENTS.get().add(new ToolCallEvent(originalToolName, toolInput, e.getMessage(), latency, true));
+ return "{\"error\": \"" + escapeJson(e.getMessage()) + "\"}";
+ }
+ }
+
+ /**
+ * 转义字符串中的特殊字符，避免破坏 JSON 格式
+ */
+ private String escapeJson(String text) {
+ if (text == null) return "未知错误";
+ return text.replace("\\", "\\\\").replace("\"", "'").replace("\n", "\\n").replace("\r", "\\r");
+ }
+
+ // ==================== Getter 方法 ====================
+
+ public Long getMcpServerConfigId() {
+ return mcpServerConfigId;
+ }
+
+ public String getToolName() {
+ return toolName;
+ }
+
+ public String getOriginalToolName() {
+ return originalToolName;
+ }
+
+ public String getToolDescription() {
+ return toolDescription;
+ }
+
+ public String getInputSchema() {
+ return inputSchema;
+ }
+
+ /**
+ * 重置当前线程的调用轮次计数器
+ * 应在每次新的对话请求开始时调用，确保轮次计数从零开始
+ */
+ public static void resetCallRounds() {
+ CALL_ROUNDS.remove();
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/mcp/McpToolCallbackAdapter.java b/src/main/java/com/wok/supportbot/mcp/McpToolCallbackAdapter.java
new file mode 100644
index 0000000..510ebfa
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/mcp/McpToolCallbackAdapter.java
@@ -0,0 +1,111 @@
+package com.wok.supportbot.mcp;
+
+import com.wok.supportbot.config.McpClientManager;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.ai.tool.ToolCallback;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * MCP 工具批量适配器
+ * 从 McpClientManager 获取所有已启用的 MCP 工具描述，
+ * 批量转换为 Spring AI ToolCallback 列表，供 ChatClient 注册。
+ *
+ * 使用方式：
+ *
+ * // 注入后在 ChatClient 构建时注册所有 MCP 工具
+ * ChatClient.builder(chatModel)
+ * .defaultTools(mcpToolCallbackAdapter.getAllToolCallbacksAsArray())
+ * .defaultAdvisors(...)
+ * .build();
+ *
+ */
+@Component
+@Slf4j
+public class McpToolCallbackAdapter {
+
+ private final McpClientManager mcpClientManager;
+
+ /**
+ * 单次对话请求中最大允许的 MCP 工具调用轮次，防止无限循环调用
+ */
+ @Value("${mcp.tools.max-call-rounds:5}")
+ private int maxCallRounds;
+
+ public McpToolCallbackAdapter(McpClientManager mcpClientManager) {
+ this.mcpClientManager = mcpClientManager;
+ }
+
+ /**
+ * 获取所有 MCP 工具的 ToolCallback 列表
+ * 遍历所有已启用的 MCP Server，将其暴露的工具转换为 ToolCallback
+ *
+ * @return ToolCallback 列表（可能为空，但不会为 null）
+ */
+ public List getAllToolCallbacks() {
+ List callbacks = new ArrayList<>();
+ List> tools = mcpClientManager.listAvailableTools();
+
+ for (Map toolInfo : tools) {
+ String configId = (String) toolInfo.get("config_id");
+ String serverName = (String) toolInfo.get("name");
+
+ @SuppressWarnings("unchecked")
+ List> toolList = (List>) toolInfo.get("tools");
+ if (toolList == null || toolList.isEmpty()) {
+ log.debug("MCP Server [{}] 暂无可用工具", serverName);
+ continue;
+ }
+
+ for (Map tool : toolList) {
+ String toolName = (String) tool.get("name");
+ String description = (String) tool.get("description");
+ String inputSchema = (String) tool.get("inputSchema");
+
+ // 工具名加 mcp_ 前缀，避免与内置工具冲突
+ String prefixedName = "mcp_" + toolName;
+ McpToolCallback callback = new McpToolCallback(
+ Long.parseLong(configId), prefixedName, toolName, description, inputSchema,
+ mcpClientManager, maxCallRounds);
+ callbacks.add(callback);
+ log.debug("注册 MCP 工具: server={}, tool={}", serverName, prefixedName);
+ }
+ }
+
+ log.info("MCP 工具适配完成，共注册 {} 个工具", callbacks.size());
+ return callbacks;
+ }
+
+ /**
+ * 获取 MCP 工具的 ToolCallback 数组（供 ChatClient.defaultTools() 使用）
+ * ChatClient.defaultTools() 接受 ToolCallback[] 参数，此方法提供便捷转换
+ *
+ * @return ToolCallback 数组
+ */
+ public ToolCallback[] getAllToolCallbacksAsArray() {
+ return getAllToolCallbacks().toArray(new ToolCallback[0]);
+ }
+
+ /**
+ * 获取指定工具名列表的 ToolCallback 数组（按角色权限过滤 MCP 工具）
+ *
+ * @param allowedTools 允许的工具名列表；["*"] 表示全部允许，其他为具体工具名列表
+ * @return 过滤后的 ToolCallback 数组（可能为空数组）
+ */
+ public ToolCallback[] getFilteredToolCallbacks(List allowedTools) {
+ if (allowedTools == null || allowedTools.isEmpty()) {
+ return new ToolCallback[0];
+ }
+ List all = getAllToolCallbacks();
+ if (allowedTools.contains("*")) {
+ return all.toArray(new ToolCallback[0]);
+ }
+ return all.stream()
+ .filter(cb -> allowedTools.contains(cb.getToolDefinition().name()))
+ .toArray(ToolCallback[]::new);
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/mcp/SseEventBuilder.java b/src/main/java/com/wok/supportbot/mcp/SseEventBuilder.java
new file mode 100644
index 0000000..814c4f9
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/mcp/SseEventBuilder.java
@@ -0,0 +1,73 @@
+package com.wok.supportbot.mcp;
+
+import org.springframework.http.codec.ServerSentEvent;
+
+/**
+ * SSE 事件构建器
+ * 用于在 MCP 工具调用流程中构建标准 SSE 事件，
+ * 让前端能区分文本内容与工具调用状态。
+ *
+ * 事件类型：
+ * - message: 普通文本内容
+ * - tool_call_start: 工具调用开始
+ * - tool_call_result: 工具调用结果返回
+ * - error: 错误信息
+ */
+public class SseEventBuilder {
+
+ /**
+ * 构建普通文本消息事件
+ */
+ public static ServerSentEvent messageEvent(String data) {
+ return ServerSentEvent.builder()
+ .event("message")
+ .data(data)
+ .build();
+ }
+
+ /**
+ * 构建工具调用开始事件
+ */
+ public static ServerSentEvent toolCallStartEvent(String toolName, String input) {
+ String json = String.format("{\"tool\":\"%s\",\"input\":\"%s\"}",
+ escapeJson(toolName), escapeJson(input));
+ return ServerSentEvent.builder()
+ .event("tool_call_start")
+ .data(json)
+ .build();
+ }
+
+ /**
+ * 构建工具调用结果事件
+ */
+ public static ServerSentEvent toolCallResultEvent(String toolName, String result, long latencyMs) {
+ String json = String.format("{\"tool\":\"%s\",\"result\":\"%s\",\"latencyMs\":%d}",
+ escapeJson(toolName), escapeJson(result), latencyMs);
+ return ServerSentEvent.builder()
+ .event("tool_call_result")
+ .data(json)
+ .build();
+ }
+
+ /**
+ * 构建错误事件
+ */
+ public static ServerSentEvent errorEvent(String message) {
+ return ServerSentEvent.builder()
+ .event("error")
+ .data("{\"message\":\"" + escapeJson(message) + "\"}")
+ .build();
+ }
+
+ /**
+ * JSON 字符串转义
+ */
+ private static String escapeJson(String s) {
+ if (s == null) return "";
+ return s.replace("\\", "\\\\")
+ .replace("\"", "\\\"")
+ .replace("\n", "\\n")
+ .replace("\r", "\\r")
+ .replace("\t", "\\t");
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/openapi/ApiKeyAuthFilter.java b/src/main/java/com/wok/supportbot/openapi/ApiKeyAuthFilter.java
index def2000..640d816 100644
--- a/src/main/java/com/wok/supportbot/openapi/ApiKeyAuthFilter.java
+++ b/src/main/java/com/wok/supportbot/openapi/ApiKeyAuthFilter.java
@@ -25,7 +25,7 @@ import java.util.Map;
*/
@Slf4j
@Component
-@Order(Ordered.HIGHEST_PRECEDENCE + 1)
+@Order(Ordered.HIGHEST_PRECEDENCE + 2)
public class ApiKeyAuthFilter extends OncePerRequestFilter {
@Autowired
diff --git a/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java b/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
index cde4582..dc3b84b 100644
--- a/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
+++ b/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
@@ -33,20 +33,30 @@ public class JwtAuthFilter extends OncePerRequestFilter {
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
+ String path = request.getRequestURI();
String token = extractToken(request);
- if (StringUtils.hasText(token) && jwtTokenProvider.validateToken(token)) {
- String username = jwtTokenProvider.getUsernameFromToken(token);
- List roles = jwtTokenProvider.getRolesFromToken(token);
+ if (StringUtils.hasText(token)) {
+ boolean valid = jwtTokenProvider.validateToken(token);
+ if (valid) {
+ String username = jwtTokenProvider.getUsernameFromToken(token);
+ List roles = jwtTokenProvider.getRolesFromToken(token);
- // 构建 Spring Security 权限列表（ROLE_ 前缀）
- List authorities = roles.stream()
- .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
- .toList();
+ // 构建 Spring Security 权限列表（ROLE_ 前缀）
+ List authorities = roles.stream()
+ .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
+ .toList();
- UsernamePasswordAuthenticationToken authentication =
- new UsernamePasswordAuthenticationToken(username, null, authorities);
- SecurityContextHolder.getContext().setAuthentication(authentication);
+ UsernamePasswordAuthenticationToken authentication =
+ new UsernamePasswordAuthenticationToken(username, null, authorities);
+ SecurityContextHolder.getContext().setAuthentication(authentication);
+ log.debug("JWT 认证成功: path={}, user={}, roles={}", path, username, roles);
+ } else {
+ log.warn("JWT Token 验证失败: path={}, tokenPrefix={}",
+ path, token.length() > 10 ? token.substring(0, 10) + "..." : token);
+ }
+ } else {
+ log.debug("JWT 未找到 Token: path={}", path);
}
filterChain.doFilter(request, response);
diff --git a/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java b/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
index dc972d4..d1330d4 100644
--- a/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
+++ b/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
@@ -1,6 +1,7 @@
package com.wok.supportbot.security;
import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.ExpiredJwtException;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import org.springframework.beans.factory.annotation.Value;
@@ -70,6 +71,9 @@ public class JwtTokenProvider {
try {
parseClaims(token);
return true;
+ } catch (ExpiredJwtException e) {
+ // Token 已过期，不打印堆栈
+ return false;
} catch (Exception e) {
return false;
}
diff --git a/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java b/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
new file mode 100644
index 0000000..0f7141d
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
@@ -0,0 +1,124 @@
+package com.wok.supportbot.security;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.ExpiredJwtException;
+import io.jsonwebtoken.JwtException;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * SDK 鉴权过滤器
+ * 拦截 /ai/** 请求，校验 SDK JWT Token。
+ *
+ * 优先级高于 ApiKeyAuthFilter，在 SecurityFilterChain 之前执行。
+ * 校验通过后提取 allowedRoleIds 用于角色鉴权。
+ * 校验失败直接返回 401/403，请求不会到达 AiController。
+ */
+@Slf4j
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE + 1)
+public class SdkAuthFilter extends OncePerRequestFilter {
+
+ @Autowired
+ private SdkJwtTokenProvider sdkJwtTokenProvider;
+
+ private static final ObjectMapper objectMapper = new ObjectMapper();
+
+ @Override
+ protected boolean shouldNotFilter(HttpServletRequest request) {
+ String path = request.getServletPath();
+ // 放行 CORS 预检请求（OPTIONS 请求不需要 Token 鉴权）
+ if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
+ return true;
+ }
+ // 仅拦截 /ai/ 路径，排除静态资源和 swagger
+ return !path.startsWith("/ai/");
+ }
+
+ @Override
+ protected void doFilterInternal(HttpServletRequest request,
+ HttpServletResponse response,
+ FilterChain chain) throws ServletException, IOException {
+ try {
+ // ① 提取 Authorization: Bearer {token}
+ String authHeader = request.getHeader("Authorization");
+ if (authHeader == null || !authHeader.startsWith("Bearer ")) {
+ writeError(response, 401, "缺少认证令牌");
+ return;
+ }
+ String token = authHeader.substring(7).trim();
+ if (token.isEmpty()) {
+ writeError(response, 401, "认证令牌为空");
+ return;
+ }
+
+ // ② JWT 签名验证 + ③ 过期检查
+ Claims claims;
+ try {
+ claims = sdkJwtTokenProvider.parseToken(token);
+ } catch (ExpiredJwtException e) {
+ writeError(response, 401, "令牌已过期");
+ return;
+ } catch (JwtException e) {
+ log.warn("SDK Token 验证失败: {}", e.getMessage());
+ writeError(response, 401, "无效的认证令牌");
+ return;
+ }
+
+ // ④ 提取 allowedRoleIds
+ Set allowedRoleIds = sdkJwtTokenProvider.getAllowedRoleIds(claims);
+
+ // ⑤ roleId ∈ allowedRoleIds 校验（仅当请求携带 roleId 参数时）
+ String roleIdParam = request.getParameter("roleId");
+ if (roleIdParam != null && !roleIdParam.isEmpty()) {
+ try {
+ Long roleId = Long.parseLong(roleIdParam);
+ if (!allowedRoleIds.isEmpty() && !allowedRoleIds.contains(roleId)) {
+ writeError(response, 403, "无权使用该客服角色");
+ return;
+ }
+ } catch (NumberFormatException e) {
+ writeError(response, 400, "无效的角色ID");
+ return;
+ }
+ }
+
+ chain.doFilter(request, response);
+ } finally {
+ // 预留清理点
+ }
+ }
+
+ /**
+ * 输出 JSON 格式的错误响应（与 ApiKeyAuthFilter 保持一致的格式）
+ * 同时添加 CORS 头，避免浏览器将鉴权失败误报为跨域错误
+ */
+ private void writeError(HttpServletResponse response, int status, String message) throws IOException {
+ response.setStatus(status);
+ response.setContentType("application/json;charset=UTF-8");
+ // 添加 CORS 头，使浏览器能正确读取错误响应
+ response.setHeader("Access-Control-Allow-Origin", "*");
+ response.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+ response.setHeader("Access-Control-Allow-Headers", "*");
+ response.setHeader("Access-Control-Allow-Credentials", "true");
+ Map body = Map.of(
+ "success", false,
+ "message", message,
+ "code", status
+ );
+ response.getWriter().write(objectMapper.writeValueAsString(body));
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java b/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
new file mode 100644
index 0000000..88829cb
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
@@ -0,0 +1,149 @@
+package com.wok.supportbot.security;
+
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.ExpiredJwtException;
+import io.jsonwebtoken.JwtException;
+import io.jsonwebtoken.Jwts;
+import io.jsonwebtoken.security.Keys;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import javax.crypto.SecretKey;
+import java.nio.charset.StandardCharsets;
+import java.util.Date;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/**
+ * SDK 专用 JWT 令牌提供者
+ * 独立于管理后台 JwtTokenProvider，使用独立密钥签发和验证 SDK Token。
+ *
+ * Token 中包含:
+ * - sub: apiKeyId（API Key 标识）
+ * - ak: 脱敏后的 API Key
+ * - rids: 允许使用的客服角色 ID 列表
+ */
+@Slf4j
+@Component
+public class SdkJwtTokenProvider {
+
+ private final SecretKey key;
+ private final long defaultExpiration;
+
+ /** 24 小时上限 */
+ private static final long MAX_EXPIRATION = 86400000L;
+ /** 5 分钟下限 */
+ private static final long MIN_EXPIRATION = 300000L;
+
+ /** 默认密钥标识（禁止使用） */
+ private static final String DEFAULT_SECRET = "support-bot-sdk-jwt-secret-2026-please-change";
+
+ public SdkJwtTokenProvider(
+ @Value("${jwt.sdk-secret:support-bot-sdk-jwt-secret-2026-please-change}") String sdkSecret,
+ @Value("${jwt.sdk-expiration:7200000}") long defaultExpiration) {
+ if (DEFAULT_SECRET.equals(sdkSecret)) {
+ log.warn("⚠️ SDK JWT 使用了默认密钥，存在安全风险！请在 application.yml 中配置 jwt.sdk-secret 为强随机字符串");
+ }
+ this.key = Keys.hmacShaKeyFor(sdkSecret.getBytes(StandardCharsets.UTF_8));
+ this.defaultExpiration = defaultExpiration;
+ }
+
+ /**
+ * 签发 SDK JWT Token
+ *
+ * @param apiKeyId API Key 标识
+ * @param maskedApiKey 脱敏后的 API Key
+ * @param roleIds 允许使用的客服角色 ID 列表
+ * @param expirationMs 过期时间（毫秒），会被钳制到 [5min, 24h]
+ * @return JWT Token 字符串
+ */
+ public String generateToken(String apiKeyId, String maskedApiKey, List roleIds, long expirationMs) {
+ long clampedExpiration = clampExpiration(expirationMs);
+ Date now = new Date();
+ return Jwts.builder()
+ .subject(apiKeyId)
+ .claim("ak", maskedApiKey)
+ .claim("rids", roleIds)
+ .issuedAt(now)
+ .expiration(new Date(now.getTime() + clampedExpiration))
+ .signWith(key)
+ .compact();
+ }
+
+ /**
+ * 使用默认过期时间签发 SDK JWT Token
+ */
+ public String generateToken(String apiKeyId, String maskedApiKey, List roleIds) {
+ return generateToken(apiKeyId, maskedApiKey, roleIds, defaultExpiration);
+ }
+
+ /**
+ * 验证并解析 Token，返回 Claims
+ *
+ * @param token JWT Token 字符串
+ * @return Claims 对象
+ * @throws ExpiredJwtException Token 已过期
+ * @throws JwtException Token 签名无效或格式错误
+ */
+ public Claims parseToken(String token) {
+ return Jwts.parser()
+ .verifyWith(key)
+ .build()
+ .parseSignedClaims(token)
+ .getPayload();
+ }
+
+ /**
+ * 验证 Token 是否有效（签名正确且未过期）
+ */
+ public boolean validateToken(String token) {
+ try {
+ parseToken(token);
+ return true;
+ } catch (Exception e) {
+ return false;
+ }
+ }
+
+ /**
+ * 从 Claims 中提取 apiKeyId（subject）
+ */
+ public String getApiKeyId(Claims claims) {
+ return claims.getSubject();
+ }
+
+ /**
+ * 从 Claims 中提取允许的角色 ID 集合
+ * JWT 中 rids 为 List<Integer>，需转换为 Set<Long>
+ */
+ @SuppressWarnings("unchecked")
+ public Set getAllowedRoleIds(Claims claims) {
+ List rids = claims.get("rids", List.class);
+ if (rids == null) {
+ return Set.of();
+ }
+ return rids.stream()
+ .map(r -> ((Number) r).longValue())
+ .collect(Collectors.toSet());
+ }
+
+ /**
+ * 脱敏 API Key: sk_ab****xyz0
+ * 保留前 4 位和后 4 位，中间用 **** 替代
+ */
+ public static String maskApiKey(String keyValue) {
+ if (keyValue == null || keyValue.length() < 12) {
+ return "****";
+ }
+ return keyValue.substring(0, 4) + "****" + keyValue.substring(keyValue.length() - 4);
+ }
+
+ /**
+ * 将过期时间钳制到 [5min, 24h] 范围内
+ */
+ private long clampExpiration(long expirationMs) {
+ return Math.max(MIN_EXPIRATION, Math.min(expirationMs, MAX_EXPIRATION));
+ }
+}
diff --git a/src/main/java/com/wok/supportbot/security/SecurityConfig.java b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
index 264283b..3bf4b10 100644
--- a/src/main/java/com/wok/supportbot/security/SecurityConfig.java
+++ b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
@@ -43,7 +43,10 @@ public class SecurityConfig {
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth -> auth
// ========== 公开接口（无需认证） ==========
- // SDK 对话接口（方案A：不认证，SDK 直接调用）
+ // SDK 对话接口
+ // SdkAuthFilter 作为 Servlet Filter 已在 SecurityFilterChain 之前执行，
+ // 校验通过时已放行，校验失败时已返回 401，不会到达此处。
+ // 因此 /ai/** 保持 permitAll()，实际安全性由 SdkAuthFilter 保证。
.requestMatchers("/ai/**").permitAll()
// 开放 API（由 ApiKeyAuthFilter 独立鉴权）
.requestMatchers("/open-api/**").permitAll()
diff --git a/src/main/java/com/wok/supportbot/service/ApiKeyService.java b/src/main/java/com/wok/supportbot/service/ApiKeyService.java
index 854cb72..409fe27 100644
--- a/src/main/java/com/wok/supportbot/service/ApiKeyService.java
+++ b/src/main/java/com/wok/supportbot/service/ApiKeyService.java
@@ -1,6 +1,8 @@
package com.wok.supportbot.service;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
import com.wok.supportbot.dao.ApiKeyMapper;
import com.wok.supportbot.entity.ApiKey;
import lombok.extern.slf4j.Slf4j;
@@ -8,10 +10,11 @@ import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.*;
+import java.util.stream.Collectors;
/**
* API Key 管理服务
- * 提供 API Key 的生成、查询、吊销、启用、删除、验证等功能。
+ * 提供 API Key 的生成、查询、吊销、启用、删除、验证、角色绑定等功能。
*/
@Slf4j
@Service
@@ -20,6 +23,11 @@ public class ApiKeyService {
@Autowired
private ApiKeyMapper apiKeyMapper;
+ @Autowired
+ private org.springframework.jdbc.core.JdbcTemplate jdbcTemplate;
+
+ private final ObjectMapper objectMapper = new ObjectMapper();
+
/**
* 生成新的 API Key
*
@@ -54,6 +62,7 @@ public class ApiKeyService {
/**
* 分页查询 API Key 列表
+ * 分两步查询：MyBatis Plus 读基础字段 + JdbcTemplate 读 JSONB role_ids
*
* @param page 页码（从1开始）
* @param size 每页条数
@@ -68,6 +77,19 @@ public class ApiKeyService {
listWrapper.last("LIMIT " + size + " OFFSET " + (long) (page - 1) * size);
List records = apiKeyMapper.selectList(listWrapper);
+ // 补充读取 JSONB role_ids 字段（MyBatis Plus 无法正确读取 JSONB）
+ if (!records.isEmpty()) {
+ Map roleIdsMap = new HashMap<>();
+ String ids = records.stream().map(k -> k.getId().toString()).collect(Collectors.joining(","));
+ String sql = "SELECT id, COALESCE(role_ids::text, '[]') AS role_ids FROM api_key WHERE id IN (" + ids + ")";
+ jdbcTemplate.query(sql, (rs) -> {
+ roleIdsMap.put(rs.getLong("id"), rs.getString("role_ids"));
+ });
+ for (ApiKey key : records) {
+ key.setRoleIds(roleIdsMap.getOrDefault(key.getId(), "[]"));
+ }
+ }
+
Map result = new HashMap<>();
result.put("records", records);
result.put("total", total);
@@ -147,24 +169,60 @@ public class ApiKeyService {
}
/**
- * 自增调用次数
+ * 自增调用次数（SQL 原子操作，避免并发竞态）
*
* @param id Key ID
*/
public void incrementCallCount(Long id) {
- // 使用 SQL 原子操作自增，避免并发问题
try {
- String sql = "UPDATE api_key SET current_calls = current_calls + 1 WHERE id = ?";
- // 通过 MyBatis Plus 无法直接做原子自增，使用 updateById 兜底
- ApiKey existing = apiKeyMapper.selectById(id);
- if (existing != null) {
- existing.setCurrentCalls(
- (existing.getCurrentCalls() != null ? existing.getCurrentCalls() : 0L) + 1
- );
- apiKeyMapper.updateById(existing);
- }
+ jdbcTemplate.update(
+ "UPDATE api_key SET current_calls = current_calls + 1 WHERE id = ? AND is_delete = false",
+ id);
} catch (Exception e) {
log.warn("自增 API Key 调用次数失败: id={}", id, e);
}
}
+
+ /**
+ * 更新 API Key 绑定的客服角色列表
+ * 使用 JdbcTemplate 显式 ::jsonb 转换，避免 MyBatis-Plus 类型不匹配
+ *
+ * @param id API Key ID
+ * @param roleIds 角色 ID 列表（空/null 表示不限制）
+ */
+ public void updateKeyRoles(Long id, List roleIds) {
+ ApiKey existing = apiKeyMapper.selectById(id);
+ if (existing == null) {
+ throw new IllegalArgumentException("API Key 不存在，ID：" + id);
+ }
+ String json;
+ try {
+ json = objectMapper.writeValueAsString(roleIds != null ? roleIds : List.of());
+ } catch (Exception e) {
+ json = "[]";
+ }
+ int rows = jdbcTemplate.update(
+ "UPDATE api_key SET role_ids = ?::jsonb, update_time = CURRENT_TIMESTAMP WHERE id = ? AND is_delete = false",
+ json, id);
+ log.info("API Key 角色绑定已更新: id={}, roleIds={}", id, json);
+ }
+
+ /**
+ * 解析 API Key 绑定的角色 ID 列表
+ *
+ * @param apiKey API Key 实体
+ * @return 角色 ID 列表；空数组表示不限制
+ */
+ public List parseRoleIds(ApiKey apiKey) {
+ if (apiKey == null || apiKey.getRoleIds() == null
+ || apiKey.getRoleIds().isBlank() || "[]".equals(apiKey.getRoleIds().trim())) {
+ return List.of();
+ }
+ try {
+ return objectMapper.readValue(apiKey.getRoleIds(), new TypeReference>() {});
+ } catch (Exception e) {
+ log.warn("解析 role_ids 失败: {}", apiKey.getRoleIds(), e);
+ return List.of();
+ }
+ }
}
diff --git a/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java b/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java
index 9888e52..34ce612 100644
--- a/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java
+++ b/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java
@@ -1,5 +1,8 @@
package com.wok.supportbot.service;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
@@ -10,13 +13,18 @@ import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
+import java.util.stream.Collectors;
@Service
+@Slf4j
public class CustomerServiceRoleService {
@Autowired
private JdbcTemplate jdbcTemplate;
+ @Autowired
+ private ObjectMapper objectMapper;
+
public List> listRoles() {
return listRoles(false);
}
@@ -25,12 +33,16 @@ public class CustomerServiceRoleService {
* @param includeDisabled true=包含已停用角色（管理页用）；false=仅启用角色（对话页用）
*/
public List> listRoles(boolean includeDisabled) {
- String roleSql = "SELECT id::text AS id, role_key, name, description, prompt, sort_order, enabled "
- + "FROM customer_service_role WHERE is_delete = false "
- + (includeDisabled ? "" : "AND enabled = true ")
- + "ORDER BY sort_order ASC, id ASC";
- List> roles = jdbcTemplate.queryForList(roleSql);
+ StringBuilder roleSql = new StringBuilder(
+ "SELECT id::text AS id, role_key, name, description, prompt, enabled, allowed_mcp_tools "
+ + "FROM customer_service_role WHERE is_delete = false ");
+ if (!includeDisabled) {
+ roleSql.append("AND enabled = true ");
+ }
+ roleSql.append("ORDER BY id ASC");
+ List> roles = jdbcTemplate.queryForList(roleSql.toString());
+ // 查询角色-分类关联
String categorySql = """
SELECT rc.role_id::text AS role_id, rc.category_id::text AS category_id, c.name AS category_name
FROM customer_service_role_category rc
@@ -87,7 +99,7 @@ public class CustomerServiceRoleService {
* 新增角色。role_key 缺省时自动生成。
*/
@Transactional(rollbackFor = Exception.class)
- public void createRole(String roleKey, String name, String description, String prompt, Integer sortOrder, Boolean enabled) {
+ public void createRole(String roleKey, String name, String description, String prompt, Boolean enabled) {
if (name == null || name.trim().isEmpty()) {
throw new IllegalArgumentException("角色名称不能为空");
}
@@ -95,11 +107,10 @@ public class CustomerServiceRoleService {
? "role_" + System.currentTimeMillis()
: roleKey.trim();
jdbcTemplate.update("""
- INSERT INTO customer_service_role (role_key, name, description, prompt, sort_order, enabled)
- VALUES (?, ?, ?, ?, ?, ?)
- """,
+ INSERT INTO customer_service_role (role_key, name, description, prompt, enabled)
+ VALUES (?, ?, ?, ?, ?)
+ """,
key, name.trim(), description, prompt,
- sortOrder != null ? sortOrder : 0,
enabled != null ? enabled : true);
}
@@ -107,7 +118,7 @@ public class CustomerServiceRoleService {
* 编辑角色基本信息（不含知识库分类，分类走 {@link #updateRoleCategories}）。
*/
@Transactional(rollbackFor = Exception.class)
- public void updateRole(Long roleId, String name, String description, String prompt, Integer sortOrder, Boolean enabled) {
+ public void updateRole(Long roleId, String name, String description, String prompt, Boolean enabled) {
if (roleId == null || roleId <= 0) {
throw new IllegalArgumentException("角色ID无效");
}
@@ -116,11 +127,10 @@ public class CustomerServiceRoleService {
}
jdbcTemplate.update("""
UPDATE customer_service_role
- SET name = ?, description = ?, prompt = ?, sort_order = ?, enabled = ?, update_time = CURRENT_TIMESTAMP
+ SET name = ?, description = ?, prompt = ?, enabled = ?, update_time = CURRENT_TIMESTAMP
WHERE id = ? AND is_delete = false
""",
name.trim(), description, prompt,
- sortOrder != null ? sortOrder : 0,
enabled != null ? enabled : true,
roleId);
}
@@ -137,6 +147,28 @@ public class CustomerServiceRoleService {
jdbcTemplate.update("UPDATE customer_service_role_category SET is_delete = true WHERE role_id = ?", roleId);
}
+ /**
+ * 更新角色的 MCP 工具权限。
+ *
+ * @param roleId 角色ID
+ * @param allowedMcpTools 允许的 MCP 工具名列表；["*"]=全部允许，空/null=不允许任何工具
+ */
+ @Transactional(rollbackFor = Exception.class)
+ public void updateRoleMcpTools(Long roleId, List allowedMcpTools) {
+ if (roleId == null || roleId <= 0) {
+ throw new IllegalArgumentException("角色ID无效");
+ }
+ String json;
+ try {
+ json = objectMapper.writeValueAsString(allowedMcpTools != null ? allowedMcpTools : List.of());
+ } catch (Exception e) {
+ json = "[]";
+ }
+ jdbcTemplate.update(
+ "UPDATE customer_service_role SET allowed_mcp_tools = ?::jsonb, update_time = CURRENT_TIMESTAMP WHERE id = ? AND is_delete = false",
+ json, roleId);
+ }
+
/**
* 服务端解析角色的知识库范围与人设。
* 用于对话时强制约束：角色只能检索其绑定分类下的内容，由后端决定，客户端无法越权跨域。
@@ -149,7 +181,7 @@ public class CustomerServiceRoleService {
return RoleScope.empty();
}
List> rows = jdbcTemplate.queryForList(
- "SELECT name, prompt FROM customer_service_role WHERE id = ? AND is_delete = false AND enabled = true",
+ "SELECT name, prompt, allowed_mcp_tools FROM customer_service_role WHERE id = ? AND is_delete = false AND enabled = true",
roleId);
if (rows.isEmpty()) {
return RoleScope.empty();
@@ -159,22 +191,97 @@ public class CustomerServiceRoleService {
List categoryIds = jdbcTemplate.queryForList(
"SELECT category_id FROM customer_service_role_category WHERE role_id = ? AND is_delete = false",
Long.class, roleId);
- return new RoleScope(true, name, prompt, categoryIds);
+ // 解析 allowed_mcp_tools JSONB 字段
+ List allowedMcpTools = parseAllowedMcpTools(rows.get(0).get("allowed_mcp_tools"));
+ return new RoleScope(true, name, prompt, categoryIds, allowedMcpTools);
+ }
+
+ /**
+ * 解析 allowed_mcp_tools JSONB 字段为 List
+ * 兼容 PostgreSQL JSONB、Java List、String 等多种输入类型
+ */
+ private List parseAllowedMcpTools(Object raw) {
+ if (raw == null) {
+ return List.of();
+ }
+ try {
+ if (raw instanceof List list) {
+ return list.stream().map(Objects::toString).toList();
+ }
+ String json = raw.toString().trim();
+ if (json.isEmpty() || "[]".equals(json) || "null".equals(json)) {
+ return List.of();
+ }
+ return objectMapper.readValue(json, new TypeReference<>() {});
+ } catch (Exception e) {
+ log.warn("解析 allowed_mcp_tools 失败: {}", raw, e);
+ return List.of();
+ }
+ }
+
+ /**
+ * 精简角色信息（Token 换取接口用）
+ */
+ public record RoleBrief(Long id, String roleKey, String name) {}
+
+ /**
+ * 查询所有启用的客服角色（精简字段）
+ *
+ * @return 精简角色信息列表
+ */
+ public List listEnabledRolesBrief() {
+ String sql = "SELECT id, role_key, name FROM customer_service_role " +
+ "WHERE enabled = true AND is_delete = false ORDER BY id";
+ return jdbcTemplate.query(sql, (rs, i) -> new RoleBrief(
+ rs.getLong("id"),
+ rs.getString("role_key"),
+ rs.getString("name")
+ ));
}
/**
- * 角色范围：是否命中角色、角色人设、可检索的知识库分类。
+ * 根据 ID 列表查询启用的客服角色（精简字段，用于 API Key 角色绑定的 Token 换取）
+ *
+ * @param roleIds 角色 ID 列表
+ * @return 精简角色信息列表
+ */
+ public List listRolesByIds(List roleIds) {
+ if (roleIds == null || roleIds.isEmpty()) {
+ return List.of();
+ }
+ String placeholders = roleIds.stream().map(id -> "?").collect(Collectors.joining(","));
+ String sql = "SELECT id, role_key, name FROM customer_service_role " +
+ "WHERE enabled = true AND is_delete = false AND id IN (" + placeholders + ") ORDER BY id";
+ return jdbcTemplate.query(sql, (rs, i) -> new RoleBrief(
+ rs.getLong("id"),
+ rs.getString("role_key"),
+ rs.getString("name")
+ ), roleIds.toArray());
+ }
+
+ /**
+ * 角色范围：是否命中角色、角色人设、可检索的知识库分类、MCP 工具权限。
*/
- public record RoleScope(boolean present, String name, String prompt, List categoryIds) {
+ public record RoleScope(boolean present, String name, String prompt, List categoryIds, List allowedMcpTools) {
public static RoleScope empty() {
- return new RoleScope(false, "", "", List.of());
+ return new RoleScope(false, "", "", List.of(), List.of());
}
public boolean hasRole() {
return present;
}
+ /** 是否允许使用 MCP 工具（非空即允许） */
+ public boolean isMcpToolsAllowed() {
+ return allowedMcpTools != null && !allowedMcpTools.isEmpty();
+ }
+
+ /** 是否允许使用所有 MCP 工具（["*"] 表示全部允许） */
+ public boolean isAllMcpToolsAllowed() {
+ return allowedMcpTools != null && allowedMcpTools.contains("*");
+ }
+
/**
* 组合角色系统提示词：当前客服角色 + 人设；都为空时返回 null（退回基础提示词）。
*/
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index aa0eb1b..b3ec335 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -73,6 +73,9 @@ public class DocumentService {
@Autowired
private DocumentProcessingService documentProcessingService;
+ @Autowired
+ private com.wok.supportbot.config.FileStorageConfig fileStorageConfig;
+
// ==================== 文档上传 ====================
/**
@@ -90,13 +93,15 @@ public class DocumentService {
* @param tags 标签列表
* @param chunkSize 分块大小（可选，覆盖全局配置）
* @param overlap 重叠大小（可选，覆盖全局配置）
+ * @param filePath 原始文件存储路径（可选，null表示无原始文件）
* @return 创建完成的文档记录（status=PROCESSING）
*/
@Transactional(rollbackFor = Exception.class)
public KnowledgeDocument uploadDocument(List documents, String title, String sourceName,
String fileType, Long fileSize, String content,
Long categoryId, List tags,
- Integer chunkSize, Integer overlap) {
+ Integer chunkSize, Integer overlap,
+ String filePath) {
// 0. 内容去重检查
String contentHash = computeContentHash(content);
if (contentHash != null) {
@@ -117,6 +122,7 @@ public class DocumentService {
.sourceName(sourceName)
.fileType(fileType)
.fileSize(fileSize != null ? fileSize : 0L)
+ .filePath(filePath)
.content(content != null && content.length() > 2000 ? content.substring(0, 2000) : content)
.categoryId(categoryId != null ? categoryId : 0L)
.tags(tags != null ? Map.of("tags", tags) : null)
@@ -138,12 +144,19 @@ public class DocumentService {
}
/**
- * 解析文件并上传
+ * 解析文件并上传（同时保存原始文件到本地）
*/
public KnowledgeDocument uploadFile(MultipartFile file, String title, Long categoryId, List tags,
Integer chunkSize, Integer overlap) {
- List documents = tikaDocumentReader.read(file);
+ // 1. 先保存原始文件到本地磁盘（必须在解析之前，因为 transferTo 只能调用一次）
+ String relativePath = saveFileToLocal(file);
+ java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
+
+ // 2. 使用保存的文件进行解析（避免 MultipartFile 的临时文件问题）
+ List documents = tikaDocumentReader.readFromFile(savedFile);
String fileType = getFileExtension(file.getOriginalFilename());
+
+ // 3. 创建文档记录并保存文件路径
return uploadDocument(documents,
title != null ? title : file.getOriginalFilename(),
file.getOriginalFilename(),
@@ -151,17 +164,45 @@ public class DocumentService {
file.getSize(),
documents.get(0).getText(),
categoryId,
- tags, chunkSize, overlap);
+ tags, chunkSize, overlap,
+ relativePath);
+ }
+
+ /**
+ * 保存上传的文件到本地磁盘
+ *
+ * @param file 上传的文件
+ * @return 相对路径
+ */
+ private String saveFileToLocal(MultipartFile file) {
+ try {
+ String relativePath = fileStorageConfig.generateRelativePath(file.getOriginalFilename());
+ java.nio.file.Path targetPath = fileStorageConfig.getFilePath(relativePath);
+
+ // 确保父目录存在
+ java.io.File parentDir = targetPath.getParent().toFile();
+ if (!parentDir.exists()) {
+ parentDir.mkdirs();
+ }
+
+ // 使用 transferTo 保存文件（这是唯一一次调用）
+ file.transferTo(targetPath.toFile());
+ log.info("文件已保存到本地: {}", targetPath);
+ return relativePath;
+ } catch (java.io.IOException e) {
+ log.error("保存文件到本地失败", e);
+ throw new RuntimeException("保存文件失败: " + e.getMessage(), e);
+ }
}
/**
- * 解析字符串并上传
+ * 解析字符串并上传（无原始文件）
*/
public KnowledgeDocument uploadString(String content, String title, Long categoryId, List tags,
Integer chunkSize, Integer overlap) {
List documents = simpleStringDocumentReader.read(content);
return uploadDocument(documents, title, title, "txt",
- (long) content.length(), content, categoryId, tags, chunkSize, overlap);
+ (long) content.length(), content, categoryId, tags, chunkSize, overlap, null);
}
/**
@@ -169,8 +210,14 @@ public class DocumentService {
*/
public KnowledgeDocument uploadMarkdown(MultipartFile file, String title, Long categoryId, List tags,
Integer chunkSize, Integer overlap) {
- List documents = markdownDocumentLoader.loadMarkdownFromFile(file);
+ // 1. 先保存原始文件
+ String relativePath = saveFileToLocal(file);
+ java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
+
+ // 2. 使用保存的文件进行解析
+ List documents = markdownDocumentLoader.loadMarkdownFromFile(savedFile);
String content = documents.stream().map(Document::getText).collect(Collectors.joining("\n"));
+
return uploadDocument(documents,
title != null ? title : file.getOriginalFilename(),
file.getOriginalFilename(),
@@ -178,7 +225,8 @@ public class DocumentService {
file.getSize(),
content,
categoryId,
- tags, chunkSize, overlap);
+ tags, chunkSize, overlap,
+ relativePath);
}
/**
@@ -186,8 +234,14 @@ public class DocumentService {
*/
public KnowledgeDocument uploadJsonBasic(MultipartFile file, String title, Long categoryId, List tags,
Integer chunkSize, Integer overlap) {
- List documents = jsonDocumentLoader.loadBasicJson(file);
+ // 1. 先保存原始文件
+ String relativePath = saveFileToLocal(file);
+ java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
+
+ // 2. 使用保存的文件进行解析
+ List documents = jsonDocumentLoader.loadBasicJsonFromFile(savedFile);
String content = documents.stream().map(Document::getText).collect(Collectors.joining("\n"));
+
return uploadDocument(documents,
title != null ? title : file.getOriginalFilename(),
file.getOriginalFilename(),
@@ -195,7 +249,8 @@ public class DocumentService {
file.getSize(),
content,
categoryId,
- tags, chunkSize, overlap);
+ tags, chunkSize, overlap,
+ relativePath);
}
/**
@@ -204,8 +259,14 @@ public class DocumentService {
public KnowledgeDocument uploadJsonFields(MultipartFile file, List fields, String title,
Long categoryId, List tags,
Integer chunkSize, Integer overlap) {
- List documents = jsonDocumentLoader.loadJsonByFields(file, fields.toArray(new String[0]));
+ // 1. 先保存原始文件
+ String relativePath = saveFileToLocal(file);
+ java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
+
+ // 2. 使用保存的文件进行解析
+ List documents = jsonDocumentLoader.loadJsonByFieldsFromFile(savedFile, fields.toArray(new String[0]));
String content = documents.stream().map(Document::getText).collect(Collectors.joining("\n"));
+
return uploadDocument(documents,
title != null ? title : file.getOriginalFilename(),
file.getOriginalFilename(),
@@ -213,7 +274,8 @@ public class DocumentService {
file.getSize(),
content,
categoryId,
- tags, chunkSize, overlap);
+ tags, chunkSize, overlap,
+ relativePath);
}
/**
@@ -222,8 +284,14 @@ public class DocumentService {
public KnowledgeDocument uploadJsonPointer(MultipartFile file, String pointer, String title,
Long categoryId, List tags,
Integer chunkSize, Integer overlap) {
- List documents = jsonDocumentLoader.loadJsonByPointer(file, pointer);
+ // 1. 先保存原始文件
+ String relativePath = saveFileToLocal(file);
+ java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
+
+ // 2. 使用保存的文件进行解析
+ List documents = jsonDocumentLoader.loadJsonByPointerFromFile(savedFile, pointer);
String content = documents.stream().map(Document::getText).collect(Collectors.joining("\n"));
+
return uploadDocument(documents,
title != null ? title : file.getOriginalFilename(),
file.getOriginalFilename(),
@@ -231,7 +299,33 @@ public class DocumentService {
file.getSize(),
content,
categoryId,
- tags, chunkSize, overlap);
+ tags, chunkSize, overlap,
+ relativePath);
+ }
+
+ // ==================== 文件下载 ====================
+
+ /**
+ * 获取文档的原始文件（用于下载）
+ *
+ * @param documentId 文档ID
+ * @return 文件对象和原始文件名
+ */
+ public java.util.Map.Entry getDocumentFile(Long documentId) {
+ KnowledgeDocument doc = documentMapper.selectById(documentId);
+ if (doc == null || doc.isDelete()) {
+ throw new RuntimeException("文档不存在");
+ }
+ if (doc.getFilePath() == null || doc.getFilePath().isEmpty()) {
+ throw new RuntimeException("该文档无原始文件（纯文本上传）");
+ }
+
+ java.io.File file = fileStorageConfig.getFilePath(doc.getFilePath()).toFile();
+ if (!file.exists()) {
+ throw new RuntimeException("文件不存在或已被删除");
+ }
+
+ return java.util.Map.entry(file, doc.getSourceName());
}
// ==================== 文档管理 ====================
@@ -907,7 +1001,7 @@ public class DocumentService {
}
/**
- * 创建分类
+ * 创建知识库分类
*/
public KnowledgeCategory createCategory(String name, String description, Long parentId, Integer sortOrder) {
KnowledgeCategory category = KnowledgeCategory.builder()
diff --git a/src/main/java/com/wok/supportbot/service/FaqService.java b/src/main/java/com/wok/supportbot/service/FaqService.java
index 070f774..dbf5d22 100644
--- a/src/main/java/com/wok/supportbot/service/FaqService.java
+++ b/src/main/java/com/wok/supportbot/service/FaqService.java
@@ -259,7 +259,8 @@ public class FaqService {
Map stats = new HashMap<>();
// 总 FAQ 数
- Long totalCount = faqMapper.selectCount(new QueryWrapper<>());
+ QueryWrapper totalWrapper = new QueryWrapper<>();
+ Long totalCount = faqMapper.selectCount(totalWrapper);
stats.put("totalCount", totalCount);
// 启用数
diff --git a/src/main/java/com/wok/supportbot/service/McpServerConfigService.java b/src/main/java/com/wok/supportbot/service/McpServerConfigService.java
new file mode 100644
index 0000000..cb1dd4f
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/service/McpServerConfigService.java
@@ -0,0 +1,320 @@
+package com.wok.supportbot.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.wok.supportbot.dao.McpServerConfigMapper;
+import com.wok.supportbot.entity.McpServerConfig;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.*;
+
+/**
+ * MCP Server 配置管理服务
+ * 提供 CRUD、启用/禁用、JSONB 字段显式持久化等功能
+ */
+@Service
+@Slf4j
+public class McpServerConfigService {
+
+ @Autowired
+ private McpServerConfigMapper mcpServerConfigMapper;
+
+ @Autowired
+ private JdbcTemplate jdbcTemplate;
+
+ /** 复用的 JSON 序列化器，避免每次持久化都新建实例 */
+ private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+ // ==================== 分页列表 ====================
+
+ /**
+ * 分页查询 MCP Server 配置列表
+ *
+ * @param page 页码（从1开始）
+ * @param size 每页大小
+ * @return 分页结果（records/total/page/size/pages）
+ */
+ public Map listConfigs(int page, int size) {
+ // 查询总数
+ LambdaQueryWrapper countWrapper = new LambdaQueryWrapper<>();
+ Long total = mcpServerConfigMapper.selectCount(countWrapper);
+ if (total == null) total = 0L;
+
+ // 查询列表（带排序和分页）
+ LambdaQueryWrapper listWrapper = new LambdaQueryWrapper<>();
+ listWrapper.orderByDesc(McpServerConfig::getCreateTime);
+ listWrapper.last("LIMIT " + size + " OFFSET " + ((page - 1) * size));
+ List records = mcpServerConfigMapper.selectList(listWrapper);
+
+ // 格式化返回结果
+ List> formattedRecords = new ArrayList<>();
+ for (McpServerConfig record : records) {
+ formattedRecords.add(formatConfig(record));
+ }
+
+ Map result = new LinkedHashMap<>();
+ result.put("records", formattedRecords);
+ result.put("total", total);
+ result.put("page", page);
+ result.put("size", size);
+ result.put("pages", (total + size - 1) / size);
+ return result;
+ }
+
+ // ==================== 详情 ====================
+
+ /**
+ * 获取单条配置详情
+ *
+ * @param id 配置ID
+ * @return 格式化的配置详情，不存在返回 null
+ */
+ public Map getConfigDetail(Long id) {
+ McpServerConfig config = mcpServerConfigMapper.selectById(id);
+ if (config == null) {
+ return null;
+ }
+ return formatConfig(config);
+ }
+
+ // ==================== 新建配置 ====================
+
+ /**
+ * 新建 MCP Server 配置
+ *
+ * @param config 配置对象
+ * @return 保存后的配置（格式化）
+ */
+ @Transactional(rollbackFor = Exception.class)
+ public Map createConfig(McpServerConfig config) {
+ // 校验必填字段
+ validateRequired(config);
+
+ mcpServerConfigMapper.insert(config);
+ // JSONB 字段显式持久化，避免 MyBatis Plus typeHandler 不触发的问题
+ persistEnvVars(config.getId(), config.getEnvVars());
+
+ log.info("新建 MCP Server 配置: name={}, transportType={}", config.getName(), config.getTransportType());
+ return formatConfig(mcpServerConfigMapper.selectById(config.getId()));
+ }
+
+ // ==================== 更新配置 ====================
+
+ /**
+ * 更新 MCP Server 配置
+ * 使用 LambdaUpdateWrapper 显式设置所有字段（含 null），
+ * 避免 updateById 默认跳过 null 字段导致无法清空可选字段。
+ *
+ * @param id 配置ID
+ * @param config 更新内容
+ * @return 更新后的配置（格式化）
+ */
+ @Transactional(rollbackFor = Exception.class)
+ public Map updateConfig(Long id, McpServerConfig config) {
+ McpServerConfig existing = mcpServerConfigMapper.selectById(id);
+ if (existing == null) {
+ throw new RuntimeException("配置不存在: id=" + id);
+ }
+
+ // 使用 LambdaUpdateWrapper 显式设置所有字段，null 也会被写入（清空语义）
+ LambdaUpdateWrapper updateWrapper = new LambdaUpdateWrapper<>();
+ updateWrapper.eq(McpServerConfig::getId, id)
+ .set(McpServerConfig::getName, config.getName())
+ .set(McpServerConfig::getTransportType, config.getTransportType())
+ .set(McpServerConfig::getServerUrl, config.getServerUrl())
+ .set(McpServerConfig::getCommand, config.getCommand())
+ .set(McpServerConfig::getArgs, config.getArgs())
+ .set(McpServerConfig::getDescription, config.getDescription());
+ // isActive 仅在前端显式传入时更新，null 表示不修改
+ if (config.getIsActive() != null) {
+ updateWrapper.set(McpServerConfig::getIsActive, config.getIsActive());
+ }
+ mcpServerConfigMapper.update(null, updateWrapper);
+
+ // JSONB 字段显式持久化（LambdaUpdateWrapper 不支持 JSONB 类型）
+ // null 或空 Map 均执行持久化（清空语义），与 LambdaUpdateWrapper 行为一致
+ persistEnvVars(id, config.getEnvVars());
+
+ log.info("更新 MCP Server 配置: id={}", id);
+ return formatConfig(mcpServerConfigMapper.selectById(id));
+ }
+
+ // ==================== 删除配置 ====================
+
+ /**
+ * 逻辑删除 MCP Server 配置
+ *
+ * @param id 配置ID
+ */
+ @Transactional(rollbackFor = Exception.class)
+ public void deleteConfig(Long id) {
+ McpServerConfig config = mcpServerConfigMapper.selectById(id);
+ if (config == null) {
+ throw new RuntimeException("配置不存在: id=" + id);
+ }
+ mcpServerConfigMapper.deleteById(id);
+ log.info("逻辑删除 MCP Server 配置: id={}, name={}", id, config.getName());
+ }
+
+ // ==================== 启用/禁用 ====================
+
+ /**
+ * 切换配置启用状态
+ *
+ * @param id 配置ID
+ * @param active 是否启用
+ */
+ @Transactional(rollbackFor = Exception.class)
+ public void toggleActive(Long id, boolean active) {
+ McpServerConfig config = mcpServerConfigMapper.selectById(id);
+ if (config == null) {
+ throw new RuntimeException("配置不存在: id=" + id);
+ }
+
+ LambdaUpdateWrapper updateWrapper = new LambdaUpdateWrapper<>();
+ updateWrapper.eq(McpServerConfig::getId, id)
+ .set(McpServerConfig::getIsActive, active);
+ mcpServerConfigMapper.update(null, updateWrapper);
+
+ log.info("切换 MCP Server 配置状态: id={}, name={}, active={}", id, config.getName(), active);
+ }
+
+ // ==================== 活跃配置查询 ====================
+
+ /**
+ * 获取所有启用的 SSE 类型配置
+ * 供 McpClientManager 建立 SSE 连接使用
+ *
+ * @return SSE 类型的活跃配置列表
+ */
+ public List listActiveSseConfigs() {
+ LambdaQueryWrapper wrapper = new LambdaQueryWrapper<>();
+ wrapper.eq(McpServerConfig::getIsActive, true)
+ .eq(McpServerConfig::getTransportType, "sse");
+ return mcpServerConfigMapper.selectList(wrapper);
+ }
+
+ /**
+ * 获取所有启用的 stdio 类型配置
+ * 供 McpClientManager 启动 stdio 进程使用
+ *
+ * @return stdio 类型的活跃配置列表
+ */
+ public List listActiveStdioConfigs() {
+ LambdaQueryWrapper wrapper = new LambdaQueryWrapper<>();
+ wrapper.eq(McpServerConfig::getIsActive, true)
+ .eq(McpServerConfig::getTransportType, "stdio");
+ return mcpServerConfigMapper.selectList(wrapper);
+ }
+
+ /**
+ * 根据 ID 获取配置（含完整字段，仅供内部使用）
+ *
+ * @param id 配置ID
+ * @return 原始配置对象，不存在返回 null
+ */
+ public McpServerConfig getConfigById(Long id) {
+ return mcpServerConfigMapper.selectById(id);
+ }
+
+ /**
+ * 获取所有启用的配置（不区分传输类型）
+ * 供 McpClientManager.refreshAll() 一次查询获取所有活跃配置
+ *
+ * @return 所有启用的配置列表
+ */
+ public List listAllActiveConfigs() {
+ LambdaQueryWrapper wrapper = new LambdaQueryWrapper<>();
+ wrapper.eq(McpServerConfig::getIsActive, true);
+ return mcpServerConfigMapper.selectList(wrapper);
+ }
+
+ // ==================== 工具方法 ====================
+
+ /**
+ * 校验必填字段
+ *
+ * @param config 配置对象
+ */
+ private void validateRequired(McpServerConfig config) {
+ if (config.getName() == null || config.getName().trim().isEmpty()) {
+ throw new IllegalArgumentException("配置名称不能为空");
+ }
+ if (config.getTransportType() == null || config.getTransportType().trim().isEmpty()) {
+ throw new IllegalArgumentException("传输类型不能为空");
+ }
+ // 根据传输类型校验对应必填字段
+ switch (config.getTransportType()) {
+ case "sse":
+ if (config.getServerUrl() == null || config.getServerUrl().trim().isEmpty()) {
+ throw new IllegalArgumentException("SSE 模式下服务地址不能为空");
+ }
+ break;
+ case "stdio":
+ if (config.getCommand() == null || config.getCommand().trim().isEmpty()) {
+ throw new IllegalArgumentException("stdio 模式下启动命令不能为空");
+ }
+ break;
+ default:
+ throw new IllegalArgumentException("不支持的传输类型: " + config.getTransportType());
+ }
+ }
+
+ /**
+ * 格式化配置为前端返回格式
+ * 雪花 ID 转字符串、时间格式化
+ *
+ * @param config 原始配置
+ * @return 格式化后的 Map
+ */
+ private Map formatConfig(McpServerConfig config) {
+ Map formatted = new LinkedHashMap<>();
+ // 雪花 ID 必须转为字符串，避免 JS 精度丢失
+ formatted.put("id", config.getId().toString());
+ formatted.put("name", config.getName());
+ formatted.put("transport_type", config.getTransportType());
+ formatted.put("server_url", config.getServerUrl());
+ formatted.put("command", config.getCommand());
+ formatted.put("args", config.getArgs());
+ formatted.put("env_vars", config.getEnvVars());
+ formatted.put("description", config.getDescription());
+ formatted.put("is_active", config.getIsActive());
+ formatted.put("create_time", config.getCreateTime());
+ formatted.put("update_time", config.getUpdateTime());
+ return formatted;
+ }
+
+ /**
+ * 显式持久化 envVars JSONB 字段
+ * MyBatis Plus 的 insert/updateById 对带 typeHandler 的 JSONB 字段可能不触发写入，
+ * 使用 JdbcTemplate 显式更新保证数据可靠落库。
+ *
+ * @param id 配置ID
+ * @param envVars 环境变量 Map
+ */
+ private void persistEnvVars(Long id, Map envVars) {
+ if (id == null) {
+ return;
+ }
+ try {
+ String json;
+ if (envVars == null || envVars.isEmpty()) {
+ json = "{}";
+ } else {
+ json = OBJECT_MAPPER.writeValueAsString(envVars);
+ }
+ jdbcTemplate.update(
+ "UPDATE mcp_server_config SET env_vars = ?::jsonb WHERE id = ?",
+ json, id);
+ log.debug("持久化 envVars: id={}, envVars={}", id, json);
+ } catch (Exception e) {
+ log.error("持久化 envVars 失败: id={}, error={}", id, e.getMessage());
+ throw new RuntimeException("持久化环境变量失败: " + e.getMessage(), e);
+ }
+ }
+}
diff --git a/src/main/resources/application-dev.yml b/src/main/resources/application-dev.yml
index e5f0aaf..472c471 100644
--- a/src/main/resources/application-dev.yml
+++ b/src/main/resources/application-dev.yml
@@ -23,6 +23,11 @@ spring:
knife4j:
enable: true
+# ==================== 文件存储路径 ====================
+knowledge:
+ storage:
+ local-path: D:/uploads
+
# ==================== 日志级别 ====================
logging:
level:
diff --git a/src/main/resources/application-prod.yml b/src/main/resources/application-prod.yml
index e4787ac..e0dbdaa 100644
--- a/src/main/resources/application-prod.yml
+++ b/src/main/resources/application-prod.yml
@@ -32,10 +32,15 @@ spring:
knife4j:
enable: false
+# ==================== 文件存储路径 ====================
+knowledge:
+ storage:
+ local-path: /www/uploads
+
# ==================== 日志级别 ====================
# 生产环境收敛日志，仅保留 WARN 及以上，业务代码保留 INFO
logging:
level:
- root: WARN
+ root: INFO
com.wok.supportbot: INFO
- org.springframework.ai: WARN
+ org.springframework.ai: INFO
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index ec43dba..fd9e56d 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -64,6 +64,10 @@ knowledge:
faq:
# FAQ 语义匹配阈值（0-1），低于此值自动降级到 RAG 检索
semantic-threshold: 0.85
+ storage:
+ # 上传文件本地存储根路径（Windows: D:/uploads, Linux: /data/uploads）
+ # 各环境可在 application-{env}.yml 中覆盖
+ local-path: ./uploads
# ==================== Knife4j API 文档通用配置 ====================
# knife4j.enable 开关在各环境 yml 中配置（生产环境建议关闭）
@@ -102,3 +106,8 @@ jwt:
expiration: 86400000
# 刷新令牌有效期：7天（毫秒）
refresh-expiration: 604800000
+ # ==================== SDK 专用 JWT 配置 ====================
+ # SDK Token 签名密钥（独立于管理后台 JWT 密钥，生产环境务必覆盖）
+ sdk-secret: support-bot-sdk-jwt-secret-2026-please-change
+ # SDK Token 默认有效期：2小时（毫秒）
+ sdk-expiration: 7200000
diff --git a/src/main/resources/init-database.sql b/src/main/resources/init-database.sql
index af1d7cb..8549303 100644
--- a/src/main/resources/init-database.sql
+++ b/src/main/resources/init-database.sql
@@ -41,7 +41,7 @@ CREATE TABLE IF NOT EXISTS chat_message (
create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
is_delete BOOLEAN NOT NULL DEFAULT FALSE,
- CONSTRAINT chk_message_type CHECK (message_type IN ('USER', 'ASSISTANT', 'SYSTEM'))
+ CONSTRAINT chk_message_type CHECK (message_type IN ('USER', 'ASSISTANT', 'SYSTEM', 'TOOL'))
);
CREATE INDEX IF NOT EXISTS idx_chat_message_conversation_id ON chat_message (conversation_id);
@@ -94,6 +94,7 @@ CREATE TABLE IF NOT EXISTS knowledge_document (
source_name VARCHAR(500),
file_type VARCHAR(20) NOT NULL,
file_size BIGINT NOT NULL DEFAULT 0,
+ file_path VARCHAR(500),
content TEXT,
category_id BIGINT NOT NULL DEFAULT 0,
tags JSONB NOT NULL DEFAULT '{}',
@@ -101,6 +102,8 @@ CREATE TABLE IF NOT EXISTS knowledge_document (
status VARCHAR(20) NOT NULL DEFAULT 'PROCESSING',
error_message TEXT,
content_hash VARCHAR(64),
+ enabled BOOLEAN NOT NULL DEFAULT TRUE,
+ extra_config JSONB NOT NULL DEFAULT '{}',
create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
is_delete BOOLEAN NOT NULL DEFAULT FALSE
@@ -110,6 +113,7 @@ CREATE INDEX IF NOT EXISTS idx_knowledge_document_category ON knowledge_docu
CREATE INDEX IF NOT EXISTS idx_knowledge_document_status ON knowledge_document (status);
CREATE INDEX IF NOT EXISTS idx_knowledge_document_create_time ON knowledge_document (create_time DESC);
CREATE INDEX IF NOT EXISTS idx_knowledge_document_content_hash ON knowledge_document (content_hash);
+CREATE INDEX IF NOT EXISTS idx_knowledge_document_enabled ON knowledge_document (enabled);
COMMENT ON TABLE knowledge_document IS '知识文档表';
COMMENT ON COLUMN knowledge_document.id IS '主键';
@@ -117,6 +121,7 @@ COMMENT ON COLUMN knowledge_document.title IS '文档标题';
COMMENT ON COLUMN knowledge_document.source_name IS '原始文件名';
COMMENT ON COLUMN knowledge_document.file_type IS '文件类型';
COMMENT ON COLUMN knowledge_document.file_size IS '文件大小（字节）';
+COMMENT ON COLUMN knowledge_document.file_path IS '原始文件存储路径（相对路径）';
COMMENT ON COLUMN knowledge_document.content IS '原文内容（截断预览）';
COMMENT ON COLUMN knowledge_document.category_id IS '所属分类ID';
COMMENT ON COLUMN knowledge_document.tags IS '标签（JSON）';
@@ -124,6 +129,8 @@ COMMENT ON COLUMN knowledge_document.chunk_count IS '分块数量';
COMMENT ON COLUMN knowledge_document.status IS '状态: PROCESSING / READY / FAILED';
COMMENT ON COLUMN knowledge_document.error_message IS '处理失败时的错误信息';
COMMENT ON COLUMN knowledge_document.content_hash IS '内容SHA-256哈希（用于去重）';
+COMMENT ON COLUMN knowledge_document.enabled IS '是否启用';
+COMMENT ON COLUMN knowledge_document.extra_config IS '扩展配置（JSON）';
COMMENT ON COLUMN knowledge_document.create_time IS '创建时间';
COMMENT ON COLUMN knowledge_document.update_time IS '更新时间';
COMMENT ON COLUMN knowledge_document.is_delete IS '逻辑删除';
@@ -137,14 +144,14 @@ CREATE TABLE IF NOT EXISTS customer_service_role (
name VARCHAR(100) NOT NULL,
description TEXT,
prompt TEXT,
- sort_order INTEGER NOT NULL DEFAULT 0,
enabled BOOLEAN NOT NULL DEFAULT TRUE,
create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
- is_delete BOOLEAN NOT NULL DEFAULT FALSE
+ is_delete BOOLEAN NOT NULL DEFAULT FALSE,
+ allowed_mcp_tools JSONB NOT NULL DEFAULT '[]'
);
-CREATE INDEX IF NOT EXISTS idx_customer_service_role_enabled ON customer_service_role (enabled, sort_order);
+CREATE INDEX IF NOT EXISTS idx_customer_service_role_enabled ON customer_service_role (enabled);
COMMENT ON TABLE customer_service_role IS '客服角色表';
COMMENT ON COLUMN customer_service_role.id IS '主键';
@@ -152,23 +159,23 @@ COMMENT ON COLUMN customer_service_role.role_key IS '角色标识符（唯一
COMMENT ON COLUMN customer_service_role.name IS '角色名称';
COMMENT ON COLUMN customer_service_role.description IS '角色描述';
COMMENT ON COLUMN customer_service_role.prompt IS '系统提示词';
-COMMENT ON COLUMN customer_service_role.sort_order IS '排序权重';
COMMENT ON COLUMN customer_service_role.enabled IS '是否启用';
COMMENT ON COLUMN customer_service_role.create_time IS '创建时间';
COMMENT ON COLUMN customer_service_role.update_time IS '更新时间';
COMMENT ON COLUMN customer_service_role.is_delete IS '逻辑删除';
+COMMENT ON COLUMN customer_service_role.allowed_mcp_tools IS '允许使用的 MCP 工具列表（JSONB 数组，空=不允许，["*"]=全部允许）';
-- 默认角色种子数据
-INSERT INTO customer_service_role (role_key, name, description, sort_order, enabled)
-VALUES ('general', '客服', '通用客服角色', 0, TRUE)
+INSERT INTO customer_service_role (role_key, name, description, enabled)
+VALUES ('general', '客服', '通用客服角色', TRUE)
ON CONFLICT (role_key) DO NOTHING;
-INSERT INTO customer_service_role (role_key, name, description, sort_order, enabled)
-VALUES ('finance', '财务', '财务相关客服角色', 1, TRUE)
+INSERT INTO customer_service_role (role_key, name, description, enabled)
+VALUES ('finance', '财务', '财务相关客服角色', TRUE)
ON CONFLICT (role_key) DO NOTHING;
-INSERT INTO customer_service_role (role_key, name, description, sort_order, enabled)
-VALUES ('administration', '行政', '行政相关客服角色', 2, TRUE)
+INSERT INTO customer_service_role (role_key, name, description, enabled)
+VALUES ('administration', '行政', '行政相关客服角色', TRUE)
ON CONFLICT (role_key) DO NOTHING;
-- ============================================================
@@ -261,6 +268,40 @@ COMMENT ON COLUMN conversation_session.role_id IS '归属角色ID';
COMMENT ON COLUMN conversation_session.create_time IS '创建时间';
COMMENT ON COLUMN conversation_session.update_time IS '更新时间';
+-- ============================================================
+-- 表 7.5: mcp_server_config — MCP Server 配置表
+-- ============================================================
+CREATE TABLE IF NOT EXISTS mcp_server_config (
+ id BIGINT PRIMARY KEY,
+ name VARCHAR(100) NOT NULL,
+ transport_type VARCHAR(20) NOT NULL DEFAULT 'sse',
+ server_url VARCHAR(500),
+ command VARCHAR(500),
+ args VARCHAR(1000),
+ env_vars JSONB DEFAULT '{}' NOT NULL,
+ description VARCHAR(500),
+ is_active BOOLEAN DEFAULT TRUE NOT NULL,
+ create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ is_delete BOOLEAN NOT NULL DEFAULT FALSE
+);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_server_config_active ON mcp_server_config (is_active) WHERE is_delete = FALSE;
+
+COMMENT ON TABLE mcp_server_config IS 'MCP Server 配置表（管理外部 MCP Server 连接配置）';
+COMMENT ON COLUMN mcp_server_config.id IS '主键（雪花算法生成）';
+COMMENT ON COLUMN mcp_server_config.name IS '配置名称';
+COMMENT ON COLUMN mcp_server_config.transport_type IS '传输类型: stdio(标准输入输出) / sse(Server-Sent Events)';
+COMMENT ON COLUMN mcp_server_config.server_url IS 'SSE 模式的 MCP Server URL';
+COMMENT ON COLUMN mcp_server_config.command IS 'stdio 模式的启动命令';
+COMMENT ON COLUMN mcp_server_config.args IS 'stdio 模式的命令参数（多个用逗号分隔）';
+COMMENT ON COLUMN mcp_server_config.env_vars IS '环境变量（JSONB 键值对）';
+COMMENT ON COLUMN mcp_server_config.description IS '描述说明';
+COMMENT ON COLUMN mcp_server_config.is_active IS '是否启用';
+COMMENT ON COLUMN mcp_server_config.create_time IS '创建时间';
+COMMENT ON COLUMN mcp_server_config.update_time IS '更新时间';
+COMMENT ON COLUMN mcp_server_config.is_delete IS '逻辑删除: FALSE=正常 TRUE=已删除';
+
-- ============================================================
-- 表 8: vector_store — 向量存储表
-- 注意: Spring AI PgVectorStore 配置了 initializeSchema(true)，
@@ -452,6 +493,7 @@ CREATE TABLE IF NOT EXISTS knowledge_faq (
answer TEXT NOT NULL,
similar_questions TEXT NOT NULL DEFAULT '[]',
category VARCHAR(128),
+ category_id BIGINT,
status VARCHAR(20) NOT NULL DEFAULT 'ENABLED',
priority INTEGER NOT NULL DEFAULT 0,
hit_count BIGINT NOT NULL DEFAULT 0,
@@ -461,9 +503,10 @@ CREATE TABLE IF NOT EXISTS knowledge_faq (
is_delete BOOLEAN NOT NULL DEFAULT FALSE
);
-CREATE INDEX IF NOT EXISTS idx_faq_status ON knowledge_faq (status) WHERE is_delete = FALSE;
-CREATE INDEX IF NOT EXISTS idx_faq_category ON knowledge_faq (category);
-CREATE INDEX IF NOT EXISTS idx_faq_priority ON knowledge_faq (priority DESC);
+CREATE INDEX IF NOT EXISTS idx_faq_status ON knowledge_faq (status) WHERE is_delete = FALSE;
+CREATE INDEX IF NOT EXISTS idx_faq_category ON knowledge_faq (category);
+CREATE INDEX IF NOT EXISTS idx_faq_category_id ON knowledge_faq (category_id);
+CREATE INDEX IF NOT EXISTS idx_faq_priority ON knowledge_faq (priority DESC);
COMMENT ON TABLE knowledge_faq IS 'FAQ 知识库表（用于意图路由后的精准问答匹配）';
COMMENT ON COLUMN knowledge_faq.id IS '主键（雪花算法生成）';
@@ -499,6 +542,29 @@ COMMENT ON COLUMN faq_embedding.embedding IS '向量嵌入（维度由 knowled
COMMENT ON COLUMN faq_embedding.model_name IS '使用的 Embedding 模型名称（用于检测模型变更后重新计算）';
COMMENT ON COLUMN faq_embedding.create_time IS '创建时间';
+-- ============================================================
+-- 清理租户相关数据（移除多租户架构）
+-- ============================================================
+DROP TABLE IF EXISTS tenant CASCADE;
+
+ALTER TABLE api_key DROP COLUMN IF EXISTS tenant_id;
+DROP INDEX IF EXISTS idx_api_key_tenant_id;
+
+ALTER TABLE customer_service_role DROP COLUMN IF EXISTS tenant_id;
+DROP INDEX IF EXISTS idx_csr_tenant_id;
+
+ALTER TABLE knowledge_category DROP COLUMN IF EXISTS tenant_id;
+DROP INDEX IF EXISTS idx_kc_tenant_id;
+
+ALTER TABLE knowledge_faq DROP COLUMN IF EXISTS tenant_id;
+DROP INDEX IF EXISTS idx_faq_tenant_id;
+
+-- ============================================================
+-- API Key 角色绑定：新增 role_ids 列
+-- ============================================================
+ALTER TABLE api_key ADD COLUMN IF NOT EXISTS role_ids JSONB DEFAULT '[]' NOT NULL;
+COMMENT ON COLUMN api_key.role_ids IS '绑定的客服角色 ID 列表（JSONB 数组，空数组=不限制，返回所有启用角色）';
+
-- ============================================================
-- 完成！
-- 共创建 14 张表及对应索引。
diff --git a/src/main/resources/static/components/ApiKeyManager.js b/src/main/resources/static/components/ApiKeyManager.js
index 2bd9842..274d9ab 100644
--- a/src/main/resources/static/components/ApiKeyManager.js
+++ b/src/main/resources/static/components/ApiKeyManager.js
@@ -1,9 +1,9 @@
/**
* API Key 管理组件
- * 支持 API Key 的生成、吊销、启用、删除、复制、分页查询
+ * 支持 API Key 的生成、吊销、启用、删除、复制、分页查询、角色绑定
*/
import { ref, onMounted, computed } from 'vue'
-import { listApiKeys, createApiKey, revokeApiKey, enableApiKey, deleteApiKey } from '../js/api.js'
+import { listApiKeys, createApiKey, revokeApiKey, enableApiKey, deleteApiKey, getAllRoles, updateApiKeyRoles } from '../js/api.js'
import { toast } from '../js/utils.js'
export default {
@@ -25,14 +25,15 @@ export default {
| Key |
频率限制 |
调用次数 |
+ 绑定角色 |
过期时间 |
状态 |
操作 |
- | 加载中... |
- | 暂无 API Key |
+ | 加载中... |
+ | 暂无 API Key |
|
{{ k.name || '未命名' }}
@@ -50,6 +51,10 @@ export default {
/ {{ k.maxCalls }}
（不限）
|
+
+ {{ getBoundRoleCount(k.roleIds) }} 个角色
+ 不限（全部）
+ |
{{ k.expireTime ? formatDate(k.expireTime) : '永不过期' }}
|
@@ -59,6 +64,7 @@ export default {
+
@@ -100,6 +106,16 @@ export default {
+
+
+ 暂无可用角色
+
+
+
+
@@ -121,6 +137,37 @@ export default {
+
+
+
+
+ 绑定客服角色 — {{ editingKeyName }}
+ 勾选允许此 API Key 使用的客服角色，不勾选任何角色则不限制（可使用所有角色）
+
+ 加载角色列表...
+ 暂无可用角色，请先创建客服角色
+ |