Docker封装的Klipper

此镜像由 prind项目 构建和使用。

什么是Klipper？

Klipper是一款3D打印机固件。它将通用计算机的算力与一个或多个微控制器结合，充分发挥硬件性能。关于使用Klipper的优势，可参考其功能文档。

引用自 [**]

使用方法

Klipper需要访问主机设备，建议以特权模式运行并挂载主机的/dev目录。非特权模式可能因MCU重置后设备名变更导致功能异常（参考相关问题）。

独立运行

准备工作

1. 创建配置文件 printer.cfg
2. 创建目录 run

运行容器

通过docker run命令

bash
docker run \
  --privileged \
  -v /dev:/dev \
  -v $(pwd)/run:/opt/printer_data/run \
  -v $(pwd)/printer.cfg:/opt/printer_data/config/printer.cfg \
  mkuf/klipper:latest

通过docker compose配置

yaml
services:
  klipper:
    image: mkuf/klipper:latest
    privileged: true
    volumes:
      - /dev:/dev
      - ./printer.cfg:/opt/printer_data/config/printer.cfg
      - ./run:/opt/printer_data/run

连接GCODE发送器

将GCODE发送器指向 run 目录下的 klipper.tty 文件即可。

与Moonraker一起使用

若需搭配Moonraker使用，两者需共享包含套接字的目录。Moonraker镜像的详细使用说明见其README.md。

准备工作

1. 创建配置文件 moonraker.conf 和 printer.cfg
2. 创建目录 run（共享套接字）和 gcode（存储GCODE文件）

运行容器

通过docker run命令
先启动Klipper：

bash
docker run \
  --privileged \
  -v /dev:/dev \
  -v $(pwd)/run:/opt/printer_data/run \
  -v $(pwd)/gcode:/opt/printer_data/gcodes \
  -v $(pwd)/printer.cfg:/opt/printer_data/config/printer.cfg \
  mkuf/klipper:latest

再启动Moonraker：

bash
docker run \
  -v $(pwd)/run:/opt/printer_data/run \
  -v $(pwd)/gcode:/opt/printer_data/gcodes \
  -v $(pwd)/moonraker.conf:/opt/printer_data/config/moonraker.conf \
  -p 7125:7125 \
  mkuf/moonraker:latest

通过docker compose配置

yaml
services:
  klipper:
    image: mkuf/klipper:latest
    privileged: true
    volumes:
      - /dev:/dev
      - ./printer.cfg:/opt/printer_data/config/printer.cfg
      - ./run:/opt/printer_data/run
      - ./gcode:/opt/printer_data/gcodes

  moonraker:
    image: mkuf/moonraker:latest
    ports:
      - "7125:7125"
    volumes:
      - ./moonraker.conf:/opt/printer_data/config/moonraker.conf
      - ./run:/opt/printer_data/run
      - ./gcode:/opt/printer_data/gcodes

默认配置

镜像标签

构建目标

健康检查

容器内提供 /opt/health.py 脚本用于健康检查。

注意：在Docker中启用健康检查可能显著增加CPU占用。测试中，每30秒执行一次检查会使容器CPU占用翻倍，每5秒执行则增至6倍。低功耗主机可能因此出现资源不足或异常行为。

脚本功能：

• 通过Unix套接字查询Klipper的info端点
• 检查状态是否为ready
• 若上述任一条件不满足，脚本返回失败状态，标记容器为不健康

Compose配置示例：

yaml
services:
  klipper:
    healthcheck:
      test: ["python3", "/opt/health.py"]
      interval: 30s