mcsmapi 0.1.4__py3-none-any.whl → 0.1.5b2__py3-none-any.whl

mcsmapi/models/image.py

@@ -3,110 +3,205 @@ from pydantic import BaseModel
 
 
 class DockerConfig(BaseModel):
+    """容器配置"""
+
+    """容器名称"""
     containerName: str = ""
-    image: str = "mcsm-ubuntu:22.04"
-    memory: int = 1024  # in MB
-    ports: List[str] = ["25565:25565/tcp"]
+    """镜像名称"""
+    image: str = ""
+    """容器分配内存(单位: MB)"""
+    memory: int = 0  # in MB
+    """容器端口映射"""
+    ports: List[str] = []  # ["25565:25565/tcp"]
+    """额外挂载卷路径"""
     extraVolumes: List[str] = []
+    """容器可使用的最大磁盘空间(单位: MB)"""
     maxSpace: Optional[int] = None
+    """网络配置，可以是网络名称或ID"""
     network: Optional[Union[str, int]] = None
+    """容器的 IO 限制"""
     io: Optional[Union[str, int]] = None
+    """网络模式(例如: bridge, host)"""
     networkMode: str = "bridge"
+    """网络别名列表"""
     networkAliases: List[str] = []
-    cpusetCpus: str = ""
+    """绑定的 CPU 核心"""
+    cpusetCpus: str = ""  # 例如 `0,1`
+    """CPU 使用率(单位: %)"""
     cpuUsage: int = 100
+    """工作目录"""
     workingDir: str = ""
+    """环境变量设置"""
     env: List[str] = []
 
 
 class DockerImageItem(BaseModel):
+    """Docker 镜像信息"""
+
+    """镜像唯一 ID"""
     Id: str = ""
+    """父镜像 ID"""
     ParentId: str = ""
-    RepoTags: List[str] = []
+    """镜像仓库标签"""
+    RepoTags: List[str] = []  # 例如 ["ubuntu:latest"]
+    """镜像摘要"""
     RepoDigests: List[str] = []
+    """镜像创建时间(Unix 时间戳)"""
     Created: int = 0
+    """镜像大小(单位: 字节)"""
     Size: int = 0
+    """镜像的虚拟大小"""
     VirtualSize: int = 0
+    """共享存储空间大小"""
     SharedSize: int = 0
+    """镜像标签"""
     Labels: dict[str, str] = {}
+    """依赖该镜像运行的容器数量"""
     Containers: int = 0
 
 
 class DockerContainerItemPort(BaseModel):
+    """Docker 容器端口映射"""
+
+    """容器内部端口"""
     PrivatePort: int = 0
+    """映射到宿主机的端口"""
     PublicPort: Optional[int] = None
+    """端口类型(tcp/udp)"""
     Type: str = ""
 
 
 class DockerContainerItemNetworkSettingsNetwork(BaseModel):
+    """Docker 容器网络设置信息"""
+
+    """网络 ID"""
     NetworkID: str = ""
+    """网络端点 ID"""
     EndpointID: str = ""
+    """网关地址"""
     Gateway: str = ""
+    """分配的 IP 地址"""
     IPAddress: str = ""
+    """IP 地址前缀长度"""
     IPPrefixLen: int = 0
+    """IPv6 网关地址"""
     IPv6Gateway: str = ""
+    """IPv6 地址"""
     GlobalIPv6Address: str = ""
+    """IPv6 地址前缀长度"""
     GlobalIPv6PrefixLen: int = 0
+    """MAC 地址"""
     MacAddress: str = ""
 
 
 class DockerContainerItemNetworkSettings(BaseModel):
+    """Docker 容器的网络配置信息"""
+
+    """容器连接的所有网络"""
     Networks: dict[str, DockerContainerItemNetworkSettingsNetwork] = {}
 
 
 class DockerContainerItemMount(BaseModel):
+    """容器挂载点信息"""
+
+    """挂载名称"""
     Name: str = ""
+    """源路径"""
     Source: str = ""
+    """目标路径"""
     Destination: str = ""
+    """驱动类型"""
     Driver: str = ""
+    """挂载模式"""
     Mode: str = ""
+    """是否允许读写"""
     RW: bool = False
+    """传播模式"""
     Propagation: str = ""
 
 
 class DockerContainerItemHostConfig(BaseModel):
+    """Docker 宿主机配置"""
+
+    """网络模式"""
     NetworkMode: str = ""
 
 
 class DockerContainerItem(BaseModel):
+    """Docker 容器详细信息"""
+
+    """容器 ID"""
     Id: str = ""
+    """容器名称列表"""
     Names: List[str] = []
+    """运行的镜像名称"""
     Image: str = ""
+    """镜像 ID"""
     ImageID: str = ""
+    """容器启动命令"""
     Command: str = ""
+    """容器创建时间(Unix 时间戳)"""
     Created: int = 0
+    """容器状态"""
     State: str = ""
+    """容器运行状态描述"""
     Status: str = ""
+    """端口映射信息"""
     Ports: List[DockerContainerItemPort] = []
+    """容器标签信息"""
     Labels: dict[str, str] = {}
+    """读写层大小(单位: 字节)"""
     SizeRw: int = 0
+    """根文件系统大小(单位: 字节)"""
     SizeRootFs: int = 0
+    """宿主机配置"""
     HostConfig: DockerContainerItemHostConfig = DockerContainerItemHostConfig()
-    NetworkSettings: DockerContainerItemNetworkSettings = (
-        DockerContainerItemNetworkSettings()
-    )
+    """容器网络配置"""
+    NetworkSettings: DockerContainerItemNetworkSettings = DockerContainerItemNetworkSettings()
+    """容器挂载信息"""
     Mounts: List[DockerContainerItemMount] = []
 
 
 class DockerNetworkItemIPAMConfig(BaseModel):
+    """Docker 网络 IPAM 配置信息"""
+
+    """子网地址"""
     Subnet: str = ""
 
 
 class DockerNetworkItemIPAM(BaseModel):
+    """Docker 网络的 IP 地址管理"""
+
+    """驱动类型"""
     Driver: str = ""
+    """IPAM 配置"""
     Config: List[DockerNetworkItemIPAMConfig] = []
 
 
 class DockerNetworkItem(BaseModel):
+    """Docker 网络详细信息"""
+
+    """网络名称"""
     Name: str = ""
+    """网络 ID"""
     Id: str = ""
+    """网络创建时间"""
     Created: str = ""
+    """网络作用范围(local/global)"""
     Scope: str = ""
+    """网络驱动类型"""
     Driver: str = ""
+    """是否启用 IPv6"""
     EnableIPv6: bool = False
+    """是否为内部网络"""
     Internal: bool = False
+    """是否可附加"""
     Attachable: bool = False
+    """是否为入口网络"""
     Ingress: bool = False
+    """IPAM 配置信息"""
     IPAM: DockerNetworkItemIPAM = DockerNetworkItemIPAM()
-    Options: dict[str, str]
-    Containers: Optional[dict[str, dict]] = {}
+    """网络选项"""
+    Options: dict[str, str] = {}
+    """连接到此网络的容器信息"""
+    Containers: Optional[dict[str, dict]] = {}

mcsmapi/models/instance.py

@@ -1,87 +1,155 @@
 from typing import List, Dict, Optional
 from pydantic import BaseModel
+from mcsmapi.models.file import FileList
 from mcsmapi.models.image import DockerConfig
 
 
 class TerminalOption(BaseModel):
+    """终端选项"""
+
+    """是否启用颜色输出"""
     haveColor: bool = False
+    """是否使用伪终端 (PTY)"""
     pty: bool = True
 
 
 class EventTask(BaseModel):
+    """事件任务"""
+
+    """是否自动启动"""
     autoStart: bool = False
+    """是否自动重启"""
     autoRestart: bool = True
+    """是否忽略该任务"""
     ignore: bool = False
 
 
 class PingConfig(BaseModel):
+    """服务器 Ping 配置"""
+
+    """服务器 IP 地址"""
     ip: str = ""
+    """服务器端口"""
     port: int = 25565
+    """Ping 类型 (1: 默认类型)"""
     type: int = 1
 
 
 class InstanceConfig(BaseModel):
+    """实例配置信息"""
+
+    """实例名称"""
     nickname: str = "New Name"
+    """启动命令"""
     startCommand: str = "cmd.exe"
+    """停止命令"""
     stopCommand: str = "^C"
+    """工作目录"""
     cwd: str = ""
-    ie: str = "gbk"  # 输入编码
-    oe: str = "gbk"  # 输出编码
+    """输入编码"""
+    ie: str = "gbk"
+    """输出编码"""
+    oe: str = "gbk"
+    """创建时间 (Unix 时间戳)"""
     createDatetime: int = 0
+    """最后修改时间 (Unix 时间戳)"""
     lastDatetime: int = 0
+    """实例类型 (universal, minecraft 等)"""
     type: str = "universal"
+    """实例标签"""
     tag: List[str] = []
+    """实例结束时间 (可选)"""
     endTime: Optional[int] = None
+    """文件编码"""
     fileCode: str = "gbk"
+    """进程类型 (如 docker, local)"""
     processType: str = "docker"
+    """更新命令"""
     updateCommand: str = "shutdown -s"
+    """实例可执行的操作命令列表"""
     actionCommandList: List[str] = []
+    """换行符 (0: LF, 1: CR, 2: CRLF)"""
     crlf: int = 2
+    """Docker 相关配置"""
     docker: "DockerConfig" = DockerConfig()
+    """是否启用 RCON 远程控制"""
     enableRcon: bool = True
+    """RCON 连接密码"""
     rconPassword: str = ""
+    """RCON 端口"""
     rconPort: int = 2557
+    """RCON IP 地址"""
     rconIp: str = ""
+    """终端选项配置"""
     terminalOption: TerminalOption = TerminalOption()
+    """事件任务配置"""
     eventTask: EventTask = EventTask()
+    """服务器 Ping 监测配置"""
     pingConfig: PingConfig = PingConfig()
 
 
 class ProcessInfo(BaseModel):
+    """进程信息"""
+
+    """CPU 使用率 (单位: %)"""
     cpu: int = 0
+    """进程占用内存 (单位: KB)"""
     memory: int = 0
+    """父进程 ID"""
     ppid: int = 0
+    """进程 ID"""
     pid: int = 0
+    """进程创建时间 (Unix 时间戳)"""
     ctime: int = 0
+    """进程运行时长 (单位: 秒)"""
     elapsed: int = 0
+    """时间戳"""
     timestamp: int = 0
 
 
 class InstanceInfo(BaseModel):
+    """实例运行状态信息( 这些选项在新版中已不再支持设置，但仍在API中返回)"""
+
+    """当前玩家数量 (-1 表示未知)"""
     currentPlayers: int = -1
+    """文件锁状态 (0: 无锁)"""
     fileLock: int = 0
+    """最大允许玩家数 (-1 表示未知)"""
     maxPlayers: int = -1
+    """是否启用 FRP 远程服务"""
     openFrpStatus: bool = False
+    """玩家数量变化图表数据"""
     playersChart: List[Dict] = []
+    """服务器版本"""
     version: str = ""
 
 
 class InstanceDetail(BaseModel):
+    """实例详细信息"""
+
+    """实例的配置信息"""
     config: InstanceConfig = InstanceConfig()
+    """实例的运行状态信息"""
     info: InstanceInfo = InstanceInfo()
+    """所属的守护进程 (Daemon) ID"""
     daemonId: str = ""
+    """实例唯一标识符 (UUID)"""
     instanceUuid: str = ""
+    """实例的进程信息"""
     processInfo: ProcessInfo = ProcessInfo()
-    space: int = 0
-    started: int = 0  # 启动次数
-    status: int = 0  # -1 = 忙碌, 0 = 停止, 1 = 停止中, 2 = 启动中, 3 = 运行中
+    """实例的存储空间大小(始终为`0`)"""
+    space: int = 0  # 在 MCSM 代码中，此项始终为 0，意义不明
+    """实例的启动次数"""
+    started: int = 0
+    """实例状态 (-1: 忙碌, 0: 停止, 1: 停止中, 2: 启动中, 3: 运行中)"""
+    status: int = 0
 
     def start(self) -> str | bool:
         """
         启动该实例。
 
         **返回:**
-       <br> - str|bool: str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        - str|bool: str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
         """
         from mcsmapi.apis.instance import Instance
 
@@ -92,7 +160,7 @@ class InstanceDetail(BaseModel):
         停止该实例。
 
         **返回:**
-       <br> - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
         """
         from mcsmapi.apis.instance import Instance
 
@@ -103,7 +171,7 @@ class InstanceDetail(BaseModel):
         重启该实例。
 
         **返回:**
-       <br> - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
         """
         from mcsmapi.apis.instance import Instance
 
@@ -114,7 +182,7 @@ class InstanceDetail(BaseModel):
         强制关闭该实例。
 
         **返回:**
-       <br> - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
         """
         from mcsmapi.apis.instance import Instance
 
@@ -125,7 +193,7 @@ class InstanceDetail(BaseModel):
         删除该实例。
 
         **返回:**
-       <br> - str: 被删除的实例的uuid。
+        - str: 被删除的实例的uuid。
         """
         from mcsmapi.apis.instance import Instance
 
@@ -136,7 +204,7 @@ class InstanceDetail(BaseModel):
         升级实例。
 
         **返回:**
-       <br> - bool: 返回操作结果，成功时返回True。
+        - bool: 返回操作结果，成功时返回True。
         """
         from mcsmapi.apis.instance import Instance
 
@@ -147,10 +215,10 @@ class InstanceDetail(BaseModel):
         更新该实例配置。
 
         **参数:**
-       <br> - config (dict): 新的实例配置，以字典形式提供，缺失内容由使用原实例配置填充。
+        - config (dict): 新的实例配置，以字典形式提供，缺失内容由使用原实例配置填充。
 
         **返回:**
-       <br> - str|bool: 更新成功后返回更新的实例UUID，如果未找到该字段，则默认返回True。
+        - str|bool: 更新成功后返回更新的实例UUID，如果未找到该字段，则默认返回True。
         """
         from mcsmapi.apis.instance import Instance
 
@@ -168,12 +236,12 @@ class InstanceDetail(BaseModel):
         重装实例。
 
         **参数:**
-       <br> - targetUrl (str): 重装文件的目标URL。
-       <br> - title (str): 重装文件的标题。
-       <br> - description (str, optional): 重装文件的描述，默认为空字符串。
+        - targetUrl (str): 重装文件的目标URL。
+        - title (str): 重装文件的标题。
+        - description (str, optional): 重装文件的描述，默认为空字符串。
 
         **返回:**
-       <br> - bool: 返回操作结果，成功时返回True
+        - bool: 返回操作结果，成功时返回True
         """
         from mcsmapi.apis.instance import Instance
 
@@ -181,24 +249,55 @@ class InstanceDetail(BaseModel):
             self.daemonId, self.instanceUuid, targetUrl, title, description
         )
 
+    def files(self, target: str = "", page: int = 0, page_size: int = 100) -> FileList:
+        """
+        获取实例的文件列表。
+
+        **参数:**
+        - target (str, 可选): 用于文件过滤的目标路径。默认为空字符串，表示不按路径过滤
+        - page (int, 可选): 指定分页的页码。默认为0。
+        - page_size (int, 可选): 指定每页的文件数量。默认为100。
+
+        **返回:**
+        - FileList: 文件列表。
+        """
+        from mcsmapi.apis.file import File
+
+        return File().show(self.daemonId, self.instanceUuid, target, page, page_size)
+
 
 class InstanceCreateResult(BaseModel):
+    """实例创建结果"""
+
+    """实例唯一标识符 (UUID)"""
     instanceUuid: str = ""
+    """实例的配置信息"""
     config: InstanceConfig = InstanceConfig()
 
 
 class InstanceSearchList(BaseModel):
+    """实例搜索列表"""
+
+    """每页的实例数量"""
     pageSize: int = 0
+    """最大页数"""
     maxPage: int = 0
+    """实例详细信息列表"""
     data: List[InstanceDetail] = []
+    """所属的守护进程 (Daemon) ID"""
     daemonId: str = ""
 
     def __init__(self, **data: str):
+        """实例化对象，并在每个实例中填充 daemonId"""
         super().__init__(**data)
         for instance in self.data:
             instance.daemonId = self.daemonId
 
 
 class UserInstancesList(BaseModel):
+    """用户实例列表"""
+
+    """实例唯一标识符 (UUID)"""
     instanceUuid: str = ""
+    """所属的守护进程 (Daemon) ID"""
     daemonId: str = ""

mcsmapi/models/overview.py

@@ -4,60 +4,109 @@ from mcsmapi.models.daemon import DaemonModel
 
 
 class SystemUser(BaseModel):
+    """系统用户信息"""
+
+    """用户 ID (UID)"""
     uid: int = 0
+    """用户组 ID (GID)"""
     gid: int = 0
+    """用户名"""
     username: str = ""
+    """用户主目录"""
     homedir: str = ""
+    """默认 Shell 解释器 (可选)"""
     shell: Optional[str] = None
 
 
 class SystemInfo(BaseModel):
+    """系统信息"""
+
+    """当前登录用户信息"""
     user: SystemUser = SystemUser()
+    """系统当前时间 (Unix 时间戳)"""
     time: int = 0
+    """系统总内存大小 (单位: 字节)"""
     totalmem: int = 0
+    """系统空闲内存大小 (单位: 字节)"""
     freemem: int = 0
+    """操作系统类型"""
     type: str = ""
+    """操作系统版本"""
     version: str = ""
+    """系统节点名称"""
     node: str = ""
+    """主机名"""
     hostname: str = ""
+    """系统负载平均值 (过去 1、5、15 分钟)"""
     loadavg: List[float] = []
+    """操作系统平台"""
     platform: str = ""
+    """系统发行版本信息"""
     release: str = ""
+    """系统运行时间 (单位: 秒)"""
     uptime: float = 0
+    """CPU 当前使用率 (单位: %)"""
     cpu: float = 0
 
 
-
 class RecordInfo(BaseModel):
+    """安全记录信息"""
+
+    """成功登录次数"""
     logined: int = 0
+    """非法访问次数"""
     illegalAccess: int = 0
+    """被封禁的 IP 数量"""
     banips: int = 0
+    """登录失败次数"""
     loginFailed: int = 0
 
 
 class ChartInfo(BaseModel):
+    """图表数据信息"""
+
+    """系统性能数据 (CPU/内存等)"""
     system: List[Dict[str, float]] = []
+    """请求统计信息 (HTTP 请求数等)"""
     request: List[Dict[str, int]] = []
 
 
 class ProcessInfo(BaseModel):
+    """进程信息"""
+
+    """CPU 使用率 (单位: %)"""
     cpu: int = 0
+    """进程占用内存 (单位: KB)"""
     memory: int = 0
+    """进程当前工作目录"""
     cwd: str = ""
 
 
 class RemoteCountInfo(BaseModel):
+    """远程守护进程统计信息"""
+
+    """远程守护进程总数"""
     total: int = 0
+    """可用的远程守护进程数量"""
     available: int = 0
 
 
 class OverviewModel(BaseModel):
+    """系统概览信息"""
+
+    """系统当前版本"""
     version: str = ""
+    """指定的守护进程 (Daemon) 版本"""
     specifiedDaemonVersion: str = ""
+    """系统信息"""
     system: SystemInfo = SystemInfo()
+    """安全访问记录"""
     record: RecordInfo = RecordInfo()
+    """进程状态信息"""
     process: ProcessInfo = ProcessInfo()
+    """系统与请求统计图表数据"""
     chart: ChartInfo = ChartInfo()
+    """远程守护进程统计信息"""
     remoteCount: RemoteCountInfo = RemoteCountInfo()
+    """远程守护进程详细信息"""
     remote: List["DaemonModel"] = []
-