跳到主要内容

FLYOS-FAST 常见问题与排障

本页集中说明 FLYOS-FAST 的系统限制、配置路径、更新方式和常见故障。具体功能的完整操作步骤通过链接跳转到对应文档，避免在 FAQ 中重复维护。

建议排查顺序
  1. 记录网页或终端显示的完整报错，不要只截取最后一行。
  2. 确认问题发生前修改过哪些配置、插件或系统选项。
  3. 检查磁盘空间、服务状态和对应日志。
  4. 涉及重启服务或上位机时，先确认打印机没有执行打印、加热或运动。

系统与账户​

为什么只能使用 root 用户？​

FLYOS-FAST 是面向打印控制设备设计的精简系统，采用单用户管理方式，root 是唯一的交互式管理账户。系统不支持创建或切换到其他用户。

为什么不能使用 apt 或 dpkg？​

FLYOS-FAST 不提供传统 Linux 发行版的软件包管理环境，因此不能使用以下命令安装或更新软件：

apt update
apt install
dpkg -i

不要从其他 Linux 系统复制软件包或系统库。额外依赖应由插件安装教程明确提供；缺少通用依赖时，请向技术支持反馈。

为什么系统目录显示为只读？​

核心系统使用只读文件系统，由完整镜像或 OTA 统一更新。不要尝试重新挂载根目录并直接修改系统文件，否则可能造成更新失败或重启后改动丢失。

用户配置、插件和打印数据应保存在持久化目录中。

文件与配置​

常用文件保存在哪里？​

内容Klipper 模式路径说明
打印机配置/usr/share/printer_data/config/包含 printer.cfg、Moonraker 和摄像头配置
G-code 文件/usr/share/printer_data/gcodes/网页上传和 U 盘打印的文件入口
运行日志/usr/share/printer_data/logs/Klipper、Moonraker、屏幕和摄像头日志
插件及源码/data/自定义插件应统一放在这里
Klipper 源码/data/klipper/系统预置的 Klipper 目录
编译产物/data/klipper/out/固件编译完成后的输出目录

RRF 模式的数据目录为 /opt/dsf/，不要把 Klipper 和 RRF 的配置路径混用。

哪些目录会持久保存？​

系统会保存 /etc、/data、/root，以及当前打印模式的数据目录。即使这些目录会保留，执行 OTA 或重新烧录前仍应单独备份打印机配置。

如何修改 FLYOS-FAST 系统配置？​

系统型号、网络、屏幕和服务开关统一在 FlyOS-Conf/config.txt 中管理。系统启动后也可以通过网页中的 .flyos-config/sys-config.conf 修改。

配置方法与生效范围：查看 FLYOS-FAST 系统配置指南

修改配置后为什么没有生效？​

不同配置需要执行不同的生效操作：

修改内容生效操作
printer.cfg 和 Klipper 配置片段在网页中执行 保存并重启
moonraker.conf重新启动 Moonraker
config.txt 或 sys-config.conf重新启动整个上位机
插件源码或软链接按插件教程重启对应服务

如果重启后仍未生效，请确认文件已经保存、配置项没有重复定义，并检查对应服务日志。

系统更新与固件​

应该怎样更新系统？​

FLYOS-FAST 应通过系统 OTA 或重新烧录对应设备的正式镜像更新。不要使用第三方系统升级脚本替换核心文件。

在线与 U 盘更新：查看 OTA 系统更新指南

重新烧录系统：查看系统镜像烧录教程

OTA 会删除打印机配置吗？​

正常 OTA 会保留 /data 和打印机数据目录，但以下情况仍可能造成配置异常：

  • 用户自行替换了 Klipper、Moonraker 或其他预置组件。
  • 自定义文件遮挡了 OTA 提供的新文件。
  • 更新过程中供电中断。
  • 更新前磁盘空间不足或文件系统已经损坏。

更新前应下载或复制一份 printer_data/config 备份。更新和重启期间保持供电稳定，不要执行打印操作。

可以单独更新 Klipper 或 Moonraker 吗？​

不建议。系统中的 Klipper、Moonraker、网页界面和屏幕服务经过配套适配，单独替换某一组件可能破坏路径、扩展接口或更新机制。请使用系统提供的整体更新方式。

OTA 后出现 MCU 版本不匹配怎么办？​

OTA 只支持自动更新 FLY-C8、FLY-C5、FLY-C8P 和 FLY-GEMINI V3 主板的 USB 固件。其他主板、CAN 固件、工具板及其他外接 MCU 均不支持自动更新，需要按对应产品教程手动烧录。

自动更新范围与检查方法：查看 OTA 后 MCU 固件更新说明

固件编译完成后去哪里找文件？​

编译产物位于：

/data/klipper/out/

实际文件可能是 klipper.bin 或 klipper.uf2，由 MCU 架构和引导程序配置决定。

固件编译说明：查看 Klipper 固件编译教程

插件与 Python 环境​

为什么找不到 ~/klippy-env/bin/python？​

FLYOS-FAST 使用系统 Python，不使用常见的 klippy-env 虚拟环境。应把命令中的 Python 解释器和 Klipper 路径改为系统实际路径。例如查询 CAN UUID 时使用：

python /data/klipper/scripts/canbus_query.py can0

不要只替换 Python 命令而保留错误的 ~/klipper/ 路径。

插件应该安装在哪里？​

插件仓库统一放在 /data/。需要向 Klipper 添加扩展文件时，优先使用软链接，并先确认插件教程要求的文件名称和依赖，不要批量复制整个插件目录到 Klipper。

安装规则与现有插件教程：查看插件安装说明

插件安装后没有生效怎么办？​

依次检查：

  1. 网络拉取步骤是否完整成功。

  2. 插件文件是否真实存在于 /data/。

  3. 软链接是否指向正确文件：

    readlink -f /data/klipper/klippy/extras/插件文件.py

  4. printer.cfg 是否加载了插件配置。

  5. Klipper 日志中是否出现缺少模块、依赖或配置项的报错。

不要为了绕过报错而删除安全配置或关闭 Klipper 的温度、限位及加热保护。

网页与网络​

各网页入口分别是什么？​

功能地址使用条件
Fluidd 或 Mainsailhttp://设备IP/Klipper 模式正常启动
OTA 管理页面http://设备IP:9998/上位机网络正常
GoCam 管理页面http://设备IP:8080/GoCam 已启用

为什么无法访问 设备IP:9999？​

FLYOS-FAST 默认不提供 fly-tools 网页服务，因此 9999 端口没有响应属于正常现象。系统配置和固件操作应使用对应的 FLYOS-FAST 文档与 SSH 命令。

主网页无法访问时如何检查？​

  1. 确认电脑和上位机处于同一局域网。

  2. 检查路由器中的设备地址，避免继续访问已经变化的旧 IP。

  3. 通过 SSH 查看当前网络地址：

    ip -br addr

  4. 查看是否存在启动失败的服务：

    systemctl --failed --no-pager

  5. 如果 SSH 也无法连接，请先检查系统是否完成启动，再排查网线、Wi-Fi 配置和供电。

SSH 连接方法：查看通过 SSH 连接上位机

打印、U 盘与摄像头​

U 盘可以识别，但无法开始打印怎么办？​

确认文件系统、G-code 扩展名、本地剩余空间和文件编码。部分非 UTF-8 G-code 会出现“本地上传正常，但从 U 盘无法开始”的情况。

U 盘打印与编码排查：查看 U 盘打印功能使用指南

摄像头没有画面怎么办？​

先确认摄像头支持 UVC 协议，再检查摄像头服务是否启用、设备节点是否正确以及分辨率是否受摄像头支持。不要同时启动两个占用同一摄像头的服务。

摄像头连接与配置：查看摄像头连接与使用

延迟摄影没有生成图片怎么办？​

先在浏览器中直接访问快照地址，确认能够返回单张图片。摄像头服务发生变化时，需要同步修改 moonraker.conf 中的 snapshoturl。

快照地址与日志排查：查看延迟摄影功能

Klipper 报错后应该从哪里开始排查？​

优先记录网页显示的原始报错，并查看 klippy.log 中最先出现的异常。最后出现的断开连接或重启提示通常只是后续现象，不一定是根因。

Klipper 报错索引：查看 Klipper 常见报错

日志与技术支持​

常用日志在哪里？​

日志路径
Klipper/usr/share/printer_data/logs/klippy.log
Moonraker/usr/share/printer_data/logs/moonraker.log
KlipperScreen/usr/share/printer_data/logs/klipperscreen.log
Crowsnest/usr/share/printer_data/logs/crowsnest.log
GoCam/usr/share/printer_data/logs/gocam.log
U 盘自动挂载/var/log/flyos-auto-mount.log

只查看最近内容时可以使用：

tail -n 100 /usr/share/printer_data/logs/klippy.log

检查主要服务状态：

systemctl status klipper moonraker --no-pager

检查系统资源：

uptime
free -h
df -h

联系技术支持时需要提供什么？​

请尽量一次性提供：

  • 上位机和主板的具体型号。
  • FLYOS-FAST 版本号。
  • 问题发生前执行的操作或修改内容。
  • 网页完整报错截图。
  • 完整的 klippy.log、moonraker.log 或对应服务日志。
  • 问题能否稳定复现，以及重启后是否仍然存在。

不要只提供截断后的最后几行日志，否则可能看不到真正的首个报错。发送配置和日志前，请删除 Wi-Fi 密码、云服务凭据、令牌等敏感信息。

Loading...