三步完成 WeKnora 的 Docker 本地部署组件、配置与避坑清单【免费下载链接】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 完成 WeKnora 本地部署改对常用配置并处理最常见的启动报错。先回答三个问题个人电脑跑得动吗跑得动。默认配置只依赖 5 个容器frontend、app、docreader、postgres、redis2 核 CPU、4GB 内存的机器能跑如果本地跑 Ollama 大模型建议 8GB 以上。前置依赖有哪些只需要 Docker含 Docker Compose和 Git。想用本地模型的话再装一个 Ollama 并执行ollama serve即可。多久能跑通网络好的机器大约 10 分钟其中大半时间耗在拉镜像上。启动后首次使用还需要注册账号、在设置里配好 LLM 和 Embedding 模型另花 5 分钟左右。跑通最短路径先确认环境CPU 2 核以上内存 4GB 以上磁盘预留 20GB终端执行docker compose version有输出如果本机 80 或 8080 端口被占用先想好改成别的然后三步启动克隆仓库git clone https://gitcode.com/GitHub_Trending/we/WeKnora # 克隆项目 cd WeKnora复制环境配置模板里有大量注释可按需修改cp .env.example .env # 生成你自己的环境变量文件拉取镜像并启动docker compose pull # 拉取 frontend/app/docreader/postgres 等镜像 docker compose up -d # 后台启动核心服务也可以用./scripts/start_all.sh一条命令完成拉取与启动--stop停止--no-pull表示离线启动。验证是否成功浏览器打开http://localhost出现注册/登录页后端健康检查http://localhost:8080/health有响应docker compose ps里各容器均为 running 状态看懂它怎么跑起来 各容器的分工如下记住「frontend 只是代理重活都在 app 和 docreader 里」就够用了容器宿主端口职责frontend80Web 界面把请求反向代理到 appapp8080主服务API、RAG 流水线、任务队列docreader仅内部 50051文档解析gRPC不映射到宿主postgresParadeDB仅内部关系数据 向量检索免单独部署向量库redis仅内部缓存与异步任务队列neo4j / minio / searxng 等按需可选组件用--profile开启可选组件按 profile 启动例如docker compose --profile neo4j up -d开启知识图谱--profile full一键拉齐全部功能。改哪些配置最有用最常动的手都在.env里改完执行docker compose up -d使其生效APP_PORT8080 # 主服务宿主端口冲突时先改它 FRONTEND_PORT80 # 前端宿主端口80 被占改成 8081 即可 OLLAMA_BASE_URLhttp://host.docker.internal:11434 # 本地 Ollama 地址 STORAGE_TYPElocal # 文件存储后端local/minio/s3/oss 等 DISABLE_REGISTRATIONfalse # 生产环境建议设 true走邀请制端口改APP_PORT/FRONTEND_PORT后访问地址跟着变两个端口分别对应 API 和界面别改混。模型服务地址用本地 Ollama 时OLLAMA_BASE_URL保持默认即可容器内经host.docker.internal回到宿主机改用云端 API 则在设置界面填BASE_URL和API_KEY。存储类型STORAGE_TYPElocal存容器卷最省事多副本或需要外部访问图片时换minio并--profile minio启动。知识图谱.env里NEO4J_ENABLEtrue且用--profile neo4j启动文档解析后才会抽取图谱。分块策略在 config/config.yaml 里调整直接影响检索粒度knowledge_base: chunk_size: 512 # 单块字符数调小更精确、调大更连贯 chunk_overlap: 50 # 相邻块重叠字符数界面侧的常用项模型选择、多模态开关见设置页报错了先看这里 统一按「现象 → 原因 → 解法」排查。1.docker: command not found原因未安装 Docker 或安装后终端未刷新。 解法安装 Docker 并重启终端用docker compose version确认输出正常。2. 启动报port is already allocated前端打不开原因宿主机 80 或 8080 端口被其他程序占用。 解法在.env里把FRONTEND_PORT或APP_PORT改成空闲端口再docker compose up -d。3. 上传文档没反应、问答无结果原因LLM / Embedding 模型没配好这是最高频的「假故障」仓库 FAQ 里专门列了它docs/QA.md。 解法在设置界面或.env补齐INIT_LLM_MODEL_NAME、INIT_EMBEDDING_MODEL_NAME等变量然后看日志定位docker compose logs -f app docreader postgres # 实时跟踪主链路日志4. app 容器反复重启、健康检查不通过原因数据库连接信息不对或.env缺少SYSTEM_AES_KEY32 字节用于敏感字段加密。 解法核对DB_USER/DB_PASSWORD/DB_NAME三件套确认SYSTEM_AES_KEY已填再看docker compose logs app里的迁移报错。5. 无外网环境docker compose up卡住原因compose 默认会先拉取镜像离线必然失败。 解法在有网机器docker save导出镜像拷到目标机docker load导入然后./scripts/start_all.sh --no-pull # 跳过拉取直接用本地镜像启动开发、生产、离线怎么选维度本地开发生产环境离线环境启动方式make dev-startdev-appdev-frontend免重建镜像、前端热重载docker compose up -dWEKNORA_VERSION锁版本start_all.sh --no-pull镜像提前docker load模型来源本地 Ollama 最快云端 API 或自建 GPU 推理只能本地 Ollama日志级别LOG_LEVELdebugLOG_LEVELinfoinfo注册策略保持DISABLE_REGISTRATIONfalse设true配合邀请制docs/RBAC说明.md按需网络端口全开方便调试反代 内网访问不直接暴露公网完全隔离make dev-start # 只拉起 postgres/redis/docreader 基础设施 make dev-app # 后端本地运行支持 Air 热重载 make dev-frontend # 前端本地运行自动热更新选择依据一句话只是自己试功能选开发模式给团队用就锁版本、关注册、换强密码断网机器先把镜像搬进去。如果你只想要单机零依赖的极简版可以看看 Lite 形态它不依赖独立数据库和消息队列docs/LITE.md 里有完整对比。最后WeKnora 的部署复杂度主要来自镜像数量和模型配置容器编排本身只有五六个核心组件把.env里端口和模型两项改对剩下的交给docker compose。跑起来之后深入使用可以从官方文档站开始API 与环境变量的全量清单都在 website-docs/ 目录里。遇到问题先翻 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），仅供参考