Windows11 + Docker + Ollama + MaxKB 本地知识库完整部署方案

本文基于实际部署过程整理，适用于：

• Windows 11
• WSL – Ubuntu – Docker – MaxKB 本地知识库
• Ollama 本地模型 – Qwen3 8B大预言模型 – Embedding向量数据库

---

一、整体架构

推荐架构：

Windows11
 ├─ Ollama（本地模型）
 			└─ Qwen3 8B
 			└─ Embedding
 │
 └─ WSL Ubuntu
      └─ Docker(MaxKB)

推荐原因：

• Ollama 在 Windows 运行更稳定
• GPU 调用更方便
• Docker Desktop 与 WSL 集成成熟
• MaxKB 使用 Docker 部署最简单

---

二、环境准备

1. Windows 11 开启 WSL

管理员 PowerShell：

wsl --install

安装完成后重启电脑。

---

2. 安装 Ubuntu

Microsoft Store 搜索：

Ubuntu

推荐：

Ubuntu 22.04 LTS

---

2、安装
更新你现有的软件包列表，并为下面的步骤安装一些依赖项。 ca-certificates, curl, gnupg 和 lsb_release 工具将被用来下载正确的Docker apt 仓库细节和你系统的签名密钥。尽管你可能已经有了这些软件包，但确保它们是可用的也无妨。

sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release

安装最新版本docker

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

2. 添加 Docker 官方 GPG 密钥

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

3. 添加 Docker 官方软件源

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4. 再次更新源

sudo apt-get update

3. 验证 Docker

Ubuntu 终端：

docker -v

如果报：

permission denied while trying to connect to docker.sock

执行：当前用户赋予权限操作 Docker

sudo usermod -aG docker $USER
newgrp docker

或者关闭终端重新进入。

---

三、部署 MaxKB

1. 拉取并启动 MaxKB

Ubuntu 中执行（下面是一个命令，请全部复制）：

docker run -d \
--name=maxkb \
--restart=always \
-p 8080:8080 \
-v ~/.maxkb:/opt/maxkb \
registry.fit2cloud.com/maxkb/maxkb

---

2. 查看运行状态

docker ps

看到：

maxkb
0.0.0.0:8080->8080/tcp

说明成功。

---

3. 浏览器访问

查看 WSL 真实 IP，在 Ubuntu 终端输入

hostname -I

你会得到一串类似这样的 IP：

192.168.xxx.xxx

使用获得的IP进行访问

http://192.168.xxx.xxx:8080

---

四、安装 Ollama（推荐 Windows 安装）

推荐：

Windows 安装 Ollama
不要在 WSL 中安装

原因：

• WSL 下载 GitHub 容易失败
• Windows GPU 支持更稳定
• Docker 调用更简单

---

1. 下载 Ollama

官方下载：需要梯子

https://ollama.com/download/windows

安装后自动启动。

---

2. 验证 Ollama

浏览器打开：

http://localhost:11434

出现：

Ollama is running

说明成功。

---

五、下载推荐模型

1. 聊天模型（LLM）

推荐：

Qwen3 8B

Windows PowerShell：

ollama pull qwen3:8b

优点：

• 中文能力强
• 企业知识库效果优秀
• 资源占用适中

---

2. Embedding 向量模型（必须）

推荐：

bge-m3

ollama pull bge-m3

作用：

• 知识库检索
• 文档向量化
• 提高命中率

---

3. 查看模型

ollama list

应看到：

qwen3:8b
bge-m3

---

六、配置 Ollama 外部访问（重要）

默认 Ollama 只允许本机访问。

MaxKB 在 Docker 中，需要开放访问。

---

1. 设置系统环境变量

Windows 搜索：

环境变量

打开：

编辑系统环境变量

新增：

变量名	值
OLLAMA_HOST	0.0.0.0:11434

---

2. 重启 Ollama

任务栏：

右键 Ollama → Quit

重新打开 Ollama。

---

七、配置 MaxKB 接入 Ollama

进入：

http://192.168.xxx.xxx:8080

账户：admin
密码：MaxKB@123..

---

1. 添加聊天模型

进入：

系统设置
→ 模型设置
→ 添加模型

选择：

Ollama

---

配置参数

项	内容
API 域名	http://host.docker.internal:11434
API Key	ollama
模型名	qwen3:8b

注意：

不要加 /v1

某些 MaxKB 版本会提示：

API 域名无效

---

2. 添加 Embedding 模型

同样方式：

项	内容
API 域名	http://host.docker.internal:11434
API Key	ollama
模型名	bge-m3

---

八、常见问题汇总

1. docker.sock 权限错误

报错：

permission denied while trying to connect to docker.sock

解决：

sudo usermod -aG docker $USER
newgrp docker

---

2. MaxKB 无法访问 Ollama

原因：

Ollama 默认只监听 127.0.0.1

解决：

配置：

OLLAMA_HOST=0.0.0.0:11434

---

3. API 域名无效

原因：

部分 MaxKB 版本：

• 不允许 /v1
• 校验 URL 格式

正确：

http://host.docker.internal:11434

错误：

http://host.docker.internal:11434/v1

---

4. Ollama 下载慢

原因：

国内访问 GitHub 慢。

解决：

推荐：

Windows 安装 Ollama

不要在 WSL 下载。

---

5. C 盘空间暴涨

原因：

• Ollama 模型
• Docker 镜像
• WSL 虚拟磁盘

清理：

docker system prune -a

查看模型：

ollama list

删除模型：

ollama rm 模型名

---

九、推荐最终方案

类型	推荐
聊天模型	qwen3:8b
embedding	bge-m3
rerank	暂不配置

这是目前：

中文本地知识库
最稳定
兼容最好
效果最均衡

的一套方案。

---