WeKnora Docker 部署完全指南：私有 RAG 知识库从环境评估到长期运维

WeKnora Docker 部署完全指南私有 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/WeKnoraWeKnora 是一个开源 LLM 知识平台可以把原始文档变成可检索的 RAG 知识库、可自主推理的 Agent 和自动维护的 Wiki。本文围绕 Docker Compose 部署展开覆盖环境评估、最小启动路径、组件职责、常见故障处理与长期运维要点目标是让一台干净机器上的部署能稳定跑下去。部署前先判断硬件门槛与模型来源WeKnora 本身是应用层资源消耗的大头在两处文档解析docreader 容器做的分块与渲染和向量检索ParadeDB 版 Postgres即带向量扩展的 Postgres。模型走 API 时一台 2 核 8GB 的机器就能跑要在本机推理内存由加载的模型决定别按部署文档估。运行场景建议配置说明模型走 API云端或远程 Ollama2 核 / 8GB / 20GB 磁盘最低可用档适合内网试用生产环境模型走 API4 核 / 16GB / 100GB 磁盘批量导入文档时的推荐档本机跑 Ollama 模型8 核 / 32GB / 100GB 磁盘内存按目标模型的显存/内存需求上浮模型来源推荐两条路线二选一有 GPU 或云端预算直接用 API解析和问答都最省心。纯内网环境用 Ollama 起本地模型。注意容器内访问宿主机要写host.docker.internal而不是localhost这条后面还会再提。核心部署路径从克隆到打开网页第 1 步克隆代码并准备环境变量git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora # 复制环境变量模板为本地副本后续只编辑这个副本 cp .env.example .env.env.example 里每个变量都有中文注释但不需要逐行看。第 2 步只改这几处关键配置变量默认值处理建议DB_PASSWORD模板占位值改成自己的强密码REDIS_PASSWORD模板占位值同上STORAGE_TYPElocal文件存本地卷单机场景不用动RETRIEVE_DRIVERpostgres向量检索复用 Postgres单机场景不用动OLLAMA_BASE_URLhttp://host.docker.internal:11434不用 Ollama 可忽略其余变量保持默认即可。模型 API Key 不用写在.env里首次登录后在界面里配见第 3 步。第 3 步拉镜像、启动、验证# 拉取全部核心镜像再后台启动 docker compose pull docker compose up -d # 观察容器状态app 显示 healthy 才算就绪 docker compose ps首次启动后打开http://localhost进入系统设置完成初始化建管理员账户、配对话模型API 或 Ollama、配向量模型。AUTO_MIGRATEtrue默认开启会让数据库结构在每次启动时自动迁移不需要手工建表。仓库里还有一个 scripts/start_all.sh 可以一键拉起并顺带装 Ollama但手动docker compose更可控推荐上面的方式。容器与组件职责速览默认up -d启动的是核心五件套数据全部落在 Docker 卷里容器承担的工作宿主端口frontendNginx 托管的 Web 界面反代到 app80FRONTEND_PORT可调app主应用API、业务逻辑、任务队列8080APP_PORT可调postgresParadeDB同时做关系库和向量库仅容器网络内redis流处理与 Asynq 任务队列仅容器网络内docreader文档解析服务gRPC 端口 50051仅容器网络内核心服务之外compose 用--profile组织了可选组件多个 profile 可以叠加Profile提供的能力默认宿主端口neo4j知识图谱构建与检索7474 / 7687minio对象存储替代 local 文件卷9000 / 9001langfuse模型调用链路追踪3000searxng自建网页搜索后端8888默认仅绑 127.0.0.1qdrant/milvus/weaviate/doris替换或补充向量库见 docker-compose.ymlfull以上全部—组合启用的写法# 例如同时启用知识图谱和对象存储 docker compose --profile neo4j --profile minio pull docker compose --profile neo4j --profile minio up -dWiki 模式下Agent 会从原始文档自治生成带链接的 Markdown 知识库与图谱效果可以见 docs/wiki/ 的说明界面形态参考下图启动阶段的高频问题与处理方式80 端口被占用frontend 起不来。宿主机已有 Nginx 或其他服务占了 80。把.env里FRONTEND_PORT80改成 8088 之类的空闲端口再执行docker compose up -d让端口重新映射。app 容器反复重启。多数是.env里DB_USER/DB_PASSWORD/DB_NAME与 postgres 容器的实际凭证对不上改过密码后容易只改一半。用docker compose logs -f app看具体报错然后把.env和数据库配置对齐重建 app 与 postgres 两个容器。app 报 Ollama 连不上但宿主机上服务明明开着。容器里的localhost指向容器自己。OLLAMA_BASE_URL要写宿主机可达地址compose 已把host.docker.internal映射到宿主机用这个即可远程 Ollama 则填实际服务地址。改完.env没生效。这是环境变量而不是文件监听compose 只在容器创建时注入一次。任何.env改动之后都要执行docker compose up -d app重建容器才生效。镜像版本和预期对不上。只跑up -d会复用本地缓存镜像。先docker compose pull再up -d顺序不能反。稳定性调优、安全核对与日常运维长期运行的三个调优点队列并发。解析任务是异步队列驱动的WEKNORA_ASYNQ_CORE_CONCURRENCY默认 8控制文档解析主链路并发机器余量大就提到 16批量导入明显变快WEKNORA_MODEL_MAX_CONCURRENCY默认 32限制每个模型的后台调用并发防止把 LLM 服务端打爆按对方限流调整。Embedding 并发。调用 embedding 接口频繁出现 429 时把CONCURRENCY_POOL_SIZE默认 5调小。日志。默认LOG_LEVELdebug输出很密稳定后改成info并设LOG_PATH落盘方便事后排查。以上改动都归属.env改完统一用docker compose up -d app生效。上线前安全核对清单 ⚠️DB_PASSWORD、REDIS_PASSWORD已替换为强随机值不保留模板占位符SYSTEM_AES_KEY已设为 32 字节随机值openssl rand -hex 16生成。它负责数据库里 API Key、模型凭证等敏感字段的加密丢了这些数据就永久解不开务必离线备份DISABLE_REGISTRATIONtrue关闭公开注册新用户走管理员邀请前端挂在 HTTPS 之后反向代理 Nginx/Caddy 终止证书备份方案演练过一次确认所有数据都在 Docker 卷里备份、升级与巡检# 数据库备份库名、用户名按 .env 实际值替换 docker compose exec postgres pg_dump -U postgres -d WeKnora weknora_$(date %F).sql# 版本升级先拉新镜像再重建顺序反了会复用旧镜像 docker compose pull docker compose up -d# 日常巡检资源占用 主应用日志 docker stats docker compose logs -f app出现异常时按容器逐个看日志docker compose logs -f docreader、docker compose logs -f postgres文档解析慢、模型超时这类问题基本都能定位到具体容器。更细的排查思路参考 常见问题排查接口级问题查 API 文档。【免费下载链接】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），仅供参考