Add REST API server, Docker support, and CI pipeline
- 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>
This commit is contained in:
kaffa
177
README.md
177
README.md
@@ -0,0 +1,177 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user