本地Windows测试：钉钉群消息/文件传输到Python服务（完整教程）

本文针对Python开发者（尤其是后端/数据分析场景），详细讲解如何在本地Windows环境下，实现钉钉群文字消息传输到Python服务，并解决测试过程中遇到的公网访问、配置入口找不到等常见问题，全程可落地、可复现。

核心场景：钉钉群发送文字消息 → 钉钉自定义机器人推送 → 本地Python服务接收（Windows环境测试），后续可扩展文件传输、数据入库等业务逻辑。

一、核心需求与实现思路

1. 需求说明

在本地Windows环境下，搭建Python服务，接收钉钉群内发送的文字消息，完成调试后可部署到服务器。核心痛点：本地服务无公网地址，钉钉无法直接推送消息。

2. 实现架构

钉钉群 → 钉钉自定义机器人（配置公网接收地址） → 内网穿透工具（ngrok，映射本地端口到公网） → 本地Python HTTP服务（接收并处理消息）

关键依赖：Flask（Python HTTP服务）、ngrok（内网穿透）、钉钉开放平台自定义机器人。

二、前置准备（Windows环境）

1. 环境与工具安装

Python环境 ：确保安装Python 3.7+，cmd输入 python --version 验证。
依赖库安装 ：打开cmd，执行以下命令安装Flask及签名验证相关库： pip install flask hmac hashlib requests
ngrok（内网穿透工具）：
- 下载地址：https://ngrok.com/download（选择Windows版本）。
- 解压到本地文件夹（如 D:\ngrok），无需安装，直接运行。
- 注册ngrok免费账号，登录后复制「Your Authtoken」（用于认证，后续启动需用到）。

2. ngrok配置（解决本地公网访问问题）

ngrok的作用是将本地端口（如8080）映射到公网，生成钉钉可访问的https地址，步骤如下：

打开cmd，切换到ngrok解压目录（示例）： cd D:\ngrok
输入命令完成认证（替换为你的ngrok Authtoken）： ngrok config add-authtoken 你的ngrok Authtoken
启动ngrok，映射本地8080端口（Python服务后续将监听该端口）： ngrok http 8080
启动成功后，控制台会显示类似信息（重点关注「Forwarding」行）： Forwarding https://abc123.ngrok.io -> http://localhost:8080复制 https://abc123.ngrok.io（你的地址会不同），这是后续钉钉机器人要配置的「消息接收地址」前缀。

⚠️ 注意：ngrok免费版重启后公网地址会变化，需重新配置钉钉机器人。

三、Python服务开发（接收钉钉消息）

使用Flask搭建HTTP服务，接收钉钉机器人推送的消息，同时验证消息签名（防止伪造请求）。

1. 完整代码（dingtalk_receive.py）

复制代码

from flask import Flask, request, jsonify
import hmac
import hashlib
import time

app = Flask(__name__)

# ================= 替换为你的钉钉机器人配置 =================
SECRET = "你的钉钉机器人加签密钥"  # 后续从钉钉机器人配置页复制
# =============================================================

def verify_signature(timestamp, nonce, signature):
    """验证钉钉消息签名（防止恶意请求）"""
    sign_str = f"{timestamp}{nonce}{SECRET}".encode("utf-8")
    sign = hmac.new(SECRET.encode("utf-8"), sign_str, hashlib.sha256).hexdigest()
    return sign == signature

@app.route("/dingtalk/receive", methods=["POST"])
def receive_dingtalk_msg():
    """接收钉钉群消息的接口"""
    # 1. 获取签名相关参数（从请求头中获取）
    timestamp = request.headers.get("Timestamp")
    nonce = request.headers.get("Nonce")
    signature = request.headers.get("Sign")
    
    # 2. 验证签名
    if not verify_signature(timestamp, nonce, signature):
        return jsonify({"msg": "签名验证失败"}), 403
    
    # 3. 解析消息内容（仅处理文字消息）
    data = request.get_json()
    if data.get("msgtype") == "text":
        msg_content = data["text"]["content"]  # 消息内容
        sender = data["senderNick"]  # 发送人昵称
        receive_time = time.strftime("%Y-%m-%d %H:%M:%S")  # 接收时间
        
        # 4. 打印消息（控制台输出）
        print(f"\n【{receive_time}】收到钉钉群消息 - 发送人：{sender} | 内容：{msg_content}")
        
        # 5. 消息持久化（写入日志文件，可选）
        with open("dingtalk_msg.log", "a", encoding="utf-8") as f:
            f.write(f"{receive_time} | {sender} | {msg_content}\n")
    
    # 6. 回复钉钉（必须返回200状态码，否则钉钉会重试推送）
    return jsonify({"msg": "消息接收成功"}), 200

if __name__ == "__main__":
    # 启动Python服务，监听8080端口（与ngrok映射端口一致）
    app.run(host="0.0.0.0", port=8080, debug=True)

2. 启动Python服务

将上述代码保存为 dingtalk_receive.py（如保存到 D:\PythonProjects）。
打开cmd，切换到文件所在目录： cd D:\PythonProjects
运行代码，启动服务： python dingtalk_receive.py
看到以下信息说明服务启动成功： * Running on http://0.0.0.0:8080 (Press CTRL+C to quit) `` * Debug mode: on

四、钉钉自定义机器人配置（关键步骤）

核心是找到「消息接收地址」配置入口，填写ngrok生成的公网地址，让钉钉能将消息推送到本地Python服务。

1. 配置步骤（新版钉钉适配）

打开需要配置的钉钉群，点击群聊右上角「...」（更多）→ 选择「智能群助手」。
在智能群助手页面，点击「添加机器人」→ 选择「自定义机器人」→ 点击「添加」。
填写机器人基本信息：
1. 机器人名称：自定义（如「Python测试机器人」）。
2. 勾选「加签」（必须勾选 ），勾选后会显示「加签密钥」，复制该密钥，粘贴到Python代码的 SECRET 变量中。
找到「消息接收地址」输入框（重点！）： ⚠️ 常见问题：部分版本/权限下，加签下方显示「IP地址段」（安全配置项），而非「消息接收地址」。解决方案：找到「消息推送」开关，开启后会自动显示「消息接收地址」输入框。输入格式：ngrok公网地址 + Python接口路径（即 https://你的ngrok地址/dingtalk/receive），示例： https://abc123.ngrok.io/dingtalk/receive
（可选）关键词配置：留空即可（测试阶段建议不限制关键词，避免消息无法推送）。
点击「完成」，机器人添加成功，同时会生成Webhook地址（无需复制，测试场景用不到）。

2. 关键配置说明

「IP地址段」：安全配置项，用于限制调用机器人发消息的IP，测试阶段留空即可，不影响消息接收。
「消息接收地址」：必须是https开头（钉钉不支持http），且地址能公网访问（ngrok生成的地址满足要求）。
加签密钥：必须与Python代码中的 SECRET 完全一致（大小写、空格需匹配），否则会出现签名验证失败。
在钉钉群内@刚添加的机器人，发送任意文字消息（如「测试消息：Hello Python！」）。
查看Python服务控制台，若输出类似以下内容，说明消息接收成功： 【2026-01-19 16:30:00】收到钉钉群消息 - 发送人：你的昵称 | 内容：测试消息：Hello Python！
查看Python文件同目录，会生成 dingtalk_msg.log 文件，消息内容已写入日志（持久化验证）。
问题现象：cmd执行 ngrok http 8080 后报错，或无Forwarding地址。
解决方案：
- 检查8080端口是否被占用：cmd输入 netstat -ano | findstr "8080"，若被占用，更换端口（如8081，需同步修改Python代码的port和ngrok命令 ngrok http 8081）。
- 确保网络正常，ngrok需要联网认证，关闭代理或防火墙重试。

2. 签名验证失败

问题现象：Python控制台输出「签名验证失败」，钉钉推送消息返回403。
解决方案：
- 确认Python代码中的 SECRET 与钉钉机器人的「加签密钥」完全一致（复制粘贴，避免手动输入错误）。
- 检查消息接收地址是否正确，钉钉推送的地址必须与Python接口路径匹配。

3. 钉钉提示「消息推送失败」

问题现象：钉钉群发送消息后，机器人提示「消息推送失败」。
解决方案：
- 检查Python服务是否正常运行（控制台无报错，监听端口正确）。
- 检查ngrok是否在线（ngrok控制台无红色错误，Forwarding地址正常）。
- 确认消息接收地址是https开头（ngrok默认生成https地址，不要改为http）。

4. 找不到「消息接收地址」输入框

问题现象：加签下方只有「IP地址段」，没有「消息接收地址」。
解决方案：
- 进入机器人「设置」页（而非「管理」页），找到「消息推送」开关，开启后会显示消息接收地址。
- 若仍无，联系企业钉钉管理员，确认账号有机器人消息推送配置权限。

七、扩展场景（可选）

本教程实现了文字消息接收，后续可扩展以下功能：

文件接收：创建钉钉企业内部应用（需企业账号），调用文件下载API，实现钉钉群文件自动下载到本地Python服务。
消息处理：将接收的消息解析后存入数据库（如MySQL、MongoDB），或调用AI接口进行内容分析。
服务部署：测试通过后，将Python服务部署到Linux服务器，替换ngrok地址为服务器公网IP/域名，实现长期稳定运行。

八、总结

本地Windows测试钉钉消息推送到Python服务的核心是「内网穿透」（ngrok）+「机器人配置」（消息接收地址），关键步骤如下：

安装依赖工具（Python库、ngrok），配置ngrok生成公网地址。
开发Python HTTP服务，实现消息接收与签名验证。
配置钉钉自定义机器人，开启消息推送，填写公网接收地址。
发送测试消息，验证Python服务接收功能。

按照本文步骤操作，可快速跑通本地测试流程，后续可根据实际业务需求扩展功能。若遇到其他问题，欢迎在评论区留言交流～