服务模式自动发现指南
这是一个管理员界面，用于展示从网络/数据库连接遥测数据(netstat、数据库连接)中实际观察到的应用程序和进程，并可一键将其启用或禁用为 Normal Service 模式。
📋 概述
服务模式自动发现(Auto-Discovery) 页面汇总了 giipAgent 采集的网络连接(netstat)和数据库连接(db_connections)遥测数据中实际观察到的程序/进程名称。它会标示每一项是否已在 Normal Service Patterns 页面中注册，未注册的项目可一键添加为模式。在此页面启用的模式将用于在 Network Topology(sql3d)页面中把匹配的客户端显示为青色(天蓝色)。
⚠️ 此页面仅限管理员使用。 访问需要
uLevel >= 50(代码中硬编码的 prop 模式值)。低于该等级的用户会被重定向到首页。
🔍 页面结构
1. 顶部标题栏
- 页面标题: "✨ Auto-Discovery: Service Patterns"。
- 说明文字: 发现的应用程序来自基础设施中实际的网络/数据库连接，点击 Enable 即可将其添加为 Normal Service 模式。
2. 命令栏
| 元素 | 说明 |
|---|---|
| 🔄 Refresh 按钮 | 从服务器重新加载发现列表。 |
| 搜索框 | 按 pattern_value(应用程序/进程名称)实时筛选列表。 |
| 📋 Manage Patterns 按钮 | 跳转到 /admin/service-patterns 页面直接管理已注册模式。 |
3. 发现列表表格
| 列 | 说明 |
|---|---|
| Application/Process | 观察到的程序名(program)或进程名(process) |
| Type | program(来自数据库连接)或 process(来自 netstat)标签 |
| Seen Count | 观察到的次数(occurrence_count) |
| Status | ✅ Pattern(已注册)或 Not enabled(未注册) |
| Action | 未注册显示 Enable，已注册显示 Disable 按钮 |
表格底部显示发现总数以及其中已启用(已注册)的数量。
🛠️ 如何启用/禁用模式
- 在列表中找到目标应用程序/进程(可用搜索框缩小范围)。
- 若显示 未注册(Not enabled)，点击 Enable — 会立即将其添加为当前项目(csn)范围内的 Normal Service 模式。
- 若显示 已注册(✅ Pattern)，点击 Disable — 将该模式停用(软删除)。
- 请求处理期间，所有 Enable/Disable 按钮会暂时禁用；完成后顶部会显示成功消息，列表会自动刷新。
- 条件: Disable 仅适用于从此页面注册的(同一 csn 拥有的)模式。全局模式(csn=0)或其他项目拥有的模式需遵循 Manage Patterns 页面的权限规则。
💡 说明
- 发现数据优先使用最近 30 分钟内采集的
tKVS(netstat/db_connections)记录。如果该时间段内完全没有采集到数据(例如新项目、未安装代理、测试环境)，页面会不限时间地改为显示最近 50 条记录作为回退。 - 列表会排除
unknown、System、Idle等无意义的值。 - 发现列表仅汇总属于目标 csn 的服务器(
tLSvr.CSn)的数据。服务器必须安装 giipAgent 并发送 netstat/数据库连接遥测数据，其进程才会出现在此列表中。 - Enable/Disable 通过 giipfaw(Azure Function)→ SQL Server 立即生效，操作完成后列表会自动刷新。
API 参考
此页面通过三个派发命令(经由 fetchAzureCommand)与后端通信。由于没有单独的 API 指南，核心内容记录如下。
| 命令 | 用途 | 主要参数 |
|---|---|---|
Net3dServicePatternDiscovery | 列出从 tKVS netstat/db_connections 发现的程序/进程(含注册状态) | csn |
Net3dServicePatternPut | 将发现的项目注册为 Normal Service 模式(启用) | csn、nspId(新建为 0)、pattern_type、pattern_value、display_name |
Net3dServicePatternDelete | 停用已注册模式(软删除) | csn、nspId |
- 三个命令都可能在响应中包含
RstVal状态字段。RstVal = 200表示成功，RstVal = 401表示鉴权失败(会话过期)，RstVal = 403表示对该项目无权限。 Net3dServicePatternDiscovery成功时返回包含pattern_value、pattern_type、occurrence_count、is_registered、nspId字段的行数组。当结果恰好只有一行时，由于后端(PowerShellConvertTo-Json)的特性，可能返回单个对象而非数组——客户端会对此进行归一化处理。
故障排查
| 症状 | 原因 | 解决方法 |
|---|---|---|
| 访问后立即被重定向到首页 | uLevel 低于 50 | 请使用管理员账号(等级 50+)登录。 |
| "Unexpected token '<' ... is not valid JSON" 错误 | (2026-08-07 之前)前端调用了一个从未存在过的 Next.js API 路由(/api/service-patterns/discovery)——已在 giip-issue #938 中修复为直接调用 fetchAzureCommand | 当前部署不应再出现此问题。若仍出现，请确认部署版本是否为最新。 |
| "Unauthorized" 错误消息 | 会话令牌过期或缺失 | 请重新登录后点击 Refresh。 |
| "No applications discovered yet." | 目标项目(csn)所属服务器近期没有 netstat/数据库连接遥测数据 | 请确认服务器已安装并运行 giipAgent，采集到数据后重试。 |
| 没有出现新项目 | 最近 30 分钟内无数据，正在回退显示最近 50 条记录 | 属正常行为。一旦最近 30 分钟内积累了数据，页面会切换到该范围。 |
| 顶部指南按钮(📖)不显示 | 指南映射缺失(旧版本部署) | 该指南部署并建立索引后即会显示。 |
版本: 1.0
最后更新: 2026-08-07
源文件: giipv3/public/help/service-patterns-discovery.zh-CN.md