NXIST-WiFi-Login 0.1.0

Low-level Python API for NXIST WiFi portal authentication

nxist-login

nxist-login 是一个用于 NXIST 校园网 WiFi 门户认证的 Python 工具。项目分为两层：

• nxwifiapi：底层 API 模块，只封装认证门户 HTTP 请求，不负责 CLI、文件存储或账号管理。
• nxwificli / nxist-login：命令行工具，负责单账号保存、cookie/session 信息保存、一键登录、状态查看和退出登录。

命令行输出为英文，方便脚本读取；本文档使用中文说明。

平台支持

目标支持：

• Windows
• macOS
• Linux

跨平台处理方式：

• 配置文件路径使用 platformdirs.user_config_dir() 获取，不硬编码系统路径。
• 配置文件使用 UTF-8 JSON。
• CLI 入口通过 pyproject.toml 的 [project.scripts] 注册，安装后在 Windows/macOS/Linux 上均由 Python 打包工具生成对应可执行入口。
• 文件路径使用 pathlib.Path。
• 表格输出使用 tabulate，并开启宽字符模式；列宽计算使用 wcwidth，用于兼容中英文混排的套餐名称等内容。
• 配置文件权限在支持的平台上尝试设置为当前用户可读写；不支持时会静默跳过，不影响 Windows 使用。

安装

项目使用 src 布局。开发环境中推荐在虚拟环境内安装：

python -m pip install -e .

安装后会注册命令：

nxist-login --help

依赖由 pyproject.toml 声明：

• requests
• beautifulsoup4
• platformdirs
• tabulate
• wcwidth

配置文件

查看当前平台上的配置文件路径：

nxist-login config-path

示例路径：

• Windows: C:\Users\<User>\AppData\Local\nxist-login\nxist-login\config.json
• macOS: /Users/<User>/Library/Application Support/nxist-login/config.json
• Linux: /home/<User>/.config/nxist-login/config.json

配置文件为 JSON，保存内容包括：

• 单个账号的用户名和密码
• 是否允许自动重登
• requests cookie 信息
• 最近一次登录后的用户 IP、设备 IP、用户 MAC 等认证信息

注意：当前 CLI 按需求使用 JSON 保存账号信息，密码会以明文形式保存在本机配置文件中。请不要把配置文件提交到仓库，也不要在共享机器上保存账号。

常用命令

保存单个账号：

nxist-login save -u USERNAME

也可以直接通过参数提供密码：

nxist-login save -u USERNAME -p PASSWORD

保存账号但禁用自动重登策略：

nxist-login save -u USERNAME --no-auto-login

使用已保存账号一键登录：

nxist-login login

临时指定账号登录：

nxist-login login -u USERNAME

临时指定账号登录并在成功后保存：

nxist-login login -u USERNAME --save

查看当前状态：

nxist-login status

退出登录，保留自动登录状态：

nxist-login logout

退出登录，并请求关闭自动登录，同时关闭本地自动重登策略：

nxist-login logout --disable-auto-login

清除本地保存的账号、cookie 和 session 信息：

nxist-login clear

登录行为

nxist-login login 的行为：

1. 加载平台标准配置路径中的 JSON 配置。
2. 恢复上次保存的 cookie。
3. 先探测当前是否已经在线。
4. 如果已经在线，则输出网络信息表。
5. 如果未在线，则使用参数提供的账号或保存的账号发起用户名密码登录。
6. 登录成功后保存 cookie、userIndex 和认证结果页中的网络信息。

登录成功后的输出为英文表格，例如：

+---------------+------------------+
| Field         | Value            |
+===============+==================+
| Status        | Login successful |
| Username      | 123456789        |
| User IP       | 10.x.x.x         |
| Device IP     | 192.168.x.x      |
| User MAC      | aabbccddeeff     |
| Service ID    | (default)        |
| MAC Fast Auth | Disabled         |
| Package       | F package name   |
+---------------+------------------+

底层 API

底层模块可以被外部程序直接调用：

from nxwifiapi import NXWifiClient

client = NXWifiClient()
result = client.login(username="USERNAME", password="PASSWORD")
print(result.response.result)

nxwifiapi 不读写配置文件，不保存账号，不提供 CLI。外部程序可以自行传入 requests.Session 来控制 cookie 生命周期：

import requests
from nxwifiapi import NXWifiClient

session = requests.Session()
client = NXWifiClient(session=session)

项目结构

src/
  nxwifiapi/
    client.py       # 底层认证 API
    models.py       # 类型化数据模型
    exceptions.py   # 异常类型
  nxwificli/
    cli.py          # CLI 入口和命令
    config.py       # JSON 配置和 cookie 序列化
    output.py       # 英文终端表格输出
docs/
  api-spec.zh-CN.md # 根据抓包整理的认证 API 规范

注意事项

• 该工具依赖 NXIST 校园网门户地址和当前校园网环境；在非校园网环境下登录探测通常会失败。
• 当前实现不支持二维码登录。
• 如果门户要求验证码，底层 API 支持验证码字段，但 CLI 暂未提供自动识别验证码能力。
• session 或 JSESSIONID 不是长期上网授权；CLI 的自动登录策略是保存 cookie，并在需要时使用保存的用户名密码重新登录。