WeKnora 零门槛 Docker 部署：3 步跑通可用的 RAG 知识库-平芜编程栈

WeKnora 零门槛 Docker 部署：3 步跑通可用的 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/WeKnora

WeKnora 是一个开源 LLM 知识平台，能把原始文档变成可检索的 RAG 知识库、推理 Agent 和自维护 Wiki。本文带你用 Docker 部署 WeKnora：从机器自查、最小化启动到生产加固，全程只需基本 Linux 命令。适合第一次部署的零基础新手和想把 WeKnora 用到生产环境的普通开发者。

部署前自查：1 分钟确认机器够不够

WeKnora 用 Docker Compose 编排多个容器（即用一个文件声明并一起启动一组容器），核心包括前端、主应用、文档解析服务、PostgreSQL（ParadeDB 版，自带向量检索）、Redis 缓存，MinIO 和 Neo4j 等按需在 Compose profile 里开启。

环境类型	CPU	内存	磁盘	说明
开发测试	2 核+	4GB+	20GB+	仅跑核心服务 + 本地 Ollama
生产环境	4 核+	16GB+	100GB+	建议另备一台 Ollama/模型服务

在终端直接运行下面这段，确认资源与 Docker 可用：

echo "CPU: $(nproc) 核" echo "内存: $(free -h | awk '/Mem:/{print $2}')" echo "磁盘: $(df -h . | awk 'NR==2{print $4}') 可用" docker version --format '{{.Server.Version}}' docker compose version

执行bash -c '粘贴上面内容'或保存为check.sh后运行bash check.sh均可。经验提示：模型推理与文档解析同时跑时内存占用会翻倍，生产机器建议预留 50% 内存余量。

3 步跑通最小部署：从代码到首次访问

第 1 步，拉取代码：

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

第 2 步，复制并确认配置。启动脚本会自动从模板生成.env，你只需确认关键项：

cp .env.example .env # 生成 .env（脚本也会自动做这步） # 打开 .env 确认以下默认值是否满足你： # APP_PORT=8080 后端 API 端口 # FRONTEND_PORT=80 前端访问端口 # DB_DRIVER=postgres 主数据库类型 # OLLAMA_BASE_URL=http://host.docker.internal:11434 # 本地 Ollama 地址

第 3 步，一键启动。启动脚本会检查 Docker 环境、拉起本地 Ollama（未安装时自动安装）、拉取镜像并启动所有核心容器：

./scripts/start_all.sh # 启动 Ollama + 全部 Docker 容器

启动完成后访问：

前端界面：http://localhost:80（即http://localhost）
API 接口：http://localhost:8080（健康检查：/health）

首次进入前端会看到初始化配置向导，在这里配置 Ollama 状态与 LLM/Embedding 模型：

核心配置项解析：启动后该改哪些变量 ⚙️

.env里有上百个变量，新手只需盯住下面这几项：

配置项	默认值	作用	建议值
`APP_PORT`	`8080`	后端 API 的宿主机端口	冲突时改为未占用端口
`FRONTEND_PORT`	`80`	前端 nginx 的宿主机端口	被占用就改并同步改访问地址
`DB_DRIVER`	`postgres`	主数据库类型（postgres/mysql/sqlite）	生产保持`postgres`
`DB_PASSWORD`	模板示例值	数据库密码	生产必须换强密码
`REDIS_ADDR`	`redis:6379`	缓存与队列连接地址	保持默认
`STORAGE_TYPE`	`local`	文件存储后端（local/minio/s3 等）	单机用`local`，多机改`minio`
`OLLAMA_BASE_URL`	`http://host.docker.internal:11434`	LLM 服务地址，容器外用此地址连宿主机	远程推理改成你的服务端点
`LOG_LEVEL`	`debug`	日志级别（debug/info/warn/error）	生产改`info`

启动后还可以在前端设置页调整语言、解析引擎、存储引擎等运行时选项，不用重启容器：

常见报错速查：卡住时直接定位 🔍

启动脚本报 "未安装Docker，请先安装Docker" 或 "Docker服务未运行"

Q: 执行./scripts/start_all.sh提示 Docker 检查不通过 A: 确认 Docker 已安装且在运行：docker version；系统服务未启动则sudo systemctl start docker，再重跑脚本。

日志提示 "本地Ollama服务启动失败" 或 "远程Ollama服务不可访问"

Q: 容器起来了，但大模型相关功能不可用 A: 先验证 Ollama 是否可连：curl -s http://localhost:11434/api/tags。本地服务未起则systemctl restart ollama；配置的是远程地址则确认.env里OLLAMA_BASE_URL可达（OLLAMA_OPTIONAL=true时仅告警不阻断启动）。

前端打不开，疑似 80 端口冲突

Q: 浏览器访问http://localhost显示别的网站或拒绝连接 A: 查端口占用ss -tulpn | grep :80，确认是 WeKnora-frontend 容器监听；若是，改.env中FRONTEND_PORT后./scripts/start_all.sh -s停止再重新启动。

生产环境优化：安全加固与性能提速 🛡️

上线前过一遍这个清单：

DISABLE_REGISTRATION=true，禁止陌生人自助注册
DB_PASSWORD、REDIS_PASSWORD全部换成强随机值
显式设置 32 字节的SYSTEM_AES_KEY（丢失会导致已加密的 API Key 等字段无法解密）
GIN_MODE=release且LOG_LEVEL=info，关闭 Swagger 与调试日志
前置 nginx/网关挂 HTTPS，不裸奔 8080 端口
定期备份data-files等 Docker 数据卷（docker volume ls查看）
多实例共享 Redis 时设置WEKNORA_REDIS_NAMESPACE隔离频道

性能侧抓住三个关键动作，每项一行命令：

盯住资源水位，确认瓶颈在 CPU 还是内存：docker stats WeKnora-app WeKnora-docreader
调整后台任务并发（WEKNORA_ASYNQ_CORE_CONCURRENCY、CONCURRENCY_POOL_SIZE，见.env注释）后热重启应用容器：docker compose up -d app
确认 ParadeDB 向量/全文索引就位，检索性能依赖它：docker compose exec postgres psql -U postgres -d WeKnora -c "\di"

环境选型：开发、生产还是离线

三种典型场景的差异如下，按需选择：

对比项	开发环境	生产环境	离线环境
代码加载	只起基础设施（`docker-compose.dev.yml`），app/frontend 本地跑热重载	镜像内置，`docker compose up -d`	提前`docker pull`或加载镜像包
日志级别	`LOG_LEVEL=debug`	`info`	`warn`以上
网络	本地端口开放	仅暴露必要端口，HTTPS 入口	内网隔离，`--no-pull`启动
更新策略	实时改码即时生效	计划窗口`docker compose pull && up -d`	手动替换镜像后重启