NPS Admin Ops（管理员运维）
Overview
面向管理员的 NPS 运维 CLI：用户、客户端、隧道、域名反代全生命周期管理 + 信息查询，全部走 /api/v1。
只接受管理员密钥（auth_key 或管理面板「系统 → API 接入」生成的 npsa_ 网页密钥）。用户 Token（npsu_）会被脚本直接拒绝并提示改用 nps-tunnel-manager。
不含：全局参数保存、服务重启、登录封禁、Geo 数据、审计日志（系统配置类）。
第一步：管理员密钥（必做）
服务端默认 https://nps.dell.4dbim.cc:1143，不要问用户地址，只问管理员密钥。
python nps_admin.py config-show # 未配置则向用户索要
python nps_admin.py configure --auth-key <ADMIN_KEY>
python nps_admin.py verify # 返回 scope=admin 才算真正拿到管理员权限
verify的scope必须是admin；若为user，说明拿到的是用户密钥，要向用户要真正的 admin key。- 报
unauthorized→ 密钥错；时差 >15 秒 → 让用户校时。 - 换服务端：
configure --url <地址> --auth-key <KEY>。
信息查询
python nps_admin.py verify # 版本、客户端/隧道/域名计数、在线数
python nps_admin.py overview # 全局面板数据（流量、配额、运行态）
python nps_admin.py platform-domains # 平台泛域名池（含 ID，建 Host 用）
用户管理
python nps_admin.py user-list [--search 张] [--limit 50]
python nps_admin.py user-get --id 10
python nps_admin.py user-add --username zhangsan --password Passw0rd --remark 研发 --max-client 2 --max-tunnel 10
python nps_admin.py user-edit --id 10 --remark 研发组 --max-client 5
python nps_admin.py user-password --id 10 --new-password NewPass123
python nps_admin.py user-status --id 10 --status off # 禁用/启用
python nps_admin.py user-token --id 10 # 生成/重置用户 API Token（npsu_）
python nps_admin.py user-token-status --id 10
python nps_admin.py user-token-revoke --id 10
python nps_admin.py user-del --id 10 # 需确认；不删客户端，但会解绑（UserId 置空）
客户端管理
python nps_admin.py client-list [--search office]
python nps_admin.py client-get --id 60
python nps_admin.py client-add --remark office --user-id 10 --max-conn 20 --flow-limit 10240
python nps_admin.py client-edit --id 60 --remark office-1 --rate-limit 2048
python nps_admin.py client-status --id 60 --status off
python nps_admin.py client-upgrade --id 60 # 远程升级 npc
python nps_admin.py client-update-check --id 60
python nps_admin.py client-del --id 60 # 需确认
client-add不传--vkey时服务端自动生成，返回后把 vkey 交给用户配到 npc。client-edit会自动预填现有值（remark/vkey/配额等），但compress/crypt必须显式指定：
--compress on|off、--crypt on|off（服务端编辑会无条件覆盖，且详情接口不返回这两个值，漏传会被置为 off）。tunnel-edit自动预填type/port（服务端缺type报错、缺port会重新分配端口）。
隧道管理
python nps_admin.py tunnel-list [--client-id 60] [--type tcp]
python nps_admin.py tunnel-get --id 12
python nps_admin.py tunnel-add --client-id 60 --type tcp --target 127.0.0.1:22 --remark ssh
python nps_admin.py tunnel-edit --id 12 --target 127.0.0.1:2222
python nps_admin.py tunnel-action start --id 12
python nps_admin.py tunnel-action stop --id 12
python nps_admin.py tunnel-action copy --id 12 # 复制一条同配置隧道
python nps_admin.py tunnel-del --id 12 # 需确认
列表返回带 access_url（来自接口的 AccessURL）。
TCP 端口规则：端口一律由服务端自动分配（1024–65535 随机，须通过 allow_ports 白名单与占用检测），CLI 不提供指定端口的选项；修改隧道也不会改动端口（tunnel-edit 会预填原端口，缺 port 服务端会重新分配）。改类型用 --type，不传则沿用现有类型。发布后必须提醒用户确认云安全组/防火墙已放行分配到的端口，否则隧道正常但外部连不上。
域名反代管理
python nps_admin.py host-list [--client-id 60]
python nps_admin.py host-get --id 42
# 平台域名（需要 platform-domain-id，从 platform-domains 取）
python nps_admin.py host-add --client-id 60 --platform-domain-id platform-xxxx --platform-prefix wenjian --target 127.0.0.1:8080 --remark 文件服务
# 自定义域名
python nps_admin.py host-add --client-id 60 --host app.example.net --target 127.0.0.1:8080 --scheme all --remark 后台
python nps_admin.py host-edit --id 42 --target 127.0.0.1:9090
python nps_admin.py host-action start --id 42 # 或 stop
python nps_admin.py host-check --platform-domain-id platform-xxxx --platform-prefix wenjian2 # 前缀占用预检
python nps_admin.py host-diagnose --host a.web.dell.4dbim.cc --scheme https --path / # 路由诊断
python nps_admin.py host-del --id 42 # 需确认
- 平台域名建 Host 前先
host-check预检前缀，占用就换。 host-edit自动预填域名身份/Header/证书等（服务端全量替换），只传要改的字段；改域名用--host或--platform-prefix。换泛域名时加--platform-suffix（优先级：后缀推导 > 显式 ID > 现有 ID），不传则沿用原泛域名。- 编辑不做前缀预检（
host-check无法排除自身）；真冲突时服务端报「已被使用」，换前缀即可。 - 列表返回
access_url+access_urls：端口按接口HttpPort/HttpsPort（空=标准端口），双开默认给 https。
安全与确认规则
- 删除类（user-del / client-del / tunnel-del / host-del）：先
*-get或列表确认目标，向用户复述 ID + 标识再执行，执行后复查。 - 破坏性编辑（改归属、改 vkey、禁用、重置 Token）：说明影响后执行。
- 普通修改（备注、端口、目标、限速、启停）：按用户描述直接执行，不必反复确认。
- 重置用户 Token 会让旧 Token 立即失效，务必提醒用户。
域名鉴权（HTTP Basic Auth）
给域名反代加访问密码，浏览器访问会弹认证框（或需带 Authorization: Basic）。
# 发布时带鉴权（可重复传多账号）
python nps_admin.py host-add --remark 后台 --platform-prefix houtai --platform-suffix web.dell.4dbim.cc \
--target 127.0.0.1:8080 --auth admin:Passw0rd --auth guest:guest123
# 给已有域名加/改鉴权
python nps_admin.py host-edit --id 42 --auth admin:NewPass123
# 清除鉴权
python nps_admin.py host-edit --id 42 --clear-auth
规则（与源码 ParseBasicAuth 一致）：
- 服务端存的是每行 用户名:密码，多个账号换行分隔，--auth 可重复传入。
- 首个冒号切分用户名/密码，密码里可以含冒号；用户名不能含冒号或换行，用户名不可重复，用户名和密码都不能为空。
- 修改时不传 --auth 会保留原鉴权；只有 --clear-auth 才清除。
- 鉴权按 Host（含 location 规则）生效，未通过返回 401。Basic 凭据是 base64 明文，务必走 HTTPS。
- 鉴权只挡访问，不替代 IP 白名单；需要更细粒度控制用隧道/Host 的 IP 黑白名单。
仅允许已登记 IP（registered_only）
客户端、TCP 隧道、域名反代三处都有这个开关，效果是：只有事先登记过的来源 IP 才能连，其他 IP 一律拒绝。
# 发布时开启
python nps_admin.py host-add --remark 后台 --platform-prefix houtai --platform-suffix web.dell.4dbim.cc \
--target 127.0.0.1:8080 --registered-only on
python nps_admin.py tunnel-add --remark ssh --target 127.0.0.1:22 --registered-only on
# 已有规则开关
python nps_admin.py host-edit --id 42 --registered-only on
python nps_admin.py tunnel-edit --id 12 --registered-only off
- 参数统一为
--registered-only on|off；编辑时不传 = 保留原值（服务端只在提交了该字段时才改）。 - 客户端级还配套两个字段（管理员 Skill）：
--register-key（登记口令）、--register-max-hours（登记有效期小时，0=不限）。 - 登记方式：客户端用自身
vkey+ 登记口令调用POST /auth/ipwhiteauth（v1 为/api/v1/ipwhiteauth），把当前公网 IP 登记进白名单，在有效期内可访问；过期需重新登记。 - 管理员可在
/api/v1/global/ip-register（get/revoke/clean/clear）查看和撤销登记记录。 - ⚠️ 顺序很重要：先登记 IP，再开启 registered_only，否则开启瞬间自己也会被挡在外面。家用宽带 IP 会变，建议登记有效期设长一点或配合
register_max_hours自动过期。
注意事项
- 全部命令输出 JSON；失败输出
{"ok":false,"error":...}退出码 1。 - v1 更新只接受 PUT/PATCH（POST 会 404），脚本已处理。
- 删用户不删客户端，仅解绑（需重新分配 user_id 才能恢复）。
- 需要干"发布服务"这类轻量活、且只有用户 Token 时，改用
nps-tunnel-managerSkill。 - API 字段表见
references/api_reference.md。
