OpenTUIPanel

OpenTUIPanel 是一个基于 Python 的终端轻量级服务器资源监控与 Docker / Docker Compose 状态巡检工具。通过单次复合 Shell 管道（Composite Payload）降低远程连接开销，提供双缓冲无闪烁的全屏交互式 TUI 视图，并支持结构化 JSON 数据导出。针对移动终端（如 Termux 101 列宽）进行了字符级排版与视口自适应优化。

---

功能清单

模块	功能 / 指标项	说明
系统基础	主机概况	主机名、操作系统发行版、内核版本、硬件架构、系统运行时间（Uptime）
CPU 负荷	核心负荷与负载	双点差分采样计算 CPU 使用率、历史趋势火花线（Sparkline）、1m/5m/15m 平均负载、核心数与型号
内存与交换	内存分层解构	物理内存总量/已用/可用容量及占比、三段式堆叠条解构应用实际占用/系统缓存（Buff/Cache）/空闲空间、Swap 占用比例
存储挂载	磁盘与文件系统	自动过滤虚拟文件系统，展示物理及逻辑分区的挂载点、文件系统类型、容量总量、已用、剩余及使用率微条
容器概况	Docker 引擎状态	Docker 守护进程版本、容器状态统计（运行中/已停止/总数）
编排概况	Docker Compose	项目名称、当前运行状态、关联容器统计（运行数/总数）、服务清单、配置文件路径
容器清单	容器实例明细	容器名称、镜像规格、运行状态与健康检查（健康/异常/启动中）、所属编排服务、端口映射
进程监控	系统进程活动采样	内置 atop -> htop -> top 自动回退体系。支持处理器视角（CPU% 排序，CMD 弹性全宽）与内存深度剖析视角（atop -m，展示常驻 RSIZE、虚存 VSIZE、Swap 占用）
深度下钻	单容器全景画像	单独探查容器的 CPU/内存实时用量、网络吞吐（入/出）、磁盘 I/O（读/写）、活跃 PIDs、内部 IP/网关/MAC、端口映射、CPU/内存配额硬限制、启动命令与挂载卷（RO/RW）
深度下钻	单项目编排画像	单独探查 Compose 项目的累计 CPU%、累计估算内存、总 PIDs 聚合统计，以及各服务细分运行状态、内部 IP 与内存微条横向对比

---

交互快捷键

全屏交互 TUI 模式（默认模式或 --watch）支持以下键盘控制：

按键	功能说明	适用视图
Tab / Shift+Tab	循环切换下一个 / 上一个选项卡（1 总览 / 2 容器 / 3 编排 / 4 进程）	全局
1 ~ 4	快速直达对应的第 1 至第 4 个选项卡	全局
↑ / ↓ 或 k / j 或 w / s	向上 / 向下移动高亮光标选择行	容器、编排、进程列表
Enter	进入当前高亮选中的容器或 Compose 项目深度详情页	容器列表、编排列表
Esc / Backspace	返回上一级列表视图	详情视图
m	切换进程监控为内存深度剖析视角（基于 atop -m）	进程选项卡
c	切换进程监控回处理器视角（基于 CPU 排序）	进程选项卡
r	手动触发一次即时指标采集与界面重绘	全局
Space (空格)	暂停 / 恢复后台自动刷新	全局
+ / -	增加 / 减少自动刷新间隔（步进 1 秒，最小 1 秒）	全局
q / Ctrl+C	退出程序并自动恢复终端原生屏幕缓冲区	全局

---

命令行操作说明

参数选项

参数选项	简写	默认值	说明
--host	-H	logshare	目标主机 SSH 地址或别名（支持 ~/.ssh/config 配置）
--local	-l	否	采集并监控当前本机系统，不使用远程 SSH
--container	-c	无	单独查看指定 Docker 容器实例的占用与详细画像（容器名或 ID）
--compose / --project	-p	无	单独查看指定 Docker Compose 项目的聚合占用与服务明细
--watch	-w	是（交互模式）	运行全屏交互式 TUI 控制模式
--no-tui / --once	-	否	单次打印控制台仪表盘快照后退出（适合自动化脚本与日志记录）
--json	-j	否	以标准 JSON 数据结构输出采集指标后退出
--interval	-i	3	自动刷新间隔秒数
--timeout	-t	15	SSH 连接与远程执行超时秒数
--width	-W	自动	显式指定终端渲染列宽（缺省自动感知终端或默认 101 列）

使用示例

1. 启动远程服务器交互式监控（默认连接 SSH 主机 logshare）：

   python3 main.py
   # 或指定目标主机别名/IP
   python3 main.py -H my-server

2. 监控本地服务器系统与容器：

   python3 main.py --local

3. 单独查看某个容器实例的深度资源占用与配置：

   python3 main.py -H logshare -c my-nginx-container --once

4. 单独查看某个 Docker Compose 项目的聚合与细分资源消耗：

   python3 main.py -H logshare -p docker-stack --once

5. 非交互单次快照输出（适合定时巡检、重定向输出）：

   python3 main.py -H logshare --once

6. 导出标准 JSON 格式数据（用于第三方平台采集或脚本解析）：

   python3 main.py -H logshare --json

---

JSON 数据输出规范

使用 --json / -j 参数时，程序遵循统一的三层响应结构输出：

{
  "code": 0,
  "message": "ok",
  "data": {
    "target": "logshare",
    "timestamp": "2026-09-12 15:03:48",
    "system": {
      "hostname": "VM-0-14-debian",
      "os_name": "Debian GNU/Linux 13 (trixie)",
      "kernel": "Linux 7.1.10-x64v3-xanmod1",
      "arch": "x86_64",
      "uptime_raw": "15:03:55 up 12 days, 1:57, 1 user, load average: 0.22, 0.20, 0.18"
    },
    "cpu": {
      "model": "Intel(R) Xeon(R) Platinum CPU",
      "cores": 2,
      "usage_percent": 8.1,
      "load_avg": [0.22, 0.2, 0.18]
    },
    "memory": {
      "total_bytes": 3898576896,
      "used_bytes": 2795642880,
      "available_bytes": 1102934016,
      "usage_percent": 71.7
    },
    "disk": { ... },
    "docker": { ... },
    "processes": { ... }
  }
}

---

环境要求与运行

依赖环境

• Python >= 3.9
• 依赖库：rich>=13.0.0
• 代码质量工具（可选）：flake8

安装与直接运行

# 安装依赖
pip install rich

# 运行 OpenTUIPanel
python3 main.py

代码质量检查

flake8 .