headscale v0.29.3

Tailscale 컨트롤 서버의 오픈 소스, 셀프 호스팅 구현체입니다.

채팅을 위해 Discord 서버에 참여하세요.

참고: 올바른 예제 구성을 사용하려면 항상 사용 중인 릴리스 버전과 동일한 GitHub 태그를 선택하세요. main 브랜치에는 릴리스되지 않은 변경 사항이 포함되어 있을 수 있습니다. 문서는 안정 버전과 개발 버전 모두에서 제공됩니다:

• 안정 버전 문서
• 개발 버전 문서

Tailscale이란

Tailscale은 Wireguard 위에 구축된 최신 VPN입니다. 이는 NAT 통과를 사용하여 네트워크의 컴퓨터들 사이에서 오버레이 네트워크처럼 동작합니다.

Tailscale의 모든 것은 오픈 소스이며, 독점 OS용 GUI 클라이언트(Windows 및 macOS/iOS)와 컨트롤 서버는 예외입니다.

컨트롤 서버는 Tailscale 네트워크의 노드들을 위한 Wireguard 공개 키의 교환 지점 역할을 합니다. 클라이언트의 IP 주소를 할당하고, 각 사용자 간의 경계를 생성하며, 사용자 간의 머신 공유를 가능하게 하고, 노드의 광고된 경로를 노출합니다.

Tailscale 네트워크(tailnet)는 Tailscale이 개인 사용자 또는 조직의 관점에서 사용자에게 할당하는 사설 네트워크입니다.

설계 목표

Headscale은 Tailscale 컨트롤 서버에 대한 셀프 호스팅, 오픈 소스 대안을 구현하는 것을 목표로 합니다. Headscale의 목표는 셀프 호스터와 취미 개발자에게 자신의 프로젝트와 랩에서 사용할 수 있는 오픈 소스 서버를 제공하는 것입니다. 이는 개인 사용이나 소규모 오픈 소스 조직에 적합한 좁은 범위, 단일 Tailscale 네트워크(tailnet)를 구현합니다.

Headscale 후원

headscale이 마음에 들고 유용하다고 생각하신다면, 저장소에 후원 및 기부 버튼이 마련되어 있습니다.

기능

문서의 "기능"을 참조하세요.

클라이언트 OS 지원

문서의 "클라이언트 및 운영 체제 지원"을 참조하세요.

headscale 실행

Headscale을 실행하기 위해 리버스 프록시와 컨테이너를 사용하는 것은 지원하지 않으며 권장하지 않습니다.

문서를 확인하세요.

NixOS 사용자의 경우 nix/에서 모듈을 사용할 수 있습니다.

main에서의 빌드

main 브랜치의 개발 빌드는 컨테이너 이미지와 바이너리로 제공됩니다. 자세한 내용은 개발 빌드 문서를 참조하세요.

발표

• Fosdem 2026 (영상): Headscale & Tailscale: The complementary open source clone
  • Kristoffer Dalby 발표
• Fosdem 2023 (영상): Headscale: How we are using integration testing to reimplement Tailscale
  • Juan Font Alonso 및 Kristoffer Dalby 발표

면책 조항

이 프로젝트는 Tailscale Inc.와 관련이 없습니다.

다만, Headscale의 활성 메인테이너 중 한 명은 Tailscale에 고용되어 있으며, 근무 시간을 프로젝트 기여에 사용할 수 있도록 허용받고 있습니다. 이 메인테이너의 기여는 다른 메인테이너들이 검토합니다.

메인테이너들은 프로젝트의 방향을 설정하기 위해 협력합니다. 기본 원칙은 지속 가능한 프로젝트를 유지하면서 셀프 호스터, 열정가, 취미 개발자 커뮤니티에 봉사하는 것입니다.

기여

CONTRIBUTING.md 파일을 읽어 주세요.

AI_POLICY.md도 확인해 보세요.

요구 사항

headscale에 기여하려면 최신 버전의 Go와 Buf(Protobuf 생성기)가 필요합니다.

개발 환경을 설정하려면 Nix를 사용할 것을 권장합니다. nix develop을 실행하면 도구가 설치되고 셸이 제공됩니다. 이를 통해 headscale 유지 관리자와 동일한 개발 환경을 보장받을 수 있습니다.

코드 스타일

증가하는 기여에 일관성을 유지하기 위해 이 프로젝트는 린팅 및 스타일/포맷 규칙을 채택했습니다:

Go 코드는 golangci-lint로 린팅되며 golangci-lint 포매터(gofumpt, gci, goimports)로 포맷됩니다. 개발 중에 편집기가 해당 도구를 실행하도록 설정하고, 코드를 커밋하기 전에 make lint와 make fmt를 실행해야 합니다.

Proto 코드는 buf로 린팅되며 clang-format으로 포맷됩니다.

문서는 mdformat으로 포맷됩니다.

나머지(Markdown, YAML 등)는 prettier로 포맷됩니다.

구체적인 설정은 .golangci.yaml과 Makefile을 확인하세요.

개발 도구 설치

• Go
• Buf
• Protobuf 도구

설치 및 활성화:

nix develop

테스트 및 빌드

프로젝트의 일부는 Protobuf로부터 Go 코드 생성이 필요하며 (proto/에 변경 사항이 있는 경우), 다음 명령으로 (재)생성해야 합니다:

make generate

참고: 검토를 용이하게 하기 위해 gen/의 변경 사항을 별도의 커밋으로 체크인하세요.

테스트를 실행하려면:

make test

프로그램을 빌드하려면:

make build

개발 워크플로

필요한 모든 도구를 갖추도록 의존성 관리를 위해 Nix를 사용할 것을 권장합니다. 의존성을 직접 관리하는 것을 선호한다면 Make를 직접 사용할 수 있습니다:

Nix 사용 (권장):

nix develop
make test
make build

직접 의존성을 사용하는 경우:

make test
make build

Makefile은 필수 도구가 누락된 경우 경고하고 nix develop 실행을 제안합니다. 사용 가능한 모든 타깃을 보려면 make help를 실행하세요.

기여자

contrib.rocks로 제작되었습니다.