如何在没有外网的内网服务器上跑通 WeKnora：从环境检查到第一份文档问答的完整实操

如何在没有外网的内网服务器上跑通 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

假设你的场景是这样的：一台公司内网的服务器，连不上公网，但老板要求把几十年的 PDF 合同、Word 制度文档做成一个可以"问一嘴就出答案"的知识库。云端大模型 API 在这里完全不适用——网络不通，数据也不能外流。

这篇文章带你把 WeKnora 完整部署在这台机器上。它本身就是一个开源的 LLM 知识平台：把上传的文档解析、分块、向量化，再结合本地大模型做检索增强问答。走完本文，你手上会有一个可以离线运行的文档问答系统，解析 PDF、Word 等十几种格式，问答全程不碰外网。跑通之后，向量检索响应一般在 300 毫秒内；8 核 CPU 下解析吞吐大约 50 页/分钟；16GB 内存跑 7B 模型的单轮回答延迟通常压在 2 秒以内。

先看懂再动手：一份文档上传后会经过哪几步

在敲命令之前，花三分钟把系统摸透，后面排查问题会顺很多。

你上传一份 PDF 之后，它的路径大致是：先进入文档解析服务（docreader），这个服务内置了多套解析引擎，会根据文件类型自动路由——扫描件会渲染成图片再走 OCR，纯文本 PDF 直接抽取文本层；解析结果被切成一个个带语义边界的"块"；接着向量化服务把每个块送进本地嵌入模型，变成一串向量存进向量库；原始文件则落到本地存储目录留底。

提问时走的是反向链路：你的问题先被理解和改写，然后系统用"全文关键词 + 向量相似度"混合的方式从库里捞出最相关的若干块，可选地再做一次重排序，最后把这些块拼进提示词，交给本地大模型生成回答。所以它答得准不准，一半取决于解析切块的质量，一半取决于检索捞回来的片段对不对。

存储这一层有三个角色：PostgreSQL 存所有元数据（知识库、会话、用户），向量库存嵌入向量，MinIO（或直接用本地目录）存原始文件。

你可能会问：为什么模型要用 Ollama 而不是云 API？原因很简单粗暴——你的机器没有外网，而 Ollama 可以把对话模型和嵌入模型都放在本机推理，数据一步都不出机房。为什么用 Docker Compose 而不是 K8s？因为这套系统总共十来个容器，一个 compose 文件就能编排，内网运维的人不用再多学一套工具。为什么解析器要本地化？云端文档解析 API 意味着敏感文档要发到别人的服务器上，这在内网合规面前是过不去的。

跟着做一遍：把整套服务拉起来

⚠️ 离线场景下最大的坑是镜像：服务器拉不到 Docker Hub。务必先在一台有网的机器上把镜像导出（docker save），拷贝到内网机器后docker load，后面启动时才敢加--no-pull。

先确认硬件够不够用

系统对硬件没有硬性门槛，但体验差别很大，建议按下表自查：

装好 Docker（≥20.10）和 Compose v2 后，用docker --version、docker compose version各验证一次。

拉代码，把离线参数配好

在有网的跳板机上克隆代码再整体拷贝进内网，或者内网机器有缓存也可以直接执行：

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

所有可调参数都收在一个环境变量文件里，从模板复制一份出来改：

cp .env.example .env

重点确认这几处（完整说明见 .env.example 里的注释）：

• STORAGE_TYPE=local——文件直接存本地目录，离线环境的正确姿势；
• OLLAMA_BASE_URL——指向 Ollama 所在地址。若 Ollama 和容器在同一台宿主机，保持默认http://host.docker.internal:11434即可；
• OLLAMA_OPTIONAL=true——Ollama 没就绪时系统只告警不崩，首次部署建议保留。

改完顺手留个底：cp .env .env.bak。

一键启动全部服务

先跑一遍环境自检，它会检查配置文件是否齐全并诊断常见问题：

./scripts/check-env.sh

确认没问题后，分两步把东西拉起来。Ollama 负责模型推理，单独启动：

./scripts/start_all.sh --ollama

再把模型拉进 Ollama——嵌入模型和对话模型各一个，离线机器上同样需要提前准备：

ollama pull bge-m3 ollama pull deepseek-r1:7b

最后启动主服务集群，--no-pull表示不再去仓库拉镜像（前提是你已经docker load好了）：

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

跑完用docker compose ps看一眼：frontend、app、docreader、postgres、redis 等容器都应该是 Up 状态，其中 app 有健康检查，显示 healthy 才算真正就绪。

上传第一份文档并提问

浏览器打开http://localhost，首次使用直接注册账号登录。接下来按界面引导走：新建一个知识库 → 上传一份本地 PDF → 等解析进度跑完，你会看到文档被切成的块列表：

然后打开会话窗口，直接问"这份文档的主要内容是什么？"。如果回答里带着原文的引用，说明从解析、向量化到本地模型推理的整条链路都通了。

跑起来之后：调优、排障和安全收口

性能往哪里拧

慢的地方通常就三处：解析、向量化、检索。解析慢，多半是大扫描件 PDF，把 .env.example 里的DOCREADER_PDF_RENDER_PARALLELISM从默认值调大（比如 4，前提是容器分到了足够的 CPU），渲染是并行最明显的环节；向量化排队，可以设BATCH_EMBED_SIZE控制批量大小，在内存紧张时调小更稳；问答太慢，优先减少检索返回的块数、或关闭重排序，用一点准确度换速度。改完环境变量重启对应容器即可生效。

平时盯这几个信号：CPU 常态 30%~70%、连续 5 分钟超 85% 就该看看是谁在空转；内存 40%~60% 健康，超 80% 注意是不是模型吃光了；向量检索响应正常在 200ms 内，稳定超过 500ms 要检查向量库负载；问答端到端超过 5 秒，先怀疑模型没跑在预期设备上。

高频问题及解法

问题：app 容器起不来或反复重启原因：内存不足、端口被占、或配置文件语法错误。 解决：free -m和df -h先看资源，docker compose logs app看最后几条报错，netstat -tulpn查 80/8080 是否已被占用。

问题：某份文档解析失败，其他文件正常原因：文件本身损坏、加密，或超过大小上限（默认MAX_FILE_SIZE_MB=50）。 解决：file <文件名>确认它是不是真的 PDF，核对大小限制，再看docker compose logs docreader里的具体报错。

问题：系统能打开、文档也传上去了，但一问就提示模型不可用原因：OLLAMA_OPTIONAL=true的设计就是 Ollama 没好也不拦你，所以表面一切正常，实际模型缺席。 解决：确认OLLAMA_BASE_URL可达，ollama list检查模型是否真的拉下来了，Ollama 侧有报错就看它的日志。

上线前顺手做几件事

• 端口收口：默认只对宿主机暴露前端 80 和后端 8080，其他服务的端口能不映射就不映射；
• 账号收口：人员都建好后，把DISABLE_REGISTRATION设为true，关掉注册入口；数据库密码换成强密码，.env文件权限收严，且永远不要提交进版本库；
• 数据收口：文件目录放在卷里，宿主机目录权限设成 700；多用户使用时靠租户（空间）划分数据边界，天然隔离；
• 备份收口：每天定时导出数据库并归档文件目录，脚本可以很短——

docker compose exec -T postgres pg_dump -U <用户名> <库名> > backup_$(date +%Y%m%d).sql tar -czf files_$(date +%Y%m%d).tar.gz /path/to/data-files

用户名和库名以.env里的实际值为准。

最后：接下来还能做什么

到这里，一台无外网的服务器上已经跑起了完整的文档问答系统：解析、检索、推理全部本地完成，数据不出机房。如果之后想再进一步，方向有三个：给模型推理加 GPU 加速把延迟再压一半、把大模型量化成更小规格以适配低内存机器、以及把多实例拆开做分布式扩展。更多细节可以查 config/config.yaml 的完整配置、config/builtin_models.yaml.example 的内置模型声明模板，以及 docs/QA.md 的常见问题文档。

【免费下载链接】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