extenda/structurizr-to-png

Structurizr DSL to PNG Docker镜像

镜像概述和主要用途

该Docker镜像提供了将Structurizr DSL（领域特定语言）文件转换为PNG图像的功能。Structurizr DSL是一种用于定义软件架构的文本格式，通过该镜像，用户可便捷地将架构描述文件转换为可视化图表，无需在本地安装Structurizr相关工具链，简化了架构文档的生成流程。

核心功能和特性

• DSL解析支持：完全兼容Structurizr DSL语法，可解析包含系统、容器、组件、关系等元素的架构定义文件。
• PNG生成：输出高质量PNG格式图像，清晰呈现软件架构层次结构与关系。
• 轻量级设计：基于精简基础镜像构建，容器体积小，启动速度快。
• 无依赖运行：容器化封装所有依赖组件，无需本地配置Java或Structurizr CLI。
• 灵活输出：支持自定义输出路径，可指定单个文件转换或批量处理目录内所有DSL文件。

使用场景和适用范围

• 软件架构可视化：架构师通过DSL定义架构后，快速生成图表用于文档或演示。
• 文档自动化：集成到CI/CD流程中，当DSL文件更新时自动生成最新架构图。
• 团队协作：在团队共享环境中统一架构图生成标准，避免本地工具版本差异导致的兼容性问题。
• 教育与培训：教学中展示架构设计从文本到图形的转换过程。

使用方法和配置说明

前提条件

• 已安装Docker引擎（20.10+版本推荐）。
• 本地存在符合Structurizr DSL语法的.dsl文件。

获取镜像

从Docker镜像仓库拉取最新版本：

bash
docker pull docker.xuanyuan.run/structurizr-dsl-to-png:latest

基本使用（单文件转换）

通过docker run命令挂载本地目录，指定输入DSL文件和输出PNG路径：

bash
docker run --rm \
  -v /本地/dsl文件目录:/input \
  -v /本地/输出目录:/output \
  docker.xuanyuan.run/structurizr-dsl-to-png:latest \
  --input /input/architecture.dsl \
  --output /output/architecture.png

• --rm：容器退出后自动删除。
• -v /本地/dsl文件目录:/input：挂载本地DSL文件所在目录到容器内/input路径。
• -v /本地/输出目录:/output：挂载本地输出目录到容器内/output路径。
• --input：指定容器内DSL文件路径（需对应挂载的/input目录）。
• --output：指定容器内PNG输出路径（需对应挂载的/output目录）。

批量处理目录

若需转换目录内所有.dsl文件，可使用--batch参数指定输入目录，输出文件将与DSL文件同名（扩展名为.png）：

bash
docker run --rm \
  -v /本地/dsl目录:/input \
  -v /本地/输出目录:/output \
  docker.xuanyuan.run/structurizr-dsl-to-png:latest \
  --batch /input \
  --output-dir /output

配置参数说明

Docker Compose配置示例

创建docker-compose.yml文件，简化本地目录挂载与参数配置：

yaml
version: '3'
services:
  structurizr-renderer:
    image: docker.xuanyuan.run/structurizr-dsl-to-png:latest
    volumes:
      - ./dsl:/input          # 本地DSL文件目录映射
      - ./output:/output      # 本地输出目录映射
    command: --batch /input --output-dir /output --force true

运行服务：

bash
docker-compose up

注意事项

• 确保DSL文件语法正确，语法错误将导致转换失败并输出错误日志。
• 挂载目录权限需允许容器读写，避免因权限问题导致文件无法访问或输出。
• 对于大型架构图，可通过--dpi参数提高图像分辨率，但会增加文件体积。