환경 설정 (/ui/system/config) — app.properties 편집
게이트웨이의 모든 설정 (DB / MQTT / OPC-UA / 사이트 / 모니터링 / 사용자 등) 이 들어있는 app.properties 파일을 웹에서 직접 편집하는 화면입니다.
홈 카드 환경 설정 → 클릭, 또는 /ui/system/config.
저장 시 /etc/kopens/app.properties (host bind mount) 가 갱신되고, 컨테이너 재시작 (/config/restart
버튼 또는 signal file /etc/kopens/host-action.request) 으로 적용됩니다. HiveMQ broker 의
auth.properties 는 container-entrypoint 가 매 부팅 시 mqtt.server.* 와 자동 동기화 — app.properties
만 변경하면 됩니다 (auth.properties 수동 편집 불필요).
CLI 변경:
sudo bash /opt/kopens/install/bin/config.sh --set edge.rest.api.auth true
sudo bash /opt/kopens/install/bin/config.sh --restart
1. 화면 구성
┌─────────────────────────────────────────────────────────────┐
│ 환경 설정 [←] [💾 저장] │
├─────────────────────────────────────────────────────────────┤
│ ⚠ 주의사항 패널 (빨강) │
│ - 환경 설정 파일 수정 시 서버 재시작 필요 │
│ - 필수 키 삭제 금지 │
│ - 웹 접속 불가시 ${PE_HOME}/conf/app.properties 수동 수정 │
├─────────────────────────────────────────────────────────────┤
│ [CodeMirror 에디터 — properties 모드 / xq-dark 테마] │
│ (라인번호, 매칭 괄호, 자동 완성, 활성 라인 하이라이트) │
└─────────────────────────────────────────────────────────────┘
2. 상단 액션
| 버튼 | 동작 |
|---|---|
| ← 뒤로 | /ui/main 으로 이동 |
| 💾 저장 (파란 버튼) | POST /config/save — 현재 에디터 내용을 app.properties 에 저장 |
저장 직후 토스트: "설정이 완료되었습니다! 서버를 재시작하시면, 설정 사항이 반영됩니다."
⚠ 저장 자체는 즉시 이루어지지만 런타임은 재시작 후 반영됩니다.
3. 에디터 — CodeMirror
| 기능 | 동작 |
|---|---|
| 모드 | text/x-properties (KEY=VALUE 형식) |
| 테마 | xq-dark (검은 배경 + 형광 키워드) |
| 라인 번호 | 좌측 표시 |
| 매칭 괄호 | ${...} 등 자동 하이라이트 |
| 활성 라인 | 커서 라인 하이라이트 |
| 자동 줄바꿈 | 긴 라인 자동 wrap |
| 높이 | 2400px (긴 파일 한번에) |
4. app.properties 핵심 키 — 자주 보는 것
상세는 app.properties 설정 참고. 자주 만지는 항목:
| 카테고리 | 키 | 의미 |
|---|---|---|
| 운영 모드 | dev.mode | EDGE / STANDALONE / PLATFORM — 보통 엣지에서는 EDGE |
| 사이트 식별 | edge.id | 게이트웨이 고유 ID (EDGE_*) |
site.id / site.name | 사이트 식별 | |
| 상위 플랫폼 | server.host / server.port / server.username | PlantPulse 플랫폼 API |
server.api_key (구 server.apikey 폴백) | 토큰 기반 인증용 토큰 (V4 setUsernameAndToken) | |
| REST API 인증 (외부 클라이언트) | edge.rest.api.auth | true 면 /api/* 호출 시 인증 강제 |
edge.rest.api.key | 외부에서 보낼 API 키. 운영에서는 EDGE_REST_API_KEY_FILE / EDGE_REST_API_KEY 로 주입하고 X-API-Key 헤더 또는 Authorization: Bearer 로 전송. ?api_key= 쿼리는 401 로 거부 | |
| OPC-UA 서버 | opc.ua.server.host / tcp.port / user / password | 게이트웨이의 내장 OPC-UA 서버 (외부 SCADA 가 접속) |
opc.ua.server.anonymous | Anonymous 허용 (yes/no/true/false/on/1) — 구 오타 키 ananymous 도 폴백 인정 (양쪽 호환) | |
| MQTT | mqtt.enable / mqtt.server.host / port / user / password / topic | HiveMQ (자체 또는 외부) |
| Sparkplug B | sparkplug.enable / sparkplug.cmd.enable / group.id / edge.node.id | Sparkplug 송신 + NCMD/DCMD 명령 수신 |
| DB / TTL | app.db.scheme_ddl | DDL 파일 경로 (default WEB-INF/db/scheme.cql — Cassandra CQL DDL) |
cassandra.host / port / keyspace / edge.ttl | 시계열 저장 정책 (TTL 단위 = 일) | |
| 모니터링 | monitor.ping.targets | 인터넷 ping 대상 |
| 수집 정책 | collector.thread.size / collector.batch.size | 수집기 풀 크기 |
| 보안 | security.session.timeout.minutes | 웹 세션 타임아웃 |
edge.id, cassandra.host, mqtt.server.host 등 필수 키가 빠지거나 형식이 깨지면 다음 부팅 시 startup listener 가 실패 합니다. 웹이 안 뜨면 SSH 로 들어가 /opt/kopens/plantpulse-edge/conf/app.properties 직접 수정 → bin/restart.sh.
5. 저장 후 반영 절차
1. [💾 저장] 클릭 → 토스트 "재시작 필요"
2. 외부 SCADA / Sparkplug 수신측에 점검 공지 (다운타임 ~6초)
3. SSH 또는 시스템 메뉴 → /config/restart 호출
4. 1–2초 대기 → 화면 새로고침 → /api/v1/edge 로 새 값 확인
빠른 재시작은 재시작 (restart.sh) (Tomcat 만, ~6초). DB / MQTT 까지 완전 재시작이 필요한 항목 (예: mqtt.enable toggle) 은 전체 재시작 (stop.sh → start.sh).
6. 자주 빠지는 함정
| 증상 | 원인 / 해결 |
|---|---|
| 저장은 됐는데 변경이 반영 안 됨 | 재시작 안 함. bin/restart.sh 호출 |
| 저장 후 웹 접속 불가 | 필수 키 삭제 / 오타. SSH 로 들어가 수동 복구 |
| 저장 직후 토스트 안 뜸 | 통신 에러 → 네트워크 / Tomcat 상태 확인 (bin/ps.sh) |
| 한글 주석이 깨짐 | 파일이 UTF-8 가 아님. 외부 편집기로 UTF-8 (BOM 없음) 강제 후 저장 |
| 같은 키가 두 번 나타남 | 마지막에 나타난 값이 우선. 첫 줄 삭제 |
7. 시스템 태그 (자동 등록 / 90000–90035)
게이트웨이 부팅 시 자기 자신의 OPC (EDGE_*) 와 36개 시스템 태그 (TAG_<edge_id>_NNNNN) 를 OPC-UA 서버에 자동 등록합니다. 외부 SCADA / IIoT 측에서 이 태그를 구독하면 게이트웨이의 상태/식별/네트워크 정보를 그대로 받아갑니다.
7.1 식별 / 호스트 (90000–90004)
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90000 | HOSTNAME | STRING | OS hostname |
| 90001 | VERSION | STRING | 게이트웨이 SW 버전 |
| 90002 | EDGE_IP | STRING | 게이트웨이 자기 IP |
| 90003 | EDGE_NAME | STRING | 게이트웨이 이름 |
| 90004 | OPERATING_SYSTEM | STRING | OS + 아키텍처 |
7.2 네트워크 (90005–90011)
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90005 | NET_1_IP | STRING | 1번 NIC IP |
| 90006 | NET_2_IP | STRING | 2번 NIC IP |
| 90007 | NET_WIFI_IP | STRING | WIFI IP |
| 90008 | NET_GSM_IP | STRING | GSM 모뎀 IP |
| 90009 | NET_VPN_IP | STRING | VPN (tailscale 등) IP |
| 90010 | NET_MGNT_IP | STRING | 관리 포트 IP |
| 90011 | TEMPERATURE | DOUBLE | CPU 온도 (°C) |
7.3 시스템 / 수집 / 큐 (90012–90027)
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90012 | CPU_USAGE | DOUBLE | CPU % |
| 90013 | MEM_USAGE | DOUBLE | 메모리 % |
| 90014 | DISK_USAGE | DOUBLE | 디스크 % |
| 90015 | OPC_COUNT | INT | OPC 등록 수 |
| 90016 | TAG_COUNT | INT | 태그 등록 수 |
| 90017 | PLC_CON_CONNECTED_COUNT | INT | 연결됨 OPC 수 |
| 90018 | PLC_CON_DISCONNECTED_COUNT | INT | 연결 끊김 OPC 수 |
| 90019 | PLC_SCAN_START_COUNT | INT | 수집 정상 OPC 수 |
| 90020 | PLC_SCAN_NOT_COLLECT_COUNT | INT | 수집 이상 OPC 수 |
| 90021 | PLC_SCAN_STOP_COUNT | INT | 수집 중지 OPC 수 |
| 90022 | QUEUE_SIZE | INT | 메모리 큐 |
| 90023 | QUEUE_DISK_SIZE | INT | 디스크 큐 |
| 90024 | SENDED_POINT_COUNT | LONG | 누적 송신 포인트 |
| 90025 | SENDED_POINT_BYTES | LONG | 누적 송신 바이트 |
| 90026 | MPS | DOUBLE | 초당 메시지 |
| 90027 | SYSTEM_ERROR_COUNT | INT | 오늘 ERROR 건수 |
7.4 운영 / 식별 (90028–90035) — 신규
| 인덱스 | 메트릭 | 타입 | 의미 |
|---|---|---|---|
| 90028 | CONNECTED_OPC_IDS | STRING | 연결된 OPC ID 목록 (콤마 구분) |
| 90029 | API_KEY | STRING | 현재 활성 REST API 키 |
| 90030 | REGISTED_OPC_IDS | STRING | 등록된 모든 OPC ID 목록 |
| 90031 | DISCONNECTED_OPC_IDS | STRING | 연결 끊김 OPC ID 목록 |
| 90032 | COLLECTING_OPC_IDS | STRING | 수집 중 OPC ID 목록 |
| 90033 | STOPPED_OPC_IDS | STRING | 수집 중지 OPC ID 목록 |
| 90034 | BUILD_DATE | STRING | 산출물 빌드일 (yyyy-MM-dd) |
| 90035 | DOCKER_CONTAINER_NAMES | STRING | 살아있는 도커 컨테이너 이름 (콤마) |
모든 시스템 태그는 1초 주기로
SendTask가 갱신합니다. 외부 SCADA 가 이걸 구독하면 현장에 가지 않고도 엣지 상태를 한눈에 보는 대시보드를 만들 수 있어요.
8. 더 알아보기
- 모든 키의 의미: app.properties 설정
- 변경 후 재시작: 재시작 (
restart.sh) - 백업 후 변경: 백업 (
backup.sh) - 시스템 로그로 변경 검증: 시스템 로그 보기
- REST API 인증 / 키 발급: REST API 가이드