Dashboard Server(포트 6600)는 웹 UI 백엔드로 H2 내장 DB에 메타데이터를 저장하고, API Server(포트 6188)를 통해 Collect Server의 데이터를 조회한다. UI Server(Next.js, 포트 6300)가 프론트엔드 역할을 한다.
1. 개요
API Server
| 항목 | 내용 |
|---|
| Docker 서비스 | api-server |
| 내부 포트 | 6188 (외부 미노출) |
| 기술 스택 | Java 8 (Corretto), REST API |
| 의존 서비스 | collect-server |
| 설정 위치 | volumes/api-server/conf/ |
| JVM 힙 (prod) | -Xmx1g -Xms1g |
Dashboard Server
| 항목 | 내용 |
|---|
| Docker 서비스 | dashboard-server |
| 내부 포트 | 6600 (외부 미노출) |
| 기술 스택 | Java 8, Spring Boot, H2 내장 DB |
| 의존 서비스 | api-server |
| 설정 위치 | volumes/dashboard-server/config/ |
| JVM 힙 (prod) | -Xmx2g -Xms1g |
UI Server
| 항목 | 내용 |
|---|
| Docker 서비스 | ui-server |
| 내부 포트 | 8080, 외부 포트 6300 |
| 기술 스택 | Next.js, PM2 클러스터, Node.js LTS |
| 의존 서비스 | dashboard-server |
| 설정 | .env (NEXTAUTH_URL, PM2_INSTANCES) |
2. 서비스 관계
브라우저 → :6300 (ui-server/Next.js)
→ :6600 (dashboard-server/Spring Boot)
→ :6188 (api-server/REST)
→ collect-server 내장 DB
→ :8090 (tx-mining-api)
- UI Server는 Dashboard Server와 TX-Mining API로 HTTP 프록시한다.
- Dashboard Server는 API Server를 통해 Collect Server 데이터를 조회한다.
- Dashboard Server의 H2 DB는 사용자 설정, 역할/권한, 대시보드 레이아웃 등 메타데이터를 저장한다.
3. 주요 설정
파라미터 테이블 (P0~P1)
| 파라미터 | 타입 | 기본값 | conf 키 | 중요도 | 설명 |
|---|
NEXTAUTH_URL | String | https://flowkat.example.com | .env NEXTAUTH_URL | 필수 | 인증 콜백 URL. 실제 접속 URL과 일치 필수. |
USE_SECURE_COOKIES | boolean | true | .env USE_SECURE_COOKIES | 필수 | HTTPS 환경에서 secure 쿠키 활성화. HTTP 환경에서는 false. |
CORS_ORIGINS | String | https://flowkat.example.com | .env CORS_ORIGINS | 핵심 | CORS 허용 도메인. 콤마 구분 복수 지정 가능. |
FLOWKAT_API_SOCKET_URL | String | (미설정) | .env FLOWKAT_API_SOCKET_URL | 핵심 | WebSocket URL. Nginx 프록시 시 설정. |
PM2_INSTANCES | int | (자동: CPU 코어 수) | .env PM2_INSTANCES | 핵심 | PM2 클러스터 인스턴스 수. |
API Server
API Server는 Collect Server의 데이터를 REST API로 노출하는 중간 계층이다. 별도 conf 파일은 Collect Server와 동일 형식을 사용한다.
| 파라미터 | 위치 | 기본값 | 설명 |
|---|
| Collect Server 주소 | Docker 내부 네트워크 | collect-server:6100 | Docker Compose에서 자동 연결. |
Dashboard Server
Dashboard Server 설정은 JSON 형식이며 volumes/dashboard-server/config/dashboard/ 하위에 위치한다.
| 설정 항목 | 위치 | 설명 |
|---|
| API Server 연결 | Docker Compose 환경변수 | http://api-server:6188 |
| TX-Mining 연결 | Docker Compose 환경변수 | http://tx-mining-api:8090 |
| H2 메타 DB | volumes/dashboard-server/META_H2/ | 역할, 권한, 대시보드 설정 저장 |
4. 설치 절차
Docker Compose 환경에서 자동 배포된다. 상세는 16.docker-compose.md 참조.
기동 확인
# API Server
docker logs -f api-server
# Dashboard Server
docker logs -f dashboard-server
# UI Server
docker logs -f ui-server
# 웹 UI 접속 테스트
curl -I http://localhost:6300
5. 볼륨 매핑
| 서비스 | 호스트 경로 | 컨테이너 경로 | 용도 |
|---|
| api-server | volumes/api-server/conf/ | /app/flowkat/api.server/conf | 설정 |
| api-server | volumes/api-server/logs/ | /app/flowkat/api.server/logs | 로그 |
| dashboard-server | volumes/dashboard-server/config/ | /app/flowkat/dashboard.server/config | JSON 설정 |
| dashboard-server | volumes/dashboard-server/META_H2/ | /app/flowkat/dashboard.server/META_H2 | H2 메타 DB |
| dashboard-server | volumes/dashboard-server/logs/ | /app/flowkat/dashboard.server/logs | 로그 |
| ui-server | volumes/ui-server/uploads/ | /app/flowkat/uploads | 업로드 파일 |
6. 주의사항
| 상황 | 주의 내용 |
|---|
| H2 DB 백업 | META_H2/ 디렉토리를 정기 백업해야 한다. 손상 시 역할/권한/대시보드 설정 유실. |
| 외부 노출 금지 | API Server(6188)와 Dashboard Server(6600)는 내부 전용. 외부 노출 시 보안 위험. |
| NEXTAUTH_URL | 실제 접속 URL과 일치해야 인증이 정상 동작한다. 로드밸런서/Nginx 환경에서 주의. |
| CORS_ORIGINS | 접속 도메인이 포함되어 있지 않으면 브라우저에서 API 호출 차단. |
7. 관련 문서
8. 비공식/고급 서버 옵션
공식 설치 가이드에 없지만 소스 코드(API 서버, 대시보드 서버, flowkat.nextjs)에서 확인되는 숨은 파라미터를 정리한다. 운영 튜닝·트러블슈팅 시 참고한다.
API Server 고급 옵션
설정 파일 위치: volumes/api-server/conf/flowkat.conf 코드 경로: API 서버/src/main/java/flowkat/api/server/framework/configure/StandAlone설정 파일
| 서비스 | 파라미터 | 타입 | 기본값 | 설명 |
|---|
| api-server | net_webapp_tcp_client_pool_size | int | 20 | Collect Server TCP 연결 풀 크기. 동시 요청이 많으면 늘린다. |
| api-server | net_webapp_tcp_client_pool_timeout | int (ms) | 3000 | TCP 연결 풀 획득 대기 타임아웃(ms). |
| api-server | net_webapp_tcp_client_so_timeout | int (ms) | 3000 | Collect Server 소켓 읽기 타임아웃(ms). |
| api-server | net_http_api_auth_ip_enabled | boolean | false | 클라이언트 IP 기반 API 접근 제어 활성화. |
| api-server | net_http_api_auth_ip_header_key | String | "" | 프록시 환경에서 실제 IP를 담은 HTTP 헤더 키 (예: X-Forwarded-For). |
| api-server | net_http_api_allow_ips | String (쉼표 구분) | localhost,127.0.0.1,::1 | IP 접근 제어 활성화 시 허용 IP 목록. 와일드카드(*) 지원. |
| api-server | net_http_api_auth_session_enabled | boolean | false | JSESSIONID 쿠키 기반 세션 인증 활성화. |
| api-server | net_http_api_session_timeout | int (sec) | 86400 (24h) | 세션 타임아웃(초). 기본값 24시간. |
| api-server | net_http_api_auth_bearer_token_enabled | boolean | false | Authorization 헤더의 Bearer 토큰 인증 활성화. |
| api-server | net_http_api_gzip_enabled | boolean | true | API 응답 Gzip 압축 활성화. 대역폭 절감에 유효. |
| api-server | net_http_api_cors_allow_origin | String | * | CORS Access-Control-Allow-Origin 값. 운영 환경에서는 특정 도메인으로 고정 권장. |
| api-server | net_http_api_cors_allow_credentials | String | true | CORS Access-Control-Allow-Credentials 값. *+true 조합 시 origin 헤더로 자동 대체. |
| api-server | net_http_api_swagger_enabled | boolean | false | Swagger UI 활성화. 내부 테스트용으로만 사용. |
| api-server | net_http_api_swagger_host_ip | String | "" | Swagger API 호출용 호스트 IP/도메인. |
| api-server | net_http_port | int | 6188 | HTTP 서비스 포트. JAVA_OPTS에서 net_http_port=N으로 오버라이드 가능. |
| api-server | net_http_extweb_dir | String | ./extweb | 사용자 정의 정적 파일 서빙 루트 디렉토리. |
| api-server | log_keep_days | int | 31 | 로그 보관 일수. |
| api-server | _trace | boolean | false | 내부 디버그 트레이스 출력 활성화. 운영 환경에서 사용 금지. |
| api-server | is_net_collector_scouter | boolean | false | Scouter 오픈소스 Collector 직접 연동 모드. false이면 FlowKat 내부 연동 ID로 처리. |
Dashboard Server 고급 옵션
설정 파일 위치: volumes/dashboard-server/config/ (Spring Boot YAML + 환경변수) 코드 경로: 대시보드 서버/src/main/resources/application.yml
| 서비스 | 파라미터 | 타입 | 기본값 | 설명 |
|---|
| dashboard-server | FLOWKAT_DEFAULT_VIEW_SERVER | String (env) | http://api-server:6188 | API Server 연결 URL. Docker 내부 네트워크 주소 사용. |
| dashboard-server | FLOWKAT_TX_MINING_URL | String (env) | http://mining-server:8086 | TX-Mining API 연결 URL. TX-Mining 통합 활성화 시 설정. |
| dashboard-server | FLOWKAT_TX_MINING_ENABLED | boolean (env) | false | TX-Mining 기능 활성화 여부. |
| dashboard-server | FLOWKAT_TX_SAVE_HOME | String (env) | ./filedump | TX 데이터 임시 저장 디렉토리. Docker 볼륨으로 영속화 권장. |
| dashboard-server | FLOWKAT_LOG_PATH | String (env) | ./logs | 로그 파일 저장 디렉토리. |
| dashboard-server | FLOWKAT_LOG_NAME | String (env) | ./logs/dashboard.log | 로그 파일 경로 및 이름. |
| dashboard-server | SERVER_PORT | int (env) | 6600 | 서비스 포트. |
| dashboard-server | spring.profiles.active | String | local | 활성 Spring 프로필. local/prod/cookie/test/dev 중 선택. |
| dashboard-server | H2 커넥션 풀 (prod 프로필) | int | 30 | maximum-pool-size와 minimum-idle 모두 30. 고부하 시 증가 가능. |
| dashboard-server | H2 커넥션 풀 (local 프로필) | int | 5 | 개발/로컬 환경용 소규모 풀. |
| dashboard-server | flowkat.tx.save.expired_day | int | 7 | TX 저장 파일 만료 일수. |
| dashboard-server | TX-Mining 서버.worker.count | int | 3 | TX-Mining 작업자 스레드 수. |
| dashboard-server | management.endpoints.web.base-path | String | /flowkat | Actuator 엔드포인트 기본 경로. 헬스체크: /flowkat/health. |
| dashboard-server | springdoc.swagger-ui.enabled | boolean | true | Swagger UI 활성화 여부 (소스 기준). 운영 환경에서는 Nginx로 차단 권장. |
| dashboard-server | JAVA_OPTS (Docker env) | String | -Xmx1g -Xms512m | JVM 힙 크기. prod용 권장: -Xmx2g -Xms1g. |
UI Server 고급 옵션
설정 파일 위치: Docker Compose 환경 변수 또는 .env 파일
| 서비스 | 파라미터 | 타입 | 기본값 | 설명 |
|---|
| ui-server | NEXTAUTH_SECRET | String | (필수 설정) | NextAuth 서명/암호화 키. 미설정 시 인증 불가. openssl rand -base64 32로 생성. |
| ui-server | AUTH_TRUST_HOST | boolean | false | 역방향 프록시 환경에서 호스트 헤더를 신뢰할지 여부. Nginx 프록시 구성 시 true로 설정. |
| ui-server | USE_NGINX_PROXY | boolean | false | Nginx 내부 프록시 활성화 여부. true 설정 시 Next.js 앞단에 Nginx가 동작. |
| ui-server | FLOWKAT_API_SERVER | String | http://dashboard-server:6600 | Dashboard Server 백엔드 URL. Next.js API Route가 프록시 대상으로 사용. |
| ui-server | FLOWKAT_API_SOCKET_URL | String | (미설정) | WebSocket/외부 접속 URL. 브라우저가 직접 연결하는 공개 URL. Nginx 프록시 시 외부 주소로 설정. |
| ui-server | TX_MINING_API_SERVER | String | http://flowkat-tx-mining-api:8090 | TX-Mining API 서버 URL. TX-Mining 통합 사용 시 설정. |
| ui-server | UPTIME_KUMA_SOCKET_URL | String | http://localhost:6300 | Uptime Kuma WebSocket 연결 URL. 가용성 모니터링 통합 시 설정. |
| ui-server | UPTIME_KUMA_API_SERVER | String | http://127.0.0.1:3001 | Uptime Kuma API 서버 내부 URL (서버사이드 프록시용). |
| ui-server | UPTIME_KUMA_API_KEY | String | flowkat-uptime-integration-key | Uptime Kuma API 인증 키. 기본값은 테스트용이므로 운영 환경에서 반드시 변경. |
| ui-server | NEXT_PUBLIC_UPTIME_KUMA_URL | String | http://localhost:3001 | 클라이언트 사이드 Uptime Kuma WebSocket URL (NEXT_PUBLIC_ 접두어로 브라우저에 노출). |
| ui-server | NEXT_PUBLIC_UPTIME_KUMA_API_KEY | String | flowkat-uptime-integration-key | 클라이언트 사이드 Uptime Kuma API 키 (브라우저에 노출됨 — 공개 키만 사용). |
| ui-server | NEXT_PUBLIC_FLOWKAT_DEV | boolean | false | 개발 모드 플래그. true로 설정 시 UI 개발자 메뉴 노출. |
| ui-server | NODE_OPTIONS | String | (미설정) | Node.js 런타임 옵션. PM2 멀티 인스턴스 시 --max-old-space-size=2048 권장. |
| ui-server | PM2_INSTANCES | int | (CPU 코어 수) | PM2 클러스터 인스턴스 수. 0=코어 전체, N=고정 수. 메모리와 코어 수를 고려해 설정. |
| ui-server | UPTIME_KUMA_API_URL | String | http://localhost:3001 | 서버사이드 페이지 컴포넌트에서 직접 사용하는 Uptime Kuma URL (SSR 전용). |
Docker Compose 환경변수 오버라이드
.env 파일을 통해 docker-production.yml의 기본값을 오버라이드할 수 있다. 관련 문서: 16.docker-compose.md, 17.network-ports.md
| 서비스 | 변수 | 기본값 | 설명 |
|---|
| 전체 | FLOWKAT_VERSION | latest | 배포할 이미지 태그. 버전 고정 시 5.0.27 등 명시. |
| 전체 | RESTART_POLICY | unless-stopped | Docker 재시작 정책. always/on-failure/no 선택 가능. |
| 전체 | VOLUME_BASE_PATH | ./volumes | 볼륨 마운트 베이스 경로. 외부 스토리지 경로로 변경 가능. |
| collect-server | NETWORK_MODE_COLLECT | host | 수집 서버 네트워크 모드. 라이선스 검증에 host 필요. 개발 환경에서는 bridge 사용 가능. |
| collect-server | COLLECT_JAVA_OPTS | -Xmx2g -Xms2g | Collect Server JVM 힙. |
| api-server | API_JAVA_OPTS | -Xmx1g -Xms1g | API Server JVM 힙. |
| dashboard-server | DASHBOARD_JAVA_OPTS | -Xmx1g -Xms1g | Dashboard Server JVM 힙. |
| ui-server | UI_PORT | 6300 | UI Server 외부 노출 포트. 기존 포트와 충돌 시 변경. |
| ui-server | NEXTAUTH_URL | http://localhost:6300 | NextAuth 콜백 URL. 실제 접속 도메인으로 반드시 변경. |
| ui-server | USE_SECURE_COOKIES | false | HTTPS 환경에서 true로 설정해 secure 쿠키 활성화. |
| ui-server | AUTH_TRUST_HOST | false | Nginx/로드밸런서 뒷단 배포 시 true 설정. |
| ui-server | UPTIME_KUMA_SOCKET_URL | http://localhost:6300 | Uptime Kuma 소켓 연결 URL. |
| ui-server | FLOWKAT_API_SERVER | http://dashboard-server:6600 | Dashboard Server 프록시 대상 URL. |