Buzz：用本地 Whisper 免费高效离线转写音频的完整指南
2026/9/7 15:47:28
WeKnora 部署实战：从最小运行到生产加固的六步路径
【免费下载链接】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 问答、会自主编排检索与工具的推理代理、以及自我维护的 Wiki。如果你要在内网落一套私有知识库，或给团队接一个能答业务问题的问答入口，这套东西可以直接跑起来。下面按"能跑 → 跑得对 → 跑得稳 → 扛得住"的顺序展开，跳过那些不碰就不影响启动的部分。
📦 项目速览
一句话：喂文档，收答案。它负责解析（含 PDF/Word/Excel/XMind 等十余种格式）、切块、向量化、混合检索，再交给大模型生成带引用的回答；需要时代理会自己调用 MCP 工具、沙箱脚本和网络搜索来完成多步任务。适合两类人——要做企业知识沉淀的技术决策者，以及负责把它跑在服务器上的运维工程师。
🧭 部署前置条件
先把依赖对齐，能少走大量弯路。三项依赖的"最低"档是官方docker-compose.yml默认能起的最小组合（Postgres + Redis + 本地文件存储），"推荐"档对应生产常见规模。
| 依赖项 | 最低档 | 推荐档 | 说明 |
|---|---|---|---|
| 内存 | 8 GB | 16 GB 以上 | 向量库和解析都吃内存，Postgres 需独立预算 |
| 磁盘可用 | 20 GB | 50 GB 以上 | 文档原件、向量索引、容器镜像都要落盘 |
| CPU | 4 核 | 8 核以上 | 大扫描件解析可并行，核越多越短 |
| Docker | 20.10+ | 24.x | 需支持docker compose（v2 插件） |
| 网络端口 | 80 / 8080 空闲 | 同左 + 对象存储端口 | 前端 80，后端 API 8080 |
注意两点：默认组合里 Postgres 用的是 ParadeDB 镜像（paradedb/paradedb:v0.22.2-pg17，自带 pgvector 向量扩展），Redis 跑在 6379。这两个容器只挂在 compose 内部网络WeKnora-network上，不对外映射，所以主机防火墙只需放行 80 和 8080 两个端口。
🚀 最小可运行部署
整条链路是一条单向数据流：frontend（Nginx，80 端口）把请求代理到app（Go 主服务，8080 端口）；app通过 gRPC 调docreader（50051，只在内网，解析文档用）；两者都依赖postgres和redis。默认存储走本地磁盘，向量检索落在 Postgres 的 pgvector 里，所以不启动任何额外容器就能跑通最小闭环。
# 1. 拉代码 git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora # 2. 生成并编辑环境变量（必填项见下一节） cp .env.example .env nano .env # 3. 启动全部核心服务（自动检查环境、拉镜像、起容器） ./scripts/start_all.sh --all.env里有几处占位符必须替换，否则容器起不来或密钥不安全：
# 数据库（compose 里的 Postgres 用这三个建库） DB_USER=postgres DB_PASSWORD=<改成强密码> DB_NAME=WeKnora # Redis 密码（compose 的 redis 容器 --requirepass 读取它） REDIS_PASSWORD=<改成强密码> # 内置模型三件套（问答能用的前提） LLM_BASE_URL=<你的模型服务地址> LLM_API_KEY=<你的 key> LLM_MODEL_NAME=<模型名> EMBEDDING_BASE_URL=<向量模型地址> EMBEDDING_API_KEY=<向量模型 key> EMBEDDING_MODEL_NAME=<向量模型名>启动成功的三个标志：./scripts/start_all.sh --all尾部打印各服务状态且无Error；docker compose ps里app、frontend、docreader、postgres、redis均为Up（app 与 docreader 带healthy）；curl http://localhost:8080/health返回 200。三者齐备，最小闭环就绪。
⚙️ 关键配置解读
config/config.yaml被以只读方式挂载进app容器，改完docker compose up -d app重启即生效。下面只挑五个真正影响"答得准不准、跑得快不快"的参数，其余保持默认即可。
| 参数 | 默认值 | 为什么这么设 | 何时该改 |
|---|---|---|---|
conversation.embedding_top_k | 30 | 混合检索阶段粗召回的候选条数，30 在精度和耗时之间平衡，给重排序留足原料 | 高精度场景调到 50，召回不足时再往上 |
conversation.rerank_top_k | 30 | 重排序后的最终候选数，直接决定塞进大模型上下文多少片段 | 上下文窗口紧张就下调到 10-15 |
conversation.vector_threshold | 0.2 | 向量相似度门槛，0.2 偏松，宁可多召回再靠 rerank 过滤，避免硬门槛漏检 | 出现大量不相关命中时抬到 0.3 |
conversation.max_rounds | 5 | 多轮上下文保留轮数，5 轮覆盖绝大多数追问链 | 长对话场景调到 10，简单 FAQ 降到 3 |
knowledge_base.chunk_size | 512 | 分块大小，512 字对中英混排文档召回粒度最稳，过小丢上下文、过大稀释语义 | 长表格/代码多的库可上调到 768 |
chunk_overlap默认 50，约为chunk_size的 10%，作用是让相邻块保留边界重叠，避免一个段落被切断后语义断裂。它和chunk_size建议按同一比例联动，不要只改一个。检索质量想再精调，看keyword_threshold（0.3）和rerank_threshold（0.3）——前者管关键词匹配，后者管重排，两者都偏保守，先动上面五个再动这两个。
✅ 功能验证
部署完不要直接放量，按顺序逐项确认模块可用。每项给出命令和预期输出。
- 容器健康：
docker compose ps。预期app显示healthy，其余核心容器为Up。若有Restarting，先docker compose logs --tail 50 app看报错。 - 后端存活：
curl -s http://localhost:8080/health。预期返回 200 且非空。这是 compose 里 app 服务自身 healthcheck 探的同一地址。 - 前端可达：
curl -I http://localhost:80。预期HTTP/1.1 200，说明 Nginx 已把静态资源和服务端代理接好。 - 解析链路：在 Web UI 建一个知识库并上传一份 PDF，看文档状态从
processing变为已完成。这一步同时验证了app → docreader → Postgres的 gRPC 与入库链路，比单测更可信。 - 检索问答：用文档里能明确命中的问题提问，预期回答带引用来源且内容对得上。若答非所问，先查
embedding_top_k与模型是否配错。
🔍 运维与故障速查
监控接入：生产建议开 Langfuse 做可观测性。设LANGFUSE_ENABLED并填LANGFUSE_HOST、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY后，agent 的推理链路、token 用量、管线耗时会进入 Langfuse，LANGFUSE_SAMPLE_RATE控制在 0.1 左右即可。运行时还有内置任务队列面板，能看各阶段 worker 池并发和失败任务，配合docker stats看容器资源、Postgres 慢查询看数据库瓶颈。
高频故障按"现象 → 原因 → 解法"排查：
| 现象 | 常见原因 | 解法 |
|---|---|---|
app 一直Restarting | .env缺必填项或密钥长度不对（如SYSTEM_AES_KEY非 32 字节） | docker compose logs app定位；补全必填、密钥用 32 字节 |
| Postgres 连接失败 | Postgres 未就绪，app 先启动 | 等待postgres变healthy；depends_on已设service_healthy，勿绕过 |
文档卡在processing | 单文档超时或解析 worker 不足 | 调大WEKNORA_DOCUMENT_PROCESS_TIMEOUT（默认 2h）；DOCREADER_PDF_RENDER_PARALLELISM加并行 |
| 问答答非所问 | 向量/对话模型配错或RETRIEVE_DRIVER与库里不一致 | 核对LLM_*/EMBEDDING_*；确认RETRIEVE_DRIVER与实际存储一致 |
| 向量检索慢 | 向量库资源不足 | 独立给向量库加内存；缩小embedding_top_k |
🛡️ 生产加固
开发和生产差异集中在三类"必须项"，其余保持默认即可，不必为开发机单独维护一套。
安全（必须）：
# 生产务必关闭公开注册、收紧密钥 DISABLE_REGISTRATION=true GIN_MODE=release JWT_SECRET=<openssl rand -hex 32 生成> SYSTEM_AES_KEY=<必须恰好 32 字节，openssl rand -base64 32 后截断>SYSTEM_AES_KEY是数据库里 API Key 等敏感字段落盘加密的主密钥，丢失则所有已加密数据不可恢复，务必离线备份。WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLED=true可强制密码含大小写+数字+特殊字符。
网络隔离（必须）：对外只暴露 80（前端）和 8080（API）。Postgres、Redis、MinIO（9000/9001）、Neo4j（7687）默认只在WeKnora-network内部可达，不要额外ports映射到0.0.0.0。若用 MinIO 存原件，MINIO_USE_SSL=true开 TLS，并配访问策略。
高可用（可选）：要开知识图谱，加--profile neo4j起 Neo4j 并在.env设NEO4J_ENABLE=true（这是图谱唯一开关，旧的ENABLE_GRAPH_RAG已废弃）。要换独立向量库，按RETRIEVE_DRIVER选qdrant/milvus/weaviate对应 profile 启动。多副本 + 负载均衡属集群场景，超出单机 compose 范畴，以项目部署文档为准。
📋 快速参考
部署前
- Docker Compose v2 可用，主机 80 / 8080 端口空闲
- 内存 ≥ 8GB、磁盘 ≥ 20GB、CPU ≥ 4 核
.env必填项已替换：数据库三件套、Redis 密码、模型三件套
启动后
docker compose ps全部Up，app/docreader 带healthycurl http://localhost:8080/health返回 200- 前端 80 端口可访问，能登录
- 上传一份文档并完成解析，问答命中且带引用
生产上线前
DISABLE_REGISTRATION=true、GIN_MODE=releaseJWT_SECRET、SYSTEM_AES_KEY已换随机值并离线备份- 数据库/Redis/对象存储未对外映射，MinIO 开 TLS
延伸阅读（仓库内相对路径）：
- docs/快速开发模式说明.md — 本地快速起后端
- docs/使用其他向量数据库.md — 换 Qdrant/Milvus/Weaviate
- docs/开启知识图谱功能.md — Neo4j 图谱启用
- docs/RBAC说明.md — 多空间角色与审计
- config/config.yaml — 对话与检索参数源头
完成以上配置后，建议先用docker compose logs -f app盯 10 分钟确认无异常滚动日志，再放开真实流量。
【免费下载链接】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），仅供参考