# ai-memo-assistant

**Repository Path**: hippoDocker/ai-memo-assistant

## Basic Information

- **Project Name**: ai-memo-assistant
- **Description**: AI应用助手 
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI

## README

# 火锅凉虾

面向开发场景的知识问答与平台管理项目，包含 Spring Boot 后端、Next.js 前端、MCP 工具服务、应用中心、知识库、葵花宝典学习内容和后台治理能力。

## 快速概览

- 首页统一入口：`/`
- 应用中心：`/workspace`
- 知识库工作台：`/workspace/knowledge`
- 葵花宝典：`/workspace/apps/kuihua`
- 后台管理：`/admin`
- 工具市场：`/market`
- AI 智能体：`Huoguo Agent`

设计系统：**Luminous v2.0** — 午夜青蓝主色 `#0F6B7A`，珊瑚红强调 `#FF4757`，详见 [UI 重设计方案](./docs/ui-redesign/README.md)

当前主线能力：

- 游客登录、普通用户登录
- Spring AI Alibaba ReactAgent + OpenAI 兼容模型配置
- 聊天模型与 Embedding 模型分离配置
- `CHAT` 与 `EMBEDDING` 模型都支持设置各自的默认模型
- 模型供应商、模型名称能力目录与 `/models` 拉取
- 模型目录管理：管理平台支持的 AI 模型及其能力配置，支持手动添加、编辑、删除模型目录条目，支持按模型类型、能力标签筛选，支持按模型代码搜索
- AI 工具系统：工具市场、工具分组、工具权限管理、MCP 外部工具接入
- 一句话创建工具：在工具市场通过自然语言描述创建工具，支持多轮对话调整
- 聊天工具调用：工具调用录制、SSE 实时流式推送、可折叠调用详情面板
- **联网搜索**：集成 SearXNG 自建搜索引擎，支持百度、360、搜狗等国内引擎
- 应用中心：应用 CRUD、图标上传（MinIO 对象存储）、上下架管理
- 知识库管理、文档解析、向量检索
- 葵花宝典内容管理与学习路线展示
- 用户、组织、角色、权限、菜单、资源管理
- 平台公告与安全审计
- 全量文件上传统一使用 MinIO 对象存储

知识库入口约定：

- 用户侧 `知识库`（`/workspace/knowledge`）只展示当前用户自己的知识库列表
- 点击知识库标题进入详情页（`/workspace/knowledge/{id}`）进行上传文档、解析文档、编辑解析结果、重解析
- 后台 `知识库配置`（`/admin`）展示全局知识库管理列表，文档明细通过详情弹窗查看

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         用户浏览器                                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Nginx 网关 (端口 80)                           │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────────┐   ┌─────────────────────────────┐
│   ai-memo-server (业务服务)   │   │  ai-memo-mcp-server (工具服务) │
│        端口: 8080            │   │        端口: 8081            │
│  - 用户管理                  │   │  - MCP 协议服务               │
│  - 聊天服务                  │   │  - 联网搜索工具               │
│  - 知识库服务                │   │  - 时间工具                   │
└─────────────────────────────┘   └─────────────────────────────┘
              │                               │
              └───────────────┬───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    PostgreSQL | Redis | MinIO | SearXNG          │
└─────────────────────────────────────────────────────────────────┘
```

## 快速开始

### 本地启动

推荐直接使用 Windows 脚本：

```powershell
pwsh -ExecutionPolicy Bypass -File .\scripts\dev-server.ps1 restart
```

查看运行状态：

```powershell
pwsh -ExecutionPolicy Bypass -File .\scripts\dev-server.ps1 status
```

默认地址：

- 前端：`http://localhost:3000`
- 后端：`http://localhost:8080/api`
- MCP 工具服务：`http://localhost:8081/mcp`
- OpenAPI：`http://localhost:8080/api/v3/api-docs`
- Swagger UI：`http://localhost:8080/api/swagger-ui.html`

常用检查命令：

```powershell
cd ai-memo-server
mvn -q -DskipTests package

cd ..\ai-memo-web
npm run lint
npm run type-check
npm run build
```

### Docker 部署

仓库已包含：

- `docker/docker-compose.yml` - 基础设施组件（PostgreSQL、Redis、MinIO、SearXNG）
- `docker-compose.yml` - 应用服务（后端、前端、MCP 服务、网关）
- `ai-memo-server/Dockerfile`
- `ai-memo-mcp-server/Dockerfile`
- `ai-memo-web/Dockerfile`
- `deploy/nginx/default.conf`
- `ai-memo-server/src/main/resources/application-prod.yml`

#### 首次部署

```bash
# 1. 启动基础设施（PostgreSQL + Redis + MinIO + SearXNG）
cd docker && docker compose up -d && cd ..

# 2. 构建并启动应用服务（后端 + 前端 + MCP 服务 + 网关）
docker compose up -d --build

# 3. 查看状态
docker compose ps
```

#### 后续升级

升级时只需重建应用服务，基础设施无需变动：

```bash
# 拉取最新代码后，重建应用服务
docker compose up -d --build
```

#### 基础设施组件

`docker/docker-compose.yml` 包含：

| 服务 | 说明 | 端口 |
|------|------|------|
| `postgres` | PostgreSQL 16 数据库 | 5432 |
| `redis` | Redis 8.6.3 缓存 | 6379 |
| `minio` | MinIO 对象存储 | 9000/9001 |
| `searxng` | SearXNG 搜索引擎 | 8888 |
| `searxng-redis` | SearXNG 缓存 | 内部 |

通过共享网络 `ai-memo-infra` 与应用服务通信。

#### 应用服务

`docker-compose.yml` 包含：

| 服务 | 说明 | 端口 |
|------|------|------|
| `backend` | Spring Boot 后端 | 8080 |
| `mcp-server` | MCP 工具服务 | 8081 |
| `frontend` | Next.js 前端 | 3000 |
| `gateway` | Nginx 网关 | 80 |

#### 首次初始化结果

首次启动时，后端会自动完成：

- 基础表结构初始化
- 权限、菜单、角色等种子数据初始化
- 默认管理员初始化

默认管理员账号：

- 用户名：`root`
- 密码：`1223456`

建议首次登录后立即修改默认管理员密码。

#### 数据持久化

默认会创建以下持久化卷：

- `postgres_data` - 数据库数据
- `redis_data` - Redis 数据
- `minio_data` - MinIO 对象存储数据
- `searxng_redis_data` - SearXNG 缓存数据
- `backend_uploads` - 后端上传文件

重复执行 `docker compose up -d --build` 不会删除已有数据。只有显式执行 `docker compose down -v` 才会连卷一起删除。

#### 关键配置项

当前仓库采用"全部配置以 yaml 为主"的模式：

- 应用运行配置：`ai-memo-server/src/main/resources/application-prod.yml`
- MCP 服务配置：`ai-memo-mcp-server/src/main/resources/application-prod.yml`
- 基础设施编排：`docker/docker-compose.yml`
- 应用服务编排：`docker-compose.yml`

#### 修改 PostgreSQL 密码

`POSTGRES_PASSWORD` 只会在 PostgreSQL 数据目录首次初始化时生效。如果 `postgres_data` 卷已经存在，需手动修改：

```bash
# 进入 PostgreSQL 容器修改密码
cd docker && docker compose exec -T postgres psql -U postgres -d studydb -c "ALTER USER postgres WITH PASSWORD '你的新密码';"
```

#### 验证命令

```bash
# 检查前端首页
curl http://localhost

# 检查 Swagger
curl http://localhost/api/swagger-ui.html

# 检查 MCP 工具服务
curl -X POST http://localhost:8081/mcp/transport \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

# 检查默认管理员是否已初始化
cd docker && docker compose exec -T postgres psql -U postgres -d studydb -c "select id,username,email,status from studys.users where username='root';"

# 检查权限种子是否已初始化
cd docker && docker compose exec -T postgres psql -U postgres -d studydb -c "select count(*) as permission_count from studys.auth_permission;"
```

## 登录与入口

- 游客登录：进入首页 `/`
- 普通用户登录：进入首页 `/`
- 普通用户可从首页进入应用中心 `/workspace`
- 后台能力统一由左侧菜单按权限显示，不再通过登录页切换入口

默认角色与入口策略：

- `GUEST` 默认具备 `chat:use`、`knowledge:chat`
- 新注册用户默认绑定 `APP_USER`，并具备 `workspace:access`、`knowledge:workspace`
- `ORG_ADMIN`、`ORG_MEMBER` 默认同样具备 `workspace:access`、`knowledge:workspace`
- `SYSTEM_ADMIN` 保持全量权限

## 模块说明

README 只保留总览、启动和部署说明，详细功能已下沉到 `docs/`：

- [产品模块说明](./docs/product-modules.md)
- [AI 与知识库实现说明](./docs/ai-knowledge-runtime.md)
- [Docker Compose 部署说明](./docs/docker-compose-deployment.md)
- [工具服务改造计划](./docs/tool-service-migration-plan.md)
- [ReactAgent 改造计划](./docs/spring-ai-alibaba-reactagent-migration-plan.md)
- [ReactAgent 详细执行计划](./docs/spring-ai-alibaba-reactagent-execution-plan.md)
- [外部数据目录覆盖模板](./deploy/docker-compose.external-data.override.yml)

## 安全加固与架构优化

本节记录近期代码审计后的修复与优化内容。

### 安全加固

- **调试端点限制**：SecurityTestController 调试端点仅在 `dev`/`local` profile 下可用，生产环境自动禁用
- **MCP 调试端点限制**：MCP Server 的 `GET /tools` 调试端点仅在 `dev`/`local` profile 下可用
- **工具代码安全检查加固**：`ToolCodeSecurityValidator` 所有 41 条正则规则统一添加 `CASE_INSENSITIVE` 标志，防止大小写绕过
- **聊天端点收紧**：移除聊天接口的公开白名单，游客统一通过 JWT Token + 限流机制访问
- **安全白名单单一数据源**：所有公开路径白名单统一收口到 `PublicPathConstants`，消除分散维护风险
- **SSRF 防护共享组件**：提取 `SsrfProtection` 为共享工具类，DNS 解析失败时直接拒绝请求
- **Redis 不可用时安全降级**：Redis 连接异常时安全拒绝访问，不再静默放行
- **XSS 修复**：`highlightKeyword` 方法修复跨站脚本注入风险
- **API Key 哈希化**：存储层对 API Key 进行哈希处理，降低明文泄露风险

### 架构优化

- **恢复 Spring AI 原生 MCP Server 传输**：移除自定义传输层，回归 Spring AI 标准实现
- **移除 current_time 重复实现**：统一使用 MCP Server 内置的时间工具
- **清理冗余 MCP 端点**：精简 MCP 服务暴露的端点，降低攻击面
- **CUSTOM_API 统一执行路径**：删除 `CustomApiToolCallback`，CUSTOM_API 类型工具统一通过 MCP Server 执行，与 FUNCTION_CALL 共享同一路径
- **线程池生命周期管理**：线程池添加 `@PreDestroy` 注解，确保应用关闭时正确释放资源

### 代码质量

- **移除死代码**：清理 `McpTool`、`McpToolImplementation`、`AiConfiguration`、`CustomApiToolCallback` 等不再使用的类，删除 6 个空壳 hooks 和孤立的 `floating-panel` 目录
- **日志框架统一**：`GenerateVideoExecutor` 统一使用 `@Slf4j`，移除手动 Logger 创建
- **SQL schema 前缀统一**：移除 14 个 Java 文件中的 `studys.` 冗余前缀，依赖 PostgreSQL `currentSchema` 配置
- **RAG 正则加固**：调用链中 RAG 查询提取正则改为大小写不敏感，支持 `Question:`/`Q:` 等变体格式
- **工具缓存升级**：工具缓存从自定义实现改为 Caffeine，设置 10 分钟过期策略
- **移除反射注入 fallback**：清理通过反射绕过依赖注入的兜底逻辑

## 项目结构

```text
ai-memo-assistant/
├── ai-memo-server/       # Spring Boot 后端
├── ai-memo-mcp-server/   # MCP 工具服务
├── ai-memo-web/          # Next.js 前端
├── docker/               # 基础设施组件（PostgreSQL、Redis、MinIO、SearXNG）
├── docs/
└── scripts/
```

## 对象存储

项目使用 **MinIO** 作为对象存储服务，替代腾讯云 COS。

| 配置项 | 值 |
|--------|-----|
| 服务地址 | `http://服务器IP:9000` |
| 管理界面 | `http://服务器IP:9001` |
| Bucket | `ai-memo` |

对象 Key 格式按业务分类：
- `app/icon/` - 应用图标
- `profile/avatar/` - 用户头像
- `chat/` - 聊天附件
- `knowledge/` - 知识库文档
- `handbook/` - 手册文件

## MCP 工具服务

项目使用独立的 **MCP (Model Context Protocol) 工具服务**，与业务服务解耦。

### 架构特点

- **服务独立**：工具服务独立部署，端口 8081
- **标准协议**：使用 Spring AI MCP Server 框架
- **Streamable HTTP**：支持 SSE 流式传输
- **易于扩展**：新增工具只需实现 ToolCallbackProvider

### 内置工具

| 工具 | 说明 |
|------|------|
| `searxng_search` | 联网搜索，集成 SearXNG 引擎 |
| `current_time` | 获取当前服务器时间 |

### AI 创建工具执行链路

通过「一句话创建工具」功能创建的工具会动态注册到 MCP Server，支持两种执行模式：

| 工具类型 | 执行方式 | 说明 |
|----------|----------|------|
| `CUSTOM_API` | 主后端直接执行 | HTTP API 调用，支持 URL 模板、请求头、响应路径提取 |
| `FUNCTION_CALL` | MCP Server 沙箱执行 | Nashorn JS 沙箱，静态代码安全检查 + 指令计数器 + 超时控制 |
| `MCP_TOOL` | MCP Server 标准协议 | 通过 MCP 协议调用外部工具服务 |

安全特性：SSRF 防护、HTTP 方法白名单、URL 参数编码、JS 沙箱静态分析（23 种危险模式检测）。

### 搜索引擎

集成 **SearXNG** 自建元搜索引擎，聚合国内可用引擎：

- 百度搜索
- 360 搜索
- 搜狗搜索
- Bing 搜索

## API 接口概览

后端接口统一以 `/api` 为前缀，完整接口文档可通过 Swagger UI 查看（`http://localhost:8080/api/swagger-ui.html`）。

主要接口模块：

- **模型目录管理**：`GET /api/admin/model-catalog`、`POST /api/admin/model-catalog`、`PUT /api/admin/model-catalog/{id}`、`DELETE /api/admin/model-catalog/{id}`
- **模型配置**：后台共享模型与用户私有模型配置，支持 CHAT / EMBEDDING 分离
- **用户与权限**：用户、组织、角色、权限、菜单、资源管理
- **应用中心**：应用 CRUD、图标上传、上下架管理
- **知识库**：知识库创建、文档上传解析、向量检索
- **聊天与 AI**：OpenAI 兼容聊天、SSE 流式推送、工具调用、知识库增强、上下文压缩（支持压缩专用模型配置）
- **对话性能优化**：SSE 流式响应单次解析、对话历史 Redis 缓存（TTL 30 分钟）、知识库权限与附件并行处理、压缩耗时日志监控

详细接口参数与响应结构请参考 [API 接口参考](./docs/api-reference.md)。

## 本地开发补充说明

开发脚本默认使用 `D:\Tools\java\java17`，并先执行 `mvn -q -DskipTests package` 再启动后端 jar，确保本地源码修改会重新打包生效，避免误启动旧的 `target/*.jar`。

如需切换运行模式：

- `AI_MEMO_BACKEND_START_MODE=source`：使用 `mvn spring-boot:run`
- `AI_MEMO_BACKEND_START_MODE=jar`：跳过打包直接运行现有产物
- `AI_MEMO_JAVA_HOME`：指定其他 JDK

脚本运行日志默认写入 `.runtime-logs`，如果该目录不可写会自动降级到 `D:\ai_space\ai-memo-assistant-runtime`。

本地开发默认集中配置文件：

- [application.yml](./ai-memo-server/src/main/resources/application.yml)
- [application-local.yml](./ai-memo-server/src/main/resources/application-local.yml)

其中包含：

- Redis 向量索引配置
- MinIO 对象存储配置
- MCP 工具服务配置
- 聊天附件临时目录

本地开发可直接使用仓库内配置启动；生产或多人环境不要提交新的明文密钥，应改用环境变量、加密值或外部配置中心覆盖。

## 数据库迁移

项目已禁用启动时自动执行数据库迁移脚本，改为手动执行方式。

### 迁移脚本位置

所有迁移脚本位于 `ai-memo-server/src/main/resources/db/migration/` 目录，按版本号命名（V4 ~ V55）。

### 合并脚本

为方便一次性执行所有迁移，已提供合并脚本：

```
ai-memo-server/src/main/resources/db/migration/all-in-one-migration.sql
```

### 手动执行方式

**方式一：使用 DBeaver / Navicat 等数据库工具**

1. 连接到 PostgreSQL 数据库（`studydb`，schema: `studys`）
2. 打开 `all-in-one-migration.sql` 文件
3. 执行全部脚本

**方式二：使用 psql 命令行**

```bash
psql -h 118.25.77.19 -U postgres -d studydb -f ai-memo-server/src/main/resources/db/migration/all-in-one-migration.sql
```

**方式三：逐个执行版本脚本**

如需按版本逐步执行，可按 V4 → V5 → ... → V55 的顺序依次执行各脚本。

### 配置说明

迁移开关配置在 `application.yml` 中：

```yaml
app:
  database:
    migration:
      enabled: false  # 设为 true 可恢复启动时自动执行
```

> **注意**：迁移脚本使用 `CREATE TABLE IF NOT EXISTS` 和 `ADD COLUMN IF NOT EXISTS` 等幂等语句，重复执行不会报错。

## 历史清理说明

本仓库已移除旧的备忘录业务主线，包括：

- 备忘录 CRUD
- 归档
- 导出
- 工作报告
- 统计分析
- 模板、分享、提醒、搜索等备忘录附属前端框架
- 对应后端接口、权限、菜单和数据库清理迁移

## 相关文档

- [后端说明](./ai-memo-server/README.md)
- [前端说明](./ai-memo-web/README.md)
- [Docker Compose 部署说明](./docs/docker-compose-deployment.md)
- [工具服务改造计划](./docs/tool-service-migration-plan.md)
- [外部数据目录覆盖模板](./deploy/docker-compose.external-data.override.yml)
- [产品模块说明](./docs/product-modules.md)
- [AI 与知识库实现说明](./docs/ai-knowledge-runtime.md)
- [权限架构设计](./docs/permission-architecture.md)
- [葵花宝典与知识库设计](./docs/kuihua-knowledge-design.md)
- [API 接口参考](./docs/api-reference.md)
- [团队技术能力提升计划](./docs/team-technicial-improvement-plan.md)
- [代码质量评估报告](./docs/code-quality-assessment-report.md)
- [Code Review 检查清单](./docs/code-review-checklist.md)
- [技术债务跟踪表](./docs/technical-debt-tracking.md)
- [技术分享会模板](./docs/weekly-tech-sharing-template.md)
- [快速启动指南](./docs/quick-start-guide.md)
- [UI 重设计方案](./docs/ui-redesign/README.md)