『DevOps运维』从零搭建企业微信告警机器人：接口对接、消息模板与自动化通知-171主机测评

📣读完这篇文章里你能收获到

📁 掌握企业微信群机器人的完整创建与配置流程

🐍 学会使用 curl 调用 Webhook 发送多种类型的告警消息

🌐 精通 Markdown 消息格式，实现彩色字体、@成员等高级功能

🖥️ 获得可直接落地的告警通知模板和最佳实践

🔧 了解文件发送、模板卡片等进阶用法

前言

在运维和开发工作中，及时获取系统告警是保障服务稳定性的关键一环。企业微信作为企业内部沟通的主流工具，其群机器人功能为我们提供了一种轻量、高效的告警通知方案。不用写复杂的邮件模板，不用搭沉重的消息队列，一个 Webhook 地址就能搞定。

这篇东西不长，但能帮你从零到一跑通整个对接流程，包括怎么@人、怎么显示彩色字体、怎么让告警消息看起来更专业。

一、创建与配置企业微信群机器人

1.1 在群里添加机器人

企业微信的群机器人功能非常直观，不需要任何开发背景就能完成创建：

打开目标群聊，点击右上角「···」进入群设置

选择「添加群机器人」→「新创建一个机器人」

填写机器人名称（建议用有意义的名称，如「生产环境监控机器人」）

点击「添加机器人」完成创建

创建完成后，系统会生成一个唯一的 Webhook 地址，格式如下：

https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

这个 key 就是机器人的身份标识，务必妥善保管。如果泄露，可以在群设置中重置。

1.2 对接流程概览

整个对接流程可以归纳为四个步骤：

在这里插入图片描述

简单来说，就是「创建机器人 → 配置服务端 → 发消息 → 收通知」。下面我们来详细看看怎么发消息。

二、消息类型与格式详解

2.1 支持的六种消息类型

企业微信机器人目前支持六种消息类型，各自适用于不同的场景：

在这里插入图片描述

消息类型msgtype适用场景特点

文本消息	text	简单通知、快速告警	支持@成员，纯文本展示
Markdown	markdown	复杂告警、格式化内容	支持3种颜色、@成员
Markdown V2	markdown_v2	标准 Markdown 内容	支持表格、代码块，不支持颜色和@
图片消息	image	截图、图表发送	需 base64 + md5
图文消息	news	文章推送、图文展示	支持图片+标题+描述+链接
文件消息	file	日志、报表发送	需先上传获取 media_id

对于告警场景，Markdown 消息是最佳选择，因为它支持颜色区分和@成员。

2.2 文本消息（text）

文本消息是最简单的类型，适合快速发送纯文本通知。

curl 示例：

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "text",
"text": {
"content": "服务器 CPU 使用率超过 90%，请尽快处理！"
}
}'

@指定成员：

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "text",
"text": {
"content": "广州今日天气：29度，大部分多云，降雨概率：60%，<@zhangsan> 请关注",
"mentioned_list": ["wangqing", "@all"]
}
}'

@手机号：

关键参数说明：

参数必填说明

content	✅	消息内容，最长不超过 2048 个字节
mentioned_list	❌	userid 列表，@all 表示@所有人
mentioned_mobile_list	❌	手机号列表，用于@对应成员

注意：文本消息不支持 Markdown 格式和颜色设置，如果需要富文本展示，请使用 Markdown 类型。

2.3 Markdown 消息（重点）

Markdown 消息是告警场景的核心，支持标题、加粗、代码块、引用，以及三种颜色。

基本格式

curl 示例：

支持的 Markdown 语法

语法示例说明

标题	# 一级标题	支持1-6级
加粗	bold
链接	[文字](URL)	可点击链接
引用	> 引用文字	灰色引用块
颜色	<font color="info">绿色</font>	仅支持3种颜色
@成员	<@userid>	@指定成员

颜色支持说明（重要）

企业微信 Markdown 只支持以下三种颜色：

绿色文字（info）
灰色文字（comment）
橙红色文字（warning）

不支持自定义色值（如 #FF0000、red、green 等），也不支持其他颜色名。

@成员的方法

在 Markdown 中@成员有两种方式：

# 方式一：@指定成员（通过 userid）
<@zhangsan> 请尽快处理

# 方式二：@所有人
<@all> 全体成员注意

注意： @userid 中的 userid 是企业微信成员的唯一标识，不是手机号，也不是姓名。获取方式：

管理员在管理后台查看

通过企业微信 API 查询

完整告警消息示例

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "markdown",
"markdown": {
"content": "## 【严重告警】数据库主从延迟过高\\n\\n**实例**: `prod-mysql-master`\\n**延迟**: 15.2s\\n**阈值**: 5s\\n\\n可能原因:\\n1. 从库 IO 线程阻塞\\n2. 大事务执行中\\n3. 网络抖动\\n\\n**时间**: 2026-05-13 14:32:08\\n**状态**: 待处理\\n\\n<@zhangsan> <@lisi> 请尽快处理"
}
}'

2.4 Markdown V2 消息（markdown_v2）

markdown_v2 是新版 Markdown，支持更标准的语法，但不支持颜色和@成员。

curl 示例：

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "markdown_v2",
"markdown_v2": {
"content": "# 标题\\n## 二级标题\\n**加粗**\\n*斜体*\\n- 无序列表\\n1. 有序列表\\n> 引用\\n[链接](https://work.weixin.qq.com)\\n| 表格 | 列2 |\\n| :—– | :—-: |"
}
}'

支持的语法子集：

语法示例说明

标题	# 标题（#后需空格）	支持1-6级
加粗	bold
斜体	italic
无序列表	– item
有序列表	1. item
引用	> 引用	支持多级
链接	[文字](URL)
图片	![alt](URL)
分割线	—
行内代码	`code`
代码块	` ```code````
表格	`	列1

⚠️ 注意：需要客户端版本 4.1.36+（安卓 4.1.38+）

2.5 图片消息（image）

图片消息需要 base64 编码和 md5 值。

curl 示例：

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "image",
"image": {
"base64": "DATA",
"md5": "MD5_VALUE"
}
}'

参数必填说明

base64	✅	图片内容的 base64 编码
md5	✅	图片内容的 MD5 值

2.6 图文消息（news）

图文卡片适合需要展示图片、标题、描述和跳转链接的场景。

curl 示例：

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "news",
"news": {
"articles": [
{
"title": "中秋节礼品领取",
"description": "今年中秋节公司有豪礼相送",
"url": "www.qq.com",
"picurl": "http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png"
}
]
}
}'

参数必填说明

title	✅	标题，最长 128 字节
description	✅	描述，最长 512 字节
url	✅	点击后跳转的链接
picurl	❌	图片 URL（可选）

2.7 文件消息（file）

文件消息需要先上传文件获取 media_id，再发送。

步骤一：上传文件

curl -F "file=@test.xlsx" 'https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media?key=YOUR_KEY&type=file'

步骤二：发送文件消息

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "file",
"file": {
"media_id": "MEDIA_ID"
}
}'

参数必填说明

media_id

✅

通过上传接口获取的文件 ID

三、实战：构建完整的告警通知系统

3.1 告警消息模板设计

一个好的告警消息应该包含以下要素：

告警级别：严重（warning 橙红）、警告（warning 橙红）、恢复（info 绿色）

告警内容：具体的指标和阈值

影响范围：涉及的服务或主机

处理人：@相关责任人

时间戳：精确到秒

状态：待处理/处理中/已恢复

在这里插入图片描述

3.2 常用告警模板

服务器指标告警

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "markdown",
"markdown": {
"content": "## 【严重告警】CPU使用率异常\\n\\n**主机**: `prod-web-01`\\n**指标**: CPU使用率\\n**当前值**: 95.2%\\n**阈值**: 85%\\n**持续时间**: 5分钟\\n\\n**时间**: 2026-05-13 14:32:08\\n**状态**: 待处理\\n\\n<@wangwu> 请尽快处理"
}
}'

数据库告警

告警恢复通知

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "markdown",
"markdown": {
"content": "## 【告警恢复】CPU使用率恢复正常\\n\\n**主机**: `prod-web-01`\\n**指标**: CPU使用率\\n**当前值**: 45.6%\\n**阈值**: 85%\\n**持续时间**: 12分钟\\n\\n**时间**: 2026-05-13 14:44:08\\n**状态**: 已恢复\\n\\n<@wangwu> 告警已恢复，无需处理"
}
}'

服务宕机告警

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"msgtype": "markdown",
"markdown": {
"content": "## 【严重告警】服务不可用\\n\\n**服务**: `order-service`\\n**环境**: 生产环境\\n**状态**: DOWN\\n**错误率**: 100%\\n\\n**影响范围**:\\n- 用户下单功能\\n- 订单查询功能\\n\\n**时间**: 2026-05-13 15:10:22\\n**状态**: 待处理\\n\\n<@oncall> <@devops> 请立即处理"
}
}'

3.3 与监控系统集成

以 Prometheus + Alertmanager 为例，配置 webhook 接收器：

# alertmanager.yml
receivers:
– name: 'wechat-work'
webhook_configs:
– url: 'http://your-service:5000/webhook/wechat'
send_resolved: true
http_config:
timeout: 10s

route:
receiver: 'wechat-work'
group_by: ['alertname', 'severity']
group_wait: 30s
group_interval: 5m
repeat_interval: 4h

四、常见问题与最佳实践

4.1 常见问题

Q1：发送失败，返回 errcode: 93000
A：Webhook key 无效或已过期。检查 key 是否正确，或重新创建机器人获取新 key。

Q2：Markdown 颜色不生效
A：企业微信只支持 info（绿色）、comment（灰色）、warning（橙红）三种颜色，且必须使用 语法（注意是双引号）。不支持 red、green、blue 等颜色名。

Q3：@成员没有高亮效果
A：确保使用的是 <@userid> 语法，且 userid 正确。注意不是手机号，也不是姓名。

Q4：消息内容被截断
A：Markdown 消息最长 4096 字节，文本消息最长 2048 字节。超长内容需要精简或拆分为多条消息。

Q5：频率限制
A：每个机器人每分钟最多发送 20 条消息。超出会被限流，建议对告警进行聚合后再发送。

Q6：markdown_v2 为什么不显示颜色？
A：markdown_v2 是标准 Markdown，不支持 标签和 @成员语法。如果需要颜色和@人，请使用 markdown 类型。

4.2 最佳实践

分级告警：严重告警@具体负责人，一般告警只发群不@人，避免骚扰

聚合发送：同一类告警在 5 分钟内只发一次，减少消息轰炸

包含恢复通知：告警恢复时主动通知，让值班人员知道问题已解决

添加跳转链接：告警消息中附上 Grafana、Kibana 等监控面板的链接

控制消息长度：关键信息放在前面，详细日志放链接里

使用代码块：主机名、IP、错误码等用 ` 包裹，提高可读性

选择合适的消息类型：需要颜色和@人用 markdown，需要表格用 markdown_v2

总结

到这一步，你应该就能稳稳复现了。咱们回顾一下这篇的核心内容：

创建机器人：群设置 → 添加机器人 → 复制 Webhook key
消息类型：text / markdown / markdown_v2 / image / news / file
彩色字体：（绿）、（橙红）、（灰）
@成员：<@userid> @个人，<@all> @所有人
文件发送：先调用 upload_media 上传获取 media_id，再发送
告警模板：提供了 CPU、数据库、服务宕机、恢复通知等完整 curl 示例

企业微信机器人的优势在于轻量和低门槛，不需要额外的服务器或复杂的配置，一个 HTTP POST 就能搞定。对于中小型团队的告警通知场景，它是一个非常实用的选择。

『DevOps运维』从零搭建企业微信告警机器人：接口对接、消息模板与自动化通知

前言