> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/admin/modules/data-gateway.md).

# data-gateway (데이터 게이트웨이)

## 역할

외부 시스템 / 콘솔이 시계열 데이터를 안전하게 조회할 수 있는 **HTTP REST + JDBC** 게이트웨이. JDBC / OPC-UA 등 다양한 직접 접근을 차단하고 게이트웨이를 통해서만 데이터에 접근하도록 하는 보안 / 권한 / 감사 레이어 역할을 합니다.

| 항목    | 값                                                          |
| ----- | ---------------------------------------------------------- |
| 모듈명   | `plantpulse-data-gateway`                                  |
| 설치 경로 | `/opt/kopens/plantpulse-platform/plantpulse-data-gateway/` |
| 포트    | **5500** (HTTP), 5501 (TLS)                                |
| 인증    | X-API-Key (`PP_DATA_GATEWAY_API_KEY`)                      |

## 구성

```mermaid
graph LR
  EXT[외부 시스템 / BI / ERP] --> DG[Data Gateway :5500]
  SVR[plantpulse-server] --> DG
  DG --> CASS[(Cassandra)]
  DG --> PG[(PostgreSQL)]
  DG --> METRICS[QPS / Latency<br/>모니터링]
```

## 디렉토리 구조

```
plantpulse-data-gateway/
├── app/                      # WAR
├── bin/start.sh stop.sh log-viewer.sh
├── server/conf/server.xml    # Tomcat
├── template/                 # 설정 템플릿
├── log/ logs/
```

## 주요 API

```bash
# 헬스 체크
curl -fsS http://127.0.0.1:5500/api/health

# 태그 시계열 조회 (인증 필요)
curl -fsS \
  -H "X-API-Key: ${PP_DATA_GATEWAY_API_KEY}" \
  "http://127.0.0.1:5500/api/v1/tags/TAG_001/values?from=2026-05-30T00:00:00Z&to=2026-05-30T23:59:59Z&limit=10000"

# QPS / 지연 메트릭
curl -fsS \
  -H "X-API-Key: ${PP_DATA_GATEWAY_API_KEY}" \
  http://127.0.0.1:5500/api/v1/metrics
```

## 운영 명령

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-startup

./restart-data-gateway.sh
./status.sh                   # 5500 RUNNING 확인
```

## 자주 발생하는 문제

| 증상                  | 원인              | 조치                            |
| ------------------- | --------------- | ----------------------------- |
| 403 Forbidden       | API Key 불일치     | `PP_DATA_GATEWAY_API_KEY` 통일  |
| 응답 느림               | Cassandra 부하    | Valkey 캐시 적중률 확인, 쿼리 시간 범위 단축 |
| 504 Gateway Timeout | 리버스 프록시 timeout | nginx `proxy_read_timeout` 상향 |

## 관련 문서

* [모듈 인덱스](/plantpulse-platform/admin/modules.md)
* [API 사용 매뉴얼](/plantpulse-platform/developer/api-manual.md)