基于 DDD 六边形架构的 AI API 聚合网关，支持多渠道调度、安全扫描、知识库 RAG、Wiki 知识图谱、Agent 对话、MCP 工具调用。
作者：小傅哥 bugstack.cn · 仓库地址：waliapi-java
- 项目简介
- 功能总览
- 架构设计
- 技术栈
- 项目结构
- 快速启动
- 配置说明
- Docker 部署
- API 端点
- 知识库 RAG 架构
- Wiki 知识图谱架构
- 安全扫描
- Agent 装配
- 数据库设计
- 学习指南
- 常见问题
WaLiAPI-Java 是一个生产级的 AI API 聚合网关。它将 OpenAI、Anthropic、Gemini、DeepSeek、通义千问、Moonshot、智谱等多种 AI 能力聚合到统一入口，提供渠道管理、密钥管理、安全扫描、知识库 RAG、Wiki 知识图谱、Agent 对话等完整功能。
一句话理解： 你只需要部署一个 WaLiAPI，就能获得一个类似 OpenAI 的 API 服务，但它背后可以连接多家 AI 供应商，并自带安全审计、知识库问答和 Agent 能力。
- 🔀 多渠道路由：10 种渠道类型，优先级 + 加权随机调度，失败自动重试
- 🔒 安全扫描：6 个子扫描器，约 40 条正则规则，支持审计/阻断/脱敏三种模式
- 📚 知识库 RAG：文档上传 → 分块 → 向量化 → 混合检索 → LLM 回答，支持深度研究
- 🗺️ Wiki 知识图谱：LLM 自动生成 Wiki 页面，构建知识图谱（wikilink/tag_share/same_type/reference 四种边类型），图谱增强 RAG 问答
- 🤖 Agent 对话：基于 Google ADK 的 Agent 装配框架（Llm/Loop/Parallel/Sequential 四种构建器）
- 📊 仪表盘：请求统计、健康评分、日志查询
- 🔧 MCP 工具：标准 MCP 协议工具列表与调用
- DDD 六边形架构的完整工程实践
- 多模块 Maven 项目的组织方式
- Spring Boot 3 + MyBatis 的企业级开发
- AI 网关的设计与实现
- RAG 检索增强生成的工程落地
- 知识图谱的构建与应用
┌──────────────────────────────────────────────────────────────────────┐
│ WaLiAPI-Java 功能全景 │
├──────────────────┬───────────────────────────────────────────────────┤
│ 网关代理 │ OpenAI / Anthropic / Responses 多协议转发 │
│ │ 流式 SSE 支持 · 失败自动重试 │
├──────────────────┼───────────────────────────────────────────────────┤
│ 渠道调度 │ 10 种渠道 · 优先级+加权随机 · 模型名映射 │
├──────────────────┼───────────────────────────────────────────────────┤
│ API Key 管理 │ 多租户密钥 · 模型/渠道白名单 · 额度控制 │
├──────────────────┼───────────────────────────────────────────────────┤
│ 安全扫描 │ 凭证/路径/Unicode/网络/工具/追踪 · 三种处置模式 │
├──────────────────┼───────────────────────────────────────────────────┤
│ 知识库 RAG │ 文档上传→分块→嵌入→HNSW索引→混合检索→LLM回答 │
│ │ vector / keyword / hybrid 三种检索模式 │
│ │ 多轮深度研究（自动追问） │
├──────────────────┼───────────────────────────────────────────────────┤
│ Wiki 知识图谱 │ LLM 自动生成 Wiki 页面 · 四种图谱边类型 │
│ │ 图谱增强 RAG · 社区检测 · 惊喜连接发现 │
│ │ FTS5 全文搜索(ngram) · 向量语义搜索 · RRF 融合 │
├──────────────────┼───────────────────────────────────────────────────┤
│ Agent 装配 │ Google ADK · Llm/Loop/Parallel/Sequential 四种 │
│ │ 递归嵌套构建 · ConcurrentHashMap 缓存 │
├──────────────────┼───────────────────────────────────────────────────┤
│ 仪表盘 │ 请求统计 · 健康评分(100分制) · 日志查询 │
├──────────────────┼───────────────────────────────────────────────────┤
│ MCP 工具 │ 标准 MCP 协议 · 工具列表与调用 │
└──────────────────┴───────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ Trigger Layer（触发层） │
│ GatewayController · ChannelController · KbController │
│ WikiController · AgentController · SecurityController │
│ McpController · DashboardController · ApiKeyController │
└──────────────┬──────────────────────┬─────────────────────┘
│ │
┌────────────────────▼──────────────────────▼────────────────────┐
│ Case Layer（应用用例层） │
│ ProxyServiceCase · ChannelServiceCase · KbServiceCase │
│ WikiServiceCase · AgentServiceCase · SecurityServiceCase │
│ DashboardServiceCase · McpServiceCase │
└────────────────────┬───────────────────────────────────────────┘
│
┌────────────────────▼───────────────────────────────────────────┐
│ Domain Layer（领域层 — 技术中立） │
│ │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Gateway │ │ Channel │ │ Security │ │ Knowledge (RAG) │ │
│ │ Service │ │Dispatch │ │ Scanner │ │ Splitter/Embed/ │ │
│ │ │ │ │ │ │ │ Retrieve/RAG │ │
│ └─────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Agent │ │ Stats │ │ Protocol │ │ Importer/Index │ │
│ │Armory │ │ Service │ │ Detector │ │ Strategy/HNSW │ │
│ └─────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Wiki (知识图谱) │ │
│ │ IngestService / SearchService / GraphService / RagService│ │
│ └──────────────────────────────────────────────────────────┘ │
└────────────────────┬───────────────────────────────────────────┘
│
┌────────────────────▼───────────────────────────────────────────┐
│ Infrastructure Layer（基础设施层） │
│ DAO (MyBatis) · PO 持久化对象 · Repository 实现 │
│ HTTP Adaptor (OkHttp) · HikariCP 连接池 │
└───────────────────────────────────────────────────────────────┘
| 原则 | 说明 |
|---|---|
| 领域层不依赖框架 | Domain 层无 Spring 注解，由 App 层 DomainConfiguration 手动装配 Bean |
| 依赖倒置 | Domain 定义接口（port），Infrastructure 实现接口（adapter） |
| 每个模块独立 | 7 个 Maven 模块，各司其职，编译隔离 |
| 值对象不可变 | VO 用 Lombok @Data + @Builder，实体用 Entity 后缀 |
trigger → case → domain ← infrastructure
↑ ↑
api types
关键：domain 层不依赖任何其他模块，case 层依赖 domain，infrastructure 实现domain 定义的接口。这样领域逻辑可以被替换不同的基础设施实现。
| 技术 | 版本 | 用途 |
|---|---|---|
| Spring Boot | 3.4.3 | Web 框架、依赖注入、自动配置 |
| MyBatis | 3.0.4 (starter) | ORM 框架，XML Mapper |
| MySQL | 8.0+ | 数据库（全文索引 + ngram 分词） |
| HikariCP | — | 数据库连接池 |
| OkHttp | 4.12.0 | HTTP 客户端（渠道适配器，SSE 流式） |
| Fastjson | 2.0.28 | JSON 序列化 |
| Google ADK | 0.5.0 | Agent Development Kit |
| Guava | 32.1.3 | 缓存 |
| Lombok | 1.18.36 | 简化样板代码 |
| Docker | — | 容器化部署 |
环境要求：
- JDK 17+
- Maven 3.8+
- MySQL 8.0+（需要 ngram 全文索引支持）
WaLiAPI-Java/
├── waliapi-types/ # 基础类型：ResponseCode 枚举、Constants、AppException
├── waliapi-api/ # API 接口层：DTO 数据传输对象（32+ 个 DTO）
├── waliapi-domain/ # 领域层：核心业务逻辑（269 个 Java 文件）
│ ├── agent/ # Agent 域：装配框架 + 对话服务
│ ├── channel/ # 渠道域：调度器、渠道/密钥实体
│ ├── gateway/ # 网关域：代理服务（同步/流式转发）
│ ├── knowledge/ # 知识库域：分块/嵌入/检索/RAG/导入策略/HNSW索引
│ ├── wiki/ # Wiki 域：摄入/搜索/图谱/RAG（知识图谱增强）
│ ├── security/ # 安全域：6 个子扫描器 + 安全设置
│ ├── protocol/ # 协议域：检测器 + Anthropic/Responses 转换器
│ ├── stats/ # 统计域：健康评分
│ └── log/ # 日志域：请求日志记录
├── waliapi-infrastructure/ # 基础设施层：DAO + PO + Repository 实现
├── waliapi-case/ # 应用用例层：编排领域服务，DTO ↔ Entity 转换
├── waliapi-trigger/ # 触发层：HTTP Controller + Filter
│ ├── http/gateway/ # 网关代理端点
│ ├── http/admin/ # 管理后台 Controller
│ ├── http/wiki/ # Wiki Controller
│ ├── http/mcp/ # MCP Controller
│ └── filter/ # API Key 认证过滤器
├── waliapi-app/ # 启动模块：Spring Boot 入口 + 配置
│ ├── src/main/java/.../config/
│ │ ├── Application.java # @SpringBootApplication 入口
│ │ ├── DomainConfiguration.java # 领域 Bean 手动装配（重点！）
│ │ ├── ThreadPoolConfig.java # 线程池
│ │ ├── SecurityConfig.java # 安全配置
│ │ ├── CorsConfig.java # 跨域
│ │ └── WaLiApiConfig.java # 业务配置
│ ├── src/main/resources/
│ │ ├── application.yml # 主配置（默认 profile: test）
│ │ ├── application-dev.yml # 开发环境
│ │ ├── application-test.yml # 测试环境
│ │ ├── application-prod.yml # 生产环境
│ │ └── logback-spring.xml # 日志配置
│ └── Dockerfile # Docker 镜像构建文件
├── docs/dev-ops/ # 运维文档
│ ├── docker-compose-environment.yml # 基础设施（MySQL/Redis/phpMyAdmin）
│ ├── docker-compose-environment-aliyun.yml # 国内镜像版
│ ├── docker-compose-app.yml # 应用容器
│ ├── app/start.sh & stop.sh # 启停脚本
│ └── mysql/sql/
│ ├── waliapi.sql # 完整建表 SQL（22 张表）
│ ├── waliapi_2026-08-08.sql # 增量升级 SQL
│ └── wiki_upgrade_v2.sql # Wiki V2 升级 SQL（FTS + embedding）
├── data/ # 运行时数据（HNSW 索引文件等）
└── pom.xml # Maven 父 POM
代码规模：269 个 Java 文件，7 个 Maven 模块
- JDK 17+
- Maven 3.8+
- MySQL 8.0+（或使用 Docker 一键启动）
- 至少一个 AI 渠道的 API Key（如 OpenAI / DeepSeek 等）
git clone https://github.com/fuzhengwei/WaLiAPI-Java.git
cd WaLiAPI-Java方式 A：使用 Docker Compose（推荐，国内镜像）
cd docs/dev-ops
docker-compose -f docker-compose-environment-aliyun.yml up -d启动后会运行以下服务：
| 服务 | 端口 | 用途 |
|---|---|---|
| MySQL 8.0.32 | 13306 | 数据库 |
| Redis 6.2 | 16379 | 缓存 |
| phpMyAdmin | 8899 | 数据库可视化管理 |
数据库会自动执行
docs/dev-ops/mysql/sql/下的 SQL 文件完成建表。
方式 B：使用已有 MySQL
# 手动导入建表 SQL
mysql -u root -p < docs/dev-ops/mysql/sql/waliapi.sql编辑 waliapi-app/src/main/resources/application-dev.yml，修改数据库连接信息：
spring:
datasource:
url: jdbc:mysql://localhost:13306/waliapi?useUnicode=true&characterEncoding=utf8&autoReconnect=true&zeroDateTimeBehavior=convertToNull&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
username: root
password: 123456 # 改为你的 MySQL 密码# 编译整个项目（跳过测试）
mvn clean install -DskipTests
# 方式 A：Maven 启动（开发模式）
cd waliapi-app
mvn spring-boot:run
# 方式 B：JAR 包启动
java -jar waliapi-app/target/waliapi-app.jar
# 方式 C：指定 Profile 启动
java -jar waliapi-app/target/waliapi-app.jar --spring.profiles.active=dev# 健康检查
curl http://localhost:8899/health
# 返回：{"status":"ok","service":"WaLiAPI-Java","version":"1.0.0"}
# 查看模型列表
curl http://localhost:8899/v1/models服务启动后，需要通过管理后台 API 添加至少一个 AI 渠道：
# 添加 OpenAI 渠道示例
curl -X POST http://localhost:8899/api/v1/channels \
-H "Content-Type: application/json" \
-d '{
"id": "ch-openai-01",
"name": "OpenAI 官方",
"type": "openai",
"base_url": "https://api.openai.com",
"api_key": "sk-你的API-Key",
"models": ["gpt-4o", "gpt-4.1", "text-embedding-3-small"],
"status": 1,
"priority": 10,
"weight": 1
}'
# 添加 API Key（用于客户端调用网关时认证）
curl -X POST http://localhost:8899/api/v1/api-keys \
-H "Content-Type: application/json" \
-d '{
"id": "key-001",
"name": "测试密钥",
"key": "sk-waliapi-test001",
"status": 1
}'# 使用 OpenAI 兼容协议调用（带上你创建的 API Key）
curl -X POST http://localhost:8899/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-waliapi-test001" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "你好，请做个自我介绍"}]
}'
# 流式调用
curl -X POST http://localhost:8899/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-waliapi-test001" \
-d '{
"model": "gpt-4o",
"stream": true,
"messages": [{"role": "user", "content": "写一首关于编程的诗"}]
}'| Profile | 端口 | 适用场景 |
|---|---|---|
dev |
8899 | 本地开发 |
test |
8899 | 测试环境 |
prod |
8091 | 生产环境 |
切换方式：修改 application.yml 中的 spring.profiles.active 或启动时加 --spring.profiles.active=dev。
server:
port: 8899 # 服务端口
spring:
datasource: # 数据库
url: jdbc:mysql://192.168.1.108:13306/waliapi?useUnicode=true&characterEncoding=utf8&autoReconnect=true&zeroDateTimeBehavior=convertToNull&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
username: root
password: 123456
hikari:
minimum-idle: 15
maximum-pool-size: 25
mybatis: # ORM
mapper-locations: classpath:/mybatis/mapper/*.xml
config-location: classpath:/mybatis/config/mybatis-config.xml
waliapi: # 业务配置
gateway:
retry-times: 2 # 网关重试次数（渠道失败后切换重试）
security:
enabled: true # 是否启用安全扫描
mode: audit # audit(仅记录) / block(阻断) / redact(脱敏)
scan-unicode: true # Unicode 异常字符扫描
scan-tools: true # 工具调用注入扫描
scan-network: true # 网络地址信息扫描
scan-response: false # 是否扫描响应内容
redact-secrets: true # 是否脱敏敏感信息
block-on-critical: true # Critical 级别是否直接阻断
thread: # 线程池
pool:
executor:
config:
core-pool-size: 20
max-pool-size: 50
keep-alive-time: 5000
block-queue-size: 5000
policy: CallerRunsPolicy
logging:
level:
root: info| 模式 | 行为 |
|---|---|
audit |
扫描并记录安全发现，不阻断请求（推荐开发阶段使用） |
block |
检测到 Critical 级别问题时直接阻断请求 |
redact |
将检测到的敏感信息（API Key、密码等）替换为 *** 后再转发 |
cd docs/dev-ops
# 国内镜像（推荐）
docker-compose -f docker-compose-environment-aliyun.yml up -d
# 官方镜像
docker-compose -f docker-compose-environment.yml up -d包含服务：MySQL 8.0.32（端口 13306）、Redis 6.2（端口 16379）、phpMyAdmin（端口 8899）、Redis Commander（端口 8081，账密 admin/admin）
# 编译打包
mvn clean package -DskipTests
# 构建镜像
cd waliapi-app
docker build -t system/waliapi-app:1.0.0-SNAPSHOT .# 方式 A：使用 docker-compose
docker-compose -f docs/dev-ops/docker-compose-app.yml up -d
# 方式 B：使用脚本
cd docs/dev-ops/app
bash start.sh
# 方式 C：手动 docker run
docker run -d --name WaLiAPI-Java \
-p 8091:8091 \
-e TZ=PRC \
-e SERVER_PORT=8091 \
system/waliapi-app:1.0.0-SNAPSHOTdocker pull registry.cn-hangzhou.aliyuncs.com/xfg-studio/waliapi-app:1.0.0-SNAPSHOT| 地址 | 说明 |
|---|---|
http://localhost:8899 |
开发模式服务端口 |
http://localhost:8091 |
Docker 容器端口 |
http://localhost:8899 (phpMyAdmin) |
数据库管理（如果用 Docker Compose 启动基础设施） |
http://localhost:8081 |
Redis Commander（账密 admin/admin） |
⚠️ 端口冲突注意：phpMyAdmin 默认也用 8899 端口，如果同时启动基础设施和应用，请修改其中一个的端口映射。
通过 Authorization: Bearer <你的API Key> 认证。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /v1/chat/completions |
OpenAI 聊天（支持 SSE 流式） |
| POST | /v1/completions |
文本补全 |
| POST | /v1/responses |
OpenAI Responses API |
| POST | /v1/messages |
Anthropic Messages API |
| POST | /v1/embeddings |
文本嵌入 |
| POST | /v1/images/generations |
图片生成 |
| POST | /v1/audio/transcriptions |
语音转文字 |
| POST | /v1/audio/speech |
文字转语音 |
| GET | /v1/models |
模型列表 |
| GET | /health |
健康检查 |
| 方法 | 路径前缀 | 说明 |
|---|---|---|
| CRUD | /api/v1/channels |
渠道管理 |
| CRUD | /api/v1/api-keys |
API Key 管理 |
| GET | /api/v1/dashboard |
仪表盘统计 |
| GET/DELETE | /api/v1/logs |
请求日志 |
| 方法 | 路径 | 说明 |
|---|---|---|
| CRUD | /api/v1/kb |
知识库管理 |
| POST | /api/v1/kb/{id}/ask |
RAG 问答 |
| POST | /api/v1/kb/{id}/deep-research |
深度研究（多轮追问） |
| POST | /api/v1/kb/{id}/search |
知识库搜索 |
| GET | /api/v1/kb/{id}/stats |
知识库统计 |
| POST | /api/v1/kb/{id}/documents/{docId}/reindex |
文档重索引 |
| CRUD | /api/v1/kb/{id}/index |
索引管理 |
| CRUD | /api/v1/kb/{id}/sources |
来源管理 |
| 方法 | 路径 | 说明 |
|---|---|---|
| CRUD | /api/v1/wiki/projects |
项目管理 |
| GET/PUT/DELETE | /api/v1/wiki/projects/{projectId}/pages/{path} |
页面管理 |
| CRUD | /api/v1/wiki/projects/{projectId}/sources |
来源管理 |
| POST | /api/v1/wiki/projects/{projectId}/sources/{sourceId}/ingest |
触发摄入 |
| POST | /api/v1/wiki/projects/{projectId}/sources/rescan |
重新扫描所有来源 |
| POST | /api/v1/wiki/projects/{projectId}/upload |
上传文件 |
| GET | /api/v1/wiki/projects/{projectId}/tasks |
任务列表 |
| GET | /api/v1/wiki/projects/{projectId}/queue-status |
队列状态 |
| GET | /api/v1/wiki/projects/{projectId}/search?q=xxx&mode=hybrid |
搜索（keyword/vector/hybrid） |
| POST | /api/v1/wiki/projects/{projectId}/ask |
Wiki RAG 问答 |
| GET | /api/v1/wiki/projects/{projectId}/graph |
获取知识图谱 |
| GET | /api/v1/wiki/projects/{projectId}/graph/subgraph?center=xxx&depth=2 |
子图查询 |
| GET | /api/v1/wiki/projects/{projectId}/graph/stats |
图谱统计 |
| POST | /api/v1/wiki/projects/{projectId}/graph/rebuild |
重建图谱 |
| GET | /api/v1/wiki/projects/{projectId}/graph/insights |
图谱洞察 |
| GET | /api/v1/wiki/projects/{projectId}/tags |
标签列表 |
| GET/DELETE | /api/v1/wiki/projects/{projectId}/conversations |
对话历史 |
| 方法 | 路径 | 说明 |
|---|---|---|
| CRUD | /api/v1/agents |
Agent 配置管理 |
| GET/PUT | /api/v1/security/rules/* |
安全规则管理 |
| GET | /api/v1/security/findings |
安全发现查询 |
| GET/POST | /api/mcp/* |
MCP 工具 |
知识库 RAG（Retrieval-Augmented Generation）是 WaLiAPI 的核心功能之一，实现了从文档上传到智能问答的完整链路。
┌─────────────────────────────────────────┐
│ 文档摄入流水线 │
└─────────────────────────────────────────┘
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐
│ 文档上传 │ → │ Document │ → │ TextSplitter│ → │ Embedder │ → │ 存储 │
│ /Git/URL │ │ Parser │ │ 分块 │ │ 向量化 │ │ kb_chunks│
└──────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘
│ │
chunk_size=512 │
overlap=50 │
Markdown标题分块 │
│ │ │
▼ │ │
┌──────────────┐ │ │
│ HNSW 索引 │ ← data/index/ │ │
│ 构建与持久化 │ (磁盘文件) │ │
└──────────────┘ │ │
│ │
┌─────────────────────────────────────────┐ │ │
│ 问答检索流水线 │◄──────────┘ │
└─────────────────────────────────────────┘ │
│
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐
│ 用户提问 │ → │ Embedder │ → │ Retriever │ → │ RagContext │ → │ LLM │
│ │ │ 查询向量化 │ │ 检索 top-K │ │ Builder │ │ 生成回答 │
└──────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘
│
┌─────┴─────┐
│ 三种模式 │
├───────────┤
│ vector │ 向量语义搜索（HNSW + 余弦相似度）
│ keyword │ 全文搜索（支持 CJK 中文分词）
│ hybrid │ 混合搜索（0.7*vector + 0.3*keyword）
└───────────┘
| 参数 | 值 | 说明 |
|---|---|---|
| chunk_size | 512 字符 | 每个分块的最大长度 |
| overlap | 50 字符 | 分块间的重叠区域，保证上下文连贯 |
| 分块方式 | Markdown 标题 + 自然边界 | 优先按 #、## 标题分块，其次按段落分块 |
| 模式 | 实现 | 适用场景 |
|---|---|---|
vector |
HNSW 索引 + 余弦相似度 | 语义相近搜索（"怎么部署" → 匹配 "安装步骤"） |
keyword |
MySQL FULLTEXT + LIKE 回退 | 精确关键词匹配（搜索特定函数名、配置项） |
hybrid |
0.7 × vector + 0.3 × keyword | 综合语义和关键词（推荐，默认模式） |
回退机制：vector/hybrid 搜索失败时自动回退到 keyword 搜索，保证可用性。
| 参数 | 值 | 说明 |
|---|---|---|
| maxM | 16 | 每个节点的最大邻居数 |
| efConstruction | 200 | 构建时的搜索宽度 |
| efSearch | 50 | 查询时的搜索宽度 |
| 距离度量 | 余弦距离 | 适合文本语义相似度 |
| 持久化 | data/index/ |
磁盘文件，重启后自动加载 |
| 策略 | 说明 |
|---|---|
GitImportStrategy |
从 Git 仓库克隆并导入文档 |
UrlImportStrategy |
从 URL 抓取网页内容 |
LocalDirImportStrategy |
遍历本地目录文件（FileWalker） |
多轮追问机制（默认 3 轮）：
- 第 1 轮：用户提问 → RAG 检索 → LLM 回答
- 第 2 轮：基于第 1 轮回答，自动生成后续问题 → 再次检索 → 补充回答
- 第 3 轮：综合前两轮，生成最终深度回答
Wiki 是知识库的进阶功能，通过 LLM 自动将原始文档转换为结构化的 Wiki 页面，并构建知识图谱增强 RAG 问答。
┌──────────────────────────────────────────────────────────────────────────┐
│ Wiki 知识图谱平台 │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ 来源管理 │ │ 摄入流水线 │ │ 搜索服务 │ │ RAG 问答 │ │
│ │ │ │ │ │ │ │ │ │
│ │ • 文件上传 │→ │ LLM 生成 │→ │ • 关键词(FTS) │→ │ 图谱增强 │ │
│ │ • URL │ │ Wiki 页面 │ │ • 向量语义 │ │ 上下文构建 │ │
│ │ • 文本输入 │ │ • Frontmatter │ │ • 混合(RRF) │ │ LLM 回答 │ │
│ │ │ │ • Wikilinks │ │ │ │ │ │
│ └─────────────┘ └──────┬───────┘ └──────────────┘ └───────────┘ │
│ │ │
│ ┌──────▼───────┐ │
│ │ 图谱服务 │ │
│ │ │ │
│ │ 四种边类型： │ │
│ │ • wikilink │ 权重 1.0 │
│ │ • tag_share │ 权重 0.8 │
│ │ • same_type │ 权重 0.3 │
│ │ • reference │ 权重 0.5 │
│ │ │ │
│ │ 社区检测 │ │
│ │ 图谱洞察 │ │
│ └──────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
源内容 → 构建 LLM Prompt → 调用 LLM 生成 Wiki 页面 → 解析 Frontmatter/Wikilinks
→ 写入 wiki_pages → 重建图谱边 → 预计算 Embedding → 完成
LLM 生成格式：
---
title: 页面标题
path: folder/page-name
tags: [标签1, 标签2]
---
页面 Markdown 内容，使用 [[页面名称]] 创建内部链接。
---PAGE--- （多个页面之间的分隔符）
---
title: 下一个页面
...
三层搜索策略，与知识库 RAG 类似但针对 Wiki 页面优化：
| 模式 | 实现 | 特点 |
|---|---|---|
keyword |
MySQL FULLTEXT (ngram 分词) + LIKE 回退 | 支持 CJK 二元组分词，标题/路径/内容/标签加权评分 |
vector |
页面 Embedding + 余弦相似度 | 优先使用预计算 Embedding，未就绪时回退实时计算（限制 50 页面） |
hybrid |
RRF (Reciprocal Rank Fusion, k=60) 融合 | 关键词 + 向量结果融合排序 |
FTS5 中文支持： 使用 MySQL ngram 分词器，将 CJK 字符拆分为二元组（如 "知识图谱" → "知识" + "识图" + "图谱"），支持中文全文搜索。
四种边类型：
| 边类型 | 权重 | 构建逻辑 |
|---|---|---|
wikilink |
1.0 | 页面内容中的 [[页面名]] 链接 |
tag_share |
0.8 | 两个页面有相同标签则建边 |
same_type |
0.3 | 相同 page_type（index/reference/guide/note）的页面互连（≤50个） |
reference |
0.5 | 页面内容中提到另一个页面标题（排除已有 wikilink） |
图谱能力：
| 功能 | 说明 |
|---|---|
| 全图构建 | buildGraph(projectId) — 返回所有节点和边 |
| 子图查询 | buildSubGraph(projectId, centerPath, depth) — BFS N-hop 邻居 |
| 图谱统计 | 节点数、边数、边类型分布、连通分量、平均度数、图密度、孤立节点 |
| 社区检测 | Union-Find 连通分量算法，为节点分配社区 ID |
| 图谱洞察 | 惊喜连接（跨类型连接）、知识空白（缺失页面）、Hub 页面（度数最高） |
| 图谱重建 | 删除所有边 → 重新构建四种边 → 同步 FTS 表 |
| 增量更新 | 单页面 wikilink 变更时，只更新该页面的边 |
Wiki RAG 与知识库 RAG 的关键区别：图谱增强上下文
用户提问
│
▼
┌──────────────┐
│ 搜索相关页面 │ hybrid 模式（RRF 融合关键词+向量）
└──────┬───────┘
│
▼
┌──────────────────────┐
│ 图谱扩展（1-hop 邻居）│ 沿图谱边找到相关邻居页面（默认最多 2 个）
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ Chunk 级上下文构建 │ 从完整页面中提取与问题最相关的 1200 字符 chunk
│ │ 最大上下文总长 8000 字符
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ LLM 回答 │ 中文 System Prompt，支持历史对话（最近 6 轮）
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ 保存对话记录 │ 持久化到 wiki_sessions 表
└──────────────────────┘
Chunk 提取算法：
- 将页面内容按 1200 字符分块（overlap 200）
- 计算每个 chunk 与问题的相关性评分（关键词重叠 + 中文二元组匹配）
- 选取评分最高的 chunk 作为上下文
- 截断到 800 字符上限
请求进入 → SecurityScanner 主扫描器
├── CredentialScanner (凭证扫描)
├── PathScanner (路径扫描)
├── UnicodeScanner (Unicode扫描)
├── NetworkScanner (网络扫描)
├── ToolRiskScanner (工具风险扫描)
└── TrackingScanner (追踪扫描)
│
▼
汇总结果 → 风险等级评定 → 处置动作
| 扫描器 | 检测内容 | 示例 |
|---|---|---|
CredentialScanner |
API Key、Token、密码、私钥 | sk-xxxx, AKIAxxxx, password=xxx |
PathScanner |
文件路径、目录遍历 | /etc/passwd, ../../ |
UnicodeScanner |
零宽字符、RTL 覆写、异常 Unicode | 零宽空格 \u200B, RTL 覆写 \u202E |
NetworkScanner |
IP 地址、URL、域名 | 192.168.1.1, https://xxx.com |
ToolRiskScanner |
工具调用注入 | 伪造的 function call 参数 |
TrackingScanner |
追踪参数、指纹 Cookie | utm_source, __cf_bm |
| 等级 | 分值 | 处置 |
|---|---|---|
| Clean | 0 | 正常放行 |
| Low | 1-30 | 记录（audit 模式）/ 标记（其他模式） |
| Medium | 31-60 | 记录 + 告警 |
| High | 61-90 | 记录 + 告警 |
| Critical | 91-100 | block-on-critical=true 时阻断请求 |
基于 Google ADK（Agent Development Kit）的 Agent 构建框架。
| 构建器 | 类型 | 说明 | 应用场景 |
|---|---|---|---|
LlmAgentBuilder |
llm | 单轮 LLM 对话 | 知识问答、文本生成 |
LoopAgentBuilder |
loop | 循环执行（可配 maxIterations） | 迭代优化、多轮搜索 |
ParallelAgentBuilder |
parallel | 并行执行多个子 Agent | 同时分析多个维度 |
SequentialAgentBuilder |
sequential | 顺序执行多个子 Agent | 流水线处理（分析→生成→审查） |
AgentConfigDTO → AgentServiceCase → AgentArmoryService
│
├── 选择 IAgentBuilder（根据 type 字段）
├── AgentBuildDelegate 递归构建嵌套 Agent
├── 注册到 ConcurrentHashMap（缓存）
└── 返回 Agent 实例
AgentBuildDelegate 支持递归构建嵌套 Agent：一个 Sequential Agent 的子 Agent 可以是 Loop Agent，Loop Agent 的子 Agent 又可以是 Llm Agent。
共 22 张表，分为 6 大类：
| 表名 | 用途 |
|---|---|
channels |
渠道配置（10 种类型，优先级+权重调度） |
api_keys |
API Key 管理（模型/渠道白名单、额度控制） |
request_logs |
请求日志（Token 用量、耗时、风险等级、响应内容） |
| 表名 | 用途 |
|---|---|
security_findings |
安全发现记录（关联请求日志） |
security_builtin_rules |
内置安全规则（约 40 条正则规则） |
security_custom_rules |
自定义安全规则 |
| 表名 | 用途 |
|---|---|
agent_configs |
Agent 配置（类型、模型、System Prompt、工具、嵌套配置 JSON） |
| 表名 | 用途 |
|---|---|
kb_knowledge_bases |
知识库 |
kb_documents |
知识库文档 |
kb_chunks |
文档分块（含向量数据） |
kb_tasks |
导入任务 |
kb_conversations |
对话记录 |
kb_sources |
文档来源 |
kb_index_meta |
HNSW 索引元数据 |
| 表名 | 用途 |
|---|---|
wiki_projects |
Wiki 项目（关联摄入/对话渠道） |
wiki_pages |
Wiki 页面（含 Frontmatter、Wikilinks、Embedding） |
wiki_sources |
来源管理（file/url/text） |
wiki_tasks |
摄入任务（进度跟踪） |
wiki_graph_edges |
图谱边（四种边类型） |
wiki_sessions |
对话历史 |
wiki_pages_fts |
全文搜索表（ngram 分词 + FULLTEXT 索引） |
wiki_graph_clusters |
图谱社区表 |
| 文件 | 说明 |
|---|---|
docs/dev-ops/mysql/sql/waliapi.sql |
完整建表 SQL（含 ALTER 升级语句） |
docs/dev-ops/mysql/sql/waliapi_2026-08-08.sql |
增量升级 SQL（最新） |
docs/dev-ops/mysql/sql/wiki_upgrade_v2.sql |
Wiki V2 升级（FTS 表 + Embedding 字段 + 社区表） |
新部署：执行
waliapi.sql+wiki_upgrade_v2.sql即可。 已有库升级：执行waliapi_2026-08-08.sql。
Application.java— Spring Boot 启动入口DomainConfiguration.java— DDD 核心：领域 Bean 手动装配，理解"领域层不依赖框架"application-dev.yml— 配置项全貌
GatewayController → ProxyServiceCase → ProtocolDetector（协议检测）
→ SecurityScanner（安全扫描）→ Dispatcher（渠道调度）
→ ProxyService（转发）→ LogService（日志记录）
KbController → KbServiceCase
→ TextSplitter（分块）→ EmbedderService（向量化）
→ IndexService（HNSW 索引）→ RetrieverService（检索）
→ RagService → RagContextBuilder（上下文构建）→ LLM 回答
WikiController → WikiServiceCase
→ WikiIngestService（LLM 生成 Wiki 页面）→ WikiGraphService（图谱构建）
→ WikiSearchService（三层搜索）→ WikiRagService（图谱增强 RAG）
SecurityController → SecurityServiceCase
→ SecurityScanner → 6 个子扫描器
AgentController → AgentServiceCase
→ AgentArmoryService → IAgentBuilder（4 种构建器）
→ AgentBuildDelegate（递归嵌套）→ AgentChatService
ChannelController → ChannelServiceCase
→ Dispatcher（优先级 + 加权随机）→ IChannelAdaptor（10 种渠道适配器）
| 模式 | 使用场景 | 代码位置 |
|---|---|---|
| 策略模式 | 搜索策略（Vector/Keyword/Hybrid）、导入策略（Git/Url/LocalDir） | SearchStrategyFactory, ImportContext |
| 工厂模式 | Agent 构建器注册表 | AgentArmoryService.builderMap |
| 建造者模式 | Agent 构建（Llm/Loop/Parallel/Sequential） | IAgentBuilder 实现类 |
| 适配器模式 | 渠道 HTTP 适配器（10 种渠道） | IChannelAdaptor 实现 |
| 依赖倒置 | Domain 定义 port 接口，Infrastructure 实现 | IKbRepository, IChannelRepository 等 |
| 模板方法 | 安全扫描流程 | SecurityScanner → ISubScanner |
- 检查 MySQL 是否启动：
docker ps | grep mysql - 检查端口和密码是否与
application-dev.yml一致 - 如果用 Docker Compose 启动，MySQL 端口映射为
13306
Docker Compose 中 phpMyAdmin 默认映射 8899 端口，与应用端口相同。解决方案：
- 修改
docker-compose-environment-aliyun.yml中 phpMyAdmin 的端口映射（如改为8898:80） - 或修改应用的
application-dev.yml中server.port
网关代理端点需要 API Key 认证。请先通过管理后台创建 API Key：
curl -X POST http://localhost:8899/api/v1/api-keys \
-H "Content-Type: application/json" \
-d '{"id":"key-001","name":"test","key":"sk-your-key","status":1}'然后请求时带上 Authorization: Bearer sk-your-key。
- 确保使用了
hybrid模式（默认） - 检查文档是否已正确分块和向量化
- 调整
topK参数（默认 5，可增大到 10） - 如果中文搜索效果差，确认 MySQL 使用 ngram 分词器
- 检查 Wiki 项目是否配置了
ingest_channel_id（摄入渠道） - 确保该渠道的模型支持长文本输入（推荐 gpt-4.1）
- 查看
wiki_tasks表的error_message字段 - 检查 LLM 返回格式是否正确（
---PAGE---分隔符）
索引文件存储在项目根目录的 data/index/ 下，重启服务时会自动加载。如果索引损坏，删除该目录后重新导入文档即可重建。
- 在
ChannelTypeVO中添加新的类型枚举 - 实现
IChannelAdaptor接口 - 在 Infrastructure 层注册新的适配器 Bean
- 在
DomainConfiguration中添加@Bean定义
修改 application.yml 中的 spring.profiles.active：
dev— 连接 192.168.1.108:13306（开发服务器）test— 连接 127.0.0.1:3306（本地 MySQL）prod— 生产环境配置（需自行配置）
Apache License 2.0