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://proberx.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://proberx.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。在管理后台"服务器"页面可以看到它。

Windows 服务器

Windows 版 Agent 由 PowerShell 脚本安装，注册为 ProberXAgent 系统服务（无需 NSSM / WinSW，停止服务即干净退出）。

# 管理员 PowerShell
& ([scriptblock]::Create((irm https://proberx.cn/install-agent.ps1))) `
    -DashboardUrl "http://agent.yqone.cn:4000" -Token "YOUR_AGENT_TOKEN" -AgentId "YOUR_AGENT_ID"

也可以手动下载二进制：https://proberx.cn/downloads/proberx-agent-windows-amd64.exe（同目录 .sha256 可校验）。

提示：脚本会写入服务级环境变量（而非机器级），因此改配置后无需重启系统，重启服务即生效。

环境变量

变量	默认值	说明
`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 天自动生成告警并推送到已配置的通知渠道（系统规则「服务器到期提醒」，可在告警中心停用）

资源总览

服务器详情页新增「资源总览」Tab —— 由 ProberX Agent 原生只读直采，不依赖宝塔等任何控制面板。只要服务器装有 Agent 即可获得完整的资源视图。

一次采集 8 组数据，每组独立成功/失败（ok / data / error），单组异常不会拖垮整份概览：系统 / 站点 / 证书 / 数据库 / 计划任务 / 运行服务 / 安全基线 / 实时网络
系统：操作系统、内核、主机名、CPU/内存/磁盘用量、运行时长
站点：Nginx 等 Web 虚拟主机列表（名称 / 根目录 / 启用状态）
证书：已部署 SSL 证书（域名 SAN、颁发者、到期时间、剩余天数），自动标记已过期 / 即将到期
数据库：常见数据库实例与库表（引擎、占用大小）
计划任务：Cron 任务列表（名称 / 调度表达式 / 启用 / 运行状态）
运行服务：systemd 服务总数 / 运行 / 失败，快速定位异常服务
安全基线：SSH 登录审计 + fail2ban 综合评分（0-100）与风险项计数
实时网络：上下行速率与累计流量、1 / 5 / 15 分钟负载

入口：服务器详情页 → 「资源总览」Tab。所有数据均来自 Agent 只读接口与内置只读命令，不执行任何写操作，安全可审计。

面板接入（可选）

已在用宝塔（BT）/ aaPanel 的服务器，可将面板 API 绑定为 ProberX 的补充数据源，读取面板侧才有的站点、证书、数据库、FTP、计划任务等详情；不依赖面板也能用资源总览，两者互不影响。

绑定入口：服务器详情 → 设置 → 面板接入，填写面板地址与 API 密钥，支持「先测试后保存」
支持适配器：bt（宝塔）、aapanel（aaPanel）
密钥加密存储，接口与页面只返回 apiKeyConfigured 与脱敏后缀，不回显明文
绑定后可拉取归一化概览：系统 / 站点 / 证书 / 数据库 / FTP / 计划任务 / 安全扫描 / 实时网络
支持随时测试连接、启用 / 停用或删除绑定；面板地址或密钥变动只影响该绑定

安全提示：绑定需要面板开放 API 权限。生产环境请开启面板 API 白名单，仅允许 Dashboard / Agent 所在出口 IP 访问，避免面板密钥与接口暴露在公网。

虚拟化与云接入

不装 Agent，直接把虚拟化 / 云平台的 API 接成数据源：平台上有什么虚拟机、开没开机，ProberX 直接问平台要。绑定是工作区级的——一台 vCenter 或一个云地域管着大量虚拟机，不隶属于任何一台服务器。

支持的数据源

平台	认证方式	能力
vCenter 7.0+	账号密码	清单 / 电源状态 / 电源操作 / 纳管
独立 ESXi	账号密码（SOAP vim25）	清单 / 电源状态 / 电源操作 / 纳管
Proxmox VE	API Token（建议 `PVEAuditor` 只读角色）	清单 / 电源状态（只读）
阿里云 ECS	AccessKey（RAM 只读子账号 + 地域）	清单 / 电源状态（只读）
腾讯云 CVM	SecretId / SecretKey（CAM 只读子用户 + 地域）	清单 / 电源状态（只读）

添加绑定

进入「虚拟化平台」页，点「新建绑定」；
选平台类型，填地址、账号、密码（公有云还要填地域 region，如 cn-hangzhou / ap-guangzhou）；
先点「测试连接」——成功会显示「N 台实例可见」，确认后再保存；
保存后「拉取清单」，查看虚拟机 / 宿主机与电源状态。

最小权限建议：vCenter 用内置 Read-only 角色；Proxmox 用 PVEAuditor；阿里云 RAM 只给 ecs:Describe*；腾讯云 CAM 只给 cvm:DescribeInstances / cvm:DescribeInstancesStatus。凭据不下发到前端（接口只返回是否配置与尾四位提示）。

电源操作与审计

默认只读：能力表里五个电源动作全部关闭，接口也会兜底拒绝。打开绑定的「允许电源操作」后，vCenter 与独立 ESXi 可执行开机 / 优雅关机 / 强制断电 / 重启 / 挂起；每次动作要在弹窗里输入虚拟机名二次确认，执行结果与审计一起落库（操作者、时间、期望状态、实际观测状态）。Proxmox 与公有云当前为只读接入，尚未实现写操作。

混合纳管

平台上的虚拟机可以「纳管到服务器」：出现在服务器列表里，在线状态跟随平台电源状态。这台机器后续装上 Agent 后会自动升格为完整纳管——监控、终端、文件、防火墙等全部能力解锁；已升格的记录不能直接取消纳管。

AI 智能体

侧边栏「AI 智能体」以对话形式编排全部 AI 能力：输入自然语言后，系统按意图自动路由到通用助手 / AI 巡检 / 自主排查 / AI 终端 / AI 运维周报 / 自定义工作流 / 13 个专项诊断助手，无需手动切换；每一步思考、工具与 MCP 调用实时可视化，可随时叫停与接管。

通用助手：日常问答与运维知识；自动判断是否需要巡检、故障排查或执行命令，并直接执行，不再只是「建议你切换」
AI 巡检：采集 CPU / 内存 / 磁盘 / 负载 / 进程 / 服务等健康指标，生成健康评分、图文报告并支持推送告警
自主排查：围绕故障目标多步只读取证 → 时间线 → 根因 / 置信度 → 修复建议；支持复检（恢复确认）、白名单修复执行与审计留痕
AI 终端：自然语言 → 安全 Shell 命令，只读优先，危险操作先说明风险再执行
AI 运维周报：按自然语言汇总最近 7 天（天数可调）的巡检 / 排查 / 修复记录，生成中文周报，可导出 Markdown / Word
13 个专项诊断助手：网站 / 数据库(MySQL) / 流量 / 安全 / 后门扫描 / 服务器 / 计划任务 / 文件 / FTP / SSL / 日志 / DNS / 性能，各配专项提示词与只读工具子集，输入「网站打不开」「慢查询」「证书过期」等关键词即自动命中
自定义工作流：可视化编排内置工具 / Shell / MCP 三类步骤，保存后对任意目标服务器一键运行，实时查看每步进度
记忆检索：对话自动触发向量记忆召回，沉淀历史排查结论与关键上下文，跨会话越用越懂你的环境
报告导出：巡检 / 排查报告支持 PDF、DOCX、Markdown、HTML 导出，便于归档、汇报或提交比赛材料

AI 接口配置：工作区设置 → AI 设置，可配置 Provider（Ollama / OpenAI / DeepSeek / Claude 等）、API URL、Model、API Key，并支持连通性测试。Shell AI、AI 智能体、巡检、周报统一复用该配置；模型切换后无需在每台服务器重复设置。

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	证书过期时间、链验证

告警通知

支持 8 种通知渠道：

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。

监控大屏

访问 /wall 进入 kiosk 式监控大屏：没有侧边栏，整屏铺开所有服务器的在线状态、CPU / 内存 / 磁盘与实时告警流。

数据来自 WebSocket 实时通道 + 6 秒自刷新：离线 / 恢复、阈值告警即时上屏；
右上角一键全屏，适合长期挂在值班室 / 机房的屏幕上；
同时显示虚拟化纳管状态（哪些虚拟机由平台纳管、是否已装 Agent）；
使用当前登录会话的数据，与后台同一套权限，不对外公开任何数据——需要对外公开请用「公开状态页」。

ProberXOS 桌面（Web 工作台）

访问 /desktop 进入 ProberXOS：浏览器里的桌面系统，适合把运维工作收进一个沉浸式工作台。

选择服务器开机屏：选一台服务器进入桌面（选择结果存在本机会话，不怕刷新）；
窗口与开始菜单：应用以可拖拽窗口打开，支持任务栏、开始菜单搜索与桌面右键菜单；
应用嵌入：已部署的应用（Docker、文件管理、终端、虚拟化等）直接嵌在桌面窗口里打开，也可一键开新标签页；
三种退出语义：退出服务器 = 断开当前服务器回选择屏（窗口保留）；关机并退出 = 关闭 ProberXOS 回到面板；退出登录 = 回登录页。三者都不会向服务器发送任何电源指令。

系统架构

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 认证。

共 190+ 端点，覆盖认证、工作空间、服务器、监控、告警、通知、Cron、API Key、状态页、AI 智能体（对话 / 巡检 / 自主排查 / 周报 / 工作流）、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 文档