By kage2k in 일상 — Mar 4, 2026

Syncthing with Portainer Stack 완벽 가이드

⚠️ 면책 고지 (Disclaimer)
본 문서는 기술 정보 제공을 목적으로 하며, 특정 환경에서의 설정 결과를 보장하지 않습니다. 네트워크 및 서버 설정 변경은 데이터 손실이나 보안 문제로 이어질 수 있으므로, 진행 전 반드시 중요한 데이터를 백업하시기 바랍니다. 본 가이드를 따름으로써 발생하는 모든 문제에 대한 책임은 사용자 본인에게 있습니다.

클라우드 서비스의 월간 비용과 개인정보 유출에 대한 걱정 없이, 내 소유의 기기들 사이에서만 파일을 자유롭게 동기화하고 싶으신가요? 시놀로지 NAS를 활용한 오픈소스 파일 동기화 솔루션, Syncthing 이 완벽한 해답이 될 수 있습니다.

본 가이드에서는 Portainer Stack을 사용하여 시놀로지 NAS 환경에 Syncthing을 안정적으로 구축하고, Nginx Proxy Manager(NPM)를 통해 안전한 외부 접속 환경을 설정하는 모든 과정을 상세히 다룹니다.

Syncthing이란? 클라우드 서비스와 비교

Syncthing은 중앙 서버를 거치지 않고 P2P(Peer-to-Peer) 방식으로 기기 간에 직접 파일을 동기화하는 오픈소스 솔루션입니다. 데이터가 제3자 서버에 저장되지 않아 개인정보 보호에 매우 유리하며, 용량 제한 없이 NAS의 저장 공간을 그대로 활용할 수 있습니다.

항목	Syncthing	일반 클라우드 서비스 (Google Drive 등)
데이터 저장 위치	내 NAS 및 개인 기기	클라우드 제공사 서버
비용	무료 (오픈소스)	용량에 따른 월/연 구독료
용량 제한	내 저장 장치의 한도	요금제에 따라 제한됨
개인정보 보호	매우 높음 (데이터 외부 저장 X)	제공사 정책에 따름
동기화 방식	P2P (기기 간 직접 통신)	중앙 서버 경유
설정 난이도	다소 높음	매우 쉬움

시작 전 필수 확인 사항

본격적인 설치에 앞서 아래 두 가지 개념과 보안 경고를 반드시 숙지해야 합니다.

P2P 동기화의 이해: Syncthing은 동기화할 모든 기기가 온라인 상태일 때 데이터가 교환됩니다. 중앙 서버가 없으므로, 한쪽 기기가 꺼져있으면 실시간 동기화가 이루어지지 않습니다.
Healthcheck 기능: Docker 컨테이너가 정상적으로 작동하는지 시스템이 주기적으로 확인하는 기능입니다. YAML 파일에 포함된 healthcheck는 Syncthing의 웹 GUI 포트(8384)가 응답하는지 검사하여 서비스의 안정성을 보장합니다.

[!CAUTION]
보안 경고: Syncthing의 웹 관리 페이지(GUI)가 외부에 노출될 경우, 인증 설정 없이는 누구나 파일 시스템에 접근할 수 있는 심각한 보안 위협이 됩니다. 반드시 GUI 접속용 사용자 이름과 비밀번호를 설정하고, 공유기 포트 포워딩 및 방화벽 설정을 신중하게 진행하십시오.

1단계: Portainer Stack으로 Syncthing 배포하기

시놀로지 NAS에 설치된 Portainer에 접속하여 [Stacks] > [Add stack] 메뉴로 이동한 뒤, 아래 YAML 코드를 웹 편집기에 붙여넣고 배포합니다.

PUID 및 PGID 확인 방법

YAML 코드의 PUID와 PGID는 Syncthing이 파일을 읽고 쓸 시놀로지 사용자의 권한 ID입니다. 이 값을 정확히 입력해야 권한 오류가 발생하지 않습니다.

시놀로지 DSM에 SSH로 접속합니다. (제어판 > 터미널 및 SNMP > SSH 서비스 활성화 필요)
출력된 결과에서 uid=1026과 gid=100 같은 부분을 확인하여 각각 PUID와 PGID 환경 변수에 입력합니다.

로그인 후, 아래 명령어를 입력합니다. [사용자계정] 부분은 실제 Syncthing이 사용할 시놀로지 계정 이름으로 변경하세요.

id [사용자계정]

Syncthing Stack YAML 코드

services:
  syncthing:
    image: ghcr.io/linuxserver/syncthing:latest
    container_name: Syncthing
    healthcheck:
      # 컨테이너 내부 8384 포트로 접속이 가능한지 정기적으로 체크합니다.
      test: curl -f http://localhost:8384/ || exit 1
      interval: 1m
      timeout: 10s
      retries: 3
    restart: on-failure:5
    security_opt:
      - no-new-privileges:true # 보안 강화를 위해 컨테이너 내 권한 상승 방지
    environment:
      - PUID=1026              # 시놀로지 사용자 ID (id 명령어로 확인 필수)
      - PGID=100               # 시놀로지 그룹 ID (id 명령어로 확인 필수)
      - TZ=Asia/Seoul
    volumes:
      - /volume1/docker/syncthing/config:/config:rw # 설정 데이터 저장 경로
      - /volume1/share2:/share2:rw                 # 실제 동기화할 NAS 폴더 경로
    ports:
      - 6384:8384              # 웹 UI 접속 포트 (관리용)
      - 22000:22000/tcp        # 데이터 전송용 TCP 포트
      - 22000:22000/udp        # 데이터 전송용 UDP 포트
      - 21027:21027/udp        # 로컬 네트워크 기기 검색용 포트

Stack 설정 핵심 포인트 분석

PUID 및 PGID: Syncthing 컨테이너가 NAS의 파일 시스템에 접근할 수 있는 권한을 지정하는 가장 중요한 값입니다. 이 값이 실제 시놀로지 사용자의 ID와 일치하지 않으면 파일 쓰기 권한 오류가 발생하여 동기화가 실패합니다.
volumes:
- /volume1/docker/syncthing/config는 Syncthing의 설정 파일이 저장될 경로입니다. 컨테이너를 재생성해도 설정이 유지됩니다.
- /volume1/share2는 실제 파일이 동기화될 NAS의 공유 폴더 경로입니다. 반드시 본인의 환경에 맞게 수정해야 합니다.

예시)

클라이언트 쪽에서 temp260303 를 만들었습니다.
아래 스샷은 원격지에서 Folder Path 설정 예시입니다.
yaml 에서 share2 로 volumes 연결했습니다. temp 기존 원격지 있는폴더 입니다. 그 아래에 temp260303 을 연결해라. 라는 의미입니다.

ports:
- 6384:8384: 웹 관리 페이지 접속 포트입니다. http://<NAS-IP>:6384로 접속합니다.
- 22000:22000: 기기 간 실제 데이터를 주고받는 핵심 포트입니다.
- 21027:21027: 로컬 네트워크 내에서 다른 Syncthing 기기를 자동으로 발견하기 위한 포트입니다.

2단계: Syncthing 초기 설정 및 보안 강화

Stack 배포가 완료되면 웹 브라우저에서 http://<NAS-IP>:6384로 접속합니다.

최초 접속 시, 상단에 보안 설정을 요구하는 경고 메시지가 표시됩니다. 즉시 [Actions] > [Settings] > [GUI] 탭으로 이동하여 GUI Authentication User와 GUI Authentication Password를 설정하고 저장하십시오. 강력한 비밀번호 사용을 권장합니다.

3단계: Nginx Proxy Manager(NPM)로 외부 접속 설정 (선택)

외부에서도 안전하게 Syncthing 관리 페이지에 접속하려면 도메인을 연결하고 HTTPS를 적용하는 것이 좋습니다.

NPM 프록시 호스트 설정

NPM 대시보드에서 [Proxy Hosts] > [Add Proxy Host]를 클릭하고 아래와 같이 설정합니다.

항목	설정 값	설명
Domain Names	`syncthing.your-domain.com`	사용할 개인 도메인
Scheme	`http`	-
Forward Hostname / IP	`<NAS-IP>`	시놀로지 NAS의 내부 IP 주소
Forward Port	8384	Syncthing 웹 GUI 포트
Cache Assets	비활성화	실시간 상태 반영을 위해 캐싱하지 않음
Block Common Exploits	활성화	기본적인 웹 공격 방어
Websockets Support	활성화 (필수)	실시간 동기화 상태 업데이트를 위함

NPM 고급 설정 (Advanced)

[Advanced] 탭에 아래 코드를 붙여넣어 프록시 헤더를 올바르게 전달하고, 대용량 파일 업로드 제한을 해제합니다.

# Syncthing Host Check 통과 및 대용량 요청 허용
location / {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # 클라이언트 요청 본문 크기 제한 해제 (설정 변경 시 필요)
    client_max_body_size 0;

    # 프록시 버퍼 설정 (UI 반응성 개선)
    proxy_buffering off;
    
    proxy_pass $forward_scheme://$server:$port;
}

SSL 탭에서 Let's Encrypt 인증서를 발급받고 Force SSL과 HSTS Enabled를 활성화하여 모든 접속을 HTTPS로 강제하는 것을 잊지 마십시오.

4단계: 안정적인 동기화를 위한 고급 팁

릴레이(Relay) 비활성화: 두 기기가 같은 내부 네트워크에 있거나 포트 포워딩을 통해 직접 연결이 가능한 경우, 성능 향상을 위해 [Actions] > [Settings] > [Connections] 탭에서 Enable Relaying 옵션을 비활성화할 수 있습니다.
파일 버전 관리(Versioning): 실수로 파일을 덮어쓰거나 삭제하는 상황을 방지하고 싶다면, 공유 폴더 설정의 [File Versioning] 탭에서 'Staggered File Versioning' 같은 옵션을 활성화하세요. 지정된 기간 동안 파일의 이전 버전을 보관해 줍니다.
데이터 전송 포트 포워딩: 외부 네트워크의 기기와 원활하게 동기화하려면 공유기(라우터)에서 TCP/UDP 22000번 포트를 NAS의 내부 IP로 포트 포워딩해야 합니다.

주요 오류 및 해결 방법 (Troubleshooting)

1. 오류: "permission denied" 또는 파일 쓰기 실패

원인: PUID 또는 PGID 값이 잘못되었거나, 해당 사용자가 volumes에 지정된 폴더에 대한 읽기/쓰기 권한이 없습니다.
해결:
- SSH에서 id 명령어로 PUID/PGID 값을 다시 확인하고 Stack을 수정 후 업데이트하세요.
- 시놀로지 'File Station'에서 해당 폴더의 속성 > 권한 탭으로 이동하여, 지정한 사용자가 읽기/쓰기 권한을 가졌는지 확인하세요.

2. 오류: 외부에서 접속 불가 또는 동기화 안 됨

원인: 방화벽 또는 포트 포워딩 문제입니다.
해결:
- 시놀로지 제어판 > 보안 > 방화벽에서 6384, 22000, 21027 포트에 대한 허용 규칙이 있는지 확인하세요.
- 공유기(라우터) 관리 페이지에서 22000번 포트가 NAS의 IP로 정확히 포워딩되었는지 재확인하세요.

마무리 및 주요 보안 수칙

Syncthing은 중앙 서버 의존성에서 벗어나 데이터 주권을 되찾을 수 있는 강력한 도구입니다. Portainer Stack을 활용하면 복잡한 설정 과정을 최소화하고 안정적으로 운영할 수 있습니다.

마지막으로, 안전한 사용을 위해 아래 수칙을 항상 기억하십시오.

Device ID 비공개: 각 기기의 고유 ID가 외부에 노출되지 않도록 주의합니다.
주기적인 폴더 확인: 동기화 폴더에 의도치 않은 파일이 생성되거나 삭제되지 않았는지 정기적으로 확인합니다.
방화벽 최적화: 공용 네트워크에서는 VPN을 사용하고, 시놀로지 방화벽에서 Syncthing에 필요한 포트(6384, 22000, 21027)만 허용하도록 설정합니다.

이제 클라우드 비용과 개인정보 걱정 없이, 나만의 완벽한 파일 동기화 시스템을 구축하고 활용해 보세요.

자주 묻는 질문 (FAQ)

Q1: PUID와 PGID 값이 틀리면 어떻게 되나요?
A1: 컨테이너가 NAS의 폴더에 파일을 생성하거나 수정할 권한이 없어 동기화가 실패합니다. Syncthing 웹 UI에서는 'permission denied'와 유사한 오류 메시지가 표시될 수 있습니다.

Q2: Nginx Proxy Manager 설정이 꼭 필요한가요?
A2: 필수는 아닙니다. 내부 네트워크에서만 IP 주소로 접속해 사용한다면 NPM 설정은 필요 없습니다. 하지만 외부에서 도메인으로 안전하게(HTTPS) 접속하여 관리하고 싶다면 설정하는 것이 좋습니다.

Q3: 동기화 속도가 너무 느립니다. 어떻게 해결할 수 있나요?
A3: 먼저 두 기기가 직접 연결되었는지 확인하세요. UI에 'Relayed (slow)'라고 표시된다면, 중간 서버를 경유하고 있다는 의미입니다. 공유기에서 22000번 포트 포워딩이 올바르게 설정되었는지 확인하고, 방화벽이 연결을 차단하고 있지 않은지 점검해야 합니다.

More Stories from Author
다른 주제도 보고 싶다면 아래에서 더 둘러봐주세요. 방문해주시면 큰 힘이 됩니다.
Flutter&일본어공부 블로그: https://kage2kapp.org/
JLPT N1 문제PDF: https://is.gd/44HpEy
유튜브: https://www.youtube.com/@heesungjin8554

📱 필자가 만든 앱(LIST)

외국어 학습이 더 쉬워지도록 그리고,
일상이 조금 더 편해지도록 만들고 있어요.

🍎 App Store → https://is.gd/Qw2aIq
🤖 Google Play → https://is.gd/JvwAZr

문의사항은 flutterkage2k@gmail.com

Syncthing with Portainer Stack 완벽 가이드

Syncthing이란? 클라우드 서비스와 비교

시작 전 필수 확인 사항

1단계: Portainer Stack으로 Syncthing 배포하기

PUID 및 PGID 확인 방법

Syncthing Stack YAML 코드

Stack 설정 핵심 포인트 분석

2단계: Syncthing 초기 설정 및 보안 강화

3단계: Nginx Proxy Manager(NPM)로 외부 접속 설정 (선택)

NPM 프록시 호스트 설정

NPM 고급 설정 (Advanced)

4단계: 안정적인 동기화를 위한 고급 팁

주요 오류 및 해결 방법 (Troubleshooting)

1. 오류: "permission denied" 또는 파일 쓰기 실패

2. 오류: 외부에서 접속 불가 또는 동기화 안 됨

마무리 및 주요 보안 수칙

자주 묻는 질문 (FAQ)

일본어 감사 표현: 助かります, 恐縮です, マジ感謝 뉘앙스 차이

일본어 内(うち)와 外(そと) 차이: '우리'를 구분하는 우치소토 문화

Syncthing이란? 클라우드 서비스와 비교

시작 전 필수 확인 사항

1단계: Portainer Stack으로 Syncthing 배포하기

PUID 및 PGID 확인 방법

Syncthing Stack YAML 코드

Stack 설정 핵심 포인트 분석

2단계: Syncthing 초기 설정 및 보안 강화

3단계: Nginx Proxy Manager(NPM)로 외부 접속 설정 (선택)

NPM 프록시 호스트 설정

NPM 고급 설정 (Advanced)

4단계: 안정적인 동기화를 위한 고급 팁

주요 오류 및 해결 방법 (Troubleshooting)

1. 오류: "permission denied" 또는 파일 쓰기 실패

2. 오류: 외부에서 접속 불가 또는 동기화 안 됨

마무리 및 주요 보안 수칙

자주 묻는 질문 (FAQ)

일본어 감사 표현: 助かります, 恐縮です, マジ感謝 뉘앙스 차이

일본어 内(うち)와 外(そと) 차이: '우리'를 구분하는 우치소토 문화

You might also like...