WeKnora 私有 RAG 知识库：Docker Compose 部署上线完整实战
【免费下载链接】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
WeKnora 是一个开源 LLM 知识平台：把原始文档灌进去，变成可检索的私有 RAG 知识库、推理 Agent 和自动维护的 Wiki。这篇文章只讲一件事——在一台机器上用 Docker Compose 把 WeKnora 部署跑通，然后完成验证、调优和上线前的安全检查。
用 Docker Compose 把核心五件套拉起来
LLM 走 API（云端或远程 Ollama）的话，4 核 8GB 的机器就够；本机跑 Ollama 时内存取决于你加载多大的模型。先花十秒自检一下环境：
# 检查 CPU、内存、磁盘和 Docker Compose 是否可用 nproc; free -h; df -h .; docker compose version都过了就直接进入 WeKnora 部署，整条路径就三步，断点排查也方便：
# 克隆代码仓库，并复制环境变量模板 git clone https://gitcode.com/GitHub_Trending/we/WeKnora && cd WeKnora cp .env.example .env打开.env，只需要动下面这几项，其余保持默认即可：
| 变量 | 你该做什么 |
|---|---|
DB_PASSWORD/REDIS_PASSWORD | 改成自己的强密码 |
SYSTEM_AES_KEY | 生成 32 字符，离线保管 |
FRONTEND_PORT | 80 被占用改 8088 |
STORAGE_TYPE | 保持 local |
OLLAMA_BASE_URL | 不用 Ollama 就留默认 |
STORAGE_TYPE默认是local，文件落在 Docker 卷里最省事；有对象存储需求再换minio/s3。OLLAMA_BASE_URL默认指向宿主机的 Ollama，不用的话留着也无害，最多启动时告警一句。
# 拉取镜像并后台启动核心服务 docker compose pull && docker compose up -d仓库里还有一键脚本 启动脚本（会顺带装 Ollama），但手动走 docker compose 更可控，推荐上面的路径。
验证容器健康检查与网页响应
判断"起没起来"只有一条硬标准：docker compose ps里 app 显示 healthy。
# 查看容器状态，app 为 healthy 才算就绪 docker compose psWeKnora-postgres paradedb/paradedb healthy WeKnora-app wechatopenai/weknora-app healthy # ……（略）默认启动的核心五件套各就各位：
| 容器 | 作用 | 宿主端口 |
|---|---|---|
| frontend | Web 界面 | 80 |
| app | API 与业务逻辑 | 8080 |
| postgres | ParadeDB 关系+向量 | 不对外 |
| redis | 队列与流处理 | 不对外 |
| docreader | 文档解析 gRPC | 不对外 |
这里说一下 postgres：它是 ParadeDB 镜像，本质是带向量扩展的 Postgres；所以选它，是为了单机部署少养一个独立的向量库；不这么做的话，就得另起 Qdrant 或 Milvus 再填连接配置。
然后打开浏览器：http://localhost是前端界面，http://localhost:8080是 API 服务。
用 profile 叠加可选组件
默认up -d只拉起核心服务，其余组件用--profile按需叠加，可自由组合：
# 例：同时启用知识图谱(Neo4j)与对象存储(MinIO) docker compose --profile neo4j --profile minio pull docker compose --profile neo4j --profile minio up -d常用的有：full（全部功能）、neo4j（知识图谱）、minio（对象存储）、langfuse（链路追踪）、searxng（自建网页搜索）。
配置模型并灌入第一批文档
容器健康但上传文档没动静，十有八九是模型没配。LLM 和 Embedding 模型要在网页「系统设置」里首次填写，API 或 Ollama 均可。走 Ollama 的话先把它跑起来：
# 启动 Ollama 并拉取一个对话模型 ollama serve ollama pull qwen2.5:7b模型配好之后，建一个知识库，扔进几篇 PDF 或 Markdown，就可以直接提问了：
回答会带引用来源，点开能核对检索命中的是不是正确段落——这一步就是检验部署质量的最直接方式。
批量导入慢就动这三个旋钮
WeKnora 部署跑起来之后，最常见的抱怨是"解析慢"。按优先级动这三处：
- 模型别将就。回答质量九成取决于 LLM，先把能力强的模型配上，胜过调任何参数。
- 调解析并发。
WEKNORA_ASYNQ_CORE_CONCURRENCY是文档解析主链路的队列并发数；它默认 8，对单机偏保守；不调的话批量导入会排队变慢，机器有余量就提到 16，体感立竿见影。 - 降日志级别。
LOG_LEVEL默认debug，又吵又占盘；稳定后改info，配合LOG_PATH落盘方便事后排查。
另外WEKNORA_MODEL_MAX_CONCURRENCY（默认 32）限制每个模型的后台并发，遇到模型提供方 429 限流时，往小调而不是往大调。
# 改完 .env 后重建 app 容器让新值生效 docker compose up -d app改的是环境变量，光重启进程不够，必须重建容器才会读进新值。
公网暴露前过一遍安全与备份清单
默认配置里不少值是占位示例，暴露到公网之前逐项核销：
DB_PASSWORD、REDIS_PASSWORD改成自己的值；- 显式设置
SYSTEM_AES_KEY，用openssl rand -hex 16生成。它是 API Key 等敏感字段的落盘加密密钥，丢了就解不开，务必离线保管 ⚠️ - 设
DISABLE_REGISTRATION=true，用户走管理员邀请而非公开注册； - 给前端挂 HTTPS，反代 nginx/caddy 终止证书即可；
- 确认备份链路可用。数据都在 Docker 卷里，一条命令导出：
# 导出数据库备份 docker compose exec postgres pg_dump -U postgres -d WeKnora > weknora_$(date +%F).sql升级和部署走同样的两步，注意先pull再up，否则会复用旧镜像：
# 升级：拉取与 WEKNORA_VERSION 匹配的新镜像并重建 docker compose pull && docker compose up -d日常巡检看两样：docker stats看资源占用，docker compose logs -f app看报错。
卡住了对照这五条
整个 WeKnora 部署过程中最容易卡住的，是下面这五个点：
Q: 报docker: command not foundA: Docker 没装，安装完成后用docker compose version复查。
Q: 连不上 daemon，报permission deniedA:sudo usermod -aG docker $USER把用户加进 docker 组，重开终端生效。
Q: 前端起不来，提示 80 端口被占用 A:.env里改FRONTEND_PORT=8088，再docker compose up -d重建。
Q: app 容器反复重启 A:docker compose logs -f app看日志定位，多数是DB_USER/DB_PASSWORD/DB_NAME与 postgres 容器对不上。
Q: 文档上传成功但问答没反应 A: 回系统设置核对 LLM 与 Embedding 模型是否配置完整且可连通，更多情况见 常见问题排查。
跑通之后，第一件事是往里扔第一批文档，然后问它一个问题——看它答得准不准。
【免费下载链接】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），仅供参考
