ProberX 使用指南

轻量级自托管服务器管理与监控平台。不止于监控 — 集成 14 个运维工具箱，覆盖日常运维全链路。支持 Web 控制台与 Windows 原生桌面客户端。

快速开始

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 单二进制，零依赖。

# 一键安装（需要 TOKEN）
curl -fsSL https://panel.yqone.cn/install-agent.sh | sudo bash -s http://agent.yqone.cn:4000 YOUR_AGENT_TOKEN YOUR_AGENT_ID

# Token 获取方式：
# 1. 登录 ProberX 后台 -> 服务器 -> 创建服务器
# 2. 填写服务器名称和 Agent 地址 -> 创建
# 3. 复制生成的 AGENT_TOKEN 和 AGENT_ID
# 4. 粘贴到上面的安装命令中

# 或手动下载
wget https://panel.yqone.cn/downloads/proberx-agent-linux-amd64 -O /usr/local/bin/proberx-agent
chmod +x /usr/local/bin/proberx-agent
export DASHBOARD_URL=http://agent.yqone.cn:4000
export AGENT_TOKEN=your-token
export AGENT_ID=your-agent-id
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）、文件管理器（浏览/上传/下载/编辑）。

服务器到期时间

服务器卡片右上角日历按钮（或卡片内「＋设置到期时间」）可设置到期日期，精确到天；Web/桌面端均支持
卡片显示到期徽标：灰色（剩余 >7 天）、琥珀色（≤7 天即将到期）、红色（已过期）
到期前 7 天自动生成告警并推送到已配置的通知渠道（系统规则「服务器到期提醒」，可在告警中心停用）

Shell AI 助手

在服务器详情页打开「Shell AI」，用中文描述运维意图，AI 直接生成可执行的 Shell 命令，支持一键执行与结果回显；桌面客户端内置聊天式 AI 面板，边聊边运维。

自研模型 ProberX-coder：基于 Qwen3-4B、使用 3600+ 条 Linux 运维指令数据微调，GGUF Q4_K_M 量化（约 2.3GB），默认部署在服务器本机 Ollama，零 API 费用、数据不出内网
中文 → 命令：例如「帮我看看磁盘还剩多少空间」→ df -h，「查看占用内存前 10 的进程」→ ps aux --sort=-%mem | head -11
多 Provider：支持 Ollama（OpenAI 兼容接口）、OpenAI、DeepSeek、Claude，可在服务器 AI 设置中切换；切换服务器不更换模型
三种能力：生成命令（确认后执行）、直接执行并返回输出、读取/保存 AI 配置
长任务友好：AI 生成接口超时已放大至 300 秒，复杂提问不再 504

监控探测

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

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

告警通知

支持 9 种通知渠道：

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

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

服务器到期提醒：为服务器设置到期时间后，系统自动创建「服务器到期提醒」规则（metric=server_expiry，剩余 ≤7 天触发），到期前推送一次告警到所有已启用渠道；可在告警中心停用该规则或调整通知渠道。

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

桌面客户端（Windows）

ProberX 提供原生 Windows 桌面客户端（Flutter 构建），暗色指挥中心风格，无需打开浏览器即可完成日常运维。

下载安装

# 下载安装包（绿色免安装，解压即用）
curl -L -o proberx-desktop-1.0.2.zip https://agent.yqone.cn/downloads/proberx-desktop-1.0.2.zip

# 解压到任意目录，双击 proberx_desktop.exe 运行
# 当前版本：1.0.2（更新信息：https://agent.yqone.cn/downloads/version.json）

功能

账号登录与会话保持（Token 自动刷新）
服务器列表与详情：实时遥测图表、systemd 服务管理、Shell AI 入口
服务器到期时间：卡片到期徽标 + 「设置到期」弹窗，到期前 7 天自动提醒
监控面板、告警中心（规则/事件管理）、监控任务管理
设置：API 地址、检查更新、退出登录

在线更新

客户端内置自动更新机制：

启动后自动检查新版本；设置页也可手动「检查更新」
更新包带 SHA256 校验，下载完成后校验完整性，防止篡改
校验通过后自动替换程序文件并重启，全程无需手动安装

提示：更新包为完整发布目录（exe + data + DLL）压缩，约 12MB。

系统架构

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 以 https://agent.yqone.cn/api/v1 为前缀，JWT Bearer Token 认证。

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

健康检查: GET /health — 无需认证。

完整 API 文档: 查看全部端点与调用示例 →

生产部署

国内服务器注意事项

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 文档