企业官网建设流程全解析

• 文档
• 教程

导读

PiKVM 在首次开机时会自动生成加密密钥并完成一系列系统初始化。官方为此提供了基于内存卡分区上pikvm.txt文件的"开机预配置（On-boot configuration）"机制：你只需在刷写系统后、首次上电前，用电脑编辑该文件中的若干KEY=VALUE选项，即可一次性完成 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_BOOT=1——这是触发首次开机初始化的开关，不要删除它，只需在其后追加你的配置行即可；
• 如果文件不存在（例如旧镜像或已被处理过），则自行创建一个空文件即可，此时不要添加FIRST_BOOT选项；
• 所有设置应用完毕后，pikvm.txt会被自动删除，避免配置被重复应用或凭据长期留在卡上。

每条配置必须严格独占一行（KEY=VALUE格式），参数区分大小写。

通过 pikvm.txt 配置 Wi-Fi

这是最常用的场景：把网线、显示器、键盘都省掉，仅凭读卡器完成无头（headless）配置。

操作步骤

1. 断电并取出 PiKVM 的内存卡；

2. 将内存卡插入电脑，挂载第一个 FAT32 分区；

3. 找到pikvm.txt：

   • 若文件内容为FIRST_BOOT=1，保留该行，在其后追加配置；
   • 若文件不存在，创建一个空文件（不添加FIRST_BOOT选项）；

4. 按如下格式写入 Wi-Fi 凭据（ESSID 为网络名）：

   WIFI_ESSID='mynet' WIFI_PASSWD='p@s$$w0rd'

   注意：密码中的反斜杠\需要转义为\\。

5. 卸载分区，把内存卡插回 PiKVM，正常开机即可。

使用须知

• 硬件限制：基于 Raspberry Pi Zero 2 W 的 PiKVM 设备不支持 5 GHz 频段，也不支持 WPA3，请使用 2.4 GHz 的 WPA2 网络；
• 信道 13 问题：在支持信道 13 的国家/地区，某些设备可能无法连接。若遇到此情况，需要在路由器上将信道限制在 1～11（即禁用信道 12～14），或关闭自动信道扫描模式；
• 文件会被删除：设置应用成功后pikvm.txt即被删除，配置项不会重复生效；
• WPA3 为实验特性：默认仅支持 WPA2。若你的路由器是 WPA2/3 混合模式而 PiKVM 连不上，请使用下文WIFI_WPA23=1选项。

与手动配置 Wi-Fi 的对比

如果不想用预配置机制，也可以参照 docs/wifi.md 在系统内手动配置：使用rw命令将文件系统切换为可写，创建/etc/systemd/network/wlan0.network并设置 DHCP，再用wpa_passphrase生成/etc/wpa_supplicant/wpa_supplicant-wlan0.conf，最后systemctl enable wpa_supplicant@wlan0.service并以ro恢复只读。手动方式适合系统已可访问（如已联网或有串口）的二次调整，而pikvm.txt方式对 Zero 2 W 这类无网线接口的板子是必选路径（见 docs/wifi.md 中的说明）。

其他可用选项：逐项解析

除 Wi-Fi 外，以下参数均可按同样方式写入pikvm.txt。注意每个参数必须单独占一行。

系统初始化类

FIRST_BOOT=1 的完整初始化清单

当FIRST_BOOT=1存在时，首次开机将执行以下操作：

• 为内部 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_BOOT=1不会将系统重置为出厂状态，PiKVM OS 也没有"恢复出厂设置"的官方途径，唯一方法就是重新刷写系统镜像（见 docs/flashing_os.md）。

以太网配置选项

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 高级配置选项

静态 IP 三件套（WIFI_ADDR/WIFI_DNS/WIFI_GW）必须与WIFI_ESSID、WIFI_PASSWD同时设置，否则会产生错误配置。与以太网一样，Wi-Fi 静态 IP 也仅支持 IPv4。

这些选项与 docs/wifi.md 中手动配置wpa_supplicant的方式一一对应：WIFI_WPA3=1对应在network={}块中加入key_mgmt=SAE与ieee80211w=2并设置全局sae_pwe=2；WIFI_WPA23=1对应key_mgmt=WPA-PSK-SHA256 WPA-PSK与ieee80211w=1；WIFI_HIDDEN=1对应全局scan_ssid=1；WIFI_REGDOM对应全局country=US。理解手动配置有助于排查预配置失效时的底层原因。

生产环境批量部署：pikvm-scripts.d 与自定义镜像

对于生产环境，往往需要把 PiKVM 自动集成到已有基础设施中（如注册到监控系统、注入 SSH 公钥、写入内部证书等），这类动作通常由管理员编写的脚本完成。PiKVM OS 为此提供了官方扩展点。

脚本目录机制

将脚本放入与pikvm.txt同分区的pikvm-scripts.d目录（在 PiKVM 系统内对应路径为/boot/pikvm-scripts.d）：

1. 如果pikvm.txt存在，则其中的参数会先被应用；
2. 随后系统检查pikvm-scripts.d目录是否存在，若存在则按字母序依次执行其中的脚本；
3. 单个脚本执行失败会被忽略——官方明确假定脚本作者应当自行处理错误情况，因此建议在脚本内部做好错误处理与幂等性设计。

重启请求

如果脚本需要重启操作系统，只需创建一个空文件/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 信道，若路由器使用了信道 12～14，请改回 1～11（详见 docs/faq.md）；
• WPA3 连不上：WIFI_WPA3=1仅为实验性支持且有镜像版本与硬件限制（>= 2026.08.16、RPi 4），建议将网络切换为 WPA2/WPA3 混合模式并使用WIFI_WPA23=1；
• 静态 IP 不生效：确认 CIDR 后缀（如/24）已写全，且以太网静态 IP 三选项或 Wi-Fi 静态 IP 五选项均同时设置；
• 无法找到设备 IP：DHCP 模式下可通过路由器客户端列表或 mDNS 发现设备（docs/cheatsheet.md）；
• pikvm.txt意外丢失：文件应用后会被自动删除，若仍需调整，可在系统内以rw挂载可写后手动修改 network 文件（见 docs/wifi.md 与 docs/faq.md）。

总结

pikvm.txt是 PiKVM 官方提供的"刷卡即配置"机制：通过一行行KEY=VALUE参数，即可在首次上电前完成 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（常见问题）。

• 文档
• 教程