SmartThings Edge Bridge · Docker

Synology Container Manager와 Linux Docker용 SmartThings Edge Bridge 및 ThinQ 수동 AEB 브리지

한국어 · English

주요 기능

• LG ThinQ Bridge용 수동 AndroidEdgeBridge(AEB) HTTP 경로
• Todd Austin 계열 EdgeBridge Driver의 ping, forward, register/callback 호환
• One UI 스타일 읽기 전용 상태 대시보드와 한국어·영어·일본어·중국어 UI
• Synology/Linux에서 Hub의 실제 출발지 IP를 유지하는 host networking
• linux/amd64, linux/arm64 GHCR 이미지
• 고정 비루트 UID/GID 10001:10001, 읽기 전용 root filesystem, capability 제거
• 영속 등록 volume, 자동 재시작, 부작용 없는 TCP healthcheck, 로그 회전

Important

이 컨테이너는 SmartThings Edge Driver가 LAN에서 호출하는 companion server입니다. Hub/Station 자체를 컨테이너 안에서 실행하는 제품이 아닙니다.

Warning

TCP 8088을 인터넷으로 포트 포워딩하지 마세요. SPK판과 Docker판도 같은 포트를 사용하므로 동시에 실행할 수 없습니다.

Synology 네이티브 패키지를 원하면 SynologyEdgeBridge SPK 저장소를 사용하세요.

빠른 설치

git clone https://github.com/sioaeko/DockerEdgeBridge.git
cd DockerEdgeBridge
docker compose pull
docker compose up -d
docker compose ps

기본 이미지는 다음과 같이 고정되어 있습니다.

ghcr.io/sioaeko/dockeredgebridge:1.1.0-105

접속 및 ThinQ 입력 주소:

GUI:       http://<NAS_LAN_IP>:8088
ThinQ AEB: <NAS_LAN_IP>:8088

기본 compose.yaml은 network_mode: host를 사용하므로 별도의 ports: 매핑이 없습니다. 이 방식은 Hub/Station의 실제 IP를 브리지에 전달해 CIDR 접근 정책과 /api/register 검증이 올바르게 동작하게 합니다.

Synology Container Manager

1. 저장소 전체를 NAS 공유 폴더에 clone하거나 Source ZIP을 File Station으로 업로드·압축 해제합니다.
2. Container Manager → 프로젝트 → 생성을 엽니다.
3. 저장소 폴더를 프로젝트 경로로 선택하고 compose.yaml을 불러옵니다.
4. 프로젝트를 빌드·시작합니다.

LG ThinQ Bridge 설정

SmartThings Station IP를 몰라도 ThinQ 수동 AEB 방식은 사용할 수 있습니다. 기본 AEB_Client_Networks = private가 같은 사설 LAN의 요청을 허용합니다.

1. LG ThinQ Bridge 채널에 참여해 Driver를 Hub/Station에 설치합니다.
2. SmartThings 앱에서 LG ThinQ Bridge 장치를 추가합니다.
3. 장치 설정에서 Auto-discover를 끕니다.
4. AEB 주소에 NAS_IP:8088만 입력합니다. http://와 마지막 /는 넣지 않습니다.
5. LG ThinQ PAT를 ThinQ Bridge 장치 설정에 입력합니다.
6. Region을 선택하고 MQTT가 필요한 Realtime Push/Beta 옵션은 끈 뒤 polling을 사용합니다.
7. 대시보드에서 AEB Ping과 AEB 외부 전달 수치가 증가하는지 확인합니다.

Note

LG ThinQ Bridge는 ping/forward 방식이므로 ThinQ 가전이 정상 작동해도 대시보드의 LAN 콜백 등록은 0대일 수 있습니다.

PAT 두 종류

구분	LG ThinQ PAT	SmartThings PAT
입력 위치	ThinQ Bridge 장치 설정	컨테이너 설정의 SmartThings_Bearer_Token
용도	LG 가전 목록·상태·제어	api.smartthings.com 전달 시에만 사용
필수	ThinQ 연동에 필요	선택 사항이며 LG ThinQ PAT를 대신하지 않음

설정

기본 설정은 docker/edgebridge.cfg입니다. Server_IP는 비워 두세요.

SmartThings PAT처럼 비밀값이 필요할 때만 Git에서 제외되는 로컬 설정을 만듭니다.

cp docker/edgebridge.cfg docker/edgebridge.local.cfg
vi docker/edgebridge.local.cfg
sudo chown 10001:10001 docker/edgebridge.local.cfg
sudo chmod 600 docker/edgebridge.local.cfg
printf 'EDGEBRIDGE_CONFIG_FILE=./docker/edgebridge.local.cfg\n' > .env
docker compose up -d --force-recreate edgebridge

이미 mount된 동일 파일의 내용만 바꿨다면 docker compose restart edgebridge면 됩니다. .env나 bind mount 경로를 바꿨다면 컨테이너를 다시 생성해야 합니다.

주요 항목	기본값	설명
Server_Port	8088	GUI·AEB 수신 포트
Allowed_Client_Networks	private	전체 API/GUI를 허용할 CIDR
AEB_Client_Networks	private	ThinQ 수동 AEB 요청 허용 CIDR
AEB_Allowed_Hosts	*.lgthinq.com,lgthinq.com	ThinQ 외부 전달 허용 호스트
Hub_Client_Networks	loopback	일반 register/callback Driver의 Hub CIDR
Token_Client_Networks	loopback	SmartThings PAT 자동 주입을 허용할 CIDR

일반 register/callback Driver를 쓸 때만 Hub IP를 DHCP 예약하고 Hub_Client_Networks = <HUB_IP>/32로 지정하세요. ThinQ 수동 AEB만 사용하면 Station IP가 필요 없습니다.

데이터·로그·업데이트

• 등록 정보: named volume smartthingsedgebridge-data의 /var/lib/edgebridge/state
• 로그: docker compose logs -f edgebridge
• 업데이트:

git pull --ff-only
docker compose pull
docker compose up -d

docker compose down -v, Container Manager의 정리(Clean) 또는 volume 삭제를 실행하면 등록 정보가 사라질 수 있습니다. 프로젝트를 삭제하기 전에 smartthingsedgebridge-data volume을 백업하세요.

소스에서 빌드

docker compose build --pull
docker compose up -d --build

로컬 검증:

python -m unittest discover -s tests -p "test_*.py" -v
python src/edgebridge/server.py --config docker/edgebridge.cfg --check-config
node --check src/edgebridge/static/app.js

보안과 호환 범위

• 기본적으로 private/loopback/link-local 목적지로의 범용 forward를 차단합니다.
• LG ThinQ AEB는 HTTPS와 정확한 LG 허용 호스트만 사용합니다.
• redirect마다 목적지를 재검증하고, origin이 바뀌면 비밀 헤더를 제거하며 body 요청은 차단합니다.
• SmartThings PAT는 정확한 https://api.smartthings.com과 허용 클라이언트에서만 주입합니다.
• PAT, Authorization, 전체 URL query와 body는 이벤트 로그에 남기지 않습니다.

이 구현의 ThinQ 범위는 ping과 LG API forward입니다. _edgebridge._tcp mDNS 자동 발견과 MQTT Realtime Push는 포함하지 않으므로 수동 주소와 polling을 사용하세요.

라이선스

Apache License 2.0 · Third-party notices