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

---

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

1. 📁 掌握企业微信群机器人的完整创建与配置流程
2. 🐍 学会使用 curl 调用 Webhook 发送多种类型的告警消息
3. 🌐 精通 Markdown 消息格式，实现彩色字体、@成员等高级功能
4. 🖥️ 获得可直接落地的告警通知模板和最佳实践
5. 🔧 了解文件发送、模板卡片等进阶用法

---

前言

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

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

---

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

1.1 在群里添加机器人

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

1. 打开目标群聊，点击右上角「···」进入群设置
2. 选择「添加群机器人」→「新创建一个机器人」
3. 填写机器人名称（建议用有意义的名称，如「生产环境监控机器人」）
4. 点击「添加机器人」完成创建

创建完成后，系统会生成一个唯一的 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"]
        }
    }'

@手机号：

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%，请尽快处理！",
            "mentioned_mobile_list": ["13800001111", "13900002222"]
        }
    }'

关键参数说明：

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

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

2.3 Markdown 消息（重点）

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

基本格式

curl 示例：

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \
   -H 'Content-Type: application/json' \
   -d '{
        "msgtype": "markdown",
        "markdown": {
            "content": "**实时新增用户反馈**<font color=\"warning\">132例</font>，请相关同事注意。"
        }
    }'

支持的 Markdown 语法

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

颜色支持说明（重要）

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

<font color="info">绿色文字（info）</font>
<font color="comment">灰色文字（comment）</font>
<font color="warning">橙红色文字（warning）</font>

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

@成员的方法

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

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

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

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

1. 管理员在管理后台查看
2. 通过企业微信 API 查询

完整告警消息示例

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \
   -H 'Content-Type: application/json' \
   -d '{
        "msgtype": "markdown",
        "markdown": {
            "content": "## <font color=\"warning\">【严重告警】数据库主从延迟过高</font>\n\n**实例**: `prod-mysql-master`\n**延迟**: <font color=\"warning\">15.2s</font>\n**阈值**: 5s\n\n可能原因:\n1. 从库 IO 线程阻塞\n2. 大事务执行中\n3. 网络抖动\n\n**时间**: 2026-05-13 14:32:08\n**状态**: <font color=\"warning\">待处理</font>\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)
图片	
分割线	---
行内代码	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 告警消息模板设计

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

1. 告警级别：严重（warning 橙红）、警告（warning 橙红）、恢复（info 绿色）
2. 告警内容：具体的指标和阈值
3. 影响范围：涉及的服务或主机
4. 处理人：@相关责任人
5. 时间戳：精确到秒
6. 状态：待处理/处理中/已恢复

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": "## <font color=\"warning\">【严重告警】CPU使用率异常</font>\n\n**主机**: `prod-web-01`\n**指标**: CPU使用率\n**当前值**: <font color=\"warning\">95.2%</font>\n**阈值**: 85%\n**持续时间**: 5分钟\n\n**时间**: 2026-05-13 14:32:08\n**状态**: <font color=\"warning\">待处理</font>\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": "## <font color=\"warning\">【严重告警】数据库主从延迟过高</font>\n\n**实例**: `prod-mysql-master`\n**延迟**: <font color=\"warning\">15.2s</font>\n**阈值**: 5s\n\n可能原因:\n1. 从库 IO 线程阻塞\n2. 大事务执行中\n3. 网络抖动\n\n**时间**: 2026-05-13 14:32:08\n**状态**: <font color=\"warning\">待处理</font>\n\n<@zhangsan> <@lisi> 请尽快处理"
        }
    }'

告警恢复通知

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \
   -H 'Content-Type: application/json' \
   -d '{
        "msgtype": "markdown",
        "markdown": {
            "content": "## <font color=\"info\">【告警恢复】CPU使用率恢复正常</font>\n\n**主机**: `prod-web-01`\n**指标**: CPU使用率\n**当前值**: <font color=\"info\">45.6%</font>\n**阈值**: 85%\n**持续时间**: 12分钟\n\n**时间**: 2026-05-13 14:44:08\n**状态**: <font color=\"info\">已恢复</font>\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": "## <font color=\"warning\">【严重告警】服务不可用</font>\n\n**服务**: `order-service`\n**环境**: 生产环境\n**状态**: <font color=\"warning\">DOWN</font>\n**错误率**: 100%\n\n**影响范围**:\n- 用户下单功能\n- 订单查询功能\n\n**时间**: 2026-05-13 15:10:22\n**状态**: <font color=\"warning\">待处理</font>\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（橙红）三种颜色，且必须使用 <font color="info"> 语法（注意是双引号）。不支持 red、green、blue 等颜色名。

Q3：@成员没有高亮效果

A：确保使用的是 <@userid> 语法，且 userid 正确。注意不是手机号，也不是姓名。

Q4：消息内容被截断

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

Q5：频率限制

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

Q6：markdown_v2 为什么不显示颜色？

A：markdown_v2 是标准 Markdown，不支持 <font> 标签和 @成员 语法。如果需要颜色和@人，请使用 markdown 类型。

4.2 最佳实践

1. 分级告警：严重告警@具体负责人，一般告警只发群不@人，避免骚扰
2. 聚合发送：同一类告警在 5 分钟内只发一次，减少消息轰炸
3. 包含恢复通知：告警恢复时主动通知，让值班人员知道问题已解决
4. 添加跳转链接：告警消息中附上 Grafana、Kibana 等监控面板的链接
5. 控制消息长度：关键信息放在前面，详细日志放链接里
6. 使用代码块 ：主机名、IP、错误码等用 ````` 包裹，提高可读性
7. 选择合适的消息类型 ：需要颜色和@人用 markdown，需要表格用 markdown_v2

---

总结

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

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

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

---