Windows 10 专属 MaxKB 部署教程（含避坑指南）

针对 Windows 10 系统优化，解决 Docker 路径、WSL2 配置等痛点问题，实测通过！

一、环境准备（15分钟）

1️⃣ 启用 WSL2 和虚拟化

# 管理员身份打开 PowerShell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
wsl --install  # 自动安装 Ubuntu
wsl --set-default-version 2

 

 

重启电脑（必须步骤！）

2️⃣ 安装 Docker Desktop

1. 下载安装包：https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe
2. 安装时勾选：

3️⃣ 配置 Docker 存储路径（防C盘爆满）

# 创建专用存储目录（建议在D盘）
mkdir D:\docker-data

# 创建配置文件
New-Item -Path "$env:USERPROFILE\.wslconfig" -Force
Add-Content -Path "$env:USERPROFILE\.wslconfig" -Value @"
[wsl2]
memory=8GB   # 根据RAM调整(建议≥8GB)
swap=0
localhostForwarding=true
"@

 

 

二、部署 MaxKB（5分钟）

1️⃣ 创建数据目录

# 在D盘创建专用目录（避免权限问题）
mkdir D:\maxkb_data

mkdir D:\python-packages

2️⃣ 一键启动容器

# 在 PowerShell 执行

docker run -d --name=maxkb --restart=always -p 8080:8080 -v D:/maxkb_data:/var/lib/postgresql/data -v D:/python-packages:/opt/maxkb/app/sandbox/python-packages registry.fit2cloud.com/maxkb/maxkb

✅ 验证：浏览器访问 http://localhost:8080 账号：admin 密码：MaxKB@123..

三、接入本地大模型（Ollama｜10分钟）

1️⃣ 安装 Ollama

# 一键安装命令
winget install ollama

2️⃣ 启动服务并下载模型

# 新开 PowerShell 窗口
ollama serve  # 保持窗口开启！

# 另开窗口下载中文模型
ollama pull qwen2.5:7b-chat

3️⃣ 获取 Windows 主机 IP

# 查询本机IP (记下 IPv4 地址)
ipconfig | findstr "IPv4"

4️⃣ MaxKB 绑定模型

1. 登录 MaxKB → 模型设置 → 添加模型
2. 配置：
   • 模型名称：本地Qwen模型
   • API 地址：http://[你的IP]:11434（如 http://192.168.1.100:11434）
   • 模型ID：qwen2.5:7b-chat

四、知识库实战（15分钟）

场景：管理公司项目文档

1. 创建知识库

   • 名称：公司项目资料库 → 嵌入模型选 text2vec

2. 上传文档（支持拖拽）

   • 上传位置：知识库 → 文档管理 → 上传
   • 推荐文件：
     • 项目计划书.docx
     • 专利清单.xlsx
     • 申报指南.pdf

3. 智能问答测试

Prompt
"找出2024年云计算相关项目的预算总额"

✅ 效果：自动提取Excel数据生成答案

五、Windows专属优化技巧

🚀 性能提升

# 限制容器内存（防卡死）
docker update maxkb --memory 6G --memory-swap 8G

💾 中文PDF解析修复

遇到扫描件解析失败时：

1. 使用 Adobe Acrobat 将PDF转为「可搜索PDF」
2. 或用免费工具：https://www.ilovepdf.com/ocr-pdf

🔌 开机自启动设置

创建 start_ai.bat 文件：

@echo off
ollama serve
docker start maxkb

放入「启动」文件夹：Win+R 输入 shell:startup

六、常见问题解决

问题现象	解决方案
访问localhost:8080失败	1. 检查WSL是否运行：wsl -l -v2. 重启Docker Desktop
Ollama连接超时	关闭防火墙：netsh advfirewall set allprofiles state off
上传文档卡在99%	修改知识库设置→分段规则→调大chunk_size到800
中文回答乱码	修改MaxKB配置文件：添加 -e LANG=C.UTF-8 到docker run命令

💡 终极方案：所有命令都在 Windows Terminal 中执行

成果验收

完成部署后您将获得： ✅ 本地安全的AI知识库（无数据外传风险） ✅ 1分钟定位历史项目资料 ✅ 3分钟生成申报材料初稿 ✅ 专利检索效率提升50%