WeKnora企业级容器化部署实战手册：从环境规划到运维优化的全流程指南

在当今AI驱动的文档理解与检索领域，WeKnora作为基于大语言模型(LLM)的框架，通过检索增强生成(RAG)范式提供深度文档理解、语义检索和上下文感知回答能力。本文将系统讲解WeKnora的容器化部署方案，涵盖环境规划、部署实施、架构解析、多场景适配及运维优化全流程，帮助技术团队实现企业级稳定部署。

1. 环境规划：构建容器化部署基础架构

1.1 系统环境评估与推荐配置

部署WeKnora前需确保基础环境满足以下要求：

• 操作系统：Linux内核3.10+（推荐Ubuntu 20.04/22.04 LTS）
• Docker版本：20.10.0+，Docker Compose版本：v2.0+
• 硬件配置：推荐8核CPU、16GB内存、50GB SSD存储（生产环境）
• 网络要求：开放80/443端口，确保容器间通信及外部访问

[!TIP] 使用docker info和docker-compose version命令验证Docker环境是否符合要求，低版本可能导致网络配置或资源限制功能异常。

1.2 网络架构设计与端口规划

WeKnora容器化部署需规划以下网络资源：

• 专用Docker网络：weknora-network（桥接模式）
• 服务端口映射表：

服务组件	容器内部端口	宿主机映射端口	协议	用途说明
app	8080	8080	TCP	主应用API服务
frontend	80	80	TCP	Web前端界面
postgres	5432	5432	TCP	关系型数据库
redis	6379	6379	TCP	缓存服务
minio	9000	9000	TCP	对象存储API
minio	9001	9001	TCP	对象存储控制台
neo4j	7474	7474	HTTP	图数据库Web界面
neo4j	7687	7687	Bolt	图数据库驱动端口
jaeger	16686	16686	HTTP	链路追踪界面

1.3 存储方案设计

WeKnora需要持久化存储以下数据：

• 数据库数据：使用Docker命名卷（postgres-data）
• 对象存储数据：使用Docker命名卷（minio-data）
• 应用配置文件：宿主机目录挂载（./config:/app/config）
• 日志数据：宿主机目录挂载（./logs:/app/logs）

[!WARNING] 生产环境建议使用外部存储系统（如NFS或云存储）挂载关键数据卷，避免容器删除导致数据丢失。

2. 部署实施：标准化容器编排流程

2.1 代码获取与环境准备

完成基础环境配置后，执行以下步骤准备部署文件：

1. 克隆项目代码库：

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

2. 创建环境配置文件：

cp .env.example .env

3. 配置核心环境变量（编辑.env文件）：

# 数据库配置
DB_DRIVER=postgres
DB_HOST=postgres
DB_PORT=5432
DB_USER=weknora
DB_PASSWORD=secure_password
DB_NAME=weknora_db

# 应用配置
APP_PORT=8080
FRONTEND_PORT=80
GIN_MODE=release

# 存储配置
STORAGE_TYPE=minio
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=minio_access_key
MINIO_SECRET_KEY=minio_secret_key

# LLM配置
OLLAMA_BASE_URL=http://ollama:11434
DEFAULT_EMBEDDING_MODEL=text-embedding-ada-002

2.2 容器编排与服务启动

使用Docker Compose实现一键部署：

1. 检查配置文件完整性：

./scripts/check-env.sh

2. 启动所有服务组件：

./scripts/start_all.sh -a

3. 验证服务状态：

docker-compose ps

[!TIP] 首次启动时添加--pull参数拉取最新镜像：./scripts/start_all.sh -a --pull，后续更新也可使用此参数。

2.3 部署验证与初始化

服务启动后执行以下验证步骤：

1. 检查应用健康状态：

curl http://localhost:8080/api/health

2. 初始化管理员账户：

docker-compose exec app ./weknoracli user create-admin \
  --username admin \
  --email [e-mail] \
  --password secure_admin_password

3. 访问前端界面： 打开浏览器访问 http://localhost:${FRONTEND_PORT}，使用管理员账户登录

3. 架构解析：容器化服务组件关系

WeKnora采用微服务架构设计，各组件通过Docker网络协同工作，形成完整的文档理解与检索系统。

3.1 核心服务组件说明

3.1.1 应用服务层

• app：主应用服务，基于Golang开发，实现核心RAG逻辑和API接口
• frontend：基于Vue.js的Web前端界面，提供用户交互接口
• docreader：文档解析服务，处理PDF、DOCX等多种格式文档

3.1.2 数据存储层

• postgres：关系型数据库，使用ParadeDB扩展支持向量检索
• redis：缓存服务，存储会话数据和热点缓存
• minio：对象存储服务，存储原始文档和处理结果
• neo4j：图数据库，构建知识图谱支持关联检索

3.1.3 辅助服务层

• jaeger：分布式追踪系统，监控服务调用链路
• ollama：本地LLM服务，提供模型推理能力（可选）

3.2 数据流转流程

WeKnora处理文档和查询的核心流程如下：

1. 数据准备与索引：

   • 文档加载与解析（OCR处理图像文档）
   • 文本分块与向量化
   • 向量与元数据存储

2. 查询与检索：

   • 查询转换与重写
   • 混合检索（关键词+向量+知识图谱）
   • 结果重排序

3. 生成与响应：

   • 上下文构建与提示工程
   • LLM推理生成回答
   • 结果格式化与返回

4. 场景适配：多环境部署策略

4.1 开发环境配置优化

开发环境需支持代码热重载和调试功能，修改docker-compose.dev.yml：

version: '3.8'
services:
  app:
    build: .
    volumes:
      - ./:/app
      - /app/vendor
    environment:
      - GIN_MODE=debug
      - LOG_LEVEL=debug
    command: air -c .air.toml

  frontend:
    volumes:
      - ./frontend:/app
      - /app/node_modules
    command: npm run dev

启动开发环境：

docker-compose -f docker-compose.dev.yml up -d

4.2 生产环境资源配置

生产环境需配置资源限制和高可用性：

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G
      restart_policy:
        condition: on-failure
        max_attempts: 3

启用HTTPS（使用Nginx反向代理）：

server {
    listen 443 ssl;
    server_name weknora.example.com;
    
    ssl_certificate /etc/ssl/certs/weknora.crt;
    ssl_certificate_key /etc/ssl/private/weknora.key;
    
    location / {
        proxy_pass http://frontend:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /api {
        proxy_pass http://app:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

4.3 离线部署镜像管理

在无互联网环境部署时，提前准备镜像包：

1. 在线环境保存镜像：

# 保存核心镜像
docker save wechatopenai/weknora-app:latest > weknora-app.tar
docker save wechatopenai/weknora-ui:latest > weknora-ui.tar
docker save wechatopenai/weknora-docreader:latest > weknora-docreader.tar
docker save paradedb/paradedb:v0.18.9-pg17 > paradedb.tar
docker save redis:7.0-alpine > redis.tar
docker save minio/minio:latest > minio.tar
docker save neo4j:latest > neo4j.tar

2. 离线环境加载镜像：

docker load < weknora-app.tar
docker load < weknora-ui.tar
docker load < weknora-docreader.tar
docker load < paradedb.tar
docker load < redis.tar
docker load < minio.tar
docker load < neo4j.tar

3. 启动离线环境：

./scripts/start_all.sh -a --no-pull

5. 运维优化：保障系统稳定运行

5.1 监控告警体系搭建

集成Prometheus和Grafana实现系统监控：

1. 添加监控服务到docker-compose.yml：

prometheus:
  image: prom/prometheus
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
    - prometheus-data:/prometheus
  ports:
    - "9090:9090"
  
grafana:
  image: grafana/grafana
  volumes:
    - grafana-data:/var/lib/grafana
  ports:
    - "3000:3000"
  depends_on:
    - prometheus

volumes:
  prometheus-data:
  grafana-data:

2. 配置关键监控指标：
   • 应用响应时间（API latency）
   • 数据库连接数和查询性能
   • 容器资源使用率（CPU、内存、磁盘I/O）
   • 文档处理队列长度

5.2 数据备份与恢复策略

实施自动化备份方案：

1. 创建备份脚本（scripts/backup.sh）：

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

# 创建备份目录
mkdir -p $BACKUP_DIR

# 数据库备份
docker-compose exec -T postgres pg_dump -U $DB_USER $DB_NAME > $BACKUP_DIR/postgres_$DATE.sql

# MinIO数据备份
docker-compose exec -T minio mc mirror local/weknora $BACKUP_DIR/minio_$DATE

# 保留最近30天备份
find $BACKUP_DIR -type f -mtime +30 -delete

2. 添加定时任务（crontab）：

0 2 * * * /path/to/WeKnora/scripts/backup.sh >> /var/log/weknora_backup.log 2>&1

3. 恢复数据示例：

# 恢复数据库
cat $BACKUP_DIR/postgres_20231015_020000.sql | docker-compose exec -T postgres psql -U $DB_USER $DB_NAME

# 恢复MinIO数据
docker-compose exec -T minio mc mirror $BACKUP_DIR/minio_20231015_020000 local/weknora

5.3 性能调优最佳实践

针对不同负载场景优化系统性能：

5.3.1 应用服务优化

• 调整Golang垃圾回收参数：

GOGC=100 ./weknora serve

• 优化API并发处理：

# config/config.yaml
server:
  read_timeout: 30s
  write_timeout: 30s
  idle_timeout: 60s
  max_header_bytes: 1048576
  concurrency: 1000

5.3.2 数据库优化

• 调整PostgreSQL配置：

max_connections = 200
shared_buffers = 2GB
work_mem = 64MB
maintenance_work_mem = 256MB

• 为频繁查询字段创建索引：

CREATE INDEX idx_chunks_kbid ON chunks(knowledge_base_id);
CREATE INDEX idx_chunks_created_at ON chunks(created_at);

5.3.3 检索性能优化

• 调整向量检索参数：

# config/config.yaml
knowledge_base:
  embedding_top_k: 20
  rerank_top_n: 5
  keyword_threshold: 0.3
  enable_rerank: true

6. 附录：部署诊断工具集

6.1 环境检查工具

• 系统兼容性检查：

./scripts/check-env.sh

功能：验证Docker环境、端口占用情况、依赖组件版本

• 配置文件验证：

docker-compose config

功能：检查docker-compose配置文件语法正确性

6.2 日志分析工具

• 实时查看应用日志：

docker-compose logs -f --tail=100 app

• 错误日志过滤：

docker-compose logs app | grep -i error

• 性能问题排查：

docker-compose exec app go tool pprof http://localhost:8080/debug/pprof/profile?seconds=30

6.3 容器管理工具

• 容器资源使用监控：

docker stats

• 服务健康状态检查：

docker-compose exec app curl -s http://localhost:8080/api/health | jq

• 数据库连接测试：

docker-compose exec postgres psql -U $DB_USER -d $DB_NAME -c "SELECT 1"

通过本指南提供的容器化部署方案，技术团队可以快速搭建企业级WeKnora服务，并根据实际业务需求进行灵活扩展和优化。无论是开发测试、生产部署还是离线环境，WeKnora的容器化架构都能提供一致的运行环境和简化的管理体验，助力企业实现高效的文档理解与检索能力。