🏛️ ExpHub — AI 原生经验知识库 + 项目空间
让多个 AI 助手共享经验、协同进化的开源平台。
🌐 门户网站:https://cloudim.club — 注册即获专属 API Key,立即接入 MCP。
💡 为什么需要 ExpHub?
你在用 AI 编程助手(如 CodeBuddy、Cursor、Copilot 等)时,是否遇到过这些痛点:
- 🔁 同样的坑反复踩 — 上次花 2 小时解决的问题,下次会话 AI 完全不记得
- 🔀 多个助手各说各话 — 不同项目用不同 AI,经验零散、无法沉淀
- 📉 上下文丢失 — 每次新会话从零开始,无法持续积累团队知识
- 🗂️ 经验难以检索 — wiki/文档写了没人看,需要时找不到
- 🧭 AI 不了解你的项目 — 每次都要重新解释架构、规范、禁忌,还总漏掉关键约束
ExpHub 解决了这个问题: 把 AI 助手当作"知识工作者",通过 MCP 协议让它们自动搜索历史经验、沉淀新知识、追踪待办任务;并可为每个项目建立项目空间,让 AI 一进来就拿到项目手册与上次的进度 —— 形成持续进化的 AI 协作知识网络。
🎯 核心能力
🧱 双层结构
一个 API Key 下可建多个项目,用项目名 / 别名 / 编码检索。
🌐 在线门户
立即体验: https://cloudim.club
- 使用邮箱注册,秒级获取专属 API Key
- 将 API Key 填入 AI 助手的 MCP 配置
- AI 自动搜索经验、记录知识、追踪待办
CodeBuddy MCP 配置示例
{
"mcpServers": {
"exphub": {
"type": "sse",
"url": "https://cloudim.club/exphub/mcp/sse",
"headers": {
"authorization-key": "在此输入你的API Key"
},
"timeout": 120000,
"disabledTools": [],
"disabled": false
}
}
}
💡 其他 MCP 客户端(Cursor、Claude Desktop 等)配置方式类似,只需修改
url和headers。
🛠️ 技术栈
双端口架构(同一 JVM)
⚠️ MCP 必须使用 WebFlux(独立 3098),不要改回 Servlet
Servlet 版下每个 SSE 长连接会占用一个 Tomcat 工作线程且长期不释放,客户端重连 / 连接堆积会耗尽线程池(默认 200 个),导致整个应用假死(进程活着、端口在听,但所有请求超时)。WebFlux 的非阻塞模型不存在该问题。详见 TROUBLESHOOTING.md。
🚀 快速开始
环境要求
- JDK 17+
- Maven 3.x
- MySQL 5.7+
⚠️ 低版本 MySQL 不支持
LOCK=NONE/ALGORITHM=INPLACE类 DDL 语法,改表请在低峰期执行并先备份。
1. 初始化数据库
# 创建数据库
mysql -u root -p -e "CREATE DATABASE exphub DEFAULT CHARSET utf8mb4;"
# 导入初始化脚本
mysql -u root -p exphub < sql/init.sql
2. 配置环境变量
export EXPHUB_DB_URL=jdbc:mysql://localhost:3306/exphub?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
export EXPHUB_DB_USERNAME=root
export EXPHUB_DB_PASSWORD=your_password
3. 启动服务
# 编译
mvn clean package -DskipTests
# 启动(会同时监听 3099 Web 与 3098 MCP)
java -jar target/exphub-1.0.0.jar
4. 访问
⚠️ 首次登录后请立即修改默认密码,在后台右上角账号菜单中操作。
🐳 Docker 一键部署(推荐)
只需 3 步,30 秒启动:
# 1. 配置数据库密码
cp .env.example .env
# 编辑 .env 中的 EXPHUB_DB_PASSWORD
# 2. 启动(自动建库建表、拉取镜像、编译运行)
docker compose up -d
# 3. 查看日志
docker compose logs -f exphub
包含的服务:
常用命令:
docker compose up -d # 启动
docker compose down # 停止并清理
docker compose down -v # 停止并删除数据卷(重置数据库)
docker compose logs -f exphub # 实时日志
docker compose restart exphub # 重启应用
🖥️ 后台管理系统
自行部署 ExpHub 后,可通过后台管理系统进行可视化管理,无需直接操作数据库。
登录方式
访问 http://localhost:3099/exphub/login,使用默认账号登录:
⚠️ 安全提醒:首次登录后请立即修改默认密码。
功能模块
管理场景示例
- 新增 AI 助手接入:在「助手管理」中创建助手,生成 API Key 后填入 MCP 配置即可
- 给项目建手册:在「项目管理」新建项目 → 填 MAIN 索引(定位 + 章节目录 + 绝对红线)→ 逐章写入,AI 之后每次会话都能读到
- 排查调用问题:在「调用日志」中按 API Key 或时间范围筛选,快速定位异常请求
- 清理无效经验:在「经验管理」中批量更新或删除过期、低质量的经验内容
📦 MCP 工具列表(共 41 个)
全局经验库(25 个)
三个「列表」工具怎么选(职责边界)
它们都能回答「这里有什么」,但排序与分页方式不同,选错了会白花 token:
一句话:按时间 → recent,按归属 → project,按内容 → search。
项目空间(14 个)
版本维护(2 个)
经验模板类型(8 种)
🏗️ 项目结构
exphub/
├── src/main/java/com/exphub/
│ ├── controller/ # REST API + 页面路由(含 ProjectController 项目空间)
│ ├── service/ # 业务逻辑层(DocService / ProjectService 等)
│ ├── mapper/ # MyBatis-Plus 数据访问
│ ├── entity/ # 数据实体(Doc / Project / AiAssistant 等)
│ ├── interceptor/ # API Key 鉴权(ApiKeyInterceptor)
│ ├── config/ # Spring 配置
│ │ ├── WebMvcConfig # 拦截器注册
│ │ ├── SecurityConfig # 安全策略
│ │ └── McpContextPropagationConfig # ★ 身份上下文跨线程传播(Reactor onScheduleHook)
│ ├── mcp/ # MCP 相关
│ │ ├── ExpHubTools.java # 全部 25 个 MCP 工具定义
│ │ ├── McpReactiveServerConfig.java # 独立 WebFlux(Netty:3098) + API Key 鉴权
│ │ └── McpRequestBodyLoggingFilter.java
│ └── common/ # 通用工具类
├── src/main/resources/
│ ├── templates/ # Thymeleaf 后台页面(含 projects/ 项目空间页面)
│ └── application.yml # 主配置文件
├── sql/ # 数据库脚本
├── portal/ # 门户网站(纯静态)
├── deploy.sh # 服务器一键部署
└── pom.xml
🔒 安全设计
- API Key 鉴权:所有 MCP/API 请求需在 Header 中携带
authorization-key - 租户隔离:每个 API Key 独立经验空间,互不可见
- 项目空间隔离:项目手册 / 进度 / 专属经验默认隔离,不会出现在全局搜索结果中
- 身份上下文跨线程传播:MCP 工具实际运行在框架内部的 Reactor 线程上,身份通过
Schedulers.onScheduleHook在调度时捕获、执行时恢复 —— 确保多 Key 场景下隔离始终可靠(不依赖裸ThreadLocal,避免池化线程复用导致的身份串号) - 权限分级:支持搜索/创建/更新权限分别控制
- 密码加密:Spring Security BCrypt 加密存储
- 改动先小后大:
append_experience/patch_experience由服务端读改写全文,客户端永不持有全文,从机制上避免「读到截断版 → 整篇写回 → 丢后半段」这类事故 - 存疑横幅在读取端,不在正文里:
get_experience_detail与export_document都会在正文前拼「⛔ 已被取代 / ⚑ 标记」,两者共用同一份文案;RenderArtifactStripper同步剥离,防止整篇写回时把提示固化进正文 authorName与updatedName是两件事:前者 = 改文档作者(作品归属),后者 = 记录「这一次是谁改的」(写进版本快照)。所有文档写入工具都支持updatedName;一个 API Key 被多个助手共用时必须传,否则都记成 Key 名,审计链等于没有- 写操作回执自证值:不只说「已刷新」,还回显重新读出的实际值(如「相似度: 0.85」/「未记录」),值被规范化时说明为什么
- 整理只标记、不合并:
mark_superseded只写指针、resolve_candidate只打标记,两者都不改正文、不删数据。合并错了不可逆,比不整理更糟 - 候选队列不是自动清理队列:
review_candidates只记录「待判断」,界面里没有「合并」「删除」按钮;真正的删除仍要人先在后台确认 - 标记不产生版本垃圾:
set_flags只改flags列,不递增版本、不写版本快照;删除经验时级联清理该文档的全部历史快照(否则主表删了、正文全文仍在库里且界面不可见) - 模型无删除权:MCP 侧只能
mark_for_deletion(必须写原因),真正删除只能在后台由人执行;待删项对检索不可见,可一键恢复 - 敏感信息提醒:创建经验时提醒 AI 不记录密码、Token 等敏感数据
🚢 部署到生产环境
# 1. 服务器上 clone 项目(Gitee 或 GitHub)
git clone https://gitee.com/coolshiyue/exphub.git /usr/local/exphub
# 或
git clone https://github.com/530653327/exphub.git /usr/local/exphub
# 2. 创建环境变量文件(不提交到 git)
mkdir -p /etc/exphub
cat > /etc/exphub/.env << 'EOF'
EXPHUB_DB_URL=jdbc:mysql://localhost:3306/exphub?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
EXPHUB_DB_USERNAME=root
EXPHUB_DB_PASSWORD=your_secure_password
EOF
# 3. 部署
./deploy.sh
Nginx 反向代理参考
# MCP SSE + 消息端点 → 独立 WebFlux 服务(3098)
# 注意:必须禁用缓冲,否则 SSE 会被缓冲导致 AI 客户端收不到消息
location /exphub/mcp/ {
proxy_pass http://127.0.0.1:3098/mcp/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
}
# 后台 Web + 门户 → 应用(3099)
location /exphub/ {
proxy_pass http://127.0.0.1:3099;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
⚠️ 不要把
/exphub/mcp/指向 3099(WebMvc) —— 那会让 SSE 长连接占满 Tomcat 线程池并导致应用假死。 更多排障细节见 TROUBLESHOOTING.md
🤝 参与贡献
- GitHub:https://github.com/530653327/exphub
- Gitee:https://gitee.com/coolshiyue/exphub
- Issue 反馈:https://gitee.com/coolshiyue/exphub/issues
- 联系邮箱:[email protected]
- 开源协议:MIT License
欢迎提交 PR 或创建 Issue 讨论新功能!
ExpHub — 让 AI 不只回答问题,更能积累智慧。