SolTrace

대시보드

사용자별 업로드 카운트

사용자별 삭제 카운트

사용자별 업로드양

사용자별 삭제량

장비 상태 현재 기준

전송/로그인 실패 건수

최근 이상 알림

시각(KST)	장비	지표	심각도	값	평소	내용
-

실패가 몰린 경로

경로	건수	비중	사용자	IP	마지막
-

사용자 (제외 경로 뺀 기준)

사용자ID	건수	경로수
-

CWD 550 은 클라이언트가 경로 존재를 떠보는 정상 동작으로도 많이 발생합니다. 실패 직후 그 경로가 만들어졌으면(CWD→MKD→업로드) 이동 실패가 아니라 존재 확인으로 보고 실패 건수·추이·알림·이 목록에서 모두 제외합니다(로그 조회 목록에서도 감춥니다). 남은 실패가 소수 경로에 몰려 있으면 침입 탐색이 아니라 홈·업로드 경로 설정 오류일 가능성이 큽니다. 원인이 확인된 경로는 제외로 함께 뺄 수 있습니다(제외 경로는 로그 조회에 그대로 남습니다).

로그 조회

기본 조회 3개월, 이상 조회 시 날짜 지정 후 진행 · CWD 실패 중 직후 그 경로가 생성된 건(존재 확인)은 실패가 아니라 목록에서 제외

시간	업로드 장비	사용자	사용자 IP	작업	파일 경로	크기	전송시간	상태
검색 조건을 입력하고 조회하세요.

장비 관리

호스트명	IP	장비상태	데몬상태	CPU / MEM / Disk	버퍼	마지막 연결	그룹
로딩 중...

그룹 관리

페이지당

로딩 중...

API 가이드

인증

모든 요청에 API 키가 필요합니다. 키는 관리자가 설정 > 고객 계정 > API 키에서 발급합니다.

방법 1 — X-API-Key 헤더 (권장)

방법 2 — Authorization 헤더

조회 전용입니다. GET 외의 요청은 403으로 거부됩니다.
권한 범위는 키를 발급한 계정과 같습니다. 고객 계정 키는 해당 고객사의 장비 데이터만 조회됩니다.
키는 발급 시 한 번만 표시됩니다. 분실하면 재발급해야 합니다.
요청 한도는 분당 60회이며, 초과하면 503이 반환됩니다.

엔드포인트

경로	설명

로그 조회 파라미터

이름	예시	설명

오류 응답

코드	의미

사용 예시

구성도

수집 → 저장 → 판정 → 알림·조회 · 인수인계 문서

시스템 구성

장비의 데몬과 WAS 의 쓰기 버퍼가 각각 버퍼를 들고 있어 한쪽이 멈춰도 로그를 버리지 않는다 — WAS 가 내려가면 데몬이 buffer.jsonl 에 쌓아 두고, DB 가 내려가면 쓰기 버퍼가 재시도 큐에 들고 있다가 다시 쓴다.

FTP 장비 N대 · proftpd

xferlog · proftpd.log

전송 · 로그인 · CWD 550

soltrace_daemon.py

10초 폴링 · 200건 배치
60초 하트비트

buffer.jsonl

WAS 장애 시 보관 · 최대 5만 줄
복구되면 자동 재전송

soltrace_bulk.py

과거 로그 일괄 전송 (수동)

WAS 서버 · Rocky Linux 8

Nginx 80/443

TLS · gzip · 레이트리밋
수집 300r/m · 조회 60r/m · 로그인 10r/m

FastAPI + Gunicorn 2 worker

JWT · API 키 · 고객사 데이터 격리

write_buffer

3초 flush · 최대 2000건
실패 배치는 재시도 큐로

service_monitor

5분 주기 — 롤업 · 이상 판정 · 발송
디스크 자동 정리

PostgreSQL 16

ftp_logs

월별 파티션 · 기본 보존 36개월

service_metrics

장비 × 10분 버킷 롤업
최근 2시간은 매 주기 재집계

service_alerts · episodes

이상 버킷과 진행 중인 장애 상태

cron · 자동 정리

월 파티션 생성 · DB 백업(3년)
디스크 임계 초과 시 오래된 월 삭제

알림 · 조회

웹훅 · Slack

감지 / 복구 알림 · 음소거 가능

HMS 메일

같은 내용을 메일로

웹 대시보드 (SPA)

대시보드 · 로그 조회 · CSV/XLSX

외부 시스템

X-API-Key 조회 전용 토큰

이상 감지 · 알림 흐름

판정은 10분 버킷마다 하지만, 발송은 에피소드(장비 × 지표)당 한 번이다. 짧은 흔들림으로 메시지가 쏟아지지 않게 발송 앞단에 지속 조건을 둔다.

1 · 롤업

10분 버킷 집계

전송 실패율 · 전송 속도
로그인 실패율 · CWD 실패

2 · 판정

baseline 이탈

최근 7일 median + k·MAD
절대 하한과 최소 표본으로 오탐 차단

3 · 적재 (화면)

service_alerts

이상 버킷은 모두 남는다
발송 여부와 무관하게 대시보드에 표시

4 · 발송 게이트

보냄

지속 버킷 수 충족(기본 2 = 20분)
심각 등급은 즉시
주의 → 심각 승격 1회

보내지 않음

1버킷 반짝 · 같은 장애의 반복
이상 알림이 없었으면 복구도 없음

5 · 복구

30분(3버킷) 조용

에피소드 종료 → 복구 알림
지속 시간과 이상 건수를 함께 보낸다

지속 버킷 수 · 임계값은 설정 > 알림 설정 > 이상 감지 임계값에서 바꾼다 (저장하면 다음 판정 주기에 반영).

인수인계 문서 운영을 넘겨받는 사람이 먼저 읽는 문서

위 구성도가 무엇이 어떻게 연결돼 있는지라면, 아래는 무엇을 해야 하는지다. 비밀값(비밀번호·토큰·웹훅 URL)은 여기에 적지 않는다 — 있는 위치만 적고 값은 서버의 .env 와 설정 화면에서 확인한다.

1 · 한 장 요약

FTP 장비(proftpd)의 로그를 데몬이 파싱해 WAS 로 보내고, WAS 가 저장·분석해 대시보드와 알림으로 보여준다. 서비스 트래픽 경로가 아니라 관측 경로라 이 시스템이 멈춰도 FTP 전송 자체는 계속된다 — 다만 그동안의 기록과 알림이 비고, 장비 쪽 버퍼(최대 5만 줄)를 넘기면 그만큼은 복구되지 않는다.

하루 한 번 볼 것 — 대시보드 장비 상태(현재 기준)에 주의·심각이 있는지, 최근 이상 알림에 새 항목이 있는지, 설정 > DB 저장소의 디스크 사용률.

2 · 서버 · 경로 (WAS)

코드	`/opt/soltrace` (git 저장소)
설정 · 비밀값	`/opt/soltrace/.env` (DB 접속, SECRET_KEY, 관리자 초기 비밀번호)
서비스	`soltrace-was` · `nginx` · `postgresql-16`
앱 로그	`/var/log/soltrace/error.log` (트레이스백) `access.log` · `selfupdate.log` — 저널이 아니라 파일
DB	PostgreSQL 16 · DB `soltrace`
백업	`/var/backups/soltrace` (매일 03:00, 3년 보관)
장비 데몬	`/opt/soltrace-daemon` · `config.ini` 서비스 `soltrace-daemon` · 로그 `/var/log/soltrace-daemon/daemon.log`

3 · 자주 하는 작업

WAS 업데이트	설정 > 시스템 업데이트 버튼 또는 서버에서 `sudo bash scripts/update_rocky8.sh main`
새 장비 붙이기	장비에 데몬 설치 → 장비 관리에서 확인(Confirm) → 그룹 배정
데몬 업데이트	장비 관리 > 해당 장비 > 원격 업데이트
고객사 계정 · API 키	설정 > 고객 계정 — FTP 계정 매핑을 반드시 등록한다(그룹 + FTP 아이디). 없으면 그 계정은 아무것도 보지 못한다
알림 채널	설정 > 알림 설정 (웹훅 · HMS) · 테스트 발송 버튼
알림이 잦을 때	설정 > 이상 감지 임계값 — 먼저 발송 전 지속 버킷 수를 올리고, 그래도 잦으면 해당 지표의 하한을 올린다
작업 중 알림 끄기	설정 > 알림 설정 > 음소거 — 다시 켜는 것을 잊지 않는다
보존 기간	설정 > DB 저장소 (기본 36개월)

4 · 이럴 때 이렇게

화면이 안 뜨거나 500	`systemctl status soltrace-was` → `/var/log/soltrace/error.log` 마지막 트레이스백. 배포 직후면 `selfupdate.log`
로그가 안 들어옴	장비 관리에서 데몬 상태 확인(하트비트 120초) → 장비에서 `systemctl status soltrace-daemon`, `daemon.log`. WAS 가 살아나면 장비 버퍼가 자동 재전송한다
알림이 쏟아짐	같은 장비·지표면 대개 임계가 그 장비에 안 맞는 것 — 위 '알림이 잦을 때'. 작업 중이면 음소거
디스크 부족	설정 > DB 저장소에서 사용률·파티션 확인. 자동 정리가 켜져 있으면 오래된 월부터 되돌릴 수 없이 지운다 — 필요한 달은 먼저 백업 확인
배포가 오래 걸림	스키마 단계에서 락 대기일 수 있다(`lock_timeout=5s`·3회 재시도). 로그를 보고 기다리되, 반복 실패면 한산한 시간에 다시 시도
CWD 실패 급증	대시보드 > CWD 실패 분석 — 한 경로에 몰려 있으면 침입 탐색이 아니라 홈·업로드 경로 설정 오류다. 원인 확인 후 그 경로를 알림에서 제외

5 · 자동으로 도는 것 (건드리지 않아도 됨)

5분마다	롤업 · 이상 판정 · 알림 발송 · 디스크 점검 (WAS 내부 스레드)
매일 03:00	DB 증분 백업 → `/var/backups/soltrace` (`/etc/cron.d/soltrace-backup`)
매월 1일 00:30	월별 파티션 생성 (`/etc/cron.d/soltrace-partitions`)
인증서	Let's Encrypt 자동 갱신 (설치 시 등록) — 만료 알림이 오면 갱신 동작부터 확인

백업·파티션 cron 이 살아 있는지는 ls /etc/cron.d/soltrace-* 와 /var/log/soltrace/backup.log 로 확인한다.

6 · 넘겨받을 때 확인할 것

☐ WAS 서버 SSH 접근(sudo) · 장비 서버 접근

☐ 관리자 계정 인계 후 비밀번호 변경, 퇴사자 계정 비활성화

☐ 저장소(GitHub) 접근 권한 — 배포가 git pull 기반이다

☐ 알림 채널(웹훅 · HMS) 수신처가 지금 팀인지 · 테스트 발송

☐ 도메인 · 인증서 갱신 주체

☐ 백업 위치와 복구를 실제로 해봤는지

☐ 고객사 계정 · API 키 목록과 용도

☐ 이상 감지 임계값을 손댔다면 왜 그렇게 뒀는지

더 자세한 설치·배포·SQL 은 저장소 README.md, 변경 내역은 왼쪽 변경 이력 탭, API 사용법은 API 가이드 탭.

변경 이력

불러오는 중…

설정

통신사 목록

불러오는 중…

DB 저장소 현황

데이터베이스 전체: -
ftp_logs (전체 파티션): -
데이터 보유 기간: -
디스크 (/): -
default 파티션: -

보존 기간 개월 초과 파티션은 야간 백업 후 삭제됩니다. 기간을 줄여도 즉시 지워지지는 않습니다.

디스크 자동 정리

사용 사용 안 함

% 초과 시 백업 여부와 관계없이 가장 오래된 월 파티션부터 삭제합니다. 되돌릴 수 없습니다.

행 수는 통계 추정치입니다. 월별 파티션은 보존 기간만큼 미리 만들어 두므로, 목록에 있는 과거 월이라도 '데이터 기간'이 비어 있으면 실제 로그는 없습니다. default 파티션에 행이 남아 있으면 해당 월 파티션이 만들어지지 않고 보존기간 정리에서도 제외되므로 scripts/rebalance_default_partition.sql 로 재배치하세요.

월별 파티션

빈 파티션 숨기기

파티션	데이터 기간	행 수(추정)	테이블	인덱스	합계	삭제
불러오는 중…

알림 설정

발송 중

일시 중지

웹훅

웹훅 URL

HMS 메일 게이트웨이

HMS URL

이상 감지 임계값

이탈 배수 (MAD k)

클수록 둔감해져 알림이 줄어듭니다.

발송 전 이상 지속 버킷 수

이상이 이 버킷 수만큼 이어질 때만 알림을 보냅니다(2 = 20분). 한 버킷 반짝했다 스스로 돌아오는 흔들림은 화면에만 남고 감지·복구 메시지가 나가지 않습니다. 1 = 즉시 발송, '심각' 등급은 이 값과 무관하게 바로 나갑니다.

전송 속도 하락 비율

평소 대비 이 비율 이상 떨어지면 알림 (0.6 = 60%↓)

전송 속도 평소 하위 분위

평소 속도의 하위 이 비율(0.05 = 하위 5%)보다 느릴 때만 알립니다. 업로드 사용자마다 회선이 달라 평소에도 느린 구간이 있으면 임계가 자동으로 내려갑니다. 낮출수록 둔감해집니다.

전송 실패율 하한

로그인 실패율 하한

CWD 실패 하한 (건)

전송 지표 최소 건수

로그인 최소 시도수

CWD 최소 건수

전송 속도 최소 대상 건수

아래 기준 크기 이상 전송이 이 건수 미만이면 속도 판정을 건너뜁니다.

CWD 실패 제외 경로

원인이 밝혀진 경로(홈·업로드 경로 설정 오류 등)를 CWD 실패 집계에서만 뺍니다. 로그 조회에는 그대로 남습니다. 최근 2시간 버킷은 다음 판정 주기에 다시 집계됩니다.

전송 속도 판정 기준 크기: -
집계 버킷 / baseline: -

작은 파일은 연결·인증 오버헤드가 전송시간의 대부분이라 실효속도가 낮게 나옵니다. 전송 속도 판정은 기준 크기 이상의 성공한 전송만 사용하므로, 소량 파일을 대량 업로드해도 속도 저하로 오인하지 않습니다. 이 두 값은 .env 에서만 변경합니다(재배포 필요).

관리자 계정 추가

아이디

비밀번호 (8자 이상)

관리자 계정에는 설정 > 계정 보안의 접속 허용 IP가 그대로 적용됩니다. 비밀번호를 5회 연속 틀리면 계정이 15분간 잠깁니다.

관리자 목록

아이디	상태	마지막 로그인	작업
불러오는 중…

마지막 활성 관리자와 로그인 중인 본인 계정은 비활성화·삭제할 수 없습니다.

고객 계정 추가

아이디

비밀번호 (8자 이상)

고객사 (그룹의 customer 와 일치)

허용 IP/CIDR (선택, 줄바꿈 구분)

비고 (담당자·연락처·용도)

FTP 계정 매핑 *

이 계정이 볼 그룹과 FTP 아이디를 등록합니다. 그룹은 여러 개, 아이디도 그룹마다 여러 개 넣을 수 있습니다(쉼표 구분). 등록하지 않으면 로그인해도 아무 데이터가 보이지 않습니다. 고객사를 먼저 입력하면 그 고객사의 그룹만 목록에 나옵니다.

고객 계정 목록

아이디 · 비고	고객사	FTP 계정	허용 IP	등록	상태	작업
불러오는 중…

API 키 (조회 전용)

대상 계정

메모 (선택)

만료일 (선택)

키	계정	메모	마지막 사용	만료	상태	작업
불러오는 중…

키는 조회(GET)만 가능하며 권한 범위는 소유 계정과 같습니다 (고객 계정 키는 해당 고객사 데이터만 보입니다). 사용 예:

curl -H "X-API-Key: slt_..." https://<주소>/api/v1/logs?size=50

대시보드

데몬 상태 상세 -

CWD(디렉토리 이동) 실패 분석

로그 조회

장비 관리

그룹 관리

API 가이드

구성도

변경 이력

설정

알림 설정

접근한 계정 선택

내 계정 —

고객 계정 수정 —

그룹 추가

장비 등록 -

그룹 배정 -