EasyTier-PyO3

使用 PyO3 编写的 EasyTier (开源 mesh P2P VPN) Python 绑定库。

可以在 Python 中直接创建、启动、管理 EasyTier 节点，查询对端/路由/指标快照，管理接入凭证，以及订阅节点事件。

本项目以 LGPL-3.0 发布（与 easytier 一致），详见 LICENSE 与 NOTICE。

from easytier_pyo3 import Node

node = Node({
    "instance_name": "my-node",
    "network_identity": {"network_name": "net1", "network_secret": "secret"},
    "ipv4": "10.144.144.1/24",
    "listeners": ["tcp://0.0.0.0:11010"],
})
node.start()
print(node.state())        # Running
print(node.peer_id())
node.stop()

安装与构建

直接安装（PyPI 发布后可用）：

pip install easytier-pyo3

源码构建 / 本地开发（环境要求、支持的平台架构、三种构建方式、构建 FAQ 等）见 构建指南。CI 会为每个平台自动构建 Python 3.11 / 3.12 / 3.13 的 wheel 并运行自测。

快速开始

最小示例（两台机器组网）

节点 A：

from easytier_pyo3 import Node

node_a = Node({
    "instance_name": "node-a",
    "network_identity": {"network_name": "my-net", "network_secret": "topsecret"},
    "ipv4": "10.144.144.1/24",
    "listeners": ["tcp://0.0.0.0:11010"],   # 监听端口，供对端连接
})
node_a.start()

节点 B：

from easytier_pyo3 import Node

node_b = Node({
    "instance_name": "node-b",
    "network_identity": {"network_name": "my-net", "network_secret": "topsecret"},
    "ipv4": "10.144.144.2/24",
    "peer": [{"uri": "tcp://<node-a-ip>:11010"}],  # 对端地址
})
node_b.start()

同一台机器上测试时，可让节点 B 显式连节点 A 的 127.0.0.1:11010。两个节点 network_name / network_secret 必须一致。

不创建 TUN 设备（无管理员权限测试）

Windows 上创建 TUN 设备需要管理员权限；仅做连通性/对端发现测试时可关闭。注意 no_tun 模式下必须同时设置 bind_device = false，否则客户端 socket 尝试绑定到虚拟 IP 会报 WSAEADDRNOTAVAIL(10049)：

node = Node({
    "network_identity": {"network_name": "test", "network_secret": "test"},
    "flags": {"no_tun": True, "bind_device": False},
})

运行时手动连接对端

node.add_connector("tcp://10.0.0.5:11010")
node.remove_connector("tcp://10.0.0.5:11010")

配置说明

Node() 接受 TOML 字符串 或 Python dict（dict 中的 None 值会被忽略，等价于不配置该字段）。

配置字段与 easytier-core 的配置文件一致：

字段	类型	说明
`instance_name`	str	节点名称
`instance_id`	str(UUID)	指定节点 ID（一般省略，自动生成）
`ipv4`	str	虚拟 IPv4 地址，如 `10.144.144.1/24`
`ipv6`	str	虚拟 IPv6 地址，如 `fd00::1/64`
`dhcp`	bool	是否启用 DHCP 获取 IPv4
`network_identity`	dict	`{"network_name": str, "network_secret": str}`
`listeners`	list[str]	监听地址，如 `tcp://0.0.0.0:11010`
`mapped_listeners`	list[str]	端口映射后的公网地址
`exit_nodes`	list[str]	出口节点 IP 列表
`peer`	list[dict]	手动对端，`{"uri": str, "peer_public_key": str?}`
`proxy_network`	list[dict]	代理网段 `{"cidr": str, "allow": list[str]?}`
`routes`	list[str]	路由网段列表
`socks5_proxy`	str	SOCKS5 代理地址
`port_forward`	list[dict]	端口转发配置
`secure_mode`	dict	安全模式配置
`acl`	dict	ACL 规则
`tcp_whitelist` / `udp_whitelist`	list[str]	ACL 端口白名单
`stun_servers` / `stun_servers_v6`	list[str]	自定义 STUN 服务器
`credential_file`	str	凭证文件路径
`flags`	dict	运行时标志，见下表

`flags` 常用项

字段	默认值	说明
`no_tun`	false	不创建 TUN 设备
`bind_device`	true	把隧道 socket 绑定到虚拟 IP；同机回环测试（或连接报 WSAEADDRNOTAVAIL/10049 时）请设为 false
`dev_name`	""	TUN 设备名
`enable_ipv6`	true	启用 IPv6
`mtu`	1380	MTU
`default_protocol`	"tcp"	默认传输协议
`disable_p2p`	false	禁用 P2P 直连
`p2p_only`	false	仅使用 P2P
`relay_network_whitelist`	"*"	允许的中继网络白名单
`enable_encryption`	true	启用加密
`encryption_algorithm`	""	加密算法
`multi_thread`	true	多线程模式
`accept_dns`	false	接受 DNS 服务
`enable_exit_node`	false	作为出口节点
`proxy_forward_by_system`	false	系统级代理转发

完整字段见 easytier-core 源码 crates/easytier-core/src/config/toml.rs。

API 参考

完整 API 文档见 docs/python_api.md。

模块级函数：

version() -> str：EasyTier 内核版本号

类 Node 主要方法：

生命周期：start() / stop() / wait() / state() / is_ready() / latest_error()
信息：instance_id() / instance_name() / peer_id() / running_listeners() / management_events()
连接：add_connector(url) / remove_connector(url) / clear_connectors() / connectors()
快照：peers() / node_info() / routes() / dump_route() / global_peer_map() / local_public_ipv6() / foreign_networks()
统计：metrics() / prometheus_metrics() / acl_stats() / acl_whitelist()
凭证：generate_credential() / revoke_credential() / upsert_credential() / credentials()
事件：events() / next_event(timeout)

事件订阅

节点运行时会持续产生事件（对端加入/离开、连接建立/断开、TUN 就绪等），可以通过 events() 或 next_event() 获取：

import time

node.start()

# 非阻塞：取出当前所有待处理事件
for event in node.events():
    print(event)

# 阻塞：最多等 5 秒，取下一个事件
event = node.next_event(timeout=5.0)
print(event)

事件返回格式为 {"事件名": 载荷} 的 dict，例如：

{"TunDeviceReady": "easytier0"}
{"PeerAdded": 123}
{"PeerConnAdded": {...}}
{"ConnectionAccepted": ["tcp://0.0.0.0:11010", "tcp://1.2.3.4:4567"]}

常见问题

Q1：Windows 上创建 TUN 失败？ 需要以管理员权限运行，或在 flags 中设置 no_tun = true。

Q2：如何卸载？ pip uninstall easytier-pyo3。

Q3：安装后创建 TUN 设备失败 / 提示找不到 wintun.dll？ wheel 内随包分发 wintun.dll、Packet.dll、WinDivert64.sys（构建时由 build.rs 从 third_party/<arch>/ 自动复制进包，与 Python 架构一致）。模块导入时会把 pyd 所在目录加入进程 DLL 搜索路径（AddDllDirectory），因此随包安装的 wintun.dll 能被 easytier 自动找到，无需手动放置。仅做 no_tun 的连通性测试则不需要这些 DLL。

TUN 已在 Windows 上实测通过（需管理员权限）：双节点建链后，用 tests/test_tun_manual.py 可验证 TUN 数据面（ping 经隧道可达）。同机回环测试时节点需设 bind_device: False，否则连接报 WSAEADDRNOTAVAIL。

Q4：easytier 会不会影响我机器上的 Radmin VPN / 其它 VPN 网卡或劫持出站？ 不会。easytier 创建的是自己独立的 wintun 网卡（et_*），只添加 虚拟网段/24 的 on-link 路由，不设默认路由，不触碰其它网卡（实测 Radmin VPN 网卡的 IP/状态/路由在 easytier 运行前后完全一致）。停止节点后网卡与路由自动清理。

Operating System
Programming Language
- Python :: 3
- Rust

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

easytier_pyo3-0.1.0.tar.gz (650.2 kB view details)

Uploaded Aug 12, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

easytier_pyo3-0.1.0-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 PyPymanylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp315-cp315t-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 CPython 3.15tmanylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp315-cp315-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 CPython 3.15manylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp314-cp314t-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 CPython 3.14tmanylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp314-cp314-win_arm64.whl (11.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.14Windows ARM64

easytier_pyo3-0.1.0-cp314-cp314-win_amd64.whl (11.9 MB view details)

Uploaded Aug 12, 2026 CPython 3.14Windows x86-64

easytier_pyo3-0.1.0-cp314-cp314-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 CPython 3.14manylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp314-cp314-macosx_11_0_arm64.whl (11.8 MB view details)

Uploaded Aug 12, 2026 CPython 3.14macOS 11.0+ ARM64

easytier_pyo3-0.1.0-cp313-cp313-win_arm64.whl (11.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.13Windows ARM64

easytier_pyo3-0.1.0-cp313-cp313-win_amd64.whl (11.9 MB view details)

Uploaded Aug 12, 2026 CPython 3.13Windows x86-64

easytier_pyo3-0.1.0-cp313-cp313-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 CPython 3.13manylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp313-cp313-macosx_11_0_arm64.whl (11.8 MB view details)

Uploaded Aug 12, 2026 CPython 3.13macOS 11.0+ ARM64

easytier_pyo3-0.1.0-cp312-cp312-win_arm64.whl (11.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.12Windows ARM64

easytier_pyo3-0.1.0-cp312-cp312-win_amd64.whl (11.9 MB view details)

Uploaded Aug 12, 2026 CPython 3.12Windows x86-64

easytier_pyo3-0.1.0-cp312-cp312-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 CPython 3.12manylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp312-cp312-macosx_11_0_arm64.whl (11.8 MB view details)

Uploaded Aug 12, 2026 CPython 3.12macOS 11.0+ ARM64

easytier_pyo3-0.1.0-cp311-cp311-win_arm64.whl (11.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.11Windows ARM64

easytier_pyo3-0.1.0-cp311-cp311-win_amd64.whl (12.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.11Windows x86-64

easytier_pyo3-0.1.0-cp311-cp311-manylinux_2_28_x86_64.whl (13.2 MB view details)

Uploaded Aug 12, 2026 CPython 3.11manylinux: glibc 2.28+ x86-64

easytier_pyo3-0.1.0-cp311-cp311-macosx_11_0_arm64.whl (11.8 MB view details)

Uploaded Aug 12, 2026 CPython 3.11macOS 11.0+ ARM64

File details

Details for the file easytier_pyo3-0.1.0.tar.gz.

File metadata

Download URL: easytier_pyo3-0.1.0.tar.gz
Upload date: Aug 12, 2026
Size: 650.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for easytier_pyo3-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`c77f569148a188dcae37de5d432a4daf84bdf488a1315e822d88366798eba27e`
MD5	`49d076954d910f2cc5af087ac11c23b7`
BLAKE2b-256	`3e8ff5d6e1ab322ba73a5f411c61ae48272cd0ba76e5afb8a8bda2d4f950e4e4`

Algorithm	Hash digest
SHA256	`74f6bcf3aad78ede025033670c891904407bf3aa4da095950d36ec19c07718bf`
MD5	`a5ce7004691f5a13b95014b4e115ea21`
BLAKE2b-256	`98c17d1f6db8759e0aad457f20861734aede532b2c7e7d888a174fead3361bc4`

Algorithm	Hash digest
SHA256	`eae03f4c03eb55a5eacadfe899520896970fa8d1544c56b1e2dc761356cf3101`
MD5	`0dcd635e5e4295d9d83f192d545ce0b3`
BLAKE2b-256	`112db91a0d7ca0ff851994bcd4aca6828f70778ef1736a05ca5162d4a65a0303`

Algorithm	Hash digest
SHA256	`9e4501d55f0aa65b5bedc7571cee3e85d6dd2d85f0d5635990ae995603bb9528`
MD5	`463388bd77054eccc9af7daf22400294`
BLAKE2b-256	`1ae6a12defc3fe44e9bb7d7af65cd90e197d415b53903fc975d8ae2b0deec4ca`

Algorithm	Hash digest
SHA256	`0f0da825afc60faba012a3c969f2d66b24b1d3d8c01053a3bdc7efbe6d225264`
MD5	`364f3b3cb856d82d647be96ee9160af8`
BLAKE2b-256	`ec5b5b8ef9851f01bac86f46d900c97619fe6c8022f243cc4be07b94ca6836e3`

Algorithm	Hash digest
SHA256	`102752cd08eb9238b18f2c0925b79d3ce7293072f06e3535f1ab4a55c8442287`
MD5	`058eb3879069922b1afda31c5b3fbf18`
BLAKE2b-256	`35fe90281acf8210140d2e7e9d1752caf2ce13cbf9004af890f30278e50e3e1d`

Algorithm	Hash digest
SHA256	`cc13f44c23df68c309abe99528c3754b081c19fe53b1c35d4e6992f504374296`
MD5	`c304e452cc807de5778c8ba9cb22472b`
BLAKE2b-256	`51f020a42896ebc0b7179629cbcfc300a993d51b45635832230041860f6b4836`

Algorithm	Hash digest
SHA256	`0cb7434c5f3a5c4636c78d3ca6b7245712544261a0187cf0350b02263a38b8cf`
MD5	`020825f12a93da744410409fe4e9e20f`
BLAKE2b-256	`535dccad75a30ce31335877eed8da74cb321c24303164b7b0fc26770e74c707e`

Algorithm	Hash digest
SHA256	`31dbc9b2297e7cb73da51f17a0876371df2b2011f5ca4ff307c6fd5e4dfb20cb`
MD5	`cb681d253f1a73633fe266ff98641c54`
BLAKE2b-256	`bec838fd93d493a00fbed36bc0eee07ede4f251c859f6738e72a2bce9cc9373c`

Algorithm	Hash digest
SHA256	`0d383b280226610326193d069abde930f1b62efe671e765f227bcf82184f2e4f`
MD5	`6b5ecee69bd23eee62443dc65f463115`
BLAKE2b-256	`a52ecee36799f0731e6f957e2b68b5f5dcd3858196a492b05e59e37e48292dc3`

Algorithm	Hash digest
SHA256	`5d07636eca8c40f411ac56906de6ab6da054a9343485632631cef2458121f922`
MD5	`9ebedb53c960c952500d2d1c0342dfd2`
BLAKE2b-256	`1bf4c67b7eac485a00c5d1b60cc68561ce235cbd858c851a972b07931752a6e1`

Algorithm	Hash digest
SHA256	`d709072950b48439dc1833fdcd5483e01ab71b508fc4fac92e24a98748dce88e`
MD5	`603f2ab1f15155de11d3eb6936622ca2`
BLAKE2b-256	`6f3a4309724a4a46b807254f34dcecfcddb27c0bb0892f9134442852085f8b59`

Algorithm	Hash digest
SHA256	`3c8fc4ccf6f6741eb49bf27cfc248af7c096c80c1912fc81986d69f39a166e75`
MD5	`02e012b836b5f3eb8549e2fdcbc1cc71`
BLAKE2b-256	`13130b53871520267c9265d7d192bc9f49794fe88d39f132210f9e7da8a593bb`

Algorithm	Hash digest
SHA256	`fe09ac02387736e23f8eadb43955e23e887e3e55b17416c0d3ccd916aee234a0`
MD5	`a4c652213abeb4bb612906d0eac836f0`
BLAKE2b-256	`adedc8f24a4fe57355e208dea9fe234a54ff03510b330f8ca116728865317f5a`

Algorithm	Hash digest
SHA256	`2eaabec3d2ec6189fd196eb2aaaa5e733fc35f47e17133c5a7cfb05c1db7a7f6`
MD5	`5373aa1e5783e99c43dab4d9b05f15c4`
BLAKE2b-256	`762e91ec30759824f3b1fd75d48667486682b53bd6df89159143a5c86143d05e`

Algorithm	Hash digest
SHA256	`b4a6d706ff6f6eeeaba71ced4f400497d1cd56aaf660d000b94ae3b110112587`
MD5	`63ff4d0cfe615684656fb3c6995c408a`
BLAKE2b-256	`d32dd18396cbfb1d9a823895fb9789d2b9f8f5debbc6ef1e355ce21bbf8ec483`

Algorithm	Hash digest
SHA256	`88cd8736f2981b8c46046066864bb45287eb97ad3c24ca097d155c71f86a0f18`
MD5	`be90486500a6a5ab949c9b1e4e301dd7`
BLAKE2b-256	`5eb127e3c5e5e61e46b60fb4418eaacb34866c3476ce1534fba36c241fc1d1f7`

Algorithm	Hash digest
SHA256	`3dad7fba7d6613a0544e8bccd4f2b1729af5e86c07391ab5e0766ebc4f5529d7`
MD5	`4fd7dcf7877b484d920f2e14fd62406d`
BLAKE2b-256	`392c642fa7c4a47c0bdb379a1be6a3ed57f13bd34348f4873e8d7d53baeee08e`

Algorithm	Hash digest
SHA256	`713698b8a7787ff4b29e50ad21044b9f3b6620f0568e5d5c8ff0fdf124a7d550`
MD5	`b5ee93db5334e833046887185330f6e3`
BLAKE2b-256	`67f958c8898aaeb8869ad47bc9c698befad996eeac3d78cb2c435ad086a78145`

Algorithm	Hash digest
SHA256	`b9622810f914627c516ed68719d163f4d4c250234cc22113ce89ca99eeeeb9d0`
MD5	`9dedd6ad541d3526d8ff6c0abd975fb2`
BLAKE2b-256	`6675c4f8aff25295a6094cba37dd45e47840b3b5372a1c2b235031a4c85f810c`

Algorithm	Hash digest
SHA256	`fc6cd16fc4f8269d96e0b4bcbdc49616086235651e841389f5b90c87d2226fd9`
MD5	`e9507c7a7af27fcc1135772b17695375`
BLAKE2b-256	`ea988d952d748b4863ce446594ab8142ed05fb9bef6e54e95a6132ced6e25f26`

easytier-pyo3 0.1.0

EasyTier-PyO3

目录

安装与构建

快速开始

最小示例（两台机器组网）

不创建 TUN 设备（无管理员权限测试）

运行时手动连接对端

配置说明

flags 常用项

API 参考

事件订阅

常见问题

Key dates

1 maintainer

License expression

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

`flags` 常用项