一、文档概述本文基于Windows WSL2 Docker Desktop环境完整记录腾讯开源 RAG 知识库框架 WeKnora 的部署全过程。聚焦本地部署高频致命报错端口权限绑定失败、容器 Unhealthy 异常、Redis 启动崩溃、Docker 内网 DNS 解析超时等核心问题提供可直接复制的修复方案、标准化启动命令、重启后运维流程解决 90% 个人本地部署卡点适合零基础开发者参考复用。环境基础Windows 10/11、Docker Desktop 最新版、WSL2 后端、Ollama 本地部署WeKnora维娜拉腾讯开源MIT 协议企业级 RAG 知识库框架Go 后端 Vue 前端主打文档理解、语义检索、Agent、知识图谱完整私有化部署适配 Ollama/Qwen2.5/Qdrant/MinIO非常适合内网私有知识库搭建weknora.on...。GitHubhttps://github.com/Tencent/WeKnora✨核心能力RAG 快速问答PDF/Word/Excel/ 图片 / OCR 扫描件自动解析布局、分块、向量化混合检索BM25 关键词 向量检索 重排降低幻觉。ReAct Agent 智能代理支持 MCP 协议可调用工具、网页搜索、复杂多步推理内置数据分析 Agent直接解析 CSV/Excel。Wiki 模式AI 自动把原始文档提炼成可编辑、带版本回退的 Markdown 知识库附带交互式知识图谱 GraphRAG。企业能力多租户 / 多工作空间、RBAC 权限、审计日志对接飞书、Notion、语雀可嵌入网页、对接企微 / 飞书机器人Langfuse 可观测追踪。二、完整从零部署流程Windows Docker 官方标准部署步骤完整部署流程为纯零基础可复刻操作从环境准备到最终启动全程无需改代码仅依赖 Docker Compose 完成 WeKnoraOllama 整套 RAG 知识库部署。2.1 前置环境准备1. 系统要求Windows10/11 专业版/家庭版支持 WSL22. 已安装Docker Desktop并开启 WSL2 后端Docker Desktop:https://www.docker.com/products/docker-desktop/Windows Docker Desktop 修改镜像源适配 WeKnora 拉镜像WSL2 后端图形界面直接改不要手动找文件JSON 语法错会导致 Docker 启动失败CSDN博...。打开配置右下角托盘 Docker 鲸鱼图标右键 →Settings→ 左侧Docker EngineCSDN博...。完整 JSON 配置直接全选替换原有内容{ builder: { gc: { defaultKeepStorage: 20GB, enabled: true } }, experimental: false, registry-mirrors: [ https://docker.xuanyuan.me, https://docker.1ms.run, https://docker.m.daocloud.io ], log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } }多个镜像源一个挂掉自动切下一个适合拉 weknora、minio、paradedb 大镜像博客园。保存重启点击右下角Apply RestartDocker 会自动重启。验证是否生效PowerShell 执行docker info往下找到Registry Mirrors能看到上面填的地址代表配置成功。3. 本地已安装并启动Ollama用于本地大模型/Embedding 向量化4. 网络正常可拉取 Docker 官方镜像2.2 项目文件准备1. 新建空目录、拉取官方完整源码关键补齐所有人卡在这里# 新建部署文件夹 mkdir WeKnora cd WeKnora # 【核心】克隆腾讯官方完整仓库第一次部署必执行 git clone https://github.com/Tencent/WeKnora.git . # 查看目录确认代码全部下载完成 dir2. 自动生成部署所需核心配置文件官方模板 -docker-compose.yml仓库自带 -.env环境变量文件手动复制模板生成 -config/config.yaml核心业务配置# 复制环境变量模板生成可用.env cp .env.example .env # 复制核心配置模板 cp config/config.yaml.example config/config.yaml2. 在目录中放置核心文件 -docker-compose.yml完整官方配置已适配 Windows 兼容 -.env环境变量配置文件自定义数据库、端口、密钥等 - 官方 config 配置目录、skills 技能目录默认自带即可2.3 关键前置配置部署必做1修改端口规避 Windows 系统预留端口将 APP 主机端口由默认 8081 改为 9091避免端口绑定权限报错对应前文坑1。2修改 Redis 配置关闭空密码校验删除 Redis 启动命令中的密码参数避免 Redis 启动崩溃对应前文坑2。3配置 Ollama 宿主机穿透app 服务写入宿主机 Ollama 地址并开启 extra_hosts 穿透保证容器可以访问本地 11434 模型服务。4手动修改 .env 文件必做否则启动失败用记事本打开目录下.env清空原有内容粘贴下面可直接运行的最简配置适配Windows、无密码、端口修复、Ollama穿透# 数据库基础配置必填 DB_USERweknora DB_PASSWORDweknora123 DB_NAMEweknora_db # 端口修复解决Windows 8081权限报错 APP_PORT9091 # Redis 无密码彻底解决Redis崩溃 REDIS_PASSWORD # Ollama 本地模型穿透容器访问宿主机11434 OLLAMA_BASE_URLhttp://host.docker.internal:11434 # 基础运行配置 GIN_MODErelease TZAsia/Shanghai MAX_FILE_SIZE_MB50 AUTO_MIGRATEtrue # Langfuse 关闭本地部署不需要 LANGFUSE_ENABLEDfalse2.4 首次部署启动命令在项目根目录执行全套标准部署命令第一次部署完整流程包含拉镜像、初始化、启动# 1. 拉取官方全部镜像首次部署必须执行约7G docker-compose pull # 2. 后台启动全套服务前端、后端、数据库、redis、文档解析 docker-compose up -d执行后 Docker 会自动依次拉取、启动前端、主程序、数据库、Redis、文档解析、向量库等全套依赖服务自动执行数据库迁移无需手动干预。2.5 首次启动健康检查# 查看所有容器状态 docker-compose ps # 实时观察启动日志等待所有服务 healthy docker-compose logs -f首次启动耗时 5–15 分钟需等待app、docreader、postgres、redis全部变为 Up (healthy) 再访问网页。三、部署核心报错 逐坑修复核心重点坑1Docker 端口绑定权限报错8081 端口无法监听完整报错信息Error response from daemon: ports are not available: exposing port TCP 0.0.0.0:8081 - 127.0.0.1:0: listen tcp 0.0.0.0:8081: bind: An attempt was made to access a socket in a way forbidden by its access permissions.报错根因Windows 系统存在预留动态端口段机制8080-8089、5000-5009 等常用端口被系统内核预留无进程占用也无法被 Docker 绑定监听并非端口被程序占用是 Windows 权限限制导致。解决方案优先最简方案修改 docker-compose.yml 动态端口变量避开系统预留端口仅修改主机对外端口容器内部端口保持不变原配置报错配置ports: - ${APP_PORT:-8081}:8080修复后配置稳定可用ports: - ${APP_PORT:-9091}:8080端口避坑规则永久适用Windows Docker 禁止使用8080、8081、8082、5000、5001 优先安全端口段9000-60000推荐 9091、9191、9292坑2WeKnora-app 容器 Unhealthy 启动失败完整报错信息dependency failed to start: container WeKnora-app is unhealthy panic: 连接Redis失败: dial tcp: lookup redis: i/o timeout / no such host报错根因Redis 容器启动参数携带空密码导致 Redis 启动崩溃、反复重启Docker 内网 DNS 无法稳定解析redis服务域名最终 WeKnora 主服务初始化 Redis 客户端失败直接 panic 退出触发依赖健康检查失败。致命诱因docker-compose.yml 中 Redis 配置开启密码校验但本地 .env 文件REDIS_PASSWORD为空Redis 7.0 不允许空字符串密码直接启动失败。最终修复方案本地部署最优解修改 Redis 服务配置本地开发关闭密码校验彻底规避空密码报错原错误配置redis: image: redis:7.0-alpine command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}修复后可用配置redis: image: redis:7.0-alpine container_name: WeKnora-redis command: redis-server --appendonly yes restart: always networks: - WeKnora-network配套操作执行docker-compose down清理异常容器重新docker-compose up -d即可恢复正常。坑3Docker 内网服务域名解析超时/不存在报错表现app 容器无法解析redis、postgres、docreader等内部服务名间歇性超时、no such host。根因WSL2 网络 DNS 不稳定 容器异常重启导致网络记录错乱多服务依赖启动顺序紊乱。解决方案1. 所有服务统一挂载自定义网桥网络WeKnora-network保证容器内网互通 2. 严格配置 depends_on 依赖顺序等待前置服务启动/健康后再启动主服务 3. 电脑重启后执行wsl --shutdown重置 WSL 网络修复 DNS 异常。坑4Ollama 跨容器访问失败问题表现WeKnora 容器无法连接本地 Ollama网页解析模型超时网页解析失败。解决方案1. 环境变量配置固定宿主机访问地址OLLAMA_BASE_URLhttp://host.docker.internal:11434 2. 开启 Ollama 局域网访问权限 3. 容器配置extra_hosts: - host.docker.internal:host-gateway保证容器可穿透访问宿主机服务。四、电脑重启后标准化运维命令必存Windows 重启后 Docker 容器不会自动恢复需执行固定命令一键拉起整套服务无需重新部署。1. 重置 WSL 网络解决 DNS/网络异常wsl --shutdown2. 进入项目部署目录cd C:\Users\Administrator\Desktop\ai_projects\WeKnora3. 后台拉起全部服务docker-compose up -d4. 查看容器运行状态校验是否正常docker-compose ps正常状态所有服务显示Up (healthy)5. 异常排查日志命令# 查看主服务日志 docker-compose logs -f app # 查看 Redis 日志 docker logs WeKnora-redis # 全局实时日志 docker-compose logs -f五、最终正常访问地址 访问报错说明✅ WeKnora 前端网页地址http://127.0.0.1:9091✅ 本地 Ollama 校验地址http://127.0.0.1:11434访问报错说明对应实测解析失败问题1.http://127.0.0.1:9091 提示URL错误原因容器未完全启动、健康检查未通过、前端 Nginx 未就绪 解决等待 2–3 分钟确认docker-compose ps全部 healthy 后刷新或重启服务docker-compose restart frontend。2.http://127.0.0.1:11434 / host.docker.internal:11434 网页解析失败原因Ollama 接口为纯API服务无网页页面浏览器访问会直接报解析错误属于正常现象 校验方式不要用浏览器使用命令行校验 Ollama 连通性curl http://127.0.0.1:11434/api/tags返回 JSON 模型列表即代表 Ollama 完全正常可被 WeKnora 正常调用。访问即代表整套 RAG 知识库服务部署、启动、连通完全正常可正常创建知识库、上传文档、问答对话。六、全局避坑总结本地部署核心准则端口避坑Windows 禁止使用 80xx、50xx 系统预留端口统一使用 9000 高位端口彻底规避权限绑定报错。Redis 必避坑本地开发环境不要配置 Redis 密码空密码会直接导致容器崩溃、主服务启动失败是最隐蔽的核心卡点。网络 DNS 修复重启电脑必执行wsl --shutdown重置 WSL 网络解决容器内网域名解析超时问题。服务依赖顺序严格遵循 redis启动→ postgres健康→ docreader健康→ app 主服务的启动顺序避免依赖缺失报错。Ollama 连通性固定使用host.docker.internal访问宿主机模型服务开启 Ollama 局域网权限保证容器与本地模型互通。重启运维规范电脑重启无需重新部署仅需重置 WSL 一键 up -d 拉起服务数据永久保留。七、补充说明本次部署全程未修改核心业务逻辑、未删减官方服务组件仅通过端口优化、Redis 配置修正、网络适配解决 Windows 环境兼容问题完全保留 WeKnora 原生 RAG 知识库、文档解析、模型对话、向量检索等全部功能适配个人本地调试、学习测试场景。