注册数据库采集器 — InfraGuard 手册

概述 —— 本页做什么

管理 ▸ 采集器是 InfraGuard 的 采集器注册表（infr_collector 表）。它把硬编码的凭据与主机映射从代码中提取出来，以数据的形式保存。采集器按 访问方式（access） 抽象。

access	用途	驱动的界面
`web`	远程代理端点（tlx 探测 · run_report）	基础设施 ▸ 健康状态
`database`	直接连接已注册的数据库以采集负载指标	服务 ▸ 数据库 · 基础设施 ▸ 告警
`agent`	内网代表采集器（Redis + nginx-vts）	服务 ▸ 会话 (Redis) · 服务 ▸ Web

本文介绍 access=database 采集器。InfraGuard 应用会定期连接已注册的数据库，读取 SHOW GLOBAL STATUS · information_schema.processlist · information_schema.tables，并把时间序列写入 infr_db_metric。它绝不会读取或写入你的数据行 —— 只采集负载与结构指标。

数据库采集器是数据库负载监控界面与告警的 数据来源。在这里注册一个数据库，它会自动出现在这两处。

何时使用

你希望在同一个控制台监控在线 MySQL / MariaDB 实例的 连接饱和度、吞吐量、慢查询与库表容量。
你正在把一台新的数据库服务器纳入监控。
你希望复用已经存在于 .env 中的数据库凭据，而不必重新输入密钥（cred_ref=env:PREFIX）。
你要同时管理多个数据库（共享默认值 + 条目数组）—— 请使用 分组编辑器。

界面构成

采集器列表按访问方式分组显示卡片。access=database 的记录会折叠进 一张「数据库」分组卡片（以免卡片泛滥）。分组卡片上的［编辑］会打开 分组编辑器（2 个标签页）。

分组编辑器的标签页

标签页	内容
基本（共享连接默认值）	`driver` · `port` · `database` · `username` · 积压阈值（`slow_time`） · `schedule` · `cred_ref` —— 应用于每一个数据库条目
数据库（条目数组）	每个条目的 `alias` · 显示名称 · `host`／IP · `driver`（覆盖） · 运行开关 · 密码（只写）

尽管界面上只显示一张分组卡片，保存时会把每个条目分别 upsert 为各自的 db@{alias} 记录（access=database）。采集流水线、服务 ▸ 数据库以及告警的目标定位，全都 按采集器 运作。删除某个条目会一并删除其 db@ 记录。

每个采集器的字段（`infr_collector`）

列	含义
`key`	唯一键。数据库条目为 `db@{alias}`（例如 `db@blue`）—— 不可修改（告警按键定位目标）
`title`	显示名称（默认为 `{alias} DB`）
`access`	固定为 `database`
`kind`	固定为 `metrics`
`host_alias`	该条目的 alias（主机标签）
`feeds_table`	固定为 `infr_db_metric`
`cred_ref`	凭据引用（例如 `env:STATS_DB`）—— 留空则回退到 config 加 `secret_enc`
`config`	`{driver, host, port, database, username, sample:{slow_time_sec, connect_timeout}}`（不含密钥）
`secret_enc`	数据库密码（Crypt · 只写 · 绝不返回给浏览器）
`is_run`	计划任务是否启用

使用方法

1. 注册新的数据库（分组编辑器）

进入管理 ▸ 采集器。
在「数据库」分组卡片上点击［编辑］ → 基本标签页，填写共享值。
- driver：mysql 或 mariadb
- port：默认 3306
- database：仅仅是连接时的默认库 —— 留空则连接到 information_schema（采集范围由账号的授权决定）
- username：监控账号（例如 infra_ro）
- 积压阈值（slow_time）：运行时间超过该秒数的查询计为「等待／积压」（1–60 秒，默认 2）
- cred_ref：填 env:PREFIX 可复用 .env 中的凭据
数据库 标签页 → ［添加数据库］ → 逐条填写：alias（必填） · host／IP · 可选密码。
［保存］。每个条目都会被创建／更新为一条 db@{alias} 记录。

2. 密钥的两种处理方式

（A）直接输入密码 —— 在密码框中输入后，会加密保存到 secret_enc。列表与 API 响应 绝不会暴露明文，只返回 has_secret／has_db_pw 布尔值。

密码是只写的。编辑时 把密码框留空即保留原有的值（不会覆盖）。若要显式移除，请使用清除操作。

（B）复用 .env 凭据（cred_ref=env:PREFIX） —— 不把密码保存在数据库里，而是引用 .env 中已有的一组凭据。DbCollectorService::resolveConn() 会读取这些键：

已填入 config 的值优先；留空的值则从 PREFIX_* 环境变量（host/port/database/username/password）补齐。

3. 服务器级的等待查询 —— PROCESS 权限

两项核心指标（连接饱和度 = Threads_running／Threads_connected／max_connections，以及 QPS · 慢查询速率 = ΔQuestions／ΔSlow_queries）用 普通（USAGE）账号 即可采集。但是，服务器级的等待查询汇总 与 全库容量分析 需要额外授权。

没有 PROCESS → 只能看到自己连接的进程列表（waiting_scope=0）。
拥有 PROCESS → 汇总所有会话（waiting_scope=1，服务器级）。

在每台目标数据库主机上以 root 执行一次的最小权限账号脚本：sql/infr_db_monitor_grant.sql。

-- 专用只读账号（请把来源主机收窄到 InfraGuard 应用服务器的 IP）
CREATE USER 'infra_ro'@'%' IDENTIFIED BY 'CHANGE_ME_TO_A_STRONG_SECRET';

-- 全局观测权限（不是数据访问权限）
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'infra_ro'@'%';

-- 库表容量分析（所有库 · 只读）。若只针对一个库，请收窄为 design.*
GRANT SELECT ON *.* TO 'infra_ro'@'%';

-- 影响面隔离 —— 防止连接被独占（源自 2026-08-06 [1040] 事故的教训）
ALTER USER 'infra_ro'@'%' WITH MAX_USER_CONNECTIONS 5;
FLUSH PRIVILEGES;

MariaDB 10.5+ 可以用 BINLOG MONITOR 代替 REPLICATION CLIENT。PROCESS 与 SELECT 完全相同。

4. 运行并验证采集

采集由 infr:collect-db artisan 命令执行。开发启动器（composer dev）的调度器面板每分钟调用一次。

# 立即对某一个采集器采样一次（绕过运维策略的开关）
php artisan infr:collect-db --key=db@blue --force

# 按策略采集所有已注册的数据库（is_run=1）
php artisan infr:collect-db

是否执行采集由运维策略决定。

策略键	默认值	含义
`db_collect_mode`	`economy`	`economy` = 仅当有控制台用户（presence）在线时采集 · `always` = 始终采集
`db_collect_interval_sec`	`60`	采集间隔（秒，最小 10）
`presence_window_sec`	—	最后一次操作之后仍视为「有用户在线」的时间窗口

用 --key 可以测试指定的数据库采集器。［测试］／［同步代码］按钮只针对 access=web 采集器，不适用于数据库采集器 —— 请用上面的命令验证。

5. 状态阈值

DbCollectorService::statusOf() 会对照运维策略中的阈值判定 up／degraded。

阈值键	默认值	超过时
`db_degrade_conn_pct`	`80`	连接饱和度（%）达到或超过 → degraded
`db_degrade_running`	`40`	`threads_running` 达到或超过 → degraded
`db_degrade_waiting`	`5`	等待查询数达到或超过 → degraded
`db_degrade_slow_qps`	`1`	慢查询速率（/秒）达到或超过 → degraded

数据来源

对象	表／来源	说明
采集器注册表	`infr_collector`（迁移 000201 + 000680）	`access` · `config`（JSON） · `secret_enc`（Crypt）
采集到的时间序列	`infr_db_metric`（迁移 000681）	由 `SHOW GLOBAL STATUS` 推导 · qps/slow_qps 差值
远端数据库状态	`SHOW GLOBAL STATUS` · `SHOW VARIABLES max_connections`	直接连接每个已注册的数据库
等待查询	`information_schema.processlist`	有 PROCESS 权限时为服务器级
库表容量	`information_schema.tables`	30 分钟的长缓存（规避慢查询）

不会泄漏连接。 DbCollectorService::withConn() 为每次采样创建一个运行时连接，并在 finally 中通过 DB::purge 立即关闭。PDO 超时（默认 5 秒）可避免 Web 请求／计划任务被远端延迟阻塞。切勿从调度器启动无限循环的守护进程 —— 那会耗尽共享 MySQL 的连接池（2026-08-06 的 [1040] Too many connections 事故）。

访问权限

界面访问与全部 CRUD：管理员（级别 ≥ 10） —— CollectorController::isAdmin() 会检查会话中的 infr_user_level >= 10（demo=1 与 staff=5 无法进入）。
失败时返回 403。保存、删除与 fill 都会审计记录到 infr_audit_log／日志。
fill/{key}（把配置注入清单 ▸ 工具的混合模板）属于 密钥注入例外（文档中的 §选项 B）—— 仅限管理员且有审计。

完整体系请参阅访问级别。

疑难解答与常见问题

等待查询只显示我自己的连接 —— 没有 PROCESS 权限，因此 waiting_scope=0。请用 sql/infr_db_monitor_grant.sql 授权。
库表容量只显示部分数据库 —— 需要全局 SELECT 权限（或对指定库的 SELECT）。
改了密码却没有生效 —— 编辑时密码框为空会保留原有的值。请输入新值以替换。
economy 模式下卡片短暂显示 down（红色） —— 因为没有控制台用户在线，采集有所滞后。进入界面会触发一次按需采样（ensureFresh），或切换到 always 模式（参见服务 ▸ 数据库的 false-red 规避）。
我想修改键 —— db@{alias} 键在编辑时不可修改（为了保证告警定位的稳定性）。请添加一个使用新 alias 的条目来生成新的键。
我是级别 5，却被拒绝访问 —— 有些文案写作「级别 5 以上」，但实际的门槛是 管理员（级别 ≥ 10）。