Immich GeoSync admin and worker for Korean reverse geocoding clusters
2.5K
Immich 사진의 대한민국 위치 정보를 한국어 주소로 보정하고, 반복 보정이 필요한 좌표 클러스터를 Admin UI에서 편리하게 관리하는 worker + admin 통합 모듈입니다.
Immich GeoSync의 고품질 한국어 주소 변환 및 지도 시각화 서비스를 구동하려면 다음 두 가지 공공/민간 API 키가 필수로 요구됩니다.
VWorld API Key (국토교통부 공간정보 오픈플랫폼 - 필수)
updater.js) 구동 시 경위도 좌표를 최신의 대한민국 지번 및 도로명 주소로 역지오코딩(Reverse Geocoding)하는 핵심 변환 API입니다.NAVER Maps API (네이버 클라우드 플랫폼 - 필수)
Client ID 및 Client Secret 필요)v3의 asset_exif, asset_file, asset.originalFileName, asset.fileCreatedAt 구조를 기준으로 동작합니다.asset.isEdited)에 맞는 preview/thumbnail 파일을 우선 선택합니다.v3의 lockedProperties 중 latitude, longitude 잠금 자산을 건너뜁니다./usr/src/app/upload뿐 아니라 UPLOAD_LOCATION 기준 custom media path도 지원합니다.이 프로젝트는 하나의 코드베이스에서 두 개의 고유 컨테이너로 역할을 분할하여 구동합니다. 두 서비스는 같은 Immich PostgreSQL 데이터베이스와 공유 .env 환경 변수 설정을 마운트하여 긴밀하게 협업합니다.
immich-geosync-worker (보정 워커)updater.js 엔진을 통해 백그라운드에서 주기적으로 데이터베이스를 전수조사하여 무주소 좌표들을 보정합니다. API 트래픽을 최소화하기 위한 3단계 공간 지능형 파이프라인을 제공합니다.
대한민국 본토 경계 검증에는 public domain인 Natural Earth 1:110m 경계를 사용하며, 일반화된 해안선 오차와 주요 도서 지역은 별도 허용영역으로 보완합니다. 최종 자동 반영은 API가 반환한 대한민국 시도명 검증까지 통과해야 합니다.
latitude 32.8longitude 124.5city, state 등)가 채워지지 않았거나 누락된 대상을 선별합니다. (옵션 --force 실행 시 전체 전수 재보정 가능)15m)로 묶습니다. DB 조회 순서가 달라도 클러스터 구성이 유지되며, 역지오코딩 대표점은 평균 가상점이 아닌 실제 촬영 좌표 중에서 선택합니다.custom_geo_geocode_cache)에 보관되어 캐시 데이터로 일괄 갱신 처리됩니다.review_required로 보류하여 사진 주소를 자동 변경하지 않습니다.country/state/city만 반영합니다.not_found)로 격리하여 무의미한 유료 API 낭비를 사전에 자동 차단합니다.immich-geosync-admin (클러스터 맵 에디터 & 웹 어드민)admin-server.js로 브라우저 운영 제어 환경을 제공하며, 네이버 지도 API와 연동된 완전한 지도 시각화 제어 도구를 구현합니다.
우리 집, 가평 OO 캠핑장)으로 무조건 강제 매핑됩니다./usr/src/app/upload)를 마운트하여 DB 속 메타데이터와 파일 실체를 실시간 매핑하기 때문에 가능한 강력한 탐색 기능입니다.기존 서버의 .env 텍스트 파일을 직접 수정할 필요 없이, Admin Web의 '설정' 탭에서 주요 구동 설정 변수들을 안전하게 조절할 수 있습니다.
****) 처리되어 가려집니다. 값을 비워둔 채 저장하면 기존 설정 값을 안전하게 보존합니다.# Web UI에서 설정을 저장한 후 적용을 위해 두 컨테이너를 함께 재기동합니다.
docker compose restart immich-geosync-worker immich-geosync-admin
본 모듈은 Immich 서비스와 같은 디렉터리에 설치하지 않고 서버 내 임의의 별도 경로(예: /docker/immich-geosync)에 단독으로 구성할 수 있습니다.
임의 폴더에 두더라도 아래의 도커 네트워크 가이드를 준수하면 자동으로 DB 컨테이너를 탐색하여 완벽하게 통신합니다.
.env 환경 변수 준비구동할 디렉터리에 .env 파일을 생성하고 하단 설정을 입력합니다.
# 데이터베이스 연결 정보 (자신의 DB 컨테이너 이름 또는 외부 IP 주소로 지정 가능)
DB_HOSTNAME=immich_postgres
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=***
DB_DATABASE_NAME=immich
# 국내 역지오코딩 API 설정 (VWorld 및 Naver API 가입 필수)
VWORLD_API_KEY=***
NAVER_CLIENT_ID=your_naver_client_id_here
NAVER_CLIENT_SECRET=***
# 동작 제어 설정
INTERVAL_HOURS=24
STEP_DELAY_MS=100
CLUSTER_RADIUS_METERS=15
APPEND_BUILDING_NAME=true
API_TIMEOUT_MS=10000
NAVER_API_TIMEOUT_MS=10000
BOUNDARY_VALIDATION_MIN_SPAN_METERS=10
# Admin UI 포트 및 경로
ADMIN_PORT=3030
ADMIN_ENV_PATH=/app/.env
UPLOAD_LOCATION=/path/to/immich/upload
사용자의 실제 도커 네트워크명(기본값은 보통 immich 또는 default 계열)으로 브릿지 연결을 하도록 networks 구성을 추가한 유연한 템플릿입니다.
version: "3"
services:
immich-geosync-worker:
container_name: immich_geosync_worker
image: lscya84/immich-geosync:latest
restart: always
volumes:
# 독립된 폴더일 경우 절대 경로로 매핑(예: /docker/immich/.env)하거나, 현재 폴더의 .env를 마운트합니다.
- ./.env:/app/.env:ro
environment:
- DB_HOSTNAME=immich_postgres # Immich DB 서비스명과 통일
networks:
- immich-network # Immich 컨테이너들이 사용하는 외부 네트워크와 통합
immich-geosync-admin:
container_name: immich_geosync_admin
image: lscya84/immich-geosync:latest
command: ["node", "admin-server.js"]
restart: always
ports:
- "3030:3030"
volumes:
- ./.env:/app/.env
# Immich의 업로드 디렉터리(사진 물리 파일 경로)를 매핑해 줍니다.
- /path/to/immich/upload:/usr/src/app/upload:ro
environment:
- DB_HOSTNAME=immich_postgres
- ADMIN_PORT=${ADMIN_PORT:-3030}
- ADMIN_ENV_PATH=/app/.env
- UPLOAD_LOCATION=/usr/src/app/upload
networks:
- immich-network
networks:
# 이미 실행 중인 Immich 도커 네트워크가 있는 경우, external 옵션을 활성화하여 그 안에 동적으로 가입시킵니다.
immich-network:
name: immich_default # 또는 immich_immich-network 등 사용자의 실제 네트워크 이름을 적어주세요.
external: true
도커 컴포즈 명령을 활용해 한 번의 입력으로 모든 프로세스를 한 번에 기동할 수 있습니다.
# 전체 구성요소 일괄 백그라운드 시작
docker compose up -d
서비스가 정상적으로 켜졌다면 브라우저를 열고 관리 페이지로 접속합니다:
👉 http://<서버IP>:3030/admin/
기존에 이미 주소 보정이 끝난 사진들까지 완전히 새 좌표 기준으로 강제 리스캔할 때 실행합니다:
docker compose exec immich-geosync-worker node updater.js --force
docker compose exec immich-geosync-worker node updater.js --clear-cache-only
docker compose exec immich-geosync-worker node reverse_geocode.js 37.5665 126.9780
Content type
Image
Digest
sha256:3a7d88a08…
Size
45.7 MB
Last updated
4 months ago
docker pull lscya84/immich-geosync