1 Introduction

For real-time health monitoring and alerting across my multi-site network, I have always used the combination of uptime-kuma + bark server (for specific setup and configuration, see:Docker Series: Building a Message Push Server Based on Bark Server和Docker Series: Building a Real-time Application Health Monitoring and Alerting System Based on Uptime and Bark)。

However, to be honest, I mainly use this combination for its real-time alerting feature and rarely look at uptime-kuma's real-time monitoring page, for the following reasons:
There is indeed no need to keep staring at uptime-kuma's real-time monitoring page (unless you have dedicated O&M personnel like a real corporate client).
The monitoring methods of uptime-kuma all rely on external probing, which offers a rather single perspective. Staring at it won't reveal much detail, such as: How much traffic is a certain device handling? Is the resource consumption of a certain Docker container or host abnormal? Which hosts have malfunctioning processes? How much CPU and memory is a specific process on a host consuming? Are there errors with specified keywords in the logs of a host? Has a critical file on a host been tampered with? Has the content of a specific table in a database reached a certain threshold, etc.
The monitoring display page of uptime-server itself is also quite monotonous and lacks aesthetic appeal:

For the above reasons, I have always used the uptime-kuma + bark server combination solely as a real-time alerting system, never really feeling it had real-time monitoring capabilities.

A few days ago, on a whim, I specifically researched (free) O&M monitoring systems. To my surprise, I actually found one that suits my taste: wgcloud. Although it has minor flaws (the free version has a limit of 10 objects for each feature), overall it meets my requirements: it can do everything I mentioned uptime-kuma couldn't, and the display interface is much more tasteful. The final result is as follows:

This article (Part 1) details the deployment process of wgcloud, and the specific configuration will be introduced in the next part.

2 Deploying wgcloud

1 Environment Preparation

1.1 Installing the Java Environment

The WGCLOUD server can run on JDK 1.8, JDK 11, or higher versions of JDK, and OpenJDK is also supported.
I am using Debian 12, so I followed these steps:
Update software sources

apt update

Install default OpenJDK 11

apt-get install default-jdk

Verify if Java is installed successfully

java -version

For installation methods on other systems, please refer to the official instructions:https://www.wgstart.com/help/docs7.html。

Note: Only the server side needs to deploy JDK; hosts that are only running the agent do not need it.

1.2 Creating a Database (Optional)

wgcloud requires a database. Supported databases (data sources) include: MySQL (both MySQL 5.X and MySQL 8.X are fine), MariaDB, Oracle, PostgreSQL (version 10 or above recommended). You can choose any of the above databases; domestic databases like openGauss and OceanBase are also supported. You can choose based on your own usage habits. I use MariaDB quite a lot for my other applications, so since I have an existing one, I chose MariaDB directly (MySQL is also fine, but given a choice, I always prioritize MariaDB).

wgcloud needs to use the corresponding database in an existing database (MariaDB in my case) and perform initialization configuration. If you don't have a database yet, you need to create a new one.

---

The recommended process for creating a new MariaDB database is as follows:
Create the directory on the host machine that needs to be mounted into the MariaDB container

mkdir -p /docker/mariadb/db

Create the MariaDB container

docker run --name=mariadb01 -d --restart=always \
  -p 3306:3306 \ #映射宿主机的3306端口到容器的3306端口
  -v /docker/mariadb/db:/var/lib/mysql \ # 挂载前面创建的宿主机目录到容器内部指定目录
  -e MARIADB_ROOT_PASSWORD=123 \ #指定数据库root用户对应的密码，这个大家自行修改
  mariadb:10.11

---

1.3 Creating a New wgcloud Database in MariaDB

For details, please refer to my other article:Tips and Tricks Series: Creating a New Empty Database and Granting Permissions to Corresponding Users, and in the following text, it is assumed that the database name, corresponding username, and password after initialization are all ”wgcloud”.

2 Deploying wgcloud Server and Agent

2.1 Downloading and Decompressing the Server

The download link for wgcloud on GitHub is as follows:https://github.com/tianshiyeben/wgcloud/releases, and the latest release when I installed it was wgcloud-v3.5.1.tar.gz (remember to download the server side, as the server package also includes the agent). In addition, the v3.x version is a free but closed-source commercial version, while the free open-source version at my time of writing was v2.3.7.

After downloading, decompress the server side to a specific directory. Here, I place it directly under the /root directory and then decompress it:

cd ~
tar -zxvf wgcloud-v3.5.1.tar.gz

The file structure of the decompressed directory wgcloud-v3.5.1.tar.gz is as follows:

---

Please note the following:
The server directory comes with the agent client. If it is a host with only a single agent, it is also recommended to place it in the same path to facilitate upgrades.
Both server and agent deployments only require decompression and minor necessary modifications to the configuration files before they can be started and run, without the need for compilation.
Only one server needs to be deployed, and all agents report metric data unidirectionally to this server
Deploy as many agents as there are hosts that need to be monitored (even if the server host needs to be monitored, the agent must be started)
The server and agent need to maintain the same version
Monitored host information is automatically collected and reported by the agent, so hosts cannot be added on the server-side host list page. Once the agent is deployed and started, you can see the monitored hosts on the [Host Management] page
wgcloud-daemon-release is a daemon process. Executing server/start.sh will start both wgcloud-server-release.jar and wgcloud-daemon-release. Do not close the daemon process, as the server needs
The system time of the hosts where the server and agent are located must be kept consistent. Even if there is a difference, the time difference should not exceed 15 hours (within this time difference, the agent will print anti-tampering verification failure messages, which can be ignored and will not affect monitoring and collection).
Note that you should not edit/modify server/wgcloud-server-release.jar, otherwise the agent log will show anti-tampering verification failure messages, and it will stop reporting data after a certain period.
If the agent cannot directly access the server, it can report data to the server via the proxy wgcloud-proxy.
If deploying and running
The server and agent can be mixed and matched, as long as they are kept on the same version. That is, if the server runs on Linux, the agent can run on Linux or Windows, and vice versa.

---

2.2 Initializing the wgcloud Database

/root/wgcloud-v3.5.1There are 3 SQL files in the directory:

Since I am using MariaDB, the initialization file selected is:wgcloud-MySQL.sql

There are many ways to apply the wgcloud-MySQL.sql file, taking phpMyAdmin as an example:

Initialization completed:

Of course, you can also import it using the command line format, as follows:

mysql -u root -p -h 127.0.0.1 #数据库IP根据实际情况修改，如果非默认的3306，就用-P参数后加端口
use wgcloud;
source /root/wgcloud-v3.5.1/wgcloud-MySQL.sql

2.3 Configuring the application.yml File

The database pointing of the wgcloud server is determined by/root/wgcloud-v3.5.1/server/config/application.ymlthe following content in the file:

My actual configuration is as follows:

“Other important parameters in the ”application.yml" file are as follows, including the administrator's username and password, web SSH, cluster functions, etc. You can modify them according to your needs. Generally, except for the administrator's username and password, others can be kept as default:

#核心配置参数
base:
  #管理员登陆账号
  account: admin
  #管理员登陆账号的密码
  accountPwd: 111111
  #是否开启免密登录，yes开启，no关闭，此功能开启需升级到专业版
  openSSO: no
  #server和agent的通信密钥，server和agent配置文件中的wgToken值要保持一致
  wgToken: wgcloud
  #每页显示多少条数据，建议不小于10
  pageSize: 20
  #是否开启web ssh客户端，yes开启，no关闭
  webSsh: yes
  #web ssh客户端的服务端口，如果要使用web ssh，那么server主机的9998端口要在防火墙放行，不用web ssh可不开启
  webSshPort: 9998
  #守护进程访问url，server服务使用，agent不使用，若守护端口修改，那此处的端口也要同步修改下（一般保持默认即可）
  daemonUrl: http://localhost:9997
  #是否开启公众看板，yes开启，no关闭，开启后看板页面无需登陆
  dashView: yes
  #是否开启数据开放接口，yes开启，no关闭
  openDataAPI: yes
  #公众看板页面主机IP是否开启脱敏显示，yes开启，no关闭
  dashViewIpHide: yes
  #是否开启大屏展示看板，yes开启，no关闭，开启后看板页面无需登陆
  dapingView: yes
  #是否自动闭合左侧菜单，yes是，no否
  sidebarCollapse: yes
  #是否在列表页面显示告警次数，yes是，no否，一般不建议开启(至少不建议长期开启)，因为可能会影响性能
  showWarnCount: no
  #是否开启指令下发(若关闭，将不能再新增和下发指令)，yes是，no否
  shellToRun: yes
  #指令下发不能包含的敏感字符，小写即可，多个用逗号隔开
  shellToRunBlock: 'rm ,mkfs, /dev/,:(){:|:&};:,mv ,wget , install ,del ,delete ,format ,ren ,rd ,rd/s/q ,rmdir '
  #数据监控的sql语句，不能编写出现的敏感字符（即sql可能注入的关键字），小写即可，多个用逗号隔开
  sqlInKeys: 'execute ,update ,delete ,insert ,create ,drop ,alter ,rename ,modify '
  #数据表监控间隔,单位秒，默认60分钟
  dbTableTimes: 3600
  #服务接口监控间隔，单位秒，默认10分钟
  heathTimes: 600
  #ftp/sftp服务监控间隔，单位秒，默认10分钟
  ftpTimes: 600
  #数通设备PING监控间隔，单位秒，默认15分钟
  dceTimes: 900
  #数通设备snmp监测间隔，单位秒，默认20分钟
  snmpTimes: 1200
  #告警缓存时间(即静默时间)间隔(此时间段内同一告警通知不再重复发)，单位秒，默认120分钟。此期间只是不推送告警到第三方（邮件钉钉微信等）了，系统监控扫描工作仍正常进行
  warnCacheTimes: 7200
  #监控数据保留天数，默认30天
  historyDataOut: 30
  #监控数据趋势折线图，每个图表每次查询时最多展现的数据量，若数据量超过此值，系统则会自动均衡化处理数据，最终保留的数据量等于此值，主要为防止图表一次展示过多数据导致浏览器卡顿，配置为0表示不压缩均衡化处理数据
  chartDataMaxShowValue: 4000
  #节点类型，master或slave，一个集群只能有一个master和N(最多31)个slave，如：slave1，slave2
  nodeType: master
  #是否开启使用标签，yes开启，no关闭
  hostGroup: no

2.4 Starting the Server

cd /root/wgcloud-v3.5.1/server
ls -l

If there is no execution permission, use the following command to add it:

chmod +x start.sh
chmod +x stop.sh

Start the server side of wgcloud:

sh start.sh #重启也是用该命令，如需停止进程，则使用sh stop.sh

The result is as follows:

Note 1: Starting the server will also start the daemon process wgcloud-daemon-relese, do not close the daemon process.
Note 2: If the host deploying the wgcloud server side has a firewall or security group, ports 9999 and 9998 need to be opened (9998 is the web ssh port, which does not need to be opened if not required).

2.5 Starting the Agent

The agent also has a corresponding configuration file, and its path is:

/root/wgcloud-v3.5.1/agent/config/application.properties

In the agent's configuration file, the only thing that needs to be modified is serverUrl, which needs to be changed to the server's address. However, the only exception is the agent on the server side itself, which does not need to be modified:

Note 1:wgTokenis the key for communication between agent and server, equivalent to a password. You can customize it to your own configuration password (needs to be consistent with the one in server/config/application.ymlwgTokenvalue), keep it default for now
Note 2: The agent actively and unidirectionally reports collected data to the server. The agent host does not need to open any ports because the server will not access the agent.

Starting the agent is the same as starting the server in the previous section, just in a different directory:

cd /root/wgcloud-v3.5.1/agent
ls -l

Start the agent side of wgcloud:

sh start.sh #重启也是用该命令，如需停止进程，则使用sh stop.sh

The result is as follows:

Please download other versions of the agent yourself, which are in the same release link where the server side was downloaded.

If you need to set the agent to start on boot, for Linux you can refer to my other article:Debian Series: 3 Common Ways to Set Commands or Scripts to Run at Startup, for macOS you can add the script to login items, and for the Windows version of the agent, you can register the agent as a service through the regAgentService.bat batch file, and then directly set the service to start on boot. I won't say much more here, as they are all very simple.

For the next part (Functionality Part), please refer to:Home Data Center Series: Deploying Your Own O&M Monitoring System via wgcloud (Part 2): Functionality。