Microcks 主组件镜像文档

1. 镜像概述和主要用途

1.1 概述

Microcks 主组件镜像包含 Microcks 应用的核心服务单元，集成了 Web 用户界面（UI）和应用程序编程接口（API）服务，是实现 Microcks 功能的基础部署载体。

1.2 主要用途

• 提供 API 契约测试、服务模拟、API 文档管理的统一访问入口
• 通过 Web UI 实现可视化操作与配置管理
• 通过 REST API 支持自动化集成与外部系统交互

2. 核心功能和特性

• Web UI 界面：提供直观的图形化操作界面，支持 API 规范导入、测试执行、模拟服务管理等功能
• REST API 接口：暴露完整的编程接口，支持外部系统调用与自动化流程集成
• 多规范支持：兼容 OpenAPI、AsyncAPI、GraphQL、gRPC 等主流 API 规范
• 服务模拟：基于 API 规范自动生成可配置的模拟服务，支持动态响应与状态管理
• 契约测试：执行 API 契约验证，确保服务实现与规范一致性
• 数据持久化：与外部数据库集成，存储 API 规范、测试结果、配置信息等数据

3. 使用场景和适用范围

3.1 典型使用场景

• 开发阶段：模拟第三方依赖服务，加速本地开发调试
• 测试阶段：执行自动化 API 契约测试，验证服务兼容性
• 文档管理：集中托管 API 规范文档，提供交互式浏览体验
• CI/CD 集成：嵌入持续集成流程，实现代码提交后的自动契约验证

3.2 适用范围

• 开发团队：本地 API 测试与模拟服务部署
• 测试团队：自动化契约测试执行与结果分析
• 架构团队：API 规范治理与文档管理
• 企业级应用：跨团队协作的 API 生命周期管理

4. 使用方法和配置说明

4.1 前提条件

• Docker 环境：Docker Engine 19.03+ 或 Docker Desktop
• 数据库：需外部 PostgreSQL 12+ 实例（用于数据持久化）
• 网络：确保容器可访问数据库，且主机端口（默认 8080）可用

4.2 镜像拉取

bash
docker pull microcks/microcks:latest

如需指定版本，将 latest 替换为具体版本号（如 1.9.0）

4.3 容器运行（docker run）

4.3.1 基础运行命令

bash
docker run -d \
  --name microcks \
  -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://postgres-host:5432/microcks \
  -e SPRING_DATASOURCE_USERNAME=dbuser \
  -e SPRING_DATASOURCE_PASSWORD=dbpass \
  microcks/microcks:latest

4.3.2 参数说明

• -p 8080:8080：端口映射（主机端口:容器端口）
• --name microcks：指定容器名称
• -e：设置环境变量（详见 4.5 环境变量说明）
• microcks/microcks:latest：镜像名称及标签

4.3.3 访问验证

启动后通过 http://<host-ip>:8080 访问 UI，默认管理员账号：admin/microcks123

4.4 docker-compose 部署

4.4.1 配置文件示例

yaml
version: '3.8'

services:
  postgres:
    image: postgres:13-alpine
    container_name: microcks-db
    environment:
      POSTGRES_DB: microcks
      POSTGRES_USER: microcksuser
      POSTGRES_PASSWORD: microckspass
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - microcks-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U microcksuser"]
      interval: 10s
      timeout: 5s
      retries: 5

  microcks:
    image: microcks/microcks:latest
    container_name: microcks-app
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/microcks
      SPRING_DATASOURCE_USERNAME: microcksuser
      SPRING_DATASOURCE_PASSWORD: microckspass
      SERVER_PORT: 8080
      LOGGING_LEVEL_ROOT: INFO
      CORS_ALLOWED_ORIGINS: "http://localhost:3000,https://example.com"
    networks:
      - microcks-net
    restart: unless-stopped

networks:
  microcks-net:
    driver: bridge

volumes:
  postgres-data:

4.4.2 启动命令

bash
docker-compose up -d

4.5 环境变量配置

4.6 数据持久化

• 数据库数据：通过挂载 PostgreSQL 数据卷（如示例中的 postgres-data）实现
• 配置文件：如需自定义配置，可通过 -v /host/config:/app/config 挂载配置目录

5. 注意事项

• 数据库依赖：生产环境必须使用外部 PostgreSQL 数据库，不支持内置数据库
• 安全加固：生产环境需修改默认管理员密码（UI 中路径：Settings > Users）和数据库凭证
• 版本兼容性：镜像版本需与数据库版本匹配（推荐 PostgreSQL 12+）
• 资源需求：建议分配至少 2GB 内存，避免因资源不足导致服务异常
• 备份策略：定期备份数据库数据，防止配置和测试记录丢失