nakla/sbfspot

sbfspot Docker镜像文档

镜像概述

本Docker镜像提供SBFspot开源项目（https://github.com/SBFspot/SBFspot%EF%BC%89%E7%9A%84%E5%AE%B9%E5%99%A8%E5%8C%96%E9%83%A8%E7%BD%B2%EF%BC%8C%E4%B8%BB%E8%A6%81%E5%8A%9F%E8%83%BD%E5%8C%85%E6%8B%AC%EF%BC%9A

• 通过SBFspot从SMA®太阳能/电池逆变器读取发电数据，支持存储到数据库、CSV文件或发送至MQTT Broker。
• 通过SBFspotUploadDaemon（需数据存储在mysql/mariadb/sqlite数据库中）将数据传输至PVoutput.org。

核心功能与特性

• 数据采集：从SMA逆变器读取实时及历史发电数据。
• 数据存储：支持CSV文件、sqlite/mysql/mariadb数据库存储。
• 数据传输：可将数据发送至MQTT Broker。
• 数据上传：通过SBFspotUploadDaemon上传数据至PVoutput.org。
• 灵活配置：通过环境变量和配置文件自定义采集间隔、存储方式等参数。
• 蓝牙支持：针对蓝牙通信的逆变器，支持主机网络模式（--network host）访问蓝牙设备。

前提条件

• 运行SBFspot需提供配置文件SBFspot.cfg并映射至容器，建议备份配置文件（容器会编辑该文件）。
• 运行SBFspotUploadDaemon需提供配置文件SBFspotUpload.cfg并映射至容器。

注意事项

• 若逆变器通过蓝牙通信，容器需以主机网络模式启动（使用--network host选项），此时容器可访问主机所有设备（包括蓝牙设备）。此模式下主机设备对容器完全可见，暂无更佳替代方案。

数据卷配置

容器需映射以下卷，主机卷需对UID 5000或GID 5000有读写权限（配置文件亦同）：

• /etc/sbfspot：配置文件目录，存放SBFspot.cfg和SBFspotUpload.cfg。
• /var/sbfspot：数据目录，用于存储CSV文件或sqlite数据库文件。

环境变量

通用环境变量

ENABLE_SBFSPOT

• 0：禁用SBFspot（不采集逆变器数据）。
• 1：启用SBFspot（采集逆变器发电数据）。

ENABLE_SBFSPOT_UPLOAD

• 0：禁用SBFspotUploadDaemon（不上传数据至PVoutput）。
• 1：启用SBFspotUploadDaemon（上传数据至PVoutput）。

SBFSPOT_INTERVAL

• 取值：秒数（默认600），定义SBFspot轮询逆变器的时间间隔。

TZ

• 取值：时区（如Europe/Berlin），需指定本地时区。时区列表参考***TZ数据库名称（"TZ database name"列）。

DB_STORAGE

• 若需上传数据至PVoutput，必须配置数据库存储；否则为可选。数据库初始化步骤见下文“数据库初始化”。
• sqlite：使用sqlite数据库。
• mysql：使用mysql数据库。
• mariadb：使用mariadb数据库。

CSV_STORAGE

• 0：不存储CSV文件。
• 1：将发电数据存储为CSV文件（可与数据库存储、MQTT发送同时启用）。

MQTT_ENABLE

• 0：不发送数据至MQTT Broker。
• 1：发送发电数据至MQTT Broker（可与数据库存储、CSV存储同时启用）。
• （使用MQTT需在SBFspot.cfg中配置MQTT参数）。

SBFspot选项

以下选项可通过环境变量直接配置：

QUIET

• 1：SBFspot无输出日志。

FINQ 或 FORCE

• 1：强制轮询逆变器（即使在夜间）。

SBFSPOT_ARGS

• 取值：参数列表，若所需选项未提供环境变量，可直接通过此变量传递。示例：SBFSPOT_ARGS="-finq -settime"（多参数以空格分隔）。

可用SBFspot选项列表：

-d#                 设置调试级别：0-5（0=无，默认=2）
-v#                 设置详细输出级别：0-5（0=无，默认=2）
-ad#                设置归档日数据天数：0-300（0=禁用，1=今日（默认）...）
-am#                设置归档月数据月数：0-300（0=禁用，1=当前月（默认）...）
-ae#                设置归档事件月数：0-300（0=禁用，1=当前月（默认）...）
-finq               强制轮询（夜间也轮询逆变器）
-q                  静默模式（无输出）
-nocsv              禁用CSV导出（覆盖配置文件中的CSV_Export设置）
-nosql              禁用SQL导出
-sp0                禁用Spot.csv导出
-installer          以安装员身份登录
-password:xxxx      安装员密码
-loadlive           使用预定义设置手动上传至pvoutput.org
-startdate:YYYYMMDD 设置历史数据检索起始日期
-settime            将逆变器时间与主机时间同步

数据库初始化

INIT_DB

• 0：正常运行（轮询逆变器和/或上传数据至PVoutput）。

• 1：初始化数据库。

• 若DB_STORAGE=sqlite：在/var/sbfspot下创建并配置新数据库文件。

• 若DB_STORAGE=mysql或mariadb：连接SBFspot.cfg中配置的数据库服务器，创建SBFspot数据库和用户（需在SBFspot.cfg中配置数据库连接信息）。

DB_ROOT_USER

• 取值：mysql/mariadb数据库的root用户名（或具有创建数据库和用户权限的用户名）。

DB_ROOT_PW

• 取值：root用户密码。

注意：数据库初始化完成后，必须删除上述三个数据库初始化变量。出于安全考虑，若提供了管理员账户，禁止正常运行。

使用方法与示例

Docker运行示例

初始化mysql数据库

bash
docker run -e "DB_STORAGE=mysql" -e "INIT_DB=1" -e "DB_ROOT_USER=root" -e "DB_ROOT_PW=secret" \
   -v /path/to/your/config/dir/on/host:/etc/sbfspot -v /path/to/your/data/dir/on/host:/var/sbfspot nakla/sbfspot:latest

仅启动SBFspot并存储数据至mariadb

bash
docker run --network host -e "DB_STORAGE=mariadb" -e "ENABLE_SBFSPOT=1" -e "TZ=Europe/Berlin" \
   -v /path/to/your/config/dir/on/host:/etc/sbfspot -v /path/to/your/data/dir/on/host:/var/sbfspot nakla/sbfspot:latest

仅启动SBFspot并存储数据至CSV文件

bash
docker run --network host -e "CSV_STORAGE=1" -e "ENABLE_SBFSPOT=1" -e "TZ=Europe/Berlin" \
   -v /path/to/your/config/dir/on/host:/etc/sbfspot -v /path/to/your/data/dir/on/host:/var/sbfspot nakla/sbfspot:latest

启动SBFspot、存储数据至mysql并上传至PVoutput

bash
docker run --network host -e "DB_STORAGE=mysql" -e "ENABLE_SBFSPOT=1" -e "ENABLE_SBFSPOT_UPLOAD=1" \
   -v /path/to/your/config/dir/on/host:/etc/sbfspot -v /path/to/your/data/dir/on/host:/var/sbfspot nakla/sbfspot:latest

Docker Compose配置

yaml
version: '3'

services:
    sbfspot:
        image: nakla/sbfspot:latest
        network_mode: host
        volumes:
            - ./etc:/etc/sbfspot
            - ./data:/var/sbfspot
        environment:
            TZ: Europe/Berlin
            ENABLE_SBFSPOT: 1
            SBFSPOT_INTERVAL: 600
            ENABLE_SBFSPOT_UPLOAD: 0
            DB_STORAGE: sqlite
            CSV_STORAGE: 1
            MQTT_ENABLE: 1
            QUIET: 0
            SBFSPOT_ARGS: -d0 -v2
            INIT_DB: 0
        restart: always

许可证

署名-非商业性使用-相同方式共享 3.0 未本地化版本 (CC BY-NC-SA 3.0)

简言之，您可以自由：

• 共享 — 复制、分发和传输本作品
• 改编 — 修改、转换或以本作品为基础进行创作

但需遵守以下条件：

• 署名：您必须按照作者或许可人指定的方式对作品进行署名（但不得暗示他们认可您或您对作品的使用）。
• 非商业性使用：您不得将本作品用于商业目的。
• 相同方式共享：如果您修改、转换本作品或以本作品为基础进行创作，您只能以与本许可相同或类似的许可分发衍生作品。

免责声明

SBFspot软件用户确认以“现状”方式接收本软件，且不依赖软件的准确性或功能性用于任何目的。用户进一步确认使用本软件的风险由其自行承担，版权所有者对软件使用或应用引起的任何责任概不负责。

SMA、Speedwire是SMA Solar Technology AG的注册商标。