Scanopy 服务定义完全手册：轻松添加200+服务类型

Scanopy 服务定义完全手册：轻松添加200+服务类型

【免费下载链接】scanopyNetwork diagrams that update themselves项目地址: https://gitcode.com/gh_mirrors/ne/scanopy

Scanopy 是一款"能自己更新的"开源网络拓扑工具，而让它真正聪明的，正是内置的200+ 服务定义（Service Definitions）。网络扫描器跑完一遍之后，Scanopy 能自动认出你的网段里藏着 Postgres、Grafana、Home Assistant 还是 UniFi 交换机——这一切都靠一个个小巧的"服务定义"驱动。无论你是想搞懂它如何识别服务，还是想亲手添加第一个新服务，这份手册都能帮你在 10 分钟内上手。

服务定义是什么？为什么重要

一次网络扫描只会得到一堆"某 IP 的某端口开着"这样的原始信息。把原始信息变成"这是一台 Elasticsearch"，靠的就是服务定义：每份定义告诉 Scanopy 三件事：

• 它叫什么：名称、描述、图标；
• 它属于哪类：监控、数据库、媒体服务器、虚拟化……决定它在拓扑图里怎么分组；
• 怎么认出它：一组"发现模式"（端口、HTTP 端点内容、MAC 厂商等）。

定义命中之后，服务会自动挂到对应主机上，进入你看到的四种视图。下图就是扫描结果生成的工作负载视图，每一个带图标的方块都是被服务定义成功识别出来的：

内置 272 份服务定义，覆盖几乎所有场景

所有定义集中存放在 backend/src/server/services/definitions/ 目录，目前包含272 个服务定义文件，从网络基础设施到智能家居一应俱全：

完整分类可以在 mod.rs 中按章节浏览——文件本身就是最好的目录。

自动识别是怎么做到的：读懂"发现模式"

每份定义的核心是discovery_pattern()，它描述"满足什么条件就认为是这个服务"。常见模式有这几类（完整说明见 contributing.md）：

• 端点模式（Endpoint）⭐ 首选：访问某个 HTTP 路径，检查响应里是否出现服务名。信号最强、误报最少，比如 Plex 定义就是查32400端口/web/index.html里是否包含 "Plex" 字样，见 plex.rs；
• 端口模式（Port）：只认固定端口，适合没有可探测端点的服务（如 Redis 认 6379）；
• 逻辑组合（AnyOf / AllOf / Not）：多个条件"或/且/非"组合，能显著提升准确性；
• 特殊模式：IsGateway（是网关）、MacVendor（MAC 地址厂商，如 Eero）、SubnetIsType（子网类型）、None（仅手动识别）。

💡 一个实用技巧：想知道某个服务的识别逻辑，直接查 ui/static/services.json——所有 268+ 个定义都以人类可读的语言导出了发现模式，例如 Sonarr 的描述就是"响应体包含 Sonarr 字样的 8989 端口请求即命中"。

后端则通过 ServiceDefinitionRegistry 统一注册和查找这些定义，扫描时逐条比对、命中即识别。

三步添加一个新服务定义

添加服务定义是 Scanopy 官方推荐的首个贡献，不需要深入理解整个代码库。

第 1 步：新建定义文件在 definitions/ 下创建your_service.rs，核心就是实现ServiceDefinitiontrait：

fn discovery_pattern(&self) -> Pattern<'_> { Pattern::Endpoint( PortBase::HttpAlt, // 服务监听的端口 "/api/health", // 探测路径 "your_service_name" // 响应中需包含的关键词 ) }

同时声明名称、描述和所属类别。类别清单定义在 categories.rs，从Monitoring、Database到IoT、Industrial共 40 余种，选最贴近的一个即可。

第 2 步：在注册表中登记在 mod.rs 对应分类下加一行pub mod your_service;，文件末尾加上inventory::submit!注册宏——服务即可被自动发现，无需改动任何扫描器代码。

第 3 步：本地验证用make dev-server启动后端确认编译通过；如果网络里真实运行着该服务，跑一次发现扫描，确认它被正确识别、图标正常显示，然后按 contributing.md 的 PR 模板提交（一次 PR 只加一个服务）。

写在最后

服务定义看似只是"认名字"，却是 Scanopy 从"端口扫描工具"进化为"活的网络文档"的关键——272 份定义覆盖了从工业 PLC 到智能音箱的广阔世界，而它依然欢迎社区补充：每添加一个定义，所有用户的下一次扫描都会变得更聪明一点。📈

如果你的网段里总有一台设备显示为"未知服务"，去 contributing.md 看看，为它写一份定义，就是最简单的开源参与方式。

【免费下载链接】scanopyNetwork diagrams that update themselves项目地址: https://gitcode.com/gh_mirrors/ne/scanopy