nps-ctl

一个用于管理 NPS 代理服务器的 Python 库和命令行工具。

注意： 本项目基于 djylb/nps，这是原版 ehang-io/nps（自 2021 年起停止维护）的活跃维护分支。API 兼容两个分支，但推荐使用 djylb/nps。

本项目会根据需求持续迭代，我也无意搞开源再闭源，请不要为了存档而 fork。如果觉得好用，欢迎加个 Star。

功能特性

API 客户端：类型安全的 NPS HTTP API Python 封装
多节点支持：通过统一界面管理多台 NPS 边缘服务器
集群同步：跨边缘节点同步客户端、隧道和域名映射
NPC 部署：通过 SSH 安装、配置和管理 NPC 客户端
命令行工具：Rich 终端界面，支持所有操作
最小依赖：仅需 rich 用于终端输出

安装

pip install nps-ctl

可选：SOCKS5 代理支持

pip install nps-ctl PySocks

快速开始

作为库使用

from nps_ctl import NPSClient

# 连接到单台 NPS 服务器
client = NPSClient(
    base_url="https://nps.example.com",
    auth_key="your_auth_key"
)

# 列出所有客户端
clients = client.list_clients()
for c in clients:
    print(f"{c['Id']}: {c['VerifyKey']}")

# 添加新客户端
client.add_client(remark="my-server", vkey="unique-key")

作为命令行工具

# 查看所有边缘节点状态
nps-ctl status

# 列出指定边缘节点的客户端
nps-ctl client list --edge nps-asia

# 从一个边缘节点同步配置到其他所有节点
nps-ctl sync --from nps-asia

# 向所有边缘节点添加域名映射
nps-ctl add-host --domain app.example.com --client my-server --target :8080

# 从 clients.toml 推送客户端配置到边缘节点
nps-ctl npc client-push

# 检查各机器上的 NPC 客户端状态
nps-ctl npc status

配置

创建 config/edges.toml 文件：

[edges.nps-asia]
api_url = "https://nps-asia.example.com"
auth_key = "your_auth_key"
region = "Asia"

[edges.nps-us]
api_url = "https://nps-us.example.com"
auth_key = "your_auth_key"
region = "US"

可选，创建 config/clients.toml 用于 NPC 客户端管理：

[clients.my-server]
ssh_host = "user@my-server.example.com"
vkey = "unique-verify-key"
edges = ["nps-asia", "nps-us"]

API 参考

NPSClient

单节点 NPS 服务器客户端。

list_clients() - 获取所有客户端
add_client() - 添加新客户端
edit_client() - 修改客户端
del_client() - 删除客户端
list_tunnels() - 获取所有隧道
add_tunnel() - 添加新隧道
list_hosts() - 获取所有域名映射
add_host() - 添加新域名映射

NPSCluster

多节点管理器。

get_all_clients() - 从所有节点获取客户端
sync_from() - 从源边缘节点同步配置到目标节点
broadcast_host() - 向所有节点添加域名映射

开发

# 安装开发依赖
pip install -e ".[dev,test]"

# 代码检查和类型检查
make lint

# 运行测试
make test

# 构建包
make build

许可证

GPL-3.0 — 详见 LICENSE。

Download files

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

Source Distribution

nps_ctl-0.6.0.tar.gz (74.5 kB view details)

Uploaded Jun 13, 2026 Source

Built Distribution

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.

nps_ctl-0.6.0-py3-none-any.whl (82.3 kB view details)

Uploaded Jun 13, 2026 Python 3

File details

Details for the file nps_ctl-0.6.0.tar.gz.

File metadata

Download URL: nps_ctl-0.6.0.tar.gz
Upload date: Jun 13, 2026
Size: 74.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for nps_ctl-0.6.0.tar.gz
Algorithm	Hash digest
SHA256	`27f9d7770bc088b556f740f7197942a8030056c14486f015b0baf0840fb7b229`
MD5	`fa857e10a23f8928461e988a790648cd`
BLAKE2b-256	`3fa395c07dc20d07aba6ae14a55ccb0d60056a5ab6a539538fe071c7563044f8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for nps_ctl-0.6.0.tar.gz:

Publisher: release.yml on Oaklight/nps-ctl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: nps_ctl-0.6.0.tar.gz
- Subject digest: 27f9d7770bc088b556f740f7197942a8030056c14486f015b0baf0840fb7b229
- Sigstore transparency entry: 1807506459
- Sigstore integration time: Jun 13, 2026
Source repository:
- Permalink: Oaklight/nps-ctl@5b347a9a84e8fb8fc55ff45913504f52337f7318
- Branch / Tag: refs/heads/master
- Owner: https://github.com/Oaklight
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5b347a9a84e8fb8fc55ff45913504f52337f7318
- Trigger Event: workflow_dispatch