一、文档概述

本文基于 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...。

GitHub：https://github.com/Tencent/WeKnora

✨核心能力

1. RAG 快速问答 PDF/Word/Excel/ 图片 / OCR 扫描件，自动解析布局、分块、向量化；混合检索：BM25 关键词 + 向量检索 + 重排，降低幻觉。
2. ReAct Agent 智能代理 支持 MCP 协议，可调用工具、网页搜索、复杂多步推理；内置数据分析 Agent，直接解析 CSV/Excel。
3. Wiki 模式 AI 自动把原始文档提炼成可编辑、带版本回退的 Markdown 知识库，附带交互式知识图谱 GraphRAG。
4. 企业能力 多租户 / 多工作空间、RBAC 权限、审计日志；对接飞书、Notion、语雀；可嵌入网页、对接企微 / 飞书机器人；Langfuse 可观测追踪。

二、完整从零部署流程（Windows Docker 官方标准部署步骤）

完整部署流程，为纯零基础可复刻操作，从环境准备到最终启动，全程无需改代码，仅依赖 Docker Compose 完成 WeKnora+Ollama 整套 RAG 知识库部署。

2.1 前置环境准备

1. 系统要求：Windows10/11 专业版/家庭版（支持 WSL2）

2. 已安装 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 & Restart，Docker 会自动重启。

验证是否生效

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 .

# 查看目录，确认代码全部下载完成
dir

2. 自动生成部署所需核心配置文件（官方模板）： - docker-compose.yml（仓库自带） - .env 环境变量文件（手动复制模板生成） - config/config.yaml 核心业务配置

# 复制环境变量模板生成可用.env
cp .env.example .env

# 复制核心配置模板
cp config/config.yaml.example config/config.yaml

2. 在目录中放置核心文件： - 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_USER=weknora
DB_PASSWORD=weknora123
DB_NAME=weknora_db

# ========== 端口修复（解决Windows 8081权限报错） ==========
APP_PORT=9091

# ========== Redis 无密码（彻底解决Redis崩溃） ==========
REDIS_PASSWORD=

# ========== Ollama 本地模型穿透（容器访问宿主机11434） ==========
OLLAMA_BASE_URL=http://host.docker.internal:11434

# ========== 基础运行配置 ==========
GIN_MODE=release
TZ=Asia/Shanghai
MAX_FILE_SIZE_MB=50
AUTO_MIGRATE=true

# Langfuse 关闭（本地部署不需要）
LANGFUSE_ENABLED=false

2.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) 再访问网页。

三、部署核心报错 & 逐坑修复（核心重点）

坑1：Docker 端口绑定权限报错（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）

坑2：WeKnora-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 即可恢复正常。

坑3：Docker 内网服务域名解析超时/不存在

报错表现

app 容器无法解析 redis、postgres、docreader 等内部服务名，间歇性超时、no such host。

根因

WSL2 网络 DNS 不稳定 + 容器异常重启导致网络记录错乱，多服务依赖启动顺序紊乱。

解决方案

1. 所有服务统一挂载自定义网桥网络 WeKnora-network，保证容器内网互通； 2. 严格配置 depends_on 依赖顺序，等待前置服务启动/健康后再启动主服务； 3. 电脑重启后执行 wsl --shutdown 重置 WSL 网络，修复 DNS 异常。

坑4：Ollama 跨容器访问失败

问题表现

WeKnora 容器无法连接本地 Ollama，网页解析模型超时，网页解析失败。

解决方案

1. 环境变量配置固定宿主机访问地址：OLLAMA_BASE_URL=http://host.docker.internal:11434； 2. 开启 Ollama 局域网访问权限； 3. 容器配置 extra_hosts: - "host.docker.internal:host-gateway"，保证容器可穿透访问宿主机服务。

四、电脑重启后标准化运维命令（必存）

Windows 重启后 Docker 容器不会自动恢复，需执行固定命令一键拉起整套服务，无需重新部署。

1. 重置 WSL 网络（解决 DNS/网络异常）

wsl --shutdown

2. 进入项目部署目录

cd C:\Users\Administrator\Desktop\ai_projects\WeKnora

3. 后台拉起全部服务

docker-compose up -d

4. 查看容器运行状态（校验是否正常）

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 知识库服务部署、启动、连通完全正常，可正常创建知识库、上传文档、问答对话。

六、全局避坑总结（本地部署核心准则）

1. 端口避坑：Windows 禁止使用 80xx、50xx 系统预留端口，统一使用 9000+ 高位端口，彻底规避权限绑定报错。

2. Redis 必避坑：本地开发环境不要配置 Redis 密码，空密码会直接导致容器崩溃、主服务启动失败，是最隐蔽的核心卡点。

3. 网络 DNS 修复：重启电脑必执行 wsl --shutdown 重置 WSL 网络，解决容器内网域名解析超时问题。

4. 服务依赖顺序：严格遵循 redis（启动）→ postgres（健康）→ docreader（健康）→ app 主服务的启动顺序，避免依赖缺失报错。

5. Ollama 连通性：固定使用 host.docker.internal 访问宿主机模型服务，开启 Ollama 局域网权限，保证容器与本地模型互通。

6. 重启运维规范：电脑重启无需重新部署，仅需重置 WSL + 一键 up -d 拉起服务，数据永久保留。

七、补充说明

本次部署全程未修改核心业务逻辑、未删减官方服务组件，仅通过端口优化、Redis 配置修正、网络适配解决 Windows 环境兼容问题，完全保留 WeKnora 原生 RAG 知识库、文档解析、模型对话、向量检索等全部功能，适配个人本地调试、学习测试场景。