SystemController使用开发指导书

作者: Bingo 日期: 2020-10-20

修订记录

版本	时间	修订说明
V1.0	2020-10-20	文档初稿完成, 随v3.0发布
V2.0	2021-12-08	重新修订并重写为MarkDown格式, 随v4.3发布
V2.1	2021-12-22	修改简介
v3.0	2022-02-13	随工具v5.0.1发布, 重命名部分控件名称及其他修订

名称	说明
Docs	工具帮助文档及文档图片归档目录.
Interface	工具界面配置文件(dependence.json)和首选项配置文件(settings.json)以及界面功能脚本所在目录.
Required	工具图标及界面图片所在目录.
LICENSE	工具使用的LICENSE信息文件.
SystemController.exe	工具的主执行程序.

4.使用说明

双击SystemController.exe运行软件

4.1 登录界面

序号	名称	说明
1	服务器信息输入栏	用于输入服务器的IP密码等信息, 登录界面会自动填入预设置的用户名/密码及root密码; 默认值可通过6.首选项进行自定义.
2	添加登录栏按钮	点击后可增加一个服务器信息输入栏用于同时登录多台服务器, 最大可同时登录20台服务器.
3	“小眼睛”按钮	点住鼠标左键可查看隐藏的用户密码和root密码, 释放鼠标变回*号.
4	删除登录栏按钮	点击后可删除对应行的服务器信息输入栏.
5	登录状态提示标签	每台服务器IP登录服务器过程的不同阶段将会显示不同的颜色, 可使用户直观了解当前服务器的登录状态.
6	首选项按钮	点击后可进行首选项配置
7	一键登录按钮	用于可以批量登录服务器, 登录成功后工具将切换至主界面.

4.2 主界面

序号	名称	说明
1	菜单栏和工具栏	提供快捷操作入口和部分额外功能, 例如: 截屏/SFTP.
2	导航栏	工具的主要功能栏, 根据主配置文件生成.
3	操作主界面	各个功能的操作界面, 其界面控件根据主配置文件生成.
4	信息提示栏	界面任务执行的状态和结果提示栏, 主要用于简短信息的提示.
5	选择执行栏	用于选择对应的服务器和执行策略进行界面任务的下发或终止.
6	输出栏	用于显示任务脚本的标准输出和标准错误内容.

5.控件介绍

5.1 Label

控件名	说明
Label	信息显示控件, 主要用于显示提示或警告信息; 也可用于显示界面任务脚本的执行结果信息(推荐使用InfoText代替).

用户只读控件, 控件内容不作为参数传递给界面任务脚本.

5.2 FileButton

控件名	说明
FileButton	按钮控件, 目前仅支持ChooseFile类型,即本地文件选择器.

控件内容传递给界面任务脚本的参数为本地文件的绝对路径.

5.3 Checkbox

控件名	说明
CheckBox	复选框控件, 可同时勾选多个选项, 选中时值为1否则为0.

控件内容传递给界面任务脚本的参数为整形列表: [1,0,0,...]

5.4 Combobox

控件名	说明
Combobox	单选框控件，从给定的一组值中选择一个.

控件内容传递给界面任务脚本的参数为控件选中的字符串.

5.5 Entry

控件名	说明
Entry	输入框控件，接受单行文本信息输入.

控件内容传递给界面任务脚本的参数为输入的字符串或者__None__(未输入时).

5.6 PasswordEntry

控件名	说明
PasswordEntry	输入框控件，接受单行文本信息输入.

控件内容传递给界面任务脚本的参数为输入的字符串或者__None__(未输入时).

5.7 Text

控件名	说明
Text	文本输入框控件，用于输入多行文本信息.

控件内容会首先写入一个临时文件, 再将该文件名作为参数传递给界面任务脚本, 任务脚本中需要从g_upload_dir目录读取该文件, 即为该控件输入的文本内容.

5.8 InfoText

控件名	说明
InfoText	文本信息输出控件, 目前仅用于显示界面任务脚本的执行结果信息.

用户只读控件, 控件内容不作为参数传递给界面任务脚本.

5.9 MultiInfoText

控件名	说明
MultiInfoText	分页显示控件, 用于分别显示多个服务器的界面任务脚本执行结果信息.

用户只读控件, 控件内容不作为参数传递给界面任务脚本.

5.10 MultiCombobox

控件名	说明
MultiCombobox	差异化单选框控件，用于对不同服务器做差异化选择.

控件内容根据服务器IP分别获取, 内容同Combobox一致, 即传递给界面任务脚本的为选中的字符串.

5.11 MultiPlotTab

控件名	说明
MultiPlotTab	图表分页显示控件, 用于分别显示多个服务器界面任务执行后绘制的图表内容.

用户只读控件, 控件内容不作为参数传递给界面任务脚本.

5.12 MultiScaleBar

控件名	说明
MultiScaleBar	图表分页显示控件, 用于同页分别显示多个服务器某数值的进度或者比例.

用户只读控件, 控件内容不作为参数传递给界面任务脚本.

5.13 MultiScaleTab

控件名	说明
MultiScaleTab	图表分页显示控件, 用于分页显示多个服务器某数值的进度或者比例.

用户只读控件, 控件内容不作为参数传递给界面任务脚本.

6.扩展界面及功能

6.1 配置文件解读

6.1.1 Interface/settings.json -- 首选项配置文件

{
    "Settings": {
        "tool_alias": "System Controller",
        "tool_version": "4.2.9",
        "log_level": "info",
        "server_home": "/home/Bingo",
        "retry_times": 2,
        "keepalive_period": 20,
        "refresh_json_period": 20,
        "login_count_limit": 10,
        "preference_ip": [],
        "sshd_port": 22,
        "passwords": {
            "username": "",
            "userpassword": "",
            "rootpassword": ""
        },
        "about_information": ["..."]
    },
    "auto_plot_period": 30,
    "auto_task_period": 20,
    "auto_task_scripts": [
        "timer_watch_system.py"
    ]
}

区域	索引项	说明
Settings	tool_alias	工具定制别名.
.	tool_version	工具定制版本号.
.	log_level	日志打印级别.
.	server_home	服务器脚本部署和运行的根目录.
.	retry_times	登录/任务等失败的重试次数.
.	keepalive_period	ssh保活周期, 单位:秒.
.	refresh_json_period	主界面json配置文件自动刷新周期, 单位:秒.
.	login_count_limit	服务器最大登录数阈值.
.	preference_ip	候选服务器IP列表, 成功登录的服务也会记录在此, 方便下次登录.
.	sshd_port	服务器sshd端口.
.	passwords	预置用户名和密码及root密码, 用于自动填写.
.	about_information	"关于软件"界面定制内容.
.	auto_plot_period	自动画图表周期, 框架提供自动下载<SERVER_DIR>/__DOWNLOAD__目录并画图表的能力, 参考系统监控相关功能.
.	auto_task_period	自动任务周期, 框架提供后台自动执行任务的能力.
.	auto_task_scripts	自动任务脚本列表, 框架提供后台自动执行任务的能力.

6.1.2 dependence.json -- 主界面配置文件

Images 图标域

"Images": {
    "ICO": "app.ico",
    "ABOUT": "about.png",
    "TV_MONITOR": "monitor.png",
    "TV_MON_SYS": "mon_system.png"
}

图标域用于指定工具各界面的"工具栏"和"导航栏"图标.

Trees 导航栏层级关系域

"Trees": [
    {
        "Text": "系统监控",
        "Image": "TV_MONITOR",
        "Page": {},
        "SubTree": [
            {
                "Text": "系统信息",
                "Image": "TV_MON_SYS",
                "Page": {
                    "Widgets": "MonitorSystemInfoWidgets",
                    "Script": "monitor_system_info.py",
                    "Attrs": ["HasBeRunInRoot", "HasPreHandle"]
                },
                "SubTree": []
            }
        ]
    }
]

导航栏层级关系域用于定义工具导航栏的布局关系.

字段	值类型	说明
Text	字符串	导航栏显示的文字及工具栏图标提示文本;该值全局唯一.
Image	字符串	对应Images域中的索引,导航栏及工具栏通过此索引进入界面.
Page	Page: 对象 Widgets: 字符串 Script: 字符串 Attrs: 列表	界面对象元数据(作为父节点时值为"NA"):
		Widgets: 对应Widgets 控件定义域中的索引,用于指定本界面控件布局;
		Script: 界面任务脚本, 对应Interface/Scripts中的任务脚本;
		Attrs: 界面属性,目前包含:
		--HasToolBarIcon: 将本界面添加到工具栏中,工具栏图标同Image;
		--HasNoStartButtons: 指定界面不显示"执行"和"终止"按钮;
		--HasPreHandle: 指定进入界面后将自动执行一次带pre参数的任务脚本;
		--HasBeRunInRoot: 指定界面任务必须使用root执行;
		--HasNotRunInRoot: 指定界面任务必须使用非root执行;
		--IsCustomPage: 指定本界面为自定义界面,界面控件为自实现;
SubTree	列表	子界面对象元数据.本节点作为父节点时才填写.

Widgets 控件定义域

"Widgets": {
    "MonitorSystemInfoWidgets": [
        {
            "WidgetType": "MultiInfoText",
            "WidgetTips": ["系统信息"],
            "WidgetValues": [],
            "WidgetParams": {"Size": [900, 600, 900, 600]},
            "WidgetAttrs": ["HasMarkdownFormat"],
            "WidgetActions": []
        }
    ]
}

控件定义域用于定义各界面的控件组合及控件内容.

字段	值类型	说明
WidgetType	字符串	控件类型;当前支持的控件详见5.控件介绍;
		当需要自己实现一些复杂的界面时, 该项值为"Self", 同时需要自己实现界面类, 类名即为WidgetValues,参考TimezonePage
WidgetTips	列表	控件提示信息; 默认为一行文本内容.
WidgetValues	列表	控件的值:
		-- Label或Entry，则每个元素为一行，显示该值;
		-- Checkbox，则每个元素为一个复选项;
		-- Combobox，则每个元素为一个单选项;
		-- Text或MultiInfoText，则直接显示;
		-- FileButton，则第一个元素为文件类型;
		__LOGIN_IPS__: 为当工具前登录的所有服务器IP;
WidgetParams	对象	控件布局参数;
		Size: 控件的画布大小和控件大小，其元素依次为画布的宽，高, 控件的宽，高. 单位:像素或行数
WidgetAttrs	列表	控件的属:
		HasPermitEmpty: 表明该控件的输入可为空, 即控件内容为空时亦可开始执行任务脚本
		HasMarkdownFormat: 表示该控件用类似Markdown格式的形式显示信息; 目前只支持InfoText和MultiInfoText控件;
WidgetActions	列表	控件需要预先完成的动作; 选择栏点击"执行"任务脚本之前，需要处理的动作;
		UploadFile: 表明执行前，需要先上传该控件输入框中输入的文件到服务器上.

6.2 编写界面任务脚本

6.2.1 内部脚本介绍

脚本名	说明
function_utils.sh	任务脚本和接口脚本依赖的公共函数脚本, 不可篡改或删除.
function_utils.py	任务脚本依赖的python接口, 可扩展, 不可删除.
caller_interface.sh	工具任务执行调用接口脚本, 不可篡改或删除.
sftp_interface.py	SFTP工具调用接口脚本, 不可篡改或删除.
timer_watch_system.sh	工具绘制内存/CPU/磁盘IO等系统资源使用情况图表的数据来源脚本, 可扩展, 不可删除.

6.2.2 编写任务脚本要求

一个界面一个任务脚本;
任务脚本必须使用UTF-8编码格式;
任务脚本必须逻辑清晰, 运行后或重入时不可造成阻塞卡死或异常崩溃;
脚本需要定义固定参数"ENTER"分支, 用于进入界面后自动执行脚本做完成的任务, 通常用于获取当前的状态;
当控件输入为空时, 传递到任务脚本的对应位参数为__None__, 脚本需做特殊判断;
脚本中各个步骤完成的时间要尽可能短;
标准输出和标准错误输出以及工具回显等功能必须使用 common_function.sh 中的函数;
详读 function_utils.sh / function_utils.py 脚本, 了解其提供的全局方法和功能.

6.3 如何添加一个新界面

6.3.1 新增一个界面，你需要:

准备一个18x18像素的png或jpg图标；
修改 dependence.json 界面配置文件；
编写任务脚本；

6.3.1.1 准备图标

推荐网站: https://www.iconfont.cn/ 阿里开源图标库, 下载后使用"格式工厂"或者"PS"进行大小为18x18像素的导出. 更名后放入 Required/Resource目录. 例如:

6.3.1.2 修改 dependence.json

添加 Images

{
"Images": {
    "TV_TEST": "Resource\\treeview_test.png"
}

添加 Trees

"Trees": [
    {
        "Text": "这是一个新的界面",
        "Image": "TV_TEST",
        "Page": {
            "Widgets": "ANewTestPageWidgets",
            "Script": "test_page_task.py",
            "Attrs": ["HasPreHandle"]
        },
        "SubTree": []
    }
]

添加 Widgets

"Widgets": {
    "ANewTestPageWidgets": [
        {
            "WidgetType": "Label",
            "WidgetTips": ["这是一个Label"],
            "WidgetValues": ["这是Label的提示信息的第一行", "这是Label的提示信息的第二行"],
            "WidgetParams": {"Size": [900, 50, 600, 50]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "Entry",
            "WidgetTips": ["这是一个Entry, 用于输入单行文本, 该值所有服务器一致"],
            "WidgetValues": ["这是Entry中的默认值"],
            "WidgetParams": {"Size": [900, 30, 30, 1]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "PasswordEntry",
            "WidgetTips": ["PasswordEntry, 用于密文输入单行文本, 该值所有服务器一致"],
            "WidgetValues": ["这是PasswordEntry中的默认值"],
            "WidgetParams": {"Size": [900, 30, 30, 1]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "FileButton",
            "WidgetTips": ["这是一个FileButton, 用于选择和上传本地文件, 该值所有服务器一致"],
            "WidgetValues": ["*"],
            "WidgetParams": {"Size": [900, 30, 40, 1]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "Checkbox",
            "WidgetTips": ["这是一个Checkbox, 用于多选, 该值所有服务器一致"],
            "WidgetValues": ["Checkbox-A", "Checkbox-B", "Checkbox-C"],
            "WidgetParams": {"Size": [900, 40, 40, 1]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "Combobox",
            "WidgetTips": ["这是一个Combobox, 用于单选, 该值所有服务器一致"],
            "WidgetValues": ["Combobox-0", "Combobox-1", "Combobox-2"],
            "WidgetParams": {"Size": [900, 30, 20, 1]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "MultiCombobox",
            "WidgetTips": ["这是一个MultiCombobox, 用于单选, 该值每个服务器可差异化选择"],
            "WidgetValues": ["", "MultiCombobox-A", "MultiCombobox-B", "MultiCombobox-C"],
            "WidgetParams": {"Size": [900, 50, 20, 3]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "Text",
            "WidgetTips": ["这是一个Text, 用于输入多行文本内容, 该值所有服务器一致"],
            "WidgetValues": [],
            "WidgetParams": {"Size": [900, 60, 600, 3]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "InfoText",
            "WidgetTips": ["这是一个InfoText, 用于同时显示所有服务器的任务结果"],
            "WidgetValues": [],
            "WidgetParams": {"Size": [900, 60, 40, 3]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "MultiInfoText",
            "WidgetTips": ["这是一个MultiInfoText, 用于分页显示每个服务器的任务结果"],
            "WidgetValues": [],
            "WidgetParams": {"Size": [900, 60, 600, 60]},
            "WidgetAttrs": [],
            "WidgetActions": []
        },
        {
            "WidgetType": "MultiScaleBar",
            "WidgetTips": ["这是一个MultiScaleBar, 用于分页显示比例"],
            "WidgetValues": [],
            "WidgetParams": {"Size": [900, 50, 180, 20]},
            "WidgetAttrs": [],
            "WidgetActions": []
        }
    ]
}

6.3.1.3 编写任务脚本

test_page_task.py

# coding=utf-8
import sys
from function_utils import Global, PsUtil

def WriteWidgetValues():
    data = [
        {},
        {},
        {},
        {},
        {},
        {},
        {},
        {},
        {"InfoText": "InfoText"},
        {"MultiInfoText": "MultiInfoText"},
        {"MultiScaleBar": 90}
    ]
    Global.values_write(data)
    Global.report_info(100)


if __name__ == '__main__':
    if sys.argv[1] == 'pre':
        WriteWidgetValues()
    elif sys.argv[1] == 'start':
        data = Global.values_parse(sys.argv[2])
        print(data)
        WriteWidgetValues()

新界面效果图:

7.其他子界面和工具

SystemController除了提供标准的界面以外, 在菜单栏和工具栏中还提供了一些额外的功能和工具, 如下图.

从左到右依次为:

展开导航栏: 用于展开或关闭导航栏的所有节点.
上一页面: 用于快速跳转到上一个页面 (导航栏中的上下页关系).
下一页面: 用于快速跳转到下一个页面 (导航栏中的上下页关系).
屏幕截取: 提供快速截屏功能.
SFTP上传下载: 提供与FileZilla, Xftp等软件类似的上传下载界面和功能.
新建登录: 提供动态添加服务器登录到工具管理列表的功能.
首选项设置: 提供工具首选项配置功能.
帮助文档: 用于快速打开本指导文档的PDF版本.
关于软件: 显示软件说明和版本声明信息.

BingoLee / SystemController .gitee-modal { width: 500px !important; }

SystemController使用开发指导书

修订记录

目录

1.简介

2.安装卸载

3.软件包说明

4.使用说明

4.1 登录界面

4.2 主界面

5.控件介绍

5.1 Label

5.2 FileButton

5.3 Checkbox

5.4 Combobox

5.5 Entry

5.6 PasswordEntry

5.7 Text

5.8 InfoText

5.9 MultiInfoText

5.10 MultiCombobox

5.11 MultiPlotTab

5.12 MultiScaleBar

5.13 MultiScaleTab

6.扩展界面及功能

6.1 配置文件解读

6.1.1 Interface/settings.json -- 首选项配置文件

6.1.2 dependence.json -- 主界面配置文件

6.2 编写界面任务脚本

6.2.1 内部脚本介绍

6.2.2 编写任务脚本要求

6.3 如何添加一个新界面

6.3.1 新增一个界面，你需要:

6.3.1.1 准备图标

6.3.1.2 修改 dependence.json

6.3.1.3 编写任务脚本

7.其他子界面和工具

简介

发行版 (11)

开源评估指数源自 OSS-Compass 评估体系，评估体系围绕以下三个维度对项目展开评估：

贡献者

近期动态

搜索帮助

BingoLee / SystemController