WeKnora知识库问答系统一键部署教程：基于Docker的快速搭建指南

1. 引言

你是不是经常遇到这样的情况：公司内部文档散落在各个角落，想要查找某个技术方案或者产品说明时，需要翻遍无数个文件夹？或者作为开发者，你想为自己的项目搭建一个智能问答系统，但又被复杂的部署流程劝退？

今天我要介绍的WeKnora，正是为了解决这些问题而生的。这是一个基于大语言模型的文档理解与语义检索框架，专门处理结构复杂、内容多样的文档场景。最棒的是，它支持Docker一键部署，哪怕你不是运维专家，也能快速搭建起属于自己的知识库系统。

我在实际部署过程中发现，虽然官方文档已经比较详细，但还是会遇到一些坑。比如端口冲突、数据库初始化失败等问题。这篇文章就是把我踩过的坑和解决方案都分享出来，让你能够真正实现"一键部署"。

2. 环境准备与系统要求

在开始之前，我们先确认一下系统环境。WeKnora支持在大多数Linux发行版上运行，我这里以Ubuntu 20.04为例进行说明。

2.1 系统要求

最低配置：

• CPU：4核以上（建议8核）
• 内存：8GB（建议16GB）
• 存储：50GB可用空间
• 系统：Linux（Ubuntu/CentOS等）

软件依赖：

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl wget git docker.io docker-compose

2.2 Docker环境检查

确保Docker和Docker Compose已正确安装：

# 检查Docker版本
docker --version
# 输出：Docker version 20.10.17, build 100c701

# 检查Docker Compose版本  
docker-compose --version
# 输出：docker-compose version 1.29.2, build unknown

# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker

如果还没有安装Docker，可以使用以下命令快速安装：

# 一键安装Docker
curl -fsSL https://get.docker.com | sh

3. 快速部署步骤

3.1 获取项目代码

首先把WeKnora的代码克隆到本地：

# 创建项目目录
mkdir -p ~/weknora && cd ~/weknora

# 克隆项目代码
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora

如果网络环境访问GitHub较慢，也可以使用国内镜像源：

# 使用国内镜像加速
git clone https://gitee.com/mirrors/weknora.git

3.2 配置环境变量

WeKnora使用环境变量文件来管理配置，我们先复制示例文件：

# 复制环境变量模板
cp .env.example .env

现在编辑.env文件，配置关键参数：

# 使用nano编辑器修改配置
nano .env

需要重点关注以下几个配置项：

# 前端服务端口（默认8081，如果冲突可以修改）
FRONTEND_PORT=8081

# 后端API端口（默认8080）
BACKEND_PORT=8080

# 数据库配置
POSTGRES_PORT=5432
POSTGRES_PASSWORD=your_secure_password_here

# Ollama配置（如果你已经部署了Ollama）
OLLAMA_HOST=your_ollama_host

特别注意：如果系统上已经运行了PostgreSQL服务，需要修改POSTGRES_PORT避免端口冲突。

3.3 启动所有服务

配置完成后，使用提供的脚本一键启动所有服务：

# 赋予脚本执行权限
chmod +x scripts/start_all.sh

# 启动所有服务
./scripts/start_all.sh

这个过程可能会花费一些时间，因为需要拉取多个Docker镜像并初始化数据库。耐心等待直到看到所有容器都正常启动。

3.4 验证服务状态

启动完成后，检查各个容器的运行状态：

# 查看所有容器状态
docker ps

# 应该看到类似这样的输出
# CONTAINER ID   IMAGE                STATUS         PORTS
# a1b2c3d4e5f6   weknora-app:latest   Up 5 minutes  0.0.0.0:8080->8080/tcp
# b2c3d4e5f6g7   weknora-db:latest    Up 5 minutes  0.0.0.0:5432->5432/tcp
# c3d4e5f6g7h8   weknora-ui:latest    Up 5 minutes  0.0.0.0:8081->80/tcp

4. 常见问题与解决方案

在部署过程中，你可能会遇到一些常见问题。这里我整理了实际遇到的情况和解决方法。

4.1 端口冲突问题

问题现象：启动时提示端口已被占用

解决方案：

# 查看端口占用情况
sudo netstat -tulpn | grep :5432

# 如果确实被占用，修改.env文件中的端口配置
# 比如将POSTGRES_PORT=5432改为POSTGRES_PORT=5433

4.2 数据库初始化失败

问题现象：服务启动后无法创建知识库

解决方案：

# 进入数据库容器检查表结构
docker exec -it weknora-postgres psql -U postgres -d weknora -c "\dt"

# 如果表不全，手动执行初始化脚本
docker exec -i weknora-postgres psql -U postgres -d weknora -f /docker-entrypoint-initdb.d/00-init-db.sql

# 再次检查表结构
docker exec -it weknora-postgres psql -U postgres -d weknora -c "\dt"

4.3 容器启动失败

问题现象：某个容器不断重启

解决方案：

# 查看容器日志定位问题
docker logs weknora-app

# 如果是内存不足，尝试增加swap空间
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

5. 首次使用与配置

服务启动成功后，打开浏览器访问 http://你的服务器IP:8081。

5.1 初始化账号

第一次访问会跳转到注册页面：

1. 点击"立即注册"
2. 填写用户名、邮箱和密码
3. 使用邮箱登录系统

5.2 配置模型服务

登录后首先需要配置AI模型：

1. LLM大模型配置：选择你已有的模型，如Qwen、DeepSeek等
2. Embedding模型：建议选择专门的嵌入模型以获得更好效果
3. 其他设置：保持默认或根据需求调整

5.3 创建知识库

点击右上角"新建知识库"：

• 输入知识库名称和描述
• 选择适合的配置模板
• 上传文档文件（支持PDF、Word、TXT等格式）

6. 实际使用体验

部署完成后，我测试了几个典型的使用场景：

文档问答：上传技术文档后，能够准确回答基于文档内容的问题 多轮对话：支持上下文关联的连续提问，适合深度分析 检索效果：混合检索策略确实比单纯的关键词搜索更智能

资源占用方面，不包括Ollama服务的情况下：

• 内存占用：约1.3GB
• CPU占用：日常使用在5-15%之间
• 存储占用：取决于文档数量和大小

7. 总结

整体来看，WeKnora的Docker部署确实做到了相对简单的一键式体验。虽然过程中可能会遇到一些小问题，但都有相应的解决方案。这个系统特别适合需要搭建企业内部知识库的中小团队，既保证了数据隐私，又提供了智能的问答能力。

部署成功后，你会发现维护成本并不高。系统运行稳定，日常只需要关注存储空间和模型服务的运行状态。如果你正在寻找一个可私有化部署的知识库解决方案，WeKnora绝对值得一试。

最后提醒一点，虽然本文提供了详细的部署指南，但每个实际环境可能都有所不同。如果遇到文中没有覆盖的问题，建议查看项目的GitHub Issues页面，或者加入开发者社区寻求帮助。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。