如何在无网络环境完成 WeKnora 离线部署：从内网隔离到首次问答的实操指南
【免费下载链接】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、提问、拿到带出处引用的答案。这就是 WeKnora 离线部署的玩法——在完全断网内网，用 Docker Compose 起一套文档问答服务，解析、索引、生成都发生在本地，数据不出机器。
快速开始：离线跑通的最小步骤
先看硬件底线。同时要跑 7B 级对话模型和整套容器，参考配置是：8 核 CPU（推荐 16 核）、32GB 以上内存、200GB 左右的 SSD。软件三件套：Docker Engine 20.10+、Docker Compose v2+、Git。
git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env docker compose up -d四步分别干的事：拿代码、复制配置模板（首次可以直接用默认值）、拉起全部容器。成功的标志：docker compose ps里所有服务都是 Up，浏览器打开 http://localhost 能看到页面。
⚠️ "离线"有个前置条件：镜像和模型要先"运"进内网。在有网机器上先docker compose pull，再用docker save $(docker compose config --images) -o weknora.tar导出，拷到目标机执行docker load -i weknora.tar。Ollama 同理：先装好、ollama pull好模型，把~/.ollama/models目录整体搬过去。镜像就位后，也可用 scripts/start_all.sh 的--no-pull参数启动，它会顺带把宿主机的 Ollama 服务拉起来。
组件分工与数据流一览
启动后是六个角色在配合，各自职责如下：
| 组件 | 职责 |
|---|---|
| frontend（Nginx） | Web 界面，把 API 请求反向代理给后端，监听 80 端口 |
| app（Go 主服务） | 业务 API、任务调度、调用模型，端口 8080 |
| docreader（Python 解析器） | 把 PDF/Word/PPT 等文件解析成结构化文本，走 gRPC 与 app 通信 |
| postgres（ParadeDB 镜像） | 存业务数据，同时充当默认向量库和检索引擎 |
| redis | 任务队列与缓存 |
| Ollama（宿主机） | 本地大模型推理，默认端口 11434 |
数据流向是单向闭环：浏览器到 frontend，frontend 转给 app；app 把文件丢给 docreader 解析，切块后调 embedding 模型转向量，文本和向量一起写入 postgres。提问时先按向量检索相关段落，再交给 Ollama 生成回答。
关键配置解读：默认值与改动后果
配置集中在.env，模板 .env.example 里每行都有注释。真正影响日常使用的只有下面五项：
- STORAGE_TYPE：默认
local，原文档落在 app 容器的本地磁盘卷。改成minio就必须加--profile minio启动，否则对象存储容器不会起来，上传会失败。 - OLLAMA_BASE_URL / OLLAMA_OPTIONAL：默认指向宿主机
http://host.docker.internal:11434。推理服务在单独的 GPU 机器上时，改掉 IP 即可；OLLAMA_OPTIONAL=true（默认）时 Ollama 挂了只告警不崩主服务。 - DB_DRIVER / RETRIEVE_DRIVER：默认都是
postgres，元数据和向量同库，零额外配置。要换 qdrant、milvus 得配对应的--profile。 - MAX_FILE_SIZE_MB：默认 50，单文件上传上限。超限直接拒收；要灌大 PDF 就调大它并重启。
- SYSTEM_AES_KEY：加密 API Key 等敏感字段的 32 字节主密钥，默认是公开占位值。⚠️ 正式使用前换成自己的值并保管好；存过密钥之后再改，旧密钥无法恢复。
模型部署也归在这节。无网环境下先把模型文件运进来，再在宿主机执行：
ollama pull bge-m3 # 嵌入模型 ollama pull deepseek-r1:7b # 对话模型成功的标志是ollama list能列出这两个模型。然后进 Web 界面"系统设置 → 模型配置"选中它们，保存并重启服务。
从上传文档到第一次问答
启动后全程在浏览器里操作，路径是固定的：
- 首次访问完成初始化。注册账号时把 Ollama 上那两个模型填进去。模型配置写进数据库，后续不用动 .env。
- 建知识库、传文档。"知识库 → 新建知识库"，拖入 PDF。状态从 processing 走到 completed 就算解析入库；长时间卡住就去查 docreader 的日志。
- 提问并核对答案。选中目标知识库，输入"如何配置离线模型？"这类问题。答案会带引用出处，点引用能跳回原文段落——离线部署的最低验收标准就是答案可溯源。
常见故障避坑指南与提速技巧
排查按"现象 → 原因 → 处理"走这张表：
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 前端打不开 | 80 端口被占，或 app 未通过健康检查 | 改FRONTEND_PORT；docker compose ps看健康状态 |
| 日志里模型连接失败 | Ollama 没起或OLLAMA_BASE_URL指错 | 宿主机ollama list验证；确认端口是 11434 |
| 文档卡在 processing | 扫描件解析慢，或文件损坏 | 换小文件验证；确认格式在支持列表内 |
| 回答慢、超时 | CPU 上跑 7B 模型到了上限 | 看下面提速技巧 |
| 内存持续吃满被 OOM | 解析和推理同时压上来 | 调小CONCURRENCY_POOL_SIZE（默认 5） |
提速技巧（对应资源调优项）：
- 换更小或量化的模型：
llama2:7b比deepseek-r1:7b轻；4-bit/8-bit 量化能再省一半内存。 - 压并发：低配机器把
CONCURRENCY_POOL_SIZE调低，减少同时解析的文档数。 - 设资源上限：在 docker-compose.yml 给 app 和 Ollama 加
deploy.resources.limits，防止单服务吃光机器。 - 检索命中率不高：把 config/config.yaml 里的 chunk 尺寸调小，段落更聚焦。
- 数据双备份：
docker compose exec postgres pg_dump -U weknora weknora > backup.sql备份库，文档原件在 contenteditable="false">【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
