WeKnora 集成完整指南

🎯 项目概述

本指南详细介绍了如何将腾讯开源的 WeKnora 知识库系统集成到 Servify 智能客服项目中，实现从简单的内存知识库到企业级 RAG 系统的升级。

📋 集成计划完成情况

✅ 已完成任务

项目路线图更新 ✅
- 更新了 README.md 中的第二阶段计划
- 将 WeKnora 集成作为 v1.1 的最高优先级
- 更新了技术架构图和技术栈说明
技术实施方案设计 ✅
- 完整的 WeKnora 客户端实现 (apps/server/pkg/weknora/)
- 增强的 AI 服务设计 (apps/server/internal/services/ai_enhanced.go)
- 降级策略和熔断器机制
- 数据结构和接口定义
开发环境配置 ✅
- Docker Compose 集成配置 (infra/compose/docker-compose.weknora.yml)
- 数据库初始化脚本 (scripts/init-db.sql)
- 环境变量配置模板 (.env.weknora.example)
- 配置文件模板 (config.weknora.yml)
部署和管理脚本 ✅
- 一键启动脚本 (scripts/start-weknora.sh)
- 知识库初始化脚本 (scripts/init-knowledge-base.sh)
- 知识库管理脚本 (scripts/manage-knowledge-base.sh)

🏗️ 技术架构

集成架构

Servify 智能客服
       ↓
   HTTP API 调用
       ↓
   WeKnora 知识库服务
       ↓
PostgreSQL (pgvector) + Redis + Elasticsearch

服务部署图

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Servify   │───▶│   WeKnora   │───▶│ PostgreSQL  │
│  (Port 8080)│    │ (Port 9000) │    │ (pgvector)  │
└─────────────┘    └─────────────┘    └─────────────┘
                           │
                           ▼
                  ┌─────────────┐
                  │    Redis    │
                  │ (缓存+队列) │
                  └─────────────┘

🚀 快速开始

1. 环境准备

# 检查环境
docker --version
docker-compose --version

# 克隆项目（如果还没有）
git clone <your-servify-repo>
cd servify

2. 配置环境变量

# 复制环境变量模板
cp .env.weknora.example .env

# 编辑环境变量，至少需要配置：
# - OPENAI_API_KEY: OpenAI API 密钥
# - WEKNORA_API_KEY: WeKnora API 密钥（可保持默认）
nano .env

3. 启动服务

# 一键启动开发环境
./scripts/start-weknora.sh dev

# 等待服务启动完成...

4. 初始化知识库

# 创建知识库并上传示例文档
./scripts/init-knowledge-base.sh

5. 验证集成

# 检查服务健康状态
curl http://localhost:8080/health
curl http://localhost:9000/api/v1/health

# 测试知识库搜索
./scripts/manage-knowledge-base.sh search "远程协助"

🔧 开发指南

项目结构

servify/
├── docs/
│   └── WEKNORA_INTEGRATION.md     # 本文档
├── scripts/
│   ├── start-weknora.sh           # 启动脚本
│   ├── init-knowledge-base.sh     # 知识库初始化
│   ├── manage-knowledge-base.sh   # 知识库管理
│   └── init-db.sql               # 数据库初始化
├── apps/
│   └── server/
│       ├── pkg/weknora/           # WeKnora 客户端
│       ├── client.go
│       └── types.go
│       └── internal/services/
│           └── ai_enhanced.go     # 增强的 AI 服务
├── infra/compose/docker-compose.weknora.yml     # WeKnora 部署配置
├── config.weknora.yml            # 配置文件模板
└── .env.weknora.example          # 环境变量模板

核心代码示例

WeKnora 客户端使用

// 创建客户端
client := weknora.NewClient(config, logger)

// 搜索知识库
response, err := client.SearchKnowledge(ctx, &weknora.SearchRequest{
    Query:           "用户问题",
    KnowledgeBaseID: "kb-id",
    Limit:           5,
    Strategy:        "hybrid",
})

// 上传文档
docInfo, err := client.UploadDocument(ctx, kbID, &weknora.Document{
    Type:    "text",
    Title:   "文档标题",
    Content: "文档内容",
    Tags:    []string{"tag1", "tag2"},
})

AI 服务集成

// 创建增强的 AI 服务
aiService := NewEnhancedAIService(config, logger)

// 处理用户查询（自动使用 WeKnora 或降级）
response, err := aiService.ProcessQuery(ctx, userQuery, sessionID)

📊 监控和维护

健康检查端点

Servify API: GET http://localhost:8080/health
WeKnora API: GET http://localhost:9000/api/v1/health
PostgreSQL: docker-compose -f infra/compose/docker-compose.yml exec postgres pg_isready
Redis: docker-compose -f infra/compose/docker-compose.yml exec redis redis-cli ping

日志查看

# 查看所有服务日志
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs -f

# 查看特定服务日志
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs -f servify
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs -f weknora

# 查看应用日志文件
tail -f logs/servify.log

性能监控

# 查看服务状态
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml ps

# 查看资源使用情况
docker stats

# 查看知识库统计
./scripts/manage-knowledge-base.sh stats

🔒 安全配置

生产环境配置

修改默认密钥：
- 更改 JWT_SECRET
- 更改 WEKNORA_API_KEY
- 更改数据库密码
网络安全：
- 限制 CORS 允许的域名
- 配置防火墙规则
- 使用 HTTPS
数据安全：
- 定期备份数据库
- 加密敏感数据
- 实施访问控制

配置示例

# 生产环境配置
security:
  cors:
    allowed_origins: ["https://yourdomain.com"]
  rate_limiting:
    enabled: true
    requests_per_minute: 60

📈 性能优化

🐛 故障排除

常见问题

1. WeKnora 服务无法启动

# 检查端口占用
lsof -i :9000

# 检查配置文件
docker-compose config

# 查看详细错误日志
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs weknora

2. 数据库连接失败

# 检查数据库状态
docker-compose -f infra/compose/docker-compose.yml exec postgres pg_isready -U postgres

# 检查网络连接
docker network ls
docker network inspect servify_servify_network

3. 知识库搜索无结果

# 检查文档是否上传成功
./scripts/manage-knowledge-base.sh list

# 检查索引状态
curl -H "X-API-Key: default-api-key" \
     http://localhost:9000/api/v1/knowledge/default-kb

🔄 更新和维护

版本更新

# 停止服务
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml down

# 更新镜像
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml pull

# 重新启动
./scripts/start-weknora.sh

数据备份

# 备份 PostgreSQL
docker-compose -f infra/compose/docker-compose.yml exec postgres pg_dump -U postgres servify > backup.sql

# 备份 WeKnora 数据
docker cp servify_weknora:/app/data ./backup/weknora_data

📚 相关资源

官方文档

社区资源

🎯 当前状态与后续方向

当前仓库里的 WeKnora 集成已经完成了角色调整：

WeKnora 不再作为系统内核能力存在，而是 KnowledgeProvider 的一个实现
AI 主流程已经迁移到 QueryOrchestrator，只依赖统一检索抽象
标准模式和增强模式都可以在不改 handler 协议的前提下切换到编排式实现
后续如果切换到其他知识库，只需要新增 provider adapter，不需要重写 AI 主流程

更细的实施任务已经迁移到 docs/implementation/02-ai-and-knowledge.md 与 docs/implementation/04-sdk-and-channel-adapters.md，当前两份 backlog 都已清零。

后续增量工作不再单独挂在 WeKnora 文档里，而是归到下面几个长期方向：

新增更多 KnowledgeProvider 实现，例如 pgvector、Milvus、Elasticsearch 或自研检索服务
补齐文档上传、批量索引、重建索引等管理能力的统一接口
把监控、缓存、故障恢复、安全策略沉到平台层，而不是绑定到某一个知识库实现
让 Web/API/App SDK 统一消费稳定的 AI/knowledge contract，而不是感知具体 provider

💬 支持和反馈

如有问题或建议，请：

查看本文档的故障排除部分
检查 WeKnora 官方文档
在项目 Issues 中提交问题
联系开发团队

当前结论：WeKnora 可以继续作为默认适配器使用，但系统架构已经不再依赖它，后续可以按成本、维护性和能力边界自由替换。