mutagenio/sidecar

镜像概述

该镜像为用于Mutagen编排集成的边车容器镜像，设计目标是在容器化环境中提供文件同步、数据共享及开发环境一致性管理能力。采用边车模式部署，作为辅助容器与主应用容器协同工作，不干扰主应用逻辑，同时通过与Mutagen工具链集成，增强容器环境中的文件同步与数据一致性保障。

核心功能与特性

• Mutagen原生集成：无缝对接Mutagen同步会话管理机制，支持通过Mutagen CLI工具配置、启动和监控同步任务
• 边车模式支持：采用边车架构设计，可独立部署于主应用容器旁，通过共享网络和存储资源提供服务，不侵入主应用代码
• 灵活文件同步：支持单向/双向文件同步、实时增量同步及定时同步，可自定义同步路径、频率及冲突解决策略
• 跨环境适配：兼容Docker、Kubernetes等主流容器编排平台，支持Linux/macOS/Windows宿主系统的容器环境
• 轻量级设计：基于Alpine基础镜像构建，镜像体积小，资源占用低，适合开发与测试环境快速部署

使用场景

• 本地开发与容器文件同步：解决容器内代码编辑效率问题，实现本地IDE修改与容器内代码实时同步，提升开发流畅度
• 多容器应用数据共享：在微服务架构中，实现跨容器实例的配置文件、静态资源等数据共享，简化多容器协调逻辑
• 开发环境一致性维护：通过统一的同步规则，确保团队成员本地开发环境、CI/CD流水线及测试环境的文件版本一致性
• 临时数据迁移辅助：在容器集群升级或迁移过程中，作为临时数据同步通道，保障数据平滑迁移

使用方法与配置说明

基础部署（Docker Run）

bash
docker run -d \
  --name mutagen-sidecar \
  --network=app-network \  # 与主应用容器共享网络
  -v /local/dev/path:/sync/source \  # 本地源目录
  -v app-data-volume:/sync/target \  # 容器目标卷
  -e MUTAGEN_SESSION=app-dev-sync \
  -e SYNC_DIRECTION=two-way-resolved \
  -e SYNC_IGNORES=".git,.env,node_modules" \
  -e SYNC_FREQ=5s \
  your-registry/mutagen-sidecar:latest

核心环境变量配置

Docker Compose配置示例

yaml
version: '3.8'
services:
  # 主应用容器
  web-app:
    image: node:20-alpine
    volumes:
      - app-code:/app  # 与边车容器共享的代码卷
    command: npm run dev
    depends_on:
      - mutagen-sidecar

  # Mutagen边车容器
  mutagen-sidecar:
    image: your-registry/mutagen-sidecar:latest
    volumes:
      - ./local-code:/sync/source  # 本地开发目录
      - app-code:/sync/target  # 与主应用共享的代码卷
    environment:
      - MUTAGEN_SESSION=web-app-sync
      - SYNC_DIRECTION=two-way-resolved
      - SYNC_IGNORES=".git,.env,coverage,dist"
      - SYNC_FREQ=3s
      - LOG_LEVEL=debug
    restart: unless-stopped

volumes:
  app-code:  # 共享卷定义

使用注意事项

1. 依赖要求：宿主机需预先安装Mutagen CLI工具（v0.16.0+），边车容器通过调用宿主机Mutagen命令实现同步管理
2. 权限配置：本地目录与容器卷的权限需匹配（建议使用非root用户或调整UID/GID映射），避免同步过程中出现权限拒绝错误
3. 冲突处理：双向同步时建议配置明确的冲突解决策略（通过SYNC_DIRECTION），关键数据目录建议使用单向同步模式
4. 性能优化：高频同步场景下（如前端热重载），建议通过SYNC_IGNORES排除node_modules、dist等大型目录，降低资源占用