fix: 全面修复bug并打包MPPT监控系统v2.3.2

- 修复POSIX兼容性(_GNU_SOURCE缺失)
- 修复缓冲区溢出风险(strncpy→snprintf)
- 修复文件句柄泄漏(db_query_history)
- 增加线程安全互斥锁保护(latest_data)
- 消除编译警告
- 更新CHANGELOG.md(v2.3.2)
- 更新TECHNICAL.md(树莓派5完整配置)
- 创建FAQ.md问答归档文档
- 打包完整项目为tar.gz

Coze-Commit-Type: user
Coze-User-ID: 256649704250362
Coze-Conversation-ID: 11640025

mppt_monitor/CHANGELOG.md

@@ -385,8 +385,9 @@ Type:Custom (自定义) Mode:DC-DC SW:v115
 
 | 库 | 版本 | 用途 |
 |----|------|------|
-| Mongoose | 7.22 | HTTP 服务器 |
+| Mongoose | 7.23 | HTTP 服务器 |
 | cJSON | 1.7.19 | JSON 序列化 |
+| SQLite3 | 3.x | 历史数据存储 |
 | OpenSSL | 3.x | TLS 支持（可选） |
 | pthread | - | 多线程 |
 

mppt_monitor/FAQ.md

@@ -0,0 +1,487 @@
+# FAQ.md - 问题解答归档
+
+> 本文档持续更新，归档开发和使用过程中遇到的所有问题及解答。
+
+---
+
+## 目录
+
+1. [编译问题](#1-编译问题)
+2. [运行问题](#2-运行问题)
+3. [Modbus 通信问题](#3-modbus-通信问题)
+4. [HTTP API 问题](#4-http-api-问题)
+5. [数据库问题](#5-数据库问题)
+6. [树莓派部署问题](#6-树莓派部署问题)
+
+---
+
+## 1. 编译问题
+
+### Q1.1: 编译时提示 `sqlite3.h: No such file or directory`
+
+**问题描述**:
+```
+src/db.h:11:10: fatal error: sqlite3.h: No such file or directory
+   11 | #include <sqlite3.h>
+```
+
+**原因**: 未安装 SQLite3 开发库
+
+**解决方案**:
+```bash
+# Ubuntu/Debian
+sudo apt-get install -y libsqlite3-dev
+
+# 验证安装
+dpkg -l | grep libsqlite3-dev
+ls /usr/include/sqlite3.h
+```
+
+---
+
+### Q1.2: 编译时提示 `getaddrinfo`、`usleep` 未声明
+
+**问题描述**:
+```
+warning: implicit declaration of function 'getaddrinfo'
+warning: implicit declaration of function 'usleep'
+```
+
+**原因**: POSIX 函数在严格 C11 模式下需要功能测试宏
+
+**解决方案**:
+在所有源文件顶部添加：
+```c
+#define _GNU_SOURCE
+```
+
+或编译时添加：
+```bash
+gcc -D_GNU_SOURCE ...
+```
+
+---
+
+### Q1.3: 编译时提示 OpenSSL 未找到
+
+**问题描述**:
+```
+OpenSSL not found - building without TLS support
+Install with: sudo apt-get install libssl-dev
+```
+
+**原因**: 未安装 OpenSSL 开发库（可选依赖）
+
+**解决方案**:
+```bash
+# 安装 OpenSSL（可选，用于 HTTPS）
+sudo apt-get install -y libssl-dev
+
+# 或继续编译（不带 TLS 支持）
+make  # 会自动跳过 TLS
+```
+
+---
+
+### Q1.4: 链接时提示 `undefined reference to 'sqlite3_*'`
+
+**问题描述**:
+```
+undefined reference to `sqlite3_open'
+undefined reference to `sqlite3_exec'
+```
+
+**原因**: 未链接 SQLite3 库
+
+**解决方案**:
+确保 Makefile 包含 `-lsqlite3`：
+```makefile
+LDFLAGS = -lpthread -lm -lsqlite3
+```
+
+---
+
+## 2. 运行问题
+
+### Q2.1: 启动时提示 `Failed to start HTTP listener on http://0.0.0.0:5000`
+
+**问题描述**:
+```
+Failed to start HTTP listener on http://0.0.0.0:5000
+```
+
+**原因**: 端口 5000 已被占用
+
+**解决方案**:
+```bash
+# 检查端口占用
+ss -tuln | grep :5000
+
+# 修改 config.ini 使用其他端口
+[server]
+port = 8085
+
+# 或杀死占用进程
+sudo fuser -k 5000/tcp
+```
+
+---
+
+### Q2.2: 程序启动后立即退出
+
+**问题描述**: 程序启动后没有输出，立即退出
+
+**原因**: 可能是配置文件缺失或数据库权限问题
+
+**解决方案**:
+```bash
+# 检查配置文件
+ls -la config.ini
+
+# 检查数据库目录权限
+ls -la mppt_data.db
+
+# 手动创建数据库目录
+mkdir -p /var/lib/mppt_monitor
+chmod 755 /var/lib/mppt_monitor
+```
+
+---
+
+### Q2.3: 历史记录查询不到数据
+
+**问题描述**: 访问 `/api/history` 返回空记录
+
+**原因**:
+1. 设备未在线，无数据存储
+2. 存储间隔未到（默认 10 秒）
+3. 数据库文件损坏
+
+**解决方案**:
+```bash
+# 1. 检查设备连接
+curl http://localhost:5000/api/data
+
+# 2. 等待至少 10 秒后再次查询
+sleep 15
+curl http://localhost:5000/api/history?page=1&page_size=10
+
+# 3. 检查数据库
+sqlite3 mppt_data.db "SELECT COUNT(*) FROM history_data;"
+
+# 4. 重建数据库
+rm mppt_data.db
+# 重启程序自动创建
+```
+
+---
+
+## 3. Modbus 通信问题
+
+### Q3.1: 设备连接失败 `Connection refused`
+
+**问题描述**:
+```
+[MODBUS] Failed to connect to discover.zhonjin.com:40635
+```
+
+**原因**:
+1. 设备未开机或网络不通
+2. 域名解析失败
+3. 防火墙阻止
+
+**解决方案**:
+```bash
+# 1. 检查网络连通性
+ping discover.zhonjin.com
+
+# 2. 检查端口可达性
+telnet discover.zhonjin.com 40635
+
+# 3. 检查 DNS 解析
+nslookup discover.zhonjin.com
+
+# 4. 检查防火墙
+sudo iptables -L -n | grep 40635
+```
+
+---
+
+### Q3.2: Modbus 响应 CRC 校验失败
+
+**问题描述**:
+```
+[MODBUS] CRC mismatch: recv=0xXXXX calc=0xYYYY
+```
+
+**原因**:
+1. TCP 缓冲区残留数据
+2. 网络丢包或数据损坏
+3. 设备响应异常
+
+**解决方案**:
+1. 代码已实现 `drain_socket()` 清空缓冲区
+2. 检查网络稳定性
+3. 增加重试次数（修改 `config.ini`）
+
+---
+
+### Q3.3: 设备地址不匹配 `Address mismatch`
+
+**问题描述**:
+```
+[MODBUS] Address mismatch: expected 1, got 105
+```
+
+**原因**:
+1. TCP 缓冲区残留数据被误解析
+2. 设备实际地址与配置不符
+
+**解决方案**:
+1. 代码已修复：添加 `drain_socket()` 和完整帧读取
+2. 确认设备地址配置正确
+3. 使用 Modbus 调试工具验证
+
+---
+
+### Q3.4: 写入参数失败 `Modbus write failed`
+
+**问题描述**:
+```json
+{"error": "Modbus write failed, CRC mismatch"}
+```
+
+**原因**:
+1. 设备离线
+2. 寄存器地址不可写
+3. 参数值超出范围
+
+**解决方案**:
+```bash
+# 1. 检查设备在线状态
+curl http://localhost:5000/api/data
+
+# 2. 确认可写寄存器
+curl http://localhost:5000/api/settings
+
+# 3. 验证参数范围
+# battery_type: 0-5
+# charge_current_limit: 5-100
+# device_address: 1-247
+```
+
+---
+
+## 4. HTTP API 问题
+
+### Q4.1: POST 请求返回 `Empty request body`
+
+**问题描述**:
+```json
+{"error": "Empty request body"}
+```
+
+**原因**: mongoose 7.x 的 `hm->body` 字段在某些情况下为空
+
+**解决方案**:
+代码已修复：添加 fallback 机制从原始 HTTP 消息提取 body
+```c
+/* Fallback: extract body from raw message */
+if (!body_buf || body_len == 0) {
+    const char *raw = hm->message.ptr;
+    size_t raw_len = hm->message.len;
+    const char *body_start = strstr(raw, "\r\n\r\n");
+    if (body_start) {
+        body_buf = body_start + 4;
+        body_len = raw_len - (body_start - raw) - 4;
+    }
+}
+```
+
+---
+
+### Q4.2: 浏览器 CORS 错误
+
+**问题描述**:
+```
+Access to fetch at 'http://xxx/api/settings' from origin 'http://yyy' 
+has been blocked by CORS policy
+```
+
+**原因**: 响应缺少 CORS 头
+
+**解决方案**:
+代码已修复：所有响应添加 CORS 头
+```c
+mg_http_reply(c, 200, 
+    "Content-Type: application/json\r\n"
+    "Access-Control-Allow-Origin: *\r\n"
+    "Access-Control-Allow-Methods: GET, POST, OPTIONS\r\n"
+    "Access-Control-Allow-Headers: Content-Type\r\n",
+    "%s", json_str);
+```
+
+---
+
+### Q4.3: OPTIONS 预检请求返回 405
+
+**问题描述**: 浏览器发送 OPTIONS 请求被拒绝
+
+**原因**: 未处理 OPTIONS 方法
+
+**解决方案**:
+代码已修复：添加 OPTIONS 处理
+```c
+if (strncmp(method, "OPTIONS", 7) == 0) {
+    mg_http_reply(c, 204, 
+        "Access-Control-Allow-Origin: *\r\n"
+        "Access-Control-Allow-Methods: GET, POST, OPTIONS\r\n"
+        "Access-Control-Allow-Headers: Content-Type\r\n", "");
+    return;
+}
+```
+
+---
+
+## 5. 数据库问题
+
+### Q5.1: 数据库文件损坏
+
+**问题描述**:
+```
+[DB] Failed to open database: mppt_data.db
+```
+
+**原因**: 数据库文件损坏或权限问题
+
+**解决方案**:
+```bash
+# 1. 检查文件权限
+ls -la mppt_data.db
+
+# 2. 备份并重建
+cp mppt_data.db mppt_data.db.bak
+rm mppt_data.db
+# 重启程序自动创建
+
+# 3. 使用 SQLite3 工具修复
+sqlite3 mppt_data.db "PRAGMA integrity_check;"
+```
+
+---
+
+### Q5.2: 数据库查询慢
+
+**问题描述**: 历史数据查询响应慢
+
+**原因**:
+1. 数据量大，无索引
+2. 未使用 WAL 模式
+
+**解决方案**:
+代码已优化：
+- 启用 WAL 模式：`PRAGMA journal_mode=WAL;`
+- 添加时间戳索引：`CREATE INDEX IF NOT EXISTS idx_timestamp ON history_data(recorded_at);`
+- 分页查询限制返回数量
+
+---
+
+## 6. 树莓派部署问题
+
+### Q6.1: 树莓派编译失败
+
+**问题描述**: 在树莓派上编译时出现错误
+
+**原因**: 依赖库未安装
+
+**解决方案**:
+```bash
+# 安装所有依赖
+sudo apt-get update
+sudo apt-get install -y build-essential gcc make
+sudo apt-get install -y libsqlite3-dev
+sudo apt-get install -y libssl-dev  # 可选
+
+# 编译
+cd mppt_monitor
+make clean && make
+```
+
+---
+
+### Q6.2: systemd 服务启动失败
+
+**问题描述**:
+```
+Failed to start mppt-monitor.service
+```
+
+**原因**: 服务配置错误或权限问题
+
+**解决方案**:
+```bash
+# 1. 检查服务状态
+sudo systemctl status mppt-monitor
+
+# 2. 查看日志
+sudo journalctl -u mppt-monitor -n 50
+
+# 3. 检查配置文件
+sudo cat /etc/systemd/system/mppt-monitor.service
+
+# 4. 重新加载配置
+sudo systemctl daemon-reload
+sudo systemctl restart mppt-monitor
+```
+
+---
+
+### Q6.3: 树莓派内存不足
+
+**问题描述**: 运行时内存占用过高
+
+**原因**: 历史数据累积过多
+
+**解决方案**:
+```bash
+# 1. 设置数据保留天数（config.ini）
+[storage]
+retention_days = 30
+
+# 2. 手动清理旧数据
+sqlite3 mppt_data.db "DELETE FROM history_data WHERE recorded_at < datetime('now', '-30 days');"
+
+# 3. 优化数据库
+sqlite3 mppt_data.db "VACUUM;"
+```
+
+---
+
+## 更新记录
+
+| 日期 | 版本 | 更新内容 |
+|------|------|---------|
+| 2026-08-28 | 1.0 | 初始版本，归档所有已知问题 |
+
+---
+
+## 问题提交格式
+
+提交新问题时请按以下格式：
+
+```
+### QX.X: 问题标题
+
+**问题描述**:
+[详细描述问题现象]
+
+**原因**:
+[分析的问题原因]
+
+**解决方案**:
+[具体的解决步骤]
+
+**相关文件**:
+- `src/xxx.c`
+- `config.ini`
+```