WeKnora Docker 部署实战：10 分钟从零到私有 RAG 知识库
【免费下载链接】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 Compose 在一台机器上把 WeKnora 跑起来：克隆仓库、配一份.env，10 分钟得到一套私有 RAG 知识库——上传文档，提问，拿到带引用的回答。机器上装好 Docker 即可，无需其他依赖。WeKnora 是开源 LLM 知识平台，把原始文档变成可检索的 RAG 知识库、自主推理 Agent 和自动维护的 Wiki。
先选路线：按场景挑机器
WeKnora 本身只是应用层，重活是文档解析与向量检索，所以机器要求取决于一件事：你的 LLM 在哪。模型走云 API 时机器只承担解析和检索；本机跑 Ollama（本地大模型服务）时，内存由你加载的模型大小决定。
| 你的场景 | 够用的配置 | 一句话原因 |
|---|---|---|
| 本机开发，LLM 走云 API | 2 核 / 8GB / 20GB 盘 | 重推理在云端，本机只做解析与检索 |
| 服务器给团队共用 | 4 核 / 16GB / 100GB | 批量解析加向量库需要余量 |
| 本机跑 Ollama 模型 | 8 核 / 32GB / 100GB+ | 内存取决于模型大小 |
动手前先做 30 秒自检，确认硬件达标且 Compose 可用：
# 30秒自检：CPU、内存、磁盘与 Docker Compose nproc; free -h; df -h .; docker compose version💡 最后一条失败，通常是 Docker 没装或当前用户不在 docker 组，先修好再继续。
最小闭环部署
两条命令完成克隆与配置准备：
# 克隆仓库并进入目录 git clone https://gitcode.com/GitHub_Trending/we/WeKnora && cd WeKnora # 复制环境变量模板（每个变量都有中文注释） cp .env.example .env然后编辑.env，只需看下表，其余保持默认：
| 配置项 | 不改会怎样 | 建议改成什么 |
|---|---|---|
DB_PASSWORD/REDIS_PASSWORD | 模板示例值，等同公开密码 | 你自己的强密码 |
SYSTEM_AES_KEY | 加密 API Key 的主密钥用了公开值 | openssl rand -hex 16生成的 32 字节随机值 |
STORAGE_TYPE/RETRIEVE_DRIVER | 没影响 | 保持默认：文件进本地卷，向量检索复用同一个 Postgres |
LOG_LEVEL | 默认debug，日志很吵 | info，可用LOG_PATH落盘 |
OLLAMA_BASE_URL | 连不上也不阻塞启动 | 仅用本地 Ollama 时改成你的地址 |
拉镜像并启动：
# 拉取镜像并后台启动核心服务 docker compose pull && docker compose up -d默认启动核心五件套：frontend（Nginx 网页界面，端口 80）、app（API 与业务逻辑，8080）、postgres（ParadeDB 版，关系数据与向量数据一体）、redis（流处理与任务队列，不对外）、docreader（文档解析，gRPC 仅容器内网）。
附加能力用--profile按需叠加，可组合：
# 按需叠加：知识图谱(Neo4j) + 对象存储(MinIO) docker compose --profile neo4j --profile minio up -d常用有full（全部）、neo4j（知识图谱）、minio（对象存储）、langfuse（链路追踪）、searxng（自建网页搜索），完整清单见 README_CN.md 可选服务一节。
启动后注册账号、建知识库、上传第一批文档，文档列表页长这样：
三道验收：进程、入口、真实提问
第一道：进程状态。
# 查看容器状态 docker compose ps # 探测 API 健康端点 curl http://localhost:8080/health通过标准：五个容器全部 Up，app 一行显示healthy（健康检查每 30 秒探测一次/health），curl 返回成功。
第二道：访问入口。浏览器打开http://localhost，出现注册页即通过；API 在http://localhost:8080。
第三道：一次真实端到端请求。前两道只证明容器活着。注册账号，在系统设置配置模型（云 API 或 Ollama 均可），建知识库传一份 PDF，等文档解析完成，再问一个文档里的问题。通过标准：回答基于文档内容并给出来源引用——解析、向量化、检索、生成全链路才算通。
排错与提速：起不来、慢、效果差
起不来类
- 现象：
docker: command not found或permission denied连不上 daemon原因：Docker 没装，或当前用户不在 docker 组处置：安装 Docker，sudo usermod -aG docker $USER加组后重开终端 - 现象：80 端口被占，前端起不来原因：
FRONTEND_PORT默认 80 被别的服务占用处置：.env里改FRONTEND_PORT=8088，再docker compose up -d重建 - 现象：app 容器反复重启原因：多半是
DB_USER/DB_PASSWORD/DB_NAME与 postgres 容器对不上处置：docker compose logs -f app看报错，核对.env三项
慢类
- 现象：批量文档解析慢原因：解析由异步队列驱动，主链路默认并发只有 8处置：机器余量大就把
WEKNORA_ASYNQ_CORE_CONCURRENCY从 8 调到 16；模型后台并发WEKNORA_MODEL_MAX_CONCURRENCY（默认 32）可同步上调
注意：.env改动不会作用于已运行的容器，改完执行docker compose up -d app重建才生效。
效果差类
- 现象：回答跑题、答非所问原因：回答质量九成取决于 LLM，模型太弱处置：系统设置里换能力更强的模型；仍不理想再按 常见问题排查 调检索参数
上线前：四个风险点
- 占位密码裸奔：
DB_PASSWORD/REDIS_PASSWORD是仓库示例值，服务暴露公网任何人都能登录，知识库内容全公开。两处替换后docker compose up -d重建容器。 - AES 主密钥没保管：
SYSTEM_AES_KEY加密 API Key 等敏感字段，丢了就解不开，所有密钥都得重填。openssl rand -hex 16生成并离线保存。 - 注册敞开：
DISABLE_REGISTRATION默认false，任何人都能注册建空间。生产设为true，用户走管理员邀请。 - 没有备份：数据都在 Docker 卷里，磁盘故障即全丢。一条命令导出：
# 一键导出数据库备份 docker compose exec postgres pg_dump -U postgres -d WeKnora > weknora_$(date +%F).sql升级永远先拉镜像：docker compose pull && docker compose up -d，只跑up -d会复用旧镜像，界面显示的版本和预期对不上。
⚠️ 四项都是「现在处理便宜、事后处理贵」的事，上线前一次性做完。
整条主线就是一条链：选路线、配.env、起五件套、三道验收。下一步很具体——把第一批真实文档传进知识库，问一个只有这些文档能回答的问题。
【免费下载链接】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），仅供参考
