h4ks-com/hanna

TLS를 통해 연결되며 원격 제어를 위한 보안 토큰 인증 기반의 REST API를 제공하는 견고하고 독립적인 Go 기반 IRC 봇입니다. 자동화, 모니터링 및 기타 서비스와의 통합에 완벽합니다.

보안 IRC 연결: 선택적인 서버 비밀번호 지원을 포함한 TLS 활성화 IRC 연결
SASL 인증: SASL PLAIN 인증이 필요한 IRC 네트워크를 위한 선택적 SASL 인증
자동 재연결: 최대 가동 시간을 위한 지수 백오프 (Exponential Backoff) 기반의 지능형 재연결
REST API: 완전한 봇 제어를 위한 토큰 보호 HTTP/HTTPS 엔드포인트
IRC 네트워크 탐색: LIST 및 WHOIS 명령어를 통한 채널 목록 확인 및 사용자 정보 획득
유연한 이벤트 시스템: 다양한 IRC 이벤트(멘션, 입장, 퇴장, 모드 변경 등)를 지원하는 고급 트리거 시스템
n8n 통합: 액션(Action) 및 트리거(Trigger) 노드를 모두 포함한 포괄적인 n8n 노드 패키지
다중 웹훅 (Multiple Webhooks): 필터링 및 인증을 지원하는 다중 트리거 엔드포인트 지원
채널 관리: 프로그래밍 방식으로 채널 입장, 퇴장 및 추적
메시지 제어: API를 통한 메시지, 공지(Notice) 및 로우(Raw) IRC 명령어 전송
우아한 종료 (Graceful Shutdown): 깔끔한 연결 해제 및 리소스 정리
의존성 없음 (Zero Dependencies): 외부 의존성이 없는 독립형 바이너리
프로덕션 준비 완료: 포괄적인 로깅, 에러 처리 및 모니터링 엔드포인트

• Go 1.24 이상
• TLS를 지원하는 IRC 서버
• (선택 사항) HTTPS API를 위한 TLS 인증서

# 저장소 클론
git clone https://github.com/h4ks-com/hanna
cd hanna
...

# Docker를 사용하여 빌드
docker build -t hanna-bot .
# 또는 docker-compose 사용
...

이 프로젝트는 적절한 Go 모듈로 구성되어 있습니다:

hanna/
├── main.go # 메인 애플리케이션 진입점
├── irc/ # IRC 클라이언트 패키지
...

# HTTP API를 사용한 기본 설정
API_TOKEN=your_secret_token \
IRC_ADDR=irc.libera.chat:6697 \
...

모든 설정은 환경 변수(Environment Variables)를 통해 이루어집니다:

변수 (Variable)	설명 (Description)	기본값 (Default)	필수 (Required)
IRC_ADDR
IRC 서버 주소 (host:port)	-	✅
IRC_TLS
TLS 연결 활성화	1	❌
IRC_TLS_INSECURE
TLS 인증서 검증 건너뛰기	0	❌
IRC_PASS
서버 비밀번호	-	❌
IRC_NICK
봇 닉네임 (Nickname)	goircbot	❌
IRC_USER
사용자 이름/ident (Username/ident)	goircbot	❌
IRC_NAME
실명/GECOS (Real name/GECOS)	Go IRC Bot	❌
SASL_USER
SASL 인증 사용자 이름	-	❌
SASL_PASS
SASL 인증 비밀번호	-	❌
AUTOJOIN
자동 참여할 채널 (쉼표로 구분)	-	❌

변수 (Variable)	설명 (Description)	기본값 (Default)	필수 (Required)
API_ADDR
HTTP/HTTPS 리슨 주소 (Listen address)	:8080	❌
API_TOKEN
API 인증을 위한 Bearer 토큰	-
API_TLS
HTTPS 활성화	0	❌
API_CERT
TLS 인증서 파일 경로	-
API_KEY
TLS 개인 키 (Private key) 파일 경로	-

변수 (Variable)	설명 (Description)	기본값 (Default)	필수 (Required)
N8N_WEBHOOK
채팅 통합을 위한 레거시 (Legacy) 웹훅 URL	-	❌
TRIGGER_CONFIG
다중 트리거 엔드포인트를 위한 JSON 설정	-	❌

이 봇은 IRC 이벤트를 여러 엔드포인트로 전송하기 위한 유연한 트리거 시스템을 지원합니다:

레거시 모드 (Legacy Mode, 하위 호환):

export N8N_WEBHOOK="https://n8n.example.com/webhook/irc-bot"

고급 모드 (Advanced Mode, 권장):

export TRIGGER_CONFIG='{
"endpoints": {
"mentions": {
...

지원되는 이벤트 유형 (Supported Event Types):

mention

• 봇이 언급되었을 때

privmsg

• 모든 채널/개인 메시지

join

• 사용자가 채널에 참여할 때

part

• 사용자가 채널을 떠날 때

quit

• 사용자가 IRC를 종료할 때

kick

• 사용자가 채널에서 킥(Kick) 당했을 때

mode

• 모드 변경 (op, voice 등)

nick

• 닉네임 변경

topic

• 채널 토픽 변경

notice

• IRC notice

*API_TLS=1일 때 필수

도메인에 대한 Let's Encrypt 인증서가 있는 경우:

export API_TLS=1
export API_CERT=/etc/letsencrypt/live/yourdomain.com/fullchain.pem
export API_KEY=/etc/letsencrypt/live/yourdomain.com/privkey.pem

# 자체 서명 인증서 생성 (Generate self-signed certificate)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
# 봇과 함께 사용 (Use with bot)
...

모든 API 엔드포인트 (/health 제외)는 Bearer 토큰을 필요로 합니다:

curl -H "Authorization: Bearer your_secret_token" https://your-server:8080/api/state

GET /health

봇의 연결 상태와 현재 닉네임을 반환합니다.

응답 (Response):

{
"ok": true,
"nick": "YourBot"
...

GET /api/state
Authorization: Bearer <token>

연결된 채널을 포함한 종합적인 봇 상태를 반환합니다.

응답 (Response):

{
"connected": true,
"nick": "YourBot",
...

POST /api/join
Authorization: Bearer <token>
Content-Type: application/json
...

POST /api/part
Authorization: Bearer <token>
Content-Type: application/json
...

POST /api/send
Authorization: Bearer <token>
Content-Type: application/json
...

POST /api/notice
Authorization: Bearer <token>
Content-Type: application/json
...

POST /api/nick
Authorization: Bearer <token>
Content-Type: application/json
...

POST /api/raw
Authorization: Bearer <token>
Content-Type: application/json
...

GET /api/list
Authorization: Bearer <token>

응답 (Response):

{
"channels": [
{
...

POST /api/whois
Authorization: Bearer <token>
Content-Type: application/json
...

응답 (Response):

{
"nick": "username",
"user": "user",
...

#!/bin/bash
# HTTPS 및 고급 n8n 트리거 연동을 포함한 운영 환경 설정 (Production setup with HTTPS and advanced n8n trigger integration)
export API_TOKEN="$(openssl rand -hex 32)"
...

이 봇은 기존의 웹훅 (webhooks)과 새로운 트리거 (trigger) 시스템 모두를 통해 n8n과의 포괄적인 연동을 제공합니다.

IRC에서 누군가가 @botname message와 같이 봇을 언급하면, 봇은 자동으로 구성된 n8n 웹훅을 호출합니다:

{
"eventType": "mention",
"sender": "username",
...

새로운 트리거 시스템은 여러 IRC 이벤트와 엔드포인트를 지원합니다:

1. n8n 노드 패키지 설치 (Install the n8n Node Package)

# n8n 설치 경로에서 (In your n8n installation)
npm install n8n-nodes-hanna

2. 트리거 워크플로우 생성 (Create Trigger Workflows)

• 워크플로우에 "Hanna Bot Trigger" 노드를 추가합니다.
• 인증 토큰 (authentication tokens) 및 이벤트 필터 (event filters)를 설정합니다.
• 웹훅 URL (webhook URLs)을 TRIGGER_CONFIG에 복사합니다.

3. 이벤트 예시 (Event Examples):

사용자가 채널에 참여할 때 (User Joins Channel):

{
"eventType": "join",
"sender": "newuser",
...

채널 모드 변경 시 (Channel Mode Change):

{
"eventType": "mode",
"sender": "operator",
...

개인 메시지 (Private Message):

{
"eventType": "privmsg",
"sender": "user123",
...

새로운 트리거 노드 사용 (권장) (Using the New Trigger Node (Recommended)):

• n8n 인스턴스에 n8n-nodes-hanna 패키지를 설치합니다.
• n8n에서 새로운 워크플로우를 생성합니다.
• "Hanna Bot Trigger" 노드를 추가합니다.
• 다음을 설정합니다:
  • 인증 토큰 (Authentication token) (안전한 무작위 토큰을 생성하세요)
  • 모니터링할 이벤트 선택 (mention, join, part 등)
  • 선택 사항: 채널 또는 사용자로 필터링
• 트리거 노드에서 웹훅 URL을 복사합니다.
• URL과 토큰을 봇의 TRIGGER_CONFIG에 추가합니다.
• 처리 노드 (OpenAI, 데이터베이스, 알림 등)를 추가합니다.
• 선택 사항: IRC로 응답을 다시 보내기 위해 "Hanna Bot" 액션 노드를 추가합니다.

레거시 웹훅 사용 (Using Legacy Webhook):

• n8n에서 새로운 워크플로우를 생성합니다.
• "Webhook" 트리거 노드를 추가합니다.
• N8N_WEBHOOK 환경 변수에 웹훅 URL을 설정합니다.
• 들어오는 IRC 데이터를 처리하고 필요에 따라 응답합니다.
• 선택 사항: Hanna API를 사용하여 IRC로 응답을 다시 보냅니다.

AI 기반 채팅 봇 (AI-Powered Chat Bot):

Hanna Bot Trigger (mention 이벤트)
→ OpenAI Chat Completion
→ Hanna Bot Send Message

채널 중재 (Channel Moderation):

Hanna Bot Trigger (kick, mode 이벤트)
→ 데이터베이스에 로그 기록
→ 스팸 감지 시 알림 전송
...

환영 시스템 (Welcome System):

Hanna Bot Trigger (join 이벤트)
→ 사용자 데이터베이스 확인
→ 신규 사용자를 위한 환영 메시지 전송
...

멀티 채널 봇 (Multi-Channel Bot):

트리거 1: 지원 채널 (mention, #support 내의 privmsg)
→ 지원 AI로 라우팅
→ 지원 티켓 로그 기록
...

멘션 예시 (Mention Examples):

@MyAwesomeBot 날씨가 어때?

→ mention 이벤트 트리거

@MyAwesomeBot help

→ mention 이벤트 트리거

MyAwesomeBot hello

→ mention (멘션)을 트리거하지 않음 (@ 누락)
@DifferentBot hello

→ mention (멘션)을 트리거하지 않음 (잘못된 봇 이름)

기타 이벤트 예시:

• 사용자가 채널에 참여
  #general

→ join (참여) 이벤트 트리거 - 사용자가 #general에서 입력
hello everyone

→ privmsg (개인 메시지) 이벤트 트리거 - 운영자가 사용자에게 음성 권한 부여 → mode (모드) 이벤트 트리거

• 사용자가 채널에서 킥(kick)됨 → kick (킥) 이벤트 트리거

# 채널에 메시지 전송
curl -X POST \
-H "Authorization: Bearer your_secret_token" \
...

import requests
import json
class IRCBotAPI:
...

#!/bin/bash
BOT_URL="https://bot.example.com"
BOT_TOKEN="your_secret_token"
...

Hanna를 실행하는 가장 쉬운 방법은 포함된 설정을 사용하여 Docker Compose를 사용하는 것입니다:

환경 변수 템플릿 복사:
cp .env.example .env

봇 설정:
.env 파일을 편집하고 최소한 다음 항목을 설정하세요:
IRC_ADDR=irc.libera.chat:6697 IRC_NICK=YourBotName API_TOKEN=your-secure-token-here AUTOJOIN=#your-channels

서비스 시작:
docker compose up -d

이렇게 하면 Hanna IRC 봇과 워크플로우 자동화를 위한 n8n이 모두 시작됩니다. 봇은 http://localhost:8080에서, n8n은 http://localhost:5678에서 사용할 수 있습니다.

포함된 compose.yaml은 다음을 제공합니다:

Hanna IRC Bot: API를 갖춘 메인 봇 서비스
n8n: 채팅 처리를 위한 워크플로우 자동화 플랫폼
n8n Workflow Loader: 시작 시 워크플로우를 자동으로 로드하는 사이드카 (Sidecar) 컨테이너
자동 네트워킹 (Automatic networking): 봇이 http://n8n:5678을 통해 n8n과 통신 가능
지속성 저장소 (Persistent storage): n8n 워크플로우 및 데이터 보존
환경 변수 기반 설정 (Environment-based config): .env 파일의 모든 설정 적용

Docker Compose 설정에는 워크플로우를 n8n으로 자동 가져오는 워크플로우 로더 (workflow loader)가 포함되어 있습니다:

기본 Echo Bot: IRC 메시지를 에코 (echo)하는 사전 구성된 워크플로우
자동 가져오기 (Auto-Import): n8n-workflow-loader/workflows/에 있는 워크플로우가 시작 시 로드됨
기존 항목 건너뛰기 (Skip Existing): 이미 가져온 워크플로우는 감지되어 건너뜀
자동 활성화 (Auto-Activation): 가져온 워크플로우가 자동으로 활성화됨
트리거 통합 (Trigger Integration): 봇의 TRIGGER_CONFIG

자동으로 구성됩니다.

커스텀 워크플로우 추가 (Adding Custom Workflows):

• 워크플로우 JSON 파일을 n8n-workflow-loader/workflows/ 디렉토리에 배치합니다.

• 워크플로우 JSON에서 id 필드를 제거합니다. 그 후 docker-compose up -d 명령어로 재시작합니다.

워크플로우 로더 (Workflow loader)는 n8n REST API를 사용하며, 에러 처리 (Error handling) 및 중복 탐지 (Duplicate detection) 기능을 포함합니다.

수동으로 빌드 및 실행하는 것을 선호하는 경우:

# 이미지 빌드
docker build -t hanna-bot .
# 환경 변수와 함께 실행
...

/etc/systemd/system/hanna.service 파일을 생성합니다:

[Unit]
Description=Hanna IRC Bot
After=network.target
...

환경 변수 파일 /opt/hanna/.env:

API_TOKEN=your_secret_token
API_TLS=1
API_CERT=/etc/letsencrypt/live/bot.example.com/fullchain.pem
...

활성화 및 시작:

sudo systemctl enable hanna
sudo systemctl start hanna
sudo systemctl status hanna

/health 엔드포인트 (Endpoint)는 봇 상태를 모니터링하는 간단한 방법을 제공합니다:

# 봇이 연결되어 있는지 확인
curl -f https://bot.example.com/health || echo "Bot is down!"

포괄적인 모니터링을 위해 Prometheus 메트릭 (Metrics)을 사용하여 봇을 확장하는 것을 고려해 보세요.

API 토큰 (API Token): 강력하고 무작위로 생성된 토큰을 사용하세요. HTTPS: 프로덕션 환경에서는 항상 HTTPS를 사용하세요. 방화벽 (Firewall): API 액세스를 신뢰할 수 있는 네트워크로 제한하세요. 파일 권한 (File Permissions): 인증서 파일을 보호하세요 (0600 권한). 정기 업데이트 (Regular Updates): 종속성 (Dependencies) 및 인증서를 최신 상태로 유지하세요.

Hanna에는 완전한 IRC 자동화를 위해 액션 노드 (Action nodes)와 트리거 노드 (Trigger nodes)를 모두 제공하는 포괄적인 n8n 노드 패키지 (n8n-nodes-hanna)가 포함되어 있습니다.

# n8n 인스턴스에 설치
npm install n8n-nodes-hanna
# 또는 전역(Global) 설치
...

• IRC 채널로 메시지 및 공지 전송

• 프로그래밍 방식으로 채널 참여 (Join) 및 퇴장 (Part)

• 봇 닉네임 변경

• 로우 (Raw) IRC 명령 전송

• 봇 상태 및 연결된 채널 정보 가져오기

• IRC 이벤트를 위한 웹훅 (Webhook) 기반 트리거

• 설정 가능한 이벤트 필터링 (멘션, 참여, 퇴장 등)

• 채널 및 사용자 필터링

• 인증 토큰 검증

• 다중 동시 트리거 지원

• 워크플로우에 "Hanna Bot" 노드 추가

• 인증 정보 (Credentials) 설정:

• API URL:
  https://your-bot.example.com

• API Token: 봇의 API 토큰

• API URL:

• 작업 (Operation) 선택 (메시지 전송 (Send Message), 채널 참여 (Join Channel) 등)

• 대상 및 메시지 파라미터 (Parameters) 설정

• 워크플로우에 "Hanna Bot Trigger" 노드 추가

• 인증 토큰 (Authentication Token) 설정 (보안을 위한 무작위 문자열)

• 모니터링할 IRC 이벤트 선택

• 선택 사항: 채널/사용자 필터 설정

• 웹훅 (Webhook) URL을 봇의 TRIGGER_CONFIG에 복사

트리거 (Trigger) 노드와 액션 (Action) 노드를 모두 사용하는 전체 워크플로우 설정은 위의 고급 워크플로우 예시 (Advanced Workflow Examples) 섹션을 참조하세요.

# 모든 테스트 실행
go test -v