twhtanghk/freecad

FreeCAD Docker镜像文档

镜像概述

twhtanghk/freecad是一个用于运行开源CAD软件FreeCAD的Docker镜像。FreeCAD是一款功能强大的开源参数化3D建模软件，广泛应用于机械设计、建筑设计、产品开发等领域。该镜像通过容器化方式封装FreeCAD运行环境，无需在本地系统直接安装，简化部署流程并确保环境一致性。

核心功能与特性

• 容器化运行：将FreeCAD及其依赖环境封装在Docker容器中，避免本地系统环境冲突
• 图形界面支持：通过挂载X11 socket实现容器内FreeCAD图形界面的显示
• 字体共享：挂载主机字体目录，确保CAD设计中字体正常显示
• 数据持久化：支持挂载本地目录到容器内，实现设计文件的持久化存储
• 系统服务集成：挂载dbus socket，支持与主机系统服务的通信

使用场景

• 需要快速使用FreeCAD进行3D建模，不想在本地系统安装复杂依赖
• 多环境下保持一致的FreeCAD运行配置
• 团队协作中统一CAD设计环境
• 临时或测试环境中快速部署FreeCAD

使用方法

前提条件

• 已安装Docker和Docker Compose
• 主机系统支持X11图形显示（Linux系统）

Docker Compose配置示例

以下是完整的docker-compose.yml配置：

yaml
version: '3'
services:
  freecad:
    image: twhtanghk/freecad
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix  # 挂载X11 socket以显示图形界面
      - /var/run/dbus:/var/run/dbus    # 挂载dbus socket用于系统服务通信
      - /usr/share/fonts:/usr/share/fonts  # 共享主机字体
      - ../src:/root                   # 挂载本地目录到容器内/root，用于文件持久化
    environment:
      - DISPLAY                        # 继承主机DISPLAY环境变量，指定显示设备
      - QTWEBENGINE_DISABLE_SANDBOX=1  # 禁用Qt WebEngine沙箱，解决部分显示问题

启动容器

在包含上述docker-compose.yml文件的目录中，执行以下命令启动FreeCAD容器：

bash
docker-compose up

配置说明

卷挂载（Volumes）

• /tmp/.X11-unix:/tmp/.X11-unix：必须挂载，用于容器内FreeCAD图形界面输出到主机显示器
• /var/run/dbus:/var/run/dbus：可选，用于容器与主机系统服务（如桌面环境）的通信
• /usr/share/fonts:/usr/share/fonts：可选，确保容器内可使用主机字体，避免中文或特殊字体显示异常
• ../src:/root：建议挂载，将本地目录（如../src）映射到容器内/root目录，实现设计文件的持久化存储和共享

环境变量（Environment）

• DISPLAY：继承主机的DISPLAY环境变量，指定图形界面显示的目标设备，通常无需修改
• QTWEBENGINE_DISABLE_SANDBOX=1：禁用Qt WebEngine的沙箱机制，解决部分系统中FreeCAD界面组件（如帮助文档）无法正常显示的问题

注意事项

• 该镜像主要适用于Linux系统，Windows或macOS需额外配置X11服务器（如XQuartz）
• 首次启动可能需要等待镜像拉取和依赖初始化
• 确保主机用户对挂载的本地目录有读写权限，避免文件操作权限问题