技术文档
本文档提供MPXE的技术配置详情、API接口说明和故障排查指南。
入门指南请查看 快速开始，无人值守配置请查看 无人值守文档。
配置文件详解
配置文件位于
网络配置参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| DHCP_SERVER_IP | 192.168.2.2 | PXE服务器IP地址（首次启动自动识别） |
| DHCP_SERVER_NIC | eth0 | 监听的网络接口名称（首次启动自动选择第一个UP网卡） |
| DHCP_SERVER_PORT | 67 | DHCP服务端口 |
| DHCP_OFFER_BEGIN | 192.168.2.100 | DHCP地址池起始IP（自动识别后计算） |
| DHCP_OFFER_END | 192.168.2.150 | DHCP地址池结束IP（自动识别后计算） |
| DHCP_SUBNET | 255.255.255.0 | 子网掩码（首次启动自动识别） |
| DHCP_ROUTER | 192.168.2.1 | 网关地址 |
| DHCP_DNS | 8.8.8.8 | DNS服务器地址 |
| DHCP_FILESERVER | 192.168.2.2 | 文件服务器地址（通常与服务器IP一致） |
| DHCP_BROADCAST | 自动计算 | 广播地址（为空时根据IP和子网掩码自动计算） |
| DHCP_LEASE_DURATION | 7200 | DHCP租约有效期（秒），到期自动清理 |
| DHCP_CHECK_IP_AVAILABILITY | true | 分配IP前进行ARP缓存+ping双重验证，避免IP冲突 |
| HTTP_SERVER_IP | 172.0.0.1 | HTTP服务监听地址（默认为回环地址） |
服务配置参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| HTTP_PORT | 80 | HTTP服务端口（Web管理界面端口，支持自定义） |
| TFTP_PORT | 69 | TFTP服务端口 |
| TFTP_SERVER_IP | 动态 | TFTP服务器IP（自动同步DHCP_SERVER_IP） |
| DHCP_MODE_PROXY | false | ProxyDHCP模式开关（用于已有DHCP服务器的环境） |
| LOG_LEVEL | INFO | 日志级别：DEBUG/INFO/WARNING/ERROR/CRITICAL |
| LEASES_FILE | config/leases.json | DHCP租约持久化文件路径 |
| SYSLOG_SERVER | ""（空） | 远程Syslog服务器地址（留空则不启用） |
| SYSLOG_PORT | 514 | 远程Syslog服务器端口 |
访问控制参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| DHCP_WHITELIST | [] | MAC白名单列表，留空表示允许所有MAC访问 |
| DHCP_BLACKLIST | [] | MAC黑名单列表，优先级高于白名单 |
引导配置参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| USE_DHCP | true | 启用DHCP服务 |
| USE_HTTP | true | 启用HTTP传输（推荐，速度更快） |
| USE_TFTP | true | 启用TFTP服务 |
| MENU_DEFAULT | ""（空） | 默认启动项名称（匹配ISO目录ID，匹配不到则默认第一个） |
| MENU_TIMEOUT | 1200 | 菜单超时时间（秒，如1200表示20分钟，-1为永不超时） |
| NETBOOT_DIR | netboot | 网络引导文件根目录 |
| NETBOOT_FILE | ""（空） | 强制指定的引导文件名（空则根据架构自动选择） |
| STATIC_CONFIG | ""（空） | 静态租约配置 |
端口需求汇总
| 端口 | 协议 | 用途 |
|---|---|---|
| 80 | TCP | HTTP服务、Web管理页面 |
| 67 | UDP | DHCP服务（PXE引导） |
| 69 | UDP | TFTP服务（引导文件传输） |
| 111, 2049 | TCP | NFS服务（镜像文件传输） |
服务详解
DHCP服务
DHCP服务负责为客户端分配IP地址并提供PXE引导信息，实现基于RFC2131/RFC2132标准。
- 监听UDP端口67
- 支持标准DHCP和ProxyDHCP两种模式
- 自动识别客户端架构（UEFI x86/ARM64/LoongArch64）
- 根据客户端架构自动返回对应的GRUB2引导文件
- 维护IP地址租约记录到leases.json
- 支持IP冲突检测（ARP缓存+ping双重验证）
- 租约持久化，服务重启后自动恢复
架构识别规则
| 客户端架构 | 架构代码 | 引导文件 |
|---|---|---|
| EFI IA32 | 6 | grub_efi/x86_64.efi |
| EFI x86-64 | 7, 9 | grub_efi/x86_64.efi |
| ARM64 | 11 | grub_efi/arm64.efi |
| LoongArch64 | 39, 40 | grub_efi/loongarch64.efi |
| MIPS (3A4000) | 12 | grub_efi/mips64el.efi |
TFTP服务
TFTP服务用于传输小型引导文件，基于RFC1350和RFC2348标准实现。
- 监听UDP端口69
- 支持可变块大小传输（blksize选项，最高5120字节）
- 支持文件大小查询（tsize选项）
- 自动超时重传机制（默认重试10次）
HTTP服务
HTTP服务提供大文件传输和Web管理界面。
- 提供Web管理界面（默认端口80）
- 支持ISO镜像文件高速传输
- 支持分块传输（Range请求）
- 提供实时日志SSE推送
- RESTful API接口
API接口
HTTP服务提供RESTful API接口，用于Web管理和客户端通信。
服务端API
| 接口路径 | 方法 | 说明 | 参数 |
|---|---|---|---|
| /web/get_info | GET | 获取服务器网卡信息、服务状态和配置 | - |
| /web/get_server_info | GET | 获取服务端配置和ISO镜像列表 | - |
| /web/get_blackwhitelist | GET | 获取黑白名单配置 | - |
| /web/set_blackwhitelist | POST | 设置黑白名单 | whitelist, blacklist |
| /web/saveandrestart | POST | 保存网络配置并重启服务 | ip_address, gateway, name, netmask, ip_start, ip_end |
| /web/setserver | POST | 设置服务器参数 | log_level, menu_timeout, menu_default, http_port |
| /web/getisoipxe | GET | 获取ISO和PXE配置 | - |
| /web/setisoipxe | POST | 设置ISO和PXE配置 | ipxename, isoname, extpathname, autoinstall, grubcfg, autoinstallcfg |
| /web/delisoipxe | POST | 删除ISO配置 | ipxename |
| /web/rescan | GET | 重新扫描ISO目录 | - |
| /web/restart | GET | 重启所有服务 | - |
| /web/log | GET | 获取日志内容 | lines (可选，默认500) |
| /web/log/sse | GET | SSE实时日志流 | - |
| /web/getclientlist | GET | 获取客户端列表 | - |
客户端API
| 接口路径 | 方法 | 说明 | 参数 |
|---|---|---|---|
| /monitor/statusreport | GET | 客户端上报安装状态 | progress, status, msg, mac |
故障排查
服务启动失败
| 问题 | 解决方案 |
|---|---|
| 提示"NFS服务未安装" | 执行： |
| 提示"iso文件夹中未发现镜像文件" | 确认已将ISO镜像放入iso目录，并重启服务 |
| 端口被占用 | 检查是否有其他服务占用了67、69、80等端口： |
客户端引导失败
| 问题 | 检查项 | 解决方案 |
|---|---|---|
| DHCP发现超时 | 防火墙、客户端PXE支持 | 检查防火墙设置；确认客户端与服务器在同一网络；检查客户端网卡PXE功能 |
| TFTP超时 | TFTP服务状态、网络带宽 | 检查TFTP服务状态；确认网络带宽足够（建议千兆网络） |
| 引导文件找不到 | netboot目录结构 | 检查netboot目录结构是否完整；查看日志获取详细信息 |
| 架构不匹配 | UEFI设置 | 确认客户端UEFI设置与ISO镜像架构匹配 |
安装过程问题
| 问题 | 解决方案 |
|---|---|
| NFS挂载失败 | 检查NFS服务状态；确认/etc/exports配置正确；检查防火墙NFS端口 |
| 镜像下载慢 | 建议启用HTTP传输模式（设置USE_HTTP=true），速度更快 |
| 应答文件不生效 | 检查应答文件语法；确认grub配置中指定了正确的应答文件路径 |
日志查看
详细日志文件位于
可通过以下方式查看：
- Web界面实时日志查看
- 命令行查看：
tail -f logs/pxe.log - 设置日志级别为DEBUG获取更详细信息
获取帮助
如问题无法解决，请提供以下信息：
- MPXE版本
- 服务器操作系统和版本
- 客户端机器型号和架构
- 相关日志内容（logs/pxe.log）
联系方式：Q群 390480890