Systemd on Yarang's Tech Lair

NATS JetStream으로 멀티-LLM 분산 오케스트레이터 구축하기

Fri, 08 May 2026 21:57:11 +0900

1편에서는 Claude, ZAI, Codex, Gemini 네 가지 AI를 같은 태스크에 동시에 돌리면서 발견한 모델별 제한 사항을 다뤘다. 이번 편은 “어떻게 그게 가능하도록 만들었나”—시스템 설계와 구현 이야기다.

시스템 개요

AgentForge는 세 가지 요소로 이루어진다.

[태스크 발행자]
 │ NATS JetStream publish
 ▼
[NATS 브로커] ─── af.worker.{id}.inbox
 │ JetStream consume (워커별 독립 스트림)
 ▼
[워커 폴러] × N (poller.py × 18개)
 │ LLM CLI 실행 (claude / codex / gemini)
 ▼
[결과 반환] af.task.{task_id}.completed

발행자가 NATS에 태스크를 올리면, 각 워커가 독립적으로 구독하고 있다가 자신의 inbox로 들어온 메시지를 받아 LLM CLI를 실행한다. 결과는 완료 주제로 다시 publish된다.

왜 NATS JetStream인가

메시지 브로커 선택지는 여러 개였다: Redis Streams, Kafka, RabbitMQ, NATS JetStream.

NATS JetStream을 선택한 이유:

단일 바이너리 — 별도의 런타임 없이 nats-server 하나로 동작한다. Kafka의 ZooKeeper나 RabbitMQ의 Erlang/OTP 의존성이 없다.
내장 영속성 — JetStream은 NATS 위에 올라가는 스트리밍 레이어로, 메시지를 파일시스템에 저장한다. 워커가 재시작되어도 처리 안 된 태스크가 유실되지 않는다.
NKey 기반 인증 — 워커별로 독립된 Ed25519 keypair를 발급할 수 있다. 한 워커가 침해되어도 다른 워커의 자격증명은 유효하다.
경량 — 단일 서버에서 메모리 사용량 ~30MB. 18개 워커를 연결해도 브로커 부하가 거의 없다.

핵심: poller.py의 백엔드 어댑터

워커의 핵심은 poller.py다. 이 파일 하나가 NATS 구독, LLM CLI 실행, 결과 반환을 모두 담당한다.

LLM별 실행 방식이 다르기 때문에, 백엔드 어댑터 딕셔너리로 분리했다.

_BACKENDS: dict[str, dict] = {
 "claude": {
 "bin": os.environ.get("CLAUDE_BIN", "/usr/local/bin/claude"),
 "tools": os.environ.get("ALLOWED_TOOLS", "Read,Edit,Write,Glob,Grep"),
 "model": os.environ.get("CLAUDE_MODEL", ""),
 },
 "codex": {
 "bin": os.environ.get("CODEX_BIN", "/usr/bin/codex"),
 "model": os.environ.get("CODEX_MODEL", ""),
 "sandbox": os.environ.get("CODEX_SANDBOX", "read-only"),
 },
 "gemini_cli": {
 "bin": os.environ.get("GEMINI_BIN", "/usr/bin/gemini"),
 "model": os.environ.get("GEMINI_MODEL", ""),
 },
}

MODEL_BACKEND 환경변수로 어떤 LLM을 쓸지 결정한다. 덕분에 동일한 poller.py 코드로 18개 워커가 각자 다른 LLM을 실행한다.

Claude 백엔드

async def run_claude(instructions: str, task_id: str) -> tuple[int, str]:
 cfg = _BACKENDS["claude"]
 cmd = [cfg["bin"], "--print", "--allowedTools", cfg["tools"]]
 if cfg.get("model"):
 cmd += ["--model", cfg["model"]]
 proc = await asyncio.create_subprocess_exec(*cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)

--print 플래그가 핵심이다. Claude Code가 대화 모드가 아닌 비대화형 모드로 실행되어 stdout으로 결과를 반환하게 만든다.

ZAI 백엔드

ZAI는 Anthropic API 호환 엔드포인트를 제공하기 때문에 별도 백엔드가 없다. 환경변수 두 개로 라우팅을 바꾼다.

# /etc/agentforge/cc-zai-high-dev-01.env
ANTHROPIC_BASE_URL=<ZAI endpoint>
ANTHROPIC_AUTH_TOKEN=<ZAI API key>

systemd EnvironmentFile= 지시어로 이 파일을 주입하면, claude 바이너리가 ZAI 엔드포인트로 요청을 보낸다. 코드 변경 없이 환경변수만으로 다른 LLM 공급자를 연결하는 셈이다.

선언적 관리: fleet.yaml × servers.yaml

18개 워커를 수동으로 관리하는 건 비현실적이다. 두 개의 YAML 파일로 전체 인프라를 선언적으로 정의했다.

servers.yaml — 서버 인벤토리

servers:
 - name: worker-node-1
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

 - name: broker-host
 role: broker-host
 services: [nats-jetstream, postgres]

 - name: worker-node-2
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

fleet.yaml — 워커 배치

workers:
 - worker_id: cc-go-dev-01
 llm: claude-code
 model: claude-sonnet-4-6
 lang: go
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: true

 - worker_id: codex-py-dev-01
 llm: codex
 model: gpt-5.5
 lang: python
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

host 필드 하나를 바꾸면 워커가 다른 서버로 이동한다. enabled: false로 설정하면 배포 스크립트가 해당 워커를 중지한다.

워커 템플릿 시스템: provision_worker.py

워커를 새로 추가할 때마다 systemd 유닛 파일을 직접 작성하는 건 오류가 생기기 쉽다. Jinja2 템플릿 + 프로비저닝 스크립트로 자동화했다.

템플릿 구조

templates/
 systemd/
 claude.service.j2 # claude-code, ZAI 공용
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

claude.service.j2의 핵심 부분:

Environment=MODEL_BACKEND=claude
Environment=CLAUDE_BIN={{ claude_bin }}
{% if claude_model %}
Environment=CLAUDE_MODEL={{ claude_model }}
{% endif %}
{% if env_file %}
EnvironmentFile={{ env_file }}
{% endif %}
Environment=WORK_BASE={{ work_base }}
Environment=WORK_DIR={{ work_base }}/repo
Environment="{{ 'ALLOWED_TOOLS=' + allowed_tools }}"
Environment=CREATE_PR={{ 'true' if create_pr else 'false' }}
{% if create_pr and github_remote %}
Environment=GITHUB_REMOTE={{ github_remote }}
{% endif %}

ZAI 워커는 env_file 블록이 활성화되어 EnvironmentFile이 추가된다. PR 생성 워커는 github_remote가 주입된다. 나머지는 기본값을 쓴다.

provision_worker.py 사용법

# 미리보기 (실제 배포 없음)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# 실제 배포 (NATS creds 발급 포함)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# fleet.yaml 전체 일괄 배포
python3 scripts/provision_worker.py --all

내부적으로 수행하는 작업:

fleet.yaml에서 워커 항목 읽기
servers.yaml에서 대상 호스트 읽기
Jinja2 템플릿 렌더링
SSH로 /etc/systemd/system/{worker_id}-poller.service 배포
워크 디렉터리 생성
systemctl daemon-reload && enable --now
(선택) nsc add user로 NATS NKey 발급 → creds 배포 → auth.conf 재생성

분산 호스트: 두 번째 서버에 워커 추가

모든 워커를 한 서버에서 돌리면 단일 장애점이 된다. 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커에 연결하는 방법은 autossh 터널이다.

[Unit]
Description=NATS 브로커 터널
After=network-online.target

[Service]
ExecStart=/usr/bin/autossh -N \
 -L 4222:127.0.0.1:4222 \
 -i /home/ubuntu/.ssh/id_ed25519 \
 broker-host
Restart=always
RestartSec=10

이 설정이 활성화된 상태에서 워커는 항상 nats://127.0.0.1:4222로 연결한다. 브로커 호스트 주소를 몰라도 된다. 터널만 살아있으면 어느 호스트에서든 동일하게 동작한다.

NATS 자격증명 운영 경험

구현 중 가장 복잡했던 부분은 NATS NKey 관리다.

NATS JetStream의 인증 구조는 계층적이다.

Operator (최상위 서명 기관)
 └── Account: SYS (시스템 계정)
 └── Account: Services (워커 계정)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

각 워커는 독립된 User NKey를 가지고, Services 계정의 권한 범위(af.>, _INBOX.>, $JS.>) 내에서만 publish/subscribe할 수 있다.

신규 워커를 추가할 때 Operator의 signing key가 필요하다. 초기에 이 키의 백업을 만들지 않았다가 분실하는 사고가 있었다. 결과적으로 Operator를 전부 재생성하고 모든 워커의 creds를 일괄 교체했다. 서비스 다운타임은 약 60초.

# 재생성 절차
nsc add operator AgentForge
nsc add account SYS
nsc add account Services
for worker in cc-dev-01 cc-go-dev-01 ...; do
 nsc add user --account Services --name $worker \
 --allow-pub "af.>,_INBOX.>,$JS.>" \
 --allow-sub "af.>,_INBOX.>,$JS.>"
done
nsc generate config --mem-resolver --sys-account SYS > auth.new.conf

새 워커 추가: 전체 절차

이 시스템이 완성된 이후 새 워커를 추가하는 절차는 단순하다.

1단계: fleet.yaml에 항목 추가

- worker_id: my-new-worker
 llm: claude-code
 model: claude-haiku-4-5
 lang: multi
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

2단계: 미리보기

python3 scripts/provision_worker.py --worker my-new-worker --dry-run

3단계: 실제 배포

python3 scripts/provision_worker.py --worker my-new-worker --issue-creds

끝이다. 템플릿 렌더링, SSH 배포, NATS 자격증명 발급, 서비스 등록까지 한 명령으로 처리된다.

다음 단계

현재 시스템은 워커가 태스크를 독립적으로 처리하는 구조다. 앞으로 만들고 싶은 것:

라우팅 정책: 태스크 특성에 따라 적합한 워커를 자동 선택 (Go 코드 → claude-go-dev, 비용 최우선 → ZAI 경량 티어)
결과 비교 대시보드: fan-out 결과를 나란히 보여주는 UI
비용 추적: 워커별 API 호출 비용 집계

코드는 GitHub에 공개되어 있다.

블로그 AI 자동 댓글 시스템 구축기 (3/3) — 배포와 트러블슈팅

Sun, 03 May 2026 01:20:00 +0900

개요

1부에서 아키텍처와 구현을, 2부에서 보안 강화를 다뤘습니다. 이번 3부에서는 실제 OCI ARM 서버에 배포하고 겪은 트러블슈팅 과정을 기록합니다.

특히 GITHUB_TOKEN이 로드되지 않는 문제를 4단계에 걸쳐 추적하고 해결한 실제 디버깅 과정을 상세히 공유합니다. “설정했는데 왜 안 되지?“라는 상황에서 어떻게 원인을 좁혀나갔는지가 이 글의 핵심입니다.

인프라 구성

서버 구성

서버	역할	스펙
ec1 (x86)	웹 서버 (nginx, Hugo 블로그)	OCI
arm1 (ARM)	워커 서버 (Flask, Claude Code)	OCI ARM

블로그는 ec1에서 Hugo로 빌드·서빙하고, AI 댓글 워커는 arm1에서 실행합니다. GitHub Webhook은 arm1으로 직접 전달됩니다.

워커 서버 디렉토리 구조

/var/www/auto-comment-worker/ # 애플리케이션
├── scripts/
│ └── auto-comment-worker.py
├── deploy/
│ └── auto-comment-worker.service
├── venv/ # Python 가상환경
└── logs/

/etc/auto-comment-worker/ # 인증 정보
├── github-token # 640, ubuntu:ubuntu
└── credentials/
 └── webhook-secret # 600, ubuntu:ubuntu

/home/ubuntu/.local/bin/claude # Claude Code CLI

systemd 서비스 구성

서비스 파일

[Unit]
Description=Auto Comment Worker for Blog
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/var/www/auto-comment-worker
Environment=PORT=8081
Environment=CLAUDE_CODE_PATH=/home/ubuntu/.local/bin/claude
Environment=BLOG_OWNERS=yarang
Environment=GITHUB_TOKEN_FILE=/etc/auto-comment-worker/github-token
Environment=GITHUB_WEBHOOK_SECRET_FILE=/etc/auto-comment-worker/credentials/webhook-secret
ExecStart=/var/www/auto-comment-worker/venv/bin/python /var/www/auto-comment-worker/scripts/auto-comment-worker.py
Restart=always
RestartSec=10

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=auto-comment-worker

# Security
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=false
ReadWritePaths=/var/www/auto-comment-worker /var/log/auto-comment-worker
ReadOnlyPaths=

# 리소스 제한
MemoryMax=512M
CPUQuota=50%
TasksMax=100

[Install]
WantedBy=multi-user.target

주요 설정 해설

Type=simple: Flask 워커는 포그라운드에서 실행되므로 simple이 적합합니다. forking은 데몬화하는 프로세스에 사용합니다.

User=ubuntu: 전용 서비스 계정을 만들 수도 있지만, Claude Code CLI가 ubuntu 사용자의 홈 디렉토리 설정에 의존하므로 ubuntu로 실행합니다.

ProtectHome=false: 보통은 true로 설정하지만, Claude Code가 ~/.agent_forge_for_zai.json 설정 파일을 필요로 하므로 홈 디렉토리 접근을 허용합니다.

ReadOnlyPaths= (빈 값): 초기에 /etc/auto-comment-worker를 지정했지만, ProtectSystem=strict와 충돌하여 비워두었습니다.

서비스 관리 명령어

# 서비스 파일 복사
sudo cp deploy/auto-comment-worker.service /etc/systemd/system/

# 서비스 등록 및 시작
sudo systemctl daemon-reload
sudo systemctl enable auto-comment-worker
sudo systemctl start auto-comment-worker

# 상태 확인
sudo systemctl status auto-comment-worker

# 로그 확인 (실시간)
sudo journalctl -u auto-comment-worker -f

# 최근 로그 확인
sudo journalctl -u auto-comment-worker --since "10 minutes ago"

nginx 리버스 프록시

Webhook 엔드포인트 설정

server {
 listen 443 ssl;
 server_name your-domain.com;

 # SSL 설정
 ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

 # Webhook 프록시
 location /webhook {
 proxy_pass http://localhost:8081;
 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;

 # GitHub Webhook 시그니처 헤더 포워딩 (필수!)
 proxy_set_header X-Hub-Signature-256 $http_x_hub_signature_256;

 # 타임아웃 (Claude Code 응답 대기)
 proxy_read_timeout 120s;
 proxy_connect_timeout 10s;
 }

 # Health check
 location /health {
 proxy_pass http://localhost:8081;
 }
}

proxy_read_timeout 120s는 Claude Code CLI가 AI 응답을 생성하는 데 최대 60초가 걸릴 수 있으므로 여유 있게 설정합니다. GitHub Webhook의 기본 타임아웃은 10초이므로, 실제로는 비동기 처리를 고려할 수 있습니다.

배포 과정

수동 배포 (rsync 실패 후)

초기에는 rsync로 배포를 시도했지만, 서버에 대상 디렉토리가 없어 실패했습니다:

rsync: [Receiver] mkdir "/var/www/auto-comment-worker/scripts" failed:
No such file or directory

대안으로 scp 기반 수동 배포를 진행했습니다:

# 1. 서버에 디렉토리 생성
ssh ubuntu@arm1 "sudo mkdir -p /var/www/auto-comment-worker/scripts"
ssh ubuntu@arm1 "sudo chown -R ubuntu:ubuntu /var/www/auto-comment-worker"

# 2. 파일 전송
scp scripts/auto-comment-worker.py ubuntu@arm1:/var/www/auto-comment-worker/scripts/
scp deploy/auto-comment-worker.service ubuntu@arm1:/tmp/

# 3. 서비스 파일 설치
ssh ubuntu@arm1 "sudo cp /tmp/auto-comment-worker.service /etc/systemd/system/"

# 4. Python 가상환경 설정
ssh ubuntu@arm1 "cd /var/www/auto-comment-worker && python3 -m venv venv"
ssh ubuntu@arm1 "cd /var/www/auto-comment-worker && venv/bin/pip install flask flask-limiter marshmallow requests"

# 5. 인증 파일 설정
ssh ubuntu@arm1 "sudo mkdir -p /etc/auto-comment-worker/credentials"
# 토큰 파일은 서버에서 직접 생성 (scp로 전송하지 않음)

# 6. 서비스 시작
ssh ubuntu@arm1 "sudo systemctl daemon-reload && sudo systemctl enable --now auto-comment-worker"

heredoc 변수 확장 함정

설치 스크립트를 heredoc으로 작성할 때 흔한 실수:

# 작은따옴표: 변수가 확장되지 않음!
ssh ubuntu@arm1 << 'ENDSSH'
echo $CREDENTIALS_DIR # 빈 문자열 출력
ENDSSH

# 큰따옴표 없음: 변수가 로컬에서 확장됨
ssh ubuntu@arm1 << ENDSSH
echo $CREDENTIALS_DIR # 로컬 변수값으로 확장
ENDSSH

이 문제를 피하기 위해 스크립트 대신 명령어를 개별 실행하는 방식으로 전환했습니다.

트러블슈팅: GITHUB_TOKEN 로드 실패

이 시스템을 배포하면서 가장 많은 시간을 소비한 문제입니다. 댓글 Webhook이 도착하면 다음 에러가 반복되었습니다:

INFO:__main__:GITHUB_TOKEN configured: False
INFO:__main__:GitHub API response status: 401
ERROR:__main__:Failed to get Discussion GraphQL ID

원인을 추적하는 과정을 단계별로 기록합니다.

1단계: LoadCredential 경로 문제

처음에는 systemd의 LoadCredential 디렉티브를 사용했습니다:

LoadCredential=github-token:/etc/auto-comment-worker/github-token
Environment=GITHUB_TOKEN_FILE=%d/github-token

%d는 credentials 디렉토리 경로로 대체되는 systemd 특수 변수입니다. 하지만 이 변수가 의도대로 해석되지 않아 토큰 파일 경로가 잘못 설정되었습니다.

해결: LoadCredential 대신 절대 경로를 직접 지정했습니다.

Environment=GITHUB_TOKEN_FILE=/etc/auto-comment-worker/github-token

2단계: 파일 소유권 문제

GITHUB_TOKEN configured: False가 여전히 나타났습니다. 파일을 확인해보니:

$ ls -la /etc/auto-comment-worker/github-token
-rw------- 1 root root 93 May 3 01:10 github-token

파일 소유자가 root이고 권한이 600이므로, ubuntu 사용자로 실행되는 서비스는 이 파일을 읽을 수 없습니다.

해결:

sudo chown ubuntu:ubuntu /etc/auto-comment-worker/github-token
sudo chmod 640 /etc/auto-comment-worker/github-token

3단계: ReadOnlyPaths 충돌

소유권을 변경한 후에도 GITHUB_TOKEN configured: False가 계속되었습니다. systemd 서비스 파일에 있던 ReadOnlyPaths 설정이 원인이었습니다:

# 이 설정이 파일 읽기를 차단함
ReadOnlyPaths=/etc/auto-comment-worker

ProtectSystem=strict가 이미 전체 파일시스템을 읽기 전용으로 마운트합니다. 여기에 ReadOnlyPaths를 추가하면 일부 환경에서 마운트 네임스페이스 충돌이 발생할 수 있습니다.

해결: ReadOnlyPaths를 빈 값으로 변경했습니다.

ReadOnlyPaths=

4단계: Python 파일 권한 검증 코드 (근본 원인)

이전 3단계를 모두 해결한 후에도 토큰이 로드되지 않았습니다. 마지막 원인은 Python 코드의 지나치게 엄격한 파일 권한 검증이었습니다:

# 파일 권한 640 → 그룹 읽기 비트(0o040)가 설정됨 → 거부!
if st.st_mode & (stat.S_IRWXO | stat.S_IRWXG):
 raise PermissionError("Token file must be 600 or 400")

2단계에서 chmod 640으로 변경했기 때문에, 그룹 읽기 비트가 설정되어 이 검증에 걸렸습니다. 하지만 에러 메시지가 로그에 나타나지 않아 발견이 늦었습니다 — PermissionError가 모듈 임포트 시점에 발생하여 서비스 시작 자체를 방해했기 때문입니다.

해결: 2부에서 설명한 것처럼 stat.S_IWOTH만 검사하도록 수정했습니다.

디버깅 로그의 중요성

이 문제를 추적하기 위해 추가한 디버깅 로그:

logger.info(f"GITHUB_TOKEN configured: {bool(GITHUB_TOKEN)}")
logger.info(f"GitHub API response status: {response.status_code}")
logger.info(f"GitHub API response body: {response.text[:500]}")

이 로그들이 없었다면 원인을 파악하는 데 훨씬 더 오래 걸렸을 것입니다. 인증 관련 코드에는 항상 토큰 로드 성공/실패 여부와 API 응답 상태를 로깅해야 합니다.

디버깅 흐름 요약

[1] LoadCredential %d 미해석 → 절대 경로로 변경
 ↓ (여전히 실패)
[2] 파일 소유자 root:root → ubuntu:ubuntu로 변경
 ↓ (여전히 실패)
[3] ReadOnlyPaths 충돌 → 제거
 ↓ (여전히 실패)
[4] Python 권한 검증 S_IRWXG → S_IWOTH로 완화
 ↓
 [해결!]

4단계에 걸친 이 디버깅에서 얻은 교훈:

한 번에 하나씩 변경하고 확인: 여러 설정을 동시에 바꾸면 어떤 것이 원인인지 알 수 없음
로그를 믿되, 로그가 없는 곳을 의심: 모듈 로드 시점의 예외는 일반 로그에 안 나타날 수 있음
보안 검증 코드도 버그의 원인: 보안 코드가 정상 동작을 차단하는 경우 — 보안과 운영의 균형

헬스 체크

서비스가 정상 동작하는지 확인하는 헬스 체크 엔드포인트:

@app.route('/health', methods=['GET'])
def health():
 """헬스 체크"""
 return jsonify({'status': 'healthy'})

모니터링 시스템에서 주기적으로 /health를 호출하여 서비스 상태를 확인합니다:

curl -s http://localhost:8081/health
# {"status": "healthy"}

향후 개선 사항

비동기 처리: GitHub Webhook 타임아웃(10초) 내에 응답하기 위해 Celery나 Redis Queue로 AI 응답 생성을 비동기화
재시도 로직: GitHub API 호출 실패 시 지수 백오프 재시도
모니터링 대시보드: Prometheus + Grafana로 응답 시간, 성공률, 에러율 모니터링
자동 배포: GitHub Actions로 코드 변경 시 자동 배포 파이프라인 구축
테스트: Webhook 페이로드 모킹으로 통합 테스트 작성

마무리

3부에 걸쳐 블로그 AI 자동 댓글 시스템의 전체 구축 과정을 기록했습니다:

1부: giscus → GitHub Webhook → Flask → Claude Code → GraphQL의 전체 아키텍처
2부: 파일 기반 인증, HMAC 검증, 입력 sanitization, systemd 보안
3부: 실제 배포, nginx 프록시, 4단계 디버깅 과정

이 시스템의 가장 큰 가치는 블로그 독자와의 소통을 자동화한다는 점입니다. 블로그 운영자가 모든 댓글에 즉시 응답하기 어렵지만, AI 어시스턴트가 1차 응답을 제공하여 독자 경험을 개선할 수 있습니다.

코드 전체는 GitHub 리포지토리에서 확인할 수 있습니다.

이 글은 AgentForge 블로그 자동 댓글 시스템 시리즈의 3부(마지막)입니다.

블로그 AI 자동 댓글 시스템 구축기 (2/3) — 보안 강화

Sun, 03 May 2026 01:10:00 +0900

개요

1부에서 AI 자동 댓글 시스템의 아키텍처와 구현을 다뤘습니다. 이번 2부에서는 보안 측면을 집중적으로 다룹니다.

외부 Webhook을 수신하고, GitHub API 토큰을 관리하며, 사용자 입력을 처리하는 시스템은 보안이 특히 중요합니다. 환경 변수 대신 파일 기반 인증으로 전환한 과정과 그 이유, 각 보안 계층의 설계를 설명합니다.

보안 위협 모델

이 시스템이 방어해야 하는 위협:

위협	공격 벡터	방어 수단
위장 Webhook	공격자가 가짜 Webhook 전송	HMAC-SHA256 시그니처 검증
토큰 유출	환경 변수 노출, 로그 노출	파일 기반 인증 + 권한 제한
XSS/인젝션	악의적인 댓글 내용	입력 sanitization
과도한 요청	DDoS, 남용	Flask-Limiter 속도 제한
권한 상승	워커 프로세스 탈취	systemd 보안 디렉티브
무한 루프	AI가 자신에게 응답	마커 기반 댓글 감지

파일 기반 인증 관리

환경 변수의 문제점

처음에는 GitHub 토큰과 Webhook 시크릿을 환경 변수로 관리했습니다:

# 초기 (안전하지 않음)
Environment=GITHUB_TOKEN=ghp_xxxxx
Environment=GITHUB_WEBHOOK_SECRET=my-secret-key

환경 변수 방식의 문제점:

/proc/PID/environ: Linux에서 프로세스의 환경 변수가 파일로 노출됨
로그 노출: 디버깅 중 환경 변수가 로그에 기록될 위험
자식 프로세스 상속: subprocess.run으로 Claude Code 실행 시 모든 환경 변수가 상속됨
systemd 설정 파일: 서비스 파일에 평문 시크릿이 포함되면 git에 커밋될 위험

파일 기반으로 전환

인증 정보를 파일 시스템에 저장하고, 환경 변수에는 파일 경로만 지정합니다:

# 개선 후 — 경로만 노출
Environment=GITHUB_TOKEN_FILE=/etc/auto-comment-worker/github-token
Environment=GITHUB_WEBHOOK_SECRET_FILE=/etc/auto-comment-worker/credentials/webhook-secret

서버의 디렉토리 구조:

/etc/auto-comment-worker/
├── github-token # GitHub Personal Access Token (640)
└── credentials/
 └── webhook-secret # GitHub Webhook HMAC Secret (600)

토큰 파일 로드 코드

import stat

GITHUB_TOKEN_FILE = os.environ.get('GITHUB_TOKEN_FILE', '')
if GITHUB_TOKEN_FILE and os.path.exists(GITHUB_TOKEN_FILE):
 # 파일 권한 검증
 st = os.stat(GITHUB_TOKEN_FILE)
 if st.st_mode & stat.S_IWOTH:
 raise PermissionError("Token file must not be world-writable")
 with open(GITHUB_TOKEN_FILE, 'r') as f:
 GITHUB_TOKEN = f.read().strip()
else:
 GITHUB_TOKEN = os.environ.get('GITHUB_TOKEN', '')

핵심 설계 결정:

파일 존재 시 파일 우선: 환경 변수는 폴백으로만 사용
권한 검증: 파일을 읽기 전에 권한을 확인
strip(): 파일 끝의 개행 문자 제거

파일 권한 검증 — 삽질의 기록

이 부분에서 가장 많은 시간을 소비했습니다. 초기 코드는 지나치게 엄격했습니다:

# 초기 코드 — 너무 엄격함
if st.st_mode & (stat.S_IRWXO | stat.S_IRWXG):
 raise PermissionError("Token file must be 600 or 400")

이 코드의 문제: S_IRWXO | S_IRWXG는 그룹의 모든 권한(읽기/쓰기/실행)과 기타의 모든 권한을 검사합니다. 즉, 파일 권한이 640 (소유자 읽기/쓰기, 그룹 읽기)이면 거부됩니다.

# 비트 마스크 분석
S_IRWXG = 0o070 # 그룹의 읽기+쓰기+실행
S_IRWXO = 0o007 # 기타의 읽기+쓰기+실행

# 640 = 0o640
0o640 & (0o070 | 0o007) = 0o640 & 0o077 = 0o040 # 0이 아님 → 거부!

실제 보안상 중요한 것은 다른 사용자(other)가 파일을 수정할 수 없는 것입니다. 그룹 읽기 권한은 같은 그룹 사용자가 파일을 읽을 수 있게 해주며, 보안상 문제가 되지 않습니다.

수정 후:

# 수정 후 — 실제 위협에 집중
if st.st_mode & stat.S_IWOTH:
 raise PermissionError("Token file must not be world-writable")

stat.S_IWOTH (0o002)만 검사하면 됩니다. 이는 “기타 사용자에게 쓰기 권한이 있는가"만 확인합니다.

권한	8진수	초기 코드	수정 후
`600`	`0o600`	허용	허용
`640`	`0o640`	거부	허용
`644`	`0o644`	거부	허용
`646`	`0o646`	거부	거부
`666`	`0o666`	거부	거부

HMAC-SHA256 시그니처 검증

GitHub Webhook은 요청 본문을 Webhook 시크릿으로 HMAC-SHA256 해싱한 시그니처를 X-Hub-Signature-256 헤더로 전송합니다. 이를 검증하여 요청이 실제 GitHub에서 왔는지 확인합니다.

def verify_webhook_signature(payload: bytes, signature: str) -> bool:
 """GitHub 웹훅 시그니처 검증"""
 if not signature:
 logger.warning("Missing webhook signature")
 return False

 if not WEBHOOK_SECRET:
 logger.warning("WEBHOOK_SECRET not configured - skipping validation")
 return True # 개발 모드 허용

 try:
 hash_algorithm, github_signature = signature.split('=', 1)
 if hash_algorithm != 'sha256':
 return False

 mac = hmac.new(
 WEBHOOK_SECRET.encode(),
 msg=payload,
 digestmod=hashlib.sha256
 )
 expected_signature = mac.hexdigest()

 # 타이밍 공격 방지
 if not hmac.compare_digest(expected_signature, github_signature):
 return False

 return True
 except Exception as e:
 logger.error(f"Signature verification error: {e}")
 return False

주요 포인트:

hmac.compare_digest(): 일반 == 비교 대신 상수 시간 비교를 사용하여 타이밍 공격을 방지합니다.
raw bytes 사용: request.data (원본 바이트)를 사용합니다. request.json으로 파싱 후 재직렬화하면 원본과 달라질 수 있습니다.
개발 모드: 시크릿이 설정되지 않으면 검증을 건너뜁니다. 프로덕션에서는 반드시 시크릿을 설정해야 합니다.

nginx 헤더 포워딩

시그니처 검증이 정상 작동하려면 nginx가 X-Hub-Signature-256 헤더를 포워딩해야 합니다:

location /webhook {
 proxy_pass http://localhost:8081;
 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-Hub-Signature-256 $http_x_hub_signature_256;
}

X-Hub-Signature-256을 명시적으로 포워딩하지 않으면, 기본 proxy_pass만으로는 커스텀 헤더가 전달되지 않을 수 있습니다.

요청 검증 (marshmallow 스키마)

Webhook 페이로드의 구조를 marshmallow 스키마로 검증합니다:

class WebhookSchema(Schema):
 action = fields.Str(required=True, validate=validate.Equal('created'))
 comment = fields.Dict(required=True)
 discussion = fields.Dict(required=True)
 repository = fields.Dict(required=True)
 sender = fields.Dict(required=False)

action = 'created'만 허용: 댓글 수정(edited)이나 삭제(deleted) 이벤트는 거부합니다.
필수 필드 검증: comment, discussion, repository가 없으면 400 에러를 반환합니다.
ValidationError → 감사 로그: 잘못된 요청은 감사 로그에 기록됩니다.

입력 Sanitization

사용자 댓글은 외부 입력이므로 반드시 처리합니다:

def sanitize_comment(body: str) -> str:
 """사용자 입력 sanitization"""
 body = re.sub(r'<[^>]+>', '', body) # HTML 태그 제거
 body = html.escape(body) # 특수 문자 이스케이프
 body = body[:1000] # 길이 제한
 return body

이 sanitization이 적용되는 곳:

댓글 본문 (comment_body)
토론 제목과 본문 (discussion_title, discussion_body)
원작성자 이름 (original_author)
AI 응답 게시 시 인용 부분

사용자명 마스킹

로그에 사용자 이름 전체를 기록하지 않습니다:

def mask_username(username: str) -> str:
 """사용자명 마스킹"""
 if not username or len(username) < 4:
 return "***"
 return f"{username[:3]}***"

로그에는 yar***처럼 마스킹된 이름만 표시됩니다. 개인정보 보호와 디버깅 편의성 사이의 균형을 맞춥니다.

속도 제한

Flask-Limiter로 엔드포인트별 속도 제한을 적용합니다:

limiter = Limiter(
 app=app,
 key_func=get_remote_address,
 default_limits=["10 per minute"],
 storage_uri="memory://"
)

@app.route('/webhook', methods=['POST'])
@limiter.limit("10 per minute")
def github_webhook():
 ...

분당 10회 제한: 정상적인 Webhook 호출 빈도를 고려한 수치
get_remote_address: 클라이언트 IP 기준으로 제한
memory://: 인메모리 저장소 (단일 프로세스에 적합)

systemd 보안 디렉티브

3부에서 systemd 배포를 상세히 다루지만, 보안 관련 디렉티브는 여기서 설명합니다:

[Service]
# 보안 강화
NoNewPrivileges=true # 권한 상승 방지
PrivateTmp=true # 독립된 /tmp 제공
ProtectSystem=strict # 파일시스템 읽기 전용
ProtectHome=false # 홈 디렉토리 접근 허용 (Claude Code 설정)
ReadWritePaths=/var/www/auto-comment-worker /var/log/auto-comment-worker

# 리소스 제한
MemoryMax=512M # 메모리 제한
CPUQuota=50% # CPU 사용량 제한
TasksMax=100 # 프로세스 수 제한

디렉티브	효과
`NoNewPrivileges=true`	`setuid`, `setgid` 등으로 권한 상승 불가
`PrivateTmp=true`	독립된 `/tmp` 네임스페이스, 다른 프로세스와 격리
`ProtectSystem=strict`	전체 파일시스템을 읽기 전용으로 마운트
`ReadWritePaths`	명시적으로 쓰기를 허용할 경로만 지정
`MemoryMax=512M`	OOM 상황에서 시스템 전체를 보호

`ProtectSystem=strict`과 `ReadOnlyPaths`의 충돌

초기에 ReadOnlyPaths=/etc/auto-comment-worker를 추가했다가 토큰 파일을 읽지 못하는 문제가 발생했습니다. ProtectSystem=strict가 이미 전체 파일시스템을 읽기 전용으로 설정하므로, 별도의 ReadOnlyPaths는 불필요합니다. 오히려 일부 환경에서 충돌을 일으킬 수 있어 제거했습니다.

마무리

이번 2부에서는 파일 기반 인증 관리, 파일 권한 검증 삽질기, HMAC-SHA256 시그니처 검증, 입력 sanitization, 속도 제한, systemd 보안 디렉티브를 다뤘습니다.

보안에서 가장 중요한 교훈: “너무 엄격한 검증은 너무 느슨한 검증만큼 해롭다.” 파일 권한을 600만 허용하는 초기 코드는 보안상 안전했지만, 실제 운영 환경에서 640 권한의 파일을 거부하여 서비스가 시작되지 않았습니다. 실제 위협(world-writable)에만 집중하는 것이 올바른 접근입니다.

다음 3부에서는 배포와 트러블슈팅 — systemd 서비스 구성, nginx 리버스 프록시, 실제 겪은 오류들과 해결 과정을 다룹니다.

이 글은 AgentForge 블로그 자동 댓글 시스템 시리즈의 2부입니다.