https://github.com/xhhcn/pulse

Lightweight server monitoring
https://github.com/xhhcn/pulse

golang monitor services

Last synced: about 2 months ago
JSON representation

Lightweight server monitoring

• Host: GitHub
• URL: https://github.com/xhhcn/pulse
• Owner: xhhcn
• License: mit
• Created: 2025-12-18T10:07:53.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2026-05-04T23:05:33.000Z (about 2 months ago)
• Last Synced: 2026-05-05T00:27:31.176Z (about 2 months ago)
• Topics: golang, monitor, services
• Language: Astro
• Homepage: https://xhh.ovh
• Size: 106 MB
• Stars: 114
• Watchers: 0
• Forks: 16
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  



Pulse




  轻量级服务器监控系统


  实时监控 CPU、内存、磁盘、网络等指标





  English | 中文





  

  

  

  





  

  

  



---



  由 DokiDoki CDN 赞助



  

    

  



---

## ✨ v1.3.0 新功能

- 🔐 **共享密钥认证** - 所有客户端使用统一的共享密钥连接服务器，简化部署配置

- 🏷️ **特殊标签支持** - 新增 `traffic:in/out` 和 `speed:in/out` 标签，实时显示流量统计和网络速率

- 🎨 **自定义 CSS/JS** - 支持全站自定义样式和脚本，打造个性化监控面板

---

## 🚀 服务端安装

### 方式一：独立二进制部署（推荐新手和 VPS 用户）

#### 一键安装

```bash

curl -fsSL https://raw.githubusercontent.com/xhhcn/Pulse/main/install-pulse-server.sh | sudo bash

```

脚本会自动：

- ✅ 检测系统架构（amd64 / arm64）

- ✅ 下载对应的二进制到 `/opt/pulse/pulse-server`

- ✅ 配置 `pulse-server.service` 并设置开机自启

- ✅ 顺手装上迁移辅助脚本 `/opt/pulse/scripts/{backup,restore,migrate}.sh`，并创建 `pulse-backup` / `pulse-restore` / `pulse-migrate` 三个 CLI 短链（详见 [迁移到另一台服务器](#-迁移到另一台服务器)）

#### 更新服务端

**amd64:**

```bash

sudo systemctl stop pulse-server && sudo wget https://github.com/xhhcn/Pulse/releases/latest/download/pulse-server-standalone-linux-amd64 -O /opt/pulse/pulse-server && sudo chmod +x /opt/pulse/pulse-server && sudo systemctl start pulse-server

```

**arm64:**

```bash

sudo systemctl stop pulse-server && sudo wget https://github.com/xhhcn/Pulse/releases/latest/download/pulse-server-standalone-linux-arm64 -O /opt/pulse/pulse-server && sudo chmod +x /opt/pulse/pulse-server && sudo systemctl start pulse-server

```

#### 卸载服务端

> 一键安装脚本除了主程序还会落地三件东西：迁移辅助脚本 `/opt/pulse/scripts/{backup,restore,migrate}.sh`、`/usr/local/bin/pulse-{backup,restore,migrate}` 三个 CLI 短链，以及 `/opt/pulse/data/`（数据库 `metrics.db` 在这里）。卸载时按需选择以下两种之一：

**仅删除程序（保留 `/opt/pulse/data/` 下的数据库，方便回滚或日后重装）:**

```bash

sudo systemctl stop pulse-server && sudo systemctl disable pulse-server && \

sudo rm -f /usr/local/bin/pulse-migrate /usr/local/bin/pulse-backup /usr/local/bin/pulse-restore && \

sudo rm -f /opt/pulse/pulse-server /etc/systemd/system/pulse-server.service && \

sudo rm -rf /opt/pulse/scripts && \

sudo systemctl daemon-reload

```

**完全删除（包括数据库 `metrics.db`，不可逆）:**

```bash

sudo systemctl stop pulse-server && sudo systemctl disable pulse-server && \

sudo rm -f /usr/local/bin/pulse-migrate /usr/local/bin/pulse-backup /usr/local/bin/pulse-restore && \

sudo rm -f /etc/systemd/system/pulse-server.service && \

sudo rm -rf /opt/pulse && \

sudo systemctl daemon-reload

```

#### 手动安装

**Linux (amd64)**

```bash

# 下载

wget https://github.com/xhhcn/Pulse/releases/latest/download/pulse-server-standalone-linux-amd64

chmod +x pulse-server-standalone-linux-amd64

# 运行

./pulse-server-standalone-linux-amd64

```

**Linux (arm64)**

```bash

# 下载

wget https://github.com/xhhcn/Pulse/releases/latest/download/pulse-server-standalone-linux-arm64

chmod +x pulse-server-standalone-linux-arm64

# 运行

./pulse-server-standalone-linux-arm64

```

访问 `http://YOUR_IP:8008` 查看监控面板

---

### 方式二：Docker 部署（推荐生产环境）

[![Docker](https://img.shields.io/badge/Docker-xhh1128/pulse-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/xhh1128/pulse)

#### Docker Compose

```bash

mkdir pulse && cd pulse

curl -sSL https://raw.githubusercontent.com/xhhcn/Pulse/main/docker-compose.yaml -o docker-compose.yaml

docker compose up -d

```

> **IPv6 支持**：如果您的服务器需要 IPv6 支持，请参考下方的 [Docker IPv6 配置](#docker-ipv6-配置) 章节。

#### Docker Run

```bash

docker run -d \

  --name pulse-monitor \

  -p 8008:8008 \

  -v $(pwd)/pulse-data:/app/data \

  --restart unless-stopped \

  xhh1128/pulse:latest

```

访问 `http://YOUR_IP:8008` 查看监控面板

---

## 🌐 Docker IPv6 配置

Pulse 支持 IPv4/IPv6 双栈，如果您的服务器需要 IPv6 支持，请按照以下步骤配置：

### 前置要求

1. **确保宿主机已启用 IPv6**

   ```bash

   # 检查 IPv6 是否启用

   ip -6 addr show

   

   # 检查 IPv6 转发是否启用

   sysctl net.ipv6.conf.all.forwarding

   # 如果输出为 0，需要启用：

   sudo sysctl -w net.ipv6.conf.all.forwarding=1

   

   # 永久启用（编辑 /etc/sysctl.conf）

   echo "net.ipv6.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.conf

   ```

2. **配置 Docker Daemon 启用 IPv6**

   编辑或创建 `/etc/docker/daemon.json`：

   ```json

   {

     "ipv6": true,

     "fixed-cidr-v6": "fd00:dead:beef:c0::/80",

     "experimental": true,

     "ip6tables": true

   }

   ```

   

   > **说明**：

   > - `ipv6: true` - 全局启用 Docker 的 IPv6 支持（**必需**）

   > - `fixed-cidr-v6` - Docker 使用的 IPv6 子网范围（可根据实际情况调整）

   > - `experimental: true` - 启用实验性功能（某些 IPv6 功能需要）

   > - `ip6tables: true` - 启用 IPv6 的 iptables 支持（用于网络隔离和端口映射）

   

   重启 Docker 服务使配置生效：

   ```bash

   sudo systemctl restart docker

   ```

3. **配置 docker-compose.yaml 启用 IPv6**

   在 `docker-compose.yaml` 中配置网络启用 IPv6：

   ```yaml

   services:

     pulse:

       image: xhh1128/pulse:latest

       container_name: pulse-monitor

       ports:

         - 8008:8008

       volumes:

         - pulse-data:/app/data

       restart: unless-stopped

       networks:

         - pulse-network

   volumes:

     pulse-data:

   networks:

     pulse-network:

       enable_ipv6: true

       ipam:

         driver: default

   ```

4. **重新创建容器**

   ```bash

   docker compose down

   docker compose up -d

   ```

5. **验证 IPv6 配置**

   ```bash

   # 检查容器 IPv6 地址

   docker exec pulse-monitor ip -6 addr show

   

   # 测试 IPv6 连接（如果容器有 ping6）

   docker exec pulse-monitor ping6 -c 2 2001:4860:4860::8888

   ```

---

## 📦 客户端安装

### Linux

```bash

curl -sSL https://raw.githubusercontent.com/xhhcn/Pulse/main/client/install.sh | sudo bash -s -- \

  --id  --server  --secret 

```

### macOS（Intel / Apple Silicon）

安装脚本会自动检测 CPU 架构，并将服务注册为 `launchd` 守护进程（开机自动启动）：

```bash

curl -sSL https://raw.githubusercontent.com/xhhcn/Pulse/main/client/install.sh | sudo bash -s -- \

  --id  --server  --secret 

```

> **注意**：macOS 需要 `sudo` 权限以便将 `.plist` 写入 `/Library/LaunchDaemons/`。

**macOS 服务管理命令：**

```bash

# 查看运行状态

sudo launchctl print system/com.pulse.client

# 查看日志

tail -f /var/log/pulse-client.log

# 重启服务（推荐方式）

sudo launchctl kickstart -k system/com.pulse.client

# 停止服务

sudo launchctl bootout system/com.pulse.client

# 重新启动已停止的服务

sudo launchctl bootstrap system /Library/LaunchDaemons/com.pulse.client.plist

```

### Windows (管理员 PowerShell)

```powershell

powershell -ExecutionPolicy Bypass -Command "& { $env:AgentId=''; $env:ServerBase=''; $env:Secret=''; irm https://raw.githubusercontent.com/xhhcn/Pulse/main/client/install.ps1 | iex }"

```

| 参数 | 说明 |

|------|------|

| `` | 服务器唯一标识（在管理后台添加系统时设置） |

| `` | 服务端地址，如 `http://your-server:8008` |

| `` | 认证密钥（在管理后台添加系统后自动生成，可在系统详情中查看） |

> **注意**：`--secret` 参数是可选的。如果服务端系统配置了 secret，则必须提供正确的 secret 才能成功注册。

### 卸载客户端

> 客户端默认开启自动更新，因此 systemd 上除了 `pulse-client.service` 还有 `pulse-client-update.service` + `pulse-client-update.timer` 两件，macOS 上则多一个 `com.pulse.client.update` 守护进程。下面的命令同时清理这些组件，无论之前是否启用过自动更新都能安全运行（缺失的 unit 会被忽略）。

**Linux (systemd):**

```bash

sudo systemctl stop pulse-client pulse-client-update.timer 2>/dev/null

sudo systemctl disable pulse-client pulse-client-update.timer 2>/dev/null

sudo rm -f /opt/pulse/probe-client /opt/pulse/update.sh \

  /etc/systemd/system/pulse-client.service \

  /etc/systemd/system/pulse-client-update.service \

  /etc/systemd/system/pulse-client-update.timer

sudo systemctl daemon-reload

```

> 同一台机器若同时跑了服务端，请保留 `/opt/pulse/`（仅删上面列出的客户端相关文件即可），数据库不受影响。

**macOS（含自动更新）:**

```bash

sudo launchctl bootout system/com.pulse.client 2>/dev/null || true

sudo launchctl bootout system/com.pulse.client.update 2>/dev/null || true

sudo rm -rf /opt/pulse \

  /Library/LaunchDaemons/com.pulse.client.plist \

  /Library/LaunchDaemons/com.pulse.client.update.plist

```

**Windows (管理员 PowerShell):**

```powershell

Stop-ScheduledTask -TaskName 'PulseClient' -ErrorAction SilentlyContinue; Unregister-ScheduledTask -TaskName 'PulseClient' -Confirm:$false -ErrorAction SilentlyContinue; Remove-NetFirewallRule -DisplayName 'Pulse Monitoring Client*' -ErrorAction SilentlyContinue; Remove-Item -Path "$env:ProgramFiles\Pulse" -Recurse -Force -ErrorAction SilentlyContinue

```

---

## ⚙️ 使用方法

1. 访问 `http://YOUR_IP:8008/admin` 进入管理后台

2. 首次访问设置管理密码

3. 点击 **Add System** 添加服务器

4. 添加系统后，系统会自动生成一个 **Secret**（认证密钥）

5. 在目标机器上运行客户端安装命令，**必须包含正确的 Secret**

6. 数据自动上报，实时显示

> **提示**：在管理后台的系统列表中，点击系统右侧的复制按钮可以快速复制包含 Secret 的安装命令。

---

## 📊 监控指标

| 指标 | 内容 |

|------|------|

| **CPU** | 使用率、核心数、型号 |

| **内存** | 使用率、总量 |

| **磁盘** | 使用率、总量 |

| **网络** | 上传/下载速率、TCPing延迟 |

| **系统** | 运行时间、IP、位置 |

---

## 🚚 迁移到另一台服务器

Pulse 服务端的全部状态（系统列表、共享密钥、TCPing 历史、管理员密码、面板配置……）都只保存在 **一个 bbolt 文件** 里。仓库提供的 `scripts/migrate.sh` 把整个流程打包成 **一条命令**：在新服务器上跑一次，就能从旧服务器把所有数据搬过来，**旧服务器全程不停机、零数据丢失**。

> 客户端 `AGENT_ID` / `SECRET` 保持不变，只有 `SERVER_BASE`（服务端地址）可能需要改。  

> 如果旧端用的是域名 + 反代，只需把 DNS 切到新 IP 即可，客户端完全不用动。

### ✨ 一条命令完成迁移

```bash

# ── 在新服务器上 ──

# 1) 安装 Pulse（二选一）

#    A. 独立二进制（systemd） — 推荐，资源占用最小

#       安装器会顺便把 backup/restore/migrate 脚本装到 /opt/pulse/scripts/

#       并创建 pulse-migrate / pulse-backup / pulse-restore 三个命令。

curl -fsSL https://raw.githubusercontent.com/xhhcn/Pulse/main/install-pulse-server.sh | sudo bash

#    B. Docker Compose

# mkdir pulse && cd pulse && \

# curl -sSL https://raw.githubusercontent.com/xhhcn/Pulse/main/docker-compose.yaml -o docker-compose.yaml && \

# docker compose up -d && \

# curl -fsSL https://raw.githubusercontent.com/xhhcn/Pulse/main/scripts/migrate.sh -o migrate.sh && chmod +x migrate.sh

#       migrate.sh 会自动从仓库拉取它所依赖的 backup.sh / restore.sh，一个文件够用

# 2) 一条命令迁移 —— 交互式输入旧服务器的管理员密码

sudo pulse-migrate --from https://OLD_HOST                 # 二进制方式（最便捷）

# 或在 Docker 目录里：

# sudo ./migrate.sh --from https://OLD_HOST

# 非交互（CI/自动化，推荐用 env var 避免密码进 `ps`）：

# sudo PASSWORD='旧服务器密码' pulse-migrate --from https://OLD_HOST -y

```

`migrate.sh` 按顺序完成：

1. 用你提供的密码登录 **旧服务器**，换取一次性管理员令牌（密码通过 stdin 传给 `curl`，不会出现在 `ps` 里）。

2. 调用 `GET /api/admin/backup` 拉一份 **事务级一致性** 的热备份——基于 bbolt 的 `Tx.WriteTo`，不会捕获到半写入页，**旧服务器不停机**。

3. 校验下载文件：大小 + bbolt 魔数 `0xEDDA0CED`，避免 `scp` 断流或误传成 `.gz` 直接使用。

4. 自动识别新服务器是 **Docker** 还是 **独立二进制**，停服 → 把当前 `metrics.db` 另存为 `metrics.db.pre-restore-<时间戳>`（一条命令回滚）→ 放入新文件 → 重启服务。

5. 轮询 `/healthz` 直到返回 200，或 60 秒超时后打印日志并给出回滚命令。

默认把下载的备份文件放在权限 `0700` 的私有临时目录，文件本身 `0600`，成功后自动清理；加 `--keep-backup ./pulse-backup.db` 可以保留一份做离线归档。

### 💾 只想手动备份？管理面板一键下载

进 `/admin` 登录后，表头右上角多了一个 **下载备份** 按钮（下载图标，绿色悬停色）。点一下浏览器就会保存一个 `pulse-backup-.db` —— 跟 `pulse-backup` / `migrate.sh` 拉到的**完全是同一个文件**（事务级一致热快照，基于 `Tx.WriteTo`），可以直接喂给 `sudo pulse-restore <文件>` 在任意新机器上还原。适合：没 SSH 环境、想快速做一次性备份、或者给迁移留个保险。

### 🔐 安全要点（认真看一眼，30 秒）

- **用 HTTPS 或 SSH 隧道**。备份里带着管理员密码哈希 + 每台机器的共享密钥，纯 HTTP 走公网等于把钥匙挂外面。脚本会在检测到非本地 `http://` 时弹出提醒。没有 HTTPS 时推荐：

  ```bash

  ssh -fN -L 8008:localhost:8008 user@OLD_HOST

  sudo pulse-migrate --from http://localhost:8008

  ```

- **别用 `--password '明文'`**。命令行参数在 `ps` 里所有本机用户都看得到。优先：交互式提示（无参数）或环境变量 `PASSWORD='...' pulse-migrate ...`。

- **备份文件 = 生产 DB**。保存时用 `0600` 权限（脚本已做），传输时走加密通道，不用了就删。

- **服务端已经做了多层防护**：登录 5 次失败锁 IP 15 分钟、密码 bcrypt、`/api/admin/backup` 只认 `Authorization: Bearer`（拒绝 `?token=` query，避免令牌进 nginx 日志）、每次备份都会写一条审计日志（包含客户端 IP）。

### 🔁 客户端地址更新（仅当 URL 变了）

```bash

# Linux（systemd 客户端）

sudo sed -i 's#http://OLD_HOST:8008#http://NEW_HOST:8008#g' \

  /etc/systemd/system/pulse-client.service

sudo systemctl daemon-reload && sudo systemctl restart pulse-client

```

### 🛡️ 回滚

旧的 `metrics.db` 在迁移时被自动备份为 `metrics.db.pre-restore-<时间戳>`，随时可以回滚：

```bash

# 独立二进制

sudo systemctl stop pulse-server

sudo cp /opt/pulse/data/metrics.db.pre-restore-* /opt/pulse/data/metrics.db

sudo systemctl start pulse-server

# Docker

docker compose stop

cp datatz/metrics.db.pre-restore-* datatz/metrics.db

docker compose up -d

```

在 `/admin` 登录正常、系统列表齐全、TCPing 图表渲染正常后，再删除这些 `.pre-restore-*` 文件即可。

### 📅 顺便：周期性备份

同一套脚本可以挂到 cron 做日常热备（零停机）：

```bash

# 每天 UTC 03:00 一次，环境变量传密码避免 ps 泄漏

0 3 * * * PASSWORD='YourAdminPW' /opt/pulse/scripts/backup.sh \

  --server http://127.0.0.1:8008 \

  --output /var/backups/pulse/pulse-$(date -u +\%Y\%m\%d).db

```

### ⚠️ 注意事项

- **备份文件等同于全部密钥**：里面包含所有系统的共享密钥和管理员密码哈希，和生产 DB 一样谨慎对待（文件权限、传输通道）。

- **不要同时运行两台服务端指向同一套客户端**——客户端会上报给最先通的那台，数据会分裂。迁移完成后及时下线旧端。

- **脚本参数全览**：`pulse-migrate --help`、`pulse-backup --help`、`pulse-restore --help`（或直接 `/opt/pulse/scripts/*.sh --help`）。

---

## ✨ 新特征

- 私有化模式

- Logo和名称自定义

- CPU类型检测

- 客户端一键部署

---

## 📄 License

[MIT](LICENSE)