基于 Go 重构的 ServerStatus 实现, 包含:

• 服务端: TCP 采集 + Gin HTTP 接口
• Web 前端: 完整复用原 ServerStatus web 目录内容
• 客户端 Agent: Golang 编写, 兼容 username:password + update {json} 协议

• Go 1.24+

• cmd/server/main.go: 程序入口
• cmd/agent/main.go: 客户端 Agent 入口
• config/servers.json: 节点与鉴权配置
• config/monitors.json: 监测项配置
• config/sslcerts.json: SSL 证书探测配置
• config/watchdogs.json: 告警规则配置
• internal/collector: TCP 采集
• internal/httpapi: Gin 路由
• internal/store: 状态存储
• internal/agent: Go Agent 实现
• internal/runtimecheck: watchdog 规则执行与 SSL 主动探测
• web: 原项目前端静态资源

在项目根目录执行:

go run ./cmd/server -config-dir config -http :8080 -collector :35601 -web-dir web
go run ./cmd/server -version

参数说明:

• -config-dir: 配置目录路径, 程序会自动读取目录下的 servers.json / monitors.json / sslcerts.json / watchdogs.json / channels.json / alert_templates.json / admin_users.json
• -data-dir: 数据目录路径, 程序会自动使用目录下的 stats.json 做状态持久化
• -http: HTTP 服务监听地址
• -collector: TCP 采集端口 (客户端连接端口)
• -web-dir: 前端静态资源目录
• -stats-interval: stats.json 落盘间隔秒(0=每次数据变更都落盘)
• -version: 输出 Version/Commit/BuildTime 并退出

/json/stats.json 始终为动态接口返回. 服务端同时会把同结构快照持久化到 -data-dir/stats.json, 用于重启后状态连续:

go run ./cmd/server -config-dir config -data-dir data -web-dir web -stats-interval 1

行为说明:

• 服务启动时会尝试从 -data-dir/stats.json 读取并恢复状态(如 last_network_in/last_network_out).
• -stats-interval=0 表示每次状态变更都会立即落盘; 大于 0 则在发生变更后按该间隔批量落盘.
• 程序退出时会额外落盘一次.
• 落盘文件内容与 /json/stats.json 返回 JSON 保持一致.
• 落盘采用临时文件 目标路径~ 写入并替换的方式尽量保证原子性(Windows 下会使用 .bak 过渡文件).

• API 与协议文档: docs/api.md
• 管理接口文档: docs/api_admin.md
• 拆分后的配置说明(用户): docs/split_config_usage.md
• 拆分后的设计说明(开发者): docs/split_config_design.md
• watchdog 配置说明: docs/watchdogs_config.md
• watchdog 开发说明: docs/watchdogs_design.md

当前版本已将主配置拆分为多个文件:

• config/servers.json: 节点账号列表 (username/password 用于客户端鉴权)
• config/monitors.json: 下发给客户端/Agent 的监测项
• config/sslcerts.json: 证书探测配置
• watchdogs.json: 独立告警规则配置
• 告警通道配置文件: config/channels.json
• 告警模板配置文件: config/alert_templates.json

这三个拆分文件现在与 channels.json 保持一致, 都使用"顶层对象 + 固定键名挂载列表"的写法:

• servers.json -> { "servers": [...] }
• monitors.json -> { "monitors": [...] }
• sslcerts.json -> { "sslcerts": [...] }

servers.json 关键字段:

• username: 客户端登录用户名
• password: 客户端登录密码
• name/type/host/location: 页面展示信息
• monthstart: 月流量重置基准日 (超过 28 自动按 1 处理)
• disabled: 为 true 时不启用该节点

monitors.json 关键字段:

• name: 监测名称
• host: 监测目标
• interval: 探测周期秒数
• type: 协议类型

sslcerts.json 关键字段:

• id: 证书唯一标识, 供规则指纹和状态恢复使用
• name: 展示名称
• domain: 证书探测目标 (支持 https://domain/path 形式)
• port: TLS 端口
• interval: 主动探测周期 (秒)

watchdogs.json 关键字段:

• defaults.pending_sec: 规则默认持续命中秒数
• defaults.cooldown_sec: 规则默认冷却秒数
• rules[].id: 规则唯一标识
• rules[].scope: 规则作用域, 支持 node / ssl
• rules[].expr: 表达式规则, 仅支持标准写法 &&, ||, ==, !=, >, <, >=, <=

watchdog 表达式语法说明:

• node / ssl 规则都必须使用标准布尔表达式
• 必须写 ==, 不能写单个 =
• 必须写 && / ||, 不能写单个 & / |
• 这是破坏性更新, 旧写法不会再被自动转换
• rules[].channels: 通道 ID 列表
• rules[].template: 模板 key
• rules[].severity: 告警级别, 支持 warning / error / critical

channels.json 关键字段:

• id: 通道唯一标识, 供 watchdogs.json -> rules[].channels 引用
• type: 通道类型, 支持 webhook / wecom_group_bot / telegram / gotify
• webhook: 使用 url, URL 规则为 url + url.QueryEscape(message), 表单字段包含 signature
• wecom_group_bot: 使用 webhook_url (或回退到 url), 请求体为企业微信群聊机器人 text 消息
• telegram: 使用 bot_token + chat_id, 发送到 sendMessage
• gotify: 使用 server_url + token (+ 可选 priority), 发送到 /message

alert_templates.json 关键字段:

• templates.watchdog: watchdog 告警模板
• templates.ssl_mismatch: SSL 域名不匹配告警模板
• templates.ssl_expiry: SSL 过期提醒告警模板

服务端启动后会自动监测 -config-dir 指向目录内的配置文件变化, 默认每 2 秒检查一次文件的修改时间与大小:

• 检测到配置变更后, 自动重新加载配置并应用到运行时
• 检测到 watchdog 规则文件变更后, 自动重新编译规则
• 检测到 channels.json 变化后, 自动热重载告警通道
• 检测到 alert_templates.json 变化后, 自动热重载告警模板
• 前端会在后续短时间内收到 reload=true 并自动刷新页面

当前热重载覆盖范围:

• servers: 节点列表, 节点展示信息, 账号密码, disabled 状态
• monitors: 下发给客户端/Agent 的监测项
• watchdogs.json: 告警规则, 冷却, 模板, 通道
• sslcerts: 证书探测目标, 周期
• channels.json: 告警通道映射

不属于热重载范围(需重启服务生效):

• 服务端启动参数, 如 -http, -collector, -web-dir, -data-dir, -stats-interval

服务端 TCP 采集端口默认启用基础防护策略:

• 鉴权读取超时: 连接建立后 5 秒内未提交 username:password, 返回 authentication timeout: credentials were not provided in time 并断开
• 空闲会话超时: 登录后连续 15 秒未收到数据, 返回 session timeout: no data received within 15 seconds 并断开
• 凭据格式错误: 返回 authentication failed: malformed credentials, expected username:password, 并对来源 IP 施加 30 秒短时封禁
• 凭据连续失败封禁: 60 秒窗口内同一 IP 认证失败达到 5 次, 返回 authentication failed: too many attempts, retry after <seconds> seconds, 并封禁 60 秒
• 已封禁来源拒绝连接: 返回 connection rejected: too many failed authentication attempts, retry after <seconds> seconds

常见错误响应:

• 用户名或密码错误: authentication failed: invalid username or password
• 同一用户重复连接: authentication failed: only one active connection is allowed per user
• 上报 JSON 非法: bad request: invalid update payload
• 未鉴权连接上报: not authenticated: reconnect and login again

TCP update {json} 回包兼容策略:

• 原版协议约定 update 回包为 0/1 (0=成功, 1=失败)
• 当前 Go 服务端可能返回 0/1 或文本错误信息, 项目内 Python 客户端已兼容两种回包并在每次 update 后主动消费回包
• 建议自定义客户端按 0/1 协议进行兼容实现, 并将详细失败原因写入服务端日志用于排障

启动命令:

go run ./cmd/agent -transport tcp -server 127.0.0.1 -port 35601 -user s01 -password USER_DEFAULT_PASSWORD -interval 1

HTTP 模式:

go run ./cmd/agent -transport http -http-url http://127.0.0.1:8080 -user s01 -password USER_DEFAULT_PASSWORD -interval 1

查看版本:

go run ./cmd/agent -version

默认行为:

• -transport 默认 tcp, 仅当显式传 http 才启用 HTTP 模式
• -server 默认 127.0.0.1, -port 默认 35601
• -http-url 默认 http://127.0.0.1:8080/collector/v1/update, 且支持只填写基础地址(如 http://127.0.0.1:8080), 会自动补齐为 /collector/v1/update
• -user 为空时默认 s01
• -password 默认 USER_DEFAULT_PASSWORD
• -interval 小于等于 0 时会重置为 1 秒
• -probe-port 默认 80, -probe-protocol-prefer 默认 ipv4
• -cu/-ct/-cm 默认 cu.tz.cloudcpp.com / ct.tz.cloudcpp.com / cm.tz.cloudcpp.com
• Agent 会输出关键错误日志(如 TCP 鉴权失败, 会话超时, HTTP 上报被拒绝), 便于定位服务端返回的错误原因

参数说明:

• -server: 服务端地址
• -port: 服务端采集端口
• -transport: 通信方式 (tcp 或 http)
• -http-url: HTTP 采集地址 (HTTP 模式使用)
• -version: 输出 Version/Commit/BuildTime 并退出
• -user: 节点用户名
• -password: 节点密码
• -interval: 上报间隔 (秒)
• -probe-port: 连通性探测端口
• -probe-protocol-prefer: 探测协议偏好 (ipv4/ipv6)
• -cu, -ct, -cm: 三网探测域名

项目提供了 Linux/Windows 的 Agent 一键安装脚本:

• Linux: scripts/install-agent.sh
• Windows: scripts/install-agent.ps1

Linux 使用方式:

sudo ./scripts/install-agent.sh install
sudo ./scripts/install-agent.sh install -transport tcp -server 127.0.0.1 -port 35601 -user s01 -password USER_DEFAULT_PASSWORD -interval 1
sudo ./scripts/install-agent.sh update
sudo ./scripts/install-agent.sh rollback

Windows 使用方式(管理员 PowerShell):

PowerShell -ExecutionPolicy Bypass -File .\scripts\install-agent.ps1 install
PowerShell -ExecutionPolicy Bypass -File .\scripts\install-agent.ps1 install -transport http -http-url https://your-host:8080 -user s01 -password USER_DEFAULT_PASSWORD -interval 1
PowerShell -ExecutionPolicy Bypass -File .\scripts\install-agent.ps1 update
PowerShell -ExecutionPolicy Bypass -File .\scripts\install-agent.ps1 rollback

说明:

• 子命令固定为 install | update | rollback, 不带子命令会显示帮助
• install 不带参数时进入交互式配置, 带参数时按传入参数安装
• update 流程为: 先下载更新文件 -> 停止服务/任务 -> 覆盖二进制 -> 启动服务/任务
• rollback 流程为: 停止服务/任务 -> 用备份二进制恢复 -> 启动服务/任务
• update/rollback 不接受额外参数
• Linux 默认备份路径: /usr/local/bin/serverstatusgo-agent.bak (可用 SERVERSTATUSGO_AGENT_BACKUP_PATH 覆盖)
• Windows 默认备份路径: C:\ProgramData\ServerStatusGo\agent.exe.bak (可用 SERVERSTATUSGO_AGENT_BACKUP_EXE_PATH 覆盖)
• Linux 脚本通过 systemd 管理自启动 (非 systemd 环境会提示手动启动命令)
• Windows 脚本通过计划任务创建开机自启动任务
• 两个脚本都支持通过环境变量覆盖二进制下载地址与安装路径

开发者约定:

• 保持两个脚本子命令语义一致: install 写入配置并安装, update 仅更新二进制, rollback 仅恢复二进制
• update 应遵循先下载再停服替换启动, rollback 遵循停服后替换再启动, 以缩短更新停机时间
• 如扩展参数, 需同时更新脚本内 Show-Usage/usage 和本节文档, 保持运维入口一致

仍可直接使用本项目自带的 Python 客户端脚本 (clients/client-linux.py, clients/client-psutil.py), 只需确保:

• SERVER 指向当前 Go 服务地址
• PORT 指向 -collector 端口 (默认 35601)
• USER/PASSWORD 与 servers.json 中一致

[Warning] 从 v0.1.2-rc.1 开始, 本仓库内 Python 客户端脚本相对原版脚本已做兼容性改造, 请注意:

• update {json} 发送后会主动读取并消费服务端回包, 避免回包堆积导致连接异常
• 已兼容 update 回包为 0/1 与文本错误两种模式, 其中 0 表示成功, 1 表示失败
• 当收到文本错误回包时, 客户端会输出服务端消息, 便于快速定位问题
• custom 监测项输出顺序改为按 key 稳定排序, 减少同一监测项在不同运行周期中的顺序抖动

如你需要与历史环境保持完全一致行为, 请固定使用对应历史版本脚本并评估上述差异影响.

协议细节与兼容点请参考 docs/api.md.

• watchdog: 服务端后台持续评估 config/watchdogs.json 中的规则
• node 规则: 固定每 2 秒评估一次, 命中后受 pending_sec 与 cooldown_sec 控制
• SSL 证书: 服务端按 sslcerts.interval 主动探测证书
• SSL 规则: 每次证书探测完成后根据 scope=ssl 规则评估, 域名不匹配与到期提醒都通过规则配置实现
• api/stats / json/stats.json 中 sslcerts 字段会动态输出 expire_ts, expire_days, mismatch, error, error_code

• 从当前版本开始, watchdog 规则只接受标准表达式语法
• 旧写法示例:
  • online4=0&online6=0
  • cpu>90&load_1>5
• 新写法示例:
  • online4 == 0 && online6 == 0
  • cpu > 90 && load_1 > 5
• 若仍使用旧写法, 服务启动或热重载时会直接报规则解析错误

• signature 取值:
  • watchdog: ServerStatus
  • SSL: ServerStatusSSL
• signature 仅用于来源分类, 不属于密码学签名
• 各通道发送协议:
  • webhook: POST + application/x-www-form-urlencoded, URL=target + url.QueryEscape(message), body=signature=<来源标识>
  • wecom_group_bot: POST + application/json, body={"msgtype":"text","text":{"content":"[signature] message"}}
  • telegram: POST + application/json, body 含 chat_id / text / disable_web_page_preview
  • gotify: POST + application/json, Header X-Gotify-Key, body 含 title / message / priority

• GET /api/alerts/health: 告警分发健康概览 (status / total / success / failed / failure_recent)
• GET /api/alerts/stats: 告警分发累计统计, 包含 by_source 与 by_channel_type 维度
• GET /api/alerts/recent?limit=20: 最近告警分发记录 (默认 20 条, 倒序返回)

字段说明:

• status: ok / degraded / down / disabled
• by_source: 按事件来源聚合, 当前主要为 watchdog / ssl
• by_channel_type: 按通道类型聚合, 如 webhook / wecom_group_bot / telegram / gotify
• mode: channel(按通道 ID 路由) 或 legacy_webhook(兼容旧目标直连模式, 新规则配置不再使用)

go build -mod=mod ./...
go test -mod=mod ./...
go vet -mod=mod ./...

PowerShell 执行策略限制

在 Windows 环境中如遇到PowerShell脚本无法执行(提示因为在此系统上禁止运行脚本), 可对当前 PowerShell 进程临时放宽执行策略:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

中国大陆网络环境依赖拉取超时

在中国大陆网络环境中如遇到依赖拉取较慢或超时, 可配置模块代理:

go env -w GO111MODULE=on
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct

服务端内置了一套管理接口, 支持通过 Web 页面或 API 对配置文件进行增删改操作.

管理员账号由 config/admin_users.json 管理, 文件结构如下:

{
  "enabled": true,
  "admins": [
    { "username": "admin", "password": "YOUR_PASSWORD" }
  ]
}

• enabled: 总开关, 设为 false 时所有管理接口均返回 503 错误
• admins: 管理员列表, 支持多个账号
• 登录成功后生成 32 字节随机 token (十六进制编码) , 存入内存, 不持久化 (重启服务后需重新登录)
• admin_users.json 支持热重载, 修改 enabled 或账号密码无需重启即可生效

登录接口:

POST /api/admin/login
Content-Type: application/json

{ "username": "admin", "password": "YOUR_PASSWORD" }

成功响应:

{ "code": 0, "msg": "login success", "data": { "token": "<hex-token>" } }

后续所有管理接口均需携带 X-Admin-Token: <token> 请求头.

所有接口均支持 GET (查询) 和 PUT (更新) , 返回格式为 {"code":0,"msg":"...","data":{...}} (code=0 表示成功) .

接口	说明
GET /api/admin/config/all	获取所有配置及版本号
GET/PUT /api/admin/config/servers	节点管理
GET/PUT /api/admin/config/monitors	监测项管理
GET/PUT /api/admin/config/sslcerts	SSL 证书探测管理
GET/PUT /api/admin/config/watchdogs	告警规则管理
GET/PUT /api/admin/config/channels	告警通道管理
GET/PUT /api/admin/config/alert-templates	告警模板管理

版本号说明: 返回数据中包含 version 字段, 格式为 mtime:size. servers / monitors / sslcerts / watchdogs / channels / templates 现在分别维护独立版本号, 更新时需传递当前域的版本号, 若版本号不匹配则返回 409 冲突错误, 防止并发写覆盖.

访问地址: /web-admin/admin.html

功能特性:

• 双模式编辑: 字段表单模式 (新手友好) 和 JSON 模式 (适合高级用户) , 可通过页面顶部按钮切换
• 字段表单模式下支持新增, 删除, 编辑各项配置
• 左侧边栏可切换配置域 (节点/监测项/证书/规则/通道/模板)
• 保存时会根据当前模式自动收集数据并提交至对应 API
• 认证状态保存在浏览器 localStorage, 刷新页面不会丢失登录状态

• GET 接口返回的原始密码字段为明文 (如需增强安全, 可在存储层或前端做脱敏处理)
• Token 仅存在于服务端内存中, 服务重启后自动失效

• config/admin_users.json: 管理员账号配置
• internal/adminauth/service.go: 认证服务实现
• internal/adminconfig/service.go: 配置管理服务实现
• internal/httpapi/router.go: 管理接口路由注册
• web/web-admin/: Web 管理后台静态资源
• docs/api_admin.md: 管理接口详细 API 文档