ProberX 使用指南

轻量级自托管服务器管理与监控平台。不止于监控 — 集成 14 个运维工具箱，覆盖日常运维全链路。

快速开始

Docker 一键部署

git clone https://github.com/longdicode/ProberX.git
cd ProberX
bash setup.sh

手动部署

cp .env.example .env
# 编辑 .env — 修改 JWT_SECRET 和 POSTGRES_PASSWORD
docker compose -f docker-compose.prod.yml up -d

启动后访问：

管理后台: http://your-server:3000
API 健康检查: http://your-server:4000/health

安装 Agent

Agent 是部署在被监控服务器上的探针。Go 单二进制，零依赖。

# 一键安装
curl -fsSL https://github.com/longdicode/ProberX/releases/latest/download/install-agent.sh | sudo bash -s http://your-dashboard:4000

# 或手动下载
wget https://github.com/longdicode/ProberX/releases/latest/download/agent-linux-amd64 -O /usr/local/bin/proberx-agent
chmod +x /usr/local/bin/proberx-agent
export DASHBOARD_URL=http://your-dashboard:4000
export AGENT_TOKEN=your-token
proberx-agent

提示: Agent 启动后会自动注册到 Dashboard。在管理后台"服务器"页面可以看到它。

环境变量

变量	默认值	说明
`PORT`	3001	Dashboard 端口 (容器内部)
`DATABASE_URL`	-	PostgreSQL 连接串
`REDIS_URL`	redis://localhost:6379	Redis 连接串
`JWT_SECRET`	- (最少16位)	JWT 签名密钥
`CORS_ORIGIN`	http://localhost:3000	允许的跨域来源，逗号分隔
`QUEUE_ENABLED`	false	启用 BullMQ 消息队列
`DASHBOARD_PORT`	3001	Dashboard 宿主机端口
`FRONTEND_PORT`	3000	前端宿主机端口

Agent 环境变量

变量	默认值	说明
`DASHBOARD_URL`	-	Dashboard 地址
`AGENT_TOKEN`	-	认证 Token
`AGENT_PORT`	9800	Agent HTTP 端口
`AGENT_ID`	hostname-pid	Agent 唯一标识

管理后台

管理后台是 ProberX 的核心操作界面。首次启动后：

访问 http://your-server:3000
注册管理员账号
创建 Workspace（工作空间）
在 Workspace 内添加 Server，生成 Agent Token
在被监控服务器上安装 Agent

开发模式: 设置 NEXT_PUBLIC_AUTH_BYPASS=true 可跳过登录。仅用于本地开发！

服务器管理

在 Workspace 中添加服务器后，Dashboard 会每 60 秒从 Agent 拉取指标：

CPU 使用率、内存、磁盘、网络流量
系统负载 (1m / 5m / 15m)
GPU 指标 (nvidia-smi)
Docker 容器列表 (CPU / 内存 / 端口 / 状态)
进程列表

支持 WebSSH 终端（浏览器内 Shell）、文件管理器（浏览/上传/下载/编辑）。

监控探测

从 Agent 向目标发起多类型探测：

类型	说明
HTTP(S)	URL 可达性、响应时间、状态码、Body 正则匹配
TCP	端口连通性、建连延迟
ICMP Ping	丢包率、RTT 延迟
DNS	解析结果、解析时间
SSL	证书过期时间、链验证

告警通知

支持 9 种通知渠道：

Webhook / Slack / Discord
Email (SMTP)
钉钉 (HMAC-SHA256 签名)
飞书 (卡片消息)
企业微信
Telegram / Telegram Bot

告警规则支持多指标触发、持续时长阈值，避免抖动误报。

Cron 计划任务

可视化的 Cron 表达式编辑器，支持：

预设快捷选择 (每小时/每天/每周/自定义)
分/时/日/月/周字段可视化编辑
人类可读预览 ("每天凌晨 2:00")
未来 5 次执行时间预览
Server 多选目标
编辑、启用/禁用切换

运维工具箱

工具	功能
Systemd	服务列表、start/stop/restart、状态监控
SSL	证书检查 (SAN/过期/指纹)、ACME 签发续期
Logs	journalctl + 文件日志浏览
Packages	apt/yum/dnf 包列表、可升级检测、批量升级
Nginx	状态查看、配置浏览、虚拟主机 CRUD
App Store	18 个预置应用、Docker Compose 一键部署
Databases	MySQL/PostgreSQL/Redis/MongoDB 安装卸载
Backups	文件/数据库备份恢复、云存储同步
Security	SSH 审计、端口扫描、Fail2ban 管理
Shell AI	自然语言 → AI → Shell (OpenAI/DeepSeek/Claude)
DNS	Cloudflare/DNSPod/GoDaddy/Vercel/DO 统一管理
Docker	镜像列表/拉取/删除/检查/清理
File Manager	文件浏览/读写/上传/下载/新建目录
Firewall	iptables 规则管理

云备份

支持 S3 兼容存储 (AWS S3 / 阿里云 OSS / Cloudflare R2 / MinIO)：

在备份工具中打开 "Cloud Settings"
选择 Provider，填写 Endpoint、Bucket、Access Key、Secret Key
创建备份后一键上传云端
开启 Auto Upload — 备份创建后自动同步
Sync All — 一键全量同步本地到云端
设置 Retention Days 自动清理旧备份

DNS 管理

统一管理 5 个 DNS 服务商的域名和解析记录：

Cloudflare · DNSPod · GoDaddy · Vercel · DigitalOcean

在 DNS 工具中配置 Provider 的 API Key，即可查看 Zone 列表、增删改 Record (A/AAAA/CNAME/MX/TXT/NS/SRV)。

公开状态页

创建公开状态页展示服务健康状态：

在 Workspace 设置中创建 Status Page
设置 slug (例如 my-service)
公开访问: http://your-server:4000/api/v1/public/status/my-service

系统架构

Browser → Frontend (Next.js :3000) → Dashboard (Fastify :4000) → Agent (Go :9800)
                                         ↕              ↕
                                    PostgreSQL + Redis   被监控服务器

数据流: Dashboard 每 60 秒通过 HTTP 从 Agent 拉取指标 → 写入 TimescaleDB → WebSocket 实时推送到前端

Agent 工具调用: 前端 → Dashboard (代理) → Agent HTTP API → 系统命令 (systemctl/docker/iptables 等)

API 参考

所有 API 以 /api/v1/ 为前缀，JWT Bearer Token 认证。

超过 80 个端点，覆盖认证、工作空间、服务器、监控、告警、通知、Cron、API Key、状态页、14 个运维工具。

查看 API 概览: GET /health — 健康检查 (无需认证)

生产部署

国内服务器注意事项

Docker 镜像加速: 编辑 /etc/docker/daemon.json，添加 registry-mirrors: ["https://docker.1ms.run"]
npm 镜像: npm config set registry https://registry.npmmirror.com
安全组/防火墙: 放行 3000 (前端)、4000 (API)、3100 (官网)

数据库初始化: 首次启动后需手动运行 SQL 迁移:

for f in apps/dashboard/src/db/migrations/*.sql; do
  docker exec -i proberx-postgres-1 psql -U proberx -d proberx < "$f"
done

前端重建

重要: NEXT_PUBLIC_* 变量在编译时内嵌。改了 API 地址后必须 docker compose build frontend --no-cache，不能只用 restart。

环境变量检查清单

NEXT_PUBLIC_API_URL 指向正确公网地址 (如 http://1.2.3.4:4000/api/v1)
POSTGRES_PASSWORD 和 DATABASE_URL 密码一致
生产环境 NEXT_PUBLIC_AUTH_BYPASS=false

问题排查

Dashboard 一直重启

docker logs proberx-dashboard-1 --tail 20

常见原因: 数据库表不存在（运行迁移）、密码不匹配（删除 pgdata volume 重建）、module 解析错误（tsconfig 问题）。

前端报 "Failed to fetch"

常见原因: CORS 未配置、NEXT_PUBLIC_API_URL 地址不对（忘了重建前端）、防火墙未放行端口。

Agent 注册失败

检查 Agent 能否访问 Dashboard: curl http://your-dashboard:4000/health

数据库连接失败

检查 PostgreSQL 是否健康: docker compose -f docker-compose.prod.yml ps postgres

ProberX 文档