From a6fc291d35b236bbce40c894a645524096f14d4b Mon Sep 17 00:00:00 2001
From: ruki <ruki@pinksky.kr>
Date: Tue, 5 May 2026 21:21:12 +0900
Subject: [PATCH] Add README: project intent, infra map, usage guide

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..911cb33
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# 🏙️ 작은도시 인프라 현황 (MiniCITY Agent Status)
+
+> **현재 단계: v0.x (내부 구축중, 미공개)**
+
+개인/소규모 인프라 환경의 실시간 가동 현황을 한눈에 확인하는 정적 대시보드. 주기적으로 각 서비스 엔드포인트를 체크하고, 결과를 JSON에 기록해 브라우저에서 GitHub Dark 테마 스타일로 표시한다.
+
+---
+
+## 구성
+
+| 파일 | 역할 |
+|------|------|
+| `health_check.py` | 서비스/에이전트/장비 헬스체크 스크립트 |
+| `index.html` | 정적 대시보드 페이지 (자체 JSON을 읽어 렌더링) |
+| `health.json` | 체크 결과 저장소 (gitignore — 실행 환경에서 자동 생성) |
+
+`health_check.py`는 **스탠드얼론 실행**을 전제로 한다. cron 등으로 주기적으로 실행해 `health.json`을 갱신하고, 브라우저에서는 `index.html`을 새로고침하면 최신 상태를 본다.
+
+---
+
+## 인프라 대상
+
+물리 장비 4대 + NAS 2대 + 라우터 3대. 전체는 Tailscale 메시 네트워크로 연결.
+
+### 장비
+
+- **맥미니 M4 Pro** — Apple M4 Pro · 64GB · 통합 GPU (pinksky.kr)
+- **메인컴 (PS-i14700K)** — Intel Core i7-14700K · 96GB · RTX 3090 24GB
+- **보조컴 (MH-3900x)** — AMD Ryzen 9 3900X · 32GB · RTX 3080 12GB
+- **서버컴 (gw-ps-5600)** — Intel Core i7-14700K · 96GB · RTX 3090 (gwenc.kr)
+- **집 NAS (mh-nas)** — Synology DS418+ (minicity.kr)
+- **회사 NAS (gwenc-nas2)** — Synology
+- **백업 NAS (ps-bk-nas)** — 14TB HDD
+
+### 장비별 운영 서비스
+
+| 장비 | 주요 서비스 |
+|------|-----------|
+| 맥미니 | Caddy 리버스 프록시, SearXNG, Gitea, MiniCITY 위키(Quartz4), 에이전트 게이트웨이 |
+| 메인컴 | Dify, 공사관리ERP API+Frontend |
+| 보조컴 | Photo Station, Everything 검색 |
+| 서버컴 | Proxmox VE, Hyper-V VM |
+| 집 NAS | Web Station, 파일 서버, DDNS |
+
+---
+
+## 대시보드 뷰
+
+1. **도메인별 현황** — `pinksky.kr` / `minicity.kr` / `gwenc.kr` 별로 서비스를 그룹핑, HTTP 응답/지연시간으로 상태 표시
+2. **에이전트별 현황** — 루키 / 미미 / 분홍 / 하늘 각 에이전트의 게이트웨이 연결 상태 확인
+
+체크 방식: `curl`, `ssh`, `tailscale ping`, `nc` 포트 체크를 혼합 사용.
+
+---
+
+## 로컬 실행
+
+```bash
+# 1. 상태 체크 → health.json 갱신
+python3 health_check.py
+
+# 2. 대시보드 확인
+open index.html
+```
+
+실서비스(`agent.pinksky.kr`)에서는 `health_check.py`를 cron으로 주기 실행한다.
+
+---
+
+## 라이선스
+
+비공개 프로젝트. 사전 협의 없는 복사 및 배포 금지.
+