웹 UI 환경 설정
게이트웨이의 설정(엣지 식별 · OPC UA · 데이터 전송 · 실행 모드 · 플랫폼 · AI · HA)을
웹에서 편집하는 화면입니다. 값은 결국 app.properties 로 저장됩니다.
1. 화면 구성 — 탭 7개짜리 폼
게이트웨이 설정을 항목별 폼으로 편집하는 화면입니다. 값마다 무엇을 뜻하는지·기본값이 무엇인지가 입력칸 아래에 적혀 있습니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 맨 위 | 주의 패널 — 재시작 필요 · 필수 키 · 웹이 안 될 때의 대처 |
| ② | 그 아래 | 탭 7개 — 엣지 · OPC UA 서버 · 데이터 전송 · 실행 모드 · 플랫폼 / API · AI 어시스턴트 · HA (이중 엣지) |
| ③ | 우측 상단 | 저장 — 지금 탭만이 아니라 전체 값을 저장합니다 |
| ④ | 본문 | 그룹 헤더 — 한 탭 안이 다시 몇 개 묶음으로 갈립니다 |
| ⑤ | 각 줄 | 라벨 · 입력칸 · 설명과 기본값 |
| ⑥ | 아래로 | 그룹이 이어집니다 (PLC 수집기 · 진단 · REST API 인증 …) |
전에는 app.properties 원문을 CodeMirror 로 통째로 편집하는 화면이었습니다. 지금은
항목별 폼이고, 키를 직접 타이핑하지 않습니다. 파일을 손으로 고쳐야 하는 상황은
웹이 안 뜰 때뿐이고, 그때 고칠 자리는 주의 패널에 적힌
/opt/kopens/plantpulse-edge/conf/app.properties 입니다.
홈 카드 환경 설정 → 클릭, 또는 /ui/system/config.
2. 탭별로 무엇이 있나
엣지
| 그룹 | 항목 |
|---|---|
| 엣지 식별 | edge.id · edge.site_id · 데이터 보존일(edge.ttl) · 24/7 운영(edge.always-on) · 플랫폼 콜백 주소(edge.base_url) |
| 관리자 계정 | edge.admin_login_id · edge.admin_password |
| 초기 등록 (CSV) | edge.init — 부팅 때 /ui/connect/csv 로 올려 둔 OPC·태그 CSV 를 자동 등록 |
| PLC 수집기 | 수집 스레드 수 · 강제 연결 리셋(ms) · 연결 경고(ms) · 주소 스캔 경고(ms) · 주소맵 스캔 경고(ms) |
| 진단 | edge.diagnostic.send.enabled — 플랫폼 진단 서버로 주기 전송 |
| REST API 인증 | edge.rest.api.auth · edge.rest.api.key |
비워 두면 LAN1 → LAN2 → 호스트명 순으로 스스로 정합니다. NAT 뒤에 있거나 관리망을 따로 쓸 때만 명시하세요. 도메인·호스트명도 되지만, 플랫폼은 사설 IP 에만 인증서 검사를 느슨하게 하므로 이름으로 넣으면 자체 서명 인증서에서 TLS 가 막힐 수 있습니다.
OPC UA 서버
엣지가 바깥에 내주는 OPC UA 서버입니다(외부 SCADA 가 붙는 쪽). 도메인 · TCP 포트 · TLS 포트 · 사용자 · 비밀번호 · 익명 접속 허용 · 보안 없는 엔드포인트.
데이터 전송
| 그룹 | 항목 |
|---|---|
| MQTT 발행자 | mqtt.enable · 호스트 · 포트 · 사용자 · 비밀번호 · 토픽 |
| Sparkplug B | sparkplug.enable · 그룹 ID · 엣지 노드 ID · 디바이스 전략 · QoS · bdSeq 경로 · 별칭 사용 · 명령 수신(sparkplug.cmd.enable) |
실행 모드
dev.mode 하나뿐입니다 — EDGE(플랫폼 연결) / STANDALONE(미연결) 둘뿐입니다.
PLATFORM 을 넣으면 기동이 중단됩니다.
플랫폼 / API
플랫폼 서버 접속 — 호스트 · 포트 · SSL · API 키 · 메시징 사용 여부와 브로커 주소.
이 탭에는 연결 테스트 버튼이 있습니다. 화면 설명 그대로 «저장하지 않고 지금 화면에
입력된 값으로 플랫폼 /api/v5 에 접속을 시험합니다». ping 은 인증이 필요 없으므로
API 키까지 함께 검증됩니다 — 틀린 키로 저장한 뒤 재시작하고 나서야 알아채는 일을
막아 줍니다.
AI 어시스턴트
| 그룹 | 항목 |
|---|---|
| AI 인퍼런스 API | ai.enabled · ai.api.base_url · ai.model · ai.api.key |
| 튜닝 | ai.max_tool_steps · ai.timeout_ms · ai.bulk_read_limit |
자세한 것은 AI 엣지 어시스턴트 를 보세요.
HA (이중 엣지)
| 그룹 | 항목 |
|---|---|
| HA 페어 | ha.peer.enabled · 상대 호스트 · 확인 주기(ms) |
| PLC 쓰기 권한 | edge.plc.write_authority |
3. 저장과 반영
저장은 지금 보고 있는 탭만이 아니라 모든 탭의 값을 함께 씁니다
(POST /config/save). 저장은 즉시 되지만 런타임은 재시작 후 반영됩니다.
1. [저장] → 토스트 "재시작 필요"
2. 외부 SCADA / Sparkplug 수신측에 점검 공지 (앱만 재시작해도 30~90초는 끊깁니다)
3. 재시작 (/config/restart 또는 bin/restart.sh)
4. 1–2초 대기 → 화면 새로고침 → /api/v1/edge 로 새 값 확인
앱만 다시 띄우면 되는 항목은 restart-app.sh
(30~90초)로 충분합니다. DB / MQTT 까지 다시 올려야 하는 항목(예: mqtt.enable 토글)은
전체 재시작 입니다.
화면 경고 그대로입니다 — 「필수 키를 비우거나 잘못된 값으로 저장하면 다음 부팅이
실패할 수 있습니다」. 웹이 안 뜨면 SSH 로 들어가
/opt/kopens/plantpulse-edge/conf/app.properties 를 직접 고치고 bin/restart.sh.
컨테이너 모드(2026.05+)에서는 저장 시 /etc/kopens/app.properties(호스트 바인드 마운트)가
갱신되고, 컨테이너 재시작으로 적용됩니다. HiveMQ 브로커의 auth.properties 는
entrypoint 가 매 부팅 때 mqtt.server.* 와 자동 동기화하므로 손댈 필요가 없습니다.
CLI 로도 됩니다.
sudo bash /opt/kopens/install/bin/config.sh --set edge.rest.api.auth true
sudo bash /opt/kopens/install/bin/config.sh --restart
4. 자주 빠지는 함정
| 증상 | 원인 / 해결 |
|---|---|
| 저장은 됐는데 변경이 반영 안 됨 | 재시작 안 함. bin/restart.sh 호출 |
| 저장 후 웹 접속 불가 | 필수 값이 비었거나 형식이 깨짐. SSH 로 수동 복구 |
| 플랫폼에 안 붙음 | 연결 테스트를 먼저 눌러 보세요 — 호스트·포트·SSL·API 키를 한 번에 가려 줍니다 |
| 저장 직후 토스트 안 뜸 | 통신 에러 → 네트워크 / Tomcat 상태 확인 (bin/ps.sh) |
전체 키 목록과 기본값은 app.properties 레퍼런스 에 있습니다.
5. 시스템 태그 (자동 등록 / 90000–90037)
게이트웨이 부팅 시 자기 자신의 시스템 연결(OPC_SYSTEM_<edge_id>)과 38개 시스템 태그(TAG_<edge_id>_90000 ~ _90037)를 OPC-UA 서버에 자동 등록합니다. 외부 SCADA / IIoT 측에서 이 태그를 구독하면 게이트웨이의 상태/식별/네트워크 정보를 그대로 받아갑니다.
5.1 식별 / 네트워크 (90000–90006)
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90000 | HOSTNAME | STRING | 엣지 박스 호스트 이름 |
| 90001 | VERSION | STRING | 엣지 SW 버전 |
| 90002 | NET_1_IP | STRING | 네트워크 포트 1 IP |
| 90003 | NET_2_IP | STRING | 네트워크 포트 2 IP |
| 90004 | NET_WIFI_IP | STRING | Wi-Fi IP |
| 90005 | NET_VPN_IP | STRING | VPN IP |
| 90006 | PING | BOOLEAN | 플랫폼 도달 가능 여부 |
5.2 자원 (90007–90011)
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90007 | CPU_USED_PERCENT | DOUBLE | CPU 사용률 (%) |
| 90008 | MEMORY_USED_PERCENT | DOUBLE | 메모리 사용률 (%) |
| 90009 | DISK_USED_PERCENT | DOUBLE | 디스크 사용률 (%) |
| 90010 | NETWORK_RX_BYTES | LONG | 네트워크 수신 바이트 |
| 90011 | NETWORK_TX_BYTES | LONG | 네트워크 송신 바이트 |
5.3 수집 / 전송 / 시스템 (90012–90027)
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90012 | PLC_CON_CONNECTED_COUNT | LONG | 연결된 연결 수 |
| 90013 | PLC_CON_DISCONNECTED_COUNT | LONG | 끊긴 연결 수 |
| 90014 | PLC_VALUE_READ_SUCCESS_COUNT | LONG | 태그 읽기 성공 건수 |
| 90015 | PLC_VALUE_READ_ERROR_COUNT | LONG | 태그 읽기 실패 건수 |
| 90016 | SENDED_POINT_COUNT | LONG | 플랫폼으로 보낸 포인트 수 |
| 90017 | SENDED_POINT_BYTES | LONG | 플랫폼으로 보낸 바이트 |
| 90018 | MPS | LONG | 초당 처리 포인트 |
| 90019 | TEMPERATURE | INT | 장치 온도 |
| 90020 | OPC_COUNT | INT | 등록된 연결 수 |
| 90021 | TAG_COUNT | INT | 등록된 태그 수 |
| 90022 | SERVER_STARTED_TIMESTAMP | LONG | 엣지 시작 시각 (epoch ms) |
| 90023 | PLC_PING_FAILED_COUNT | INT | ping 에 응답하지 않는 장치 수 |
| 90024 | SYSTEM_DB_TTL | INT | 로컬 데이터 보관 기간 (TTL) |
| 90025 | SYSTEM_TOTAL_DB_SIZE | LONG | 로컬 DB 크기 |
| 90026 | SYSTEM_ERROR_COUNT | LONG | 엣지 오류 건수 |
| 90027 | THREAD_COUNT | LONG | JVM 스레드 수 |
5.4 운영 / 식별 (90028–90037)
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90028 | CONNECTED_OPC_IDS | STRING | 연결된 연결 ID 목록 |
| 90029 | API_KEY | STRING | REST API 키 자리. 값은 늘 마스킹(******)되어 실제 키가 나가지 않습니다 |
| 90030 | REGISTED_OPC_IDS | STRING | 등록된 연결 ID 목록 |
| 90031 | DISCONNECTED_OPC_IDS | STRING | 끊긴 연결 ID 목록 |
| 90032 | COLLECTING_OPC_IDS | STRING | 수집 중인 연결 ID 목록 |
| 90033 | STOPPED_OPC_IDS | STRING | 수집 중지된 연결 ID 목록 |
| 90034 | BUILD_DATE | STRING | 엣지 빌드일 |
| 90035 | DOCKER_CONTAINER_NAMES | STRING | 실행 중인 도커 컨테이너 |
| 90036 | NET_MGNT_IP | STRING | 관리 네트워크 IP |
| 90037 | NET_GSM_IP | STRING | 셀룰러(GSM) IP |
타입은 스키마 타입입니다. CPU · 메모리 · 디스크 사용률과 네트워크 바이트는 INT 로 발행됩니다. 시스템 태그는 10초 주기로
SendTask가 갱신합니다. 외부 SCADA 가 이걸 구독하면 현장에 가지 않고도 엣지 상태를 한눈에 보는 대시보드를 만들 수 있어요.
6. 더 알아보기
- 모든 키의 의미: app.properties 레퍼런스
- 변경 후 재시작: 재시작 (
restart.sh) - 백업 후 변경: 백업 (
backup.sh) - 시스템 로그로 변경 검증: 시스템 로그 보기
- REST API 인증 / 키 발급: REST API 가이드