🏠 HEIS Tool — 통합 데이터 관리 플랫폼
HEIS Tool은 태양광 발전소 데이터를 수집·변환·검증하는 3개의 핵심 도구와 실시간 서버 모니터로 구성된 통합 플랫폼입니다.
서버(InfluxDB) 데이터를 추출하거나 로컬 파일을 서버에 적재하는 전체 파이프라인을 제공합니다.
- CSV 전처리 및 기간 필터링 (Trim)
- Line Protocol 형식 변환 + Fuzzy 매칭 (Convert)
- 서버 부하 자동 감지 · 속도 조절 (Extract)
- 대용량 파일 일괄 적재 (Load)
ISL(설비 사양서)을 분석하여 HEIS 태그·알람 정보를 자동 생성하고 DB에 반영하는 전문 도구입니다.
- 설비 기준 정보 자동 추출 (Step 2)
- 파라미터·단위·스케일 자동 매핑 (Step 3)
- 알람 등급 자동 분류 (Step 4~5)
- SQL 자동 생성 & 원격 DB 전송 (Step 6)
현장 데이터(SCADA)와 서버 데이터(InfluxDB)를 정밀 비교하여 오차를 시각화 리포트로 제공합니다.
- K8s 로그 분석 · 누락 태그 감지
- 캐시 즉시 갱신 (Cache Refresh)
- SCADA ↔ InfluxDB 오차 비교 (QC Compare)
- HTML 시각화 보고서 자동 생성
🔄 시스템 데이터 흐름 (Data Flow)
현장에서 발생한 데이터가 최종 화면(HEIS 2.0)까지 전달되는 전체 경로입니다.
Agent
Agent
🧱 기술 스택 (Tech Stack)
v1.5.2 기준 — 각 레이어의 핵심 기술만 명시합니다.
| 🖥️ Runtime | Python 3.14+ · PySide6 / Qt6 (데스크톱 UI) · QML (설정 페이지) |
| 🗄️ Database |
MySQL/MariaDB (homdb, 매핑·태그 기준정보) · InfluxDB 1.x (시계열 센서 데이터) SSH → mysql -N -B TSV 스트림 · MappingRepository 세션 캐시 · Excel fallback
|
| 🔒 Security |
keyring (Win Credential Manager / macOS Keychain) → fallback AES-256-GCM + PBKDF2 (320k iter) 패스프레이즈: MAC+hostname SHA-256 머신 파생 · MySQL full-escape (백슬래시·NUL·CR·LF 포함) · InfluxQL tag_filter 화이트리스트 · DEV/PRD 크레덴셜 분리 |
| 📡 SSH |
OpenSSH (System32 > shutil.which, Win/Mac/Linux 자동 탐지) · ProxyJump 3-hop 터널재시도 + 지수 백오프 (최대 2회) · PEM chmod 400 / icacls · config chmod 600 · atexit 자동 정리 |
| ⚙️ 설정·빌드 |
단일 버전 소스: heis_main.py __version__ → pyproject.toml / __init__.py / HEIS_guide.html 자동 동기화OS별 기본 경로 자동 선택 (Win/macOS/XDG) · backfill_config 상수 — IP·User 하드코딩 전면 제거 · Briefcase 빌드 |
| 🗺️ 매핑 |
DB-first: TB_TAG_STDR_INFO ⋈ TB_SCADA_TAG_INFO · tb_scale_info FORML 수식 eval · SP_GET_HEIS_TAG_INFO 저장 프로시저 SSH 불가 시 _mapping.xlsx 자동 fallback · gzip 압축 업로드로 Excel → MySQL 일괄 임포트 |
- 상단 탭을 클릭하여 각 도구의 상세 가이드로 이동하세요.
- 처음 사용자라면 Backfill → QC Tool 순서로 탭을 확인하세요.
- 서버 상태는 우측 사이드바 서버 모니터에서 실시간 확인 가능합니다.
⚙️ 설치 및 초기 설정
단계를 클릭해 상세 내용을 확인하세요. 완료한 항목은 체크리스트에서 클릭하면 진행률이 표시됩니다.
공인 IP · Public Subnet
10.157.xx.xx · App Subnet
10.157.xx.xx · EKS Subnet
10.157.xx.xx · DB Subnet
저장 경로: %USERPROFILE%\Documents\_tunnel\pem\
· 자동 감지 키워드: Bastion / APSUB / EKSSUB / DBSUB
HEIS Tool이 SSH config 파일을 자동 생성 → OpenSSH ProxyJump로 4단계 터널을 투명하게 연결합니다. 키 파일 권한(icacls / chmod 400)도 자동 적용됩니다.
HEIS Tool 실행 시 자동 적용됩니다. 수동 실행이 필요한 경우에만 아래 명령을 사용하세요.
🪟 Windows PowerShell
$pem = "$env:USERPROFILE\Documents\_tunnel\pem"
Get-ChildItem "$pem\*.pem" | ForEach-Object {
icacls $_.FullName /inheritance:r /grant:r "${env:USERNAME}:R"
Write-Host "✅ $($_.Name)"
}
🐧 Linux / macOS
chmod 400 ~/Documents/_tunnel/pem/*.pem
✅ 방법 A — Settings UI (권장)
Windows Credential Manager에 암호화 저장. 파일로 남지 않음.
- 상단 ⚙️ 설정 탭 클릭
- DB Credentials 입력
- Save → keyring 자동 저장
📄 방법 B — db_credentials.json
⚠️ 평문 저장 — OneDrive 동기화 폴더 제외
{
"db_user": "root",
"db_pass": "your_password",
"db_user_prd": "root",
"db_pass_prd": "your_prd_pw"
}
설정 저장 위치: %USERPROFILE%\.hanwha\global_config.json
(비밀번호는 Windows Credential Manager에 별도 보관)
각 탭에서 연결 상태를 확인하세요.
📋 신규 PC 셋업 체크리스트
항목을 클릭하면 체크됩니다. 완료 시 자동으로 저장됩니다.
☁️ Backfill Tool — InfluxDB 데이터 이관
SCADA CSV 전처리부터 InfluxDB 추출·적재·상태 확인까지 처리하는 통합 도구입니다. 사이드바에서 작업 목적에 맞는 메뉴를 선택하세요.
🌍 Global Configuration — 공통 설정
DEV — 개발 서버, 검증용PRD — 운영 서버, 실데이터📋 메뉴별 기능 상세
🛠️ Trim — CSV 전처리
대용량 원본 CSV 파일에서 설정한 날짜 범위만 잘라내어 trim/ 하위 폴더에 저장합니다. 또는 여러 CSV를 하나로 병합합니다.
- 날짜 범위 필터링 — 수백만 행도 빠르게 처리
- UTC ↔ KST 시간대 자동 보정
- Merge — 복수 CSV를 단일 파일로 합치기
- 작업 디렉토리 / 병합 디렉토리 개별 지정
trim/ 폴더 내 정제된 CSV🚀 Convert — Line Protocol 변환
SCADA CSV를 InfluxDB 전용 Line Protocol(.lp) 형식으로 변환합니다. 엑셀 매핑 파일로 컬럼명·스케일을 자동 처리합니다.
- 최대 파일 크기 제한 (MB 단위 분할)
- Host 태그 모드: default / custom / no_host
- 파일명 유효성 검증 (Fuzzy Matching 포함)
- 기간 필터링, 단일 LP 병합 옵션
.lp 파일 (InfluxDB 적재용)📡 Extract — 서버 → 로컬
DEV 또는 PRD InfluxDB에서 데이터를 추출해 로컬 .lp 파일로 저장합니다. 서버 부하를 실시간 감지해 자동 스로틀링합니다.
- 추출 환경 선택 (DEV / PRD)
- 날짜 범위 + 추출 간격 (1h / 1d 등) 설정
- 포함/제외 태그 필터, Measurement 선택
- gzip 압축 여부, 태그 제외 패턴
iowait > 15% 시 자동 일시 중지[THROTTLE] 메시지 확인🚚 Load — 로컬 → 서버 적재
로컬의 .lp 파일을 원격 InfluxDB 서버에 업로드·적재합니다. 다수 파일 일괄 전송과 스마트 스로틀링을 지원합니다.
- 로컬/원격 작업 디렉토리 개별 설정
- 동기화 지연(초) — 파일 간 전송 간격 조절
- 로컬 정리 / 원격 정리 자동 삭제 옵션
- gzip 압축 전송, 자동 스로틀 옵션
📊 Data Status — 서버 데이터 현황 조회
지정한 환경(DEV/PRD)·Plant·기간으로 InfluxDB 서버의 데이터 적재 현황을 조회합니다. 적재 완료 여부 확인 및 누락 구간 검출에 활용합니다.
- 환경 선택: DEV / PRD
- Plant ID (사이트) 입력
- 조회 기간 (Global 날짜 범위 적용)
- Check InfluxDB 버튼으로 즉시 실행
⏱️ Unix Time — 타임스탬프 변환기
Unix 타임스탬프(ms)와 UTC 날짜·시간을 양방향 실시간 변환합니다. LP 파일 디버깅 및 시간 범위 계산에 유용합니다.
- 13자리 Unix ms 입력 → UTC 자동 변환
- UTC 날짜 입력 → Unix ms 자동 변환
- 타임존 오프셋 (±12~14시) 조정
- ↑↓ 화살표 키로 1초 / 1분 단위 이동
🤖 스마트 PRD 노드 자동 선택
PRD 작업 시 툴이 자동으로 Node 140 또는 Node 170 중 활성 쓰기 노드를 선택합니다.
- 날짜 범위와 Plant 필터를 반드시 재확인하세요 — 실 운영 데이터입니다.
- 서버 I/O 대기(iowait)가 15%를 초과하면 작업이 자동으로 일시 중지됩니다.
- 로그에서
[THROTTLE]메시지를 확인하세요. - Load 완료 후 Data Status 탭에서 적재 현황을 반드시 검증하세요.
🏷️ Tag Generator — 설비 태그 관리
ISL 파일을 입력받아 설비 기준 정보·태그·알람을 자동 생성하고 원격 DB에 등록하는 종합 태그 관리 도구입니다. Step 2 → 6 순서대로 진행합니다.
📁 작업 전 파일 준비
파일명이 ISL_ 로 시작해야 합니다.
- 설비 리스트 시트 포함
- 알람(alarm) 시트 포함
- 파일명으로 사이트 자동 감지 (예:
ISL_IA002.xlsx)
파일명이 HEIS_ 로 시작해야 합니다.
- 각 Step 결과가 시트별로 기록됨
- 실행 시 버전이 자동 증가하여 새 파일 생성 (예:
HEIS_v2.xlsx) tag시트 — 영문명·단위 매핑 기준표
🏗️ 설비 기준 정보 생성
ISL 파일의 설비 시트에서 모든 설비를 추출하여 HEIS 파일의 「2. 설비 기준 정보」 시트를 구성합니다.
- 부모설비 ID / 자식설비 ID 계층 자동 추출
- 설비 유형별 정렬 및 그룹 코드 매핑 (HEIS
tag시트 기반) - 한글명·영문명 자동 생성, 대표설비 여부 설정
- 단선도 사용 여부(Y/N) 자동 판별
tag 시트HEIS_v{n+1}.xlsx 새 파일 생성🏷️ 설비 태그 정보 수집
ISL의 SCADA TAG·파라미터·단위·데이터 타입을 수집하여 HEIS 「3. 설비 태그 정보」 시트를 구성합니다.
- ISL에서 SCADA TAG 전체 수집
- 설비 유형별 정렬 후 그룹 구분선 자동 삽입
- 영문명은 HEIS
tag시트에서 매핑하여 덮어쓰기 - 단위(UNIT), 데이터 타입(A/D) 자동 할당
tag 매핑 시트HEIS_v{n+1}.xlsx 새 파일 생성⚖️ 단위 및 스케일 변환
Step 3-1에서 수집된 태그의 단위를 표준화하고 스케일 번호를 자동 적용합니다. 변환된 셀은 노란색 강조로 표시됩니다.
- 단위가
MW인 태그 →kW로 변환 - 스케일 번호 20 자동 부여 (×1,000 변환)
- 음수 보정 태그는 스케일 39 (÷−1,000)
- ⚡ BESS 사이트는 단위 변환 불필요 — 체크 해제 후 실행
- 파라미터명이
TAP인 행 발견 시 - 해당 행 위에
ORGTAP행 자동 삽입 - 스케일 구분을 위한 원본 보존 처리 — 필요 시만 ON
⚖️ 스케일 번호 참고표
| Scale No. | 변환 공식 | 단위 예시 | 적용 상황 |
|---|---|---|---|
| 20 | TAG × 1,000 | MW → kW | 표준 kW 단위 변환 (가장 일반적) |
| 39 | TAG ÷ −1,000 | MW → kW (음수) | 부호 반전이 필요한 특수 보정값 |
| 19 | TAG × 100 | ratio → % | 백분율 계열 (0~1 → 0~100) |
| 42 | TAG × 10 | — | 소수점 1자리 보정 |
| 0 | TAG (변환 없음) | kW, %, A, V … | 이미 표준 단위인 경우 |
🚨 알람 태그 정보 수집
ISL의 alarm 시트를 파싱하여 HEIS 「4. 알람 설비 태그」 시트를 구성합니다. 파라미터 유형·태그 속성·데이터 타입을 자동 분류합니다.
PARMTY02 — 디지털 알람PARMTY04 — 아날로그 알람R — 읽기 전용 (Read)A — 알람 (Alarm)H — 히스토리 (History)A — Analog (아날로그)D — Digital (디지털)➕ 알람 확장
사이트별 설비 수·파라미터 구성을 기반으로 알람 파라미터(ALRM1, ALRM2 …)를 대량으로 자동 생성합니다.
- 사이트 자동 감지 — ISL 파일명에서 사이트 ID 추출 (예:
IA002) site_configs.py에서 해당 사이트의 설비 수·파라미터 매트릭스 로드- ISL alarm 시트에서 영문명·한글명 자동 매핑 후 행 생성
- 수백~수천 행의 알람 파라미터를 수초 내 완성
Step 4-2 화면 우측의 Edit Config 버튼을 클릭하면 site_configs.py 편집 창이 열립니다.
- 사이트별 설비 종류·개수 추가/수정
- 파라미터 확장 패턴 커스터마이징
- 저장 즉시 옵션 목록에 반영됨
🎯 알람 대상 정보 생성
Step 4 에서 생성된 알람 태그를 읽어, 알람명 키워드 분석으로 등급(ALVL)을 자동 분류하여 「5. 알람 설비 대상 정보」 시트를 생성합니다.
🚀 SQL 추출 및 원격 업로드
완성된 HEIS 파일의 SQL 컬럼 데이터를 추출하여 로컬에 저장하고, SSH 터널을 통해 원격 DB 서버에서 직접 실행합니다.
- HEIS 파일의 SQL·SQL2 컬럼에서 쿼리 수집
INSERT→REPLACE자동 변환query.sql/re_query.sql로컬 저장
- SSH Bastion → DB 서버 2단 터널 접속
- gzip 압축 전송 후 리모트에서 압축 해제
- MySQL 자동 실행 후 임시 파일 정리 (Clean 옵션)
db_credentials.json 에 별도 저장됩니다. 소스 코드에 하드코딩하지 마세요.
- 각 Step 실행 전 🚫 Kill Excel 버튼으로 열려 있는 엑셀을 모두 종료하세요 — 파일 잠금으로 인한 쓰기 오류 방지.
- Source 파일명에
isl, Target 파일명에heis가 포함되어야 자동 인식됩니다. - Step 6 Upload 전 반드시 DEV 환경에서 먼저 검증한 뒤 PRD 로 전환하세요.
- 새 사이트 추가 시 Step 4-2 의 Edit Config에서
site_configs.py를 먼저 업데이트하세요.
🔍 QC Tool — 데이터 검증
데이터 정합성 확인, 캐시 갱신, 시스템 진단을 위한 통합 검증 도구입니다.
Tag / Scale 캐시 정보를 즉시 갱신합니다. PV ID나 Tag ID를 입력하면 해당 항목의 캐시를 바로 업데이트합니다.
캐시 갱신K8s 파서 포드의 로그를 분석하여 누락된 태그(Not Registered)나 시스템 오류를 빠르게 찾아냅니다.
수집기(Parser) 데이터와 HEIS DB 데이터의 일치 여부를 실시간 API로 대조합니다. 주기적 자동 로깅도 지원합니다.
실시간 대조현장 원본 데이터(SCADA) ↔ InfluxDB 서버 데이터를 정밀 비교합니다. 오차가 큰 태그를 HTML 시각화 리포트로 생성합니다.
비교 리포트📊 QC Compare — 단계별 흐름
SCADA(현장) 데이터와 InfluxDB(서버) 데이터가 어떻게 비교되어 리포트로 나오는지, 7단계로 설명합니다.
두 파일 모두 Backfill Tool에서 만들어집니다.
매핑 엑셀 기반으로 컬럼명·스케일 자동 처리
scada_사이트명.lp 생성 완료
별도 변환 작업 없이 추출 즉시 .lp 형식으로 저장
influx_사이트명.lp 생성 완료
결과:
태그명 → { 타임스탬프(ms): 값 } 형태의 내부 구조
measurement,pdevice=PV01,cdevice=INV01,parameter=ACPower value=1234.5 1700000000000
변환 후 값이 InfluxDB에 저장된 값과 동일한 단위가 됩니다.
| Scale No. | 변환 공식 | 예시 |
|---|---|---|
| 20 | 값 × 1,000 | 5 → 500 |
| 18 | 값 ÷ 1,000 | 1000 → 1.0 |
| 42 | 값 × 10 | 12.3 → 123 |
| 39 | 값 ÷ −1,000 | 반전 보정 |
Tolerance(허용 오차) 설정 시 정확히 일치하지 않아도 가장 가까운 값을 자동으로 찾습니다.
브라우저에서 바로 열어 누구나 쉽게 결과를 확인할 수 있습니다.
- 분석 결과는 Copy 버튼으로 클립보드에 즉시 복사할 수 있습니다.
- Clear files로 작업 중 생성된 임시 CSV/HTML 파일을 일괄 삭제하세요.
🖥️ 서버 모니터 — 실시간 부하 현황
앱 우측 사이드바에 항상 표시되는 실시간 서버 모니터입니다. DEV · PRD · PRD2 세 환경을 동시에 확인하고 작업 시점을 판단하는 데 활용합니다.
● live — cpu load average (예시 수치)
📋 모니터 표시 항목
서버가 처리 중인 작업량. 숫자가 높을수록 서버가 바쁜 상태입니다.
InfluxDB 프로세스의 CPU 사용률과 메모리 점유량을 개별 표시합니다.
서버 디스크 여유 공간 현황. Load 이후 디스크가 가득 찰 경우 오류 발생 가능.
🛡️ 서버 부하 감소를 위한 자동 보호 장치
대용량 데이터 작업 중 서버에 과도한 부하가 걸리지 않도록 툴이 자동으로 여러 안전장치를 작동합니다. 별도 설정 없이 항상 활성화되어 있습니다.
Extract / Load 작업 중 서버의 I/O 대기(iowait)가 15%를 초과하면 데이터 전송 속도를 자동으로 줄입니다. 서버가 안정되면 자동으로 재개합니다.
[THROTTLE] iowait=XX% — pausing 메시지가 표시됩니다.
PRD 환경 작업 시 Node 140(PRD)과 Node 170(PRD2) 중 현재 쓰기 요청을 처리 중인 활성 노드를 자동으로 감지하여 접속합니다. 덜 바쁜 서버로 자동 분산됩니다.
서버 접속은 SSH 보안 터널을 통해 이루어집니다. 장시간 실행 시 터널이 끊길 수 있어 5분마다 자동으로 갱신합니다. 작업 중 연결이 끊기는 상황을 방지합니다.
네트워크 불안정 등으로 연결이 끊기면 모니터에 [OFFLINE]이 표시되고 5초 → 10초 → 30초 간격으로 자동 재연결을 시도합니다. 자동 복구되므로 별도 조작이 필요 없습니다.
🖱️ 모니터 UI 사용 방법
사이드바 상단의 탭을 클릭하면 InfluxDB 상세 정보 또는 Bastion 서버 정보로 전환됩니다.
각 환경 항목 옆 🔍 버튼을 클릭하면 CPU·메모리·디스크·InfluxDB 버전 등 상세 정보 팝업이 열립니다.
가로 바 그래프의 분홍색 점선이 Load 5 기준선입니다. PRD 서버가 이 수준을 초과하면 작업 속도가 자동으로 줄어들며, 가능하면 작업을 잠시 대기하거나 서버 부하가 낮은 시간대에 진행하세요.
📋 릴리즈 노트
오래된 버전이 위 · 최신 버전이 아래에 표시됩니다. 탭을 열면 자동으로 최신 버전으로 스크롤됩니다.
초기 릴리즈 — 핵심 Backfill Tool 기능 출시 by Juns
모듈식 UI 구현 — 사이드바 레이아웃 및 통합 다크 테마 적용
SSH 멀티플렉싱 지원 추가 (실험적)
CPU Load / 메모리 기반 기본 자동 속도 조절(Auto-Throttle) 구현
hbeat 제거, 모든 항목 누락 없이 추출.
site_registry.json에 영구 보관 및 앱 시작 시 자동 로드.
HEIS_guide.html 탭 구조 전환.
heis_main.py __version__ 단일 소스 → 빌드 시 HTML changelog 자동 갱신.
mysql -N -B TSV 조회·세션 캐시. Excel 파일 의존성 제거, SSH 불가 시 자동 fallback.
tb_scale_info.FORML 수식 우선 eval. 수식 없으면 하드코딩 fallback 유지.