本地优先的 RAG 知识库与对话工作台。Go 后端 + React 前端 + Qdrant 向量库一体化打包,支持 Ollama 等本地模型,也可挂任意 OpenAI 兼容服务,全部数据落在本地磁盘。
- 本地优先:对话历史、知识库元数据、上传文件、向量索引全部存在
backend/data/与 Qdrant 容器卷里,不依赖任何 SaaS。 - 多模型:聊天 / Embedding 各自独立配置,可挂 Ollama、任意 OpenAI 兼容网关,或同时使用。
- 多用户:自带账号体系(SQLite + bcrypt + JWT),每个用户独立的对话历史、知识库范围与模型 API Key;用户级 API Key 可选 AES-GCM 落盘加密。
- MCP 支持:内置 MCP server,可被外部 Agent 通过
/mcp端点调用知识库检索能力。 - 混合检索:稠密向量 + 稀疏向量(BM25 风格)RRF 融合,结构化文档(CSV/Excel)自动生成摘要 chunk 排在前位。
- 可选增强:查询改写、多查询扩展、语义重排、上下文压缩、语义缓存,均以特性开关控制,默认关闭。
- 单二进制部署:构建阶段把前端
dist/嵌入到 Go 后端二进制,生产模式下后端同时托管 SPA 与 API。
| 层 | 选型 | 说明 |
|---|---|---|
| 后端语言 | Go 1.25 | 单二进制,模块化 service / handler / router |
| Web 框架 | gin v1.9.1 | + 自实现 requestID / accessLog / CORS 中间件 |
| 鉴权 | golang-jwt/jwt v5 | access 15min + refresh 30 天,单 flight 续期 |
| 存储 | modernc.org/sqlite | 纯 Go SQLite(无 CGO),auth.db + chat-history.db |
| 文档解析 | ledongthuc/pdf, xuri/excelize | PDF、Excel、CSV、Markdown 文本抽取 |
| 向量库 | Qdrant v1.13.4 | 通过 HTTP API 直连,无 SDK 依赖 |
| 前端框架 | React 18 + Vite 5 + TypeScript 5 | SPA |
| 富文本 | react-markdown + remark-gfm + mermaid | 助手回复支持 Markdown / 代码块 / 图表 |
| 模型 SDK | openai v4 | 仅在前端用作 OpenAI 兼容侧的探活辅助 |
| 部署 | Docker Compose | 3 容器:qdrant / backend / frontend(nginx) |
适合日常调试:Qdrant 跑在容器里,后端 go run,前端 vite dev。
- Go 1.25+
- Node.js 18+
- Docker(仅给 Qdrant 用)
- 任一种模型来源:
- 本地 Ollama,且至少有一个 chat 模型(
qwen2.5:7b/qwen2.5:0.5b等)和一个 embedding 模型(bge-m3、nomic-embed-text等) - 或任意 OpenAI 兼容服务的 base URL + key(启动后从前端设置面板填入)
- 本地 Ollama,且至少有一个 chat 模型(
./dev.shdev.sh 行为:
- 若主机上没有 Qdrant 容器在跑,自动
docker compose up -d qdrant拉起。 - 在后台
go run .(日志写到/tmp/knowport-backend.log),等待/health通过。 - 前台启动
npm run dev --port 5174 --host 0.0.0.0。 Ctrl+C退出时自动 kill 后端进程;Qdrant 容器保留(数据不丢)。
启动完毕后访问:
- 前端:http://localhost:5174
- 后端 API:http://localhost:8080
- Qdrant:http://localhost:6333
直接 export 或写到根目录 .env:
QDRANT_VECTOR_SIZE=1024 # 必须与 embedding 模型输出维度一致
OLLAMA_BASE_URL=http://localhost:11434
JWT_SECRET=please-change-in-prod
CONFIG_ENCRYPTION_KEY= # 32 字节 base64,留空则用户 API Key 明文落盘完整环境变量见 backend/internal/config/config.go 的 LoadServerConfig。
适合放在自己的服务器或本机长期跑。
仓库根目录有一份 env.example 模板。复制后编辑成你自己的 .env(.env 已 gitignore,不会进版本控制):
cp env.example .env然后用编辑器打开 .env,至少改两项必填的密钥(模板里标了 CHANGE_ME 的就是必改项):
# 生成 JWT 签名密钥(48 字节随机 base64)
echo "JWT_SECRET=$(openssl rand -base64 48)"
# 生成 API Key 加密密钥(32 字节随机 base64)
echo "CONFIG_ENCRYPTION_KEY=$(openssl rand -base64 32)"把两条 echo 的输出贴回 .env 里替换对应的 CHANGE_ME 行。
关键提示:
JWT_SECRET决定登录态签名安全性,必须随机;改了之后所有现有用户会被踢下线。CONFIG_ENCRYPTION_KEY用来加密用户在前端设置面板填的模型 API Key。一旦设置后丢了,所有用户存的 Key 都解不出来——务必备份到密码管理器或其他物理介质。QDRANT_VECTOR_SIZE必须与你后续在前端设置面板里选的 embedding 模型一致:bge-m3 → 1024,nomic-embed-text → 768。Qdrant collection 第一次创建后维度就固定了,改维度需要清掉 qdrant 数据卷。
.env 在 docker compose up 时被 compose CLI 自动加载(要求 .env 与 docker-compose.yml 同级),里面的变量替换 compose 文件里 ${VAR:-...} 占位符,再通过 environment: 段注入容器进程。
./build.shbuild.sh 把 BUILD_TIME 与 GIT_COMMIT 注入构建参数,然后 docker compose build。
docker compose up -d容器对外端口:
| 服务 | 容器端口 → 主机端口 | 说明 |
|---|---|---|
| qdrant | 6333 → 6333 | 向量库 HTTP API |
| backend | 8080 → 8081 | Go 后端 + 嵌入式 SPA |
| frontend | 4173 → 5173 | Nginx 反代 /api、/v1、/mcp 到 backend |
完成后:
./backend/data/经 bind mount 进容器,包含 SQLite 数据库与上传文件,不要手动删。- Qdrant 用 named volume
qdrant_storage,重建容器不丢;如需彻底清空:docker compose down -v。
git pull
./build.sh
docker compose up -dai-localbase/
├── backend/ Go 后端
│ ├── main.go 进程入口;加载配置 / 初始化 service / 挂路由 / embed dist
│ ├── dist/ 嵌入式前端产物(构建时由前端 build 填充)
│ ├── data/ 运行时数据(大部分被 gitignore)
│ │ ├── app-state.json 全局应用状态(系统级默认 chat/embedding 配置等)
│ │ ├── auth.db SQLite:用户、refresh token、用户级模型配置
│ │ ├── chat-history.db SQLite:对话与消息
│ │ └── uploads/ 原始上传文件
│ ├── eval/ RAG 评估脚本(命令行工具)
│ └── internal/
│ ├── auth/ JWT 中间件、密码哈希、token 仓库
│ ├── config/ ServerConfig 加载与默认值
│ ├── handler/ HTTP handler:app_handler.go / auth_handler.go
│ ├── router/ 路由组装 + 中间件
│ ├── service/ 核心业务(见下方"模块")
│ ├── mcp/ MCP server 与工具暴露
│ ├── model/ 领域结构体
│ └── util/ 文档抽取、ID 生成等
├── frontend/ React 前端
│ └── src/
│ ├── App.tsx 根组件 + 全局状态机
│ ├── api/auth.ts token 存储 + 401 单 flight 续期
│ ├── components/
│ │ ├── AuthGate.tsx
│ │ ├── LoginPage.tsx
│ │ ├── LandingPage.tsx
│ │ ├── Sidebar.tsx
│ │ ├── ChatArea.tsx
│ │ ├── brand/ "知港"品牌组件
│ │ ├── welcome/ 登录后欢迎页
│ │ ├── knowledge/ 知识库面板
│ │ └── settings/ 设置抽屉(模型 / MCP / 高级)
│ ├── constants/ 文案常量
│ └── index.css 全局样式(含磨砂背景实现)
├── docker/ Dockerfile 与 nginx 配置
├── docker-compose.yml 生产 compose(唯一一份)
├── dev.sh 本地开发启动脚本
├── build.sh 本地镜像构建脚本
└── docs/ 学习与设计参考(部分文件本地保留,未推送)
| 文件 | 职责 |
|---|---|
app_service.go |
应用层聚合:知识库 CRUD、文档上传/索引/删除、对话保存、模型配置探活、用户级 embedding/chat 配置解析 |
app_state_store.go |
全局 app-state.json 读写,含系统默认 chat/embedding 配置 |
user_store.go |
用户表 + 用户级模型配置(API Key 可选 AES-GCM 加密落盘) |
chat_history_store.go |
对话与消息的 SQLite 存储 |
llm_service.go |
上游 chat completion 调用(Ollama / OpenAI 兼容) |
rag_service.go |
文档切分、Embedding、Qdrant 写入/检索、RRF 融合、查询改写 |
model_probe.go |
模型可用性探活(前端"测试连接"用) |
auth_handler.go:/api/auth/register | login | refresh | logout | meapp_handler.go:业务接口(详见router/router.go),全部走RequireUserJWT 中间件- OpenAI 兼容端点:
/v1/chat/completions[/stream](也鉴权) - MCP:
/mcp/*(基于ENABLE_MCP开关)
AuthGate.tsx:未登录则渲染LandingPage+LoginPage;已登录进入主工作台。Sidebar.tsx:会话列表、知识库列表、用户菜单、入口到设置抽屉。ChatArea.tsx:消息流、Markdown 渲染、知识库召回信息、流式响应。settings/SettingsPanel.tsx:模型配置 / MCP / 高级开关;带显式"保存"按钮与状态文案。knowledge/:知识库与文档面板(上传、删除、状态显示)。
完整链路:PDF/Excel/CSV/MD/TXT → 文本抽取 → 切分 → 结构化摘要前置 → Embedding → Qdrant 入库 → 检索时 RRF 融合。
按扩展名分发:PDF(ledongthuc)、Excel(excelize)、CSV(自带表头扫描,输出"字段:xx。数据行数:n。"等结构化摘要行)、Markdown / TXT 直读。失败回退到文件名 + 文件大小占位文本,保证索引链路不中断。
- 默认
CHUNK_SIZE=400,CHUNK_OVERLAP=80(按 rune 计算,CJK 友好)。 - 优先在句末标点处切,避免词中切断。
- 对结构化文档(CSV / Excel):先抽取"统计摘要 / 字段分布 / 文件汇总"行,生成
kind=structured_summary的摘要 chunk,强制排在 chunk 列表最前位。 - 普通文档的第一个 chunk 也会标记为
kind=summary,便于检索时优先曝光开头。
- 用户级配置优先:
currentEmbeddingConfigFor(userID)从 user_store 读取,回退到全局默认。 - 调用 Ollama
/api/embeddings或 OpenAI 兼容的/embeddings。 - 上游失败时回退到
deterministicEmbedding(基于哈希的伪向量,仅保证流程不挂;检索质量会下降,但能等模型恢复)。 - 向量维度 =
QDRANT_VECTOR_SIZE,必须与 embedding 模型对齐。
- 每个知识库对应一个 Qdrant collection,命名
kb_<knowledgeBaseID>。 - 创建时按
QDRANT_VECTOR_SIZE+QDRANT_DISTANCE(默认cosine)建集合。 - 写入 payload 字段:
chunk_id / text / document_id / document_name / knowledge_base_id / chunk_index / kind。
- 基线:
searchDense用查询向量在 Qdrant 上做/points/search。 - 混合检索(
ENABLE_HYBRID_SEARCH=true):同时跑 dense + sparse(BuildSparseVector,BM25 风格,按 token 频次 + CJK 分词构造稀疏向量),按 RRF(Reciprocal Rank Fusion,rrfFusion)合并。 - 多查询扩展:
MultiQuerySearch并发地用 N 条改写查询召回,去重后再融合,缓解原问题表述模糊导致召回偏窄的问题。 - 关键参数:
RETRIEVAL_TOPK_DOCUMENT=4—— 单文档/单 KB 最终保留 chunk 数。RETRIEVAL_CANDIDATE_TOPK_DOCUMENT=8—— 单文档召回候选数(fusion 前)。RETRIEVAL_TOPK_KNOWLEDGE_BASE=5—— "全 KB"模式默认 topK。RETRIEVAL_CANDIDATE_TOPK_ALL_DOCS=10—— 全 KB 召回候选数。RETRIEVAL_MAX_CHUNKS_PER_DOCUMENT=1—— 防止单文档刷屏。RETRIEVAL_MAX_CONTEXT_CHARS=2400—— 拼接进 prompt 的字符上限。
NewLLMQueryRewriter用 chat 模型把原问题改写为 N 条等价/扩展查询(保留原句),列表化输出。- 用于
MultiQuerySearch的并发召回,去重后送入融合阶段。
- 在 RRF 融合后,对 top-K 候选用 chat 模型做相关性打分重排(开销大,默认关)。
- 检索到的 chunk 在拼 prompt 前先用小模型做"抽取式压缩",去掉与问题无关的句子,降低上下文消耗。
- 用问题向量在内存 LRU 里查相似 QA 对,命中阈值内直接复用答案,跳过检索 + LLM 推理(适合 FAQ 类高频问题)。
- 把命中 chunk 按文档分组、限制条数与字符上限,附带
chunk_id/document_name供前端展示"召回来源"。 - 失败容忍:若检索完全失败,返回空上下文继续走纯对话,让链路不会因为向量库故障整体挂掉。
- 当首轮命中分数偏低时自动拓展窗口或追加 chunk,避免回答时上下文不足。
Qdrant collection 创建时的维度与当前 embedding 模型输出维度不一致。修复:
- 在前端设置面板确认 embedding 模型,或本地
ollama list查看模型维度。 - 修改
.env的QDRANT_VECTOR_SIZE(bge-m3 = 1024;nomic-embed-text = 768)。 - 清旧数据后重启:
docker compose down docker volume rm ai-localbase_qdrant_storage docker compose up -d
宿主跑 Ollama,容器请求 host.docker.internal 失败。docker-compose.yml 里 backend 已配置:
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
OLLAMA_BASE_URL: http://host.docker.internal:11434如果仍然失败,先在宿主验证 Ollama API 是否真的起来:
curl -v http://localhost:11434/v1/models返回 200 + 模型列表才算正常。Linux 用户若 host-gateway 不可用,可手动给容器加路由或把 Ollama 改成监听 0.0.0.0:11434,然后用宿主 LAN IP 替换 host.docker.internal。
历史遗留 bug:旧版本 IndexDocument 用全局默认 embedding 配置,忽略了用户在设置面板填的 base URL / key。已修复为按当前登录用户的 user-level 配置走(currentEmbeddingConfigFor(userID))。如果仍遇到,确认:
- 设置面板里 embedding 模型 base URL / key 已点 保存,看到 "已保存" 状态。
- 后端日志能看到向你期望的 base URL 发请求。
绝大多数是 Vite dev server 长时间运行后 HMR 状态损坏。本地开发模式下:
# 重启前端 dev 进程
pkill -f 'vite' ; ./dev.sh浏览器侧 Ctrl+Shift+R 强刷一次。生产模式(Docker)出现白屏通常是 Nginx 反代到 backend 不通,看 docker compose logs frontend backend。
打包 backend/data/ 与 Qdrant volume 即可:
docker compose down
tar czf knowport-data.tgz backend/data
docker run --rm -v ai-localbase_qdrant_storage:/src -v "$PWD":/dst alpine \
tar czf /dst/knowport-qdrant.tgz -C /src .新机器解压到对应位置后 docker compose up -d 即可恢复。
docker compose down -v # 清 qdrant volume
rm -f backend/data/app-state.json # 清全局默认配置
rm -f backend/data/auth.db backend/data/chat-history.db # 清用户与历史
docker compose up -d注意此操作会清空全部数据。
# 后端日志
docker compose logs backend --tail 100
# 前端 nginx 日志
docker compose logs frontend --tail 100
# Qdrant 健康
curl -s http://localhost:6333/healthz
# 后端健康
curl -s http://localhost:8081/healthMIT,沿用原仓库。详见 LICENSE。