从零用 Docker 部署 WeKnora 开源知识库的完整指南：5 步快速上手

从零用 Docker 部署 WeKnora 开源知识库的完整指南：5 步快速上手

【免费下载链接】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 知识平台，能把 PDF、Word、网页等原始文档变成可问答的 RAG 知识库、可自主推理的 Agent 和自动维护的 Wiki。本文带你完成 WeKnora 的 Docker 部署：从环境自检到一键启动，再到生产优化要点，全程只需敲 4 条命令。

读完本文你会得到：一张环境需求表、一条最短部署路径、一份「真正要改的配置」清单，以及生产环境的安全与性能要点。

环境准备：部署前花 2 分钟确认

本章给你一张硬件需求表和几个自检动作，避免装到一半卡在资源不足。

需求表

环境自检

启动前确认三件事即可：执行docker info确认 Docker 服务在运行；执行nproc和free -h确认 CPU 与内存满足上表；确认 80、8080 端口未被占用（可用netstat -tulpn | grep -E ':80|:8080'）。仓库自带./scripts/start_all.sh -c也能做一次完整环境检查，包括 Ollama 和磁盘空间。

快速上手：5 步启动 WeKnora

本章是最小组装路径，先克隆、再配置、最后启动，每步都有验证点。

第 1 步：克隆仓库

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora

第 2 步：准备环境变量

cp .env.example .env

.env.example里每个变量都有中文注释，直接复制后按需修改。核心服务用默认值就能跑起来，真正必填的只有数据库账号密码和模型配置（详见后文「关键配置」）。

第 3 步：拉取镜像

docker compose pull

第 4 步：启动核心服务

docker compose up -d

启动后执行docker compose ps，应看到 frontend、app、docreader、postgres、redis 五个容器全部 healthy。仓库也提供一键脚本./scripts/start_all.sh，它会顺带检查并拉起本地 Ollama，适合完全不想手动操作的场景。

第 5 步：打开界面完成初始化

浏览器访问http://localhost，注册第一个账号，然后在「设置 → 模型」里配置对话模型（LLM）和向量模型（Embedding），支持 OpenAI、DeepSeek、Qwen、Ollama 等 20+ 提供商。配置完上传第一篇文档，就能在问答界面检索你的知识库了。

看懂内部：5 个核心容器如何协同

本章讲清端口、依赖和数据流向，出问题时你能定位到具体是哪个组件。

组件职责一览

启动顺序由 compose 的健康检查保证：postgres 和 docreader 先就绪，app 才启动，frontend 最后等 app 变 healthy 才放行。

数据流向

一次「上传并问答」的完整链路是：文档经 frontend 传给 app；app 调 docreader 解析成文本块，做 embedding 后写入 postgres；提问时 app 在 postgres 里做向量+关键词混合检索，把命中的片段连同问题一起交给外部 LLM 生成带引用的回答。异步任务（解析、摘要、图谱抽取）全部走 redis 队列，由 app 内的工作池消费。

可选组件（按需开启 Profile）

核心服务之外，其余组件都放在 Docker Compose Profile 里，需要时加参数启动：neo4j（知识图谱，7474/7687）、minio（对象存储，9000/9001）、qdrant/milvus（替换向量库）、searxng（自建网页搜索，8888）、langfuse（链路追踪，3000）、mcp（MCP Server，8082）。多个可组合：docker compose --profile neo4j --profile minio up -d。完整特性可一步到位：--profile full。

关键配置：只有这几项真正需要改

本章列出 .env.example 中建议你动手改的字段，其余保持默认即可。

# ---- 数据库（默认值可直接用，多用户共享部署建议改密码）---- DB_USER=postgres # 默认 postgres DB_PASSWORD=postgres123!@# # 默认值，生产必改 DB_NAME=WeKnora # 默认 WeKnora # ---- Redis（默认密码）---- REDIS_PASSWORD=redis123!@# # 生产必改 # ---- 存储与向量库（默认本地磁盘 + postgres 向量）---- STORAGE_TYPE=local # 可选 minio/s3/cos/oss 等 RETRIEVE_DRIVER=postgres # 可选 qdrant/milvus/opensearch 等 # ---- 模型服务（用本地 Ollama 时保持默认即可）---- OLLAMA_BASE_URL=http://host.docker.internal:11434 OLLAMA_OPTIONAL=true # Ollama 不可用时只告警不阻断 # ---- 安全密钥（生产必改）---- JWT_SECRET=weknora-jwt-secret # 留空则启动时随机生成 SYSTEM_AES_KEY=weknora-system-aes-key-32bytes!! # 必须 32 字节， # 丢失则库内加密的 API Key 全部不可恢复 # ---- 注册开关（生产建议关闭公开注册）---- DISABLE_REGISTRATION=false # 默认 false，生产建议 true

两点提醒：

• SYSTEM_AES_KEY是 AES-256 主密钥，用于加密数据库里所有 API Key 和模型凭证，生产环境必须显式设置并妥善备份，丢失意味着已加密字段全部作废。
• 模型（对话/向量/Rerank）默认在界面里配置而不是.env，启动后到「设置」页填写即可，无需改代码。

生产与优化：安全清单和性能旋钮

本章分安全、性能两小节，用清单过一遍即可。

安全清单

• 修改所有默认密码：DB_PASSWORD、REDIS_PASSWORD、MinIO 账号（若启用）。
• 重新生成JWT_SECRET和 32 字节的SYSTEM_AES_KEY，并备份到密钥管理工具。
• 设置DISABLE_REGISTRATION=true，新成员走管理员邀请。
• 部署在内外网隔离环境，不要直接暴露公网；必须对外时加 HTTPS 反向代理并收紧防火墙规则。
• 确认GIN_MODE=release（默认即生产模式，禁用 Swagger 文档）。
• 为容器设置 CPU/内存限制，配置日志轮转，避免日志撑满磁盘。
• 定期升级镜像版本，跟随官方安全补丁（升级方式：.env中设WEKNORA_VERSION后重新docker compose pull && docker compose up -d）。

性能要点

• 解析吞吐：大批量 PDF 时调大DOCREADER_PDF_RENDER_PARALLELISM（渲染并行进程数）和DOCREADER_ODL_MAX_WORKERS，CPU 富余时收益明显。
• 任务并发：Asynq 工作池默认核心并发 8、富化并发 12，可在.env的WEKNORA_ASYNQ_*_CONCURRENCY调整，也能在系统设置页运行时热调，无需重启。
• Embedding 限流：调用远程模型出现 429 时调小CONCURRENCY_POOL_SIZE（默认 5）。
• 向量库选型：知识库超过百万级 chunk 时，可切换RETRIEVE_DRIVER到 Qdrant/Milvus/OpenSearch，或保留默认 postgres 的 HNSW 索引（对 1024 维向量有加速）。
• 资源监控：docker stats看容器水位；任务积压、失败重试可在前端「系统管理 → 运行时队列」面板查看，这是生产排障最有用的入口。

收尾：场景速查表

遇到问题优先看 docs/QA.md 的官方 FAQ 和 docs/ 目录下的专题文档（如 docs/开发指南.md），覆盖模型配置、图片失效、端口冲突等高频坑。部署完成后，建议从一篇你最常查的文档开始建库，先跑通「上传 → 解析 → 问答」闭环，再逐步叠加图谱、Agent 和 IM 渠道等能力。

【免费下载链接】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