WeKnora Helm Chart 部署指南在 Kubernetes 上部署 AI 知识库 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/WeKnoraWeKnora 是一个开源的 AI 知识库 RAG 平台将文档解析、向量检索与 BM25 混合检索、LLM 对话集成和多租户加密能力整合为一体。本指南基于仓库中 helm/README.md 及helm/目录下的 Chart 源码系统讲解如何使用 Helm 3 在 Kubernetes 集群上一键部署 WeKnora 全套组件后端 API、前端 UI、Docreader 文档解析服务、PostgreSQL/ParadeDB 与 Redis并深入解析每个配置参数的作用、模板注入逻辑与生产级安全实践。读完本文你将掌握从快速安装、接入外部 LLM、启用 Ingress 与可选组件MinIO/Neo4j/Qdrant到升级、卸载与排障的完整运维闭环。Chart 概览与组件架构helm/是一个标准 Helm v2apiVersion: v2Application 类型 Chart当前 Chart 版本为0.1.0对应应用版本appVersion: v0.8.0并要求 Kubernetes 版本不低于 1.25见 helm/Chart.yaml。它把一个完整的 WeKnora 知识库平台拆分为以下几个可独立启停的组件Frontend基于 Vue.js 的 Web UIwechatopenai/weknora-ui由 Nginx 提供静态资源并反向代理后端AppBackend基于 Go/Gin 的 API 服务器wechatopenai/weknora-app对外暴露 8080 端口负责知识库管理、检索、会话与 LLM 调用Docreader文档解析服务wechatopenai/weknora-docreader通过 gRPC 协议默认docreader:50051向 App 提供 PDF、DOCX、HTML 等多格式解析能力PostgreSQLParadeDB默认使用paradedb/paradedb镜像在 PostgreSQL 之上提供向量检索pgvector 类能力与 BM25 全文检索是默认的检索后端Redis用作流管理Stream Manager与异步任务队列Async Queue例如文档处理任务、会话流式输出等。各组件通过集群内 Service 名互相引用整体流量走向如下来自 helm/README.md 的架构示意┌─────────────┐ │ Ingress │ └──────┬──────┘ │ ┌───────────────┴───────────────┐ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ Frontend │ │ Backend │ │ (Vue.js) │ │ (Go/Gin) │ └─────────────┘ └──────┬──────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Docreader │ │ PostgreSQL │ │ Redis │ │ (gRPC) │ │ (ParadeDB) │ │ (Queue) │ └─────────────┘ └─────────────┘ └─────────────┘前置条件Kubernetes 1.25Chart 在Chart.yaml中声明了kubeVersion: 1.25.0-0的硬性约束Helm 3.10支持 Chart 的模板语法与lookup函数底层基础设施需支持 PV ProvisionerPostgreSQL、Redis、上传文件数据都需要持久化存储Ingress Controller推荐 nginx-ingress如需从集群外访问 Web UI需要启用 Ingress。快速开始一条命令拉起全套组件首次安装只需提供三个必填 Secret数据库密码、Redis 密码、JWT 签名密钥helm install weknora ./helm \ --namespace weknora \ --create-namespace \ --set secrets.dbPasswordyour-db-password \ --set secrets.redisPasswordyour-redis-password \ --set secrets.jwtSecretyour-jwt-secret安装完成后Helm 会在终端输出 helm/templates/NOTES.txt 渲染的提示信息包括未启用 Ingress 时使用端口转发访问kubectl port-forward svc/frontend -n weknora 8080:80 # 然后打开 http://localhost:8080已部署组件清单含各组件镜像连接 LLM 的环境变量示例排障常用命令。注意secrets.dbPassword、secrets.redisPassword、secrets.jwtSecret三个参数在 helm/templates/secrets.yaml 中通过required函数强校验缺失时helm install会直接报错终止这是 Chart 主动拒绝“裸奔部署”的设计。安装场景进阶启用 Ingress 对外暴露helm install weknora ./helm \ --namespace weknora \ --create-namespace \ --set ingress.enabledtrue \ --set ingress.hostweknora.example.com \ --set ingress.tls.enabledtrue \ --set ingress.tls.secretNameweknora-tls \ --set secrets.dbPasswordsecure-password \ --set secrets.redisPasswordsecure-password \ --set secrets.jwtSecret$(openssl rand -base64 32)从 helm/templates/ingress.yaml 可以看到路由规则的设计/api前缀路径路由到名为app的后端 Service必须放在前面因为更具体的路径优先匹配/兜底路由到名为frontend的 Service默认携带一组对知识库平台非常关键的 Nginx 注解定义于 helm/values.yaml 的ingress.annotationsannotations: nginx.ingress.kubernetes.io/proxy-body-size: 100m nginx.ingress.kubernetes.io/proxy-connect-timeout: 60 nginx.ingress.kubernetes.io/proxy-read-timeout: 3600 nginx.ingress.kubernetes.io/proxy-send-timeout: 3600其中proxy-body-size: 100m保证大文件上传不被 Nginx 拦截proxy-read-timeout/send-timeout: 3600为长耗时的 LLM 流式问答留足通道。接入外部 LLM以 Ollama 为例WeKnora 本身不包含模型推理能力需要对接 LLM 后端。Chart 通过app.extraEnv向 App 容器注入任意环境变量helm install weknora ./helm \ --namespace weknora \ --create-namespace \ --set app.extraEnv[0].nameOLLAMA_BASE_URL \ --set app.extraEnv[0].valuehttp://ollama.ollama:11434 \ --set app.extraEnv[1].nameINIT_LLM_MODEL_NAME \ --set app.extraEnv[1].valueqwen2.5:7b \ --set secrets.dbPasswordsecure-password \ --set secrets.redisPasswordsecure-password \ --set secrets.jwtSecret$(openssl rand -base64 32)app.extraEnv的注入实现在 helm/templates/app.yaml 末尾{{- with .Values.app.extraEnv }}会将列表原样渲染为容器的 env 条目。结合 docker-compose.yml 中OLLAMA_BASE_URL、INIT_LLM_MODEL_NAME等变量的定义可以推断 WeKnora 的模型层兼容 Ollama本地、OpenAI API 兼容端点、Qwen/DeepSeek 等常见 LLM 服务安装后也可在 Web 界面的模型设置中继续补充模型配置。生产环境安装使用 values 文件生产部署建议把配置固化为values-production.yaml文件# values-production.yaml global: storageClass: fast-ssd app: replicaCount: 3 resources: requests: cpu: 500m memory: 1Gi limits: cpu: 2 memory: 4Gi postgresql: persistence: size: 100Gi ingress: enabled: true host: weknora.company.com tls: enabled: true secretName: weknora-tls secrets: existingSecret: weknora-secrets # Use pre-created secrethelm install weknora ./helm \ --namespace weknora \ --create-namespace \ -f values-production.yaml该示例综合了四个生产要点指定高性能存储类global.storageClass、扩展 App 副本数并设置资源上限滚动更新策略maxSurge: 1maxUnavailable: 0见 helm/templates/app.yaml、扩大数据库 PVC 容量、复用预创建的 Secret 而非在 values 中明文写密码。配置参数全解以下参数表完整继承自 helm/README.md 的 Configuration 章节并结合 helm/values.yaml 的默认值与注释进行扩充。Global 全局参数参数描述默认值global.storageClass所有 PVC 使用的存储类设为-表示使用集群默认存储类global.imagePullSecrets私有镜像仓库的拉取凭证[]global.podSecurityContextPod 级安全上下文默认启用seccompProfile: RuntimeDefault见 values.yamlglobal.containerSecurityContext容器级安全上下文默认allowPrivilegeEscalation: false见 values.yamlServiceAccount参数描述默认值serviceAccount.create是否创建 ServiceAccounttrueserviceAccount.nameServiceAccount 名称留空自动生成serviceAccount.annotationsServiceAccount 注解{}serviceAccount.name的解析逻辑定义在 helm/templates/_helpers.tpl 的weknora.serviceAccountName中创建时默认取 release 全名不创建时回退到default。此外 values.yaml 还提供automountServiceAccountToken默认false与labels等未在 README 中列出的控制项。App后端参数描述默认值app.enabled是否启用后端trueapp.replicaCount副本数1app.image.repository镜像仓库wechatopenai/weknora-appapp.image.tag镜像标签使用appVersionapp.resources资源请求与限制requests: 100m/256Milimits: 1/1Giapp.env内置环境变量见下文见 values.yamlapp.extraEnv附加环境变量[]值得展开的是app.env中的一组关键运行参数均来自 helm/values.yaml环境变量作用Chart 默认值GIN_MODEGin 运行模式release为生产模式releaseRETRIEVE_DRIVER检索引擎驱动可选postgres、elasticsearch_v7、elasticsearch_v8、qdrant等postgresSTORAGE_TYPE文件存储类型可选local、minio、cos、tos、s3等localLOCAL_STORAGE_BASE_DIR本地文件存储目录对应 PVC 挂载点/data/files/data/filesSTREAM_MANAGER_TYPE流管理器类型redisCONCURRENCY_POOL_SIZE文档处理并发池大小5AUTO_RECOVER_DIRTY是否自动回收卡在 processing 状态的脏任务trueWEKNORA_SANDBOX_DOCKER_ENABLED是否启用 Docker 沙箱开启等同获得宿主机 root 权限默认关闭false在 helm/templates/app.yaml 中App 容器还硬编码了若干与集群内 Service 强绑定的连接信息理解这些固定值有助于排查问题DB_HOSTpostgres、DB_PORT5432DB_USER/DB_PASSWORD/DB_NAME通过secretKeyRef从 Secret 注入REDIS_ADDRredis:6379、REDIS_DB0、REDIS_PREFIXstream:密码同样取自 SecretDOCREADER_ADDRdocreader:50051指向 Docreader 的 gRPC ServiceJWT_SECRET、SYSTEM_AES_KEY均通过secretKeyRef引用 Secret当neo4j.enabledtrue时自动注入NEO4J_ENABLEtrue、NEO4J_URIbolt://neo4j:7687及从 Secret 读取的 Neo4j 凭证。Frontend参数描述默认值frontend.enabled是否启用前端truefrontend.replicaCount副本数1frontend.image.repository镜像仓库wechatopenai/weknora-uifrontend.image.tag镜像标签latesthelm/templates/frontend.yaml 会注入APP_HOST默认app与APP_PORT默认后端 Service 端口 8080两个环境变量让 Nginx 容器知道如何反代后端同时以emptyDir挂载/var/cache/nginx与/var/run满足 Nginx 对可写临时目录的需求。Service 名固定为frontend被 Ingress 引用。PostgreSQLParadeDB参数描述默认值postgresql.enabled是否启用 PostgreSQLtruepostgresql.image.repository镜像仓库paradedb/paradedbpostgresql.image.tag镜像标签v0.18.9-pg17postgresql.persistence.enabled是否启用持久化truepostgresql.persistence.sizePVC 容量10Gihelm/templates/postgres.yaml 中数据库使用Recreate 更新策略避免多副本同时挂载同一数据卷造成数据损坏POSTGRES_USER/PASSWORD/DB全部取自 Secret数据目录为/var/lib/postgresql/data/pgdata就绪/存活探针均使用pg_isready。Redis参数描述默认值redis.enabled是否启用 Redistrueredis.image.repository镜像仓库redisredis.image.tag镜像标签7-alpineredis.persistence.enabled是否启用持久化trueredis.persistence.sizePVC 容量1Gihelm/templates/redis.yaml 使用redis-server --requirepass $(REDIS_PASSWORD) --appendonly yes --dir /data启动开启 AOF 持久化密码来自 Secret探针通过redis-cli -a $REDIS_PASSWORD ping | grep PONG验证鉴权后的连通性。Ingress参数描述默认值ingress.enabled是否启用 Ingressfalseingress.classNameIngressClass 名称nginxingress.host域名weknora.example.comingress.tls.enabled是否启用 TLSfalseingress.tls.secretNameTLS 证书 Secret 名称Secrets参数描述默认值secrets.dbUser数据库用户名postgressecrets.dbPassword数据库密码必填secrets.dbName数据库名weknorasecrets.redisPasswordRedis 密码必填secrets.jwtSecretJWT 签名密钥必填secrets.existingSecret使用已有 Secret 而不是自动创建values.yaml 中还有一些 README 未列出的 Secret 细节值得关注secrets.redisUsernameRedis 6.0 ACL 用户名可选secrets.systemAesKey数据库敏感字段 AES-256 加密主密钥必须恰好为 32 字节。加密范围覆盖租户 API Key、模型 API Key、向量库凭证、Web Search Provider 密钥、WeKnoraCloud AppSecret 等。若留空首次安装时会随机生成 32 位值。可选组件对应 docker-compose profiles参数描述默认值minio.enabled启用 MinIO 作为 S3 兼容存储falseneo4j.enabled启用 Neo4j 知识图谱GraphRAGfalseqdrant.enabled启用 Qdrant 向量数据库false这三个开关与 docker-compose.yml 中的minio、neo4j、qdrantprofile 一一对应。启用细节MinIO需同时设置minio.rootPassword以及可选的rootUser默认minioadmin持久化默认 20GiNeo4j启用后 Chart 自动向 App 注入NEO4J_ENABLEtrue并创建包含NEO4J_USERNAME/NEO4J_PASSWORD的 Secret 条目此时必须设置neo4j.password否则required校验失败。NEO4J_ENABLE是知识图谱的唯一开关旧的ENABLE_GRAPH_RAG已废弃、Go 主应用不再读取见 helm/templates/app.yaml 与 helm/templates/secrets.yaml 的注释。Neo4j 镜像标签为2025.10.1与 docker-compose 保持一致Qdrant作为备选向量库持久化默认 10Gi。启用后可配合app.extraEnv将RETRIEVE_DRIVER指向 Qdrant。源码视角模板实现的关键设计依赖硬编码的固定 Service 名从 helm/templates/app.yaml、helm/templates/postgres.yaml、helm/templates/redis.yaml、helm/templates/docreader.yaml 的 Service 定义可以看到一个共同设计Service 名称被刻意固定为app、postgres、redis、docreader、frontend而不是标准的release-name-组件名命名。模板注释明确说明这是为了让 App 容器的DB_HOST、REDIS_ADDR、DOCREADER_ADDR以及前端 Nginx 和 Ingress 的反代目标可以稳定解析。这意味着在同一 Namespace 内多次部署时需要注意 Service 名冲突。Secret 的滚动升级安全helm/templates/secrets.yaml 是模板中最值得研读的部分之一。它通过 Helm 内置的lookup函数实现“随机密钥的幂等生成”{{- $existing : lookup v1 Secret .Release.Namespace $secretName }} {{- $existingSystemKey : }} {{- if and $existing $existing.data }} {{- if index $existing.data SYSTEM_AES_KEY }} {{- $existingSystemKey index $existing.data SYSTEM_AES_KEY | b64dec }} {{- end }} {{- end }} {{- $systemAesKey : .Values.secrets.systemAesKey | default $existingSystemKey | default (randAlphaNum 32) }}其逻辑是优先使用用户显式设置的systemAesKey未设置则回读集群中已存在的 Secret 里的SYSTEM_AES_KEY并继续复用两者都为空时才生成新的随机值。这保证了每次helm upgrade不会重新滚动加密主密钥——否则旧密钥加密的数据如租户 API Key将永久无法解密界面上会显示enc:v1:...密文。命名与标签规范helm/templates/_helpers.tpl 提供了完整的命名与标签模板weknora.fullnamerelease 名与 chart 名拼接、截断 63 字符、weknora.componentLabels统一注入helm.sh/chart、app.kubernetes.io/version、app.kubernetes.io/managed-by、app.kubernetes.io/part-of: weknora与组件级app.kubernetes.io/component标签。排障时可以直接利用这些标签筛选资源例如kubectl get pods -n weknora -l app.kubernetes.io/instanceweknora kubectl logs -n weknora -l app.kubernetes.io/componentapp -f存储类、镜像与安全上下文的合并规则weknora.storageClasshelm/templates/_helpers.tpl约定global.storageClass为空时不写storageClassName使用集群默认存储类设为-时显式写入空字符串其余情况写入指定的存储类名。Pod 安全上下文则遵循“组件覆盖合并全局默认”的规则app组件可在app.podSecurityContext中覆盖global.podSecurityContext而 postgres/redis/frontend/docreader 直接使用全局值。安全最佳实践Secret 管理永远不要把密钥提交到 GitChart 提供三种可选方式Helm--set标志仅限测试环境helm install weknora ./helm --set secrets.dbPasswordxxxExternal Secrets Operator生产推荐把云厂商 Secret Manager 同步为集群 Secret 后复用secrets: existingSecret: weknora-external-secret使用existingSecret时Chart 不再创建自己的 Secrethelm/templates/secrets.yaml 最外层即{{- if not .Values.secrets.existingSecret }}守卫要求 Secret 内必须包含DB_USER、DB_PASSWORD、DB_NAME、REDIS_USERNAME、REDIS_PASSWORD、JWT_SECRET、SYSTEM_AES_KEY这些键各组件模板通过secretKeyRef按键名读取Sealed SecretsGitOps 场景把 Secret 加密成可入库的 SealedSecretkubeseal secret.yaml sealed-secret.yamlPod 安全Chart 遵循 CNCF 安全最佳实践定义于 helm/values.yaml 的 global 安全上下文默认不启用runAsNonRoot——因为官方镜像nginx、postgres、redis默认以 root 运行强制非 root 反而导致启动失败values.yaml 中对此有专门注释说明所有容器默认allowPrivilegeEscalation: false禁止提权Pod 默认启用seccompProfile: RuntimeDefaultServiceAccount 默认automountServiceAccountToken: false降低容器内被窃取 API 凭证的风险文件系统写权限按需最小化仅 App 容器挂载可写的/data/filesPVC前端 Nginx 只挂载两个emptyDir临时目录数据库与 Redis 各挂载各自的数据卷。升级与卸载升级helm upgrade weknora ./helm \ --namespace weknora \ --reuse-values--reuse-values会保留上一次安装时通过--set传入的值避免升级时因未重复传参而覆盖生产配置。由于 Secret 模板具备“lookup 复用旧密钥”的能力升级不会导致SYSTEM_AES_KEY轮换详见上文模板解析。卸载helm uninstall weknora --namespace weknora # 可选清理 PVC kubectl delete pvc -n weknora -l app.kubernetes.io/instanceweknoraHelm 默认不会删除 PVC避免误删数据需要按 release 标签显式清理持久化数据。故障排查指南基础排查# 查看 Pod 状态 kubectl get pods -n weknora # 后端日志 kubectl logs -n weknora -l app.kubernetes.io/componentapp -f # 前端日志 kubectl logs -n weknora -l app.kubernetes.io/componentfrontend -f由于模板统一注入了组件标签app.kubernetes.io/component可以精准筛选app、frontend、docreader、databasePostgreSQL、cacheRedis等组件。常见问题Pod 一直处于 Pending检查 PVC 是否已绑定kubectl get pvc -n weknora确认存储类存在kubectl get scConnection refused 错误等待所有 Pod 变为 ReadyApp 依赖数据库、Redis、Docreader 全部就绪检查 Service 端点是否正常kubectl get endpoints -n weknora数据库连接错误核对 Secret 中的账号密码是否与secrets.*配置一致查看 PostgreSQL 日志kubectl logs -n weknora -l app.kubernetes.io/componentdatabaseLLM 无法调用通过--set app.extraEnv[...]确认OLLAMA_BASE_URL等变量已正确注入可用kubectl exec进入容器env验证若使用了 Ollama确认集群网络可以连通 Ollama 的 Service 地址。从 docker-compose 到 Kubernetes 的迁移对照这份 Chart 与仓库根目录的 docker-compose.yml 存在清晰的对应关系理解这种映射有助于快速定位“compose 能跑、K8s 不行”的问题docker-compose 服务Helm 组件说明frontendweknora-uifrontend.*Nginx 反代注入APP_HOST/APP_PORTappweknora-appapp.*后端 API挂载/data/filesdocreaderdocreader.*gRPC 文档解析探针用grpc_health_probepostgresparadedb/paradedbpostgresql.*默认检索后端注意 compose 用v0.22.2-pg17Chart 默认v0.18.9-pg17可按需覆盖postgresql.image.tagredisredis.*队列与流管理minio/neo4j/qdrantprofileminio.*/neo4j.*/qdrant.*可选组件默认关闭两种部署方式共享同一套环境变量语义如RETRIEVE_DRIVER、STORAGE_TYPE、SYSTEM_AES_KEY因此迁移时可以把成熟的 compose.env经验直接映射为app.extraEnv。结语WeKnora 的 Helm Chart 是一个组件划分清晰、生产化考虑周全的部署方案固定 Service 名的“零配置互联”设计降低了上手门槛lookup幂等密钥保证了升级安全可选的 MinIO/Neo4j/Qdrant 组件让部署拓扑可以随知识图谱、向量检索等能力需求平滑演进。本文涉及的完整参数表可直接参考 helm/values.yaml模板实现细节可查阅 helm/templates/ 下的各个渲染文件若需要进一步了解平台自身的能力如文档解析、混合检索、RBAC 与加密机制可以继续阅读仓库根目录的 README.md 与 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），仅供参考