
文档教程【免费下载链接】pikvmOpen and inexpensive DIY IP-KVM based on Raspberry Pi项目地址https://gitcode.com/gh_mirrors/pi/pikvm点击查看免费下载导读PiKVM 在首次开机时会自动生成加密密钥并完成一系列系统初始化。官方为此提供了基于内存卡分区上pikvm.txt文件的开机预配置On-boot configuration机制你只需在刷写系统后、首次上电前用电脑编辑该文件中的若干KEYVALUE选项即可一次性完成 Wi-Fi 连接、静态 IP、SSH 端口修改等设置无需接显示器、键盘或串口。本文以 docs/on_boot_config.md 为主体结合 docs/wifi.md、docs/flashing_os.md、docs/faq.md 等仓库文档完整讲解所有可用选项并深入介绍面向生产环境的pikvm-scripts.d自动化脚本部署方案让你读完后能离线批量初始化任意数量的 PiKVM 设备。开机预配置的工作原理PiKVM OS 将内存卡划分为多个分区其中第一个分区为 FAT32 引导分区。在第一次启动时PiKVM 会执行以下动作生成加密密钥、初始化系统、生成唯一标识等。预配置机制的载体是位于第一个 FAT32 分区根目录下的pikvm.txt文件如果你还没有给 PiKVM 上过电该文件会存在且内容只有一行FIRST_BOOT1——这是触发首次开机初始化的开关不要删除它只需在其后追加你的配置行即可如果文件不存在例如旧镜像或已被处理过则自行创建一个空文件即可此时不要添加FIRST_BOOT选项所有设置应用完毕后pikvm.txt会被自动删除避免配置被重复应用或凭据长期留在卡上。每条配置必须严格独占一行KEYVALUE格式参数区分大小写。通过 pikvm.txt 配置 Wi-Fi这是最常用的场景把网线、显示器、键盘都省掉仅凭读卡器完成无头headless配置。操作步骤断电并取出 PiKVM 的内存卡将内存卡插入电脑挂载第一个 FAT32 分区找到pikvm.txt若文件内容为FIRST_BOOT1保留该行在其后追加配置若文件不存在创建一个空文件不添加FIRST_BOOT选项按如下格式写入 Wi-Fi 凭据ESSID 为网络名WIFI_ESSIDmynet WIFI_PASSWDps$$w0rd注意密码中的反斜杠\需要转义为\\。卸载分区把内存卡插回 PiKVM正常开机即可。使用须知硬件限制基于 Raspberry Pi Zero 2 W 的 PiKVM 设备不支持 5 GHz 频段也不支持 WPA3请使用 2.4 GHz 的 WPA2 网络信道 13 问题在支持信道 13 的国家/地区某些设备可能无法连接。若遇到此情况需要在路由器上将信道限制在 111即禁用信道 1214或关闭自动信道扫描模式文件会被删除设置应用成功后pikvm.txt即被删除配置项不会重复生效WPA3 为实验特性默认仅支持 WPA2。若你的路由器是 WPA2/3 混合模式而 PiKVM 连不上请使用下文WIFI_WPA231选项。与手动配置 Wi-Fi 的对比如果不想用预配置机制也可以参照 docs/wifi.md 在系统内手动配置使用rw命令将文件系统切换为可写创建/etc/systemd/network/wlan0.network并设置 DHCP再用wpa_passphrase生成/etc/wpa_supplicant/wpa_supplicant-wlan0.conf最后systemctl enable wpa_supplicantwlan0.service并以ro恢复只读。手动方式适合系统已可访问如已联网或有串口的二次调整而pikvm.txt方式对 Zero 2 W 这类无网线接口的板子是必选路径见 docs/wifi.md 中的说明。其他可用选项逐项解析除 Wi-Fi 外以下参数均可按同样方式写入pikvm.txt。注意每个参数必须单独占一行。系统初始化类选项说明FIRST_BOOT1触发首次开机初始化见下文详解ENABLE_AVAHI1触发 Avahi 服务生成如有需要并启用avahi-daemon默认禁用ENABLE_OTG_SERIAL1仅 V2在 USB 模拟器上启用虚拟串口可让被控主机侧通过该串口登录 PiKVM出于安全原因默认禁用SSH_PORT1234将 SSH 服务端口从默认的 22 改为指定端口示例为 1234FIRST_BOOT1 的完整初始化清单当FIRST_BOOT1存在时首次开机将执行以下操作为内部 systemd 机制生成唯一的/etc/machine-id生成唯一的 SSH 主机密钥host keys为 HTTPS 与 VNC 生成唯一的 SSL 证书生成包含 Pi 序列号的 Avahi ZeroConf 服务/etc/avahi/services/pikvm.service但默认保持 Avahi禁用状态仅 V2将 Mass Storage 镜像分区重新格式化使其扩展填满 SD 卡末尾的可用空间执行一些零碎操作如fc-cache更新。需要特别强调的是FIRST_BOOT1不会将系统重置为出厂状态PiKVM OS 也没有恢复出厂设置的官方途径唯一方法就是重新刷写系统镜像见 docs/flashing_os.md。以太网配置选项选项说明ETH_DHCP1以太网口使用 DHCP 自动获取地址。这是 PiKVM OS 的默认行为ETH_ADDR192.168.0.100/24配置静态 IPCIDR 格式ETH_DNS8.8.8.8配置 DNS 服务器ETH_GW192.168.0.1配置默认网关ETH_ADDR、ETH_DNS、ETH_GW三个选项必须同时设置否则会产生错误配置。静态 IP 仅支持 IPv4如需 IPv6需要在运行中的系统里修改 systemd-networkd 的配置文件/etc/systemd/network/下的 network 文件参见 docs/faq.md 中关于静态 IP 的说明。特别提醒在 docs/faq.md 中官方明确警告手动配置静态地址时务必保留/24这种 CIDR 后缀否则配置不生效且 PiKVM 会变得不可达——这正是预配置机制替你规避的典型坑。Wi-Fi 高级配置选项选项说明WIFI_ESSIDfooWi-Fi 网络名ESSID必须与WIFI_PASSWD同时设置WIFI_PASSWDbarWi-Fi 密码必须与WIFI_ESSID同时设置WIFI_WPA31启用连接 WPA3 网络的实验性支持。⚠️仅适用于 2026.08.16 的新镜像且仅限基于 Raspberry Pi 4 的设备WIFI_WPA231允许以 WPA2 模式连接 WPA2/WPA3 混合网络本质是启用 WPA2 PMFProtected Management Frame受保护管理帧支持。仅适用于 2025.03.03 的新镜像WIFI_HIDDEN1允许连接隐藏 SSID 的 Wi-Fi 网络。仅适用于 2024.03.12 的新镜像WIFI_ADDR192.168.0.100/24Wi-Fi 静态 IPCIDR 格式WIFI_DNS8.8.8.8Wi-Fi DNS 服务器WIFI_GW192.168.0.1Wi-Fi 默认网关WIFI_REGDOMUS修改 Wi-Fi 无线监管域regulatory domain使用 ISO 3166-1 alpha-2 国家代码例如美国为US静态 IP 三件套WIFI_ADDR/WIFI_DNS/WIFI_GW必须与WIFI_ESSID、WIFI_PASSWD同时设置否则会产生错误配置。与以太网一样Wi-Fi 静态 IP 也仅支持 IPv4。这些选项与 docs/wifi.md 中手动配置wpa_supplicant的方式一一对应WIFI_WPA31对应在network{}块中加入key_mgmtSAE与ieee80211w2并设置全局sae_pwe2WIFI_WPA231对应key_mgmtWPA-PSK-SHA256 WPA-PSK与ieee80211w1WIFI_HIDDEN1对应全局scan_ssid1WIFI_REGDOM对应全局countryUS。理解手动配置有助于排查预配置失效时的底层原因。生产环境批量部署pikvm-scripts.d 与自定义镜像对于生产环境往往需要把 PiKVM 自动集成到已有基础设施中如注册到监控系统、注入 SSH 公钥、写入内部证书等这类动作通常由管理员编写的脚本完成。PiKVM OS 为此提供了官方扩展点。脚本目录机制将脚本放入与pikvm.txt同分区的pikvm-scripts.d目录在 PiKVM 系统内对应路径为/boot/pikvm-scripts.d如果pikvm.txt存在则其中的参数会先被应用随后系统检查pikvm-scripts.d目录是否存在若存在则按字母序依次执行其中的脚本单个脚本执行失败会被忽略——官方明确假定脚本作者应当自行处理错误情况因此建议在脚本内部做好错误处理与幂等性设计。重启请求如果脚本需要重启操作系统只需创建一个空文件/boot/pikvm-reboot.txt。重启动作会在所有脚本执行完毕后统一进行一次避免多次无谓重启。面向大规模部署的自定义镜像如果不想在每张内存卡上手动拷贝脚本更合理的做法是构建包含所需内容的自定义 OS 镜像。构建方法见 docs/building_os.md克隆 PiKVM OS 构建环境后在config.mk中配置BOARD如rpi4、zero2w、PLATFORM如v2-hdmi、v3-hdmi、HOSTNAME、LOCALE、TIMEZONE、ROOT_PASSWD、WEBUI_ADMIN_PASSWD等变量依次执行make os与make image得到*.img镜像再按 docs/flashing_os.md 刷写到内存卡。将预置脚本固化进镜像后即可实现刷卡即上线的流水线式部署。与刷写流程的衔接需要注意PiKVM OS不支持RPi Imager 的自定义选项功能——docs/flashing_os.md 明确警告RPi Imager 的定制选项是为 Raspberry Pi OS 设计的应用到 PiKVM OS 会导致镜像损坏。正确的姿势是用 RPi Imager 或dd刷写原始镜像后拒绝所有定制选项再通过pikvm.txt/pikvm-scripts.d完成配置。常见问题与排错要点Wi-Fi 连不上信道问题检查 2.4 GHz 信道若路由器使用了信道 1214请改回 111详见 docs/faq.mdWPA3 连不上WIFI_WPA31仅为实验性支持且有镜像版本与硬件限制 2026.08.16、RPi 4建议将网络切换为 WPA2/WPA3 混合模式并使用WIFI_WPA231静态 IP 不生效确认 CIDR 后缀如/24已写全且以太网静态 IP 三选项或 Wi-Fi 静态 IP 五选项均同时设置无法找到设备 IPDHCP 模式下可通过路由器客户端列表或 mDNS 发现设备docs/cheatsheet.mdpikvm.txt意外丢失文件应用后会被自动删除若仍需调整可在系统内以rw挂载可写后手动修改 network 文件见 docs/wifi.md 与 docs/faq.md。总结pikvm.txt是 PiKVM 官方提供的刷卡即配置机制通过一行行KEYVALUE参数即可在首次上电前完成 Wi-Fi含 WPA2/WPA3/隐藏网络/静态 IP/监管域、以太网静态 IP、SSH 端口、Avahi 与 OTG 串口等全部网络与系统初始化设置配合pikvm-scripts.d字母序脚本目录与pikvm-reboot.txt重启标记再结合自定义镜像构建可以完全自动化地批量交付生产环境中的 PiKVM 设备。掌握这套机制就等于掌握了 PiKVM 无头部署与规模化运维的入口。相关文档docs/on_boot_config.md本篇主体、docs/wifi.md手动 Wi-Fi 配置对照、docs/flashing_os.md镜像刷写、docs/building_os.md自定义镜像构建、docs/faq.md常见问题。赞分享文档教程【免费下载链接】pikvmOpen and inexpensive DIY IP-KVM based on Raspberry Pi项目地址https://gitcode.com/gh_mirrors/pi/pikvm点击查看免费下载相关推荐xmrig静态编译实战指南从环境配置到生产级部署xmrig静态编译实战指南从环境配置到生产级部署 在Linux环境下构建高性能加密货币挖矿软件时静态编译技术能够显著提升软件的可移植性与部署效率。本文将系统区块链高性能计算transitions状态机部署指南生产环境最佳配置实践transitions状态机部署指南生产环境最佳配置实践 在复杂的软件系统中状态管理是确保业务流程正确执行的关键。transitions是一个轻量级、面向对后端流程编排Transitions部署指南生产环境状态机的最佳配置Transitions部署指南生产环境状态机的最佳配置 Transitions是一个轻量级的Python状态机库它提供了强大的状态管理和转换功能特别适合在后端流程编排上一篇网络资源捕获大师5分钟掌握全平台媒体下载技巧下一篇torchtune数据加载器白皮书大数据训练效率创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考