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 秒扫完项目最低要求说明CPU / 内存2 核 / 8GBLLM 走远程 API 时够用CPU / 内存8 核 / 32GB本机用 Ollama 跑模型才需要磁盘20GB 以上镜像与向量索引的存放空间Docker带 Compose v2整个部署的基础Git任意版本用于取回代码密钥有两类要提前准备。一是数据库与 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 个关键变量变量默认值建议设置DB_PASSWORD示例占位换你自己生成的强密码REDIS_PASSWORD示例占位同样处理SYSTEM_AES_KEY内置示例值换成 32 字节随机值并离线备份STORAGE_TYPElocal保留文件落在本地卷RETRIEVE_DRIVERpostgres保留向量引擎复用 ParadeDB# 生成 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 个容器全部 runningapp 显示 healthy健康检查含约 60 秒预热窗口。此时的核心服务构成如下容器职责宿主端口frontendWeb 界面Nginx 承载80app主应用API 与业务逻辑8080postgresParadeDB关系库与向量库二合一仅内网redis流处理与异步任务队列仅内网docreader文档解析服务gRPC 50051仅内网需要知识图谱、对象存储、链路追踪等额外能力时给 compose 命令加 --profile 参数即可。例如同时加装 Neo4j 与 MinIO# 扩展知识图谱与对象存储两个附加服务 docker compose --profile neo4j --profile minio up -d完整 profile 清单见 README_CN.md 的可选服务一节。容器起来只是第一步接下来在浏览器里确认服务真的可用。首次进入与成功验证浏览器打开 http://localhost。首次部署会进入初始化向导按提示完成注册登录。按顺序走完三步每一步都走通部署就算成功在向导里配置 LLM 与 Embedding 模型填 API 地址或指向本地 Ollama 均可。建一个知识库上传一份 PDF文档列表中的状态由解析中变为完成。在问答框输入一个问题回答能流式返回并带引用来源。同时访问 http://localhost:8080能响应即说明后端 API 正常。上面三项确认后部署环节就算闭环中间若卡住多数落在下面几类问题上。常见坑与快速修复坑 1docker 命令不存在。现象终端报docker: command not found。原因机器没装 Docker。修复命令# 以 Debian/Ubuntu 为例安装 Docker 全家桶 sudo apt-get install -y docker-ce docker-ce-cli containerd.io装完重跑docker compose version复查。坑 2Docker 权限被拒。现象任何 docker 命令都报permission denied。原因当前用户不在 docker 组。修复# 把当前用户加入 docker 组 sudo usermod -aG docker $USER重新登录或开新终端后生效。坑 380 端口打不开前端。现象浏览器访问 80 端口看到的不是 WeKnora。原因端口被别的服务占用。修复把 .env 里 FRONTEND_PORT 的值改为 8088然后执行docker compose up -d frontend重建。坑 4app 容器反复重启。现象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 个坑排除掉之后就可以谈长期稳定运行了。稳定运行与上线前检查三条调优建议按收益从大到小排把模型配到位。回答质量主要取决于 LLM保持GIN_MODErelease并在设置页选一个能力强的模型。上调解析并发。解析任务由队列驱动WEKNORA_ASYNQ_CORE_CONCURRENCY默认 8机器余量大就提到 16WEKNORA_MODEL_MAX_CONCURRENCY默认 32限制每模型的后台并发。日志降级。LOG_LEVEL默认是 debug服务稳定后改为 infoLOG_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
