가이드 추가: 실제 Zabbix Agent 설치 + 배포 SSH 키/GitHub Secrets 설정

- docs/ZABBIX_AGENT_ACTIVE_SETUP.md 전면 재작성(7.4): Agent2 설치(Ubuntu/RHEL/mac)
  → 설정(Server/ServerActive/Hostname) → Zabbix Web Host 등록 → problem 발생 →
  mori-worker 폴링 → MORI Alert Triage 확인 → resolve 확인 + 트러블슈팅.
- docs/DEPLOY_SSH_SETUP.md 신규: ed25519 배포키 생성 → 서버 authorized_keys →
  known_hosts → GitHub 6종 시크릿 등록 → 동작 확인 + 보안 메모.
- README 참고문서 링크 추가.

Author: saranf

README.md

@@ -583,7 +583,8 @@ docker compose up -d mori-api
 | `docs/PHASE1_INPUT_SOURCES_AND_SCHEMA.md` | Phase 1 입력 소스·스키마·질의 명세 |
 | `docs/PHASE1_LOGICAL_SCHEMA.md` | Phase 1 논리 스키마·테이블 관계 |
 | `docs/DEPLOYMENT.md` | 서버 배포·운영·트러블슈팅 가이드 |
-| `docs/ZABBIX_AGENT_ACTIVE_SETUP.md` | Zabbix Agent 온보딩 |
+| **`docs/DEPLOY_SSH_SETUP.md`** | 배포용 SSH 키 생성 + GitHub Actions 시크릿 설정 (단계별) |
+| **`docs/ZABBIX_AGENT_ACTIVE_SETUP.md`** | 실제 Zabbix Agent 2 설치 → MORI Triage 연동 (Zabbix 7.4) |
 | `docs/TRIVY_USAGE.md` | Trivy 파일시스템/이미지 스캔 가이드 |
 | `docs/FLEET_MACBOOK_ENROLLMENT_AND_TEST.md` | Fleet macOS 등록·검증 |
 | `docs/FLEET_RESET_AND_REINSTALL_GUIDE.md` | Fleet 초기화·재설치 |

docs/DEPLOY_SSH_SETUP.md

@@ -0,0 +1,103 @@
+# 배포용 SSH 키 & GitHub Actions 시크릿 설정 가이드
+
+`deploy-mori-soc` 워크플로우(`.github/workflows/deploy.yml`)가 GitHub → 배포 서버로
+**SSH 접속하여 자동 배포**하려면 아래 시크릿이 필요합니다. 시크릿이 없으면
+워크플로우는 **자동으로 스킵**(초록)되므로, 자동 배포를 쓸 때만 설정하면 됩니다.
+
+| 시크릿 | 용도 | 필수 |
+|---|---|---|
+| `DEPLOY_HOST` | 배포 서버 호스트/IP | ✅ |
+| `DEPLOY_PORT` | SSH 포트 (기본 22) | ✅ |
+| `DEPLOY_USER` | SSH 로그인 계정 | ✅ |
+| `DEPLOY_SSH_KEY` | **개인키**(private key) 전체 내용 | ✅ |
+| `DEPLOY_ENV_FILE` | 서버에서 쓸 `.env` 전체 내용(멀티라인) | ✅ |
+| `DEPLOY_KNOWN_HOSTS` | 서버의 known_hosts 라인 | 선택(없으면 ssh-keyscan 자동) |
+
+---
+
+## 1. 배포 전용 SSH 키쌍 생성 (로컬)
+
+개인 계정 키를 재사용하지 말고 **배포 전용 키**를 새로 만드세요.
+
+```bash
+ssh-keygen -t ed25519 -C "mori-deploy" -f ~/.ssh/mori_deploy -N ""
+# 생성물:
+#   ~/.ssh/mori_deploy       ← 개인키 (GitHub Secret DEPLOY_SSH_KEY 에 넣을 것)
+#   ~/.ssh/mori_deploy.pub   ← 공개키 (서버에 등록)
+```
+
+> `-N ""` = 패스프레이즈 없음. CI는 대화형 입력을 못 하므로 배포 키는 패스프레이즈 없이 만듭니다. (대신 이 키는 배포에만 쓰고, 유출 시 서버에서 즉시 제거)
+
+---
+
+## 2. 공개키를 배포 서버에 등록
+
+```bash
+# 방법 A) ssh-copy-id (가장 간단)
+ssh-copy-id -i ~/.ssh/mori_deploy.pub -p <DEPLOY_PORT> <DEPLOY_USER>@<DEPLOY_HOST>
+
+# 방법 B) 수동 — 서버에서
+#   ~/.ssh/authorized_keys 에 mori_deploy.pub 내용을 한 줄로 추가
+mkdir -p ~/.ssh && chmod 700 ~/.ssh
+cat mori_deploy.pub >> ~/.ssh/authorized_keys
+chmod 600 ~/.ssh/authorized_keys
+```
+
+접속 테스트(개인키로):
+
+```bash
+ssh -i ~/.ssh/mori_deploy -p <DEPLOY_PORT> <DEPLOY_USER>@<DEPLOY_HOST> "echo OK && docker --version"
+```
+
+`OK` 가 나오면 성공입니다.
+
+---
+
+## 3. known_hosts 값 얻기 (선택)
+
+`DEPLOY_KNOWN_HOSTS` 를 설정하면 CI가 매번 ssh-keyscan 하지 않아 더 안전합니다.
+
+```bash
+ssh-keyscan -p <DEPLOY_PORT> <DEPLOY_HOST>
+# 출력된 라인들을 그대로 DEPLOY_KNOWN_HOSTS 값으로 복사
+```
+
+설정하지 않으면 워크플로우가 `ssh-keyscan`으로 자동 처리합니다(TOFU).
+
+---
+
+## 4. GitHub 저장소에 시크릿 등록
+
+GitHub 저장소 → **Settings → Secrets and variables → Actions → New repository secret** 에서
+아래를 각각 추가합니다.
+
+| Name | Value |
+|---|---|
+| `DEPLOY_HOST` | 예: `mori.example.com` |
+| `DEPLOY_PORT` | 예: `22` |
+| `DEPLOY_USER` | 예: `deploy` |
+| `DEPLOY_SSH_KEY` | `cat ~/.ssh/mori_deploy` **전체 출력**(`-----BEGIN … END-----` 포함) |
+| `DEPLOY_ENV_FILE` | 서버용 `.env` 전체 내용(멀티라인 그대로) |
+| `DEPLOY_KNOWN_HOSTS` | 3단계 출력(선택) |
+
+개인키 복사:
+
+```bash
+cat ~/.ssh/mori_deploy   # 이 전체를 DEPLOY_SSH_KEY 값에 붙여넣기
+```
+
+> ⚠️ **`.pub`(공개키)가 아니라 개인키 파일 내용**을 넣습니다. `DEPLOY_SSH_KEY`가 비어 있으면 "The ssh-private-key argument is empty" 에러로 실패합니다(가드로 스킵되지만 자동 배포는 안 됨).
+
+---
+
+## 5. 동작 확인
+
+- 시크릿 등록 후 `main`에 push하거나 **Actions → deploy-mori-soc → Run workflow**(수동 실행).
+- 성공 시: 서버에서 `rsync` → `.env` 업로드 → `docker compose pull && up -d` 순으로 배포됩니다.
+- 시크릿을 하나라도 안 넣었으면 워크플로우는 **스킵(초록)** — 실패로 뜨지 않습니다.
+
+## 6. 보안 메모
+
+- 배포 키는 **배포 전용**으로만 사용하고, 서버 `authorized_keys`에서 필요 시 즉시 제거할 수 있게 관리하세요.
+- 가능하면 `DEPLOY_USER`는 `docker` 그룹만 가진 **최소 권한 계정**으로 두고, 서버 방화벽에서 SSH 포트를 신뢰 IP로 제한하세요.
+- `DEPLOY_ENV_FILE`에는 실운영 비밀번호가 들어가므로 **GitHub Secret으로만** 관리하고 저장소에 커밋하지 마세요.

docs/ZABBIX_AGENT_ACTIVE_SETUP.md

@@ -1,135 +1,151 @@
-# Zabbix Agent Active 등록 가이드
+# 실제 Zabbix Agent 설치 & MORI 연동 가이드 (Zabbix 7.4)
 
-## 1. 목적
+실제 서버/PC에 **Zabbix Agent 2**를 설치해 MORI 스택의 Zabbix Server에 연결하고,
+문제(problem)가 발생하면 **MORI Alert Triage로 흘러 들어오는 것까지** 확인하는 전체 절차입니다.
 
-이 문서는 개인 PC 또는 테스트 단말을 **Zabbix Agent Active 방식**으로
-MORI SOC-lite의 Zabbix Server에 연결하는 절차를 정리합니다.
-
-## 2. 권장 방식
-
-권장 방식은 **Active Agent**입니다.
+```
+[대상 서버] Zabbix Agent 2  ──(Active)──▶  [MORI] Zabbix Server(10051)
+                                                    │
+                                        트리거 발생 → problem
+                                                    │  (mori-worker 30초 폴링)
+                                                    ▼
+                                          MORI Alert Triage → Incident → 증적
+```
 
-- 단말이 Zabbix Server로 직접 연결
-- NAT/사내망 환경에서 상대적으로 구성 단순
-- 서버가 단말의 `10050` 포트로 직접 들어올 필요 없음
+권장은 **Active Agent** 방식입니다 — 단말이 서버로 outbound 접속하므로 NAT/사내망에서 구성이 단순하고, 서버가 단말의 10050 포트로 들어올 필요가 없습니다.
 
-현재 서버 공개 포트 기준:
+---
 
-- Zabbix Web: `http://mori.rmstudio.co.kr:18081`
-- Zabbix Server: `mori.rmstudio.co.kr:10051`
+## 0. 사전 확인 (MORI 측)
 
-## 3. 사전 조건
+MORI 스택이 떠 있으면 Zabbix Server/Web은 이미 실행 중입니다.
 
-- 내 PC에서 `mori.rmstudio.co.kr:10051`로 outbound 연결 가능
-- Zabbix Web 로그인 가능
-- Host 이름을 직접 지정할 수 있음
+```bash
+docker compose ps zabbix-server zabbix-web
+```
 
-초기 Zabbix Web 계정(초기 설치 기준):
+- **Zabbix Web**: `http://<서버>:18081` (`.env`의 `MORI_ZABBIX_UI_URL`, 기본 `Admin` / `zabbix`)
+- **Zabbix Server(agent 접속 대상)**: `<서버>:10051` (compose에서 `10051:10051` 노출)
 
-- ID: `Admin`
-- PW: `zabbix`
+대상 서버에서 `<서버>:10051` 로 outbound 연결이 가능해야 합니다.
 
-## 4. 서버 측 Host 생성
+```bash
+nc -vz <서버> 10051    # succeeded 나오면 OK
+```
 
-Zabbix Web에서 아래 순서로 등록합니다.
+---
 
-1. `Data collection` → `Hosts`
-2. `Create host`
-3. 아래 값 입력
+## 1. 대상 서버에 Zabbix Agent 2 설치
 
-- Host name: Agent 설정의 `Hostname`과 동일값
-- Templates:
-  - Windows: `Windows by Zabbix agent active`
-  - Linux: `Linux by Zabbix agent active`
-  - macOS: 운영 환경에 맞는 active 템플릿 또는 범용 agent 템플릿
-- Host groups: 예) `Endpoints`
-- Interfaces: Active 전용만 사용할 경우 필수는 아니지만 관리 편의상 추가 가능
+### Ubuntu / Debian
 
-## 5. Agent 설정 예시
+```bash
+# Zabbix 7.4 리포지토리 (배포판 버전에 맞게: ubuntu24.04, debian12 등)
+wget https://repo.zabbix.com/zabbix/7.4/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_latest_7.4+ubuntu24.04_all.deb
+sudo dpkg -i zabbix-release_latest_7.4+ubuntu24.04_all.deb
+sudo apt update
+sudo apt install -y zabbix-agent2
+```
 
-저장소 예시 파일:
+### RHEL / Rocky / AlmaLinux
 
-- `config/zabbix_agent/zabbix_agent2.active.example.conf`
+```bash
+sudo rpm -Uvh https://repo.zabbix.com/zabbix/7.4/release/rhel/9/noarch/zabbix-release-latest-7.4.el9.noarch.rpm
+sudo dnf clean all
+sudo dnf install -y zabbix-agent2
+```
 
-핵심 설정은 아래 4개입니다.
+### macOS (Homebrew — 테스트용)
 
-- `Server=mori.rmstudio.co.kr`
-- `ServerActive=mori.rmstudio.co.kr:10051`
-- `Hostname=PC별_고유이름`
-- `HostMetadata=windows|linux|macos`
+```bash
+brew install zabbix
+# 설정 파일: $(brew --prefix)/etc/zabbix/zabbix_agent2.conf
+```
 
-예시:
+---
 
-```conf
-Server=mori.rmstudio.co.kr
-ServerActive=mori.rmstudio.co.kr:10051
-Hostname=SRANG-LAPTOP
-HostMetadata=windows
-```
+## 2. 에이전트 설정
 
-## 6. OS별 적용 포인트
+설정 파일: `/etc/zabbix/zabbix_agent2.conf` (macOS는 brew 경로). 아래 3개만 맞추면 됩니다.
 
-### Windows
+```ini
+# 수동 체크(Passive)용 — 서버 IP 허용
+Server=<MORI 서버 IP>
 
-- Zabbix Agent 2 설치
-- 예시 설정 파일 내용을 `zabbix_agent2.conf`에 반영
-- 서비스 재시작
+# Active 체크용 — 에이전트가 접속할 서버:포트
+ServerActive=<MORI 서버 IP>:10051
 
-권장 메타데이터:
+# 이 호스트의 고유 이름 — Zabbix Web에서 등록할 Host name 과 반드시 동일하게
+Hostname=my-web-01
+```
 
-- `HostMetadata=windows`
+적용:
 
-### Linux
+```bash
+sudo systemctl enable --now zabbix-agent2
+sudo systemctl restart zabbix-agent2
+sudo systemctl status zabbix-agent2      # active(running) 확인
+# 로그: /var/log/zabbix/zabbix_agent2.log
+```
 
-- 패키지로 Zabbix Agent 2 설치
-- `/etc/zabbix/zabbix_agent2.conf` 수정
-- 서비스 재시작
+---
 
-권장 메타데이터:
+## 3. Zabbix Web에서 Host 등록
 
-- `HostMetadata=linux`
+Zabbix Web(`:18081`, Admin/zabbix) 접속 후:
 
-### macOS
+1. **Data collection → Hosts → Create host**
+2. 값 입력:
+   - **Host name**: 에이전트의 `Hostname`과 **동일값** (예: `my-web-01`)
+   - **Templates**: `Linux by Zabbix agent` (또는 `Linux by Zabbix agent active`) 추가
+   - **Host groups**: `Linux servers` 등 아무 그룹
+   - **Interfaces → Add → Agent**: 대상 서버 IP / 포트 `10050`
+     - (Active만 쓸 경우 인터페이스 IP는 형식상 넣어두면 됩니다)
+3. **Add** 저장
 
-- Zabbix Agent 2 설치
-- 설정 파일에 Active 항목 반영
-- LaunchAgent/서비스 재시작
+수 분 뒤 **Monitoring → Latest data**에서 CPU/메모리/디스크 값이 들어오면 성공입니다.
 
-권장 메타데이터:
+> 💡 **CLI로 등록**하고 싶으면 `host.create` + `templateid` API를 쓸 수 있습니다. 데모용 문제 발생은 `./scripts/mori-zabbix-demo-problem.sh` 참고.
 
-- `HostMetadata=macos`
+---
 
-## 7. 연결 확인 방법
+## 4. 문제(problem) 발생 → MORI로 흐르는지 확인
 
-Zabbix Web에서 아래를 확인합니다.
+실제 트리거가 걸리는 상황(디스크 사용률 초과, 서비스 다운 등)을 만들거나,
+`Linux by Zabbix agent` 템플릿의 기본 트리거가 발화하면 **Monitoring → Problems**에 문제가 뜹니다.
 
-- `Monitoring` → `Hosts`
-- Host 상태가 활성으로 보이는지 확인
-- `Latest data`에서 CPU/Memory/Disk 항목 수집 확인
+- **mori-worker**가 30초 주기로 `problem.get`을 폴링해 정규화 → PostgreSQL `alerts` 적재.
+- MORI `/ui` → **🚨 Alert Triage** 탭에 `source=zabbix`로 표시됩니다(각 알림에 `Zabbix ↗` 딥링크).
+- 확인용:
 
-처음 데이터 반영까지는 수 분 정도 걸릴 수 있습니다.
+```bash
+# MORI가 방금 폴링했는지 (source freshness)
+docker exec -it mori-soc-soc-postgres-1 psql -U mori -d mori_soc \
+  -c "SELECT source,status,last_success_at FROM source_syncs WHERE source='zabbix';"
 
-## 8. 추천 PoC 항목
+# 적재된 zabbix alert
+docker exec -it mori-soc-soc-postgres-1 psql -U mori -d mori_soc \
+  -c "SELECT alert_id,severity,rule_name,resolved_at FROM alerts WHERE source='zabbix' ORDER BY observed_at DESC LIMIT 5;"
+```
 
-처음에는 아래 항목만 확인해도 충분합니다.
+Zabbix에서 문제가 **해소(resolve)** 되면(복구 이벤트 발생) MORI alert의 `resolved_at`이 채워지고
+Triage에 "✓ 소스 해소" 뱃지가 표시됩니다.
 
-- CPU utilization
-- Memory utilization
-- Disk usage
-- Network interface status
-- Agent availability
+---
 
-## 9. 트러블슈팅
+## 5. 자주 겪는 문제
 
-### 데이터가 안 들어올 때
+| 증상 | 원인 / 해결 |
+|---|---|
+| Latest data에 값이 안 옴 | `Hostname`(에이전트) ≠ Host name(Web) 불일치 / 방화벽에서 10051 outbound 막힘 |
+| Web에서 host가 빨간 ZBX | Passive 인터페이스 IP 오류 — Active만 쓰면 무시 가능, 또는 IP 교정 |
+| MORI Triage에 안 뜸 | Problems에 실제 problem이 있는지 확인 → `source_syncs` last_success 갱신 확인 → `mori-worker` 로그 확인 |
+| `mori-worker` 로그에 Zabbix 인증 오류 | `.env`의 `MORI_ZABBIX_USER/PASSWORD` 확인 (기본 Admin/zabbix). 7.x는 반복 로그인 일시 차단 있음 |
 
-- `Hostname`이 Zabbix Host 이름과 정확히 같은지 확인
-- `ServerActive=mori.rmstudio.co.kr:10051`로 설정했는지 확인
-- 단말 방화벽/사내망에서 outbound `10051/tcp` 차단이 없는지 확인
-- Active 템플릿을 연결했는지 확인
+---
 
-### 로그인은 되는데 Host가 회색일 때
+## 6. 참고
 
-- Host 템플릿이 맞지 않거나
-- Agent 서비스가 아직 재시작되지 않았거나
-- Active check 대상 호스트명이 일치하지 않는 경우가 많습니다.
+- MORI는 Zabbix를 **read-only**로 폴링만 합니다(에이전트 설치·Zabbix 설정 변경은 이 문서대로 사용자가 수행). MORI가 Zabbix 구성을 바꾸지 않습니다.
+- 데모 시나리오(실제 서버 없이 problem 발생)는 `./scripts/mori-zabbix-demo-problem.sh` 로 재현할 수 있습니다.
+- 배포 자동화(GitHub Actions)용 SSH 설정은 [DEPLOY_SSH_SETUP.md](./DEPLOY_SSH_SETUP.md) 참고.