API 参考

服务暴露两个 HTTP 端点：POST /api/v1/push 与 GET /health。 本文说明推送接口的请求体字段、响应、鉴权方式、消息类型与环境变量。

接口一览

方法	路径	说明
POST	/api/v1/push	推送消息到钉钉群
GET	/health	健康检查，返回 { "status": "ok" }

POST /api/v1/push

请求体字段

字段	类型	必填	说明
msgtype	string	是	消息类型，"text" 或 "markdown"
content	string	是	消息内容
title	string	否	Markdown 标题，msgtype 为 markdown 时生效，默认 "消息"
atMobiles	string[]	否	@成员的手机号列表
isAtAll	bool	否	是否 @所有人
hostname	string	否	来源主机标识，用于多服务器共用时区分来源

响应

所有响应均为 application/json。成功时：

{ "ok": true }

钉钉返回的错误会透传：

{ "ok": false, "errcode": 300005, "errmsg": "token is not exist" }

状态码	含义
400	校验失败（JSON 解析失败、msgtype 非法、content 缺失或非字符串）
401	鉴权失败（配置了 DINGTALK_API_TOKEN 但请求未携带或 token 不匹配）
405	方法不允许（/api/v1/push 仅接受 POST）
502	服务自身异常（请求钉钉超时、响应解析失败等）

鉴权

配置了 DINGTALK_API_TOKEN 后，所有 /api/v1/push 请求必须携带 Authorization: Bearer <token> 请求头，否则返回 401。 未配置该变量则不启用鉴权，接口对网络内所有可达者开放。

curl -X POST http://localhost:3000/api/v1/push \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"text","content":"hello"}'

消息类型

文本（text）

curl -X POST http://localhost:3000/api/v1/push \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"text","content":"hello"}'

Markdown

curl -X POST http://localhost:3000/api/v1/push \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"markdown","title":"标题","content":"# hello\n**bold**"}'

@成员

curl -X POST http://localhost:3000/api/v1/push \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"text","content":"hello","atMobiles":["138xxxx"],"isAtAll":false}'

标记来源主机

多台服务器共用同一推送服务时，通过 hostname 字段区分来源。 text 消息会在内容前加 [hostname] 前缀；markdown 消息会在顶部追加红色加粗的来源标题。

curl -X POST http://localhost:3000/api/v1/push \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"markdown","title":"标题","content":"## 备份完成","hostname":"server-b"}'

环境变量

变量	必填	默认值	说明
DINGTALK_WEBHOOK_URL	是	-	钉钉群机器人 Webhook 地址
DINGTALK_SECRET	否	-	加签密钥，机器人配置了加签时必填
DINGTALK_API_TOKEN	否	-	API 鉴权 token，设置后请求需带 Authorization: Bearer <token> 头
DINGTALK_ACCESS_LOG	否	-	请求日志文件路径，不设置则不写文件
PORT	否	3000	服务监听端口