간단한 GeoIP 조회 API입니다. 기본은 GeoLite2-City.mmdb를 사용해 IP를 나라/지역/도시/위도/경도로 매핑하며, 선택적으로 PostgreSQL + maxminddb_fdw로 가져온 데이터를 조회할 수 있습니다. 초기 적재 후에는 DB만으로 조회가 가능하도록 읽기 전용 테이블과 함수가 생성됩니다.

요구 사항

Go 1.25+
GeoLite2-City.mmdb (레포지토리 루트에 위치)
Docker / Docker Compose (컨테이너 실행 시)

설치 및 실행

로컬 (Go)

go mod tidy            # 필요한 경우 go.sum 생성
PORT=8080 GEOIP_DB_PATH=./GeoLite2-City.mmdb go run ./cmd/server

Docker 최초 실행시

docker network create --driver bridge --attachable geo-ip

Docker Compose (PostgreSQL + FDW + API)

docker compose up --build

서비스
- postgres (5432): Dockerfile.postgres로 maxminddb_fdw를 빌드하여 확장 설치 후 GeoLite2-City.mmdb를 FDW로 읽고, 로컬 테이블로 적재합니다. 초기 적재 완료 후 mmdb 없이도 DB에서 조회가 가능합니다.
- api (8080): 기본적으로 Postgres 백엔드(GEOIP_BACKEND=postgres)를 사용해 조회합니다.
볼륨
- ./GeoLite2-City.mmdb:/initial_data/GeoLite2-City.mmdb:ro (Postgres 초기 적재용)
- pgdata (DB 데이터 지속)

환경 변수

공통
- PORT (기본 8080): 서버 리스닝 포트
- GEOIP_BACKEND (mmdb|postgres, 기본 mmdb)
MMDB 모드
- GEOIP_DB_PATH (기본 /initial_data/GeoLite2-City.mmdb): GeoIP 데이터베이스 경로
Postgres 모드
- DATABASE_URL: 예) postgres://geoip_readonly:geoip_readonly@postgres:5432/geoip?sslmode=disable
- GEOIP_LOOKUP_QUERY (선택): 기본은 geoip.lookup_city($1) 사용

사용법

헬스체크: GET /health
조회: GET /lookup?ip=<IPv4|IPv6>
- ip 생략 시 호출자 IP를 사용

예시:

curl "http://localhost:8080/lookup?ip=1.1.1.1"

응답 예시:

{
  "IP": "1.1.1.1",
  "Country": "Australia",
  "Region": "Queensland",
  "City": "South Brisbane",
  "Address": "South Brisbane, Queensland, Australia",
  "Latitude": -27.4748,
  "Longitude": 153.017
}

개발 참고

주요 코드: cmd/server/main.go, internal/geo (MMDB/Postgres resolver)
테스트 실행: go test ./...
- Postgres 통합 테스트 실행 시 GEOIP_TEST_DATABASE_URL을 설정하면 DB 백엔드 조회 테스트가 수행됩니다(미설정 시 skip).
컨테이너 빌드: docker build -t geoip:local .

Postgres/FDW 쿼리 예시

단건 조회 함수 (CIDR 매칭): SELECT * FROM geoip.lookup_city('1.1.1.1');
원시 테이블 조회: SELECT * FROM geoip.city_blocks LIMIT 5;
API는 lookup_city(inet)를 사용하여 가장 구체적인 네트워크(prefix) 한 건을 반환합니다.

보안 및 운영 주의사항

GeoLite2 라이선스 준수: GeoLite2-City.mmdb 교체 시 기존 파일을 대체하여 재시작하세요.
Postgres 포트(5432) 외부 노출 시 방화벽/보안 그룹으로 제한하고 강한 비밀번호를 사용하세요.
DB는 읽기 전용 계정(geoip_readonly)을 기본으로 사용하며, 초기 스키마에서 default_transaction_read_only를 강제합니다.