一、前言

WeKnora 是腾讯开源的轻量化企业级知识库RAG系统，支持本地私有部署、文档解析、语义检索、大模型问答。常规官方部署方案依赖 Docker Desktop + WSL2，但大量Windows用户会遇到WSL内核损坏、服务启动失败、虚拟化异常、内存溢出等顽固问题。

本文记录一套纯Windows原生、零Docker、零WSL、无需虚拟机的 WeKnora 完整部署方案，搭配本地 Ollama 大模型实现私有化本地知识库，同时汇总全程所有真实踩坑点与终极解决方案，适合低配笔记本、WSL故障、不想折腾容器环境的用户。

适配本机配置：i7-8850H / 16G内存 / MX130 2G（无GPU推理能力，纯CPU运行）

二、整体部署架构

摒弃官方Docker容器化方案，采用轻量化原生架构，最大化降低硬件、系统依赖：

• 大模型服务：Ollama Windows 原生客户端（本地离线运行）

• 知识库系统：WeKnora 源码本地Go编译运行

• 数据库：SQLite 文件数据库（无需安装PostgreSQL）

• 任务队列：内存模式（无需安装Redis）

• 向量检索：内置数据库向量能力（无需Qdrant/Milvus）

• 文件存储：本地磁盘存储（无需MinIO对象存储）

优势：零依赖、零虚拟化、零容器、占用内存极低、普通Windows电脑即可稳定运行。

三、前置环境准备

1. 安装依赖工具

• Go 1.23+：用于编译运行WeKnora源码，安装时勾选自动配置环境变量

• Ollama Windows版：本地离线大模型推理服务

2. 拉取适配本机的大模型

16G内存、纯CPU设备，最优模型组合（稳定不卡顿、无内存溢出）：

ollama pull qwen2.5:7b 
ollama pull nomic-embed-text

模型说明：

• qwen2.5:7b：通用问答大模型，默认Q4量化，适配16G内存CPU推理

• nomic-embed-text：文档向量嵌入模型，用于知识库语义检索

验证Ollama服务正常：浏览器访问 http://127.0.0.1:11434，显示Ollama is running 即为成功。

3. 下载WeKnora源码

从官方Github下载源码压缩包，解压至全英文无空格路径（禁止中文路径）。

四、核心配置文件 .env 适配改造

官方默认.env是Docker容器专用配置，直接使用必报错。针对Windows原生运行，进行全套适配改造，核心修改点如下：

1. 关键改造逻辑

• 容器域名 host.docker.internal / postgres / redis 全部废弃，替换为本地127.0.0.1

• 数据库从PostgreSQL改为SQLite，免安装、零配置

• 队列从Redis改为内存模式，去除中间件依赖

• 密钥严格规范，修复AES密钥长度报错

2. 完整可用.env配置（Windows原生专用）

# WeKnora Windows 原生部署配置（无Docker、无WSL）
# 基础运行配置
WEKNORA_VERSION=latest
GIN_MODE=release
TZ=Asia/Shanghai
AUTO_MIGRATE=true
AUTO_RECOVER_DIRTY=true

# 本地服务地址
APP_HOST=127.0.0.1
APP_PORT=8080
DOCREADER_ADDR=127.0.0.1:50051
DOCREADER_TRANSPORT=grpc

# 轻量化数据库配置（SQLite 无需额外安装）
DB_DRIVER=sqlite
DB_PATH=./weknora.db

# 内存队列，禁用Redis
STREAM_MANAGER_TYPE=memory

# 本地文件存储
STORAGE_TYPE=local
LOCAL_STORAGE_BASE_DIR=./data/files
MAX_FILE_SIZE_MB=50

# Ollama本地模型配置
OLLAMA_OPTIONAL=true
OLLAMA_BASE_URL=http://127.0.0.1:11434
LLM_MODEL=qwen2.5:7b
EMBED_MODEL=nomic-embed-text

# 文档解析参数
DOCREADER_GRPC_MAX_WORKERS=4
DOCREADER_PDF_RENDER_DPI=200
WEKNORA_DOCUMENT_PROCESS_TIMEOUT=2h

# 安全密钥（请勿照搬，可自定义，AES严格32位字符）
JWT_SECRET=wk-local-win-secret-20260820
SYSTEM_AES_KEY=abcdef123456abcdef123456abcdef12

# 账号注册配置
DISABLE_REGISTRATION=false
WEKNORA_AUTH_DEFAULT_TENANT_MODE=create_personal

# 智能体超时
WEKNORA_AGENT_LLM_TIMEOUT=300

# 并发限制
CONCURRENCY_POOL_SIZE=5

五、WeKnora 启动步骤

1. 配置Go代理（解决依赖下载失败）

go env -w GOPROXY=https://goproxy.cn,direct

2. 下载项目依赖

go mod download

3. 启动服务

go run main.go

4. 启动成功标识

终端输出以下日志即为正常启动：

• Loaded env from .env

• using sqlite driver

• auto migrate database success

• serve http on 127.0.0.1:8080

5. 访问系统

浏览器打开：http://127.0.0.1:8080，注册账号即可创建本地私有知识库、上传文档问答。

六、部署全程核心踩坑汇总 + 终极解决方案

本文汇总本次部署所有真实报错、坑点，每一条均对应原因+精准解决办法，全网通用。

坑1：WSL内核更新报错，无法安装Docker

报错现象：执行 wsl --update 提示「配置成在该可执行程序中运行的这个服务不能执行该服务」，WSL服务损坏，无法启动Docker。

根因：Windows系统WSL组件注册表/服务异常，无法通过命令行修复。

解决方案：彻底放弃Docker+WSL方案，改用Windows原生源码部署，完全规避虚拟化、容器所有问题。

坑2：Ollama模型拉取报错 file does not exist

报错现象：执行 ollama pull qwen2.5:7b-q4_K_M 提示模型不存在。

根因：错误拼接量化后缀，Ollama官方qwen2.5:7b默认就是Q4量化，无需手动加后缀。

解决方案：使用标准命令拉取模型：ollama pull qwen2.5:7b

坑3：Docker环境配置照搬，Ollama连接失败

报错现象：WeKnora无法调用大模型，提示Ollama连接拒绝。

根因：原生Windows环境不识别Docker专属域名 host.docker.internal。

解决方案：.env中Ollama地址改为本地回环地址：http://127.0.0.1:11434

坑4：启动报错 AES key length must be 32

报错现象：服务启动直接崩溃，提示AES密钥长度非法。

根因：官方示例密钥长度不标准，SYSTEM_AES_KEY必须严格32个字符。

解决方案：替换为32位固定密钥，不增不减。

坑5：必须依赖PostgreSQL/Redis，启动失败

报错现象：默认配置连接postgres、redis容器地址，本地无服务直接报错。

解决方案：数据库改为sqlite、队列改为memory，零中间件依赖。

坑6：中文路径导致服务启动异常、文件解析失败

根因：Go项目、Ollama、知识库系统均不支持中文、空格路径。

解决方案：全程使用纯英文路径部署项目。

坑7：MX130 2G显卡无法加速大模型

问题：显卡显存过低，无法承载任何7B模型GPU推理。

解决方案：无需配置GPU，Ollama自动CPU推理，7B量化模型完美适配16G内存。

坑8：网页解析失败、URL报错、内网地址无法访问

现象：系统自动抓取docker内网域名、空域名、无效地址，提示解析失败。

根因：默认配置残留大量容器环境无效路由。

解决方案：改用轻量化原生配置，清除所有容器环境冗余配置。

坑9：重启电脑后模型丢失

误区：用户误以为重启需要重新拉取模型。

真相：Ollama模型存储在系统隐藏目录 C:\Users\Administrator\.ollama\models，重启、关机不会丢失，无需重复下载。

七、最终总结

1. 低配Windows机器最优方案：放弃官方Docker/WSL容器部署，采用「Ollama本地模型 + WeKnora源码原生运行 + SQLite轻量化架构」，适配绝大多数普通笔记本，无虚拟化开销、不卡死、不报错。

2. 核心避坑核心：容器环境配置绝对不能直接用于Windows原生部署，必须修改Ollama地址、数据库、队列、密钥四大核心配置。

3. 硬件适配结论：i7-8850H+16G内存纯CPU环境，qwen2.5:7b + nomic-embed-text 是唯一稳定可用组合，13B及以上模型会内存溢出、卡顿严重。

4. 部署优势：全程零收费、零联网依赖、数据本地私有化存储、无第三方接口调用，完全实现离线私有知识库问答。