commercetools-project-sync 镜像文档

1. 镜像概述

commercetools-project-sync 是一个专为 commercetools 电商平台设计的配置同步工具，旨在解决多环境（如开发、测试、生产）间项目配置不一致的问题。通过自动化同步产品类型、属性、类别、工作流、扩展等核心配置，该工具可显著减少手动操作错误，提高多环境管理效率，确保各环境配置的一致性与准确性。

2. 核心功能与特性

2.1 支持的配置类型

• 产品类型与属性：同步产品定义结构、自定义属性及属性约束
• 类别与类别树：同步商品分类层级结构及元数据
• 工作流与状态机：同步订单、库存等业务流程的状态定义与转换规则
• 扩展与触发器：同步API扩展、消息队列触发器等集成配置
• 其他核心配置：包括 shipping methods（配送方式）、tax categories（税分类）、discount codes（折扣码）等

2.2 关键特性

• 增量同步：仅同步变更配置，减少网络传输与处理时间
• 配置验证：同步前自动校验配置合法性，避免无效配置导入
• 详细日志：记录同步过程、变更内容及错误信息，便于问题排查
• 灵活认证：支持 commercetools 标准 OAuth 2.0 认证（客户端ID/密钥）
• 多环境适配：兼容 commercetools 全球区域 API（如欧洲、北美、亚太节点）

3. 使用场景与适用范围

3.1 典型使用场景

• 多环境开发团队：在开发、测试、预发布环境间同步配置，确保测试环境与生产环境一致
• CI/CD 集成：作为部署流程的一环，自动将配置从开发环境同步至测试/生产环境
• 新环境快速搭建：基于现有环境配置快速初始化新项目（如临时测试环境、客户演示环境）
• 配置迁移：跨区域或跨租户迁移项目配置（需注意数据隐私与权限控制）

3.2 适用范围

• commercetools 项目管理员、DevOps 工程师及多环境开发团队
• 需管理 2 个及以上 commercetools 项目环境的场景
• 依赖统一配置确保业务流程一致性的电商平台

4. 使用方法与配置说明

4.1 前置条件

• 已创建 commercetools 源项目（Source）与目标项目（Target）
• 源项目与目标项目均配置有效的 API 凭证（Client ID、Client Secret、Project Key）
• 凭证需具备对应配置的读写权限（如 manage_product_types、manage_types 等 scope）

4.2 Docker 快速启动

4.2.1 基础同步命令

通过 docker run 直接执行同步，需指定源/目标项目的 API 信息及待同步资源类型：

docker run --rm \
  -e SOURCE_PROJECT_KEY="dev-project" \
  -e SOURCE_API_URL="[***]" \
  -e SOURCE_CLIENT_ID="source-client-id" \
  -e SOURCE_CLIENT_SECRET="source-client-secret" \
  -e TARGET_PROJECT_KEY="test-project" \
  -e TARGET_API_URL="[***]" \
  -e TARGET_CLIENT_ID="target-client-id" \
  -e TARGET_CLIENT_SECRET="target-client-secret" \
  -e RESOURCES="product-types,attributes,categories" \  # 需同步的资源类型，逗号分隔
  -e LOG_LEVEL="info" \  # 日志级别：debug/info/warn/error
  commercetools/commercetools-project-sync:latest

4.2.2 Docker Compose 配置示例

对于固定环境，可通过 docker-compose.yml 管理配置，便于重复执行：

version: '3.8'
services:
  project-sync:
    image: commercetools/commercetools-project-sync:latest
    environment:
      # 源项目配置
      SOURCE_PROJECT_KEY: "dev-project"
      SOURCE_API_URL: "[***]"
      SOURCE_CLIENT_ID: "${SOURCE_CLIENT_ID}"  # 建议通过环境变量注入敏感信息
      SOURCE_CLIENT_SECRET: "${SOURCE_CLIENT_SECRET}"
      
      # 目标项目配置
      TARGET_PROJECT_KEY: "prod-project"
      TARGET_API_URL: "[***]"
      TARGET_CLIENT_ID: "${TARGET_CLIENT_ID}"
      TARGET_CLIENT_SECRET: "${TARGET_CLIENT_SECRET}"
      
      # 同步参数
      RESOURCES: "product-types,attributes,workflows,extensions"  # 同步所有核心资源
      SYNC_MODE: "incremental"  # incremental（增量）/ full（全量）
      LOG_LEVEL: "debug"  # 调试时使用 debug 级别
      DRY_RUN: "false"  # true 时仅模拟同步，不实际修改目标环境

启动命令：docker-compose up

4.3 核心配置参数

4.3.1 环境变量（必填）

4.3.2 可选配置参数

5. 注意事项

• 数据备份：同步前建议备份目标环境配置，避免不可逆变更
• 权限控制：确保源/目标项目凭证仅具备必要权限，遵循最小权限原则
• 测试验证：新配置同步前建议在测试环境验证，确认同步结果符合预期
• API 限流：commercetools API 存在调用频率限制，高并发同步时可降低 CONCURRENCY 值

6. 参考链接

• commercetools 官方文档
• commercetools-project-sync GitHub 仓库（获取最新版本与更新日志）