跳到主要内容

监听端口与 ports.json

· 阅读需 6 分钟
Lessica
Lessica
XXTouch Elite 维护者

XXTouch Elite 使用一份可选的 JSON 文件统一配置内置网络服务的监听端口。缺省安装不会创建该文件，因此无需额外设置即可继续使用原有默认端口。

配置文件​

配置文件的规范路径为：

/var/mobile/Media/1ferver/conf/ports.json

在标准越狱安装布局中，同一文件也会暴露为：

/usr/local/xxtouch/etc/ports.json

两条路径指向同一份配置，请勿分别维护两份文件。

ports.json 不会作为软件包 conffile 安装，缺省情形下不存在。当文件不存在、不可读取或不是合法 JSON 时，所有服务均使用默认端口。

ports.json 是唯一受支持的端口配置文件。早期开发版本中曾出现过的 network.json 文件名已不再读取。

同一目录中安装有 ports.example.json，可将其复制为 ports.json 后再修改。请勿重命名或直接修改示例文件本身。

文件格式​

推荐格式与随软件安装的示例一致：

ports.json
{
  "ports": {
    "http_port": 46952,
    "discovery_port": 46953,
    "legacy_discovery_port": 14099,
    "logging_udp_port": 46956,
    "logging_websocket_port": 46957,
    "webdav_port": 80,
    "remote_control_port": 46968,
    "control_center_port": 46969,
    "control_center_udp_port": 35452
  }
}

无需修改的项目可以省略，缺少的项目会采用默认值。为兼容已有配置，也可将这些已知键直接放在 JSON 根对象中；新配置应使用上例所示的 ports 对象。如果配置中存在 ports 对象，位于该对象之外的端口键将被忽略。

该文件必须是严格的 JSON，不支持注释、尾随逗号、十六进制数字或表达式。

端口一览​

配置键传输协议默认值涉及范围
http_portTCP46952OpenAPI、内置网页、IDE 通信及内部 HTTP 客户端
discovery_portUDP46953XXTouch Elite 设备发现及中控设备搜索
legacy_discovery_portUDP14099兼容触动精灵、触摸精灵的设备发现
logging_udp_portUDP46956内部脚本日志接收，包括 nLog 的网络日志输出
logging_websocket_portTCP46957设备日志页和脚本编辑页使用的实时日志 WebSocket
webdav_portTCP80WebDAV 文件服务
remote_control_portTCP46968实时桌面与远程控制 WebSocket
control_center_portTCP46969中控 WebSocket，包括网页端和脚本端客户端
control_center_udp_portUDP35452中控设备发现响应接收端口

只有表中列出的键可通过 ports.json 配置。iOS、越狱环境、SSH 或第三方软件使用的其他端口不在该文件的管理范围内。

校验与回退规则​

原生服务与内置 Lua 组件会按照相同规则分别解析该文件；网页客户端则从 /ports.js 获取实际生效值，因此监听服务与随附客户端能够保持一致。

  • 端口值必须是 1 至 65535 之间的 JSON 整数。
  • 布尔值、字符串、小数、零、负数和超出范围的数值均无效。
  • 未知键会被忽略。
  • 单个项目缺失或无效时，仅该项目回退到默认值，不影响其他合法项目生效。
  • 整份文件无法解析时，所有项目均回退到默认值。
  • 同一传输协议下的两个服务不能使用相同端口。发生 TCP 与 TCP 或 UDP 与 UDP 冲突时，所有参与冲突的项目均回退到各自的默认值，并继续检查，直至不存在冲突。
备注

TCP 与 UDP 使用相互独立的端口空间。同一个数值分别用于一个 TCP 服务和一个 UDP 服务不视为冲突，但这样配置仍可能给维护人员造成困惑。

修改端口​

可以通过 Filza、SFTP 或 SSH 创建并编辑配置。以下 SSH 命令会复制随软件安装的示例，并设置常规的所有者和权限：

cp /var/mobile/Media/1ferver/conf/ports.example.json \
   /var/mobile/Media/1ferver/conf/ports.json
chown mobile:mobile /var/mobile/Media/1ferver/conf/ports.json
chmod 0644 /var/mobile/Media/1ferver/conf/ports.json

只需修改需要调整的项目。应用配置前请先保存设备上的工作：用户空间重启会关闭应用，并中断当前 SSH 连接。

在提供 jbctl 的越狱环境中，可执行以下命令使配置生效：

jbctl reboot_userspace

完整重启设备同样可以使配置生效。

目前不支持运行时重新载入。编辑 ports.json 不会改变正在运行的服务或客户端所使用的端口；仅刷新浏览器页面也不足以应用修改。

对客户端和集成的影响​

该配置同时覆盖监听服务及其内置客户端：

  • 内置 Lua 组件使用最终解析出的 HTTP、设备发现、日志、远程控制和中控端口。
  • 内置网页通过 GET /ports.js 获取最终端口，并据此建立 HTTP 或 WebSocket 连接。/ports.js 是动态生成的网页客户端配置接口，不是需要编辑的文件。
  • 原有的 GET /network_config.js 路由已不再注册；网页集成应改用 GET /ports.js。
  • 旧版 /var/mobile/Media/1ferver/1ferver.conf 中的 HTTP 端口会根据 http_port 自动生成。请勿通过修改 1ferver.conf 调整监听端口。
  • 设备发现响应会携带最终解析出的 HTTP 端口，使兼容的 IDE 和中控客户端能够连接正确的服务地址。
  • 使用手工填写地址或端口的外部客户端仍需由使用者同步调整，例如 OpenAPI 集成、反向代理、防火墙规则或 SSH 端口转发。

例如，将 http_port 改为 47152 后，内置网页和 OpenAPI 的基础地址变为：

http://<设备IP地址>:47152/

WebDAV、实时日志、实时桌面和中控服务也会分别迁移到配置中指定的端口。

验证实际生效值​

设备或用户空间重启后，可从最终 HTTP 端口读取动态生成的网页客户端配置：

curl http://<设备IP地址>:<http_port>/ports.js

响应会将实际生效值赋给 window.XXTNetworkPorts，其中也包括因校验失败而采用的默认值。打开内置设备日志、实时桌面或中控页面，也可以进一步验证相应网页客户端是否使用了这些端口。

如需恢复全部默认值，删除自定义配置并重启设备或用户空间：

rm /var/mobile/Media/1ferver/conf/ports.json
jbctl reboot_userspace

修改端口不能替代访问控制。服务是否允许远程设备访问，仍由 XXTouch Elite 的远程访问设置及网络层防火墙策略决定。