我的世界服务器映射应用接口文档

概述

本应用提供了一系列接口，用于管理 MC服务器的映射、查看服务器状态、查看日志等功能，后端采用Python模块化设计，每个接口的调用通过 port.py 模块进行，此文档将详细描述每个接口的调用方式和返回数据格式，以便于前端开发时的集成

接口总览

添加映射接口
删除映射接口
更改映射接口
打开映射接口
关闭映射接口
查看服务器详细信息接口
查看日志接口

添加映射接口

描述

该接口用于添加新的服务器映射，并启动相应的代理和局域网广播功能。

调用方法

add_mapping(name: str, address: str, preferred_port: int = 25565) -> bool

参数

name (str): 映射名称，用于标识该映射。
address (str): 服务器的域名或 IP 地址，格式如 example.com 或 192.168.1.1。
preferred_port (int, 可选): 本地映射的首选端口，默认为 25565。

返回值

成功时返回 True，失败时返回 False。

错误处理

如果映射名称已存在，则会返回 True 并记录日志。
如果解析地址失败或端口不可用，将返回 False 并记录详细错误日志。

删除映射接口

描述

该接口用于停止并删除指定的服务器映射。

调用方法

remove_mapping(name: str)

参数

name (str): 映射名称，用于标识需要删除的映射。

返回值

无返回值。

错误处理

如果映射名称不存在，将记录警告日志。

更改映射接口

描述

该接口用于修改已存在的服务器映射的地址或端口。

调用方法

update_mapping(name: str, new_address: str = None, new_port: int = None) -> bool

参数

name (str): 映射名称，用于标识需要更改的映射。
new_address (str, 可选): 新的服务器地址（域名或 IP）。
new_port (int, 可选): 新的首选端口，默认为 25565。

返回值

成功时返回 True，失败时返回 False。

错误处理

如果映射名称不存在，将返回 False 并记录警告日志。

打开映射接口

描述

该接口用于重新打开或启动一个指定的映射。

调用方法

open_mapping(name: str, address: str, preferred_port: int = 25565) -> bool

参数

name (str): 映射名称。
address (str): 服务器的域名或 IP 地址。
preferred_port (int, 可选): 本地映射的首选端口，默认为 25565。

返回值

成功时返回 True，失败时返回 False。

错误处理

如果映射已在运行，将直接返回 True 并记录日志。

关闭映射接口

描述

该接口用于关闭正在运行的服务器映射。

调用方法

close_mapping(name: str)

参数

name (str): 映射名称，用于标识需要关闭的映射。

返回值

无返回值。

错误处理

如果映射名称不存在，将记录警告日志。

查看服务器详细信息接口

描述

该接口用于获取指定服务器的详细状态信息，如版本、延迟、MOTD、在线玩家数等。

调用方法

get_server_info(address: str) -> dict | None

参数

address (str): 服务器的域名或 IP 地址。

返回值

成功时返回包含服务器状态的字典：

{
    'version': str,        # 服务器版本
    'latency': float,      # 服务器延迟（毫秒）
    'motd': str,           # 服务器 MOTD（描述）
    'players': int,        # 在线玩家数量
    'icon': str            # Base64 编码的服务器图标
}

如果获取失败，返回 None。

错误处理

如果无法获取服务器状态，将返回 None 并记录错误日志。

查看日志接口

描述

该接口用于查看当前所有映射的日志数据。

调用方法

get_mapping_logs() -> list[str]

参数

无参数。

返回值

返回包含所有映射状态的日志列表，每个日志项为字符串格式，包含映射名称和运行状态。

错误处理

无特定错误处理，通过日志模块记录获取日志的操作。

获取已分配的本地 IP 和端口信息

描述

返回当前所有正在运行的服务器映射的本地 IP 和端口。

调用方法

get_assigned_ports_info

参数

在 Flask 或其他接口调用处，你可以调用 get_assigned_ports_info() 来获取已分配的本地 IP 和端口信息，并将其显示在前端。

返回值

get_assigned_ports_info{
    "ExampleServer1": "127.0.0.1:25565",
    "ExampleServer2": "127.0.0.1:25566"
}

错误处理

无特定错误处理，通过日志模块记录获取日志的操作。

错误处理与日志记录

所有接口调用过程中的错误将被记录到 server_mapping.log 文件中。日志分为以下几类：

INFO: 一般操作信息，例如映射的启动、停止、更新等。
WARNING: 非致命警告，例如尝试停止不存在的映射。
ERROR: 错误信息，例如解析失败、无法连接等。
DEBUG: 调试信息，用于记录更详细的操作流程和状态。

前端开发人员可以通过查看日志文件来调试和确认后端的执行情况。

备注

所有接口均为同步调用，前端可根据需要使用异步方法进行包装，以提升用户体验。
端口号范围建议在合理范围内配置（默认 25565-65535）。
服务器状态获取依赖 mcstatus 库，请确保环境中已正确安装该依赖库。