WeKnora部署指南：Docker容器化部署与多环境适配最佳实践

引言

在当今快速发展的AI领域，WeKnora作为一款基于LLM（大语言模型）的框架，为深度文档理解、语义检索和上下文感知回答提供了强大支持。本指南将详细介绍如何使用Docker容器化技术部署WeKnora，并提供多环境适配的最佳实践，帮助您快速搭建稳定高效的WeKnora服务。

环境准备

在开始部署WeKnora之前，确保您的系统满足以下要求：

1. 安装Docker和Docker Compose
2. 至少4GB内存和20GB可用磁盘空间
3. 互联网连接（用于拉取Docker镜像）

Docker Compose部署

WeKnora提供了便捷的Docker Compose部署方式，只需几步即可完成部署：

1. 克隆代码仓库

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

2. 配置环境变量

创建并编辑.env文件，设置必要的环境变量：

cp .env.example .env
vi .env

关键配置项包括：

• DB_DRIVER：数据库驱动类型
• STORAGE_TYPE：存储类型
• OLLAMA_BASE_URL：Ollama服务地址
• APP_PORT：应用端口
• FRONTEND_PORT：前端端口

3. 启动服务

使用提供的启动脚本一键启动所有服务：

./scripts/start_all.sh

该脚本支持多种参数，如：

• -a, --all：启动所有服务（默认）
• -d, --docker：仅启动Docker容器服务
• -o, --ollama：仅启动Ollama服务
• -s, --stop：停止所有服务

启动成功后，您可以通过以下地址访问服务：

• 前端界面：http://localhost:${FRONTEND_PORT:-80}
• API接口：http://localhost:${APP_PORT:-8080}
• Jaeger链路追踪：http://localhost:16686

容器架构详解

WeKnora的Docker Compose配置定义了多个服务容器，共同构成完整的应用生态系统：

主要服务组件包括：

1. app：WeKnora主应用服务

   • 镜像：wechatopenai/weknora-app:latest
   • 端口：8080
   • 依赖：redis, postgres, minio, docreader, neo4j

2. frontend：前端Web界面

   • 镜像：wechatopenai/weknora-ui:latest
   • 端口：80

3. postgres：数据库服务

   • 镜像：paradedb/paradedb:v0.18.9-pg17
   • 端口：5432

4. redis：缓存服务

   • 镜像：redis:7.0-alpine
   • 端口：6379

5. minio：对象存储服务

   • 镜像：minio/minio:latest
   • 端口：9000, 9001

6. docreader：文档解析服务

   • 镜像：wechatopenai/weknora-docreader:latest
   • 端口：50051

7. neo4j：图数据库服务

   • 镜像：neo4j:latest
   • 端口：7474, 7687

8. jaeger：分布式追踪服务

   • 镜像：jaegertracing/all-in-one:latest
   • 端口：16686

这些服务通过Docker网络（WeKnora-network）相互通信，形成一个完整的微服务架构。

多环境适配

WeKnora支持多种环境配置，可根据实际需求进行调整：

开发环境

对于开发环境，您可以使用本地代码挂载，实现热重载：

volumes:
  - ./:/app
  - /app/node_modules

并使用开发模式启动应用：

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

生产环境

生产环境建议进行以下优化：

1. 使用环境变量配置敏感信息
2. 启用HTTPS加密
3. 配置适当的资源限制
4. 设置日志轮转

示例生产环境配置：

app:
  environment:
    - GIN_MODE=release
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 4G
      reservations:
        cpus: '1'
        memory: 2G

离线环境

对于无法访问互联网的环境，可提前拉取镜像并保存：

# 保存镜像
docker save wechatopenai/weknora-app:latest > weknora-app.tar
docker save wechatopenai/weknora-ui:latest > weknora-ui.tar

# 在离线环境加载镜像
docker load < weknora-app.tar
docker load < weknora-ui.tar

然后使用--no-pull参数启动：

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

自定义配置

WeKnora提供了丰富的配置选项，可通过config/config.yaml文件进行自定义：

服务器配置

server:
  port: 8080
  host: "0.0.0.0"

知识库配置

knowledge_base:
  chunk_size: 512
  chunk_overlap: 50
  split_markers: ["\n\n", "\n", "。"]

对话服务配置

conversation:
  max_rounds: 5
  keyword_threshold: 0.3
  embedding_top_k: 10
  enable_rewrite: true
  enable_rerank: true

更多配置详情，请参考config/config.yaml文件。

常见问题解决

1. 服务启动失败

检查容器日志以定位问题：

docker-compose logs -f app

常见原因包括：

• 端口冲突：修改.env文件中的端口配置
• 环境变量缺失：确保.env文件配置完整
• 依赖服务未就绪：检查依赖服务的健康状态

2. 数据库连接问题

确保数据库服务正常运行，并检查连接参数：

docker-compose exec postgres psql -U $DB_USER -d $DB_NAME

3. 文件上传问题

检查存储服务配置和权限：

# 检查MinIO状态
docker-compose exec minio mc admin info local

4. 性能优化

对于大规模部署，可考虑：

• 增加应用实例数量
• 配置负载均衡
• 优化数据库索引
• 调整缓存策略

部署最佳实践

1. 定期备份

设置定期备份数据库和关键数据：

# 数据库备份
docker-compose exec postgres pg_dump -U $DB_USER $DB_NAME > backup_$(date +%Y%m%d).sql

# MinIO数据备份
docker-compose exec minio mc mirror local/weknora /backup/weknora

2. 监控与告警

集成Prometheus和Grafana进行系统监控：

prometheus:
  image: prom/prometheus
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
  ports:
    - "9090:9090"

grafana:
  image: grafana/grafana
  ports:
    - "3000:3000"
  depends_on:
    - prometheus

3. CI/CD集成

通过CI/CD管道自动化部署流程：

# .gitlab-ci.yml示例
deploy:
  stage: deploy
  script:
    - docker-compose pull
    - docker-compose up -d
  only:
    - main

4. 安全加固

• 使用非root用户运行容器
• 定期更新镜像和依赖
• 限制容器网络访问
• 启用内容安全策略

总结

WeKnora的Docker容器化部署提供了灵活、可扩展的部署方案，适应从开发到生产的全生命周期需求。通过本文介绍的方法，您可以快速搭建稳定高效的WeKnora服务，并根据实际需求进行定制化配置。

无论是小型项目还是企业级部署，WeKnora的容器化架构都能提供一致的运行环境和简化的管理体验。随着项目的发展，您可以逐步扩展基础设施，优化性能，确保系统持续稳定运行。

附录：常用命令参考

命令	描述
./scripts/start_all.sh	启动所有服务
./scripts/start_all.sh -s	停止所有服务
./scripts/start_all.sh -c	检查环境并诊断问题
docker-compose ps	查看容器状态
docker-compose logs -f	查看所有服务日志
docker-compose exec app bash	进入应用容器
docker-compose pull	拉取最新镜像

更多详细文档，请参考项目的官方文档：

• API文档
• 知识库使用指南
• 项目介绍
• 中文文档