WeKnora 离线部署：Docker + Ollama 跑通文档问答全链路-编程实验室

WeKnora 离线部署：Docker + Ollama 跑通文档问答全链路

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora

WeKnora 把 PDF、Word 等原始文档变成可检索的 RAG 知识库（检索增强生成：先查文档片段再让大模型作答），配一个能自主推理的问答 Agent。本文带你在一台无外网的机器上完成 WeKnora 离线部署，从克隆代码到拿到带引用出处的回答。

这类场景才值得动手

机器连不上外网。单位内网、机房服务器调不通云端模型 API，离线部署后文档解析、向量检索、模型推理全在本机完成，拔网线照样跑。如果只是个人尝鲜、不需要多空间协作，看 docs/LITE.md 介绍的单应用 Lite 版本，部署更轻。
数据不能出机器。金融、政务、医疗文档动辄涉密，丢给第三方 API 过不了合规，私有化部署后文件只落在自己的磁盘上。如果只是测试云端方案效果，直接用官方 SaaS 或自带 API Key 部署更省事。
想在单机上吃透整套 RAG 链路。不为生产，只为学习检索链路或给小团队做试点，单机 Docker 就够，不需要 Kubernetes 那套重型编排。

动手前的硬条件

一张短清单，全部满足再开工：

软件：Docker（≥ 20.10）+ Docker Compose（v2）+ Git。为什么：整套服务用 Compose 编排，Ollama 由启动脚本托管，缺一个都拉不起来。
硬件：8 核 CPU + 32GB 内存起步。为什么：模型推理主要吃内存，跑 7B 对话模型建议留 16GB 以上可用。
磁盘：预留 200GB。为什么：镜像、模型、文档解析产物都会往盘上写，解析大扫描件时空间消耗比想象的大。
⚠️网络窗口：首次拉镜像、拉模型必须联网。真正的无网环境，正确姿势是一台联网机器下载好所有东西再拷到目标机，而不是在目标机上现拉。

把服务拉起来的完整操作

拿到代码并初始化配置

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env

整个部署只有一个配置入口：数据库密码、存储类型、Ollama 地址全在.env，模板里每项都带注释，照着填就行。

改对三个关键变量

打开.env，重点确认这几处，其余保持默认：

STORAGE_TYPE保持local，文件直接存容器挂载的本地目录，不引入对象存储；
OLLAMA_BASE_URL默认http://host.docker.internal:11434，让容器找到宿主机的 Ollama；
DB_PASSWORD、REDIS_PASSWORD、SYSTEM_AES_KEY换成自己生成的值，内网部署也别沿用模板示例值。

另外 config/config.yaml 会被直接挂载进 app 容器，想微调解析和检索行为时改它就行，不用重建镜像。

一条命令拉起全部容器

./scripts/start_all.sh --no-pull

这个脚本把三件事串起来：确认 Ollama 在跑、检查.env是否齐全、再用 Compose 拉起前端、app、postgres、docreader、redis 这批容器。--no-pull表示不联网拉镜像、直接用本地已有的，这正是 WeKnora 离线环境部署的关键开关；第一次在有网机器上部署的话去掉这个参数。动手前可以先跑./scripts/start_all.sh -c做一次环境自检。

🚀 脚本末尾打印出"前端界面: http://localhost"和"API接口: http://localhost:8080"，说明集群起来了。

灌入本地模型

对话和嵌入各需要一个：

ollama pull bge-m3 # 嵌入模型 ollama pull qwen2.5:7b # 对话模型，换成你已有的模型名

无网机器上，这两步要在联网机器执行、导出模型文件后拷过来再导入。这是 Ollama 模型导入最容易踩的地方：ollama pull只负责联网下载，离线环境只能走"导出—拷贝—导入"。模型没就位时 app 只会告警、不会崩，但问答功能暂时用不了。

跑没跑通，5 秒验证

执行docker compose ps：所有容器状态为 Up，重点看 WeKnora-app、WeKnora-postgres、WeKnora-docreader。
执行curl -f http://localhost:8080/health：返回 200，后端健康检查通过。
浏览器打开 http://localhost 并注册登录第一个账号：默认开放注册，能进首页说明前端与 API 已连通。
新建知识库、上传一份 PDF，等解析状态变成"完成"：docreader 解析、分块、向量化这条链路通了。
在问答页问一句"这份文档主要讲什么"，拿到带引用出处的回答，整条 RAG 链路全通。

高频踩坑，两句话解决

app 容器反复重启，日志全是 Ollama 连不上：先在宿主机curl http://localhost:11434/api/tags确认 Ollama 活着 → 再核对.env的OLLAMA_BASE_URL，容器内要写host.docker.internal，不能写localhost。
上传文档直接被拒：默认单文件上限 50MB（MAX_FILE_SIZE_MB），超限直接拒 → 文件没超就看docker compose logs docreader，解析器会报具体是哪种格式不支持。
问答太慢：无 GPU 时推理全压在 CPU 上 → 换一个更小的对话模型，或把.env里的BATCH_EMBED_SIZE调小换内存，通常比换硬件见效快。