WeKnora 离线部署实战内网机器从零到 RAG 问答的 4 步路径【免费下载链接】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/WeKnoraWeKnora 是一个开源 RAG 知识平台把上传的文档解析、分块、向量化后入库再基于向量检索做问答和 Agent 推理。本文记录如何在一台完全不通公网的内网机器上把它跑起来——从容器编排、环境变量、离线镜像搬运到启动后的健康验证以及我实际卡住的 3 个坑。 先看清 compose 里到底有什么结论先行核心链路只有 5 个常驻容器Ollama 不在其中。很多人第一次上手就卡在这——以为模型服务会在docker compose ps里出现其实它跑在宿主机上。看 docker-compose.yml默认 profile 下的常驻服务是这几个服务职责健康检查说明frontendNginx前端页面 反代 API无宿主机 80 端口appGo 后端业务与调度中枢GET /health宿主机 8080 端口docreader文档解析gRPCgrpc_health_probe仅容器内网可达50051 不对宿主暴露postgres元数据 向量检索ParadeDB 镜像自带 pgvector 系能力pg_isready默认 profile 就起无需额外开关redis任务队列Asynq与流处理无队列不落地内存重启会丢MinIO、Neo4j、Qdrant、Milvus 这些都在profiles后面--profile minio之类才拉起默认不占资源。内网单机部署建议保持默认文件存储走STORAGE_TYPElocal向量检索走RETRIEVE_DRIVERpostgres一个数据库把元数据和向量都装了省一个容器。 如果你的机器只有 4 核 8G 还觉得重可以先用 Lite 模式单应用 SQLite 内存队列零外部依赖代价是没有共享空间和完整解析引擎矩阵详见 docs/LITE.md。 .env 三处必改改错就起不来cp .env.example .env之后90% 的启动失败都出在下面三个变量。模板在 .env.example注释很全这里只说踩坑点。cp .env.example .env这条命令复制环境变量模板之后所有改动都在.env里做别直接改 compose 文件。# 数据库三件套app 启动就等它 DB_USERpostgres DB_PASSWORD你的强密码 DB_NAMEWeKnora # 文件落地本地卷内网部署别用对象存储 STORAGE_TYPElocal # app 容器访问宿主机 Ollama 的地址 OLLAMA_BASE_URLhttp://host.docker.internal:11434逐个说为什么DB_PASSWORDcompose 里 postgres 容器用${DB_PASSWORD}初始化POSTGRES_PASSWORD。你留空或者改完密码不重建容器app 会反复连库失败日志里全是 connection refused。改密码必须docker compose down后重建数据卷里已经初始化过的旧密码不会跟着变。STORAGE_TYPElocal默认值就是local但如果你从云上模板抄来的.env带着minio而 minio profile 又没起上传文档会直接报存储不可用。内网场景保持local最省事文件落在data-files卷里。OLLAMA_BASE_URL这是最容易错的一个。Ollama 装在宿主机app 跑在容器里容器内不能写127.0.0.1那是容器自己的回环。compose 里给 app 配了extra_hosts: host.docker.internal:host-gateway所以必须写http://host.docker.internal:11434。⚠️OLLAMA_OPTIONALtrue是默认值意思是 Ollama 连不上只告警不阻断。这个温柔会让你在界面上配模型时才发现地址没配对排查反而绕路。内网部署建议把验证做到位见下一节。改完配置用项目自带的检查脚本过一遍./scripts/check-env.sh它会逐项核对.env是否存在、DB_*/STORAGE_TYPE/REDIS_ADDR/OLLAMA_BASE_URL是否非空以及 Docker 和 Compose 是否可用缺什么报什么。 离线搬运镜像和模型要带网机预拉真正的离线部署卡点不在 WeKnora 本身而在镜像和模型文件怎么进内网。分两条流水线走Docker 镜像侧。带网机上拉取核心 5 个镜像 沙箱镜像Agent Skills 依赖可选然后导出# 带网机执行 docker compose pull docker save -o weknora-images.tar \ wechatopenai/weknora-ui:latest \ wechatopenai/weknora-app:latest \ wechatopenai/weknora-docreader:latest \ paradedb/paradedb:v0.22.2-pg17 \ redis:7.0-alpine内网机上导入后启动注意--no-pull否则 compose 会尝试联网拉镜像直接失败# 内网机执行 docker load -i weknora-images.tar ./scripts/start_all.sh --no-pullstart_all.sh 的--no-pull参数会让启动走本地镜像不触发任何网络请求不带网内网机第一次跑时它会顺手把缺失的.env从模板补出来省一步。Ollama 模型侧。带网机把模型拉下来打包内网机导入# 带网机 ollama pull qwen2.5:7b # 对话模型 ollama pull bge-m3 # 嵌入模型 ollama pull qwen2.5:7b qwen2.5.tar ollama pull bge-m3 bge-m3.tar # 内网机 ollama create qwen2.5:7b -f qwen2.5.tar # 或直接 docker import 到 Ollama 卷 内网机的 Ollama 不用走start_all.sh的自动安装它默认会从官网下安装脚本内网必挂。把带网机上 Ollama 的程序包和/usr/share/ollama/.ollama/models整个目录拷过来即可模型目录拷完 Ollama 重启后自动识别。⚠️ 模型选型直接影响能不能跑7B 对话模型 CPU 推理时 16GB 内存比较稳嵌入模型选bge-m3这种 1GB 级别的就行别一上来就拉 13B 以上。 起来了之后先看什么按依赖顺序验证别直接开浏览器。三步1. 容器状态docker compose ps看app是否healthy它配了 60 秒start_period首次启动等满 1 分钟再下结论docreader同理。2. 后端健康检查curl -f http://localhost:8080/health这是 compose 里 app 健康检查用的同一个端点通了说明后端起来了。3. 全链路冒烟浏览器开http://localhost注册账号 → 在模型设置里添加 Ollama 的对话模型和嵌入模型 → 新建知识库 → 传一份 PDF → 等解析完成 → 提问验证引用来源。解析和问答都走通了离线闭环才算成立。三个高频故障现象 → 原因 → 解法app 一直starting进不了healthy原因九成是连不上 postgres密码没配对见上节小概率是DB_NAME里的大小写和初始化时对不上。解法docker compose logs app | grep -i connect对照日志里的报错改.env然后docker compose up -d app。上传文档后卡在 processing 不动原因docreader 和 app 之间的 gRPC 断了或文件超过MAX_FILE_SIZE_MB默认 50MBGo / Nginx / docreader / 浏览器四层都会拦。解法docker compose logs docreader看有没有收到请求没收到就检查DOCREADER_ADDRdocreader:50051是否被改过收到了就是解析报错日志里有明确异常。模型列表是空的或者问答超时原因app 容器里host.docker.internal解析不到或 Ollama 没把模型加载起来7B 冷加载本身要 30 秒以上第一次超时不代表坏了。解法docker compose exec app curl -s http://host.docker.internal:11434/api/tags验证连通性通了就把 Agent 的 LLM 超时从默认 120 秒调大。收尾动作跑稳之后先做备份postgres-data和data-files两个卷就是全部家底。docker compose exec -T postgres pg_dump -U $DB_USER $DB_NAME backup.sql再把data-files卷里的目录 tar 一份。离线环境没有重装一下这个选项备份是唯一保险。后续想提性能优先动两个旋钮WEKNORA_ASYNQ_CORE_CONCURRENCY解析并发和 Ollama 的模型量化档位比加容器更见效。关键文件docker-compose.yml · scripts/start_all.sh · .env.example【免费下载链接】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 离线部署实战：内网机器从零到 RAG 问答的 4 步路径
WeKnora 离线部署实战内网机器从零到 RAG 问答的 4 步路径【免费下载链接】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/WeKnoraWeKnora 是一个开源 RAG 知识平台把上传的文档解析、分块、向量化后入库再基于向量检索做问答和 Agent 推理。本文记录如何在一台完全不通公网的内网机器上把它跑起来——从容器编排、环境变量、离线镜像搬运到启动后的健康验证以及我实际卡住的 3 个坑。 先看清 compose 里到底有什么结论先行核心链路只有 5 个常驻容器Ollama 不在其中。很多人第一次上手就卡在这——以为模型服务会在docker compose ps里出现其实它跑在宿主机上。看 docker-compose.yml默认 profile 下的常驻服务是这几个服务职责健康检查说明frontendNginx前端页面 反代 API无宿主机 80 端口appGo 后端业务与调度中枢GET /health宿主机 8080 端口docreader文档解析gRPCgrpc_health_probe仅容器内网可达50051 不对宿主暴露postgres元数据 向量检索ParadeDB 镜像自带 pgvector 系能力pg_isready默认 profile 就起无需额外开关redis任务队列Asynq与流处理无队列不落地内存重启会丢MinIO、Neo4j、Qdrant、Milvus 这些都在profiles后面--profile minio之类才拉起默认不占资源。内网单机部署建议保持默认文件存储走STORAGE_TYPElocal向量检索走RETRIEVE_DRIVERpostgres一个数据库把元数据和向量都装了省一个容器。 如果你的机器只有 4 核 8G 还觉得重可以先用 Lite 模式单应用 SQLite 内存队列零外部依赖代价是没有共享空间和完整解析引擎矩阵详见 docs/LITE.md。 .env 三处必改改错就起不来cp .env.example .env之后90% 的启动失败都出在下面三个变量。模板在 .env.example注释很全这里只说踩坑点。cp .env.example .env这条命令复制环境变量模板之后所有改动都在.env里做别直接改 compose 文件。# 数据库三件套app 启动就等它 DB_USERpostgres DB_PASSWORD你的强密码 DB_NAMEWeKnora # 文件落地本地卷内网部署别用对象存储 STORAGE_TYPElocal # app 容器访问宿主机 Ollama 的地址 OLLAMA_BASE_URLhttp://host.docker.internal:11434逐个说为什么DB_PASSWORDcompose 里 postgres 容器用${DB_PASSWORD}初始化POSTGRES_PASSWORD。你留空或者改完密码不重建容器app 会反复连库失败日志里全是 connection refused。改密码必须docker compose down后重建数据卷里已经初始化过的旧密码不会跟着变。STORAGE_TYPElocal默认值就是local但如果你从云上模板抄来的.env带着minio而 minio profile 又没起上传文档会直接报存储不可用。内网场景保持local最省事文件落在data-files卷里。OLLAMA_BASE_URL这是最容易错的一个。Ollama 装在宿主机app 跑在容器里容器内不能写127.0.0.1那是容器自己的回环。compose 里给 app 配了extra_hosts: host.docker.internal:host-gateway所以必须写http://host.docker.internal:11434。⚠️OLLAMA_OPTIONALtrue是默认值意思是 Ollama 连不上只告警不阻断。这个温柔会让你在界面上配模型时才发现地址没配对排查反而绕路。内网部署建议把验证做到位见下一节。改完配置用项目自带的检查脚本过一遍./scripts/check-env.sh它会逐项核对.env是否存在、DB_*/STORAGE_TYPE/REDIS_ADDR/OLLAMA_BASE_URL是否非空以及 Docker 和 Compose 是否可用缺什么报什么。 离线搬运镜像和模型要带网机预拉真正的离线部署卡点不在 WeKnora 本身而在镜像和模型文件怎么进内网。分两条流水线走Docker 镜像侧。带网机上拉取核心 5 个镜像 沙箱镜像Agent Skills 依赖可选然后导出# 带网机执行 docker compose pull docker save -o weknora-images.tar \ wechatopenai/weknora-ui:latest \ wechatopenai/weknora-app:latest \ wechatopenai/weknora-docreader:latest \ paradedb/paradedb:v0.22.2-pg17 \ redis:7.0-alpine内网机上导入后启动注意--no-pull否则 compose 会尝试联网拉镜像直接失败# 内网机执行 docker load -i weknora-images.tar ./scripts/start_all.sh --no-pullstart_all.sh 的--no-pull参数会让启动走本地镜像不触发任何网络请求不带网内网机第一次跑时它会顺手把缺失的.env从模板补出来省一步。Ollama 模型侧。带网机把模型拉下来打包内网机导入# 带网机 ollama pull qwen2.5:7b # 对话模型 ollama pull bge-m3 # 嵌入模型 ollama pull qwen2.5:7b qwen2.5.tar ollama pull bge-m3 bge-m3.tar # 内网机 ollama create qwen2.5:7b -f qwen2.5.tar # 或直接 docker import 到 Ollama 卷 内网机的 Ollama 不用走start_all.sh的自动安装它默认会从官网下安装脚本内网必挂。把带网机上 Ollama 的程序包和/usr/share/ollama/.ollama/models整个目录拷过来即可模型目录拷完 Ollama 重启后自动识别。⚠️ 模型选型直接影响能不能跑7B 对话模型 CPU 推理时 16GB 内存比较稳嵌入模型选bge-m3这种 1GB 级别的就行别一上来就拉 13B 以上。 起来了之后先看什么按依赖顺序验证别直接开浏览器。三步1. 容器状态docker compose ps看app是否healthy它配了 60 秒start_period首次启动等满 1 分钟再下结论docreader同理。2. 后端健康检查curl -f http://localhost:8080/health这是 compose 里 app 健康检查用的同一个端点通了说明后端起来了。3. 全链路冒烟浏览器开http://localhost注册账号 → 在模型设置里添加 Ollama 的对话模型和嵌入模型 → 新建知识库 → 传一份 PDF → 等解析完成 → 提问验证引用来源。解析和问答都走通了离线闭环才算成立。三个高频故障现象 → 原因 → 解法app 一直starting进不了healthy原因九成是连不上 postgres密码没配对见上节小概率是DB_NAME里的大小写和初始化时对不上。解法docker compose logs app | grep -i connect对照日志里的报错改.env然后docker compose up -d app。上传文档后卡在 processing 不动原因docreader 和 app 之间的 gRPC 断了或文件超过MAX_FILE_SIZE_MB默认 50MBGo / Nginx / docreader / 浏览器四层都会拦。解法docker compose logs docreader看有没有收到请求没收到就检查DOCREADER_ADDRdocreader:50051是否被改过收到了就是解析报错日志里有明确异常。模型列表是空的或者问答超时原因app 容器里host.docker.internal解析不到或 Ollama 没把模型加载起来7B 冷加载本身要 30 秒以上第一次超时不代表坏了。解法docker compose exec app curl -s http://host.docker.internal:11434/api/tags验证连通性通了就把 Agent 的 LLM 超时从默认 120 秒调大。收尾动作跑稳之后先做备份postgres-data和data-files两个卷就是全部家底。docker compose exec -T postgres pg_dump -U $DB_USER $DB_NAME backup.sql再把data-files卷里的目录 tar 一份。离线环境没有重装一下这个选项备份是唯一保险。后续想提性能优先动两个旋钮WEKNORA_ASYNQ_CORE_CONCURRENCY解析并发和 Ollama 的模型量化档位比加容器更见效。关键文件docker-compose.yml · scripts/start_all.sh · .env.example【免费下载链接】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），仅供参考