배포 전 체크리스트

고객 설명 포인트

"고객님, FlowKat 설치는 약 30분~1시간 정도 소요됩니다. 사전에 서버 사양과 네트워크 포트만 확인해주시면, 나머지는 저희가 원격 또는 현장에서 진행해드립니다. 설치 과정에서 고객님 애플리케이션을 중단할 필요는 없고, 에이전트 연결 시에만 WAS 재시작이 필요합니다."

FlowKat 신규 설치 및 업그레이드 시 단계별 확인 항목이다. 설치 전 → 설치 중 → 설치 후 순서로 진행한다.

---

1. 설치 전 — 서버 환경 확인

1-1. 서버 사양 요건

환경	최소 CPU	최소 RAM	최소 디스크	비고
Development	2 core	4 GB	20 GB	테스트 전용
Demo	4 core	4 GB	50 GB	시연용
Production / Aircap	8 core	16 GB	100 GB+	운영 권장

• CPU / RAM 사양 확인 (nproc, free -h)
• 디스크 여유 공간 50 GB 이상 확인 (df -h)
• OS: Linux x86_64 또는 ARM64 확인 (uname -m)

1-2. 필수 소프트웨어

• Docker 20.10 이상 설치 확인 (docker --version)
• Docker Compose v2 이상 설치 확인 (docker compose version)
• curl 설치 확인 (curl --version)
• IP 포워딩 영구 설정 확인 (sysctl net.ipv4.ip_forward → 1이어야 함)
  • 미설정 시: /etc/sysctl.conf에 net.ipv4.ip_forward=1 추가 후 sysctl -p
  • grep -r "ip_forward" /etc/sysctl.d/로 다른 파일이 덮어쓰지 않는지 확인
• 기동 계정 UID 확인 (id -u:id -g) — .env의 POSTGRES_USER_ID와 일치해야 함

1-3. 네트워크 포트 개방

방화벽 인바운드 포트 개방 여부를 확인한다.

포트	프로토콜	필수 여부	용도
6100	TCP	필수	에이전트 데이터 수집 (V3 TCP 전용)
6300	TCP	필수	웹 UI 사용자 접속
8090	TCP	선택	TX-Mining REST API (외부 접근 필요 시)

• 포트 6100 TCP 인바운드 개방 확인
• 포트 6300 TCP 인바운드 개방 확인
• 포트 5433, 6380 외부 노출 여부 결정 (내부 전용 권장)

# 포트 개방 여부 테스트 (외부에서)
nc -zv <서버IP> 6100
nc -zv <서버IP> 6300

1-4. 릴리즈 번들 준비

• 릴리즈 번들 다운로드 및 압축 해제
• 번들 내 images/ 디렉토리에 7개 tar 파일 존재 확인

ls flowkat-release-*/images/
# 확인 목록: collect-server.tar, api-server.tar, dashboard-server.tar,
#            ui-server.tar, mining-server.tar, valkey.tar, postgres-ai.tar

---

2. 설치 중 — 환경 설정 및 기동

2-1. Docker 이미지 로드

cd flowkat-release-<version>
./load-images.sh
# 참고: load-images.sh는 릴리즈 번들에만 포함된다. 소스 리포지토리에는 존재하지 않는다.

• 이미지 로드 완료 (docker images | grep flowkat)
• 7개 이미지 모두 로드됨 확인

2-2. 환경 설정 (대화형)

./flowkat-env-setup.sh

• 환경 선택: development / production / aircap / demo
• 서버 IP 입력 (NEXTAUTH_URL — 브라우저에서 접근하는 실제 URL)
• Production 환경: POSTGRES_PASSWORD 기본값 txmining → 변경 확인

2-3. .env 파일 필수 항목 검토

cat .env | grep -E "NEXTAUTH_URL|DEPLOYMENT_ENV|TX_MINING_ENABLED|SENTRY_ADDRESS|NETWORK_MODE_COLLECT|COLLECT_POSTGRES_HOST"

• DEPLOYMENT_ENV 올바른 환경 값인지 확인
• NEXTAUTH_URL 실제 서버 IP/도메인 포함 여부 확인
• NETWORK_MODE_COLLECT 설정 확인
  • Production/Aircap: host → COLLECT_POSTGRES_HOST=127.0.0.1
  • Development/Demo: bridge → COLLECT_POSTGRES_HOST=172.17.0.1
• Production 환경: POSTGRES_PASSWORD=CHANGE_ME_IN_PRODUCTION 변경 여부 확인

2-4. 볼륨 초기화

./flowkat-volume-manager.sh init

• 볼륨 디렉토리 생성 완료 (ls volumes/)

2-5. 서비스 기동

./start-all.sh
# 또는
docker compose -f docker-compose-all.yaml up -d

• 기동 명령 오류 없이 완료
• 기동 순서 대기: postgres → valkey → collect-server → tx-mining-api → api-server → dashboard-server → ui-server (healthcheck 기반 자동 순서, 완료까지 1~3분 소요) 참고: collect-server는 postgres에만 의존한다(valkey 의존 없음). tx-mining-api는 valkey와 postgres 모두에 의존한다.

---

3. 설치 후 — 동작 확인

현장 체크리스트 — 고객 앞에서 시연

• 브라우저에서 http://<서버IP>:6300 접속하여 로그인 화면 표시
• 초기 관리자 계정으로 로그인 성공
• 대시보드 메인 화면에서 시스템 상태 정상 표시
• 에이전트 연결 후 센트리 화면에서 녹색 아이콘 확인
• 대시보드에서 TPS, 응답시간 그래프에 실시간 데이터 표시
• 트랜잭션 익스플로러에서 XLog 데이터 조회 가능

3-1. 서비스 상태 확인

docker compose ps -a

• 7개 컨테이너 모두 Up 상태 확인
• Restarting 또는 Exit 상태 컨테이너 없음

3-2. UI 접속 확인

curl -I http://<서버IP>:6300

• HTTP 200 응답 확인
• 브라우저에서 http://<서버IP>:6300 접속 후 로그인 화면 표시 확인

3-3. Collect Server 헬스체크

./check-collect-server.sh

• 프로세스 기동 확인
• TCP 6100 포트 리슨 확인

3-4. TX-Mining 헬스체크

./check-tx-mining.sh

• tx-mining-api HTTP 헬스 /api/v1/health 200 응답
• Valkey ping 응답 PONG
• PostgreSQL pg_isready 응답 정상

3-5. 에이전트 연결 확인

에이전트 설치 후 다음을 확인한다.

• 에이전트 conf에 net_collector_ip = 수집 서버 실제 IP 설정
• 에이전트 conf에 obj_name 고유 이름 설정 (복수 인스턴스 시 필수)
• 대시보드 센트리 화면에서 에이전트 녹색 표시 확인

3-6. 데이터 수집 확인

• 대시보드 메인 화면에서 TPS, 응답시간 그래프 데이터 표시 확인
• 트랜잭션 익스플로러(/tx-mining)에서 XLog 데이터 표시 확인 (에이전트 연결 후 5분 내)

---

4. 업그레이드 추가 체크리스트

기존 설치에서 버전 업그레이드 시 추가 확인 항목이다.

4-1. 업그레이드 전

# 볼륨 백업
./flowkat-volume-manager.sh backup

• 볼륨 백업 완료 확인
• 백업 파일 외부 저장소 보관
• 기존 버전 및 신규 버전 확인 (FLOWKAT_VERSION in .env)

4-2. 업그레이드 후

• H2 DB 스키마 변경 여부 확인 (dashboard-server 로그)
• PostgreSQL 파티션 상태 확인 (./check-tx-mining.sh)
• 기존 알람 규칙 유지 확인 (대시보드 설정 > 알람 규칙)
• 기존 사용자 권한 유지 확인 (대시보드 설정 > 사용자 관리)

---

5. 자주 발생하는 설치 오류

고객 질문 예시

Q: "설치 후 화면은 뜨는데 데이터가 안 보여요." A: "에이전트가 정상 연결되었는지 먼저 확인해보겠습니다. 센트리 화면에서 에이전트 상태를 확인하고, 연결이 안 되어 있다면 방화벽 6100 포트와 에이전트 설정 파일을 점검하겠습니다."

Q: "로그인은 되는데 빈 화면이에요." A: ".env 파일의 NEXTAUTH_URL 설정이 실제 접속 주소와 다를 때 발생합니다. 확인 후 수정해드리겠습니다."

증상	원인	해결
ECONNREFUSED dashboard-server:6600	dashboard-server 기동 실패	docker logs flowkat-dashboard-server 확인
ui-server 로그인 후 빈 화면	NEXTAUTH_URL 오설정	.env에서 실제 서버 IP로 수정 후 재기동
에이전트 연결 안 됨	net_collector_ip 오설정 또는 방화벽	conf 파일 및 방화벽 6100 포트 확인
XLog 데이터 없음	COLLECT_POSTGRES_HOST 오설정	네트워크 모드에 맞는 IP 설정
no space left on device	디스크 부족	df -h 확인, 불필요한 이미지/볼륨 정리
postgres/valkey Permission denied	볼륨 UID 불일치. 일반 계정으로 기동 시 발생	.env에서 POSTGRES_USER_ID를 기동 계정의 UID:GID(id -u:id -g)로 설정 후 chown 실행
재부팅 후 컨테이너 간 통신 불가	net.ipv4.ip_forward가 0으로 초기화됨	/etc/sysctl.conf에 net.ipv4.ip_forward=1 영구 등록. sysctl -p로 즉시 적용

---

관련 문서: *30.troubleshooting-flow.md* (진단 플로우), *31.log-collection.md* (로그 수집), *spec/architecture-draft.md* (포트/서비스 상세)