Check-CX

Check-CX 是一个用于多端点健康检查、状态聚合展示和后台配置管理的监控系统。它采用 Go + PostgreSQL + React 的单体式交付形态：后端负责定时检查、结果持久化、管理 API 和 SSE 实时推送，前端提供公开看板、分组详情页和后台管理界面；生产构建时，前端静态资源会被打包进 Go 二进制，由同一个服务统一对外提供。

项目概览

维度	说明
公开能力	首页 Dashboard 展示分组状态、全局统计、公告和历史趋势；支持按关键词、标签、时间范围筛选
下钻能力	`/group/:groupName` 分组详情页展示单组端点、历史趋势和实时状态
后台能力	分组管理、端点管理、Metadata / Request Header 模板管理、运行时设置、导入导出、手动触发检查、维护模式、清理历史
实时链路	首屏通过 REST 拉取快照，运行中通过 `/api/v1/events` SSE 接收 `check_result` 事件做增量更新
部署形态	Go 单体服务 + PostgreSQL；前端打包后 embed 到后端二进制中
配置模型	基础运行配置来自 `.env`；管理员账号、检查频率、超时、并发、后台路径、站点标题、公告等运行时配置来自数据库单例表 `app_settings`

核心能力

模块	能力说明
Dashboard	聚合展示所有分组状态、端点统计、公告和历史图表，支持搜索、标签筛选、时间范围切换和分组排序
Group Detail	展示单个分组下所有端点的状态、响应时间、Ping 和历史走势，适合问题下钻
Groups 管理	管理分组名称、标签、详情页外链、显示顺序，并支持清空单组历史
Endpoints 管理	管理端点类型、URL、模型、所属分组、维护状态、Header 模板、Metadata 模板等
Metadata 管理	维护 `request_header_groups` 与 `metadata_groups`，支持 JSON 编辑、校验、格式化
Settings	管理检查间隔、超时、并发、后台路径、站点标题、公告、全站维护、全量/单点触发检查、全站清理历史、导入导出
运维脚本	通过 `scripts/checkcx-admin.sh` 和根目录 `Makefile` 快速执行触发检查、批量维护开关、分组测试等操作

技术栈

层	技术
Backend	Go 1.24、Chi、pgx、JWT、SSE
Frontend	React 19、TypeScript、Vite、Tailwind CSS 4、Radix UI、Recharts
Database	PostgreSQL
Build / Dev	`make`、`go build`、`go test`、`npm run dev`、`npm run build`、`npm run lint`

目录结构

.
├── backend
│   ├── cmd/server                # 服务入口：加载配置、连库、迁移、启动调度器和 HTTP 服务
│   ├── internal/api              # 路由与 handlers
│   ├── internal/auth             # JWT / Cookie 会话
│   ├── internal/checker          # 各类 endpoint 检查器
│   ├── internal/config           # 环境变量配置加载
│   ├── internal/db               # SQL、迁移、数据访问层
│   ├── internal/leader           # PostgreSQL advisory lock leader election
│   ├── internal/scheduler        # 定时调度与单点触发
│   ├── internal/sse              # SSE broker
│   ├── embed.go                  # embed 前端静态资源
│   └── frontend_dist             # 前端生产构建产物复制目录
├── frontend
│   ├── src/pages                 # Dashboard、Group Detail、Admin 页面
│   ├── src/components            # 公共 UI 与后台守卫组件
│   ├── src/lib                   # API、鉴权、SSE、站点标题等客户端逻辑
│   └── vite.config.ts            # 开发代理：/api -> http://localhost:8080
├── scripts
│   └── checkcx-admin.sh          # 运维脚本
├── .env.example                  # 本地环境变量示例
├── Makefile                      # 开发、构建、运维快捷命令
└── README.md

架构摘要

后端运行流程

启动时定位 .env 并加载环境变量。
连接 PostgreSQL，自动执行内置迁移。
读取 app_settings 单例配置。
创建 SSE broker。
按 app_settings 中的检查间隔、超时和并发初始化 checker.Dispatcher 与 scheduler.Scheduler。
可选启动历史数据清理任务。
注册 /api/v1 公共接口、鉴权接口和后台接口。
若存在前端构建产物，则通过 embed + SPA fallback 统一提供 Web UI。

实时刷新模型

前端首屏先通过 REST 获取 Dashboard / Group Detail 的初始快照。
后端调度器按周期拉取所有启用端点，按并发上限执行检查。
每次检查结果都会写入 check_results，然后通过 SSE 发布 check_result。
前端收到事件后更新端点状态、统计信息和历史数据。

这条链路的目标是“最终一致的实时刷新”，不是带回放保证的消息系统。

快速开始

1. 准备依赖

依赖	说明
PostgreSQL	必需，后端启动时自动执行迁移
Go 1.24+	后端开发、测试、构建
Node.js + npm	前端开发、构建、Lint
`make`	建议使用，仓库已提供快捷命令

2. 配置环境变量

在项目根目录创建 .env：

cp .env.example .env

至少需要填写以下内容：

DB_HOST=localhost
DB_PORT=5432
DB_NAME=checkcx
DB_USER=user
DB_PASSWORD=password
DB_SSLMODE=disable

PORT=8080
JWT_SECRET=change-this-to-a-random-secret

说明：

推荐使用拆分的 DB_* 配置；如果未提供完整的 DB_HOST/DB_NAME/DB_USER，后端才会回退读取 DATABASE_URL。
.env 只负责基础运行配置，不再负责管理员账号、检查间隔、超时、并发等运行时设置。

3. 启动开发环境

分别启动后端与前端：

make dev-backend
make dev-frontend

等价命令：

cd backend && go run ./cmd/server
cd frontend && npm run dev

开发模式下：

后端默认监听 http://localhost:8080
前端 Vite 默认启动本地开发服务器
frontend/vite.config.ts 已配置 /api 代理到 http://localhost:8080

4. 首次初始化管理员

系统首次启动时，app_settings 会自动创建默认行，但管理员账号初始为空。此时：

如果你正在使用 make dev-frontend，打开前端开发地址的 /admin/login，通常是 http://localhost:5173/admin/login
如果你运行的是已打包的单体服务，打开 http://localhost:8080/admin/login
前端会先调用 /api/v1/auth/bootstrap
若返回 setup_required=true，登录页会进入“初始化管理员”模式
填写用户名与密码后，后端通过 /api/v1/auth/setup 写入 app_settings

默认后台路径是 /admin。如果后续在设置页修改了 admin_base_path，后台入口将变成新的路径，例如 /ops-center/login。

5. 生产构建与运行

完整构建：

make build

构建完成后：

前端产物会从 frontend/dist 复制到 backend/frontend_dist
Go 后端会将 backend/frontend_dist embed 进二进制
最终产物输出到 bin/check-cx

启动生产二进制：

./bin/check-cx

配置说明

一、环境变量 `.env`

以下是当前仓库里最重要的环境变量分类：

类别	变量	说明
数据库	`DB_HOST` `DB_PORT` `DB_NAME` `DB_USER` `DB_PASSWORD` `DB_SSLMODE`	推荐的 PostgreSQL 连接配置
数据库兼容项	`DATABASE_URL`	当拆分 `DB_*` 未配置完整时的回退连接串
服务端口	`PORT`	HTTP 服务监听端口，默认 `8080`
阈值	`DEGRADED_THRESHOLD_MS`	成功请求超过该阈值时标记为 `degraded`
调度主从控制	`LEADER_ELECTION_ENABLED`	是否启用 PostgreSQL advisory lock，避免多实例重复调度
历史清理	`HISTORY_RETENTION_DAYS` `HISTORY_PRUNE_INTERVAL_HOURS`	历史数据自动清理策略
鉴权	`JWT_SECRET`	管理后台 JWT 签名密钥，必填
历史缓存	`HISTORY_HTTP_CACHE_ENABLED` 及相关 `HISTORY_HTTP_CACHE_*`	历史查询接口的内存缓存配置

完整示例请查看根目录 .env.example。

二、数据库单例配置 `app_settings`

以下配置保存在数据库 app_settings 表中，支持运行时更新，保存后立即生效：

字段	作用	修改入口
`admin_username` / `admin_password_md5`	后台管理员账号	首次 Setup
`check_interval_minutes`	检查周期	Settings 页面
`check_timeout_seconds`	单次 API 检查超时	Settings 页面
`ping_timeout_seconds`	Ping 超时	Settings 页面
`check_concurrency`	调度并发上限	Settings 页面
`admin_base_path`	后台入口路径，默认 `/admin`	Settings 页面
`site_title`	站点标题	Settings 页面
`announcement_enabled` / `announcement_title` / `announcement_message`	公告开关与内容	Settings 页面

重要说明：

调度器启动时会读取 app_settings 初始化。
保存 Settings 时，后端会调用 scheduler.UpdateSettings(...) 让检查周期、超时和并发即时生效，无需重启服务。
后台路径一旦修改，前端会跳转到新的 /${adminBase}/settings。

主要接口概览

分类	路径前缀	说明
Public API	`/api/v1/*`	分组列表、分组详情、端点列表、历史数据、统计、站点标题、公告、SSE
Auth API	`/api/v1/auth/*`	启动检查、首次 Setup、登录、登出、会话校验、后台路径校验
Admin API	`/api/v1/admin/*`	Settings、Groups、Endpoints、Metadata/Header 模板、导入导出、手动触发检查、维护操作
Web UI	`/` `/group/:groupName` `/:adminBase/*`	公开看板、分组详情、动态后台页面

后台鉴权支持两种方式：

浏览器场景默认使用 HttpOnly Cookie：check_cx_auth
脚本或外部工具可使用 Authorization: Bearer <token>

数据模型概览

表	用途
`groups`	分组定义、标签、外链、显示顺序
`endpoints`	端点配置、模型、URL、维护状态、Header / Metadata 关联
`check_results`	每次检测结果、状态码、延迟、Ping、错误信息、响应体、检测时间
`request_header_groups`	可复用请求头模板
`metadata_groups`	可复用 Metadata 模板
`app_settings`	单例系统设置和管理员账号

常用命令

开发与构建

命令	说明
`make dev-backend`	启动后端开发服务
`make dev-frontend`	启动前端 Vite 开发服务器
`make build`	构建前端并打包后端二进制
`make build-frontend`	仅构建前端
`make build-backend`	构建 embed 前端后的后端二进制
`make clean`	清理 `bin/`、`frontend/dist/`、`backend/frontend_dist/`

校验

命令	说明
`cd backend && go test ./...`	后端测试
`cd frontend && npm run build`	前端生产构建校验
`cd frontend && npm run lint`	前端 ESLint 校验
`cd frontend && npm run preview`	本地预览前端生产构建

运维快捷命令

命令	说明
`make list-groups`	列出后台当前所有分组
`make check-trigger`	触发一次全量检查
`make maintenance-all-on`	打开全站维护
`make maintenance-all-off`	关闭全站维护
`make maintenance-group-on GROUP='示例分组'`	打开指定分组维护
`make maintenance-group-off GROUP='示例分组'`	关闭指定分组维护
`make group-test GROUP='示例分组'`	对指定分组执行“解除维护 -> 触发检查 -> 等待结果 -> 汇总 -> 恢复维护”的测试流程

运维脚本

根目录脚本 scripts/checkcx-admin.sh 基于后台 API 封装了常用管理动作。

使用示例：

bash scripts/checkcx-admin.sh groups
bash scripts/checkcx-admin.sh trigger
bash scripts/checkcx-admin.sh maintenance-all on
bash scripts/checkcx-admin.sh maintenance-group off "My Group"
bash scripts/checkcx-admin.sh group-test "My Group" --keep --days 7 --timeout 120

脚本说明：

默认读取根目录 .env
默认访问 http://localhost:${PORT:-8080}
使用当前 shell 环境或 .env 中的 ADMIN_USERNAME / ADMIN_PASSWORD 作为登录入参访问后台接口
这两个变量只是脚本调用后台登录 API 时使用的输入值，真正的管理员配置仍保存在数据库 app_settings 中
适合本地联调、批量运维和简单 smoke test

前端页面说明

页面	路径	说明
Dashboard	`/`	全局监控看板
Group Detail	`/group/:groupName`	单分组详情页
Admin Login	`/:adminBase/login`	管理员登录 / 首次初始化
Groups	`/:adminBase/groups`	分组管理
Endpoints	`/:adminBase/endpoints`	端点管理
Metadata	`/:adminBase/metadata`	Metadata / Request Header 模板管理
Settings	`/:adminBase/settings`	运行时设置、维护操作、导入导出

开发注意事项

事项	说明
后台路径是动态的	不要把后台入口写死成 `/admin`，应以 `app_settings.admin_base_path` 为准
运行时设置不在 `.env`	管理员账号、检查频率、超时、并发、站点标题、公告等来自 `app_settings`
生产 UI 依赖前端构建产物	只有在执行过 `make build` 或 `make build-backend` 后，后端二进制才会内置前端页面
SSE 是最终一致刷新	适合状态看板，不应当把它当成带回放的消息队列
多实例部署建议开启 leader election	这样定时调度和历史清理只会由一个实例执行

关键文件索引

文件	用途
backend/cmd/server/main.go	后端启动入口
backend/internal/api/router.go	路由定义
backend/internal/config/config.go	环境变量配置
backend/internal/db/migrations.go	初始迁移
backend/internal/db/settings.go	`app_settings` 数据访问
backend/internal/scheduler/scheduler.go	定时调度与单点触发
backend/internal/checker/checker.go	检查器分发逻辑
backend/internal/sse/broker.go	SSE fan-out
frontend/src/App.tsx	前端路由入口
frontend/src/pages/Dashboard.tsx	Dashboard 页面
frontend/src/pages/GroupDetail.tsx	分组详情页
frontend/src/pages/admin/Settings.tsx	运行时设置页
scripts/checkcx-admin.sh	运维脚本

后续可补充方向

如果要把 README 继续扩成团队级文档，建议再拆出：
- docs/api.md：详细接口契约
- docs/deploy.md：部署、反向代理、TLS、备份建议
- docs/import-export.md：导入导出数据格式与示例
- docs/operations.md：巡检、维护、故障排查流程

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Check-CX

项目概览

核心能力

技术栈

目录结构

架构摘要

后端运行流程

实时刷新模型

快速开始

1. 准备依赖

2. 配置环境变量

3. 启动开发环境

4. 首次初始化管理员

5. 生产构建与运行

配置说明

一、环境变量 `.env`

二、数据库单例配置 `app_settings`

主要接口概览

数据模型概览

常用命令

开发与构建

校验

运维快捷命令

运维脚本

前端页面说明

开发注意事项

关键文件索引

后续可补充方向

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Check-CX

项目概览

核心能力

技术栈

目录结构

架构摘要

后端运行流程

实时刷新模型

快速开始

1. 准备依赖

2. 配置环境变量

3. 启动开发环境

4. 首次初始化管理员

5. 生产构建与运行

配置说明

一、环境变量 .env

二、数据库单例配置 app_settings

主要接口概览

数据模型概览

常用命令

开发与构建

校验

运维快捷命令

运维脚本

前端页面说明

开发注意事项

关键文件索引

后续可补充方向

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

一、环境变量 `.env`

二、数据库单例配置 `app_settings`

Packages