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 的本地化部署在无外网机器上从零走通镜像与模型怎么预置、容器集群怎么一键拉起、离线配置怎么验证以及慢在哪里怎么调。断网环境还能不能跑先认清离线的真实边界动手之前先回答一个最实际的疑问把网线拔了这套系统到底还依赖什么。WeKnora 的运行链路很短——应用服务、文档解析器、Web 界面、数据库、队列全部以容器形式跑在同一台机器上向量索引不是独立组件而是直接建在 PostgreSQL 的向量扩展里官方镜像用的 ParadeDB所以不需要再单独部署向量数据库。真正伸到容器外的依赖只剩一个模型服务 Ollama。大模型推理和文本向量化都交给它它跑在宿主机上通过host.docker.internal:11434被容器访问。理解这一点离线部署的准备工作就只剩两件事——镜像包和模型权重都需要在有网的机器上提前备好。机器档位建议按下面这张表来核心逻辑是7B 级模型的推理和内存占用是大头解析和检索反而是轻活。资源最低配置推荐配置说明CPU8 核16 核推理吃核心内存32GB64GB留给 Ollama 的余量磁盘200GB SSD500GB镜像向量数据增长拉代码之后用自带的启动脚本做环境自检它会替你核对 Docker、Compose、.env里的必填项和磁盘内存水位git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora然后在项目根目录执行自检./scripts/start_all.sh --check做完你应该看到Docker 环境检查通过、.env必填项无缺失、CPU 与内存输出正常。此刻你的终端应该显示一连串[INFO]和绿色[SUCCESS]没有红色[ERROR]。如果有缺项它会直接告诉你是哪个变量没配。一键拉起容器集群前先改哪几个配置项环境没问题了接下来是部署中最容易翻车的一段配置。仓库里带了.env.example模板复制一份再改只动这几个关键点cp .env.example .env需要动的就是下面这几行数据库密码必须改掉文件存储用本地目录Ollama 地址保持指向宿主机# ……其余保持默认…… DB_PASSWORD改成你自己的强密码 STORAGE_TYPElocal OLLAMA_BASE_URLhttp://host.docker.internal:11434⚠️ 这里的 Ollama 是宿主机服务不是容器。离线机器上要先装好 Ollama 并保证ollama serve在跑否则容器起来也是能启动、不能答。模型权重在有网机器上拉好再搬过来嵌入和对话模型各备一个尺寸按内存选ollama pull bge-m3 # 嵌入模型 ollama pull 7B级对话模型 # 按内存余量选规格搬模型可以走ollama save导出 tar 包离线机器上ollama load导入容器镜像同理联网机上docker compose pull后docker save打包离线机上docker load解包随后启动时加--no-pull跳过联网拉取。整条链路的分工可以先在脑子里过一遍排障时按图索骥容器职责app主服务API、任务编排、检索docreader文档解析PDF/Office 等frontendWeb 界面Nginx 反代到 apppostgres元数据 向量索引ParadeDBredis任务队列与流式输出配置就绪后一条命令拉起全部服务./scripts/start_all.sh --no-pull脚本会先确认 Ollama 活着再执行docker compose up最后打印前端和 API 的访问地址默认http://localhost。确认状态用docker compose ps此刻你的终端应该显示app、postgres、frontend、docreader 四行全是Up (healthy)如果某一行是Restarting别往下走先看下一章开头的日志命令。文档丢进系统后数据走了哪几步服务绿了不等于部署成了得让一份真实文档走完整个闭环。先理解数据路径验证时才知道每一步该盯什么上传的文档先进 docreader 容器做解析扫描件会走 OCR 渲染产出结构化文本后由 app 侧智能分块每块调用 Ollama 的嵌入模型转成向量连同原文一起写进 ParadeDB问答时则反着来——查询向量化后做混合检索召回的片段交给对话模型生成答案。浏览器打开首页第一次访问会进入初始化向导完成账号与基础信息设置然后按这个顺序验收每步都有明确的对了的信号新建知识库选一个绑定本地 Ollama 嵌入模型的配置上传一份带目录的 PDF 或 Word列表状态从 processing 变成 completed——卡在 processing 超过几分钟就去看docker compose logs docreader发起问答问文档主要讲了什么答案应能引用到具体段落。此刻你的浏览器应该显示一条带引用来源的回答且引用能点开定位到原文。如果界面能进但问答无响应十有八九是 Ollama 没连通用curl http://localhost:11434/api/tags验证一下。跑起来之后慢在哪里就调哪里上线后最常见的抱怨是慢但慢的环节完全不同别盲目加资源。按下面的对照表定位症状先查什么调哪里文档排队解析Asynq 核心并发是否过低.env的WEKNORA_ASYNQ_CORE_CONCURRENCY默认 8上传大批文档内存吃紧嵌入批大小.env的BATCH_EMBED_SIZE调小问答首字延迟高模型规格是否超配换更小量化模型检索结果太多太杂召回数量config/config.yaml中 top_k 调小改.env里的变量后需要docker compose up -d app让容器重新读取改config/config.yaml同理重启 app。⚠️ 一个隐性开关值得点名OLLAMA_OPTIONALtrue是默认值Ollama 挂掉时系统只告警不阻断。表现就是服务全绿、问答哑火这是离线环境最典型的假正常。排障时按这个路径走基本能覆盖 90% 的问题故障现象第一步命令容器反复重启看应用日志docker compose logs app解析失败看解析器日志docker compose logs docreader问答无响应验 Ollama 连通curl -s http://localhost:11434/api/tags健康检查不通过直接探活curl http://localhost:8080/health此刻你的终端应该显示健康检查返回 200日志里没有持续刷新的 error 行。这些坑翻车前都值得看一眼最后把最容易踩的坑和安全清单放在一起部署收尾前逐条过⚠️ 密码别用模板默认值.env.example里的数据库和 Redis 密码只是占位内网环境也不例外这是备份和交接时的第一个雷。⚠️SYSTEM_AES_KEY必须是 32 字节且妥善保管。它负责加密落盘的 API Key 等敏感字段丢了就意味着所有已加密字段永久无法解密UI 上只会显示为空。⚠️ 端口暴露做减法默认部署下 MinIO、Neo4j、Qdrant 等都是 profile 可选组件不开就不开开了也注意别让 9000/9001 这类管理端口漏到公网。生产收尾清单数据库、Redis 密码已更换并记录到密码本SYSTEM_AES_KEY已生成32 字节并离线备份DISABLE_REGISTRATIONtrue禁止自助注册GIN_MODErelease关闭调试信息已验证 Ollama 断连时的告警能看到postgres-data、data-files卷已纳入定时备份如果场景只是个人或小团队本机试用、完全不需要多服务编排可以看 Lite 模式——单应用零依赖数据全部落在本地文档在docs/LITE.md。这套方案解决的是无外网环境下文档到问答的完整闭环不解决模型微调和多机水平扩展——那属于另一篇故事的范畴。下一步建议先用最小配置跑通本文的验证流程再按第四章的对照表逐项调优。更多细节可参考官方文档README_CN.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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本文面向第一次接触本项目的开发与运维同学把 WeKnora 的本地化部署在无外网机器上从零走通镜像与模型怎么预置、容器集群怎么一键拉起、离线配置怎么验证以及慢在哪里怎么调。断网环境还能不能跑先认清离线的真实边界动手之前先回答一个最实际的疑问把网线拔了这套系统到底还依赖什么。WeKnora 的运行链路很短——应用服务、文档解析器、Web 界面、数据库、队列全部以容器形式跑在同一台机器上向量索引不是独立组件而是直接建在 PostgreSQL 的向量扩展里官方镜像用的 ParadeDB所以不需要再单独部署向量数据库。真正伸到容器外的依赖只剩一个模型服务 Ollama。大模型推理和文本向量化都交给它它跑在宿主机上通过host.docker.internal:11434被容器访问。理解这一点离线部署的准备工作就只剩两件事——镜像包和模型权重都需要在有网的机器上提前备好。机器档位建议按下面这张表来核心逻辑是7B 级模型的推理和内存占用是大头解析和检索反而是轻活。资源最低配置推荐配置说明CPU8 核16 核推理吃核心内存32GB64GB留给 Ollama 的余量磁盘200GB SSD500GB镜像向量数据增长拉代码之后用自带的启动脚本做环境自检它会替你核对 Docker、Compose、.env里的必填项和磁盘内存水位git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora然后在项目根目录执行自检./scripts/start_all.sh --check做完你应该看到Docker 环境检查通过、.env必填项无缺失、CPU 与内存输出正常。此刻你的终端应该显示一连串[INFO]和绿色[SUCCESS]没有红色[ERROR]。如果有缺项它会直接告诉你是哪个变量没配。一键拉起容器集群前先改哪几个配置项环境没问题了接下来是部署中最容易翻车的一段配置。仓库里带了.env.example模板复制一份再改只动这几个关键点cp .env.example .env需要动的就是下面这几行数据库密码必须改掉文件存储用本地目录Ollama 地址保持指向宿主机# ……其余保持默认…… DB_PASSWORD改成你自己的强密码 STORAGE_TYPElocal OLLAMA_BASE_URLhttp://host.docker.internal:11434⚠️ 这里的 Ollama 是宿主机服务不是容器。离线机器上要先装好 Ollama 并保证ollama serve在跑否则容器起来也是能启动、不能答。模型权重在有网机器上拉好再搬过来嵌入和对话模型各备一个尺寸按内存选ollama pull bge-m3 # 嵌入模型 ollama pull 7B级对话模型 # 按内存余量选规格搬模型可以走ollama save导出 tar 包离线机器上ollama load导入容器镜像同理联网机上docker compose pull后docker save打包离线机上docker load解包随后启动时加--no-pull跳过联网拉取。整条链路的分工可以先在脑子里过一遍排障时按图索骥容器职责app主服务API、任务编排、检索docreader文档解析PDF/Office 等frontendWeb 界面Nginx 反代到 apppostgres元数据 向量索引ParadeDBredis任务队列与流式输出配置就绪后一条命令拉起全部服务./scripts/start_all.sh --no-pull脚本会先确认 Ollama 活着再执行docker compose up最后打印前端和 API 的访问地址默认http://localhost。确认状态用docker compose ps此刻你的终端应该显示app、postgres、frontend、docreader 四行全是Up (healthy)如果某一行是Restarting别往下走先看下一章开头的日志命令。文档丢进系统后数据走了哪几步服务绿了不等于部署成了得让一份真实文档走完整个闭环。先理解数据路径验证时才知道每一步该盯什么上传的文档先进 docreader 容器做解析扫描件会走 OCR 渲染产出结构化文本后由 app 侧智能分块每块调用 Ollama 的嵌入模型转成向量连同原文一起写进 ParadeDB问答时则反着来——查询向量化后做混合检索召回的片段交给对话模型生成答案。浏览器打开首页第一次访问会进入初始化向导完成账号与基础信息设置然后按这个顺序验收每步都有明确的对了的信号新建知识库选一个绑定本地 Ollama 嵌入模型的配置上传一份带目录的 PDF 或 Word列表状态从 processing 变成 completed——卡在 processing 超过几分钟就去看docker compose logs docreader发起问答问文档主要讲了什么答案应能引用到具体段落。此刻你的浏览器应该显示一条带引用来源的回答且引用能点开定位到原文。如果界面能进但问答无响应十有八九是 Ollama 没连通用curl http://localhost:11434/api/tags验证一下。跑起来之后慢在哪里就调哪里上线后最常见的抱怨是慢但慢的环节完全不同别盲目加资源。按下面的对照表定位症状先查什么调哪里文档排队解析Asynq 核心并发是否过低.env的WEKNORA_ASYNQ_CORE_CONCURRENCY默认 8上传大批文档内存吃紧嵌入批大小.env的BATCH_EMBED_SIZE调小问答首字延迟高模型规格是否超配换更小量化模型检索结果太多太杂召回数量config/config.yaml中 top_k 调小改.env里的变量后需要docker compose up -d app让容器重新读取改config/config.yaml同理重启 app。⚠️ 一个隐性开关值得点名OLLAMA_OPTIONALtrue是默认值Ollama 挂掉时系统只告警不阻断。表现就是服务全绿、问答哑火这是离线环境最典型的假正常。排障时按这个路径走基本能覆盖 90% 的问题故障现象第一步命令容器反复重启看应用日志docker compose logs app解析失败看解析器日志docker compose logs docreader问答无响应验 Ollama 连通curl -s http://localhost:11434/api/tags健康检查不通过直接探活curl http://localhost:8080/health此刻你的终端应该显示健康检查返回 200日志里没有持续刷新的 error 行。这些坑翻车前都值得看一眼最后把最容易踩的坑和安全清单放在一起部署收尾前逐条过⚠️ 密码别用模板默认值.env.example里的数据库和 Redis 密码只是占位内网环境也不例外这是备份和交接时的第一个雷。⚠️SYSTEM_AES_KEY必须是 32 字节且妥善保管。它负责加密落盘的 API Key 等敏感字段丢了就意味着所有已加密字段永久无法解密UI 上只会显示为空。⚠️ 端口暴露做减法默认部署下 MinIO、Neo4j、Qdrant 等都是 profile 可选组件不开就不开开了也注意别让 9000/9001 这类管理端口漏到公网。生产收尾清单数据库、Redis 密码已更换并记录到密码本SYSTEM_AES_KEY已生成32 字节并离线备份DISABLE_REGISTRATIONtrue禁止自助注册GIN_MODErelease关闭调试信息已验证 Ollama 断连时的告警能看到postgres-data、data-files卷已纳入定时备份如果场景只是个人或小团队本机试用、完全不需要多服务编排可以看 Lite 模式——单应用零依赖数据全部落在本地文档在docs/LITE.md。这套方案解决的是无外网环境下文档到问答的完整闭环不解决模型微调和多机水平扩展——那属于另一篇故事的范畴。下一步建议先用最小配置跑通本文的验证流程再按第四章的对照表逐项调优。更多细节可参考官方文档README_CN.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
