WeKnora企业级知识平台深度部署指南：5步构建智能RAG与Agent系统

【免费下载链接】WeKnora Open-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是一个基于大语言模型的开源知识管理平台，能够将原始文档转化为可查询的RAG系统、自主推理Agent和自维护的Wiki知识库。通过本指南，您将掌握WeKnora完整的企业级部署流程，构建智能化的知识管理系统。

项目概述与技术价值

WeKnora作为腾讯开源的企业级AI知识框架，提供了从文档理解、语义检索到智能问答的完整解决方案。该平台围绕三大核心能力构建：基于RAG的快速问答系统、自主执行多步骤任务的ReAct智能代理，以及自动从原始文档生成结构化Markdown知识库的Wiki模式。WeKnora支持从飞书、Notion、语雀等20+数据源自动同步知识，处理PDF、Word、图像、Excel等10+文档格式，并可通过IM渠道如企业微信、飞书、Slack和Telegram提供问答服务。

平台采用完全模块化架构，支持本地和私有云部署，确保数据主权，并集成了Langfuse提供全面的可观测性，包括代理推理、令牌使用和管道追踪。其企业级RBAC权限管理支持4级角色矩阵，为多租户场景提供完善的访问控制和审计日志。

系统架构深度解析

WeKnora采用现代化的微服务架构，各个组件分工明确，支持灵活的扩展和替换。系统架构分为输入渠道、核心引擎、存储层和外部服务四个主要层次。

输入渠道层支持Web UI、IM机器人、CLI命令行、Chrome浏览器扩展、网站嵌入小部件和微信小程序等多种接入方式。核心引擎层包括文档处理、RAG与Agent引擎，负责文档解析、向量化、智能检索和推理决策。存储层采用PostgreSQL关系数据库、向量数据库、Neo4j知识图谱存储和MinIO对象存储的混合方案。外部服务层集成了OpenAI、DeepSeek、通义千问等20+LLM提供商，以及DuckDuckGo、Bing、Google等网络搜索引擎。

数据处理与问答流程采用三阶段设计：数据准备与索引阶段包括数据源加载、文档处理、嵌入向量化和存储；查询与检索阶段支持查询重写、混合检索和重排序；生成与响应阶段通过LLM模型生成最终答案。这种架构设计确保了高可扩展性和灵活性，每个组件都可以根据业务需求进行替换或升级。

环境准备与依赖检查

在开始部署前，需要确保系统满足以下基本要求：

系统环境要求

• Docker 20.10及以上版本
• Docker Compose 2.0及以上版本
• 至少4GB可用内存
• 20GB以上磁盘空间
• 支持AVX指令集的CPU（用于向量计算）

网络配置确认

• 确保能够访问Docker Hub镜像仓库
• 检查80、8080、5432、6379、7474等端口是否可用
• 确认网络连接稳定，能够下载必要的依赖包

存储准备

• 为PostgreSQL数据库预留至少10GB存储空间
• 为MinIO对象存储预留至少20GB存储空间
• 建议使用SSD存储以提高向量检索性能

权限配置

• 确保当前用户具有Docker和Docker Compose的执行权限
• 配置适当的防火墙规则，允许容器间通信
• 为生产环境配置SSL证书和域名解析

服务部署实战步骤

第一步：获取项目源码与基础配置

通过以下命令获取最新的WeKnora项目代码：

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

复制环境配置文件并进行个性化设置：

cp .env.example .env

主要配置项包括数据库类型选择、存储服务配置、本地LLM服务地址和前后端服务端口。关键配置参数如下：

• DATABASE_TYPE: 数据库类型（postgresql/sqlite）
• VECTOR_DB_TYPE: 向量数据库类型（pgvector/elasticsearch/milvus）
• LLM_PROVIDER: LLM提供商（openai/deepseek/qwen）
• OBJECT_STORAGE_TYPE: 对象存储类型（local/minio/s3）
• NEO4J_ENABLE: 是否启用Neo4j知识图谱

第二步：一键启动核心服务

使用自动化脚本快速启动所有组件：

./scripts/start_all.sh

此脚本会自动启动PostgreSQL、Redis、MinIO等基础设施服务，并启动WeKnora应用服务。启动完成后，可以通过以下命令检查服务状态：

docker-compose ps

第三步：启用可选功能组件

WeKnora支持通过Docker Compose Profiles启用可选功能组件，多个Profile可以组合使用：

# 启用知识图谱功能
docker-compose --profile neo4j up -d

# 启用对象存储功能
docker-compose --profile minio up -d

# 启用可观测性功能
docker-compose --profile langfuse up -d

# 组合启用多个功能
docker-compose --profile neo4j --profile minio --profile langfuse up -d

第四步：初始化数据库与配置

首次启动后，需要初始化数据库并配置管理员账户：

# 运行数据库迁移
./scripts/migrate.sh

# 创建管理员账户
docker-compose exec app ./weknora admin create-user \
  --email admin@example.com \
  --password your_password \
  --name "Administrator"

第五步：验证部署结果

访问以下服务地址验证部署是否成功：

• Web UI界面：http://localhost
• 后端API服务：http://localhost:8080
• Langfuse追踪界面：http://localhost:3000（如果启用）
• Neo4j知识图谱：http://localhost:7474（如果启用）

配置调优与性能测试

数据库性能优化

针对PostgreSQL数据库进行性能调优：

# 在docker-compose.yml中调整PostgreSQL配置
postgres:
  image: postgres:16-alpine
  environment:
    POSTGRES_DB: weknora
    POSTGRES_USER: weknora
    POSTGRES_PASSWORD: weknora_password
    POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
  command: >
    postgres
    -c max_connections=200
    -c shared_buffers=256MB
    -c effective_cache_size=1GB
    -c maintenance_work_mem=64MB
    -c checkpoint_completion_target=0.9
    -c wal_buffers=16MB
    -c default_statistics_target=100
  volumes:
    - postgres_data:/var/lib/postgresql/data

向量检索优化

配置pgvector索引策略提升检索性能：

-- 创建HNSW索引加速向量检索
CREATE INDEX ON knowledge_chunks USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- 优化向量维度配置
ALTER TABLE knowledge_chunks ALTER COLUMN embedding SET DATA TYPE vector(1024);

缓存策略配置

调整Redis缓存策略优化响应时间：

redis:
  image: redis:7-alpine
  command: >
    redis-server
    --maxmemory 512mb
    --maxmemory-policy allkeys-lru
    --save 900 1
    --save 300 10
    --save 60 10000
  volumes:
    - redis_data:/data

负载测试与性能基准

使用内置测试工具进行性能基准测试：

# 运行端到端测试
make test-e2e

# 执行负载测试
docker-compose exec app ./weknora test load \
  --concurrent 10 \
  --duration 60s \
  --endpoint /api/v1/chat

故障诊断与运维指南

服务启动异常处理

当遇到服务启动失败时，可以通过以下方式排查：

检查容器运行状态：

docker-compose ps
docker-compose logs -f app
docker-compose logs -f postgres

验证数据库连接：

docker-compose exec postgres psql -U weknora -d weknora -c "\l"

检查存储服务状态：

docker-compose exec minio mc admin info local

常见问题解决方案

向量数据库连接失败：

# 检查向量数据库服务状态
docker-compose exec vector-db curl localhost:9200

# 验证pgvector扩展
docker-compose exec postgres psql -U weknora -d weknora -c "CREATE EXTENSION IF NOT EXISTS vector;"

文档解析服务异常：

# 检查文档解析器服务
docker-compose logs -f docreader

# 验证gRPC连接
docker-compose exec app curl http://docreader:50051/health

内存不足问题：

# 在docker-compose.yml中调整内存限制
services:
  app:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

日志收集与分析

配置集中式日志收集：

# 启用JSON格式日志
export LOG_FORMAT=json

# 设置日志级别
export LOG_LEVEL=debug

# 查看应用日志
docker-compose logs --tail=100 app

# 查看特定服务的详细日志
docker-compose logs --since="10m" app

扩展部署与生产实践

高可用架构部署

对于生产环境，建议采用高可用架构部署：

# docker-compose.prod.yml
version: '3.8'
services:
  app:
    image: weknora/app:latest
    deploy:
      mode: replicated
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    environment:
      - DATABASE_HOST=postgres-ha
      - REDIS_HOST=redis-sentinel
      - OBJECT_STORAGE_ENDPOINT=minio-cluster
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

监控与告警配置

集成Prometheus和Grafana进行监控：

# prometheus.yml配置
scrape_configs:
  - job_name: 'weknora'
    static_configs:
      - targets: ['app:8080']
    metrics_path: '/metrics'
    scrape_interval: 15s

  - job_name: 'postgres'
    static_configs:
      - targets: ['postgres-exporter:9187']

  - job_name: 'redis'
    static_configs:
      - targets: ['redis-exporter:9121']

备份与恢复策略

配置定期备份策略确保数据安全：

#!/bin/bash
# backup.sh
BACKUP_DIR="/backup/weknora"
DATE=$(date +%Y%m%d_%H%M%S)

# 备份PostgreSQL数据库
docker-compose exec postgres pg_dump -U weknora weknora > "${BACKUP_DIR}/db_${DATE}.sql"

# 备份MinIO数据
docker-compose exec minio mc mirror --overwrite local/ "${BACKUP_DIR}/minio_${DATE}/"

# 备份配置文件
cp -r config/ "${BACKUP_DIR}/config_${DATE}/"

# 压缩备份文件
tar -czf "${BACKUP_DIR}/weknora_backup_${DATE}.tar.gz" -C "${BACKUP_DIR}" .

安全加固措施

实施安全最佳实践：

# 安全配置示例
services:
  app:
    environment:
      - JWT_SECRET=your_secure_jwt_secret
      - ENCRYPTION_KEY=your_32_byte_encryption_key
      - CORS_ALLOWED_ORIGINS=https://your-domain.com
      - RATE_LIMIT_ENABLED=true
      - RATE_LIMIT_REQUESTS=100
      - RATE_LIMIT_PERIOD=1m
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

运维命令速查表

核心服务管理命令

# 启动所有服务
./scripts/start_all.sh

# 停止所有运行服务
./scripts/start_all.sh -s

# 系统环境健康检查
./scripts/start_all.sh -c

# 查看容器运行状态
docker-compose ps

# 实时监控应用日志
docker-compose logs -f app

# 重启单个服务
docker-compose restart app

数据库管理命令

# 执行数据库迁移
./scripts/migrate.sh

# 备份数据库
docker-compose exec postgres pg_dump -U weknora weknora > backup.sql

# 恢复数据库
docker-compose exec -T postgres psql -U weknora weknora < backup.sql

# 查看数据库大小
docker-compose exec postgres psql -U weknora -d weknora -c "SELECT pg_size_pretty(pg_database_size('weknora'));"

性能监控命令

# 查看系统资源使用
docker stats

# 监控API请求
docker-compose logs --tail=50 app | grep "HTTP"

# 检查向量检索性能
docker-compose exec app ./weknora test vector-search --count 1000

# 查看缓存命中率
docker-compose exec redis redis-cli info stats | grep -E "(keyspace_hits|keyspace_misses)"

通过本指南的详细步骤，您可以快速完成WeKnora平台的完整部署。无论是个人学习使用还是企业级应用场景，这套容器化方案都能提供稳定可靠的服务基础，助力您构建智能化的知识管理体系。WeKnora的模块化设计和丰富的功能集使其成为构建企业知识管理平台的理想选择。

【免费下载链接】WeKnora Open-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