企业官网建设流程全解析

• 运维观测
• 指标监控
• 告警

本篇文章围绕 Open-Falcon（falcon-plus）监控系统 API 模块中"查询主机关联的主机组（HostGroup）"这一核心接口展开，结合 Host/2017-01-01-host_related_hostgroup.md 文档与 API 模块源码，讲解接口的认证前提、请求方式、响应字段语义、底层数据表关系与实现原理。读完本文，你将掌握通过GET /api/v1/host/{host_id}/hostgroup获取指定主机所属主机组的完整方法，并理解 Host → HostGroup → Template 三级关联链条的查询机制。

一、接口定位与使用场景

在 falcon-plus 的运维体系中，主机组（HostGroup）是承载告警策略、模板、插件与聚合器（Aggregator）配置的核心组织单元：一台主机（Host）可以同时加入多个主机组，一个主机组也可以被多个主机使用。因此，当需要排查"某台主机的告警策略从何而来""这台机器被归入了哪些组""组内配置了哪些模板"时，首先就要查询主机与主机组的关联关系。

本文讲解的接口正是完成这一任务的入口：

• 请求方法：GET
• 接口路径：/api/v1/host/{host_id}/hostgroup
• 路径参数：host_id—— 主机在host表中的自增主键 ID（注意不是主机名 hostname）
• 功能：返回指定主机关联（绑定）的全部主机组列表
• 认证要求：需要携带有效的 Session（Apitoken）

原文档给出的实际示例路径为/api/v1/host/1647/hostgroup，即查询 ID 为 1647 的主机所绑定的主机组。

二、认证前提：Session 校验与 Apitoken

文档在接口说明的第一行即标注了Session Required。falcon-plus API 模块对/api/v1下的所有路由统一挂载了认证中间件，这一点可以直接在 路由注册源码 中确认：

func Routes(r *gin.Engine) { db = config.Con() hostr := r.Group("/api/v1") hostr.Use(utils.AuthSessionMidd) ... }

AuthSessionMidd中间件（auth_middle.go）会调用h.SessionChecking完成校验；校验逻辑位于 helper/session.go，其核心流程是：

1. 从请求头Apitoken中读取 JSON 格式的会话凭证；
2. 若配置项default_token非空且与 token 中的sig相等，则直接放行（用于服务端内部调用）；
3. 否则在 uic 库的user表与session表中校验name+sig是否匹配有效会话。

因此，调用本接口时请求头需要携带类似如下的凭证（详细说明参见 Auth Session 文档）：

Apitoken: {"name":"root","sig":"427d6803b78311e68afd0242ac130006"}

若skip_auth配置为true或未提供有效 token，请求会被中间件以401 Unauthorized中断（其他错误码可参考 response status codes 文档）。

三、请求示例与完整调用

以 curl 为例，完整调用方式如下：

# 查询 host_id = 1647 的主机所关联的所有主机组 curl -H "Apitoken: {\"name\":\"root\",\"sig\":\"427d6803b78311e68afd0242ac130006\"}" \ http://localhost:8080/api/v1/host/1647/hostgroup

其中 API 模块默认监听端口以 api.json 配置 中的port为准。请求成功时返回Status: 200，响应体为 JSON 数组：

[ { "id": 78, "grp_name": "tplB", "create_user": "userA" }, { "id": 145, "grp_name": "Owl_Default_Group", "create_user": "userA" } ]

若该主机当前未绑定任何主机组，则返回空数组[]。响应中的grp_name即主机组名称（原文档注释明确标注：grp_name: hostgroup name）。

四、响应字段语义

每个数组元素对应一个主机组记录，字段含义如下：

需要说明的是：虽然响应只暴露这三个字段，但底层grp表实际还包含create_at（创建时间戳）与come_from（来源标记）等字段；come_from字段在模型中被标记为json:"-"（见 HostGroup 模型），因此不会出现在 API 响应中。这一点体现了 falcon-plus 通过结构体 JSON tag 精确控制对外字段的习惯。

五、底层实现：两级查询与关联表

从源码看，该接口的实现并不复杂，但清晰地反映了"关联表 + 主表回查"的经典范式。路由将请求派发到控制器 GetGrpsRelatedHost（同时该文件中也保留了一个功能等价但实现略旧的GetHostBindToWhichHostGroup，两者都遵循下述查询逻辑）。

5.1 第一步：校验主机存在

控制器先解析路径参数host_id并转换为整型，随后在host表中按主键查找主机记录。若主机不存在，接口返回417 Expectation Failed；若参数缺失或非法，返回400 Bad Request。

5.2 第二步：从关联表 grp_host 取 grp_id

主机的关联信息不直接存储在host表，而是由中间表grp_host维护。该表结构（grp_host.go）只有两个字段且构成复合主键：

| grp_id | int(10) unsigned | PRI | | host_id | int(11) | PRI |

Host.RelatedGrp()（host.go）的执行逻辑如下：

func (this Host) RelatedGrp() (Grps []HostGroup) { db := con.Con() grpHost := []GrpHost{} db.Falcon.Select("grp_id").Where("host_id = ?", this.ID).Find(&grpHost) tids := []int64{} for _, t := range grpHost { tids = append(tids, t.GrpID) } Grps = []HostGroup{} db.Falcon.Where("id in (?)", tids).Find(&Grps) return }

即：先按host_id查出该主机关联的所有grp_id集合，再以id in (grp_id列表)回查grp表得到完整的主机组记录。由于grp_host表采用复合主键，同一对（grp_id, host_id）只会存在一条记录，天然避免了重复绑定。

5.3 对应的 SQL 形态

将上述 ORM 逻辑翻译为原生 SQL，大致等价于：

-- 查主机关联的主机组 ID SELECT grp_id FROM grp_host WHERE host_id = 1647; -- 回查主机组明细 SELECT id, grp_name, create_user FROM grp WHERE id IN (78, 145, ...);

这也解释了为什么响应中的create_user是主机组的创建者，而非当前请求用户：该字段直接来自grp表。

六、关联关系的建立：绑定与解绑

既然本接口用于查询"主机绑定了哪些主机组"，自然需要了解绑定关系是如何建立与解除的。API 模块在 host_routes.go 中提供了配套的写操作：

• POST /api/v1/hostgroup/host——BindHostToHostGroup：将主机加入主机组；
• PUT /api/v1/hostgroup/host——UnBindAHostToHostGroup：将主机从主机组移除；
• PATCH /api/v1/hostgroup/{host_group}/host——PatchHostGroupHost：批量调整主机组成员。

绑定操作的业务语义与请求/响应细节可参考 HostGroup 相关文档 与 hostgroup_unbind_host.md。绑定一旦完成，grp_host表中即插入对应记录，随后便可通过本文接口查询到。

七、链条延伸：从主机到模板（Host → HostGroup → Template）

本接口得到的不仅仅是主机组列表，它还是更深层查询的"第一跳"。falcon-plus 的关联链路为：主机 → 主机组 → 模板（Template）→ 策略（Strategy）。主机本身并不直接绑定模板，模板绑定在主机组上（由grp_tpl表维护，见 grp_tpl.go）。

Host.RelatedTpl()（host.go）正是沿着这条链路实现的：先调用RelatedGrp()拿到主机所属组，再经grp_tpl表取出每个组绑定的tpl_id，最后回查tpl表得到模板明细。与之对应的独立接口为：

• GET /api/v1/host/{host_id}/template—— 查询主机绑定的模板列表（见 host_related_template.md）

该接口响应示例：

[ { "id": 125, "tpl_name": "tplA", "parent_id": 0, "action_id": 99, "create_user": "root" } ]

其中parent_id表示模板的父模板（0 表示无父模板），action_id指向action表中该模板对应的告警动作配置。从 tpl.go 模型 可确认这些字段一一对应tpl表结构。因此，将两个接口配合使用，即可从任意一台主机出发，完整梳理出它所属的主机组及其生效的模板。

八、实践要点小结

1. 参数是 ID 而非主机名：host_id是host表自增主键；若只知道 hostname，可先通过GET /api/v1/hosts（主机列表接口）或按主机名查询接口换取 ID。
2. 认证必带：所有/api/v1路由均经过AuthSessionMidd，请求头必须携带Apitoken（除非skip_auth=true）。
3. 响应为纯数组：成功时 HTTP 200，body 是主机组对象数组；无绑定关系时为空数组，不属于错误。
4. 数据一致性：绑定关系由grp_host复合主键保证唯一，查询逻辑（host_controller.go + host.go）以两级查询完成，可放心用于自动化脚本、巡检任务或内部平台对接。

通过本文，你已能够独立调用 falcon-plus 查询主机与主机组的关联关系，并可顺势延伸至模板与策略链路，为监控资产的自动化梳理打下基础。相关数据库建表语句可进一步参考 2_portal-db-schema.sql，其中包含host、grp、grp_host、grp_tpl等表的完整定义。

• 运维观测
• 指标监控
• 告警