WeKnora 本地部署3 条命令跑通2 个高频报错提前知道【免费下载链接】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 知识平台能把 PDF、Word 等原始文档变成可语义检索的 RAG 知识库并支持 Agent 推理与自动 Wiki 生成。本文带你用 Docker Compose 在本地完成一次完整部署并提前知道最常踩的两个坑。先确认你的场景和机器三类典型诉求想在本地把一份 PDF 灌进知识库做语义问答需要给团队搭一个文档机器人做日常知识查询或者要为内部系统接入一套可私有化的文档解析与向量检索能力。对号入座后看下机器配置是否够用途CPU内存磁盘开发机4 核16 GB50 GB生产机8 核32 GB200 GB部署依赖 Docker 与 Docker Compose。跑一条命令做自检docker compose version docker info --format {{.ServerVersion}}输出正常长这样Docker Compose version v2.x.x后跟一行 Docker 版本号说明环境就绪。部署前要做的 3 个选择存储怎么接。默认STORAGE_TYPElocal文件直接落在 app 容器的数据卷里单机开发最省事。文件量上来或要做备份换成 MinIOcompose 里已内置minioprofile或你已有的 S3/OSS/COS改.env对应字段即可不用动代码。模型走哪条路。三条路本机 Ollama默认OLLAMA_BASE_URL指向host.docker.internal:11434OLLAMA_OPTIONALtrue保证 Ollama 没启动时服务也不会起不来远程 API在.env填INIT_LLM_MODEL_BASE_URL/INIT_LLM_MODEL_API_KEY及对应 Embedding 配置或混合使用按模型分别指定。模型没配好是上传文档失败的头号原因务必先想清楚。跑在什么环境。开发机用make dev-startmake dev-appmake dev-frontend后端走 Air 热重载改代码 510 秒生效生产用固定镜像docker compose up -d离线内网提前把镜像 load 进主机启动时加--no-pull。从 clone 到看到页面的最短路径拉代码并复制出.envgit clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env里真正必须动的只有几项其余保持默认即可DB_USERpostgres # 内置 postgres 的用户 DB_PASSWORD你的数据库密码 # 必须与 compose 中 postgres 容器一致 INIT_LLM_MODEL_NAME对话模型名 # Ollama 或远程 API 的模型 INIT_EMBEDDING_MODEL_NAME向量模型名 INIT_EMBEDDING_MODEL_DIMENSION向量维度 # 如 1024拉镜像并启动核心服务frontend、app、docreader、postgres、redis 共 5 个容器docker compose pull docker compose up -d等约 1 分钟验证两件事。健康检查接口返回成功即后端就绪curl -s http://localhost:8080/health浏览器打开http://localhost端口 80 是前端能看到登录/注册页即部署完成。若 80 端口被占改.env中FRONTEND_PORT再docker compose up -d即可。高频报错收在这里按需展开报错原文port is already allocated → 端口冲突原因80 或 8080 被本机其他服务占用。修复sudo lsof -i :80找出占用进程改.env中FRONTEND_PORT/APP_PORT后重启容器。报错原文上传文档卡在解析或提示模型错误 → 模型未配置原因.env中 LLM/Embedding 模型变量缺失或地址不可达详见 常见问题排查。修复补全INIT_LLM_MODEL_*与INIT_EMBEDDING_MODEL_*字段docker compose restart app。报错原文Ollama 连接失败告警 → 本地模型服务未启动原因宿主机没有运行 Ollama。修复宿主机执行ollama serve确认OLLAMA_BASE_URL指向正确若改用远程 API 则无需理会OLLAMA_OPTIONALtrue只告警不阻断。需要知识图谱或链路追踪时按需叠加 profiledocker compose --profile neo4j --profile langfuse up -d可组合使用。出问题去哪里查上线前看什么排障入口就两个docker compose logs -f app docreader看实时日志docs/QA.md 覆盖了模型、图片显示、OCR 兼容性等高频问题。上线前自查清单数据库与 Redis 密码已替换默认值SYSTEM_AES_KEY已设置并妥善保管服务未直接暴露在公网GIN_MODErelease、日志级别调为 info数据卷纳入定期备份WEKNORA_VERSION固定为具体版本而非 latest跑通单机之后进阶方向主要是集群化与可观测Kubernetes 部署见 helm/README.mdAgent 全链路追踪可在.env配置 Langfuse 后在 Web UI 里直接查看每次对话的 Token 消耗与工具调用瀑布图。收束现在你有一台能解析文档、做语义检索并对外提供问答的 WeKnora 实例。更多接口与环境变量细节查 docs/ 下的官方文档即可。【免费下载链接】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），仅供参考
