커뮤니티 솔루션

원격 액세스를 위해 ZimaOS에서 Tailscale 실행하는 방법

A ZimaOS 1.2.5 user installed the Tailscale App Store package but its WebUI link only returned to ZimaOS. Community replies showed that the container should be authenticated through TS_AUTHKEY or the Tailscale CLI rather than treated like a normal web application.

Tailscale 앱이 ZimaOS에 설치되었지만 WebUI를 클릭했을 때 ZimaOS 대시보드로 단순히 돌아간다고 해서 반드시 Tailscale 컨테이너가 고장 난 것은 아닙니다. 2024년 11월 커뮤니티 스레드는 ZimaOS 1.2.5에서 정확히 이러한 증상으로 시작되었습니다. 유용한 해결책은 Tailscale이 일반적인 애플리케이션 WebUI가 아니라 인증, 환경 변수 및 Tailscale CLI를 통해 주로 구성된다는 점이었습니다.

기존 답변에서는 App Store 패키지를 사용하고 Tailscale 인증 키를 다음 위치에 제공할 것을 권장했습니다. TS_AUTHKEY. 이후 2025년 ZimaOS 스레드에서는 또 다른 작동 방법을 확인했습니다. Tailscale을 설치하고 다음을 실행하세요. tailscale status CLI에서 반환된 로그인 URL을 열고 노드를 인증하세요. 현재 Tailscale Docker 문서는 인증 키 기반 및 로그인 기반 워크플로를 모두 지원하며, 컨테이너가 재시작 후에도 동일한 노드 ID를 유지하도록 영구 상태를 사용할 것을 권장합니다.

Tailscale “WebUI” 링크가 혼동을 일으킬 수 있는 이유

기존 사용자는 설치 후 앱이 관리 페이지를 열 것으로 예상했습니다. 그러나 브라우저는 ZimaOS 홈페이지로 돌아갔습니다.

기존 커뮤니티 보고서의 ZimaOS App Store Tailscale 설치 화면
해당 출처 스레드에서는 WebUI 링크가 일반적인 앱 페이지처럼 작동하지 않았지만 ZimaOS에 Tailscale이 성공적으로 설치된 것을 보여 줍니다.
기존 2024년 커뮤니티 스레드에 표시된 ZimaOS Tailscale 앱 세부 정보
유용한 구성은 독립적인 WebUI가 아니라 Tailscale 컨테이너 설정과 인증 흐름에 있습니다.

기존 커뮤니티 해결 방법: TS_AUTHKEY 사용

첫 번째 답변에서는 인증 키를 생성하여 다음 위치에 붙여 넣으면 App Store 패키지를 사용할 수 있다고 했습니다.

TS_AUTHKEY

현재 Tailscale 문서에서도 다음을 정의합니다. TS_AUTHKEY Docker 컨테이너를 tailnet에 인증하는 데 사용되는 환경 변수입니다.

현재 참조 문서: Tailscale Docker 구성 매개변수.

Tailscale 관리 콘솔에서 키를 생성한 다음, 보안 비밀로 취급하세요. 스크린샷, 포럼 게시물, Git 리포지토리 또는 공유 Compose 파일에 게시하지 마세요.

대안: Tailscale CLI를 통한 인증

이후 ZimaOS 커뮤니티 솔루션에서는 다음 방법을 사용했습니다.

tailscale status

노드가 아직 인증되지 않은 경우, Tailscale은 로그인 URL을 반환했습니다. 사용자는 브라우저에서 해당 URL을 열고 장치를 승인했습니다.

설치된 컨테이너와 셸 컨텍스트에 따라 ZimaOS 호스트에서 직접 명령을 실행하는 대신 Tailscale 컨테이너 내부에서 실행해야 할 수 있습니다.

먼저 컨테이너를 식별합니다.

docker ps --format '{{.Names}}' | grep -i tailscale

그런 다음 필요한 경우:

docker exec -it TAILSCALE_CONTAINER tailscale status

시스템에 표시되는 실제 컨테이너 이름을 사용합니다.

다시 시작해도 Tailscale 상태 유지

현재 Tailscale Docker 문서에서는 다음 설정을 권장합니다.

TS_STATE_DIR=/var/lib/tailscale

해당 디렉터리를 영구 호스트 스토리지에 마운트합니다. 영구 상태가 없으면 다시 시작되거나 재생성된 컨테이너가 이전 ID를 유지하는 대신 새 노드로 등록될 수 있습니다.

Tailscale은 다음 기능도 제공합니다.

TS_AUTH_ONCE=true

컨테이너에 기존 상태가 없을 때만 인증해야 하는 배포의 경우.

현재 컨테이너 설정에 필요한 사항

최소한의 개념적 Docker 설정에는 다음이 포함됩니다.

environment:
  - TS_AUTHKEY=YOUR_SECRET_KEY
  - TS_STATE_DIR=/var/lib/tailscale
  - TS_AUTH_ONCE=true

volumes:
  - /YOUR/ZIMAOS/PERSISTENT/PATH:/var/lib/tailscale

정확한 호스트 경로와 추가 네트워크/장치 설정은 ZimaOS 앱 스토어 정의에 따라 달라집니다. 2024년 스레드에서 CasaOS 튜토리얼로 연결되었다는 이유만으로 작동 중인 현재 앱 정의를 오래된 CasaOS YAML로 교체하지 마세요.

ZimaOS에 액세스하는 것과 전체 LAN을 광고하는 것은 다릅니다

일반적인 목표는 두 가지입니다.

  • 자체 Tailscale 노드에 연결: Tailscale 주소 또는 MagicDNS 이름을 사용하여 ZimaOS/Tailscale 노드에 연결합니다.
  • ZimaOS LAN의 다른 장치에 연결: 노드를 Tailscale 서브넷 라우터로 구성합니다.

두 번째 목표는 더 복잡합니다. 현재 Tailscale 문서에 따르면 라우터는 경로를 광고해야 하며 해당 경로는 관리자 콘솔에서 승인되어야 합니다.

Tailscale 서브넷 라우터 문서를 참조하세요.

Docker화된 ZimaOS Tailscale 앱의 서브넷 라우팅에는 추가 요구 사항이 있습니다

2026년 ZimaOS 커뮤니티 보고서에서는 성공적으로 연결되었지만 LAN 경로를 광고하지 못한 Tailscale Docker 컨테이너가 소개되었습니다. 해당 설정에는 호스트 네트워킹, 권한 모드 및 /dev/net/tun그럼에도 서브넷 경로는 여전히 표시되지 않았습니다.

중요한 경계가 있습니다. tailnet에 성공적으로 참여한 컨테이너가 자동으로 작동하는 서브넷 라우터가 되는 것은 아닙니다. 라우팅에는 커널/네트워크 권한, 포워딩, 경로 광고 및 관리자 승인이 필요합니다.

ZimaOS 자체에 원격으로 접속하는 것이 유일한 목적이라면 서브넷 라우팅을 불필요하게 활성화하지 마세요.

Tailscale에는 SMB 게스트 액세스가 필요하지 않습니다

2024년 커뮤니티 답변에서는 Tailscale 터널을 통해 SMB 폴더 공유가 작동하려면 게스트 권한이 필요하다고 주장했습니다. 이를 현재 Tailscale의 요구 사항으로 일반화해서는 안 됩니다.

Tailscale은 네트워크 연결을 제공합니다. SMB 인증은 독립적인 Samba/Windows/macOS 권한 계층으로 유지됩니다. 적절히 구성된 명명된 SMB 계정은 LAN을 통해 사용할 수 있는 것처럼 Tailscale 경로를 통해서도 사용할 수 있습니다.

게스트 액세스는 이전 논의에서 사용된 특정 CasaOS/ZimaOS Samba 구성의 해결 방법이었을 수 있지만, Tailscale에 본질적으로 필요한 것은 아닙니다.

보안 참고 사항

  • 배포 요구 사항에 따라 범위가 제한된 재사용 가능 인증 키 또는 일회성 인증 키를 사용하세요.
  • 스크린샷과 리포지토리에 인증 키가 노출되지 않도록 하세요.
  • 노드가 반복해서 다시 등록되지 않도록 상태를 영구 저장하세요.
  • Tailscale ACL 또는 grants를 사용하여 어떤 tailnet 장치가 ZimaOS 노드에 연결할 수 있는지 제어하세요.
  • 원격 액세스가 필요하다는 이유만으로 ZimaOS 대시보드를 공용 인터넷에 직접 노출하지 마세요.

ZimaOS Tailscale 설정 체크리스트

  1. 현재 Tailscale App Store 패키지를 설치하세요.
  2. 앱의 WebUI 링크를 기본 구성 방법으로 사용하지 마세요.
  3. 다음으로 인증 TS_AUTHKEY 또는 Tailscale CLI 로그인 URL을 사용하세요.
  4. 다음 경로에 영구 저장 /var/lib/tailscale 다음을 사용하여 TS_STATE_DIR.
  5. 노드가 Tailscale 관리자 콘솔에 표시되는지 확인하세요.
  6. 실행 tailscale status 그리고 노드가 연결되어 있는지 확인하세요.
  7. 서브넷 라우팅을 시도하기 전에 ZimaOS 노드에 액세스할 수 있는지 테스트하세요.
  8. 전체 LAN이 필요한 경우 서브넷 경로를 별도로 구성하고 승인하세요.

ZimaOS 및 Tailscale FAQ

Tailscale WebUI 링크가 ZimaOS로 돌아가는 이유는 무엇인가요?

Tailscale 컨테이너는 일반적으로 기존 앱 WebUI가 아니라 환경 변수, 인증 및 CLI 명령을 통해 구성됩니다. 원본 스레드에서도 바로 이 부분이 혼동의 원인이었습니다.

TS_AUTHKEY란 무엇인가요?

이는 컨테이너를 tailnet에 인증하는 데 사용되는 Tailscale Docker 환경 변수입니다.

TS_STATE_DIR를 영구 저장해야 하는 이유는 무엇인가요?

영구 상태를 사용하면 컨테이너가 재시작되거나 다시 생성된 후에도 노드 ID와 인증 정보를 유지할 수 있습니다.

ZimaOS에 원격으로 액세스하려면 서브넷 라우팅이 필요한가요?

아니요. 서브넷 라우팅은 Tailscale 노드가 로컬 네트워크의 다른 Tailscale이 아닌 장치로 트래픽을 라우팅해야 할 때만 필요합니다.

Tailscale을 통한 SMB에 게스트 모드가 필요한가요?

일반적인 Tailscale 규칙으로는 그렇지 않습니다. SMB 계정 인증은 Tailscale 네트워킹과 별개입니다.

Related Community

CommunitySep 11, 2026CasaOS 또는 ZimaOS에 Apache Guacamole 안전하게 설치하기A 2023 CasaOS tutorial introduced Apache Guacamole through BigBearCasaOS as a browser gat...CommunitySep 08, 2026기본 IceWhale 앱 스토어인 BigBearCasaOS: ‘사전 설치’의 의미와 유지 관리 주체A March 2025 community announcement saying BigBearCasaOS would be available by default ac...CommunitySep 04, 2026CasaOS에 LinuxServer 타사 앱 스토어를 추가하는 방법A 2023 video tutorial showing how to add WisdomSky's CasaOS LinuxServer catalog as a thir...CommunitySep 04, 2026한 커뮤니티 회원이 CasaOS에 AdGuard Home을 도입한 방법Christopher shared a video tutorial introducing AdGuard Home on CasaOS as a way to block ...CommunitySep 04, 2026커뮤니티 동영상으로 BigBearCasaOS 앱 스토어가 추가된 과정Christopher shared a video walkthrough for adding the community-maintained BigBearCasaOS ...