INSTALL.md - 编译安装配置文档

本文档持续更新，记录 MPPT Monitor 在各平台上的编译、安装、运行配置。

一、系统要求

项目	最低要求
操作系统	Ubuntu 24.04 LTS (x86_64) / Raspberry Pi OS (aarch64/arm64)
编译器	GCC 12+ (推荐 GCC 13+)
内存	64MB 可用 RAM
磁盘	50MB 可用空间
网络	TCP 出站连接 (discover.zhonjin.com:40635)

二、Ubuntu 24.04 环境配置

2.1 安装编译工具链

# 更新软件源
sudo apt-get update

# 安装基础编译工具
sudo apt-get install -y build-essential gcc g++ make

# 安装 OpenSSL 开发库（TLS 支持）
sudo apt-get install -y libssl-dev

# 可选：安装 pkg-config（自动检测 OpenSSL 路径）
sudo apt-get install -y pkg-config

# 验证安装
gcc --version       # 应显示 13.x+
openssl version     # 应显示 3.x+

2.2 编译项目

# 进入项目目录
cd mppt_monitor

# 编译（自动检测 OpenSSL）
make

# 编译输出在 build/mppt_monitor
ls -la build/mppt_monitor

2.3 运行

# 直接运行
./build/mppt_monitor

# 或
make run

2.4 安装为系统服务

# 安装到 /usr/local/bin
sudo make install

# 安装并启用 systemd 服务（开机自启 + 崩溃自动重启）
sudo make systemd

# 管理服务
sudo systemctl start mppt-monitor     # 启动
sudo systemctl stop mppt-monitor      # 停止
sudo systemctl restart mppt-monitor   # 重启
sudo systemctl status mppt-monitor    # 查看状态
sudo journalctl -u mppt-monitor -f    # 查看实时日志

三、树莓派 5 8G 环境配置

3.1 系统安装

下载 Raspberry Pi OS (64-bit) 或 Ubuntu Server 24.04 for RPi5
使用 Raspberry Pi Imager 烧录到 SD 卡 / NVMe SSD
首次启动配置网络（WiFi 或有线）

3.2 安装编译环境

# Ubuntu Server 24.04 for RPi5
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev pkg-config

# Raspberry Pi OS (Debian-based)
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev pkg-config

# 验证
gcc --version
uname -m    # 应显示 aarch64

3.3 编译（与 Ubuntu 完全相同）

cd mppt_monitor
make

Makefile 会自动检测平台架构，无需额外配置。

3.4 树莓派 5 特殊注意事项

项目	说明
GPIO 冲突	本项目使用 TCP 网络通信，不涉及 GPIO，无冲突
散热	建议安装散热片，长时间运行 CPU 温度可能较高
电源	使用官方 27W USB-C PD 电源，确保稳定供电
网络	优先使用有线网络，WiFi 可能增加延迟
存储	推荐使用 NVMe SSD 而非 SD 卡，提升可靠性

3.5 树莓派 5 性能优化（可选）

# 设置 CPU 性能模式（减少调度延迟）
echo performance | sudo tee /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# 禁用蓝牙（如不需要，减少中断）
sudo systemctl disable hciuart

# 优化网络参数
sudo sysctl -w net.core.rmem_max=16777216
sudo sysctl -w net.core.wmem_max=16777216

四、自定义 OpenSSL 路径编译

如果 OpenSSL 安装在非标准路径（如 /opt/openAI/Lib64U/），使用以下命令：

# 方式一：手动指定编译参数
gcc src/main.c src/modbus_client.c src/web_server.c \
    lib/cJSON-1.7.19/cJSON.c lib/mongoose-7.22/mongoose.c \
    -W -Wall -Wextra -g -I. \
    -Isrc -Ilib/cJSON-1.7.19 -Ilib/mongoose-7.22 \
    -DMG_ENABLE_OPENSSL=1 \
    -I/opt/openAI/Lib64U/include \
    -L/opt/openAI/Lib64U/lib \
    -lssl -lcrypto \
    -lpthread -lm \
    -o mppt_monitor

# 方式二：设置环境变量后使用 make
export CFLAGS="-DMG_ENABLE_OPENSSL=1 -I/opt/openAI/Lib64U/include"
export LDFLAGS="-L/opt/openAI/Lib64U/lib -lssl -lcrypto -lpthread -lm"
make

五、无 OpenSSL 编译（纯 HTTP）

如果不需要 TLS/HTTPS 支持：

# 确保不定义 MG_ENABLE_OPENSSL
make CFLAGS="-Wall -Wextra -Wno-unused-parameter -O2 -g"

六、调试模式编译

# 带 AddressSanitizer 和调试符号
make debug

# 使用 GDB 调试
gdb ./build/mppt_monitor
(gdb) run

七、项目目录结构

mppt_monitor/
├── Makefile                  # 构建脚本
├── INSTALL.md                # 本文档
├── TECHNICAL.md              # 技术方案文档
├── CHANGELOG.md              # 变更日志
├── src/
│   ├── main.c                # 主程序入口
│   ├── modbus_client.h       # Modbus 客户端头文件
│   ├── modbus_client.c       # Modbus RTU over TCP 实现
│   ├── web_server.h          # HTTP 服务器头文件
│   └── web_server.c          # Mongoose HTTP 服务器实现
├── lib/
│   ├── cJSON-1.7.19/         # cJSON 库源码
│   │   ├── cJSON.c
│   │   └── cJSON.h
│   └── mongoose-7.22/        # Mongoose 库源码
│       ├── mongoose.c
│       └── mongoose.h
└── build/                    # 编译输出目录
    └── mppt_monitor          # 可执行文件

八、常见问题

Q1: 编译报错 "openssl/ssl.h: No such file or directory"

sudo apt-get install libssl-dev

Q2: 运行时 "Connection refused" 或 "DNS resolution failed"

检查网络连接：ping discover.zhonjin.com
检查防火墙是否放行 40635 端口出站
检查 DNS 解析：nslookup discover.zhonjin.com

Q3: Web 服务端口 8085 被占用

修改 src/web_server.h 中的 WEB_SERVER_PORT 和 WEB_SERVER_LISTEN_URL，然后重新编译。

Q4: 树莓派上编译很慢

正常现象，树莓派 5 编译此项目约需 30-60 秒。可以使用交叉编译加速：

# 在 x86 主机上交叉编译 ARM64
sudo apt-get install gcc-aarch64-linux-gnu
make CC=aarch64-linux-gnu-gcc

Q5: 程序崩溃或 Segfault

# 使用 debug 模式编译，启用 ASAN
make debug
./build/mppt_monitor
# ASAN 会打印详细的内存错误信息

九、版本兼容性矩阵

平台	GCC	OpenSSL	状态
Ubuntu 24.04 x86_64	13.3	3.0.13	已验证
Raspberry Pi 5 (RPi OS)	12.2+	3.0.x	兼容
Raspberry Pi 5 (Ubuntu 24.04)	13.x	3.0.x	兼容

最后更新: 2026-08-04

INSTALL.md 6.3 KB História Raw