6a26c0c4e4
- Add FastAPI-based REST API server (api_server.py) - Add Dockerfile and docker-compose.yaml for containerized deployment - Add Gitea Actions CI workflow for building and pushing images - Refactor CLI to support dual-server SSH (bouncer + crowdsec) - Update dependencies with FastAPI and uvicorn - Update CLAUDE.md and README.md with full documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
178 lines
4.9 KiB
Markdown
178 lines
4.9 KiB
Markdown
# CrowdSec Cloudflare Bouncer Manager
|
|
|
|
CrowdSec Cloudflare Worker Bouncer를 관리하는 CLI/API 도구입니다.
|
|
|
|
## 기능
|
|
|
|
- 보호 도메인 CRUD (추가/조회/수정/삭제)
|
|
- Cloudflare 도메인 자동 동기화
|
|
- Turnstile CAPTCHA 설정 관리
|
|
- CrowdSec 차단 결정 조회
|
|
- 설정 백업/복원
|
|
- **REST API 서버 모드 지원**
|
|
|
|
## 요구사항
|
|
|
|
- Python 3.13+
|
|
- SSH 접근 가능한 2개의 서버:
|
|
- Bouncer 서버 (crowdsec-cloudflare-worker-bouncer 실행)
|
|
- CrowdSec 서버 (CrowdSec 엔진 실행)
|
|
|
|
## 설치
|
|
|
|
### 로컬 실행
|
|
|
|
```bash
|
|
# uv 설치 (없는 경우)
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# 의존성 설치
|
|
uv sync
|
|
|
|
# 환경변수 설정
|
|
export CFB_BOUNCER_HOST="10.253.100.131"
|
|
export CFB_CROWDSEC_HOST="10.253.100.240"
|
|
|
|
# CLI 실행
|
|
uv run python cf_bouncer.py list
|
|
|
|
# API 서버 실행
|
|
uv run uvicorn api_server:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
### Container 실행 (권장)
|
|
|
|
```bash
|
|
# 이미지 빌드
|
|
podman build -t cf-bouncer-manager:latest .
|
|
|
|
# CLI 모드
|
|
podman run --rm \
|
|
-v ~/.ssh:/root/.ssh:ro \
|
|
-e CFB_BOUNCER_HOST="10.253.100.131" \
|
|
-e CFB_CROWDSEC_HOST="10.253.100.240" \
|
|
cf-bouncer-manager:latest list
|
|
|
|
# API 서버 모드
|
|
podman run -d --rm --name cfb-api \
|
|
--network host \
|
|
-v ~/.ssh:/root/.ssh:ro \
|
|
-e CFB_BOUNCER_HOST="10.253.100.131" \
|
|
-e CFB_CROWDSEC_HOST="10.253.100.240" \
|
|
--entrypoint uv \
|
|
cf-bouncer-manager:latest \
|
|
run uvicorn api_server:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
### Alias 설정 (편의용)
|
|
|
|
```bash
|
|
# ~/.bashrc 또는 ~/.zshrc에 추가
|
|
alias cfb='podman run --rm -v ~/.ssh:/root/.ssh:ro -e CFB_BOUNCER_HOST="10.253.100.131" -e CFB_CROWDSEC_HOST="10.253.100.240" cf-bouncer-manager:latest'
|
|
|
|
# 사용
|
|
cfb list
|
|
cfb status
|
|
cfb add example.com
|
|
```
|
|
|
|
## 환경변수
|
|
|
|
| 변수 | 필수 | 기본값 | 설명 |
|
|
|------|------|--------|------|
|
|
| `CFB_BOUNCER_HOST` | O | - | Bouncer 서버 호스트 |
|
|
| `CFB_BOUNCER_PORT` | X | 22 | Bouncer 서버 SSH 포트 |
|
|
| `CFB_BOUNCER_USER` | X | root | Bouncer 서버 SSH 사용자 |
|
|
| `CFB_BOUNCER_KEY` | X | - | Bouncer 서버 SSH 키 경로 |
|
|
| `CFB_CROWDSEC_HOST` | O | - | CrowdSec 서버 호스트 |
|
|
| `CFB_CROWDSEC_PORT` | X | 22 | CrowdSec 서버 SSH 포트 |
|
|
| `CFB_CROWDSEC_USER` | X | root | CrowdSec 서버 SSH 사용자 |
|
|
| `CFB_CROWDSEC_KEY` | X | - | CrowdSec 서버 SSH 키 경로 |
|
|
| `CFB_API_HOST` | X | 0.0.0.0 | API 서버 바인드 호스트 |
|
|
| `CFB_API_PORT` | X | 8000 | API 서버 포트 |
|
|
|
|
## CLI 명령어
|
|
|
|
```
|
|
cfb list # 보호 중인 도메인 목록
|
|
cfb show <domain> # 도메인 상세 정보
|
|
cfb add <domain> # 새 도메인 추가
|
|
cfb edit <domain> # 도메인 설정 수정
|
|
cfb remove <domain> # 도메인 제거
|
|
cfb sync # Cloudflare 도메인 동기화
|
|
cfb apply # 설정 적용 (서비스 재시작)
|
|
cfb status # bouncer 상태 확인
|
|
cfb available # 추가 가능한 도메인 목록
|
|
cfb logs [-f] # 로그 조회 (-f: 실시간)
|
|
cfb decisions # CrowdSec 차단 결정 조회
|
|
cfb metrics # Prometheus 메트릭 조회
|
|
cfb backup # 설정 백업
|
|
cfb restore [file] # 설정 복원
|
|
cfb diff [file] # 설정 비교
|
|
cfb export # 설정 내보내기
|
|
cfb history # 변경 이력 조회
|
|
```
|
|
|
|
## REST API
|
|
|
|
API 서버 실행 후 `http://localhost:8000/docs`에서 Swagger UI를 확인할 수 있습니다.
|
|
|
|
### 주요 엔드포인트
|
|
|
|
| Method | Endpoint | 설명 |
|
|
|--------|----------|------|
|
|
| GET | `/health` | 헬스 체크 |
|
|
| GET | `/domains` | 보호 중인 도메인 목록 |
|
|
| GET | `/domains/{domain}` | 도메인 상세 정보 |
|
|
| POST | `/domains` | 새 도메인 추가 |
|
|
| PUT | `/domains/{domain}` | 도메인 설정 수정 |
|
|
| DELETE | `/domains/{domain}` | 도메인 제거 |
|
|
| POST | `/apply` | 설정 적용 |
|
|
| GET | `/status` | bouncer 상태 확인 |
|
|
| GET | `/available` | 추가 가능한 도메인 목록 |
|
|
| GET | `/decisions` | CrowdSec 차단 결정 조회 |
|
|
| POST | `/sync` | Cloudflare 도메인 동기화 |
|
|
| POST | `/backup` | 설정 백업 |
|
|
| GET | `/history` | 변경 이력 조회 |
|
|
|
|
### API 사용 예시
|
|
|
|
```bash
|
|
# 도메인 목록 조회
|
|
curl http://localhost:8000/domains
|
|
|
|
# 도메인 추가
|
|
curl -X POST http://localhost:8000/domains \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"domain": "example.com", "action": "captcha", "turnstile_enabled": true}'
|
|
|
|
# 도메인 수정
|
|
curl -X PUT http://localhost:8000/domains/example.com \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"action": "ban"}'
|
|
|
|
# 설정 적용
|
|
curl -X POST http://localhost:8000/apply
|
|
|
|
# 상태 확인
|
|
curl http://localhost:8000/status
|
|
```
|
|
|
|
## 서버 설정
|
|
|
|
각 서버에 sshd가 설치되어 있어야 합니다:
|
|
|
|
```bash
|
|
# Debian/Ubuntu
|
|
apt install openssh-server
|
|
systemctl enable --now ssh
|
|
|
|
# SSH 키 복사
|
|
ssh-copy-id root@bouncer-server
|
|
ssh-copy-id root@crowdsec-server
|
|
```
|
|
|
|
## 라이선스
|
|
|
|
MIT
|