WeKnora Docker 部署实战：4 个目标 5 个容器，从登录页到生产稳态

WeKnora Docker 部署实战4 个目标 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/WeKnoraWeKnora 是一个基于 LLM 的深度文档理解框架把原始文档变成三样东西可查询的 RAG 问答、能自主推理的 Agent、会自己更新的 Wiki。部署完你能拿到什么浏览器里能打开的 Web 界面默认 http://localhost、一套后端 API默认 http://localhost:8080以及一组可以按需扩展的容器化服务。这篇 WeKnora 部署指南不讲原理只按目标推进看到登录页 → 看懂容器分工 → 按场景定制 → 生产环境配置稳定上线。每个操作都给了成功标志照做即可每一步都知道自己成了没有。目标一跑起来看到登录页 先花 30 秒确认机器配置三条硬指标经验值以实际压测为准CPU4 核起步。2 核能跑但文档解析会明显变慢。内存8GB 起步。低于 4GB 建议直接换机器。磁盘50GB 可用空间。镜像加数据预留要留足。一条命令自检nproc free -h df -h .按输出对号入座配置能干什么2 核 4GB够体验核心功能别传大文件4 核 8GB够日常开发与测试8 核 16GB 以上够生产跑本地大模型也稳最短启动路径只留必要的命令git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env成功标志目录里能看到docker-compose.yml.env文件已生成。忘了复制.env也没关系启动脚本 检测到缺失会自动从模板补一份。然后是真正的一步./scripts/start_all.sh脚本先处理 Ollama没装会自动装、没起会自动起再拉起全部容器。成功标志终端打印所有服务启动完成并给出两个地址——前端 http://localhost、API http://localhost:8080。浏览器打开前端看到注册/登录页就算跑通了。不放心就再看一眼容器docker compose psfrontend、app、postgres、redis、docreader 五个服务全部处于 running 状态即成功。已有远程模型直接跳过 Ollama机器上已经有远程 LLM 服务、不想碰 Ollama 时只起容器./scripts/start_all.sh -d-d跳过 Ollama 只跑 Docker 服务容器齐了照样用docker compose ps验收。目标二看懂这 5 个容器各管什么默认部署常驻 5 个容器职责一张表说清容器对外端口干什么依赖frontend80Web 界面把请求转给 appappapp8080业务核心API、对话、文档入库redis、postgres、docreaderdocreader无容器内 50051把 PDF、Word 等解析成文本无postgres无容器内 5432存数据内置 ParadeDB 向量检索无redis无容器内 6379缓存与任务队列无拿邮局打个比方frontend 是窗口app 是分拣中心docreader 是文档核对间postgres 是档案室redis 是值班台。只有 80 和 8080 两个口映射到宿主机其余组件全走容器内网天然不对外暴露——这也是默认配置比裸跑更安全的原因。默认之外的组件都用 profile 按需追加不需要的一个都不会起docker compose --profile minio up -d # 对象存储 docker compose --profile langfuse up -d # 链路追踪minio 提供对象存储控制台在 9001 端口langfuse 拉起一套自建的链路追踪界面在 http://localhost:3000。完整 profile 清单——neo4j 知识图谱、qdrant、milvus 等——直接看 docker-compose.yml 里各服务的profiles字段。目标三改成自己想要的样子 ⚙️换端口与模型地址只动 .env 两行APP_PORT8081 # 后端对外端口默认 8080 OLLAMA_BASE_URLhttp://192.168.1.10:11434 # 指向你的模型服务改完docker compose up -d重载。成功标志新端口能访问到 API。模型也可以不走命令行直接在 Web 设置界面里配文档分块参数文件已挂载改完重启即生效分块策略直接决定检索质量。config/config.yaml 已挂载进容器改完重启 app 即生效不用重建镜像knowledge_base: chunk_size: 512 # 分块大小FAQ 调小、长文调大 chunk_overlap: 50 # 相邻块重叠字符防止断句界面上还能按单个知识库单独调分块取值范围与推荐值见分块指南。开发、生产、离线差异压成一张表改动全落在.env配置项开发生产离线日志级别LOG_LEVELdebugLOG_LEVELinfo同生产用户注册允许DISABLE_REGISTRATIONtrue同生产镜像获取在线拉取在线拉取启动加--no-pull用本地镜像模型来源本地 Ollama远程 LLM 地址预载本地模型运行模式GIN_MODEdebugGIN_MODErelease同生产生产环境配置层面就一句话保持GIN_MODErelease.env默认即是顺手换掉默认数据库密码齐了。目标四上线后别翻车 ️安全加固清单逐条打勾改掉.env里的默认DB_PASSWORD与REDIS_PASSWORD重新生成JWT_SECRET以及 32 字节的SYSTEM_AES_KEY丢了它库里已加密的凭证就再也解不开生产环境设DISABLE_REGISTRATIONtrue关掉注册入口对外只留 80 和 8080数据库、缓存端口保持不映射默认已如此定期备份postgres-data卷并且恢复演练至少完整走过一次稳定性体检3 条现成命令# 数据库连通性按 .env 实际账号库名替换 docker compose exec postgres psql -U postgres -d WeKnora -c SELECT 1;返回一行1即正常。# 各容器 CPU / 内存实时占用 docker stats哪个容器在烧资源一眼看穿。# 盯应用日志定位慢请求 docker compose logs -f app高频故障快速问答80 端口打不开现象浏览器访问 http://localhost 连不上。原因宿主机 80 端口被其他服务占了。处理.env把FRONTEND_PORT改成 8081执行docker compose up -d。app 容器反复重启现象docker compose ps里 app 状态不停跳。原因postgres 没就绪或.env里数据库账号密码对不上。处理docker compose logs app看报错逐项核对DB_USER、DB_PASSWORD、DB_NAME。对话时报模型连接失败现象能登录一问话就报错。原因OLLAMA_BASE_URL指向的地址从容器内访问不到。处理宿主机先执行curl http://你的地址:11434/api/tags通了再写进.env。文档上传后一直解析中现象文档状态卡在解析中不往前走。原因docreader 没通过健康检查或文件超过MAX_FILE_SIZE_MB默认 50MB。处理docker compose logs docreader查原因大文件就调大.env里的MAX_FILE_SIZE_MB。命令报 docker: command not found现象跑start_all.sh直接失败。原因Docker 没装或守护进程没起。处理装好 Docker 并启动服务docker compose version能打印版本即恢复。更多排障思路见官方排障文档。收个尾WeKnora 从装得上走到了跑得稳登录页、容器分工、场景定制、生产稳态四个目标都验收过了剩下的就是往里灌文档、问问题。挑一个方向继续分块策略调优website-docs/03-features/04-chunking.md开启知识图谱website-docs/03-features/09-knowledge-graph.md后端 API 全集website-docs/04-api/01-api-overview.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），仅供参考