企业官网建设流程全解析

说起 WGCLOUD，这套监测系统在我这边已经稳定跑了好几个环境。以前部署服务端，流程是装 JDK、下载安装包、解压、改配置、nohup 拉起进程，每台机器都要重复一遍，升级时还担心数据文件被覆盖。后来改用 Docker 部署 WGCLOUD 监控系统 server 端，一条 docker run 就能把服务跑起来，数据用数据卷持久化，迁移和升级都省心很多。这篇文章就把我用 Docker 部署 server 端的完整过程、参数选型和踩过的坑都整理出来，适合两类人参考：一类是想快速搭建一套主机监控、不想被 Java 环境折腾的运维同学；另一类是已经在用 WGCLOUD、考虑从传统部署迁移到容器方式的团队。

1. 部署前先认清架构：server端在监控系统里管什么

1.1 server端与agent端的职责划分

WGCLOUD 是一套开源的轻量级监控系统，整体拆成两个程序：server 和 agent。Agent 部署到每一台需要监控的机器上，按采集周期获取 CPU 占用、内存、磁盘空间、网络流量、进程数量、关键端口连通情况等指标，然后实时上报给 server。Server 端负责接收所有数据、统一落库、汇总计算、生成趋势图表、判断告警阈值，并通过 Web 控制台把结果展示给运维人员。除了基础主机监控，WGCLOUD 还能做应用监控、日志监控、端口探测等，但核心都是围绕"agent 采集、server 汇聚"这个模型运转的。

理解了这层关系，就能明白 server 端是整套系统的中枢。Agent 偶尔掉线，下个采集周期还会补报；但 server 本身如果挂掉或者数据丢失，所有被监控主机的历史曲线和告警记录都会受影响。所以部署 server 端，我优先考虑的就是稳定性、数据持久化和可维护性，这也是我最终全面转向 Docker 部署的直接原因。

1.2 直接跑jar包 vs Docker部署

早期部署 WGCLOUD server，流程是装 JDK、从项目页面下载 server 安装包、解压到固定目录、按需修改数据库配置、再用启动脚本把进程拉起来。这个流程本身不复杂，但有几类问题在实际操作中反复出现。

第一是环境一致性问题。不同 Linux 发行版预装的 JDK 版本不一样，有时候明明按教程操作，启动就报 UnsupportedClassVersionError，最后发现是系统默认 JDK 太老。第二是升级维护问题，替换新包时最怕忘记备份，老安装包里的数据文件被新包覆盖，历史监控数据就全没了。第三是资源管理问题，一台服务器上如果还跑了其他 Java 应用，端口冲突、内存互相挤占的情况时有发生。

Docker 部署恰好把这三类问题都按住了。镜像里已经封装好正确版本的 Java 运行环境，宿主机装没装 JDK 都不影响容器内运行；容器文件系统独立，配合数据卷挂载，升级只是换镜像，老数据目录原封不动；内存和端口可以分别用参数限制和映射，跟其他容器互不干扰。另外还有一层隐藏的收益：用 docker stop 和 docker rm 就能把整个服务卸载干净，不会在系统里留下散落的目录和进程。

1.3 部署前需要搞清楚的三个关键点

在敲 docker run 之前，有三件事最好先想明白，否则后面容易返工。

一是端口规划。WGCLOUD server 默认有两个核心端口：9999 是 Web 控制台访问端口，浏览器打开http://服务器IP:9999就是登录页；9998 是 agent 上报数据的通信端口，每台被监控主机的 agent 都要能访问到服务器上的这个端口。这两个端口通过 docker run 的 -p 参数映射出来即可。

二是数据持久化。WGCLOUD server 默认使用内置数据库保存监控数据，数据落在容器内部某个目录。如果部署时不挂载数据卷，容器一旦被删除，所有历史监控数据会跟着容器一起消失。这个坑我亲眼见过不止一次，后面会专门讲怎么挂载和确认。

三是时区问题。容器默认时区通常是 UTC，监控图表展示的是北京时间，如果不处理，曲线图横轴会整体偏移 8 个小时。虽然控制台页面里可能有时区配置项，但更省事的办法是运行容器时挂载宿主机的时区文件，同时设置 TZ 环境变量，双保险。

2. 环境准备与镜像选型

2.1 服务器资源需要多大

先说结论：WGCLOUD 是个轻量级监控系统，server 端没有想象中吃资源。我个人的经验是，一台 2 核 2GB 的云服务器，跑 server 再带上它自己作为被监控主机，日常负载很轻松。如果监控规模扩大到几十台主机，建议 4 核 4GB，主要余量留给 JVM 堆内存和数据库读写。

如果只是搭建起来体验一下，1 核 1GB 的机器也能跑，但要注意别让内置数据库文件无限制增长。磁盘方面，监控数据会持续写入，建议数据卷所在分区至少留出 20GB 以上余量，具体视监控主机数量和采集频率而定。另外，生产环境不建议用 Windows 宿主机跑，虽然 Docker Desktop 也能跑通，但文件路径格式、卷挂载行为和 Linux 有差异，维护成本反而更高。

2.2 Docker环境检查

确认宿主机装好了 Docker，并且服务处于可用状态。用两条命令快速检查：

docker version docker info

docker version能看到客户端和服务端的版本信息，如果服务端没起来，docker info会直接报错。我遇到过 docker 命令能执行，但docker info提示 Cannot connect to the Docker daemon 的情况，多半是 docker 服务没有启动，用systemctl start docker拉起来就好。版本方面，20.10 以上基本都能放心用，旧版本建议升级，主要是为了容器运行时稳定性和安全补丁。

2.3 镜像与版本标签的选择

WGCLOUD 项目官方会发布 server 端 Docker 镜像，通常从项目主页可以找到镜像仓库地址。拉取时我主要看两个信息：镜像名和版本标签。

测试环境图省事，直接拉 latest 标签；生产环境我建议固定到具体版本号，比如跟随主版本的 v3.x.y 这类标签。固定版本的好处有两个：一是升级行为可控，避免某天重新部署时拉到新版本导致行为变化；二是不会因为 latest 镜像更新而引入未知问题。Docker 镜像支持多标签共存，本地保留旧标签镜像，遇到问题随时回滚。

拉取命令的固定格式是：

docker pull <镜像仓库地址>/<镜像名>:<版本标签>

具体仓库地址和镜像名以项目官方发布页为准。拉取完成后，用docker images确认镜像已经存在于本地。

2.4 数据卷与目录规划的细节

Docker 容器本身是"用完即扔"的，容器删除后，它可写层里所有文件都会丢失。对 WGCLOUD server 来说，最重要的数据是内置数据库文件、日志和配置文件，部署时一定要把这些目录从容器外挂进来。

我通常的习惯是先在宿主机建一个专用部署目录，例如/opt/wgcloud-server/data，然后把容器内部对应的数据目录映射到这个位置。容器内部路径，我使用较多版本的官方镜像是/home/wgcloud，也就是 server 启动时的工作目录和数据目录。但不同版本可能有所调整，最稳妥的做法是看该版本 Dockerfile 里 VOLUME 指令声明的路径，或者用docker exec进入容器，实际看一眼目录结构。

提示：拿不准内部路径时，可以先启动一个不带挂载的临时容器，执行docker exec -it wgcloud-server find / -name "*.mv.db"，找到内置库文件的实际路径，再按这个路径挂载。这一步确认清楚，后面就踏实了。

目录挂载关系确定之后，数据其实只跟这一个目录有关。后续升级容器、删除容器、迁移机器，只要这个目录的备份还在，监控数据就能跟着走，这也是 Docker 部署最值钱的地方。

3. 手把手部署server端

3.1 创建部署目录并拉取镜像

开始之前，先创建宿主机上的数据目录：

mkdir -p /opt/wgcloud-server/data cd /opt/wgcloud-server

这样目录层级清晰，备份、查看日志都集中在一个地方。然后拉取 server 镜像，标签按你在镜像仓库页面确认到的版本填：

docker pull wgcloud/wgcloud-server:latest

拉完之后确认一下：

docker images | grep wgcloud

如果镜像是从私有仓库拉取，记得确保 docker 客户端已经配置好认证信息。

3.2 启动server容器

核心命令如下，我会逐行解释每个参数的含义：

docker run -d \ --name wgcloud-server \ --restart=always \ -p 9999:9999 \ -p 9998:9998 \ -v /opt/wgcloud-server/data:/home/wgcloud \ -v /etc/localtime:/etc/localtime:ro \ -e TZ=Asia/Shanghai \ wgcloud/wgcloud-server:latest

几个参数逐个说明：

• -d：后台运行容器。
• --name wgcloud-server：给容器起固定名字，后续 docker logs、docker stop、docker rm 都可以直接使用，不用记容器 ID。
• --restart=always：容器退出时自动拉起。这个参数在宿主机重启后尤其有用，否则机器一重启，监控系统也要手动恢复。
• -p 9999:9999和-p 9998:9998：把容器内端口映射到宿主机同端口。如果宿主机端口被占用，可以改成别的映射，但 agent 连接端口要对应调整。
• -v /opt/wgcloud-server/data:/home/wgcloud：宿主机数据目录挂载到容器数据目录，这是持久化的关键一步。
• -v /etc/localtime:/etc/localtime:ro：把宿主机时区文件挂进容器，解决监控图表时间偏差问题。
• -e TZ=Asia/Shanghai：同时设置时区环境变量，和上一条双保险。

关于容器内部数据路径/home/wgcloud，再啰嗦一句：不同版本镜像可能不同，务必以你拉取版本的官方文档或 Dockerfile 为准。如果拿不准，可以先不挂载数据卷，启动后用 docker exec 看一眼实际路径，再重新 run。

如果你习惯用 Compose 管理容器，也可以写一份对应的 compose 文件：

services: wgcloud-server: image: wgcloud/wgcloud-server:latest container_name: wgcloud-server restart: always ports: - "9999:9999" - "9998:9998" volumes: - /opt/wgcloud-server/data:/home/wgcloud - /etc/localtime:/etc/localtime:ro environment: - TZ=Asia/Shanghai

保存为 docker-compose.yml 后执行docker compose up -d即可。Compose 的优点是参数一目了然，适合团队协作时留下部署记录。

启动完成后，先看一眼容器状态：

docker ps

这时候容器处于 UP 状态不代表 Web 页面马上能访问，因为 server 第一次启动要做内置数据库初始化，可能要等几十秒到一分钟，不要急着判断失败。

3.3 验证启动过程和控制台

用 docker logs 排查启动问题是最有效的手段。第一次启动时，建议盯着日志看：

docker logs -f wgcloud-server

正常情况下，启动日志会逐步输出数据库初始化、表结构创建等过程。当看到类似 Tomcat started on port 9999 或者 Started ServerApplication 这样的内容，说明容器内的服务已经起来了。

然后用 curl 从宿主机测一下端口：

curl -I http://127.0.0.1:9999

如果返回 HTTP 200 或登录跳转相关的 30x 响应，说明服务对外正常。接下来在浏览器打开http://服务器IP:9999，能看到登录页。WGCLOUD 默认管理员账号一般是 admin/admin。这里必须强调：登录后第一件事是修改默认密码，我见过不少 server 直接暴露在公网、默认密码一直没改的例子，没过多久就被扫描器盯上，甚至配置信息被篡改。

3.4 在受控主机上接入agent

server 起来之后，监控系统还没有数据，因为还没有任何 agent 接入。在一台想被监控的机器上，用类似的 Docker 方式启动 agent：

docker run -d \ --name wgcloud-agent \ --restart=always \ --network host \ -e SERVER_ADDR=192.168.1.100:9998 \ wgcloud/wgcloud-agent:latest

这里的SERVER_ADDR是 server 所在机器的 IP 和通信端口，务必填 agent 能从自身机器访问到的地址。如果 agent 和 server 在同一内网，填内网 IP；如果跨网络，填路由可达的地址。

--network host是 agent 常用的网络模式，因为 agent 除了主动上报数据，还可能要在本地监听端口配合服务端探测，host 模式能直接复用宿主机网络，减少端口映射的麻烦。如果环境不允许 host 模式，也可以用 bridge 模式加端口映射，但需要保证必要端口的连通性。

注意：如果 agent 和 server 跑在同一个宿主机上，agent 使用 host 网络时，SERVER_ADDR直接填127.0.0.1:9998就能连上；如果 agent 使用 bridge 网络，则要填 docker 网关地址，通常是172.17.0.1:9998。很多人在本机测试时连不上 server，就是因为填了容器内部的 IP。

agent 启动后，回到 server 的 Web 控制台，在被监控主机列表里应该能看到这台机器上线。刚接入的几分钟内数据可能还不全，要等至少一个采集周期之后，才能看到完整的 CPU、内存、磁盘指标曲线。如果一直显示离线，排查思路在下一章细说。

3.5 上线后建议立即做的几件事

服务能跑起来只是第一步，把下面几个动作做掉，后续能省很多事：

• 修改管理员密码，设置强密码策略。
• 检查告警配置，把邮件或 Webhook 告警通道先配上，不要等出故障了才想起来。
• 在系统设置里核对时区与时间格式，确保图表时间显示正确。
• 确认监控数据保留周期，按需清理历史数据，避免数据库文件无限增大。
• 给宿主机数据目录设置合理权限，避免其他用户误删或篡改。

这些操作不需要花太多时间，但对一个要长期运行的监控系统来说，价值很大。

4. 运维实操：备份、升级、问题排查

4.1 日常日志查看与容器状态管理

server 跑起来之后，日常基本不用管，但出了状况要知道从哪里看。三个命令建议熟记：

docker ps # 看容器是否在运行 docker logs --tail 200 wgcloud-server # 看最近200行日志 docker stats wgcloud-server # 看容器CPU和内存消耗

docker logs 是排障时最趁手的工具。比如 Web 页面打不开，先看日志里有没有端口绑定失败；agent 全部离线，看日志里有没有连接异常。docker stats 可以顺带观察 server 容器的内存占用趋势。如果内存持续走高，要考虑是不是数据库文件过大或者 JVM 堆配置不够，及时调整。

4.2 常见问题速查表

下面这张表，是我实际部署和帮别人排查时遇到频率比较高的问题，整理成对照关系：

针对几个高频问题，展开讲讲排查思路。

页面打不开：第一步永远是 docker ps 确认容器状态，第二步 docker logs --tail 100 看最后一段日志。这两步能过滤掉八成以上的假死。真正常见的坑是防火墙或安全组只放行了 22 端口，忘记放行 9999，内网机器能访问，外部浏览器就死活打不开，放行端口后立刻就好。

agent 离线：八成问题出在地址配置和网络隔离。先在 agent 所在机器执行telnet <serverIP> 9998，如果端口不通，就是中间网络的锅；如果 TCP 能通但 agent 还是离线，再看 agent 容器日志，确认它有没有成功注册到 server。跨网段部署时，还要注意 agent 版本和 server 版本是否匹配，大版本不一致经常导致握手失败。

时区问题：表现非常典型，曲线图横轴整体偏移 8 小时。处理办法就是挂载时区文件加设置 TZ，重新 run 一次容器，旧数据不受影响。

数据卷路径不对导致的丢失：这是最难受的一种。因为内置数据库文件落在容器内某个具体目录，如果你挂载的路径不是它实际写数据的路径，容器删掉后，宿主机挂载目录里只有一堆无关文件，真正的库文件还是随容器消失了。所以建议启动后第一时间确认数据库文件实际位置，确保挂载点覆盖到位。

4.3 数据备份的推荐姿势

内置数据库是文件型数据库，备份最稳妥的方式是停服拷贝。我的习惯做法：

docker stop wgcloud-server tar -czf wgcloud-backup-$(date +%F).tar.gz -C /opt/wgcloud-server/data . docker start wgcloud-server

先停掉容器再打包，是为了保证数据库文件的一致性。运行中直接复制文件，可能拷到写入中间状态，恢复时未必能正常加载。停服拷贝耗时通常很短，监控数据的空窗期可以接受。

做完一次完整备份后，把命令写进 crontab 定期执行，保留最近若干份即可。备份文件建议至少有一份放在宿主机之外，比如对象存储或另一台机器的备份目录，避免服务器本身磁盘损坏时备份也跟着丢。

4.4 升级与回滚的思路

Docker 部署在升级上优势很明显。步骤是：先备份数据卷，拉取新版本镜像，停掉旧容器，用同一组参数重新 run 新容器，镜像换成新标签，等待启动并验证页面和 agent 状态。

这里有个关键细节：重复 run 时，-v挂载的宿主机路径必须和原来完全一致，新容器才能读到旧数据。升级失败想回滚也很简单，本地保留旧标签镜像，直接用旧标签再 run 一次，数据和配置都还在。

升级后在控制台确认版本号是否符合预期，再看 agent 是否全部正常上线。如果升级后 agent 握手机制有变化，可能需要重启 agent 重新注册，具体看项目升级说明。

4.5 监控规模扩大以后的演进方向

如果监控规模只有几十台主机，用默认内置数据库完全够。但随着规模变大、历史数据保留周期变长，内置数据库可能逐渐成为瓶颈，我建议考虑两条路。

第一，把数据库切换到外部 MySQL 或 MariaDB。项目文档通常会给数据库连接的相关配置，切换后查询性能和容量弹性都有提升，也便于数据库单独备份。切换前一定要先做完整数据迁移，并验证 Web 控制台和告警功能都正常。

第二，给 server 容器合理分配 JVM 内存。默认配置通常比较保守，规模大时可以调整 JVM 堆参数再重启容器。注意别把堆内存设置得超过宿主机实际可用内存，避免把宿主机拖垮。另外，如果有多套业务环境，建议每套环境独立部署一套 server，把 agent 按环境分组，告警归属和权限管理都会清爽很多。

我在多套环境里用 Docker 部署 WGCLOUD server 之后，最大的感受是：监控这种基础设施，最重要的不是第一次能跑起来，而是跑起来之后好维护。数据卷、重启策略、时区、备份脚本，这些细节看起来不起眼，但每一个都是后面省心的前提。尤其是数据卷，我跟身边朋友反复念叨：部署之前先问自己一句，这个目录挂了吗，挂在哪儿了。答案有眉目了，再把 docker run 敲下去。这套流程建议新环境都照这个顺序走一遍，踩坑成本很低，回头看都值得。