WeKnora Docker 部署实战：单台机器 10 分钟，私有 RAG 知识库与 Agent 问答就位

WeKnora Docker 部署实战：单台机器 10 分钟，私有 RAG 知识库与 Agent 问答就位

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora

本文写给在一台装有 Docker 的 Linux 或 Mac 上想自建知识库的人。跟着做，你会得到 WeKnora 的私有化部署——一个围绕大模型构建的开源知识平台，主打 RAG 问答、Agent 多步推理和自动生成 Wiki 三项能力。全程约 10 分钟。

部署前把环境摸清楚

先看一张机器、软件与密钥的速查表，30 秒扫完：

密钥有两类要提前准备。一是数据库与 Redis 的密码，在 .env.example 里只是占位值，必须替换；二是 SYSTEM_AES_KEY，一把 32 字节的加密主密钥，负责 API Key 等敏感字段落库加密，丢了已加密的数据就解不回来，生成后离线保管。

一条命令完成自检，全部有输出再往下走：

# 自检：CPU 核数、内存、磁盘与 Docker Compose 版本 nproc && free -h && df -h . && docker compose version

自检全部通过后，下面开始把服务真正拉起来。

部署执行：四步拉起核心服务

后续命令都在项目根目录下敲。

1. 取回代码并生成配置文件

# 获取 WeKnora 项目代码并进入目录 git clone https://gitcode.com/GitHub_Trending/we/WeKnora && cd WeKnora

# 复制环境模板，生成 .env cp .env.example .env

完成标志：目录下出现 WeKnora 文件夹，其中包含 .env 文件。

2. 改好 .env 里的 5 个关键变量

# 生成 32 字节随机密钥，粘贴回 .env 替换 SYSTEM_AES_KEY openssl rand -hex 16

完成标志：.env 中上述 5 项均已替换，不再保留示例值。

3. 拉取镜像并后台启动核心服务

# 拉取全部镜像，后台启动核心容器 docker compose pull && docker compose up -d

首次拉取的镜像数据量不小，耗时取决于你的网络环境。

完成标志：命令执行完毕且无报错输出。

4. 确认容器达到 healthy 状态

# 查看容器状态，重点看 app 是否变为 healthy docker compose ps

完成标志：5 个容器全部 running，app 显示 healthy（健康检查含约 60 秒预热窗口）。

此时的核心服务构成如下：

需要知识图谱、对象存储、链路追踪等额外能力时，给 compose 命令加 --profile 参数即可。例如同时加装 Neo4j 与 MinIO：

# 扩展知识图谱与对象存储两个附加服务 docker compose --profile neo4j --profile minio up -d

完整 profile 清单见 README_CN.md 的可选服务一节。

容器起来只是第一步，接下来在浏览器里确认服务真的可用。

首次进入与成功验证

浏览器打开 http://localhost。首次部署会进入初始化向导，按提示完成注册登录。

按顺序走完三步，每一步都走通，部署就算成功：

1. 在向导里配置 LLM 与 Embedding 模型，填 API 地址或指向本地 Ollama 均可。
2. 建一个知识库，上传一份 PDF，文档列表中的状态由解析中变为完成。
3. 在问答框输入一个问题，回答能流式返回并带引用来源。

同时访问 http://localhost:8080，能响应即说明后端 API 正常。上面三项确认后，部署环节就算闭环；中间若卡住，多数落在下面几类问题上。

常见坑与快速修复

坑 1：docker 命令不存在。现象：终端报docker: command not found。原因：机器没装 Docker。修复命令：

# 以 Debian/Ubuntu 为例安装 Docker 全家桶 sudo apt-get install -y docker-ce docker-ce-cli containerd.io

装完重跑docker compose version复查。

坑 2：Docker 权限被拒。现象：任何 docker 命令都报permission denied。原因：当前用户不在 docker 组。修复：

# 把当前用户加入 docker 组 sudo usermod -aG docker $USER

重新登录或开新终端后生效。

坑 3：80 端口打不开前端。现象：浏览器访问 80 端口看到的不是 WeKnora。原因：端口被别的服务占用。修复：把 .env 里 FRONTEND_PORT 的值改为 8088，然后执行docker compose up -d frontend重建。

坑 4：app 容器反复重启。现象：docker compose ps里状态在 restarting 与 Exited 之间跳动。原因：.env 中数据库的用户、密码、库名与 postgres 服务实际承载的不一致。修复：

# 跟踪 app 日志定位具体报错 docker compose logs -f app

按日志改好 .env，再执行docker compose up -d app。

坑 5：提问无响应或提示模型错误。现象：页面能打开，问答却报错。原因：模型未配置，或 Ollama 没启动。修复：在设置页补齐 API 模型；本地 Ollama 方案则先执行ollama serve拉起服务并 pull 一个模型。

坑 6：升级后版本没变。现象：代码已更新，界面版本仍是旧的。原因：只执行了 up -d 而没先 pull，复用了缓存里的旧镜像。修复：

# 先拉取与版本号匹配的新镜像，再重建容器 docker compose pull && docker compose up -d

这 6 个坑排除掉之后，就可以谈长期稳定运行了。

稳定运行与上线前检查

三条调优建议，按收益从大到小排：

1. 把模型配到位。回答质量主要取决于 LLM，保持GIN_MODE=release，并在设置页选一个能力强的模型。
2. 上调解析并发。解析任务由队列驱动，WEKNORA_ASYNQ_CORE_CONCURRENCY默认 8，机器余量大就提到 16；WEKNORA_MODEL_MAX_CONCURRENCY默认 32，限制每模型的后台并发。
3. 日志降级。LOG_LEVEL默认是 debug，服务稳定后改为 info；LOG_PATH可把日志落到文件便于排查。

改完 .env 需重建容器才生效：

# 重建 app 容器，使新环境变量生效 docker compose up -d app

⚠️ 暴露到公网前，逐项核对下面这份清单：

• DB_PASSWORD、REDIS_PASSWORD 都已换成自设值
• SYSTEM_AES_KEY 已替换为 32 字节随机值，并完成离线备份
• DISABLE_REGISTRATION 设为 true，账号由管理员邀请产生
• 前端挂上 HTTPS，证书在反向代理层终止
• 备份方式验证可用，业务数据存放在 Docker 卷中

数据库备份一条命令：

# 导出数据库，文件名带当天日期 docker compose exec postgres pg_dump -U postgres -d WeKnora > weknora_$(date +%F).sql

日常巡检盯两个点：docker stats看资源水位，docker compose logs -f app看报错。更细的排查方法参考 docs/QA.md。

到这里，从零到可用的私有知识库部署已经完整走完。下一步把第一批业务文档灌进知识库，开始真实提问。文档量上来后，记得回来复盘一遍上面的并发参数。

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora