rcooler/jinko_exporter repository overview

⁠jinko-exporter

jinko-exporter is a Prometheus exporter with pluggable data sources:

• jinko: private browser-backed Jinko detail API
• solarman: Solarman OpenAPI
• modbus: placeholder module until the local protocol/register map is confirmed

The exporter polls upstream on a fixed interval, keeps the latest snapshot in memory, and exposes Prometheus metrics on HTTP.

jinko-exporter can publish read-only Home Assistant MQTT Discovery messages. It does not create command topics and does not control the inverter.

⁠Metrics

The exporter exposes:

• solar_up{source,device_sn}
• solar_last_update_timestamp_seconds{source,device_sn}
• solar_poll_duration_seconds{source}
• solar_request_errors_total{source}
• solar_metric{source,device_sn,group,key,name,unit}

solar_metric is the generic numeric metric stream. For the Jinko detail source it uses values from paramCategoryList.fieldList, typically keyed by storageName.

⁠Alerts

SMTP alerts are optional and disabled by default.

Supported first alert path:

• Jinko bearer token already expired
• Jinko bearer token expiring within a configurable window
• Jinko API 401 / 403 responses
• Solarman token/discovery/currentData request failures
• No successful poll for a configured time window
• Active inverter alarm/fault metrics
• Grid down when all available grid voltages collapse below a threshold
• Optional low battery SOC and high temperature thresholds

Alert config:

• --alerts-enabled / ALERTS_ENABLED
• --alerts-cooldown / ALERTS_COOLDOWN
• --smtp-host / SMTP_HOST
• --smtp-port / SMTP_PORT
• --smtp-username / SMTP_USERNAME
• --smtp-password / SMTP_PASSWORD
• --smtp-from-email / SMTP_FROM_EMAIL
• --smtp-from-name / SMTP_FROM_NAME
• --smtp-to-email / SMTP_TO_EMAILS
• --smtp-use-tls / SMTP_USE_TLS
• --smtp-starttls / SMTP_STARTTLS
• --smtp-timeout / SMTP_TIMEOUT
• --alert-no-successful-poll-window / ALERT_NO_SUCCESSFUL_POLL_WINDOW
• --alert-grid-down-voltage-threshold / ALERT_GRID_DOWN_VOLTAGE_THRESHOLD
• --alert-battery-soc-low-threshold / ALERT_BATTERY_SOC_LOW_THRESHOLD
• --alert-high-temperature-threshold / ALERT_HIGH_TEMPERATURE_THRESHOLD

If SMTP_TO_EMAILS is not set, the exporter falls back to SMTP_FROM_EMAIL as the recipient.

Metric-value alerts:

• inverter alarm/fault metrics: enabled automatically when alerts are enabled
• no successful poll: disabled by default until ALERT_NO_SUCCESSFUL_POLL_WINDOW is set above 0
• grid down: enabled automatically using ALERT_GRID_DOWN_VOLTAGE_THRESHOLD and defaults to 20
• low battery SOC: disabled by default until ALERT_BATTERY_SOC_LOW_THRESHOLD is set above 0
• high temperature: disabled by default until ALERT_HIGH_TEMPERATURE_THRESHOLD is set above 0

⁠Jinko detail source

Required config:

• --jinko-device-id / JINKO_DEVICE_ID
• --jinko-site-id / JINKO_SITE_ID
• --jinko-bearer-token / JINKO_BEARER_TOKEN

Optional config:

• --jinko-cookie / JINKO_COOKIE
• --jinko-request-jitter-max / JINKO_REQUEST_JITTER_MAX
• --jinko-token-alert-window / JINKO_TOKEN_ALERT_WINDOW
• --jinko-language / JINKO_LANGUAGE
• --jinko-need-realtime / JINKO_NEED_REALTIME_DATA

⁠Docker compose

services:
  jinko_exporter:
    build: .
    image: rcooler/jinko-exporter:local
    container_name: jinko_exporter
    restart: unless-stopped
    environment:
      EXPORTER_SOURCE_PRIORITY: "jinko,solarman"
      EXPORTER_LISTEN: ":9876"
      EXPORTER_METRICS_PATH: "/metrics"
      EXPORTER_POLL_INTERVAL: "60s"
      EXPORTER_LOG_LEVEL: "info"
      EXPORTER_METRIC_PREFIX: "solar"

      SOLARMAN_BASE_URL: "https://globalapi.solarmanpv.com"
      SOLARMAN_API_VERSION: "v1.0"
      SOLARMAN_LANGUAGE: "en"
      SOLARMAN_TIMEOUT: "20s"
      SOLARMAN_APP_ID: "<APP_ID>"
      SOLARMAN_APP_SECRET: "<APP_SECRET>"
      SOLARMAN_EMAIL: "[email protected]"

      # Use one of these:
      SOLARMAN_PASSWORD: "<PASSWORD>"
      # SOLARMAN_PASSWORD_SHA256: "<PASSWORD_SHA256>"

      # Recommended to skip discovery if you already know it:
      SOLARMAN_DEVICE_SN: "1234567890"
      # Optional if you want discovery through a specific station:
      # SOLARMAN_STATION_ID: "123456"

      ALERTS_ENABLED: "true"
      ALERTS_COOLDOWN: "6h"
      SMTP_TIMEOUT: "15s"
      SMTP_HOST: "smtp.example.com"
      SMTP_PORT: "587"
      SMTP_USERNAME: "<SMTP_USERNAME>"
      SMTP_PASSWORD: "<SMTP_PASSWORD>"
      SMTP_FROM_EMAIL: "[email protected]"
      SMTP_FROM_NAME: "Jinko Exporter"
      SMTP_TO_EMAILS: "[email protected]"
      SMTP_USE_TLS: "false"
      SMTP_STARTTLS: "true"
      ALERT_NO_SUCCESSFUL_POLL_WINDOW: "10m"
      ALERT_GRID_DOWN_VOLTAGE_THRESHOLD: "20"
      ALERT_BATTERY_SOC_LOW_THRESHOLD: "15"
      ALERT_HIGH_TEMPERATURE_THRESHOLD: "55"

      MQTT_ENABLED: "true"
      MQTT_BROKER: "tcp://homeassistant.local:1883"
      MQTT_USERNAME: "<MQTT_USER>"
      MQTT_PASSWORD: "<MQTT_PASSWORD>"
      MQTT_TOPIC_PREFIX: "jinko-exporter"
      MQTT_DISCOVERY_PREFIX: "homeassistant"
      MQTT_DEVICE_NAME: "Jinko Inverter"
      MQTT_RETAIN: "true"
      MQTT_QOS: "0"
    ports:
      - "9876:9876"

⁠Useful endpoints

• Metrics: http://localhost:9876/metrics
• Health: http://localhost:9876/healthz
• Ready: http://localhost:9876/readyz