타 솔루션 연동 가이드

FlowKat을 외부 포털, 통합 대시보드, ITSM 솔루션과 연결하는 방법을 정의한다. 연동 방식은 표시 목적과 데이터 접근 방식에 따라 선택한다.

1. 개요

1.1 연동 시나리오

시나리오	방식	포트	비고
외부 포털에 FlowKat 화면 임베드	Iframe	6300 (ui-server)	인증 토큰 쿠키 전달 필요
특정 대시보드 링크 공유	공유 URL	6300 (ui-server)	읽기 전용 세션
외부 시스템에서 성능 데이터 조회	REST API	6188 (api-server)	Bearer 토큰 인증
알람 이벤트를 외부 채널로 전송	웹훅 플러그인	N/A (아웃바운드)	Slack/Mattermost/Telegram/Email/LINE

1.2 서비스 포트 구조

연동 시 접근하는 포트는 역할이 다르다.

외부 접근 (방화벽 개방)
  :6300  ui-server (Next.js)  — Iframe / 공유 URL
  (내부 전용)
  :6600  dashboard-server      — Dashboard 메타데이터 API
  :6188  api-server            — 성능 데이터 REST API (3rd-party 연동)

Nginx 리버스 프록시를 사용하는 경우 외부 포트는 80/443이며 내부적으로 6300으로 프록시된다. 자세한 포트 구성은 17.network-ports.md를 참고한다.

2. Iframe 통합 대시보드

2.1 개요

FlowKat 대시보드 화면을 외부 포털이나 통합 운영 콘솔에 삽입한다. ui-server(:6300)의 URL을 <iframe src> 속성에 지정한다.

2.2 URL 구조

https://{flowkat-host}:6300/{locale}/dashboard

경로 세그먼트	설명	예시
`{locale}`	언어 코드	`ko`, `en`
`/dashboard`	대시보드 메인	기본 진입점

특정 대시보드 직접 링크:

https://{flowkat-host}:6300/ko/dashboard?dashboardId={id}

2.3 인증 처리

FlowKat은 NextAuth.js v5 기반의 세션 쿠키 인증을 사용한다. Iframe에서 외부 포털과 FlowKat 간 도메인이 다르면 쿠키가 전달되지 않아 로그인 페이지로 리다이렉트된다.

처리 방법:

동일 도메인 배포: 외부 포털과 FlowKat을 같은 도메인 하위 경로에 배포한다.
- 예: portal.example.com + portal.example.com/flowkat
사전 로그인 후 Iframe 로드: Iframe 로드 전에 /auth/signin을 팝업 창으로 열어 세션을 생성한 뒤 Iframe을 표시한다.
SSO 연동: 동일 IdP(Identity Provider)를 사용하는 경우 SAML/OIDC를 통한 세션 공유 방식은 현재 지원하지 않는다. 커스텀 구현이 필요하다.

2.4 X-Frame-Options 해제

ui-server는 기본적으로 X-Frame-Options 헤더를 설정하지 않는다. 단, Nginx 리버스 프록시에서 헤더를 추가한 경우 해제가 필요하다.

Nginx 설정 예시 — Iframe 허용:

# /etc/nginx/conf.d/flowkat.conf
server {
    listen 443 ssl;
    server_name flowkat.example.com;

    location / {
        proxy_pass http://localhost:6300;

        # X-Frame-Options 제거 (Iframe 허용)
        proxy_hide_header X-Frame-Options;

        # 특정 포털 도메인만 허용하는 경우
        add_header Content-Security-Policy "frame-ancestors 'self' https://portal.example.com";
    }
}

frame-ancestors에 와일드카드 도메인(*)을 사용하면 클릭재킹 공격에 노출된다. 허용 도메인을 명시적으로 지정한다.

2.5 CORS 설정

api-server 직접 호출이 필요한 경우(Iframe 내부에서 XHR), .env의 CORS_ORIGINS를 수정한다.

# volumes/api-server/.env 또는 docker-compose 환경변수
CORS_ORIGINS=https://flowkat.example.com,https://portal.example.com

3. 공유 URL

3.1 개요

특정 대시보드 뷰를 읽기 전용으로 외부에 공유한다. 현재 FlowKat은 별도의 공개 공유 링크 기능을 제공하지 않는다. 따라서 공유는 아래 방식으로 구현한다.

3.2 읽기 전용 역할 계정

공유 URL 접근용 전용 계정을 생성하고 읽기 전용 역할을 부여한다.

설정 경로: 설정 > 역할/권한 > 역할 추가

항목	설정값
역할명	`readonly-viewer`
권한	대시보드 조회만 허용, 설정 변경 권한 없음
계정	공유용 전용 계정 생성

공유 받는 사람은 해당 계정으로 로그인 후 URL에 접근한다.

3.3 URL 파라미터

대시보드 URL에 파라미터를 추가해 초기 상태를 지정할 수 있다.

https://{flowkat-host}:6300/ko/dashboard?dashboardId={id}&timeRange=1h

파라미터	설명	예시
`dashboardId`	특정 대시보드 ID	`dashboard_001`
`timeRange`	시간 범위 (UI 지원 시)	`1h`, `6h`, `24h`

4. REST API 연동

4.1 개요

api-server(:6188)는 Scouter-compatible REST API를 제공한다. 외부 모니터링 시스템이나 BI 도구에서 FlowKat 성능 데이터를 직접 조회할 때 사용한다.

API 스펙은 Swagger UI에서 확인한다:

http://{api-server-host}:6188/swagger-ui.html

OpenAPI 스펙 다운로드:

curl http://{api-server-host}:6188/swagger/api-docs -o flowkat-api.json

api-server(:6188)는 기본적으로 외부에 노출되지 않는다. 직접 접근이 필요한 경우 방화벽 개방과 보안 검토가 필요하다.

4.2 인증 방식

api-server는 Bearer 토큰 방식을 사용한다.

Bearer 토큰 발급

curl -X POST http://{api-server-host}:6188/v1/user/loginGetToken \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "id": "admin",
      "password": "password"
    },
    "serverId": 0
  }'

응답 예시:

{
  "resultCode": 0,
  "message": "success",
  "result": {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

resultCode === 0이면 성공이다. result.token 값을 이후 요청의 Authorization 헤더에 사용한다.

토큰 사용

curl http://{api-server-host}:6188/v1/info/server \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

토큰 갱신

토큰 만료 시 동일한 loginGetToken 엔드포인트로 재발급한다. 토큰 유효 기간은 서버 설정에 따라 다르다.

4.3 주요 API 엔드포인트

엔드포인트	메서드	설명	인증 필요
`GET /v1/info/server`	GET	연결된 Collect Server 목록 조회	불필요
`GET /v1/object`	GET	모니터링 객체(에이전트) 목록 조회	필요
`GET /v1/counter/{counter}/realtime`	GET	실시간 카운터 값 조회	필요
`GET /v1/counter/{counter}/ofType/{objType}`	GET	오브젝트 타입별 카운터 이력 조회	필요
`GET /v1/xlog/realTime`	GET	실시간 XLog 조회	필요
`GET /v1/xlog`	GET	XLog 이력 조회	필요
`GET /v1/alert`	GET	알람 이력 조회	필요
`GET /v1/summary/service`	GET	서비스 요약 통계 조회	필요
`GET /v1/visitor/realTime`	GET	실시간 방문자 수 조회	필요
`GET /v1/activeService/realTime`	GET	실시간 활성 서비스 수 조회	필요

4.4 응답 형식

모든 API 응답은 공통 래퍼 형식을 따른다.

{
  "resultCode": 0,
  "message": "success",
  "result": { ... }
}

필드	타입	설명
`resultCode`	int	`0` = 성공, 그 외 = 오류 코드
`message`	string	결과 메시지
`result`	object	실제 응답 데이터

오류 코드 예시:

코드	설명
`0`	성공
`-1`	일반 오류
`401`	인증 실패
`403`	권한 없음
`503`	요청 타임아웃 (기본 30초)

4.5 API 요청 예시

실시간 활성 서비스 수 조회:

curl "http://{api-server-host}:6188/v1/activeService/realTime?serverId=0" \
  -H "Authorization: Bearer {token}"

특정 오브젝트의 카운터 이력 조회:

curl "http://{api-server-host}:6188/v1/counter/Heap_Used/ofObject/{objHash}?startTime=20260101000000&endTime=20260101235959" \
  -H "Authorization: Bearer {token}"

오브젝트 목록 조회:

curl "http://{api-server-host}:6188/v1/object?serverId=0" \
  -H "Authorization: Bearer {token}"

5. 알림 외부 연동

5.1 개요

FlowKat 알람 이벤트를 외부 채널로 전송한다. flowkat.plugin.* 모듈은 Collect Server에 플러그인으로 로드되어 알람 발생 시 외부 웹훅을 호출한다.

아키텍처:

임계값 초과 이벤트
    → collect-server (AlertRule 평가)
        → 알림 데이터 생성
            → flowkat.plugin.* (플러그인 체인 실행)
                → 외부 채널 웹훅 호출 (Slack / Mattermost / Telegram / Email / LINE)

5.2 지원 알림 채널

채널	모듈	설정 키 네임스페이스
Slack	`flowkat.plugin.slack`	`SLACK_PLUGIN`
Mattermost	`flowkat.plugin.mattermost`	`MATTERMOST_PLUGIN`
Telegram	`flowkat.plugin.telegram`	`TELEGRAM_PLUGIN`
Email	`flowkat.plugin.email`	`EMAIL_PLUGIN`
LINE	`flowkat.plugin.line`	`LINE_PLUGIN`
Synology Chat	`flowkat.plugin.synochat`	`SYNOCHAT_PLUGIN`

5.3 플러그인 설정 방법

플러그인 설정은 FlowKat UI를 통해 KV Store에 저장된다.

설정 경로: 설정 > 알람 > 알람 연동

각 플러그인은 공통적으로 {plugin}_enabled 키로 활성화 여부를 제어한다.

Slack 설정

설정 키	설명	예시
`slack_enabled`	Slack 알림 활성화	`true`
`slack_webhook_url`	Slack Incoming Webhook URL	`https://hooks.slack.com/services/...`
`slack_channel`	전송 채널	`#monitoring-alerts`
`slack_username`	발신 봇 이름	`FlowKat Alert`
`slack_icon_emoji`	봇 아이콘 이모지	`:bell:`

Mattermost 설정

Mattermost 플러그인은 Slack과 동일한 Incoming Webhook 형식을 사용한다.

설정 키	설명
`mattermost_enabled`	Mattermost 알림 활성화
`mattermost_webhook_url`	Mattermost Webhook URL
`mattermost_channel`	전송 채널

Telegram 설정

설정 키	설명
`telegram_enabled`	Telegram 알림 활성화
`telegram_bot_token`	Telegram Bot API 토큰
`telegram_chat_id`	전송 대상 채팅 ID

Email 설정

설정 키	설명
`email_enabled`	이메일 알림 활성화
`email_smtp_host`	SMTP 서버 주소
`email_smtp_port`	SMTP 포트
`email_from`	발신자 이메일 주소
`email_to`	수신자 이메일 주소 (복수 시 콤마 구분)
`email_use_tls`	TLS 사용 여부

5.4 알림 메시지 형식

모든 알림 플러그인은 동일한 알림 데이터 정보를 전송한다.

The following alert [CRITERIA] was caught by FlowKat.

Object Type: {objType}
Object Name: {objName}
Alert Level: {WARN|CRITICAL|FATAL}
Alert Time: {datetime}
Alert Title: {title}
Alert Message: {message}

5.5 플러그인 동작 테스트

알림 설정 후 동작 테스트:

방법 1: UI 테스트 기능 사용

설정 > 알람 > 알람 연동 > [채널] > 테스트 발송 버튼 클릭

방법 2: API 직접 테스트

# collect-server 알람 API를 통해 테스트 알람 발생
curl -X POST http://localhost:6180/api/plugin/test \
  -H "Content-Type: application/json" \
  -d '{"plugin": "SLACK_PLUGIN"}'

6. 주의사항

6.1 보안 고려사항

API 키 / 토큰 관리

Bearer 토큰을 소스코드나 버전 관리 시스템에 커밋하지 않는다.
연동 전용 계정은 최소 권한 원칙을 적용한다 (읽기 전용 권한).
토큰 유효 기간을 최대한 짧게 설정하고 만료 시 재발급 로직을 구현한다.

IP 제한

api-server(:6188)를 외부에 노출하는 경우 Nginx에서 허용 IP를 제한한다.

location /v1/ {
    allow 10.0.0.0/24;   # 허용 IP 대역
    deny all;
    proxy_pass http://localhost:6188;
}

Iframe 보안

frame-ancestors에 명시적인 허용 도메인만 지정한다.
frame-ancestors * 설정은 클릭재킹 취약점을 발생시키므로 사용하지 않는다.

웹훅 URL 보안

Slack/Mattermost 웹훅 URL이 외부에 노출되면 스팸 메시지가 전송될 수 있다.
KV Store에 저장된 웹훅 URL은 설정 > 역할/권한에서 설정 편집 권한을 가진 계정만 조회할 수 있다.

6.2 성능 영향

API 폴링 주기

외부 시스템에서 REST API를 폴링하는 경우 최소 간격을 준수한다.

데이터 종류	권장 최소 폴링 주기	비고
실시간 카운터	5초	이하 주기는 collect-server 부하 유발
XLog 이력	30초	대용량 쿼리 시 더 긴 간격 권장
알람 이력	60초
오브젝트 목록	60초	자주 변하지 않음

동시 연결 수

api-server의 기본 스레드 풀은 제한되어 있다. 외부 연동 시스템이 다수의 동시 요청을 보내면 응답 지연이 발생한다. 연동 시스템 당 최대 5개의 동시 연결을 유지한다.

6.3 타임아웃 처리

api-server의 비동기 응답 타임아웃은 기본 30초다. 외부 연동 클라이언트의 HTTP 타임아웃을 35초 이상으로 설정해 응답을 대기한다.

# curl 예시 — 타임아웃 35초 설정
curl --max-time 35 "http://{api-server-host}:6188/v1/counter/..." \
  -H "Authorization: Bearer {token}"

연동 관련 핵심 파라미터

파라미터	타입	기본값	conf 키	중요도	설명
`NEXTAUTH_URL`	string	`http://localhost:3000`	.env NEXTAUTH_URL	필수	인증 콜백 URL. Iframe/공유 URL 연동 시 외부 도메인 설정 필수
`CORS_ORIGINS`	string	-	.env CORS_ORIGINS	필수	CORS 허용 도메인. Iframe 연동 시 외부 도메인 추가
`x_frame_options`	string	`SAMEORIGIN`	nginx.conf	핵심	X-Frame-Options 헤더. Iframe 연동 시 해제 또는 ALLOW-FROM 설정
`api_auth_token_expire_sec`	int	`3600`	application.yml	핵심	API 토큰 만료 시간(초). REST API 연동 시 갱신 주기 고려
`webhook_url`	string	-	알림 채널 설정	고급	외부 웹훅 URL. 알림 연동 시 플러그인별 설정
`async_response_timeout_ms`	int	`30000`	application.yml	고급	비동기 응답 타임아웃(ms). 외부 클라이언트 타임아웃보다 짧게 설정

1. 개요​

1.1 연동 시나리오​

1.2 서비스 포트 구조​

2. Iframe 통합 대시보드​

2.1 개요​

2.2 URL 구조​

2.3 인증 처리​

2.4 X-Frame-Options 해제​

2.5 CORS 설정​

3. 공유 URL​

3.1 개요​

3.2 읽기 전용 역할 계정​

3.3 URL 파라미터​

4. REST API 연동​

4.1 개요​

4.2 인증 방식​

Bearer 토큰 발급​

토큰 사용​

토큰 갱신​

4.3 주요 API 엔드포인트​

4.4 응답 형식​

4.5 API 요청 예시​

5. 알림 외부 연동​

5.1 개요​

5.2 지원 알림 채널​

5.3 플러그인 설정 방법​

Slack 설정​

Mattermost 설정​

Telegram 설정​

Email 설정​

5.4 알림 메시지 형식​

5.5 플러그인 동작 테스트​

6. 주의사항​

6.1 보안 고려사항​

API 키 / 토큰 관리​

IP 제한​

Iframe 보안​

웹훅 URL 보안​

6.2 성능 영향​

API 폴링 주기​

동시 연결 수​

6.3 타임아웃 처리​

연동 관련 핵심 파라미터​

관련 문서​