netbird

netbirdio活跃维护

基于 WireGuard 的点对点零信任网络平台，用统一身份把人员、机器和 AI 代理安全接入任意网络，无需复杂 VPN 配置。

NetBird securely connects people, machines and AI agents across any network with one identity-based Zero Trust platform. Powered by peer-to-peer WireGuard®

v0.82.0发布于 2026-10-29 13:56 UTC30,860star +90 / 7 天1,845fork同步于 2026-11-10 11:21 UTC

零信任网络 WireGuard 点对点组网 NAT 穿透身份认证

对比 GitHub 官网 golang mesh mesh-networks nat-traversal netbird

怎么上手

由 README 提炼，执行前请确认

原文

export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

硬件要求按 README 说明

自托管需一台至少 1 CPU、2 GB 内存的 Linux VM，公网开放 TCP 80/443 与 UDP 3478，并准备指向该 VM 的域名；客户端侧 README 未说明具体硬件或显存要求。

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼

没人工点评？写下你的经验

基于 WireGuard 的点对点私有网络与集中访问控制平台，免开端口免配防火墙

基于 WireGuard 的点对点零信任网络平台，用统一身份把人员、机器和 AI 代理安全接入任意网络，无需复杂 VPN 配置。

核心能力

用 WireGuard 建立加密覆盖网络，自动打通机器间隧道
通过 ICE/STUN 协商点对点连接，NAT 失败时回退中继
集中管理分组与访问规则，支持 SSO、MFA 与设备姿态检查
提供自托管快速启动脚本与 Terraform、Ansible 自动化
覆盖 Linux、macOS、Windows、iOS、Android 及容器等多平台

容易踩的坑

自托管需 Docker 及 Compose v2 以上版本，且必须有公网域名和开放 80/443/3478 端口；客户端需先安装并注册到管理服务才能组网；提交问题前需先在 Discussions 中反馈而非直接开 issue。

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

Release Notes for v0.82.0

Highlights

🛣️ Latency-aware HA routing that holds stable routes

Routing peers in an HA group with equal metrics are meant to be chosen by latency, but the client used to sample latency only once, when the connection was set up, and moved the route on events that did not need it. Every switch between masquerading routing peers resets the TCP connections using the route, so SSH sessions and other long-lived flows dropped more often than they had to.

The client now samples the latency of connected routing peers continuously and smooths it, and moves a route for latency only when the gain clears a margin: at least 20ms, 20% of the current latency, and the measurement noise of both paths. After a latency-driven switch it keeps the new peer for at least 30 seconds. A routing peer that drops from direct to relay keeps the route for a grace period before it moves to an equivalent direct peer, and a peer that comes up over relay first is held the same way while the others turn direct. Failover, better metrics and connected-over-idle still switch immediately.

The grace period is set on the client with NB_HA_RELAYED_SWITCH_DELAY (a duration, 0, or never; default 30s). Routing peer switches are now logged at warning level with the reason and published as system events, so they show in netbird status -d and in debug bundles.

📖 High availability for routing peers · #7689, #8192

📋 `netbird status --table`

netbird status --table (-t) lists peers in a table with their name, IP, status, connection type, latency and traffic, which is easier to scan than the detailed output on a large network. It works with the existing filter flags, so netbird status -t -S connected -T P2P shows only connected peer-to-peer peers.

Peers (3/5 connected):
NAME          IP            STATUS       CONN      LATENCY   RX / TX
web-01        100.64.0.12   Connected    P2P       12ms      1.2 MiB / 3.4 MiB
db-01         100.64.0.15   Connected    Relayed   48ms      54.0 KiB / 12.1 KiB
ci-runner     100.64.0.40   Connecting   -         -         0 B / 0 B

--table cannot be combined with -d, --json, --yaml, --ipv4 or --ipv6.

📖 CLI: status, table view · #8305

🗄️ A dedicated database for reverse proxy access logs

Reverse proxy access logs are now read and written through their own database connection instead of the main store's, and can live in a separate database. Nothing needs to change on upgrade: by default the access log store follows the main store engine, as a separate access_logs.db file in the data directory on SQLite, or the main store DSN through its own connection pool on PostgreSQL.

To point it elsewhere, set server.accessLogStore (engine, dsn, file) in the combined server's config.yaml, or the environment variables below:

Variable	Purpose
`NB_ACCESS_LOG_STORE_ENGINE`	`sqlite` or `postgres`
`NB_ACCESS_LOG_POSTGRES_DSN`	a dedicated PostgreSQL database
`NB_ACCESS_LOG_SQLITE_FILE`	the SQLite file, `access_logs.db` by default
`NB_ACCESS_LOG_SQL_MAX_OPEN_CONNS`	pool size, falling back to `NB_SQL_MAX_OPEN_CONNS`

📖 Reverse proxy access logs · #8303

Removal: MySQL store

The MySQL store engine for management, deprecated in v0.81.0, is removed. A management server configured with the mysql engine refuses to start on v0.82.0 and points to the migration guide.

**Migrate to PostgreSQL

v0.82.0-rc.1pre-release2026-10-26 · 2026-10-26 18:16 UTC
查看更新说明
Breaking changes
- MySQL has been removed. To upgrade, you must follow the migration docs to postgres: https://docs.netbird.io/selfhosted/migration/mysql-to-postgresql
- Reverse proxy access logs move to their own database. Nothing to configure: by default they follow your main store (a separate access_logs.db on SQLite, the same DSN on PostgreSQL). A new optional accessLogStore section lets you point them elsewhere. This means logs will stay in the old database file, but the dashboard/management API will only report from the new one.
Deprecation notice
- Rosenpass will be marked as deprecated, and a replacement is in the final testing phase
What's Changed
- [client] Bump wireguard-go to bd0cb75a3df0 by @pappz in https://github.com/netbirdio/netbird/pull/8229
- [management] Return the reason when custom domain validation fails by @thomashacker in https://github.com/netbirdio/netbird/pull/8122
- [client,relay] Bump quic-go to v0.64.0 by @riccardomanfrin in https://github.com/netbirdio/netbird/pull/8249
- [misc] Fix errcheck findings from the latest golangci-lint by @lixmal in https://github.com/netbirdio/netbird/pull/8251
- New Crowdin updates by @netbirddev in https://github.com/netbirdio/netbird/pull/8101
- [client] Add Hebrew to the language picker by @thomashacker in https://github.com/netbirdio/netbird/pull/8102
- [client] Avoid Signal reconnect listener shutdown deadlock by @mlsmaycon in https://github.com/netbirdio/netbird/pull/8257
- [management] Add support for pagination in GetAllPeers call by @dmitri-netbird in https://github.com/netbirdio/netbird/pull/8190
- [misc] Announce tag-pushed releases on the forum by @riccardomanfrin in https://github.com/netbirdio/netbird/pull/8265
- [client] Fix grammatical error in post-install message by @alireza-hdri in https://github.com/netbirdio/netbird/pull/8242
- [management] Mask credentials in logged URLs by @bcmmbaga in https://github.com/netbirdio/netbird/pull/8250
- [client] Keep the resolv.conf watch armed while repairing DNS in file mode by @riccardomanfrin in https://github.com/netbirdio/netbird/pull/8207
- [client] Drop the non-functional admin URL by @mlsmaycon in https://github.com/netbirdio/netbird/pull/8267
- [misc] Let suites outside the module reach the e2e harness network by @mlsmaycon in https://github.com/netbirdio/netbird/pull/8260
- [management] Remove the MySQL store engine by @bcmmbaga in https://github.com/netbirdio/netbird/pull/7914
- [relay] Negotiate the protocol version on the server side by @pappz in https://github.com/netbirdio/netbird/pull/8231
- [client] Migrate the desktop UI to Tailwind CSS 4 and fix frontend npm audit findings by @heisbrot in https://github.com/netbirdio/netbird/pull/8277
- [management] Use account owner as inviter for service user invites by @bcmmbaga in https://github.com/netbirdio/netbird/pull/8276
- [management] Make EDR sync interval configurable by @bcmmbaga in https://github.com/netbirdio/netbird/pull/8273
- [management] Give the /api/setup owner account the single account mode domain by @smrrazavian in https://github.com/netbirdio/netbird/pull/8147
- [client] Stop the service and UI before the NSIS installer extracts files by @emrcbrn in https://github.com/netbirdio/netbird/pull/8255
- [infrastructure] Increase WASM build size to 70MB by @theodorsm in https://github.com/netbirdio/netbird/pull/8281
- [client] Remove the replace directives from the embedded client by @lixmal in https://github.com/netbirdio/netbird/pull/8280
- [management] Skip inactivity expiration rescan on connect when a job is scheduled by @mlsmaycon in https://github.com/netbirdio/netbird/pull/8287
- [management] Add additional indexes for groups, events, pats and access logs by @pascal-fischer in https://github.com/netbirdio/netbird/pull/8289
- [management] reduce calls to update last usage for users and pats by @pascal-fischer in https://github.com/netbirdio/netbird/pull/8290
- [management] remove ac
v0.81.52026-10-26 · 2026-10-26 17:38 UTC
查看更新说明
What's Changed
- [client] Validate and bound SSH session requests and channels (#8344) by @lixmal in https://github.com/netbirdio/netbird/pull/8368
- [client] Bound the SSH session request queue and keep resizes from blocking the session loop (#8363) by @lixmal in https://github.com/netbirdio/netbird/pull/8369
Full Changelog: https://github.com/netbirdio/netbird/compare/v0.81.4...v0.81.5
v0.81.42026-10-24 · 2026-10-24 11:24 UTC
查看更新说明
What's Changed
- [client] Drop SSH privileges through libc in PKCS#11 package builds (https://github.com/netbirdio/netbird/pull/8323) (https://github.com/netbirdio/netbird/pull/8331)
- [client,proxy,management,signal,relay] Distrust compromised eMudhra CA keys (#8326) by @mlsmaycon in https://github.com/netbirdio/netbird/pull/8328
- [client] Drop SSH privileges through libc in PKCS#11 package builds (#8323) by @lixmal in https://github.com/netbirdio/netbird/pull/8331
Full Changelog: https://github.com/netbirdio/netbird/compare/v0.81.3...v0.81.4

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

🤖 NetBird Agent Network (Beta)

Identity-aware access control for AI agents — keyless access to LLM APIs and private resources over the encrypted NetBird tunnel. See agent-network/ or read the docs at netbird.ai.

NetBird combines a configuration-free peer-to-peer private network and a centralized access control system in a single platform, making it easy to create secure private networks for your organization or home.

Connect. NetBird creates a WireGuard-based overlay network that automatically connects your machines over an encrypted tunnel, leaving behind the hassle of opening ports, complex firewall rules, VPN gateways, and so forth.

Secure. NetBird enables secure remote access by applying granular access policies while allowing you to manage them intuitively from a single place. Works universally on any infrastructure.

https://github.com/user-attachments/assets/10cec749-bb56-4ab3-97af-4e38850108d2

Self-host NetBird (video)

Key features

Connectivity	Management	Security	Automation	Platforms
✓ Kernel WireGuard	✓ Admin Web UI	✓ SSO & MFA support	✓ Public API	✓ Linux
✓ Peer-to-peer connections	✓ Auto peer discovery and configuration	✓ Access control: groups & rules	✓ Setup keys for bulk provisioning	✓ macOS
✓ Connection relay fallback	✓ IdP integrations	✓ Activity logging	✓ Self-hosting quickstart script	✓ Windows
✓ Routes to external networks	✓ Private DNS	✓ Traffic events	✓ IdP groups sync with JWT	✓ Android
✓ Domain-based DNS routes	✓ Custom DNS zones	✓ Device posture checks	✓ Terraform provider	✓ Android TV
✓ Exit nodes	✓ Multiuser support	✓ Peer-to-peer encryption	✓ Ansible collection	✓ iOS
✓ IPv6 dual-stack overlay	✓ Multi-account profile switching	✓ SSH with central access policies		✓ Apple TV
✓ Browser SSH & RDP		✓ Quantum-resistance with Rosenpass		✓ FreeBSD
✓ Reverse proxy with auto-TLS		✓ Periodic re-authentication		✓ pfSense
				✓ OPNsense
				✓ MikroTik RouterOS
				✓ OpenWRT
				✓ Synology
				✓ TrueNAS
				✓ Proxmox
				✓ Raspberry Pi
				✓ Serverless
				✓ Container

Quickstart with NetBird Cloud

Download and install NetBird at https://app.netbird.io/install.
Follow the steps to sign up with Google, Microsoft, GitHub or your email address.
Check the NetBird admin UI.

Quickstart with self-hosted NetBird

This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM. Follow the Advanced guide with a custom identity provider for installations with different IdPs.

Infrastructure requirements:

A Linux VM with at least 1 CPU and 2 GB of memory.
The VM should be publicly accessible on TCP ports 80 and 443 and UDP port 3478.
A public domain name pointing to the VM.

Software requirements:

Docker with the Compose plugin (Compose v2 or higher). See the Docker installation guide.

Steps

Download and run the installation script:

export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

A bit on NetBird internals

Every machine in the network runs the NetBird agent, which manages WireGuard.
Every agent connects to the Management Service, which holds network state, manages peer IPs, and distributes updates to agents.
Agents use ICE (via pion/ice) to discover connection candidates for peer-to-peer connections.
Candidates are discovered with the help of STUN servers.
Agents negotiate a connection through the Signal Service, exchanging end-to-end encrypted messages with candidates.
When NAT traversal fails (e.g. mobile carrier-grade NAT) and a direct p2p connection isn't possible, the system falls back to a Relay Service and a secure WireGuard tunnel is established through it.

See a complete architecture overview for details.

Reporting bugs and requesting features

NetBird uses a discussion-first workflow. Bug reports and feature requests start in Discussions, not as issues.

What you want to do	Where to go
Report a bug, regression, or unexpected behavior	Issue Triage
Request a feature or share an idea	Ideas & Feature Requests
Ask about setup, configuration, or self-hosting	Q&A / Support
Report a security vulnerability	Security policy, never a public thread

Our team and maintainers triage discussions, ask follow-up questions, check for duplicates, and reproduce bugs. Validated reports are promoted to issues. This keeps the issue tracker a clear answer to one question: what is the team working on.

Please search existing discussions and issues first, including closed ones. If something similar already exists, upvote it and add your details there instead of opening a duplicate.

For bug reports, include your NetBird version, operating system, deployment type (Cloud, self-hosted, Kubernetes, or Docker), reproduction steps, expected and actual behavior, and a debug bundle where relevant:

netbird version
netbird status -d -A
netbird debug for 1m -A -S -U

-U uploads the bundle and prints a file key you can paste instead of attaching the archive. -A anonymizes the output, which matters on a public thread. It masks most identifying details but is not full redaction, so read the bundle before posting it. Two levels are available:

Level	How to select	What it masks
`default`	`-A` / `--anonymize`	Public IP addresses, IPv6 ULA addresses, MAC addresses, and domains other than `netbird.io`, `netbird.cloud`, `netbird.selfhosted`, and `netbird.stage`. IPv4 private, CGNAT, and link-local ranges are kept
`strict`	`--anonymize-level strict` (implies `-A`)	The above, plus IPv4 private, CGNAT, and link-local ranges, peer names in front of `netbird.cloud`, `netbird.selfhosted`, and `netbird.stage`, and WireGuard public keys. Labels under `netbird.io` are kept, since it only hosts infrastructure

See collecting a debug bundle and the CLI reference for details.

See How to use Discussions, Issues, and Pull Requests for the full workflow, or SUPPORT.md for a shorter version.

Contributing

Contributions are welcome. Read CONTRIBUTING.md first. NetBird works ticket first, anything that changes behavior needs an issue the team has agreed on before you open a pull request.

Community projects

NetBird installer script
netbird-tui - terminal UI for managing NetBird peers, routes, and settings
caddy-netbird - Caddy plugin that embeds a NetBird client for proxying HTTP and TCP/UDP traffic through NetBird networks

Note: The main branch may be in an unstable or even broken state during development. For stable versions, see releases.

Support acknowledgement

In November 2022, NetBird joined the StartUpSecure program sponsored by the Federal Ministry of Education and Research of the Federal Republic of Germany. Together with the CISPA Helmholtz Center for Information Security, NetBird brings security best practices and simplicity to private networking.

CISPA_Logo_BLACK_EN_RZ_RGB (1)

Acknowledgements

We build on open source technologies like WireGuard®, Pion ICE, and Rosenpass. We greatly appreciate the work these projects are doing, and we'd love it if you could support them too (e.g., by starring or contributing).

Legal

This repository is licensed under the BSD-3-Clause license, which applies to all parts of the repository except for the directories management/, signal/ and relay/. Those directories are licensed under the GNU Affero General Public License version 3.0 (AGPLv3). See the respective LICENSE files inside each directory.

WireGuard and the WireGuard logo are registered trademarks of Jason A. Donenfeld.

怎么上手

项目说明

核心能力

容易踩的坑

最近发版

Changelog

Release Notes for v0.82.0

Highlights

🛣️ Latency-aware HA routing that holds stable routes

📋 netbird status --table

🗄️ A dedicated database for reverse proxy access logs

Removal: MySQL store

Breaking changes

Deprecation notice

What's Changed

What's Changed

What's Changed

用户点评

README 原文

🤖 NetBird Agent Network (Beta)

Self-host NetBird (video)

Key features

Quickstart with NetBird Cloud

Quickstart with self-hosted NetBird

A bit on NetBird internals

Reporting bugs and requesting features

Contributing

Community projects

Support acknowledgement

Acknowledgements

Legal

相关项目

📋 `netbird status --table`