WGCLOUD 这个监控系统很多做运维的朋友应该不陌生。它的优势就是轻、快、功能够用一个小组自己维护几十台机器比直接上一套重型监控平台划算得多。我最近把 WGCLOUD 的 server 端从传统的解压 jar 包部署切到了 Docker顺手把配套数据库也一起容器化了整个过程踩了不少坑理清楚之后发现其实就是几条命令的事。这篇东西适合两类人看一是准备在服务器上用 Docker 部署 WGCLOUD server 端但还没动手的新手二是已经跑起来了但想理解环境变量、数据持久化、升级回滚这些细节的老用户。我尽量把每一步背后的为什么也讲清楚不光是给命令。1. WGCLOUD 是什么为什么偏要用 Docker 来跑 server 端1.1 先搞清楚 WGCLOUD 能干什么WGCLOUD 是一套开源的主机监控系统server 端用 JavaSpring Boot写的agent 端装在每一台被监控主机上负责采集 CPU、内存、磁盘、网络流量、进程、服务、端口这些基础指标还支持日志监控、自定义脚本监控和告警通知。功能覆盖面不比大厂监控平台差多少但资源占用小很多部署链路也短非常适合中小规模集群。我最早接触它还是下载 tar.gz 包找一个空目录解压配一个 MySQL然后 nohup java -jar 起服务这套流程。用起来没毛病但换机器、升级版本、处理 JDK 依赖的时候确实有点烦。好几次遇到操作系统自带 OpenJDK 版本和项目不兼容白白折腾半天。后来我把基础设施逐步容器化WGCLOUD server 端也就顺理成章迁到了 Docker 里。1.2 Docker 部署相比传统方式的优势传统方式其实不复杂那为什么还要多引入一层 Docker我的理由有三个环境一致性server 端依赖 JDK 版本、字符集、时区这些运行时细节。镜像把 JDK 和运行参数都固定好了pull 下来就能跑不会再因为某台机器默认 JDK 版本不对而启动失败。升级回滚方便升级就是拉新镜像重建容器出问题再把旧镜像恢复回来比手动覆盖 jar 包干净得多。迁移友好服务要换机器时只要把 compose 文件和数据卷拷过去一条 docker compose up 就能复现环境不用重新回忆当初是怎么装的。1.3 整体部署架构WGCLOUD 的部署分三部分先把这个架构看清楚后面所有配置都不会懵数据库server 的监控指标数据、主机信息、告警规则全存在这里用 MySQL 或 MariaDB。server 端提供 Web 管理界面默认监听 9999 端口同时负责给 agent 下发指令、接收上报数据。agent 端安装在每台被监控主机上主动向 server 上报采集结果。Docker 部署主要解决数据库和 server 端这两块。agent 端通常直接装在目标主机上一般不建议塞进容器——容器里拿不到宿主机的真实 CPU、内存和磁盘数据那就失去监控意义了。这是很多人第一次部署时容易想歪的地方。2. 部署前的准备镜像、数据库、端口和目录规划2.1 环境要求别急着敲命令先把硬性条件过一遍。我自己的经验是这几条内存建议 2G 以上。server 端 JVM 堆默认开得不算小再加上数据库和系统自身占用1G 内存的云主机跑起来会比较紧张后面我会专门说怎么调堆。需要装好 Docker 和 docker-compose 插件。现在的新版 Docker 直接用 docker compose 命令就行老版本才是 docker-compose语法上有细微差别。数据库建议 MySQL 5.7 / MariaDB 10.x 及以上低版本在某些新版本的自动建表逻辑上会报语法错误。2.2 镜像选择WGCLOUD server 端的镜像在 Docker Hub 上可以直接搜到 ttrsa/wgcloud我实际部署用的就是它。拉镜像时建议把版本 tag 一起带上不要一上来就 latestlatest 会随着上游更新悄悄变化不利于以后回滚到已知稳定版本docker pull ttrsa/wgcloud:latest注意拉取前先确认镜像平台和宿主机架构一致。ARM 机器上如果没指定平台拉下来的是 amd64 镜像启动时会直接报 exec format error。遇到这种情况用 --platform 显式指定或者换对应 arm64 的镜像。2.3 数据库方案选择server 端必须有数据库两条路方案 A复用已有的 MySQL。你本来就有数据库服务在跑那就别折腾直接让 wgcloud 连过去。方案 B用 docker-compose 把 MySQL 和 wgcloud server 一起拉起来。适合全新部署也是我推荐的做法。我推荐方案 B 的理由很实际compose 文件本身就是完整的部署文档换机器直接复制粘贴MySQL 容器重启后数据目录仍然在宿主机上不会因为升级 server 时误删数据库。方案 A 虽然少跑一个容器但 server 升级时要格外小心别把连接串配错指向测试库。不管哪种方案都要提前建一个空库比如 wgcloud字符集用 utf8mb4。server 第一次启动会自动建表不需要你手工导入 SQL——这个机制很多人第一次不知道以为要自己初始化数据库结果重复执行了官方给的部分脚本反而搞出冲突。2.4 端口与目录规划部署前把端口和目录想清楚后面少走弯路。我习惯的规划是这样的项值说明Web 管理端口9999server 端默认 HTTP 端口浏览器访问用agent 连接方向agent 主动连 server:9999防火墙只需放行 9999 入站数据库端口3306容器内部网络时无需暴露到宿主机目录方面我建议至少把两个目录挂到宿主机MySQL 的数据目录以及 server 的日志目录。镜像里 server 日志目录通常是 /usr/local/program/wgcloud/logs挂出来后排错非常方便容器重建也不会丢日志。3. 实操docker-compose 一键拉起 server 端3.1 编写 docker-compose.yml直接给一份我目前跑得比较稳的配置保存为 docker-compose.ymlversion: 3.8 services: wgcloud-mysql: image: mysql:5.7 container_name: wgcloud-mysql environment: MYSQL_ROOT_PASSWORD: root-pass-change-me MYSQL_DATABASE: wgcloud MYSQL_USER: wgcloud MYSQL_PASSWORD: wgcloud-pass-change-me TZ: Asia/Shanghai command: - --character-set-serverutf8mb4 - --collation-serverutf8mb4_unicode_ci volumes: - ./mysql-data:/var/lib/mysql restart: unless-stopped wgcloud-server: image: ttrsa/wgcloud:latest container_name: wgcloud-server depends_on: - wgcloud-mysql ports: - 9999:9999 environment: TZ: Asia/Shanghai WGCLOUD_DB_URL: jdbc:mysql://wgcloud-mysql:3306/wgcloud?useUnicodetruecharacterEncodingUTF-8useSSLfalseserverTimezoneAsia/Shanghai WGCLOUD_DB_USERNAME: wgcloud WGCLOUD_DB_PASSWORD: wgcloud-pass-change-me volumes: - ./wgcloud-logs:/usr/local/program/wgcloud/logs restart: unless-stopped几个细节解释一下免得你抄完不知道发生了什么MYSQL_DATABASE 和 MYSQL_USER 是 MySQL 官方镜像首次初始化时自动建库建账号用的只在数据卷为空时生效。如果你已经有旧的 mysql-data 目录改这两个变量不会起作用。连接串里我带了 useUnicode、characterEncodingUTF-8 和 serverTimezone 参数避免中文乱码和 Java 侧 UTC 与本地时间差 8 小时的问题。depends_on 只保证容器启动顺序不保证数据库已经能接受连接。第一次启动时server 端大概率会因为 MySQL 还没就绪而报一两次错这是正常的restart: unless-stopped 会让容器自动重试。3.2 启动与初始化在 docker-compose.yml 同目录下执行docker compose up -d docker compose ps docker logs -f wgcloud-server观察日志出现类似 started 或者监听 9999 的提示就说明 server 起来了。再确认数据库里已经生成业务表docker exec -it wgcloud-mysql mysql -uwgcloud -p wgcloud -e show tables;如果能看到一批业务相关的表说明自动建表成功。常见坑日志里报 Access denied 或者 Table doesnt exist 时先别急着改代码优先查数据库账号权限。server 首次启动需要建表和后续升级加列的权限只给了 SELECT、INSERT 这类普通权限会直接失败。3.3 验证 server 端启动成功浏览器访问 http://服务器IP:9999能看到登录页就成功了一大半。默认账号一般从登录页提示可以找到常见默认是 admin / 111111登录后第一件事就是改密码这个不用我多说吧。4. 单容器部署只想先跑起来一个 server4.1 用已有 MySQL 直接 docker run你已经有一套 MySQL 在跑时不需要拉一个数据库容器一条 docker run 就够了docker run -d \ --name wgcloud-server \ --restart unless-stopped \ -p 9999:9999 \ -e TZAsia/Shanghai \ -e WGCLOUD_DB_URLjdbc:mysql://你的数据库IP:3306/wgcloud?useUnicodetruecharacterEncodingUTF-8useSSLfalseserverTimezoneAsia/Shanghai \ -e WGCLOUD_DB_USERNAMEwgcloud \ -e WGCLOUD_DB_PASSWORD你的密码 \ -v /srv/wgcloud/logs:/usr/local/program/wgcloud/logs \ ttrsa/wgcloud:latest这里有个高频坑如果 MySQL 和 Docker 在同一台宿主机上容器里访问 localhost 是会失败的因为容器有自己的网络栈。要用宿主机网卡的真实 IP。Windows 和 Mac 的 Docker Desktop 环境则可以直接用 host.docker.internal 这个特殊域名。4.2 环境变量参数解析变量作用备注WGCLOUD_DB_URLJDBC 连接串里面带 ? 参数docker run 时建议用双引号包住整个值WGCLOUD_DB_USERNAME数据库账号建议用专用账号别直接用 rootWGCLOUD_DB_PASSWORD数据库密码密码里带特殊字符时要格外注意转义TZ容器时区不设的话告警时间会整体偏移提醒不同镜像版本的环境变量命名可能有差异。如果你拉到的镜像不识别这套变量启动后还是默认配置不要硬试。docker exec 进容器看 /usr/local/program/wgcloud/application.yml直接在宿主机挂载目录里改配置再重启这是更稳的兜底方案。4.3 首次登录与初始化登录进去之后先别急着加主机按这个顺序来能省掉后面很多怎么不告警的困惑改管理员密码顺便检查登录 IP 限制这类安全项。配置告警接收人和通知通道邮件、Webhook 这类先填上。再去主机管理里看 agent 有没有上报数据。很多人一登录就满界面乱点结果 agent 都没装告警当然一条收不到然后又回头怀疑部署有问题。5. 接入 Agent让监控真正生效5.1 下载并安装 agentserver 端起来不等于监控生效还得在被监控主机上装 agent。WGCLOUD 管理界面里通常提供 agent 包的下载入口也可以直接从 server 容器里的安装目录把 agent 压缩包拷出来或者用 wget 从 server 的下载路径拉。我一般这么做wget http://服务器IP:9999/agent包路径.tar.gz tar -zxvf wgcloud-agent.tar.gz cd agent目录 chmod x start.sh ./start.shagent 是轻量进程资源消耗非常小。我在几台 1C1G 的小机器上都装过完全不影响业务。5.2 agent 配置与连接agent 启动前要确认它知道自己该连哪个 server。配置文件里改 server 地址和端口默认就是连接 server 的 9999 端口。改完重启 agent。网络方向这块要强调一下agent 是主动向 server 发起连接的所以防火墙要放行的是 server 的 9999 入站而不是 agent 的某个端口。只要 agent 所在机器能访问到 server:9999就能正常上报。5.3 验证监控数据回到 Web 界面过一两分钟刷新主机管理能看到主机 IP、CPU、内存、磁盘曲线出来整条链路就算通了。如果 agent 进程起来了但界面里看不到主机优先做两件事在 agent 机器上 curl 一下 server:9999 确认网络通再看 agent 的日志是连接被拒、超时还是鉴权失败日志里写得明明白白。6. 避坑指南部署和日常使用中常见的问题6.1 数据库相关现象大概率原因处理建议容器反复重启数据库连不上、账号权限不足docker logs 看具体报错确认空库已建、账号有 DDL 权限首次启动后缺表账号只给了部分权限用 root 或给足权限的账号重新初始化中文乱码字符集不是 utf8mb4建库时指定 utf8mb4连接串加 characterEncodingUTF-8数据库连接串是我踩坑最多的地方。有一次升级时把 serverTimezone 参数漏了所有监控曲线和告警时间凭空多了 8 小时排查半天才发现是时区参数丢了。建议把这行连接串当成固定模板保存每次部署直接复制。6.2 时区与内存时区问题最隐蔽表现就是告警时间不对很多人以为自己看错了。容器默认 UTC会比本地时间晚 8 小时。解决方案就是启动时加 TZAsia/Shanghaicompose 配置和 docker run 都要加。内存方面小机器部署要注意 server 默认 JVM 堆可能偏大。可以在 docker run 时通过环境变量限制 JVM 参数-e JAVA_OPTS-Xms256m -Xmx768m提示WGCLOUD 本身很轻但数据库连接池和监控数据都在内存里。堆给太小的话主机数量一多就会频繁 Full GC界面卡顿。以我的经验管理 500 台以内的规模1G 堆是相对稳妥的平衡点。6.3 数据持久化新手最容易忽略的就是这个。compose 文件里 MySQL 数据目录如果没挂载到宿主机容器一删所有监控历史全部蒸发。我把数据卷放到独立目录后又额外养成了每天备份的习惯。上次一个朋友部署完没挂卷升级时 docker compose down 顺手把容器删了所有告警历史和数据灰飞烟灭那种体验真的糟心。6.4 端口冲突与防火墙启动前先看一眼 9999 有没有被占ss -lntp | grep 9999如果宿主机上已经有服务在听 9999WGCLOUD 的容器端口映射会失败。要么换宿主机端口映射比如 -p 10099:9999要么先处理掉占用服务。CentOS 这一类系统上端口映射起来了但浏览器打不开多半是 firewalld 或 SELinux 拦住了。先看放行状态再临时关掉 SELinux 测试一下确认是它的问题再写规则别一上来就永久 disable生产环境不安全。7. 日常维护升级、备份与调优7.1 平滑升级升级 server 端其实就是拉新镜像、重建容器两步但顺序有讲究先备份数据库这一步永远别省。docker compose pull 拉新镜像。停旧容器docker compose down。重新 docker compose up -d。docker logs 确认启动正常再观察 agent 是否自动重连。升级前后数据结构可能变化新版本启动时会自动加字段或建新表。我经历过一次小版本升级就是因为备份在手初始化报错后直接回滚到旧镜像零损失切回原样。没有备份的话这种时候就只能干瞪眼。7.2 数据库备份与恢复最稳的备份方式还是 mysqldumpdocker exec wgcloud-mysql mysqldump -uwgcloud -p wgcloud wgcloud-backup-$(date %F).sql恢复时先建好空库再导入docker exec -i wgcloud-mysql mysql -uwgcloud -p wgcloud wgcloud-backup-2025-01-01.sql我会配合 crontab 每天凌晨执行备份保留最近 7 天。备份文件不大监控系统几万条历史指标压缩下来也就几十兆留着绝对不亏。没有定期备份习惯的人第一次出事时都会后悔没早做。7.3 性能观察与调优主机数量上来之后先看 WGCLOUD 自己监控面板里 server 进程的内存曲线再决定要不要调整堆大小。别凭感觉直接给 4G 堆堆设太大反而让整机内存吃紧尤其是容器里还同时跑着 MySQL 的场景。容器化部署的好处就在这里docker stats 一眼就能看到 server 容器和数据库容器的真实占用调优不再是盲人摸象。我实际用下来的一套经验先按 768M 堆起步观察两天曲线如果 GC 频繁且有大量主机的场景再逐步往上加。WGCLOUD 在中小规模下的运维成本确实低配合 Docker 之后从部署到升级到备份都能用标准容器流程来管理这套组合我用到现在没后悔过。