openZro 是一个基于 [WireGuard®](https://www.wireguard.com/) 的零信任覆盖网络：您接入网络的每台机器都会获得一个平坦、加密的私有局域网，具备 SSO、MFA、状态检查和精细化访问策略 —— 无需端口转发，无需 VPN 网关，无需为每台设备进行手动配置。 它是 [`netbirdio/netbird@v0.52.2`](https://github.com/netbirdio/netbird/tree/v0.52.2) 的一个分支（[上游在 2025 年 8 月将三个核心组件重新许可为 AGPLv3 之前的最后一个 BSD-3 版本](docs/FORK.md)），并在 BSD-3-Clause 许可下继续开发，为希望拥有自由许可、功能完备基线的自托管部署服务。 ## 项目状态 **已投入生产使用。** openZro 已运行于真实生产部署 —— 完整的控制平面（管理 + 信令 + 中继 + 仪表板）运行在 Kubernetes 上，对等点通过 Dex 登录，运维界面每日均在使用。 **仍在开发中。** 代码库迭代迅速。功能开发和近期计划详见 [docs/ROADMAP.md](docs/ROADMAP.md) 和 [未解决的问题](https://github.com/openzro/openzro/issues)；在项目稳定之前，图表值和配置格式可能在版本之间发生变化。 **文档正在完善中。** 少数页面仍逐字复制了上游 NetBird 的措辞，正在根据 [文档一致性审查](https://github.com/openzro/docs/issues/7) 进行更新。 当文档与代码不一致时，以代码为准。 **请试用并告诉我们哪里有问题。** 请提交一个 [问题](https://github.com/openzro/openzro/issues/new/choose) 或发起 [讨论](https://github.com/openzro/openzro/discussions) —— 每一份来自真实部署的报告都有助于塑造下一个版本。 ## 为何选择openZro而非上游NetBird？ | | NetBird ≥ v0.53 | **openZro** | |---|---|---| | `management/`、`signal/`、`relay/` 的**许可** | AGPLv3 | **BSD-3-Clause** | | 功能完备的自托管 | 可行，但任何通过网络提供的修改都需遵守 AGPL 义务 | **仅需遵守 BSD 署名要求，无其他许可义务** | | 每个对等点的更新缓冲区 | 硬编码为 100（超出部分静默丢弃） | **可配置，默认 1000** ([提交](https://github.com/openzro/openzro/commit/17f40f94)) | | 账户扇出并发数 | 硬编码为 10 | **可配置，默认 64** ([提交](https://github.com/openzro/openzro/commit/092ddb6f)) | | 高可用方案 | 需要粘性会话，无原生集群支持 | **通过 Redis 兼容方案（Valkey/Redis/Dragonfly）、外部 NATS 或嵌入式 NATS 实现原生高可用** | | 安全公告回溯 | 不适用（您使用的是当前上游版本） | 记录于 [`docs/security/advisories.md`](docs/security/advisories.md)，进行独立重写实现 | 完整原因记录于 [ADR-0001](docs/adr/0001-openzro-foundation.md)。 ## 架构 ``` ┌──────────────┐ ┌─────────────────┐ │ client │◄────────│ signal-server │ WebRTC ICE candidate exchange │ (WireGuard) │ │ (HA-capable) │ └──────┬───────┘ └─────────────────┘ │ ▼ ┌──────────────┐ ┌─────────────────┐ ┌────────────────┐ │ client │◄────────│ management │◄───────►│ Postgres/MySQL │ │ (WireGuard) │ gRPC │ (HA-capable) │ DB │ (state of │ └──────────────┘ Sync └────────┬────────┘ │ truth) │ │ └────────────────┘ │ pub/sub + locks ▼ ┌───────────────┐ │ Valkey / NATS │ (only required for HA) └───────────────┘ ``` ### 高可用模式（选择一个 —— 仅 ≥2 实例时需要） | 模式 | 运行内容 | 适用场景 | |---|---|---| | **无（单实例）** | management + signal + Postgres/MySQL | 默认选项。开箱即用。 | | **Valkey** *（推荐）* | + Valkey 8（或 Redis 5+，或 Dragonfly） | 与 openZro 同属一个许可家族。 | | **NATS（外部）** | + 一个带 JetStream 的 NATS 2.7+ 代理 | 已有 NATS 运行其他工作负载。 | | **NATS（嵌入式）** | 无需额外组件；每个 openZro 实例启动一个进程内 NATS 服务器 | 除 openZro 本身外无需外部基础设施。 | 通过设置以下**一个**环境变量来激活： ``` OPENZRO_REDIS_URL=valkey://broker:6379/0 # Valkey/Redis/Dragonfly OPENZRO_NATS_URL=nats://broker:4222 # external NATS OPENZRO_BROKER=embedded # embedded NATS OPENZRO_CLUSTER_PEERS=nats://node2:6222,nats://node3:6222 ``` 相同的代理选择同时驱动信令高可用和管理高可用 —— 一份有状态基础设施，服务两个组件。参见 [ADR-0001 §3.4](docs/adr/0001-openzro-foundation.md#34-ha-architecture)。 ## 仓库布局 ``` openzro/ ├── CLAUDE.md Brand & engineering rules (read by Claude Code) ├── design-tokens.md Colors / typography reference ├── brand/ Official brand assets (icon, etc.) ├── client/ WireGuard agent ├── management/ Control plane (gRPC + HTTP API) ├── signal/ WebRTC signaling ├── relay/ TURN-style relay ├── cluster/ Distributed coordinator (HA primitives) ├── dashboard/ Next.js web UI (with its own CLAUDE.md) ├── deploy/ Local docker-compose for dev/HA testing └── docs/ ├── FORK.md Fork-point provenance ├── adr/ Architecture Decision Records └── security/ Security advisories tracking ``` ## 安装 ### 客户端代理 (Linux / macOS / Windows) **Linux** —— 自动检测发行版的一行命令（涵盖通过签名的 apt/yum/zypper 仓库安装的 Debian/Ubuntu/RHEL/Fedora/SUSE，对于 Arch/CachyOS 会回退到 pacman/AUR，其他情况使用二进制 tarball）： ``` curl -fsSL https://pkg.openzro.io/install.sh | sh ``` 手动仓库设置（apt 示例）： ``` curl -sSL https://pkg.openzro.io/openzro-archive-key.asc | \ sudo gpg --dearmor -o /usr/share/keyrings/openzro-archive-keyring.gpg echo 'deb [signed-by=/usr/share/keyrings/openzro-archive-keyring.gpg] \ https://pkg.openzro.io/apt stable main' | \ sudo tee /etc/apt/sources.list.d/openzro.list sudo apt-get update && sudo apt-get install openzro ``` **Windows** —— `.msi` 安装程序 + 用于便携使用的 `.zip`： - 安装程序：[`openzro__windows_amd64.msi`](https://github.com/openzro/openzro/releases/latest) - 系统托盘 UI：解压 `openzro-ui__windows_amd64.zip`，以管理员身份运行 `openzro-ui.exe` MSI 目前未签名（Windows 在首次运行时会显示 SmartScreen 警告；点击 *更多信息 → 仍要运行*）。通过 [SignPath Foundation](https://signpath.org/foundation) 进行 EV 签名的工作已作为 [问题 #1](https://github.com/openzro/openzro/issues/1) 跟踪。 **macOS** —— 通用 `.pkg` 安装程序或 Homebrew tap： ``` # Homebrew（命令行界面） brew install openzro/tap/openzro sudo brew services start openzro # 或从 GH Releases 下载 .pkg 安装程序 # https://github.com/openzro/openzro/releases/latest → # openzro__darwin_universal.pkg ``` `.pkg` 未签名；首次运行可能需要 `xattr -d com.apple.quarantine` 或右键单击 → *打开*。Apple Developer ID 公证已作为 [问题 #2](https://github.com/openzro/openzro/issues/2) 跟踪。 ### 在 Kubernetes 上自托管控制平面 ``` helm repo add openzro https://openzro.github.io/helms helm repo update # 控制平面（管理 + 信号 + 中继 + 仪表盘 + Dex） helm install openzro openzro/openzro \ --create-namespace -n openzro \ -f my-values.yaml # 可选：K8s operator（用于协调对等节点/组/策略的 CRDs） helm install openzro-operator openzro/openzro-operator -n openzro ``` 完整的操作指南参见 [`docs/operator/k8s-deployment-guide.md`](docs/operator/k8s-deployment-guide.md)（values 覆盖、使用 Gateway API 代替 Ingress、运维人员个人访问令牌配置、故障排查）。 ### 在单台虚拟机上自托管控制平面 `infrastructure_files/configure.sh` 会生成 docker-compose 堆栈（management + signal + relay + dashboard + Dex + mTLS PKI）。身份提供方架构参见 [ADR-0006](docs/adr/0006-embed-dex.md)。 ## 快速开始（开发环境） ``` # 1. 本地启动 Postgres + Valkey + NATS make dev.deps.up # 2. 构建 Go 核心 make build # 3. 运行测试 make test ``` 单实例开发环境： ``` export OPENZRO_STORE_ENGINE=postgres export OPENZRO_STORE_ENGINE_POSTGRES_DSN=postgres://openzro:openzro@localhost:5432/openzro?sslmode=disable ./management/management management --datadir=/tmp/openzro ``` 高可用开发环境（选择一个）： ``` # Valkey export OPENZRO_REDIS_URL=valkey://localhost:6379/0 # 外部 NATS export OPENZRO_NATS_URL=nats://localhost:4222 # 嵌入式 NATS（无需代理容器） export OPENZRO_BROKER=embedded export OPENZRO_CLUSTER_PEERS=nats://localhost:6222 ``` `make help` 列出了所有可用目标。 ## 文档 | 文档 | 内容 | |---|---| | [docs/adr/0001-openzro-foundation.md](docs/adr/0001-openzro-foundation.md) | 本分支存在的原因、许可立场、高可用架构 | | [docs/adr/0006-embed-dex.md](docs/adr/0006-embed-dex.md) | 嵌入式 Dex IdP —— 通过 gRPC API 进行联邦认证 | | [docs/adr/0007-client-packaging.md](docs/adr/0007-client-packaging.md) | MSI / PKG / Homebrew / Linux 软件包策略 + 路线图 | | [docs/adr/0008-kubernetes-helm-operator.md](docs/adr/0008-kubernetes-helm-operator.md) | Helm chart + Kubernetes operator 架构 | | [docs/operator/k8s-deployment-guide.md](docs/operator/k8s-deployment-guide.md) | K8s 自托管实践指南（helm + operator + CRDs） | | [docs/FORK.md](docs/FORK.md) | 确切的分支点和许可边界 | | [docs/ROADMAP.md](docs/ROADMAP.md) | 按优先级排序的路线图（安全回溯、状态检查提供程序等） | | [docs/security/advisories.md](docs/security/advisories.md) | 我们评估过的每个 CVE/GHSA 的分流记录 | | [CLAUDE.md](CLAUDE.md) | 品牌 + 工程规则（供 AI 助手阅读） | | [dashboard/CLAUDE.md](dashboard/CLAUDE.md) | 前端特定的工程规则 | 兄弟仓库： | 仓库 | 内容 | |---|---| | [`openzro/helms`](https://github.com/openzro/helms) | Helm charts（`openzro` 控制平面、`openzro-operator`、`openzro-operator-config`） | | [`openzro/openzro-operator`](https://github.com/openzro/openzro-operator) | Kubernetes operator —— 用于对等点/组/策略/设置密钥/网络资源的 CRDs | | [`openzro/homebrew-tap`](https://github.com/openzro/homebrew-tap) | macOS 的 Homebrew formula（在打标签时从此仓库自动发布） | ## 贡献 1. **无 CLA。** openZro 接受符合“入站许可等于出站许可”规则的 BSD-3 贡献。提交 PR 即表示您同意其将以 BSD-3 许可发布。 2. **永远禁止引入 AGPL 代码。** 请勿复制、镜像或翻译 `netbirdio/netbird` 在 `v0.53.0`（AGPLv3 切分点）之后的代码。根据公开的 CVE/CWE/协议描述进行重新实现是可以的，这也是我们回溯安全修复的方式 —— 参见 [`docs/security/advisories.md`](docs/security/advisories.md) 中的现有示例。 3. **默认采用 TDD。** 新代码必须先写好测试再提交。参见 [CLAUDE.md](CLAUDE.md) 中的 §工程规则。 ## 上游致谢 openZro 继承并感谢 [`netbirdio/netbird`](https://github.com/netbirdio/netbird) 截至 `v0.52.2`（BSD-3-Clause）的先前工作。上游的 `LICENSE` 和 `AUTHORS` 文件在 BSD-3 署名条款下逐字保留。openZro 本身的新贡献者会单独添加到 `AUTHORS` 文件中。 WireGuard® 和 WireGuard 标识是 Jason A. Donenfeld 的[注册商标](https://www.wireguard.com/trademark-policy/)。 ## 许可 [BSD 3-Clause](LICENSE) —— 永久适用，适用于所有目录。

标签：BSD-3许可证, EVTX分析, Go语言, JSONLines, MFA支持, posture检查, SSO集成, Streamlit, VPN替代, WireGuard, 企业网络, 分布式网络, 加密通信, 子域名突变, 审计日志, 开源, 搜索引擎查询, 日志审计, 流导出, 私有LAN, 移动设备管理, 程序破解, 端到端加密, 端点检测与响应, 网格网络, 网络安全, 网络安全框架, 脱壳工具, 自托管, 访问控制, 请求拦截, 隐私保护, 零信任, 高可用性