keletes/freecad

freecad-docker 镜像文档

概述和主要用途

freecad-docker是一个Docker镜像，旨在通过XVFB（虚拟X服务器）运行FreeCAD。FreeCAD是一款开源的参数化3D CAD建模软件，而XVFB允许在没有物理图形界面的环境中运行GUI应用程序。该镜像适用于需要在服务器、CI/CD管道或其他无头环境中执行FreeCAD相关任务的场景，确保跨环境的一致性和便捷部署。

核心功能和特性

• 虚拟图形环境：基于XVFB提供虚拟X11显示支持，无需物理显示器即可运行FreeCAD GUI应用
• FreeCAD集成：预配置FreeCAD，可直接执行建模、脚本运行等核心功能
• 容器化部署：简化环境配置，避免依赖冲突，支持快速部署和扩展
• 跨平台兼容：可在任何支持Docker的环境中运行，包括Linux、macOS和Windows（通过Docker Desktop）

使用场景和适用范围

• 服务器环境：在云服务器或本地服务器中运行FreeCAD自动化脚本
• CI/CD流程：集成到持续集成/持续部署管道，自动执行CAD模型验证、导出等任务
• 无头环境：在没有图形界面的系统（如Docker容器、虚拟机）中使用FreeCAD
• 开发与测试：为FreeCAD插件开发提供一致的测试环境

使用方法和配置说明

前提条件

• 已安装Docker Engine（推荐版本20.10+）

拉取镜像

bash
docker pull docker.xuanyuan.run/[镜像仓库地址]/freecad-docker:latest

（注：请替换[镜像仓库地址]为实际的镜像仓库，如Docker Hub或私有仓库）

基本运行命令

bash
docker run -it --rm docker.xuanyuan.run/[镜像仓库地址]/freecad-docker:latest freecad

此命令将启动容器并运行FreeCAD，通过XVFB提供虚拟显示支持。

挂载工作目录

如需访问本地文件或保存输出结果，可挂载本地目录到容器内：

bash
docker run -it --rm -v /path/to/local/workdir:/workdir docker.xuanyuan.run/[镜像仓库地址]/freecad-docker:latest freecad /workdir/your_file.FCStd

其中/path/to/local/workdir为本地工作目录，/workdir为容器内的挂载点。

运行FreeCAD脚本

可直接执行FreeCAD Python脚本：

bash
docker run -it --rm -v /path/to/scripts:/scripts docker.xuanyuan.run/[镜像仓库地址]/freecad-docker:latest freecad -c /scripts/your_script.py

-c参数用于以控制台模式运行脚本，不启动GUI界面。

环境变量配置

例如，自定义虚拟屏幕分辨率：

bash
docker run -it --rm -e XVFB_SCREEN=1920x1080x24 docker.xuanyuan.run/[镜像仓库地址]/freecad-docker:latest freecad