1. 从拆封到跑通Microduck 部署到底在折腾什么Microduck 这个名字听起来像是个玩具但它本质上是一套跑在 Radxa ZERO 3W 上的机器人控制软件。我第一次拿到这块板子的时候心里想的是“不就是刷个系统、装个软件嘛”结果从拆封到真正让机器人动起来中间踩的坑足够写一篇完整的实战记录。这篇文章就是把这套流程从头到尾捋一遍包括硬件准备、系统烧录、Rust 环境搭建、依赖库处理、编译调试以及最后跑通控制软件时遇到的各种意外情况。如果你手上正好有一块 Radxa ZERO 3W或者你对用 Rust 写机器人控制程序感兴趣那这篇内容应该能帮你省下不少查文档和试错的时间。Microduck 这个项目本身不算特别复杂但它涉及的东西挺杂嵌入式系统、Rust 交叉编译、硬件外设驱动、网络配置任何一个环节出问题都会让你卡住。我尽量把每个步骤背后的逻辑讲清楚而不是只给一串命令让你照抄。先说结论整个部署过程最耗时间的不是写代码而是环境配置和依赖管理。Rust 的包管理机制虽然强大但在嵌入式场景下交叉编译和目标平台适配会带来不少额外工作。再加上 Radxa ZERO 3W 本身的硬件特性有些默认配置需要手动调整。下面我按实际操作的顺序把整个过程拆开来讲。2. 硬件与系统准备Radxa ZERO 3W 的初始配置2.1 板子到手后先确认这几件事Radxa ZERO 3W 是一块体积很小的单板计算机尺寸跟树莓派 Zero 系列差不多但性能要强不少。它用的是 Rockchip 的处理器具体型号根据版本不同会有差异但整体架构是 ARM64。拿到板子之后先别急着上电检查一下包装里有没有这些东西板子本体、天线如果有无线模块、排针有些版本需要自己焊、以及电源接口的规格说明。电源这块要特别注意。Radxa ZERO 3W 通常通过 USB Type-C 供电但它对电流有一定要求。如果你用电脑的 USB 口直接供电可能会因为电流不足导致板子反复重启或者根本起不来。我建议用一个能稳定输出 5V/2A 以上的电源适配器别用那种便宜的多口充电头电压不稳会让调试过程变得非常痛苦。存储方面Radxa ZERO 3W 一般用 microSD 卡作为系统盘。选卡的时候别贪便宜低速卡会让系统响应慢到你想砸桌子。我实测下来Class 10 以上的卡基本够用如果有条件上 A2 级别的卡随机读写性能会好很多。容量建议至少 16GB因为后面装 Rust 工具链和编译依赖会占不少空间。2.2 系统镜像的选择与烧录Radxa 官方提供了多个系统镜像选项包括 Debian、Ubuntu 等。对于 Microduck 这个项目我建议用 Ubuntu 22.04 或者 Debian 11 以上的版本因为 Rust 工具链对新系统的支持更好而且很多依赖库的版本也比较合适。烧录镜像的工具有很多选择Balena Etcher 是比较省事的一个图形界面操作选好镜像文件和目标卡就行。如果你习惯命令行dd 命令也能用但要特别小心别写错设备名不然可能把电脑的硬盘给覆盖了。烧录完成后先别急着插到板子上把卡插回电脑检查一下 boot 分区里有没有需要修改的配置文件。对于 Radxa ZERO 3W有些镜像默认没有开启串口调试或者 SSH你需要手动在 boot 分区里加一些配置。具体来说检查 config.txt 或者 uEnv.txt 这类文件确保串口和网络相关的选项是打开的。如果你打算用无线网络还要提前把 WiFi 的 SSID 和密码写进配置文件不然板子起来之后你连不上它。2.3 首次上电与网络连通性验证把烧录好的卡插进板子接上电源等待系统启动。第一次启动会比较慢因为系统要做一些初始化工作。如果你接了 HDMI 显示器可以看到启动日志滚动。如果没有显示器那就等个两三分钟然后尝试用 SSH 连接。这里有个小技巧如果你不知道板子的 IP 地址可以先登录路由器的管理界面看看新接入的设备。或者用 nmap 扫一下局域网段找到开放 22 端口的设备。Radxa ZERO 3W 的默认主机名通常是 radxa 或者类似的名字可以用 ping 命令配合主机名试试。连上 SSH 之后第一件事是更新系统包。Ubuntu 和 Debian 都用 apt 管理软件包运行sudo apt update sudo apt upgrade把系统更新到最新状态。这个过程可能需要几分钟取决于网络速度和更新量。更新完成后重启一次确保所有变更生效。3. Rust 环境搭建从安装到镜像源优化3.1 为什么这个项目用 Rust 而不是 PythonMicroduck 选择 Rust 作为开发语言这个决定其实挺有意思。机器人控制软件对实时性和内存安全的要求比较高Python 虽然开发快但在资源受限的嵌入式设备上运行时的开销和垃圾回收的不确定性会成为问题。Rust 没有垃圾回收编译后的二进制文件直接跑在硬件上性能可预测而且它的所有权模型能在编译期就排除掉很多内存安全问题。不过 Rust 的代价是学习曲线陡峭而且工具链的配置比 Python 复杂不少。特别是在 ARM64 平台上有些 crate 可能需要额外的系统依赖才能编译通过。但一旦环境配好后续的开发和部署流程其实挺顺畅的。3.2 在 Radxa ZERO 3W 上安装 Rust 工具链在板子上直接安装 Rust 是最简单的方式虽然编译速度会比在电脑上慢一些但省去了交叉编译的配置麻烦。安装命令很简单curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh这个脚本会下载 rustup 并安装最新的稳定版工具链。安装过程中会问你选择哪种安装方式默认选 1 就行。安装完成后需要把 Rust 的二进制目录加到 PATH 环境变量里通常安装脚本会自动帮你改好 .bashrc 或 .profile但你需要重新登录或者手动 source 一下才能生效。验证安装是否成功rustc --version cargo --version如果能看到版本号输出说明工具链已经就绪。接下来建议安装几个常用的组件rustup component add rustfmt clippyrustfmt 用来格式化代码clippy 是静态检查工具这两个在开发过程中会经常用到。3.3 镜像源配置让依赖下载不再龟速Rust 默认从 crates.io 下载依赖包国内网络环境下速度可能不太理想。解决办法是配置镜像源。打开或创建~/.cargo/config.toml文件加入以下内容[source.crates-io] replace-with mirror [source.mirror] registry sparsehttps://mirrors.tuna.tsinghua.edu.cn/crates.io-index/这里用的是清华大学的镜像源稀疏索引格式下载速度会快很多。配置完成后可以试着创建一个新项目测试一下cargo new test_project cd test_project cargo build如果依赖下载顺利说明镜像源配置生效了。注意有些镜像源可能不是实时同步的如果你需要的 crate 版本比较新可能要多等一段时间或者换回官方源。3.4 交叉编译的取舍在板子上直接编译还是用电脑这个问题我纠结过一阵子。在 Radxa ZERO 3W 上直接编译 Rust 项目优点是配置简单不需要处理交叉编译工具链的各种坑。缺点是编译速度慢特别是项目依赖多的时候一次完整编译可能要十几分钟甚至更久。交叉编译的方案是在性能更强的电脑上编译好 ARM64 的二进制文件然后传到板子上运行。这样做速度快但需要配置交叉编译工具链还要处理链接库的路径问题。对于 Microduck 这种依赖不算特别复杂的项目我建议先在板子上直接编译等确认功能没问题了再考虑优化编译流程。如果你决定用交叉编译需要安装gcc-aarch64-linux-gnu这类工具链然后在 Cargo 配置里指定链接器。具体配置方式因项目而异这里不展开讲后面如果有机会再单独写一篇。4. Microduck 项目结构拆解与依赖处理4.1 拿到源码后先看这几个文件Microduck 的源码结构通常包含几个关键部分Cargo.toml定义项目元信息和依赖src/目录放源代码可能还有config/或scripts/目录存放配置文件和启动脚本。拿到源码后先别急着cargo build花几分钟看一下Cargo.toml里的依赖列表心里有个数。Cargo.toml里会列出项目依赖的所有 crate有些是纯 Rust 实现的编译起来没什么问题有些可能依赖系统库比如 OpenSSL、SQLite 之类的这些就需要提前在系统里装好对应的开发包。常见的系统依赖包括libssl-dev、libsqlite3-dev、pkg-config等用 apt 就能装sudo apt install libssl-dev libsqlite3-dev pkg-config build-essential4.2 依赖编译失败的常见原因与排查思路Rust 项目编译失败十有八九是依赖问题。错误信息通常会告诉你哪个 crate 编译不过以及缺少什么。常见的错误类型有几种第一种是缺少系统库。比如某个 crate 依赖 OpenSSL但系统里没装libssl-dev编译时就会报找不到头文件的错误。解决办法就是装上对应的开发包。第二种是版本冲突。不同的 crate 可能依赖同一个库的不同版本Cargo 会尝试解析出一个兼容的版本组合但有时候会失败。这种情况下错误信息会提示版本冲突的具体细节你可能需要手动调整Cargo.toml里的版本约束。第三种是目标平台不支持。有些 crate 只支持特定的操作系统或架构在 ARM64 上可能编译不过。遇到这种情况要么找替代方案要么看看有没有 feature flag 可以关闭相关功能。排查依赖问题时cargo build的输出信息是关键。仔细读错误信息通常会直接告诉你缺什么或者哪里不兼容。如果错误信息太长可以用cargo build 21 | tee build.log把输出保存到文件里方便慢慢看。4.3 用 sqlx 操作 MySQL 时的编译期陷阱Microduck 如果涉及数据存储可能会用到 sqlx 这个库。sqlx 的特点是编译期检查 SQL 语句这本来是个好事但在部署阶段会带来一些麻烦。因为编译期检查需要连接数据库如果你在板子上编译时数据库还没配好编译就会失败。解决办法有几种。第一种是设置SQLX_OFFLINEtrue环境变量让 sqlx 使用离线模式依赖之前生成的查询缓存文件。第二种是提前把数据库跑起来确保编译时能连上。第三种是改用运行时检查的 API牺牲一些类型安全性换取部署灵活性。我个人的做法是在开发阶段用在线模式确保 SQL 语句正确部署到板子上时用离线模式提前把.sqlx缓存目录一起打包过去。这样既保证了代码质量又避免了部署时的依赖问题。5. 编译、运行与调试让机器人真正动起来5.1 首次编译耐心与日志同样重要在 Radxa ZERO 3W 上首次编译 Microduck做好等待的心理准备。如果项目依赖比较多编译时间可能超过二十分钟。这时候别闲着可以开着htop看看 CPU 和内存占用情况。如果内存不足编译过程可能会被系统杀掉这时候需要增加交换空间或者减少并行编译的任务数。Cargo 默认会并行编译多个 crate可以通过-j参数控制并行度。如果板子内存比较小比如 2GB 或 4GB建议用cargo build -j 2限制同时编译的任务数避免内存耗尽。编译成功后二进制文件会放在target/debug/或target/release/目录下。调试阶段用 debug 版本就行虽然性能差一些但编译快而且有调试符号。等确认功能正常了再用--release重新编译获得更好的运行性能。5.2 运行时报错动态链接库找不到怎么办编译成功不代表能跑起来。我第一次运行 Microduck 的时候就遇到了动态链接库找不到的问题。错误信息大概是error while loading shared libraries: libxxx.so.x: cannot open shared object file。这是因为编译时链接了某个系统库但运行时系统找不到它。解决办法是确认这个库是否已经安装。用ldd命令可以查看二进制文件依赖的所有动态库ldd target/debug/microduck如果某个库显示not found就需要安装对应的包。有时候库已经装了但版本不对或者路径不在默认的搜索路径里。可以通过设置LD_LIBRARY_PATH环境变量来指定额外的库搜索路径export LD_LIBRARY_PATH/usr/local/lib:$LD_LIBRARY_PATH5.3 硬件外设初始化失败的排查链路机器人控制软件免不了要和硬件外设打交道比如 GPIO、I2C、SPI、串口等。Microduck 在启动时会初始化这些外设如果某个环节失败程序可能直接退出或者行为异常。排查这类问题时先确认硬件连接是否正确。杜邦线有没有插紧电源有没有供上这些看似低级的问题其实经常发生。然后检查系统层面外设是否可用比如 I2C 设备是否被识别i2cdetect -y 1如果能看到设备地址说明硬件层面没问题。如果看不到可能是驱动没加载或者设备树配置不对。Radxa ZERO 3W 的设备树配置可能需要手动调整具体方法取决于你用的镜像版本。还有一种情况是权限问题。访问 GPIO 或 I2C 设备通常需要 root 权限或者特定的用户组。把当前用户加到gpio或i2c组里可以避免每次都用 sudosudo usermod -aG gpio,i2c $USER改完之后需要重新登录才能生效。5.4 用日志和调试工具定位运行时问题Microduck 运行时如果行为不符合预期日志是第一手线索。Rust 项目通常用log和env_logger这类库来输出日志运行时可以通过环境变量控制日志级别RUST_LOGdebug ./target/debug/microduck这样能看到详细的调试信息包括每个模块的初始化和运行状态。如果日志还不够可以用gdb或者lldb做更深入的调试。在板子上跑 gdb 可能比较慢可以考虑用gdbserver在板子上运行然后在电脑上用交叉编译的 gdb 连接过去调试。另外strace是个很好用的工具可以跟踪系统调用看看程序到底卡在哪个环节strace -f ./target/debug/microduck输出会很多但仔细看能发现不少线索比如某个文件打不开、某个网络连接超时之类的。6. 部署完成后的稳定性验证与日常维护6.1 跑通不等于稳定持续运行测试怎么做程序能跑起来只是第一步机器人控制软件需要在长时间运行中保持稳定。我一般会做一个至少 24 小时的连续运行测试观察内存占用是否有增长趋势CPU 温度是否在合理范围以及有没有偶发的崩溃或重启。监控内存可以用free -h或者htop温度可以用sensors命令需要先安装lm-sensors。如果发现内存持续增长可能存在内存泄漏需要用valgrind或者 Rust 的heaptrack工具进一步分析。6.2 开机自启动配置让 Microduck 随系统启动每次手动启动程序太麻烦配置成 systemd 服务是更优雅的做法。创建一个服务文件[Unit] DescriptionMicroduck Robot Control Service Afternetwork.target [Service] Typesimple Userradxa WorkingDirectory/home/radxa/microduck ExecStart/home/radxa/microduck/target/release/microduck Restarton-failure RestartSec5 EnvironmentRUST_LOGinfo [Install] WantedBymulti-user.target把这个文件保存到/etc/systemd/system/microduck.service然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable microduck sudo systemctl start microduck用systemctl status microduck查看运行状态用journalctl -u microduck -f实时查看日志。6.3 版本更新与回滚别把自己锁死在坏版本上部署完成后后续可能需要更新 Microduck 的版本。更新之前先备份当前可用的二进制文件和配置文件这样万一新版本有问题可以快速回滚。更新流程一般是拉取新代码、编译、停止服务、替换二进制文件、启动服务、验证功能。如果新版本有问题把备份的文件恢复回去重启服务就行。这个过程可以写成一个脚本减少手动操作的出错概率。7. 几个让我印象深刻的坑与应对经验7.1 编译时内存不足导致进程被杀Radxa ZERO 3W 的内存有限编译大型 Rust 项目时如果并行任务太多很容易触发 OOM内存不足。系统会直接杀掉编译进程错误信息可能不太直观只显示signal: 9, SIGKILL。遇到这种情况减少并行编译任务数或者临时增加交换空间sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile这样能缓解内存压力但交换空间毕竟在 SD 卡上速度慢只能作为临时方案。7.2 镜像源同步延迟导致的依赖版本问题用国内镜像源虽然快但有时候会遇到同步延迟的问题。你需要的 crate 最新版本在镜像源上还没有Cargo 就会报找不到版本的错误。这时候可以临时切回官方源或者指定一个稍旧的版本。我一般会在Cargo.toml里把版本号写得更宽松一些比如用^1.0而不是1.0.3给 Cargo 更多选择空间。7.3 硬件外设的电源噪声问题这个问题比较隐蔽。机器人上的电机、舵机这类执行器在启动和停止时会产生电源噪声可能干扰到 Radxa ZERO 3W 的正常运行导致 I2C 通信失败或者系统重启。解决办法是给板子和执行器分别供电或者在电源线上加滤波电容。如果条件允许用独立的电源模块给板子供电执行器用另一路电源能避免大部分干扰问题。7.4 长时间运行后的 SD 卡磨损SD 卡的写入寿命有限如果 Microduck 频繁写日志或者数据库SD 卡可能会在几个月内出现坏块。缓解办法是把日志写到 tmpfs 或者外部存储减少对 SD 卡的写入。另外选择高耐久度的 SD 卡也能延长使用寿命。如果项目对可靠性要求高考虑用 eMMC 或者 SSD 替代 SD 卡。8. 关于 Rust 在嵌入式机器人项目中的实际体会用 Rust 做机器人控制软件最大的感受是“编译期痛苦运行期安心”。Rust 的所有权系统和类型检查在编译阶段就能发现很多潜在问题虽然一开始会被编译器折腾得够呛但一旦编译通过运行时崩溃的概率确实比 C 或 C 低很多。不过 Rust 在嵌入式领域的生态还在完善中有些硬件相关的 crate 文档不够详细遇到问题需要自己看源码或者去社区提问。另外交叉编译的配置对新手来说确实不太友好需要花时间理解工具链的工作原理。Microduck 这个项目本身不算复杂但它涉及的知识面挺广嵌入式系统、Rust 工具链、硬件外设、网络配置、服务管理。把这一套跑通之后再遇到类似的机器人控制项目心里就有底了。如果你也在折腾类似的东西希望这篇记录能帮你少走一些弯路。
