GridPerch 使用教程

产品概述

GridPerch 是一款开箱即用的轻量级分布式运维监控系统，主打极简部署、自动化运行、零模板零脚本。 服务端与采集端协同工作，可监控数千台主机。

核心监控指标

支持的资源监控

可视化与告警

告警闭环怎么用

告警的价值不在于「发出来」，而在于「有人管、有记录、有结论」。控制台「告警」页提供四件事：

关键特性

架构与端口

┌──────────────┐POST /agent/minTask┌───────────────┐     ┌──────────┐
│ gridperch-  │───────────────────►│ gridperch-   │────►│ SQLite   │
│ agent        │  JSON + MD5(token) │ server        │     │ 单文件库 │
│ 采集端        │◄───────────────────│ 服务端 / 控制台 │◄────│ 读写分离 │
│ 本地探针│  GET /agent/tasks     └───┬───────┬───┘     └──────────┘
└──────────────┘                          │       │ 平台代拉（可选）
                                  内嵌静态资源     ▼       ▼
                              Web 控制台 + 大屏   ┌──────────────────┐
                                （浏览器）        │ 授权系统（独立）   │
                                                  └──────────────────┘

Docker Compose 部署推荐

最省事的方式。整个系统一个容器、一个数据目录，备份就是拷一个目录。

1. 准备目录

mkdir -p /opt/gridperch/data
cd /opt/gridperch

2. 编写 docker-compose.yml

services:
  gridperch:
    image: gridperch/gridperch:latest
    container_name: gridperch
    restart: unless-stopped
    ports:
      - "9999:9999"
    volumes:
      # SQLite 数据库所在目录，必须挂载，否则容器重建后数据全丢
      - ./data:/opt/gridperch/data
      # 采集端发布物缓存目录（用于一键安装采集端），可选
      - ./releases:/opt/gridperch/releases
    environment:
      # 监听地址：保持默认，不要写成 127.0.0.1，否则其他主机接不进来
      GRIDPERCH_ADDR: ":9999"
      # SQLite 文件路径
      GRIDPERCH_DB: "/opt/gridperch/data/gridperch.db"
      # 采集端通信密钥，两端必须一致，建议部署后立即修改
      GRIDPERCH_TOKEN: "请改成你自己的密钥"
      # 控制台初始账号密码，仅首次启动生效
      GRIDPERCH_ADMIN_USER: "admin"
      GRIDPERCH_ADMIN_PASS: "请改成强密码"
      # 对外访问地址，反向代理 / 端口映射场景务必显式指定
      # 安装脚本与采集端升级下载都用它拼装绝对地址
      GRIDPERCH_PUBLIC_URL: "http://192.168.1.10:9999"
      # 历史数据保留天数，0 表示永久保留
      GRIDPERCH_RETENTION: "30"
      # 超过该秒数未上报判定主机离线
      GRIDPERCH_OFFLINE_SEC: "180"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9999/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

3. 启动

docker compose up -d
docker compose logs -f --tail=100

看到 控制台访问地址：http://…:9999 即启动成功，浏览器打开该地址，用上面设置的账号登录。

4. 常用运维命令

docker compose restart gridperch   # 重启
docker compose stop gridperch      # 停止
docker compose up -d                # 启动
docker compose logs -f              # 跟踪日志
docker compose pull && docker compose up -d   # 拉新版并重建

1Panel 部署

1. 安装 Docker 应用

   在 1Panel 左侧「应用商店」搜索并安装 Docker（若已安装可跳过）。

2. 新建容器

   「容器」→「创建容器」，填写：

   字段	值
   名称	gridperch
   镜像	gridperch/gridperch:latest
   重启策略	始终重启
   端口映射	主机 9999 → 容器 9999
   文件夹	新建 /opt/gridperch/data
   挂载	/opt/gridperch/data → /opt/gridperch/data（读写）
   环境变量	见下方表格

3. 设置环境变量

   变量	建议值
   GRIDPERCH_TOKEN	自定义强密钥
   GRIDPERCH_ADMIN_USER	admin
   GRIDPERCH_ADMIN_PASS	自定义强密码
   GRIDPERCH_PUBLIC_URL	http://服务器IP:9999

4. 配置反向代理（可选）

   「网站」→「创建网站 → 反向代理」，域名如 monitor.example.com， 代理地址填 http://127.0.0.1:9999。 配了反向代理后务必把 GRIDPERCH_PUBLIC_URL 改成 https://monitor.example.com。

5. 防火墙放行

   服务器防火墙与云安全组都要放行 9999/TCP（或反向代理的 443）。

宝塔面板部署

1. 安装 Docker 管理器

   「软件商店」→ 搜索 Docker 管理器 → 安装。

2. 添加容器

   「Docker」→「容器管理」→「添加容器」，镜像填 gridperch/gridperch:latest， 端口映射 9999:9999，目录挂载 /opt/gridperch/data 到 /opt/gridperch/data。

3. 设置环境变量

   同 1Panel，注意 GRIDPERCH_PUBLIC_URL 要填对外可达地址。

4. 反向代理

   「网站」→ 添加站点 → 反向代理到 http://127.0.0.1:9999。

5. 放行端口

   「安全」→ 添加放行端口 9999。

Linux 二进制部署

不想用容器时，直接跑二进制。服务端只需要 glibc 与一个可写目录。

1. 下载并安装

mkdir -p /opt/gridperch/data && cd /opt/gridperch
curl -fLo gridperch-server https://github.com/sangxi/gridperch/releases/latest/download/gridperch-server-linux-amd64
curl -fLo gridperch-agent   https://github.com/sangxi/gridperch/releases/latest/download/gridperch-agent-linux-amd64
chmod +x gridperch-server gridperch-agent
./gridperch-server -version

2. 前台试跑

./gridperch-server \
  -addr :9999 \
  -db ./data/gridperch.db \
  -token '你的通信密钥' \
  -user admin -pass '你的控制台密码' \
  -public-url 'http://192.168.1.10:9999'

确认能访问 http://服务器IP:9999 后再做成systemd 服务。

3. 注册为 systemd 服务

sudo tee /etc/systemd/system/gridperch.service >/dev/null <<'EOF'
[Unit]
Description=GridPerch 运维监控服务端
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/gridperch
ExecStart=/opt/gridperch/gridperch-server -addr :9999 -db /opt/gridperch/data/gridperch.db -token 你的通信密钥 -user admin -pass 你的控制台密码 -public-url http://192.168.1.10:9999
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now gridperch
sudo systemctl status gridperch --no-pager

4. 常用命令

systemctl restart gridperch
journalctl -u gridperch -f          # 实时日志
journalctl -u gridperch --since today

Windows 部署

服务端

# 解压到 C:\GridPerch
cd C:\GridPerch
.\gridperch-server.exe -addr :9999 -db .\data\gridperch.db -token 你的通信密钥

注册为开机自启（需管理员 PowerShell）：

$action = New-ScheduledTaskAction -Execute 'C:\GridPerch\gridperch-server.exe' `
  -Argument '-addr :9999 -db C:\GridPerch\data\gridperch.db -token 你的通信密钥'
$trigger= New-ScheduledTaskTrigger -AtStartup
$principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -RunLevel Highest
Register-ScheduledTask -TaskName 'gridperch' -Action $action -Trigger $trigger `
  -Principal $principal -Force
Start-ScheduledTask -TaskName 'gridperch'

放行防火墙

netsh advfirewall firewall add rule name="GridPerch" dir=in action=allow protocol=TCP localport=9999

采集端日常运维

Start-ScheduledTask -TaskName gridperch-agent                          # 手动重启
Get-ScheduledTask -TaskName gridperch-agent | Select-Object State              # 查看状态（应为 Running）
Get-ScheduledTaskInfo -TaskName gridperch-agent | Select-Object LastRunTime,LastTaskResult
Unregister-ScheduledTask -TaskName gridperch-agent -Confirm:$false             # 卸载

文件挂载清单

部署前按这张表核对，避免出现「重启后数据全丢」这类事故。

目录结构

/opt/gridperch/
├── gridperch-server          # 服务端二进制（容器内为镜像自带，不用挂）
├── gridperch-agent           # 采集端二进制（仅手工部署采集端时需要）
├── data/
│   ├── gridperch.db# SQLite 主库 必须挂载
│   ├── gridperch.db-wal      # WAL 日志，与主库同目录
│   └── gridperch.db-shm      # 共享内存索引，与主库同目录
├── releases/                  # 采集端发布物缓存（可选，用于一键安装采集端）
│   └── gridperch-agent-linux-amd64
└── gridperch-file-baseline.json   # 文件防篡改基线（仅采集端，产生在采集端本机）

挂载对照表

时区配置

services:
  gridperch:
    environment:
      TZ: "Asia/Shanghai"
    volumes:
      - /etc/localtime:/etc/localtime:ro

文件权限参考

端口与防火墙

一键安装采集端

1. 控制台生成命令

   登录控制台 → 左侧「监控」→「添加主机」→ 选择系统与架构、填写主机名 → 复制命令。

2. 确认目标平台已发布

   页面会提前校验该「系统 + 架构」是否已有可下发的采集端版本。 平台是按系统 + 架构分别发布的， linux/amd64 发布过不等于 linux/arm64 就能装。

3. 在目标主机执行

   Linux / macOS：

   curl -fsSL "http://服务端IP:9999/install.sh?wgToken=密钥MD5&name=web-01" | sudo bash

   Windows（管理员 PowerShell，单行）：

   Invoke-Expression (Invoke-WebRequest -UseBasicParsing "http://服务端IP:9999/install.ps1?wgToken=密钥MD5&name=win-01").Content

4. 脚本自动完成的事

   识别系统与架构 → 查询平台下发版本 → 下载二进制 → 校验 SHA256 → 拉取平台下发的运行配置 → 注册开机自启的系统服务 （Linux 用 systemd、macOS 用 launchd、Windows 用计划任务）。

5. 确认上线

   主机自动出现在「主机监控」列表中，默认每分钟上报一次。

手工部署采集端

不便执行脚本的场景（安全管控、离线环境）可以手工安装。

Linux（systemd）

sudo install -m 0755 gridperch-agent /usr/local/bin/
sudo tee /etc/systemd/system/gridperch-agent.service >/dev/null <<'EOF'
[Unit]
Description=GridPerch 采集端
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/gridperch-agent -server http://服务端IP:9999 -token 你的通信密钥 -name 本机名
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now gridperch-agent
sudo systemctl status gridperch-agent --no-pager
journalctl -u gridperch-agent -f

macOS（launchd）

sudo install -m 0755 gridperch-agent /usr/local/bin/
sudo tee /Library/LaunchDaemons/gridperch-agent.plist >/dev/null <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>gridperch-agent</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/gridperch-agent</string>
    <string>-server</string><string>http://服务端IP:9999</string>
    <string>-token</string><string>你的通信密钥</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/var/log/gridperch-agent.log</string>
  <key>StandardErrorPath</key><string>/var/log/gridperch-agent.log</string>
</dict>
</plist>
EOF

sudo launchctl load -w /Library/LaunchDaemons/gridperch-agent.plist

卸载

# Linux
sudo systemctl disable --now gridperch-agent
sudo rm -f /etc/systemd/system/gridperch-agent.service /usr/local/bin/gridperch-agent

# macOS
sudo launchctl unload /Library/LaunchDaemons/gridperch-agent.plist
sudo rm -f /Library/LaunchDaemons/gridperch-agent.plist /usr/local/bin/gridperch-agent

# Windows
Unregister-ScheduledTask -TaskName gridperch-agent -Confirm:$false

主机记录会保留，历史数据按服务端保留天数自动清理。

容器内采集宿主主机

需要监控 Docker 所在宿主机的物理指标时，把宿主机根目录挂进容器。

services:
  gridperch-agent:
    image: gridperch/gridperch-agent:latest
    container_name: gridperch-agent
    restart: unless-stopped
    pid: host
    network_mode: host
    volumes:
      # 只读挂载宿主机根目录，让采集端看到真实的 /proc、/sys
      - /:/host:ro,rslave
    environment:
      - TZ=Asia/Shanghai
    command:
      - -server=http://服务端IP:9999
      - -token=你的通信密钥
      - -name=容器宿主机名

服务端配置项

命令行参数优先于环境变量。完整清单如下。

授权中心通信

平台默认已接入内置授权中心（地址已内置在程序里，无需手动填写），每次同步做四件事：

1. 拉取并校验导入授权码（授权中心签发后最长一个间隔内生效）
2. 下载各平台采集端发布物到本地 releases/，设为下发版本
3. 检测到服务端自身有新版本时自动下载、校验 SHA256、替换二进制；就位后按 -hub-restart 决定是否自动重启生效（默认自动）
4. 把采集端升级结果回执授权中心

采集端配置项

主机重命名与删除 1.1.5 起

「主机监控」列表里每台主机行的操作区（最右侧一排图标）有 重命名（铅笔）与 删除（垃圾桶）两个图标，仅管理员可见； 鼠标悬停在图标上会显示完整说明，其余图标依次是 下发指令（终端）、采集端配置（滑块）、归类（文件夹）。 主机名支持中文、日文等任意语言文字（1.1.5 起修复了中文名被一键安装脚本清成一串 - 的问题）。

重命名

主机名由采集端的 -name 启动参数决定，平台无法远端修改已部署主机上的服务参数。 因此平台侧的做法是：把该主机名下的全部数据迁移到新名字，并登记「旧名 → 新名」映射。 迁移范围包括指标、告警、系统事件、目录归属、采集端配置、监控项里的「作用主机」，以及资产管理中的「关联监控主机」。

删除

删除会连同该主机的全部历史数据一起清理，不可撤销。 注意：若该主机的采集端仍在运行，它会在下次上报时被重新发现—— 有活着的采集端就是在线主机。要让它彻底不再出现，请先在目标主机上停用或卸载采集端 （sudo systemctl disable --now gridperch-agent）。

可视化大屏

大屏共 8 套模板，全部用 ECharts 渲染（已内嵌为本地资源，内网离线可用）。

操作方式

修改大屏名称

大屏顶部那个名字（以及浏览器标签页标题）不再是写死的，可以改成自己单位的叫法： 系统设置 →「界面定制」→ 大屏标题，填完保存即可。

• 留空时自动使用「系统名称 + 运维监控中心」——只改系统名称也能整体换名，默认安装下仍是「GridPerch 运维监控中心」
• 改完最迟 10 秒（一次刷新周期）就反映到大屏上，不用重开投屏页面
• 标题过长时头部按省略号截断，鼠标悬停可看全称，不会把两侧的时钟、模板下拉挤变形

投屏建议

• 浏览器按 F11 或点大屏内的「全屏」按钮，隐藏浏览器边框
• 1920×1080 用模板 2 或 6；3840×1080 双屏用模板 7
• 不同屏幕固定不同地址，例如主屏 /screen/2、副屏 /screen/5

图表变成空白？升级到 1.1.6 1.1.6 已修

1.1.6 之前有个缺陷：大屏刚打开时图表正常，约 10 秒后（正好一个自动刷新周期） KPI 数字仍在跳动、所有图表面板却一起变成空白。原因是每次刷新都会重建整块页面 DOM，而 ECharts 实例还绑在被移除的旧容器上，新数据被画到了已经不在页面里的 画布上。1.1.6 起改为「只要容器换了就重建实例」，已彻底修复——升级到 1.1.6 及以上版本即可，无需改动任何配置。

备份与恢复

全部状态都在一个 SQLite 文件里，备份就是拷文件。

在线热备份（推荐）

直接复制 gridperch.db 可能在写入过程中拿到不一致的快照。 用 SQLite 自带的备份命令更稳妥：

# 需要容器内有 sqlite3，或用官方镜像临时起一个
sqlite3 /opt/gridperch/data/gridperch.db ".backup '/opt/gridperch/backup/gridperch-$(date +%F).db'"

停机冷备份（最简单可靠）

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

恢复

docker compose stop gridperch
tar xzf /backup/gridperch-2026-10-11.tar.gz -C /opt/gridperch
docker compose start gridperch

建议的定时备份

# 每天 03:17 冷备一次，保留 14 天
17 3 * * * cd /opt/gridperch && \
  tar czf /backup/gridperch-$(date +\%F).tar.gz data && \
  find /backup -name 'gridperch-*.tar.gz' -mtime +14 -delete

升级与回滚

服务端升级

# Docker
docker compose pull && docker compose up -d

# 二进制（手工替换，务必按下面 5 步）
sudo systemctl stop gridperch
sudo cp /opt/gridperch/gridperch-server /opt/gridperch/gridperch-server.bak
sudo cp 新版/gridperch-server /opt/gridperch/gridperch-server
sudo systemctl start gridperch

手工替换二进制升级步骤

1. 备份旧二进制

   sudo cp /opt/gridperch/gridperch-server /opt/gridperch/gridperch-server.bak

2. 清理待生效标记文件

   sudo rm -f /opt/gridperch/.gridperch-server.pending

   不清掉的话，启动时程序会认为「上次升级尚未生效」而回滚到 .bak，表现为「换了二进制又变回旧版」。这一步最关键。

3. 替换二进制并赋权

   sudo cp 新版/gridperch-server /opt/gridperch/gridperch-server && sudo chmod +x /opt/gridperch/gridperch-server

4. 重启服务

   sudo systemctl restart gridperch

5. 校验版本

   /opt/gridperch/gridperch-server -version

前端（HTML / JS / CSS）通过 //go:embed all:web 编译进同一个二进制，因此升级只需替换这一个二进制文件，无需另行部署静态资源。

平台自升级与自动重启（1.1.3 起）

服务端自身在平台升级换完二进制后会自动重启使新版本生效，不再需要人工 systemctl restart：

• systemd（unit 用 Restart=always）：进程退出后由 systemd 用新版本拉起
• Docker Compose（restart: unless-stopped）：容器 PID 1 退出后由 compose 重启容器
• 手工 nohup 启动：自行拉起同参数的新进程后退出；端口被占用会重试，最多 20 秒
• 新版本启动失败：下次启动时自动回滚到 .bak

行为由 -hub-restart 控制：auto（默认）自动重启生效；off 只替换文件不重启，需人工重启。启动时端口被占用会自动重试最多 20 秒，覆盖「新进程先起、旧进程后退」的交接窗口。

采集端自动升级

采集端按平台配置的检查间隔（默认 30 分钟）查询版本，发现新版本会自行 下载 → 校验 SHA256 → 替换二进制 → 重启，全程不需要登录目标主机。

• 由 systemd / launchd 托管时直接退出交给服务管理器拉起，不会同时跑两个进程
• 替换走「旧文件改名 → 新文件落位」的原子流程，Windows 上正在运行的 exe 也能安全替换
• 校验不过直接中止并保留原进程；替换失败会回滚旧文件

回滚

采集端发布物按「系统 + 架构」分别登记，每个平台可保留多个版本， 其中一个是下发版本——改它就是灰度或回滚。 在控制台「在线升级」页操作即可。

常见问题排查

部署类

数据类

授权中心类

登录与控制台类

排查顺序

1. 看服务端日志：docker compose logs --tail=200 或 journalctl -u gridperch -n 200
2. 看采集端日志：Linux journalctl -u gridperch-agent -n 200， Windows Get-ScheduledTaskInfo -TaskName gridperch-agent
3. 在目标主机自测连通性：curl http://服务端IP:9999/
4. 自测授权中心：curl -o /dev/null -w '%{http_code}' "https://<你的授权中心地址>/api/v1/check?token=xxx"，期望 200
5. 看控制台「操作审计」，确认配置改动是否生效
6. 看控制台「系统设置 → 机器人推送 / 邮件」，确认告警通道是否可用（可点测试）