Skip to content

Repository files navigation

Z-Pulse

외부 봇(2oolkit-bot) 및 내부 봇 프로세스를 감시·재시작하고 Telegram으로 운영하는 독립 모니터링 봇.


🔎 특징

  • 프로세스 감시 / 자동 재시작TARGET_DIR 하위 봇 디렉토리를 주기적으로 스캔하고 중단된 프로세스를 자동 재시작
  • Telegram 대시보드 — 인라인 버튼 UI로 상태 확인·제어 (재시작 / 종료 / 상세 보기)
  • ReplyKeyboard 퀵 메뉴 — 채팅 하단 고정 버튼 (대시보드 / 터미널 정렬 / 스크린샷 / 봇 업데이트)
  • 경제지표 캘린더 (선택) — ECONOMIC_CALENDAR_ENABLED=true/economic 명령어 활성화
  • 메모리 경고 알림 — 메모리 임계치 초과 시 Telegram 알림 (MEMORY_ALERT_ENABLED)
  • 키워드 알림 — 봇 로그(monitor.log)에서 운영자가 지정한 문구를 감지해 Telegram으로 알림
  • RAPID_ENTRY_GUARD — 봇 로그에서 빠른 반복 진입 징후(비정상적 변동성)를 감시해 강제종료·지연 재시작하는 Z-Pulse 운영 안전장치
  • Z-Flow 연동 레이어 (선택 주입) — Z_FLOW_ENABLED=true 시 sibling z_flow를 자동 감지해 ZFlowBridge를 통해 Z-Flow 슬롯 상태와 명령 표면을 노출

요구사항

  • Python 3.11 이상 (run_all.sh 자동 확인) + pip
  • 가상환경(uv venv)

⚙️ 설치 및 설정

중요: 배포 압축 파일은 애플리케이션 파일이 z_pulse 디렉토리 안에 위치하도록 압축 해제하고, 설치와 실행 명령은 반드시 해당 z_pulse 디렉토리에서 실행합니다.

Z-Pulse는 uv로 Python 가상환경을 생성·관리합니다. 설치 전에 uv 사용 가능 여부를 확인합니다.

uv --version

uv가 없으면 아래 공식 명령으로 설치합니다.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux
cd z_pulse
bash setup_bot.sh

# Windows
cd z_pulse
setup_bot.bat

스크립트가 대화형으로 아래 항목을 설정하고 setting.env를 생성합니다.

섹션 내용
Section 1/4: 필수 설정 텔레그램 봇 토큰·채팅 ID, TARGET_DIR, PROCESS_NAME
Section 2/4: 기능 토글 경제지표 캘린더(업데이트 시간 포함), 메모리 경고
Section 3/4: Z-Flow 연동 설정 (선택) 같은 상위 디렉토리의 sibling z_flow 자동 감지 → Z_FLOW_PATH·Z_FLOW_ENABLED 자동 설정. Enter 시 단독 모드
Section 4/4: Python 환경 가상환경(uv venv) 생성 및 requirements.txt 패키지 설치

참고: Z-Flow 연동을 사용하려면 z_pulsez_flow를 같은 상위 디렉토리에 배치합니다. Section 3에서 활성화하면 setup이 sibling z_flow를 자동 감지해 Z_FLOW_PATH를 기록합니다. sibling z_flow가 없으면 연동은 비활성화됩니다. (기본값: Z-Pulse 단독 모드)

수동 설정은 setting.env.examplesetting.env로 복사한 뒤 편집합니다.


▶️ 실행

# macOS / Linux
cd z_pulse
./run_all.sh
:: Windows
cd z_pulse
run_all.bat

run_all.sh / run_all.bat는 다음을 자동 처리합니다:

  • Python 3.11+ 가상환경 확인·생성 및 의존성 설치
  • setting.env 로드
  • 기존 Z-Pulse 프로세스 정리
  • Z_FLOW_ENABLED=trueZFlowBridge 기반 Z-Flow 연동 활성화
  • Z-Pulse 실행 (__main__.py)

직접 디버깅이 필요한 경우에만 python app.py를 사용합니다.


💬 텔레그램 명령어

코어 명령어 (항상 활성)

명령어 설명
/start 봇 시작 및 환영 메시지
/status 대시보드 열기
/restart <디렉토리> 특정 프로세스 재시작 (DB유지)
/restart_all 모든 프로세스 재시작
/restart_clean <디렉토리> 초기화 후 재시작 (DB삭제)
/restart_running 실행 중인 봇만 재시작
/restart_main 메인 봇(Z-Pulse 자체) 전체 재시작
/kill <디렉토리> 특정 프로세스 종료
/screenshot 화면 스크린샷 전송
/log 봇 로그 보기
/arrange_windows 터미널 창 정렬
/update_bot 2oolkit-bot 바이너리 업데이트
/rename <old> <new> 디렉토리명 변경
/help 전체 명령어 도움말

/update_bot 동작 방식

/update_bot 명령어(= ReplyKeyboard "봇 업데이트")는 감시 대상 프로세스(2oolkit-bot)의 바이너리를 업데이트합니다.

바이너리 배치: 최초 1회 .update 경로를 생성하고, 2oolkit-bot 바이너리를 미리 두어야 합니다.

동작 순서:

  1. .update/<2oolkit-bot*> 파일 존재 확인 (없으면 경고 후 중단)
  2. .update/ 디렉토리에서 바이너리 실행 후 출력 파싱
    • Already up to date. → 최신 버전 안내
    • Updated to ... → 업데이트 확인
  3. 업데이트 확인 시: 전체 봇 정지·정리 후 각 봇 디렉토리로 바이너리 배포

경제지표 활성 시 추가 명령어 (ECONOMIC_CALENDAR_ENABLED=true)

명령어 설명
/economic 경제지표 확인

📊 대시보드 (버튼 UI)

ReplyKeyboard (채팅 하단 고정 버튼)

/start 또는 /help 실행 시 하단에 고정됩니다.

버튼 기능
대시보드 /status 와 동일
터미널 정렬 /arrange_windows 와 동일
스크린샷 /screenshot 와 동일
봇 업데이트 /update_bot 와 동일

메인 대시보드 (/status)

각 봇 디렉토리 행에 상태 버튼 + 액션 버튼 표시:

상태 아이콘 의미
🟢 <dir> 실행 중 — 클릭 시 상세 보기
🔴 <dir> 중단됨 — 클릭 시 상세 보기
⚪ <dir> 무시(ignore) 상태 — 클릭 시 상세 보기

액션 버튼 (상태에 따라 동적 표시):

버튼 조건
종료 실행 중인 봇
시작 중단된 봇

하단 제어 버튼:

버튼 기능
🔥 재시작(전체) 모든 프로세스 재시작 확인
▶️ 재시작(실행중) 실행 중인 프로세스만 재시작
📜 운영봇 로그(전체) Z-Pulse 전체 로그 출력
📄 운영봇 로그(100줄) Z-Pulse 최근 100줄 출력
🔄 새로고침 대시보드 갱신

상세 보기 (봇 디렉토리 선택 시)

Ignore 상태가 아닌 봇 선택 시 아래 버튼이 표시됩니다:

버튼 기능
⚙️ 설정 변경 개별 봇 설정 편집 메뉴
🔔 키워드 알림 설정 봇별 키워드 알림 메뉴
✨ 재시작(DB삭제) JSON/DB 초기화 후 재시작
🔄 재시작(DB유지) DB를 유지하고 재시작
📜 로그(전체) 해당 봇 전체 로그 출력
📄 로그(100줄) 해당 봇 최근 100줄 출력
🔙 돌아가기 메인 대시보드로 복귀

🔔 키워드 알림

키워드 알림은 Z-Pulse가 TARGET_DIR 하위 각 봇 디렉토리의 monitor.log를 감시하다가, 사용자가 봇별로 등록한 문구가 새 로그에 나타나면 Telegram으로 알리는 운영 알림 기능입니다. RAPID_ENTRY_GUARD와 같은 LogKeywordMonitor 안에서 동작하지만 목적이 다릅니다. 키워드 알림은 운영자가 지정한 일반 문구를 보고 알림을 보내는 기능이고, RAPID_ENTRY_GUARD추가 진입 같은 반복 진입 징후를 별도 정책으로 판정해 강제종료와 지연 재시작까지 수행하는 안전장치입니다.

동작 방식:

  1. Z-Pulse 시작 시 기존 monitor.log의 현재 파일 크기를 시작 위치로 저장해 시작 전 로그는 기본 감지 대상에서 제외합니다.
  2. 실시간 감시 대상은 TARGET_DIR/*/monitor.log입니다. macOS에서는 폴링 observer를 사용하며, 주기 점검 경로에서도 새 로그를 읽습니다.
  3. 설정은 봇 디렉토리 이름별로 관리합니다. 기본 설정 파일명은 log_keywords.json이고, 파일이 없으면 {"bots": {}} 구조로 생성합니다.
  4. 키워드 항목은 검증된 기본 구조 기준으로 phrase, is_json_block, cooldown_seconds를 사용합니다. 예: {"bots": {"bot-a": [{"phrase": "ERROR", "is_json_block": false, "cooldown_seconds": 300}]}}
  5. 매칭은 정규식 패턴 해석이 아니라 re.escape(phrase) 기반의 정확한 부분 문자열 검색입니다. 대소문자 정규화가 없으므로 영문 문구는 대소문자를 구분합니다.
  6. 같은 봇과 같은 문구는 cooldown_seconds 동안 중복 알림을 억제합니다. 기본 쿨다운 값은 코드 상수 기준 3600초입니다.
  7. is_json_block=true이면 매칭 위치 주변의 완전한 JSON 블록은 포맷팅하고, 완전하지만 유효하지 않은 JSON은 원문 블록으로 보냅니다. 완전한 블록을 찾지 못하면 매칭된 한 줄 또는 텍스트 알림을 보냅니다. false이면 매칭된 한 줄을 보냅니다.
  8. 알림 메시지는 봇 이름, 키워드, 매칭 라인 또는 JSON 블록을 MarkdownV2 형식으로 보냅니다. Telegram 메시지 길이 제한을 넘으면 안전 길이에서 잘라 보냅니다.
  9. kill_on_match=true 키워드는 감지 시 알림 후 해당 봇 프로세스를 종료하는 확장 필드입니다. Telegram 키워드 설정 UI 입력 흐름에는 포함되지 않으므로 수동 JSON 편집 시에만 사용합니다.
  10. 외부에서 log_keywords.json이 변경되면 mtime 증가를 감지해 재로드하고, Telegram UI에서 추가·수정·삭제한 내용은 원자적 JSON 저장 헬퍼로 저장합니다.

키워드 설정 방법:

경로 설정 표면
Telegram 대시보드 /status → 봇 상세 보기 → 🔔 키워드 알림 설정
상세 보기 콜백 keyword_menu:{target}
메뉴 내부 콜백 kw_add_start, kw_edit_start, kw_delete_start, kw_sel_{idx}, kw_json_yes, kw_json_no, kw_confirm, kw_back
입력 흐름 문구 입력 → JSON 블록 여부 선택 → cooldown_seconds 초 입력 → 저장

운영자 설정 표면은 /status의 봇 상세 보기에서 여는 🔔 키워드 알림 설정 메뉴이며, 상세 보기 콜백은 keyword_menu:{target}입니다.

경계와 주의사항:

  • 이 기능은 Z-Pulse 운영 알림 기능이며 Z-Flow 전략 기능이나 전략 설정이 아닙니다.
  • 감시 소스는 봇별 monitor.log이므로, Z-Flow에서 나온 로그 문구도 해당 파일에 기록된 뒤에야 감지됩니다.
  • 정규식, 대소문자 무시, 다중 조건식은 기본 키워드 UI/매칭 경로에서 지원하지 않습니다.
  • 시작 시점 이전 로그는 기본적으로 무시되므로, 재시작 직전 이미 기록된 문구는 새 알림으로 재전송되지 않을 수 있습니다.
  • JSON 블록 추출은 매칭 위치 주변의 중괄호를 기준으로 하므로, 로그가 잘린 블록이거나 중괄호 구조가 깨져 있으면 원문 일부로 전송될 수 있습니다.
  • 쿨다운은 같은 봇·같은 문구 기준으로 적용되므로, 짧게 설정하면 알림량이 늘고 길게 설정하면 반복 장애 신호가 늦게 보일 수 있습니다.

🛡️ RAPID_ENTRY_GUARD

RAPID_ENTRY_GUARD는 Z-Pulse가 소유한 운영 감시/안전장치입니다. TARGET_DIR 하위 target/external bot의 monitor.log에서 발생한 문구를 감시하며, Z-Flow 로그 문구도 신호 소스가 될 수 있습니다. 정책 판단과 프로세스 제어는 Z-Pulse의 LogKeywordMonitorprocess_controller가 담당하므로 Z-Flow 전략 기능이나 전략 설정이 아닙니다.

동작 방식:

  1. Z-Pulse 시작 시 monitor.log 실시간 모니터가 시작되며, 시작 이전 로그는 감지 대상에서 제외합니다.
  2. TARGET_DIR 하위 봇 디렉토리마다 watchdog observer를 등록합니다. macOS에서는 polling observer를 사용하고, guard가 켜져 있으면 별도 라인 폴링 스레드도 함께 시작합니다.
  3. 로그 문구 감지는 기본적으로 RAPID_ENTRY_GUARD_PHRASE 값을 사용합니다. 기본 문구는 추가 진입입니다.
  4. 같은 봇에서 RAPID_ENTRY_GUARD_SEQUENCE_WINDOW_SEC 안에 RAPID_ENTRY_GUARD_SEQUENCE_COUNT회 이상 감지되면 폭주로 판단합니다. 현재 트리거 판정은 횟수와 시퀀스 윈도우만 사용하며, RAPID_ENTRY_GUARD_MIN_INTERVAL_SECRAPID_ENTRY_GUARD_MAX_INTERVAL_SEC는 호환성 유지와 향후 정책 확장을 위해 로드되는 예약 파라미터입니다.
  5. RAPID_ENTRY_GUARD_FORCE_CONSECUTIVE=true이면 새 로그 청크 안에서 RAPID_ENTRY_GUARD_FORCE_PHRASES에 포함된 대표 배너형 문구 라인이 기준 횟수 이상 보일 때 즉시 연속 감지로 등록합니다.
  6. 로그 타임스탬프 기준 감지 지연이 RAPID_ENTRY_GUARD_LAG_ALERT_THRESHOLD_SEC 이상이면, lag alert가 켜진 경우 cooldown 범위 안에서 중복을 억제하고 Telegram으로 지연 경보를 보냅니다.
  7. 트리거되면 process_controller.kill_specific_process()로 해당 봇 프로세스를 먼저 종료하고 Telegram에 결과를 알립니다.
  8. RAPID_ENTRY_GUARD_RESTART_DELAY_SEC 동안 재시작 윈도우를 유지해 추가 감지를 무시한 뒤, process_controller.start_bot_process()로 지연 재기동을 예약합니다.

주요 설정:

기본값 설명
RAPID_ENTRY_GUARD_ENABLED true guard 활성화. 끄려면 false로 설정
RAPID_ENTRY_GUARD_PHRASE 추가 진입 기본 감지 문구
RAPID_ENTRY_GUARD_SEQUENCE_COUNT 3 트리거에 필요한 감지 횟수
RAPID_ENTRY_GUARD_SEQUENCE_WINDOW_SEC 3.3 기준 횟수를 판단할 시간 윈도우
RAPID_ENTRY_GUARD_MIN_INTERVAL_SEC 0.7 호환성/예약용 감지 간격 하한값. 현재 트리거 조건에는 미사용
RAPID_ENTRY_GUARD_MAX_INTERVAL_SEC 1.4 호환성/예약용 감지 간격 상한값. 현재 트리거 조건에는 미사용
RAPID_ENTRY_GUARD_RESTART_DELAY_SEC 180 강제종료 후 자동 재기동까지 대기할 초
RAPID_ENTRY_GUARD_POLL_INTERVAL_SEC 0.2 라인 폴링 주기. 0 이하 값은 기본값으로 대체
RAPID_ENTRY_GUARD_FORCE_CONSECUTIVE false 새 로그 청크의 강제 연속 감지 모드
RAPID_ENTRY_GUARD_FORCE_PHRASES 최초 진입,추가 진입 강제 연속 감지에 사용할 쉼표 구분 문구 목록
RAPID_ENTRY_GUARD_LAG_ALERT_ENABLED false 감지 지연 경보 활성화
RAPID_ENTRY_GUARD_LAG_ALERT_THRESHOLD_SEC 5 지연 경보 기준 초
RAPID_ENTRY_GUARD_LAG_ALERT_COOLDOWN_SEC 60 같은 봇 지연 경보 중복 억제 초
RAPID_ENTRY_GUARD_DEBUG true hit/ignore/no-trigger 디버그 로그 출력
KEYWORD_MONITOR_OBSERVER_TIMEOUT_SEC macOS 1.0, 기타 0.2 watchdog/polling observer timeout

setup_bot.sh, setup_bot.bat, setting.env.example은 기본 예시로 RAPID_ENTRY_GUARD_FORCE_PHRASES="최초 진입,추가 진입"을 기록합니다. 다른 키를 조정하려면 setting.env에 직접 추가합니다. 트리거 문구는 target/external bot 로그에서 파생되며 Z-Flow 로그 문구도 신호 소스가 될 수 있지만, 감지 정책·알림·강제종료·지연 재시작은 Z-Pulse 운영 계층에서만 수행합니다.


🔧 설정 (setting.env 주요 키)

기본값 반영 시점 설명
TELEGRAM_BOT_TOKEN 재시작 텔레그램 봇 토큰 (@BotFather에서 생성)
TELEGRAM_CHAT_ID 재시작 허용할 텔레그램 채팅 ID
TARGET_DIR ~/Documents/toolkit 재시작 모니터링 대상 봇 디렉토리 상위 경로
PROCESS_NAME 2oolkit-bot-macos-arm64 재시작 감시할 프로세스 이름
ECONOMIC_CALENDAR_ENABLED true 재시작 경제지표 캘린더 활성화
ECONOMIC_UPDATE_HOUR 06 재시작 경제지표 일일 업데이트 시간 (0-23)
Z_FLOW_PATH 재시작 sibling z_flow 루트 경로 (setup_bot Section 3에서 자동 기록, 일반 운영 수동 설정 불필요)
Z_FLOW_ENABLED false 재시작 Z-Flow 연동 활성화
MEMORY_ALERT_ENABLED true 즉시 메모리 임계치 초과 시 알림

🔗 Z-Flow 통합 레이어 (선택)

z_pulsez_flow를 같은 상위 디렉토리에 둔 뒤 setup에서 Z_FLOW_ENABLED=true를 선택하면, setup이 sibling z_flow를 감지해 Z_FLOW_PATH를 기록합니다. Z-Flow 런타임이 존재하는 경우 Z-Pulse가 ZFlowBridge 단일 주입점을 통해 Z-Flow를 오케스트레이션합니다. Z-Pulse는 Z-Flow 내부 전략 키나 market-data 스크립트를 직접 소유하지 않습니다.

활성화 시 추가되는 기능:

텔레그램 명령어 추가:

명령어 설명
/pair_trading 페어 매매 현황 확인
/transfer <FROM> <TO> <금액> 자산 이전 (현재는 GRVT 거래소만 지원)

대시보드 액션 버튼 추가 (메인):

버튼 조건
🔄 종료 실행 중인 Z-Flow 슬롯 봇
🔄 시작 중단된 Z-Flow 슬롯 봇
⚠️ 재개 필요 Z-Flow 슬롯 — 비정상 상태
🔄 시그널 대기 Z-Flow 슬롯 — 신호 대기 중

대시보드 상세 보기 버튼 추가:

버튼 기능
🤖 자동 배정 ON (...) / ⏸️ 자동 배정 OFF 페어 로테이션 토글
⚡ 자동 배정 재개 비정상 종료 후 자동 배정 재개 (조건부)

시장 데이터 데몬:

  • Z-Pulse는 bridge와 런타임 DI를 통해 필요한 상태와 제어 표면만 사용합니다.

Z-Flow가 없는 환경에서는 관련 UI가 완전히 숨겨지며, Z-Pulse는 단독으로 동작합니다.


🗂️ 파일 구조

z_pulse/
├── app.py                      # 진입점
├── __main__.py                 # run_all.sh 실행 진입점
├── run_all.sh                  # 통합 실행 스크립트 (권장)
├── run_all.bat                 # 통합 실행 스크립트 (Windows)
├── stop_all.sh                 # 프로세스 일괄 종료 (macOS/Linux)
├── stop_all.bat                # 프로세스 일괄 종료 (Windows)
├── setup_bot.sh                # 설정 스크립트 (macOS/Linux)
├── setup_bot.bat               # 설정 스크립트 (Windows)
├── economic_scheduler.py       # 경제지표 스케줄러
├── constants.py                # 전역 상수
├── setting.env.example         # 환경변수 예시
├── platforms/                  # 플랫폼별 구현
├── bot/
│   ├── factory.py              # Application 생성 및 핸들러 등록
│   ├── keyboard_helper.py      # ReplyKeyboardMarkup 헬퍼
│   └── handlers/
│       ├── commands.py         # 슬래시 명령어 처리
│       ├── dashboard.py        # 대시보드 UI
│       ├── process_actions.py  # 버튼 콜백 (시작/종료/재시작)
│       ├── callback_router.py  # 콜백 라우팅
│       ├── settings.py         # 설정 메뉴
│       └── keywords.py         # 키워드 모니터링 메뉴
├── config/                     # 환경변수 로드 및 런타임 설정
├── features/                   # 프로세스 제어, 경제지표, 창 관리 등
├── integration/
│   ├── z_flow_bridge.py        # Z-Flow 단일 주입점
│   ├── telegram_extensions.py  # Z-Flow 활성 시 추가 명령어/콜백
│   ├── strategy_registry.py    # 전략 타입 해석
│   ├── uptime_restart_scheduler.py  # 업타임 기반 재시작 스케줄러
│   └── z_flow_runtime_di.py    # Z-Flow 런타임 DI
├── monitoring/                 # 프로세스 감시, 로그 키워드 모니터
├── scripts/                    # Z-Pulse 소유 보조 유틸리티
│   ├── stop_processes.py       # 기존 프로세스 정리
│   ├── daemon_watchdog.py      # 데몬 워치독
│   ├── log_wrapper.sh
│   └── 기타 Z-Pulse 운영 유틸리티
└── utils/                      # 공통 유틸리티

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages