企业官网建设流程全解析

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/WeKnora

WeKnora 是开源 LLM 知识平台，把原始文档变成可查询的 RAG 问答、推理 Agent 与自维护 Wiki。本文按"核对配置 → 一键启动 → 组件分工 → 场景化配置 → 稳定上线"的顺序，带你完成一次 WeKnora Docker 部署，并覆盖本地部署后的生产环境配置与常见问题处理。

最低配置自检：部署前先核对这一张表

先对硬件，再对软件。两条都不满足时，容器起来也会卡。

一行自检命令，输出即判断依据：

nproc && free -h && df -h . && docker compose version

配置档位对照：

• 2 核 + 4 GB：体验功能可用，别传大文件，别跑本地模型。
• 4 核 + 8 GB：开发与测试够用。
• 8 核 + 16 GB 以上：生产可用，本地大模型也稳。

一键部署主流程：四步到可访问 🚀

第 1 步：获取代码

拉取仓库，compose 文件与启动脚本都在根目录：

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

看到docker-compose.yml与 scripts/start_all.sh 即通过。

第 2 步：初始化环境配置

cp .env.example .env # 复制模板为 .env，运行时参数全部从这里读

app 服务通过env_file直接读取整个 .env.example 模板生成的文件，注意别把它提交进版本库。ls .env不再报错即通过。

第 3 步：一键启动

scripts/start_all.sh 支持按场景选参：

./scripts/start_all.sh # 默认：尝试拉起 Ollama 并启动全部容器 ./scripts/start_all.sh -d # 已有远程模型：只起容器，跳过 Ollama ./scripts/start_all.sh --no-pull # 离线环境：不拉镜像，用本机已有的

脚本先探测 Docker 与镜像，再执行docker compose up -d。

第 4 步：验证访问

docker compose ps # 查看五件套状态 curl -f http://localhost:8080/health # app 健康检查端点

看到 frontend、app、postgres、redis、docreader 五个容器全部处于运行状态，curl 返回 200，浏览器打开 http://localhost 出现登录页，即通过。

系统速览：搞清 Docker 部署里每个服务的分工 🧩

整套结构像一个开放图书馆：frontend 是借阅台，app 是值守馆员，docreader 是图书加工师，postgres 是书架档案，redis 是预约登记板。只有 80 与 8080 映射到宿主机，其余三个只走容器内网——端口少暴露一层，攻击面就少一层，这也是默认 compose 的设计意图。

需要对象存储、Neo4j 图谱、SearXNG 搜索时，按 docker-compose.yml 中的 profile 追加，例如docker compose --profile minio up -d。

生产环境改造：高频改动就这三处 ⚙️

一、换端口与模型地址

改哪里：.env.example 生成的.env两行。

APP_PORT=8081 # 后端对外端口，默认 8080 OLLAMA_BASE_URL=http://192.168.1.10:11434 # 指向你的模型服务

为什么：共享机器上 80/8080 常被占用；模型服务不在本机时，默认值host.docker.internal够不着，必须改地址。

怎么验证：curl http://localhost:8081/health返回 200；模型也可在 Web 设置页配置，不用动文件。

二、分块等检索参数

改哪里：config/config.yaml 的knowledge_base段。该文件以只读方式挂载进容器，改完重启 app 即生效，不重建镜像。

knowledge_base: chunk_size: 512 # 分块字符数：FAQ 类调小，长文调大 chunk_overlap: 50 # 相邻块重叠，防止语义在边界被截断

为什么：分块粒度直接决定召回质量，块太大稀释关键词密度，太小丢失上下文。

怎么验证：上传一篇测试文档，在分块编辑页核对块长与切分位置。

三、开发、生产、离线三环境差异

改动全部落在.env，一行一项对照：

稳定性自检与高频问答：生产上线前最后过一遍 🛡️

上线前自检清单

• DB_PASSWORD、REDIS_PASSWORD已改掉默认值
• 重新生成JWT_SECRET与 32 字节SYSTEM_AES_KEY——AES 密钥丢失后，已加密凭证不可恢复
• DISABLE_REGISTRATION=true已设置
• 对外仅暴露 80 与 8080，数据库、缓存端口未映射
• postgres-data卷有备份脚本，且完整跑过一次恢复
• GIN_MODE=release

高频问题问答

问：浏览器访问 http://localhost 连不上？

答：先docker compose ps看 frontend 是否存活；多数是 80 端口被占，把.env里FRONTEND_PORT改成 8081 后执行docker compose up -d。

问：app 容器反复重启？

答：docker compose logs app看报错。最常见是.env中DB_USER、DB_PASSWORD、DB_NAME与 postgres 实际值不一致，三项对齐即可。

问：能登录，一问话就报模型连接失败？

答：OLLAMA_BASE_URL指向的地址从容器内不可达。先在宿主机执行curl http://你的地址:11434/api/tags确认可达再写入.env；模型服务就在宿主机上时，容器里要用host.docker.internal而非 localhost。

问：文档状态一直停在"解析中"？

答：docker compose logs docreader查原因；若文件超限，调大.env中MAX_FILE_SIZE_MB（默认 50），改完同时重启 app 与 frontend。

问：执行启动脚本提示 docker: command not found？

答：Docker 未安装或守护进程未启动。装好并启动服务后，docker compose version能打印版本号即恢复。

进阶路线

• 可选服务与 profile 全集：docker-compose.yml
• 内置模型声明与目录覆盖：website-docs/03-features/06-models.md
• 轻量单机版部署：docs/LITE.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