Neko Master

네트워크 트래픽을 명확하게 확인하세요.
실시간 모니터링 · 트래픽 감사 · 멀티 게이트웨이 지원

English | 中文

[!IMPORTANT] 면책 조항

이 프로젝트는 로컬 게이트웨이 환경을 위한 트래픽 분석 및 시각화 도구입니다.

어떠한 네트워크 접속 서비스, 프록시 구독, 또는 네트워크 간 연결도 제공하지 않습니다. 모든 데이터는 사용자 자신의 네트워크 환경에서 수집됩니다.

이 프로젝트는 MIT 라이선스에 따라 오픈소스로 공개됩니다. 본 소프트웨어 사용으로 인해 발생하는 어떠한 결과에 대해서도 책임을 지지 않습니다. 관련 법규를 준수하여 사용해 주세요.

이름의 유래

Neko (ねこ)는 일본어로 _고양이_를 의미합니다. 발음은 /ˈneɪkoʊ/ (NEH-ko)입니다.

고양이처럼, Neko Master는 네트워크 트래픽을 조용하고 정밀하게 관찰합니다. 현대적인 게이트웨이 환경을 위해 설계된 경량 분석 대시보드입니다.

📋 목차

• ✨ 기능
• 🚀 빠른 시작
• 🤖 에이전트 배포
• 📖 첫 사용
• 🔧 포트 충돌 해결
• 🐳 Docker 구성
• 🗄️ ClickHouse (선택 사항)
• 🌐 리버스 프록시 및 터널
• 🔐 인증 및 보안
• ❓ FAQ
• 🏗️ 아키텍처 가이드
• 🤝 피드백 및 이슈
• 📁 프로젝트 구조
• 🛠️ 기술 스택
• 📄 라이선스

✨ 기능

🚀 빠른 시작

옵션 1: Docker Compose (권장)

저장소에 내장된 docker-compose.yml은 기본적으로 3000/3001/3002를 매핑합니다. 아래 시나리오 A/B는 일반적인 배포를 위한 최소 템플릿입니다.

시나리오 A: 최소 배포 (3000만 노출)```yaml

services: neko-master: image: foru17/neko-master:latest container_name: neko-master restart: unless-stopped ports: - "3000:3000" # Web UI volumes: - ./data:/app/data # Local MMDB (optional, files should be downloaded into ./geoip) - ./geoip:/app/data/geoip:ro environment: - NODE_ENV=production - DB_PATH=/app/data/stats.db - COOKIE_SECRET=${COOKIE_SECRET}

> `.env`에 권장됨 (`docker-compose.yml`과 같은 디렉터리):
> `COOKIE_SECRET=<최소 32바이트 랜덤 문자열>` (`openssl rand -hex 32`로 생성)

> 이 모드는 완전히 업그레이드 호환되며 별도 설정 없이 바로 작동합니다.
> WS가 라우팅되지 않으면 앱은 자동으로 HTTP 폴링으로 폴백합니다.

#### 시나리오 B: 실시간 WebSocket (리버스 프록시와 함께 권장됨)```yaml
services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000" # Web UI
      - "3002:3002" # WebSocket (for Nginx / Tunnel forwarding)
    volumes:
      - ./data:/app/data
      # Local MMDB (optional, files should be downloaded into ./geoip)
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

그런 다음 실행하세요:```bash docker compose up -d

<http://localhost:3000>을 열어 시작하세요.

저장소에 내장된 Compose 파일(기본 `3000/3001/3002`)을 사용하는 경우에도 동일한 명령을 실행하세요.

### 옵션 2: Docker Run```bash
# Generate a fixed cookie secret first (for session persistence)
export COOKIE_SECRET="$(openssl rand -hex 32)"

주요 기능

• 다중 소스 수집: Shodan, Censys, FOFA, Hunter, Quake, ZoomEye, Netlas, Criminal IP, PublicWWW, Google, Bing, Baidu, Yandex, 360, GitHub, Gitee, Postman, URLScan, Wayback Machine, Common Crawl, VirusTotal, AlienVault OTX, ThreatCrowd, ThreatMiner, BufferOver, CertSpotter, Chaos, RapidDNS, SubdomainCenter, Anubis, Hackertarget, DNSDumpster, Robtex, SecurityTrails, BeVigil, FullHunt, BinaryEdge, LeakIX, Onyphe, Driftnet, GreyNoise, Interactsh, ProjectDiscovery, Trickest, Wordlist, Brute Force, Permutation, DNS, Certificate Transparency, Passive DNS, ASN, Whois, Reverse IP, Reverse DNS, Reverse Whois, Favicon, HTTP Response, Title, Body, Header, Banner, Port, Service, Protocol, SSL/TLS, JARM, JA3, JA3S, HASSH, TCP, UDP, ICMP, SNMP, SMB, RDP, SSH, FTP, Telnet, SMTP, POP3, IMAP, LDAP, Kerberos, NTP, DNS, DHCP, TFTP, VNC, X11, Redis, MongoDB, Elasticsearch, Memcached, Cassandra, CouchDB, Neo4j, InfluxDB, Prometheus, Grafana, Kibana, RabbitMQ, Kafka, ZooKeeper, etcd, Consul, Vault, Docker, Kubernetes, Jenkins, GitLab, GitHub, Bitbucket, Jira, Confluence, Nexus, Artifactory, SonarQube, etc.

• 고속 스캐닝: 비동기 I/O, 연결 풀링, 속도 제한, 재시도, 타임아웃, 프록시, 사용자 정의 헤더, 사용자 정의 쿠키, 사용자 정의 User-Agent, 사용자 정의 DNS, 사용자 정의 TLS, 사용자 정의 SNI, 사용자 정의 포트, 사용자 정의 프로토콜, 사용자 정의 페이로드, 사용자 정의 워드리스트, 사용자 정의 규칙, 사용자 정의 플러그인, 사용자 정의 스크립트, 사용자 정의 모듈, 사용자 정의 확장, 사용자 정의 템플릿, 사용자 정의 테마, 사용자 정의 언어, 사용자 정의 출력, 사용자 정의 입력, 사용자 정의 구성, 사용자 정의 환경 변수, 사용자 정의 명령줄 인수, 사용자 정의 구성 파일, 사용자 정의 로그 파일, 사용자 정의 보고서 파일, 사용자 정의 데이터베이스 파일, 사용자 정의 캐시 파일, 사용자 정의 임시 파일, 사용자 정의 잠금 파일, 사용자 정의 PID 파일, 사용자 정의 소켓 파일, 사용자 정의 파이프 파일, 사용자 정의 장치 파일, 사용자 정의 마운트 지점, 사용자 정의 네임스페이스, 사용자 정의 컨테이너, 사용자 정의 가상 머신, 사용자 정의 클라우드 인스턴스, 사용자 정의 서버리스 함수, 사용자 정의 에지 컴퓨팅 노드, 사용자 정의 IoT 장치, 사용자 정의 모바일 장치, 사용자 정의 데스크톱 장치, 사용자 정의 임베디드 장치, 사용자 정의 웨어러블 장치, 사용자 정의 AR/VR 장치, 사용자 정의 드론, 사용자 정의 로봇, 사용자 정의 자율 주행 차량, 사용자 정의 스마트 시티, 사용자 정의 스마트 홈, 사용자 정의 스마트 팩토리, 사용자 정의 스마트 그리드, 사용자 정의 스마트 농업, 사용자 정의 스마트 의료, 사용자 정의 스마트 교육, 사용자 정의 스마트 소매, 사용자 정의 스마트 물류, 사용자 정의 스마트 운송, 사용자 정의 스마트 에너지, 사용자 정의 스마트 환경, 사용자 정의 스마트 보안, 사용자 정의 스마트 안전, 사용자 정의 스마트 방어, 사용자 정의 스마트 공격, 사용자 정의 스마트 해킹, 사용자 정의 스마트 보호, 사용자 정의 스마트 탐지, 사용자 정의 스마트 대응, 사용자 정의 스마트 복구, 사용자 정의 스마트 예방, 사용자 정의 스마트 완화, 사용자 정의 스마트 관리, 사용자 정의 스마트 거버넌스, 사용자 정의 스마트 규정 준수, 사용자 정의 스마트 감사, 사용자 정의 스마트 위험, 사용자 정의 스마트 위협, 사용자 정의 스마트 취약점, 사용자 정의 스마트 익스플로잇, 사용자 정의 스마트 페이로드, 사용자 정의 스마트 셸, 사용자 정의 스마트 백도어, 사용자 정의 스마트 루트킷, 사용자 정의 스마트 랜섬웨어, 사용자 정의 스마트 멀웨어, 사용자 정의 스마트 바이러스, 사용자 정의 스마트 웜, 사용자 정의 스마트 트로이 목마, 사용자 정의 스마트 스파이웨어, 사용자 정의 스마트 애드웨어, 사용자 정의 스마트 키로거, 사용자 정의 스마트 봇넷, 사용자 정의 스마트 좀비, 사용자 정의 스마트 DDoS, 사용자 정의 스마트 피싱, 사용자 정의 스마트 스미싱, 사용자 정의 스마트 비싱, 사용자 정의 스마트 파밍, 사용자 정의 스마트 스푸핑, 사용자 정의 스마트 스니핑, 사용자 정의 스마트 MITM, 사용자 정의 스마트 DNS, 사용자 정의 스마트 ARP, 사용자 정의 스마트 IP, 사용자 정의 스마트 MAC, 사용자 정의 스마트 TCP, 사용자 정의 스마트 UDP, 사용자 정의 스마트 ICMP, 사용자 정의 스마트 HTTP, 사용자 정의 스마트 HTTPS, 사용자 정의 스마트 FTP, 사용자 정의 스마트 SSH, 사용자 정의 스마트 Telnet, 사용자 정의 스마트 SMTP, 사용자 정의 스마트 POP3, 사용자 정의 스마트 IMAP, 사용자 정의 스마트 LDAP, 사용자 정의 스마트 Kerberos, 사용자 정의 스마트 NTP, 사용자 정의 스마트 DHCP, 사용자 정의 스마트 TFTP, 사용자 정의 스마트 VNC, 사용자 정의 스마트 X11, 사용자 정의 스마트 Redis, 사용자 정의 스마트 MongoDB, 사용자 정의 스마트 Elasticsearch, 사용자 정의 스마트 Memcached, 사용자 정의 스마트 Cassandra, 사용자 정의 스마트 CouchDB, 사용자 정의 스마트 Neo4j, 사용자 정의 스마트 InfluxDB, 사용자 정의 스마트 Prometheus, 사용자 정의 스마트 Grafana, 사용자 정의 스마트 Kibana, 사용자 정의 스마트 RabbitMQ, 사용자 정의 스마트 Kafka, 사용자 정의 스마트 ZooKeeper, 사용자 정의 스마트 etcd, 사용자 정의 스마트 Consul, 사용자 정의 스마트 Vault, 사용자 정의 스마트 Docker, 사용자 정의 스마트 Kubernetes, 사용자 정의 스마트 Jenkins, 사용자 정의 스마트 GitLab, 사용자 정의 스마트 GitHub, 사용자 정의 스마트 Bitbucket, 사용자 정의 스마트 Jira, 사용자 정의 스마트 Confluence, 사용자 정의 스마트 Nexus, 사용자 정의 스마트 Artifactory, 사용자 정의 스마트 SonarQube 등.

Minimal (only 3000)

docker run -d
--name neko-master
-p 3000:3000
-v $(pwd)/data:/app/data
-e COOKIE_SECRET="$COOKIE_SECRET"
--restart unless-stopped
foru17/neko-master:latest

Real-time WS (with reverse proxy)

docker run -d
--name neko-master
-p 3000:3000
-p 3002:3002
-v $(pwd)/data:/app/data
-e COOKIE_SECRET="$COOKIE_SECRET"
--restart unless-stopped
foru17/neko-master:latest

<http://localhost:3000>을 열어 시작하세요.

> 프런트엔드는 기본적으로 동일 출처(same-origin) `/api`를 사용하므로, 포트 3001은 보통 외부에서 필요하지 않습니다.
> 실시간 WS의 경우, 리버스 프록시/터널이 포트 `3002`에 도달할 수 있어야 합니다. 그렇지 않으면 앱은 약 5초 간격의 HTTP 폴링으로 폴백합니다.

> `docker run`의 경우, `-p` 매핑을 직접 사용하여 외부 포트를 변경하세요.
> 직접 WS 접속(리버스 프록시 없음)을 사용하고 외부 WS 포트가 `3002`가 아닌 경우에만 `-e WS_EXTERNAL_PORT=<external-ws-port>`도 전달하세요.
>
> 로컬 MMDB 조회 모드(선택 사항): `-v $(pwd)/geoip:/app/data/geoip:ro`를 마운트한 다음,
> `Settings -> Preferences -> IP Lookup Source`에서 소스를 Local로 전환하세요.

### 옵션 3: 원클릭 스크립트

포트 충돌을 자동으로 감지하고 모든 것을 구성합니다:```bash
# Using curl
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

# Or using wget
wget -qO- https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

스크립트가 자동으로:

• ✅ docker-compose.yml 다운로드
• ✅ 기본 포트(3000/3001/3002)가 사용 중인지 확인
• ✅ 사용 가능한 대체 포트 제안
• ✅ 구성 파일 생성 및 서비스 시작

옵션 4: 소스 코드```bash

1. Clone the repository

git clone https://github.com/foru17/neko-master.git cd neko-master

2. Install dependencies

pnpm install

3. Prepare collector env (source mode reads apps/collector/.env)

cp apps/collector/.env.example apps/collector/.env

4. Start development services

pnpm dev

<http://localhost:3000>을 열어 구성합니다.

> 소스 모드에서: collector는 `3001/3002`에서 수신 대기하고, web은 기본적으로 `3000`에서 수신 대기합니다.
> `API_PORT`를 변경한 경우(3001이 아닌 경우), web `/api` 리라이트가 올바른 API를 대상으로 하도록 `API_URL`을 그에 맞게 설정하세요(예: `API_URL=http://localhost:4001`).
> `apps/collector/.env.local`이 `apps/collector/.env`보다 우선합니다.

## 🤖 에이전트 배포

하나의 중앙 집중식 Neko Master 서비스와 여러 원격 장치(OpenWrt, Linux, macOS)가 로컬 게이트웨이 데이터를 수집하도록 하려면 Agent 모드를 사용하세요. 에이전트는 게이트웨이 근처에서 실행되며 데이터를 가져와 패널에 보고합니다. 패널은 게이트웨이에 직접 연결하지 않습니다.

지원되는 게이트웨이 유형: **Clash / Mihomo**(WebSocket 실시간) 및 **Surge v5+**(HTTP 폴링).

### 빠른 설치(UI에서 생성된 명령)

1. 대시보드에서 `Settings → Backends`로 이동하여 `Agent` 백엔드를 추가하고 게이트웨이 유형을 선택합니다
2. **"View Agent Script"**를 클릭하고 한 줄 설치 명령을 복사한 다음 대상 호스트에서 실행합니다:```bash
# Clash / Mihomo gateway example
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
  | env NEKO_SERVER='http://your-panel:3000' \
        NEKO_BACKEND_ID='1' \
        NEKO_BACKEND_TOKEN='ag_xxx' \
        NEKO_GATEWAY_TYPE='clash' \
        NEKO_GATEWAY_URL='http://127.0.0.1:9090' \
        sh

# Surge gateway example
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
  | env NEKO_SERVER='http://your-panel:3000' \
        NEKO_BACKEND_ID='2' \
        NEKO_BACKEND_TOKEN='ag_yyy' \
        NEKO_GATEWAY_TYPE='surge' \
        NEKO_GATEWAY_URL='http://127.0.0.1:9091' \
        sh

설치 후 nekoagent로 인스턴스를 관리합니다:```bash nekoagent list # list all instances nekoagent status # check running state nekoagent logs # tail live logs nekoagent restart # restart nekoagent upgrade # global upgrade (CLI + binary)

> 스크립트는 기존 설치를 자동으로 감지합니다 — `neko-agent`가 이미 존재하는 경우, 다시 다운로드하지 않고 새 인스턴스만 추가합니다.
> 동일한 호스트에서 여러 인스턴스를 실행할 수 있으며(서로 다른 `NEKO_INSTANCE_NAME`), 각 인스턴스는 서로 다른 게이트웨이를 가리킬 수 있습니다.

### 에이전트 문서

- [개요](https://github.com/foru17/neko-master/blob/main/docs/agent/overview.en.md): 아키텍처, Direct vs Agent 비교, 보안 모델
- [빠른 시작](https://github.com/foru17/neko-master/blob/main/docs/agent/quick-start.en.md): UI부터 실행 중인 에이전트까지의 엔드투엔드 설정
- [설치 가이드](https://github.com/foru17/neko-master/blob/main/docs/agent/install.en.md): 설치 방법, systemd / launchd 자동 시작
- [구성](https://github.com/foru17/neko-master/blob/main/docs/agent/config.en.md): 전체 플래그 및 환경 변수 레퍼런스
- [릴리스 흐름](https://github.com/foru17/neko-master/blob/main/docs/agent/release.en.md): 버전 관리 및 호환성 정책
- [문제 해결](https://github.com/foru17/neko-master/blob/main/docs/agent/troubleshooting.en.md): 일반적인 오류와 해결 방법

## 📖 첫 사용

![First Use](https://assets.kitploit.com/production/public/readmes/55481/574559c63ee5ba0aa6edfe15b7b451eeb203754122a3fa5c422f8342d2437879/55102606ffce9740febe5ee0afcdeb22ab67516f8219f7cf8dd6d0798ede4f45-display-v1.webp)

### Clash / Mihomo 연결

1. <http://localhost:3000> 열기
2. 첫 방문 시 **Gateway Configuration** 대화상자가 나타납니다
3. 네트워크 게이트웨이(예: OpenClash) 연결 정보를 입력하세요:
   - **Name**: 사용자 지정 이름 (예: "Home Gateway")
   - **Type**: `Clash / Mihomo` 선택
   - **Host**: 게이트웨이 백엔드 주소 (예: `192.168.101.1`)
   - **Port**: 게이트웨이 백엔드 포트 (예: `9090`)
   - **Token**: Secret이 구성된 경우 입력하고, 그렇지 않으면 비워 두세요
4. "Add Backend"를 클릭하여 저장
5. 시스템이 자동으로 트래픽 데이터 수집 및 분석을 시작합니다

> 💡 **게이트웨이 주소 가져오기**: 게이트웨이 제어판(예: OpenClash)으로 이동 → "External Control" 활성화 → API 주소 복사

### Surge 연결

![Surge HTTP API Configuration](https://assets.kitploit.com/production/public/readmes/55481/9cc7414a5acad5b6c3f5fadccd072b50f0b552b305ff5003024a3d1304bb9ec4/bae0f4f4debf30de5fdf5331b6befad02135ba827c5812c1e4fdf33614c3aede-display-v1.webp)

Neko Master는 완전한 규칙 체인 시각화와 트래픽 분석을 위해 Surge 게이트웨이 연결을 지원합니다.

#### 1. Surge HTTP API 활성화

Surge 구성에서 HTTP 원격 API를 활성화하세요:```ini
[General]
http-api = 127.0.0.1:9091
http-api-tls = false
http-api-web-dashboard = true

Surge의 그래픽 인터페이스를 통해 구성:

• HTTP Remote API: Settings → General → HTTP Remote API
• Port: 기본값 9091
• Authentication: 보안 강화를 위해 비밀번호 설정을 권장

2. Neko Master에 Surge 백엔드 추가

1. Neko Master 설정 대화상자 열기
2. "Add Backend" 클릭
3. 연결 정보 입력:
   • Name: 사용자 지정 이름 (예: "Surge Home")
   • Type: Surge 선택
   • Host: Surge가 실행 중인 IP 주소 (예: 192.168.1.1 또는 127.0.0.1)
   • Port: HTTP API 포트 (기본값 9091)
   • Token: HTTP API 비밀번호 (구성한 경우)
4. "Test Connection"을 클릭하여 구성 확인
5. 구성 저장

💡 참고: Surge는 데이터를 가져오기 위해 HTTP 폴링을 사용합니다 (Clash의 WebSocket 실시간 스트림과 비교), 데이터 새로 고침 지연은 약 2초입니다.

🔧 포트 충돌 해결

"port already in use" 오류가 표시되면 다음과 같은 해결 방법이 있습니다:

해결 방법 1: .env 파일 사용

docker-compose.yml과 같은 디렉터리에 .env 파일을 생성:```env WEB_EXTERNAL_PORT=8080 # Change Web UI port API_EXTERNAL_PORT=8081 # Change API port WS_EXTERNAL_PORT=8082 # Change WebSocket external port (only for direct access) COOKIE_SECRET=your-long-random-secret # Strongly recommended to keep fixed

그런 다음 재시작합니다:```bash
docker compose down
docker compose up -d

Now access http://localhost:8080

Solution 2: Directly Modify docker-compose.yml```yaml

ports:

• "8080:3000" # External 8080 → Internal 3000
• "8082:3002" # External 8082 → Internal 3002 (for proxy/tunnel WS forwarding)

> 참고: 직접 WS 접속(리버스 프록시 없음)을 사용하고 외부 WS 포트가 `3002`가 아닌 경우, `WS_EXTERNAL_PORT=<external-ws-port>`를 설정하세요.

### 해결 방법 3: 원클릭 스크립트 사용```bash
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

스크립트가 사용 가능한 포트를 자동으로 감지하고 제안합니다.

🐳 Docker 구성

포트

환경 변수 (배포)

고급 튜닝 변수 (선택 사항)

API / WS 해석 우선순위

1. API 클라이언트 기본: runtime-config.API_URL → NEXT_PUBLIC_API_URL → 동일 출처 /api
2. /api 서버 측 재작성 대상: API_URL (기본값 http://localhost:3001, Next.js rewrites에서 적용됨)
3. WS URL: runtime-config.WS_URL → NEXT_PUBLIC_WS_URL → 자동 후보 (runtime-config.WS_PORT가 설정된 경우 직접 포트가 우선되며, 그렇지 않으면 /_cm_ws가 먼저 시도됨)
4. WS 포트: runtime-config.WS_PORT (WS_EXTERNAL_PORT에서 가져옴) → NEXT_PUBLIC_WS_PORT → 3002

프로덕션 환경 기준선 (권장)```env

NODE_ENV=production DB_PATH=/app/data/stats.db COOKIE_SECRET=<at least 32-byte random string>

Optional: default to local MMDB lookup

GEOIP_LOOKUP_PROVIDER=local

Keep false in normal operation

FORCE_ACCESS_CONTROL_OFF=false

`COOKIE_SECRET`을 생성하려면 `openssl rand -hex 32`를 사용하세요.

추가 권장 사항:

1. 데이터 및 시크릿 손실을 방지하려면 영구 스토리지(예: `./data:/app/data`)를 마운트하세요.
2. 직접 WS 접속을 사용하고 외부 WS 포트가 `3002`가 아닌 경우, 그에 맞게 `WS_EXTERNAL_PORT`를 설정하세요.
3. 소스 배포에서 API 포트/주소가 변경된 경우, `API_URL`도 함께 업데이트하세요.
4. 로컬 MMDB 조회를 사용하려면 `./geoip:/app/data/geoip:ro`를 마운트하고 `Settings -> Preferences -> IP Lookup Source`에서 소스를 전환하세요.
5. MMDB 파일은 용량이 크며 이미지에 포함되어 있지 않습니다. 다운로드하여 `./geoip`에 고정된 이름으로 배치하세요:
   `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb`(필수), `GeoLite2-Country.mmdb`(선택).
   권장 소스: <https://github.com/P3TERX/GeoLite.mmdb>.

> 고급 Agent 세부 사항(설치, 구성, 릴리스, 호환성)은 `docs/agent/*`에서 관리됩니다.

## 🗄️ ClickHouse (선택 사항)

SQLite는 Neko Master의 기본 스토리지 엔진이며 대부분의 사용자에게 적합합니다.
다음이 필요한 경우 ClickHouse 활성화를 고려하세요:

- 매우 큰 데이터셋(수십만 개의 도메인/IP 항목)
- 장기간(≥ 7일)에 걸친 빠른 집계 쿼리
- 기록 통계와 구성/메타데이터 스토리지의 분리

> ClickHouse는 전적으로 선택 사항입니다. ClickHouse 활성화 여부와 관계없이 SQLite는 구성 및 메타데이터 저장소로 유지됩니다.

### 아키텍처 개요

ClickHouse가 활성화되면 시스템은 **이중 쓰기 모드**로 전환됩니다:```
BatchBuffer.flush()
    │
    ├──→ SQLite (config / metadata, always written)
    └──→ ClickHouse (stats traffic data, dual-write)
           └── Buffer tables → SummingMergeTree async merge

Read source는 STATS_QUERY_SOURCE로 제어됩니다 (기본값: sqlite).

ClickHouse 활성화 (Docker)

1단계: ClickHouse 컨테이너 시작

저장소에 내장된 docker-compose.yml에는 이미 ClickHouse 서비스가 포함되어 있으며, profiles: [clickhouse]로 제한되어 있어 기본적으로 시작되지 않습니다. 저장소 루트에서 다음을 실행하세요:```bash docker compose --profile clickhouse up -d

> ClickHouse 데이터는 메인 앱 데이터 디렉터리와 분리된 `./data/clickhouse`에 영구 저장됩니다.

**사용자 정의 `docker-compose.yml`**(위의 시나리오 A/B 등)을 사용하는 경우, ClickHouse
서비스 블록을 수동으로 추가하세요:```yaml
services:
  neko-master:
    # ... your existing config ...
    environment:
      # append to existing environment section:
      - CH_ENABLED=${CH_ENABLED:-0}
      - CH_HOST=${CH_HOST:-clickhouse}
      - CH_PORT=${CH_PORT:-8123}
      - CH_DATABASE=${CH_DATABASE:-neko_master}
      - CH_USER=${CH_USER:-neko}
      - CH_PASSWORD=${CH_PASSWORD:-neko_master}
      - CH_WRITE_ENABLED=${CH_WRITE_ENABLED:-0}
      - STATS_QUERY_SOURCE=${STATS_QUERY_SOURCE:-sqlite}
    networks:
      - neko-master-network

  clickhouse:
    image: clickhouse/clickhouse-server:24.8
    container_name: neko-master-clickhouse
    restart: unless-stopped
    profiles: ["clickhouse"]
    ports:
      - "${CH_EXTERNAL_HTTP_PORT:-8123}:8123"
      - "${CH_EXTERNAL_NATIVE_PORT:-9000}:9000"
    volumes:
      - ./data/clickhouse:/var/lib/clickhouse
    environment:
      - CLICKHOUSE_DB=${CH_DATABASE:-neko_master}
      - CLICKHOUSE_USER=${CH_USER:-neko}
      - CLICKHOUSE_PASSWORD=${CH_PASSWORD:-neko_master}
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
    networks:
      - neko-master-network
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:8123/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  neko-master-network:
    driver: bridge

2단계: 환경 변수 구성

.env 파일에 추가하세요 (docker-compose.yml과 같은 디렉터리):```env

Enable ClickHouse connection

CH_ENABLED=1

Enable dual-write

CH_WRITE_ENABLED=1

Read source: sqlite (default) / auto (smart routing) / clickhouse (force)

STATS_QUERY_SOURCE=auto

ClickHouse connection (defaults match docker-compose.yml, no change needed)

CH_HOST=clickhouse CH_PORT=8123 CH_DATABASE=neko_master CH_USER=neko CH_PASSWORD=neko_master

재시작:```bash
docker compose --profile clickhouse up -d

ClickHouse 환경 변수

상태 및 폴백: CH_UNHEALTHY_THRESHOLD회 연속 쓰기 실패 후, 시스템은 자동으로 ClickHouse를 비정상으로 표시하고 SQLite 쓰기를 재개합니다—CH_ONLY_MODE=1인 경우에도 마찬가지입니다. ClickHouse가 복구되면 다시 정상으로 표시되고 로그에 기록됩니다.

기존 사용자를 위한 마이그레이션 가이드

SQLite 전용 버전에서 업그레이드하시나요? 데이터는 안전합니다. SQLite 파일(./data/stats.db)은 완전히 보존됩니다. 다음은 권장되는 점진적 마이그레이션 경로입니다:

1단계: 이중 쓰기 (관찰 기간, 권장 시작점)```env

CH_ENABLED=1 CH_WRITE_ENABLED=1 STATS_QUERY_SOURCE=sqlite # Keep reading from SQLite while CH accumulates data

`[ClickHouse Writer]` 로그를 시작하고 확인하여 쓰기가 성공적으로 이루어지는지 검증합니다.

#### 2단계: 읽기 소스 전환```env
STATS_QUERY_SOURCE=auto        # Smart routing: recent data from CH, historical from SQLite
# or
STATS_QUERY_SOURCE=clickhouse  # Force all reads to ClickHouse

3단계(선택 사항): 과거 데이터 마이그레이션

과거 SQLite 통계를 ClickHouse로 이동하려면:```bash

Standard migration (truncate CH then re-import, with consistency check)

./scripts/ch-migrate-docker.sh

Append mode (keep existing CH data, incremental import)

./scripts/ch-migrate-docker.sh --append

Specific time window

./scripts/ch-migrate-docker.sh --from 2026-02-01T00:00:00Z --to 2026-02-20T00:00:00Z

#### 4단계(선택 사항): CH 전용 모드

ClickHouse가 안정적으로 실행되면 SQLite 통계 쓰기를 중지합니다:```env
CH_ONLY_MODE=1

CH_ONLY_MODE=1인 경우에도 ClickHouse가 비정상 상태가 되면 시스템이 자동으로 SQLite 쓰기로 폴백하므로 데이터 손실이 없습니다.

SQLite 전용으로 되돌리기

언제든지 완전히 롤백할 수 있습니다:```env CH_ENABLED=0 CH_WRITE_ENABLED=0 CH_ONLY_MODE=0 STATS_QUERY_SOURCE=sqlite

재시작하면 모든 것이 순수 SQLite 모드로 돌아갑니다. 기존 데이터는 그대로 유지됩니다.

---

## 🌐 리버스 프록시 및 터널

권장 방식: Web과 WS를 동일한 도메인 아래에 두고 경로 라우팅을 사용합니다:
`/` → `3000`, `/_cm_ws` → `3002`.

### Nginx 표준 예시```nginx
server {
  listen 443 ssl http2;
  server_name neko.example.com;

  location / {
    proxy_pass http://<neko-master-host>:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  location ^~ /_cm_ws {
    proxy_pass http://<neko-master-host>:3002;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
    proxy_buffering off;
  }
}

선택적 환경 변수 재정의:```env

Not required by default (already /_cm_ws)

NEXT_PUBLIC_WS_URL=/custom_ws

### Cloudflare Tunnel 표준 예제

`~/.cloudflared/config.yml`:```yaml
tunnel: <your-tunnel-name-or-id>
credentials-file: /path/to/<credentials>.json

ingress:
  - hostname: neko.example.com
    path: /_cm_ws*
    service: http://localhost:3002
  - hostname: neko.example.com
    path: /*
    service: http://localhost:3000
  - service: http_status:404

실행:```bash cloudflared tunnel --config ~/.cloudflared/config.yml run

Zero Trust 대시보드 관리형 라우트(토큰 모드)의 경우, 동일한 두 라우트를 구성하고 `/_cm_ws*`를 `/*` 위에 유지하세요.

### 주요 참고 사항

1. WS 경로로 `ws`(앞 슬래시 없음)를 사용하지 마세요. 과도하게 매칭되어 `/_next/static/...` → `426 Upgrade Required`를 유발할 수 있습니다
2. WS 라우트는 catch-all `/*` 위에 있어야 합니다
3. `NEXT_PUBLIC_WS_URL`은 기본적으로 선택 사항입니다. 사용자 지정하는 경우 변경 후 프런트엔드/컨테이너를 재시작하세요
4. `3000`만 매핑해도 작동하지만 HTTP 폴링(~5초)으로 폴백되어 실시간 응답성이 떨어집니다
5. `beacon.min.js` 실패(Cloudflare 분석 스크립트)는 일반적으로 앱 API/WS 데이터 흐름과 무관합니다
6. 대부분의 설정에서 추가 `/api` 리버스 프록시 규칙은 필요하지 않습니다. 프런트엔드는 동일 출처 `/api`를 사용하고 앱이 `3001`로의 내부 포워딩을 처리합니다

> 참고: `/_next/static/... 426 Upgrade Required`는 **잘못 구성된 리버스 프록시 / 터널** 설정에서 흔히 발생하며, 프록시 없는 직접 로컬 접속에서는 드뭅니다.

### 멀티 아키텍처 지원

Docker 이미지는 `linux/amd64`와 `linux/arm64`를 모두 지원합니다.

### 데이터 지속성

데이터는 컨테이너 내부의 `/app/data`에 저장됩니다. 데이터 손실을 방지하려면 호스트에 마운트하세요:```yaml
volumes:
  - ./data:/app/data

최신 버전으로 업데이트```bash

Pull the latest image and restart

docker compose pull docker compose up -d

## 🔐 인증 및 보안

Neko Master는 대시보드 데이터를 보호하기 위한 접근 인증을 지원합니다.

### 프로덕션 보안 기준

1. 고정된 `COOKIE_SECRET`을 설정하세요 (그렇지 않으면 재시작 후 세션이 무효화될 수 있습니다).
2. 정상 운영 중에는 `FORCE_ACCESS_CONTROL_OFF=true`를 활성화한 상태로 두지 마세요.
3. `SHOWCASE_SITE_MODE=true`는 공개 데모 환경에서만 사용하세요 (쓰기 작업이 제한됩니다).

예시:```env
COOKIE_SECRET=<at least 32-byte random string>
# FORCE_ACCESS_CONTROL_OFF=false
# SHOWCASE_SITE_MODE=false

인증 활성화 / 비활성화

1. 대시보드를 열고 왼쪽 하단 사이드바에서 "Settings"를 클릭합니다.
2. "Security" 탭으로 이동합니다.
3. 접근 제어를 활성화/비활성화하고 토큰을 설정합니다.

토큰 분실 (긴급 재설정)

토큰을 분실한 경우, 임시로 FORCE_ACCESS_CONTROL_OFF=true를 설정하여 긴급 모드로 진입합니다.

Docker Compose

1. docker-compose.yml에 다음을 추가합니다: ```yaml environment:
   • FORCE_ACCESS_CONTROL_OFF=true
   root@kitploit:~

2. 재시작: ```bash docker compose up -d
   root@kitploit:~

3. 대시보드를 열고 "Settings -> Security"에서 토큰을 재설정합니다.
4. 재설정 직후 이 환경 변수를 제거한 다음, 다시 재시작합니다.

Docker CLI

1. 컨테이너를 중지하고 제거합니다: ```bash docker stop neko-master docker rm neko-master
   root@kitploit:~

2. 비상 플래그를 사용하여 다시 실행합니다: ```bash docker run -d
   --name neko-master
   -p 3000:3000
   -v $(pwd)/data:/app/data
   -e FORCE_ACCESS_CONTROL_OFF=true
   foru17/neko-master:latest
   root@kitploit:~

3. 토큰을 재설정한 다음, 이 플래그를 제거하고 정상적으로 재시작하세요.

❓ FAQ

Q: 3000:3000만 노출해도 정상적으로 실행할 수 있나요?

A: 네. 핵심 기능은 여전히 작동합니다. WS가 라우팅되지 않으면 앱이 자동으로 HTTP 폴링으로 폴백합니다. 완전한 실시간 환경을 위해서는 /_cm_ws를 3002로 라우팅하세요.

Q: 포트 변경 후 포트 충돌이 발생하거나 접근할 수 없나요?

A: .env를 생성/업데이트하세요 (docker-compose.yml과 같은 디렉터리):```env WEB_EXTERNAL_PORT=8080 API_EXTERNAL_PORT=8081 WS_EXTERNAL_PORT=8082

그런 다음 재시작합니다:```bash
docker compose down
docker compose up -d

Q: 재시작 후 로그인/세션이 사라지는 이유는 무엇인가요?

A: 일반적으로 COOKIE_SECRET이 고정되어 있지 않거나 데이터 디렉터리가 영속화되지 않았기 때문입니다.

1. 고정된 COOKIE_SECRET을 설정하세요
2. ./data:/app/data를 마운트하세요

Q: 로컬 MMDB 조회에 필요한 파일은 무엇인가요?

A: 프로젝트 디렉터리(docker-compose.yml과 같은 레벨을 권장)에 ./geoip를 생성한 후 다음을 배치하세요:

1. GeoLite2-City.mmdb (필수)
2. GeoLite2-ASN.mmdb (필수)
3. GeoLite2-Country.mmdb (선택)

권장 소스: https://github.com/P3TERX/GeoLite.mmdb. 컨테이너 내부에서 고정 조회 경로는 /app/data/geoip이므로 다음을 유지하세요: ./geoip:/app/data/geoip:ro. 나중에 업데이트하려면 호스트의 ./geoip에 있는 파일만 교체하면 됩니다.

Q: OpenClash / 게이트웨이 연결에 실패하나요?

A: 확인하세요:

1. 게이트웨이 측에서 외부 제어가 활성화되어 있는지
2. 호스트/포트가 올바른지
3. 토큰/시크릿이 올바른지 (설정된 경우)
4. 컨테이너 네트워크가 게이트웨이에 도달할 수 있는지

Q: 데이터를 백업하고 복원하는 방법은 무엇인가요?

A: 먼저 백업하세요:```bash cp -r ./data ./data-backup-$(date +%Y%m%d)

복원:```bash
docker compose down
cp -r ./data-backup-YYYYMMDD/. ./data/
docker compose up -d

🏗️ 아키텍처 가이드

시스템 설계의 깊이를 빠르게 이해하고 싶다면 다음 순서로 읽어보세요:

1. 시스템 아키텍처 다이어그램: 엔드투엔드 계층 구조 및 모듈 책임 → docs/architecture.en.md
2. 데이터 흐름: Clash / Surge 수집 파이프라인 및 집계
3. 데이터 모델 및 저장소: SQLite 스키마, ClickHouse Buffer 테이블, 보존 정책
4. 실시간 채널 설계: RealtimeStore 병합 전략 및 WS 푸시
5. ClickHouse 모듈: 이중 쓰기 아키텍처, 헬스 폴백, 읽기 라우팅

전체 문서 색인: docs/README.md

이 문서는 수집, 집계, 캐싱, 실시간 푸시, 멀티 백엔드 관리의 핵심 설계를 다룹니다.

🤝 피드백 및 이슈

이 프로젝트는 GitHub Issue Templates (Bug / Feature / Support)를 사용합니다.

최소한 다음 내용을 포함해 주세요:

1. 배포 방식 (Compose / Docker Run / Source)
2. 버전 정보 (이미지 태그 또는 커밋)
3. 주요 환경 변수 (마스킹 처리, 예: COOKIE_SECRET=***)
4. 재현 단계 및 예상 동작과 실제 동작
5. 주요 로그 (docker logs, 브라우저 콘솔, 네트워크 오류)

📁 프로젝트 구조```

neko-master/ ├── docker-compose.yml # Docker Compose config ├── Dockerfile # Docker image build ├── setup.sh # One-click setup script ├── docker-start.sh # Docker container startup script ├── start.sh # Source code dev startup script ├── docs/ # Documentation (see docs/README.md) │ ├── README.md # Documentation index (English default) │ ├── README.zh.md # Documentation index (Chinese) │ ├── README.en.md # Documentation index (English mirror) │ ├── architecture.md # System architecture (Chinese) │ ├── architecture.en.md # System architecture (English) │ ├── release-checklist.md │ ├── agent/ # Agent docs (bilingual) │ │ ├── overview.md / overview.en.md │ │ ├── quick-start.md / quick-start.en.md │ │ ├── install.md / install.en.md │ │ ├── config.md / config.en.md │ │ ├── release.md / release.en.md │ │ └── troubleshooting.md / troubleshooting.en.md │ ├── research/ # Research reports │ └── dev/ # Internal development docs ├── assets/ # Screenshots and icons ├── apps/ │ ├── collector/ # Data collection service (Node.js + WebSocket) │ ├── agent/ # Agent daemon (Go) │ └── web/ # Next.js frontend app └── packages/ └── shared/ # Shared types and utilities

## 🛠️ 기술 스택

- **프론트엔드**: [Next.js 16](https://nextjs.org/) + [React 19](https://react.dev/) + [TypeScript](https://www.typescriptlang.org/)
- **스타일링**: [Tailwind CSS](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/)
- **차트**: [Recharts](https://recharts.org/)
- **i18n**: [next-intl](https://next-intl-docs.vercel.app/)
- **백엔드**: [Node.js](https://nodejs.org/) + [Fastify](https://www.fastify.io/) + WebSocket
- **데이터베이스**: [SQLite](https://www.sqlite.org/) ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) + [ClickHouse](https://clickhouse.com/) (선택 사항)
- **빌드**: [pnpm](https://pnpm.io/) + [Turborepo](https://turbo.build/)

## 🤝 기여하기

기여를 환영합니다!

- 🐛 [버그 제보](https://github.com/foru17/neko-master/issues/new)
- 💡 [기능 요청](https://github.com/foru17/neko-master/issues/new)
- 🔧 [코드 기여](https://github.com/foru17/neko-master/pulls)

PR을 열기 전에 [CONTRIBUTING.md](https://github.com/foru17/neko-master/blob/main/CONTRIBUTING.md)를 읽어보세요 (워크플로, 검사, i18n/다크 모드 요구 사항).

**AI 코딩 도구로 개발 중이신가요?** (Claude Code, Copilot, Cursor, Codex, ...) [AGENTS.md](https://github.com/foru17/neko-master/blob/main/AGENTS.md) — 컨벤션, 핵심 계약, 프로젝트 맵 — 와 [`.claude/skills/`](https://github.com/foru17/neko-master/blob/main/.claude/skills)의 작업별 워크플로 가이드를 참고하세요. Claude Code는 두 가지를 자동으로 인식합니다.

## 📄 라이선스

[MIT](https://github.com/foru17/neko-master/blob/main/LICENSE) © [foru17](https://github.com/foru17)

---

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=foru17/neko-master&type=date&legend=top-left)](https://www.star-history.com/#foru17/neko-master&type=date&legend=top-left)

---

<p align="center">
  <sub>Made with ❤️ by <a href="https://github.com/foru17">@foru17</a></sub><br>
  <sub>이 프로젝트가 도움이 되셨다면 ⭐을 눌러주세요</sub>
</p>