juanfont/headscale

Tailscale 제어 서버의 오픈 소스 자가 호스팅 구현체입니다.

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

참고: 올바른 예제 구성을 확인하려면 항상 사용 중인 릴리스 버전과 동일한 GitHub 태그를 선택해야 합니다. main 브랜치에는 아직 출시되지 않은 변경 사항이 포함되어 있을 수 있습니다. 안정 버전 및 개발 버전의 문서는 다음과 같습니다:

Tailscale은 Wireguard를 기반으로 구축된 최신 VPN입니다. NAT 트래버설(NAT traversal)을 사용하여 네트워크 내 컴퓨터 간에 오버레이 네트워크처럼 작동합니다.

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

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

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

Headscale은 Tailscale 제어 서버의 자가 호스팅 오픈 소스 대안을 구현하는 것을 목표로 합니다. Headscale의 목표는 자가 호스팅 사용자 및 취미 개발자들에게 자신들의 프로젝트와 실험실에 사용할 수 있는 오픈 소스 서버를 제공하는 것입니다. 이는 개인적인 사용 또는 작은 오픈 소스 조직에 적합한 단일 Tailscale 네트워크(tailnet)라는 좁은 범위를 구현합니다.

만약 headscale이 마음에 들고 유용하다고 생각된다면, 레포지토리에서 스폰서십 및 기부 버튼을 이용할 수 있습니다.

문서의

브랜치들은 컨테이너 이미지와 바이너리 형태로 이용 가능합니다. 자세한 내용은 개발 빌드 문서를 참고하십시오.

• Fosdem 2026 (영상): Headscale & Tailscale: 상호 보완적인 오픈 소스 클론을 소개합니다

  • 발표자: Kristoffer Dalby

• Fosdem 2023 (영상): Headscale: 통합 테스트를 활용하여 Tailscale을 재구현하는 방법

  • 발표자: Juan Font Alonso 및 Kristoffer Dalby

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

하지만, Headscale의 활동적인 유지 관리자 중 한 명은 Tailscale에 고용되어 있으며, 근무 시간 일부를 이 프로젝트 기여에 할애하는 것이 허가되었습니다. 이 유지 관리자의 기여는 다른 유지 관리자에 의해 검토됩니다.

유지 관리자들은 함께 프로젝트의 방향을 설정합니다. 근본적인 원칙은 지속 가능한 프로젝트를 유지하면서 셀프 호스팅 사용자, 애호가 및 취미 개발자 커뮤니티에 봉사하는 것입니다.

CONTRIBUTING.md 파일을 읽어주십시오.

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

개발 환경 설정에는 Nix 사용을 권장합니다. 이는 nix develop를 사용하여 수행할 수 있으며, 이 명령은 도구를 설치하고 셸을 제공합니다. 이를 통해 headscale 유지 관리자와 동일한 개발 환경을 보장받을 수 있습니다.

증가하는 기여에 대한 일관성을 확보하기 위해, 본 프로젝트는 린팅 및 스타일/포맷 규칙을 채택했습니다:

Go 코드는 golangci-lint로 린트되고, golines(너비 88)와 gofumpt로 포맷됩니다.
개발하는 동안 에디터를 구성하여 이 도구들을 실행하고, 코드를 커밋하기 전에 반드시 make lint 및 make fmt를 실행하십시오.

Proto 코드는 buf로 린트되고, clang-format으로 포맷됩니다.

**문서(docs)**는 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에서 제작됨.