Evolution API Docker部署全攻略：从单机到K8s集群-优快云博客

Evolution API Docker部署全攻略：从单机到K8s集群

【免费下载链接】evolution-api 项目地址: https://gitcode.com/GitHub_Trending/ev/evolution-api

部署架构概览

Evolution API提供了灵活的部署方案，支持从单机开发环境到企业级K8s集群的全场景覆盖。本文将系统讲解Docker Compose单机部署、Docker Swarm集群部署以及K8s迁移路径，帮助运维人员快速实现生产级部署。

环境准备

基础依赖

Docker Engine 20.10+
Docker Compose 2.0+
Git

源码获取

git clone https://gitcode.com/GitHub_Trending/ev/evolution-api
cd evolution-api

单机部署（Docker Compose）

标准生产环境部署

环境变量配置

cp env.example .env
# 编辑数据库密码等核心配置
vim .env

启动服务栈

docker-compose up -d

核心配置文件：docker-compose.yaml

服务组成 | 服务名 | 容器名 | 镜像 | 功能 | |--------|--------|------|------| | api | evolution_api | evoapicloud/evolution-api:latest | 核心API服务 | | frontend | evolution_frontend | evoapicloud/evolution-manager:latest | 管理界面 | | redis | evolution_redis | redis:latest | 缓存服务 | | evolution-postgres | evolution_postgres | postgres:15 | 主数据库 |

开发环境部署

开发环境使用本地构建镜像，支持代码热重载：

docker-compose -f docker-compose.dev.yaml up -d --build

开发配置文件：docker-compose.dev.yaml

数据库初始化

数据库部署脚本会自动读取.env配置并执行迁移：

bash Docker/scripts/deploy_database.sh

部署脚本：Docker/scripts/deploy_database.sh

环境变量加载逻辑：Docker/scripts/env_functions.sh

集群部署（Docker Swarm）

前期准备

初始化Swarm集群

docker swarm init --advertise-addr <manager-ip>

创建共享数据卷

docker volume create --name evolution_v2_data --driver local

部署服务栈

docker stack deploy -c Docker/swarm/evolution_api_v2.yaml evolution

Swarm配置文件：Docker/swarm/evolution_api_v2.yaml

关键配置解析

服务副本与约束

deploy:
  mode: replicated
  replicas: 1
  placement:
    constraints:
      - node.hostname == evolution-manager

Traefik反向代理

labels:
  - traefik.enable=true
  - traefik.http.routers.evolution_v2.rule=Host(`evo2.site.com`)
  - traefik.http.routers.evolution_v2.tls.certresolver=letsencryptresolver

环境变量配置

environment:
  - SERVER_URL=https://evo2.site.com
  - DATABASE_PROVIDER=postgresql
  - DATABASE_CONNECTION_URI=postgresql://postgres:SENHA@postgres:5432/evolution

迁移至Kubernetes

核心迁移步骤

容器化适配
- 将Docker Compose配置转换为K8s资源清单
- 调整存储为PersistentVolumeClaims
- 使用ConfigMap/Secret管理配置
状态管理
- 数据库使用云厂商托管服务或StatefulSet部署
- 实例数据使用NFS或云存储卷
服务发现
- 使用Ingress替代Traefik标签路由
- 配置Service实现内部服务发现

资源清单示例

apiVersion: apps/v1
kind: Deployment
metadata:
  name: evolution-api
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: evoapicloud/evolution-api:latest
        volumeMounts:
        - name: instances-volume
          mountPath: /evolution/instances
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: evolution-instances-pvc
spec:
  accessModes: [ "ReadWriteMany" ]
  resources:
    requests:
      storage: 10Gi

监控与维护

日志查看

# 单机
docker-compose logs -f api

# Swarm集群
docker service logs -f evolution_evolution_v2

性能监控

复制示例配置

cp prometheus.yml.example prometheus.yml
cp grafana-dashboard.json.example grafana-dashboard.json

部署监控栈（Prometheus + Grafana）

docker-compose -f docker-compose.monitor.yaml up -d

部署架构对比

部署方式	适用场景	优势	复杂度
Docker Compose	开发/测试/小型生产	简单快速	★☆☆☆☆
Docker Swarm	中型集群	原生Docker集成	★★☆☆☆
Kubernetes	大型企业级部署	高可用/自动扩缩容	★★★★☆

常见问题解决

数据库连接失败
- 检查.env中DATABASE_CONNECTION_URI配置
- 执行数据库健康检查：docker exec -it evolution_postgres pg_isready
实例数据持久化
- 确认volumes配置正确挂载：docker volume inspect evolution_instances
证书自动续期
- Traefik配置中启用letsencryptresolver
- 检查ACME挑战日志：docker service logs evolution_traefik

总结

Evolution API通过容器化部署实现了环境一致性和快速扩缩容。对于中小规模应用，Docker Compose/Swarm提供了简单可靠的解决方案；企业级用户可平滑迁移至K8s架构，满足高并发业务需求。部署过程中需特别注意数据持久化策略和环境变量安全配置。

完整部署文档：README.md

【免费下载链接】evolution-api 项目地址: https://gitcode.com/GitHub_Trending/ev/evolution-api

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考