常见问题

按主题归类。仍无法解决时，可到 GitHub Issues 提问。

鉴权与接入

请求返回 401 unauthorized？

服务配置了 DINGTALK_API_TOKEN，但请求未携带 Authorization: Bearer <token> 头，或 token 不匹配。 要么带上正确的头，要么清空 DINGTALK_API_TOKEN 关闭鉴权。

钉钉返回 errcode 300005「token is not exist」？

这是 Webhook 地址里的 access_token 无效或已失效。 回到钉钉群机器人设置里重新复制 Webhook，更新 DINGTALK_WEBHOOK_URL。

加签密钥怎么填？

机器人在「安全设置」里勾选了「加签」时，把密钥（SEC 开头那串）填入 DINGTALK_SECRET。未勾选加签则留空。填错会导致钉钉校验签名失败。

推送与消息

返回 502 是什么原因？

服务向钉钉 API 请求超时（10 秒）或响应解析失败时返回 502。 常见于 Webhook 地址不可达、网络不通，或钉钉返回了非 JSON 内容。

返回 400 invalid msgtype？

msgtype 只支持 "text" 和 "markdown" 两种，其他值会被拒绝。

Markdown 消息怎么换行、加粗？

换行用 \n，加粗用 **文字**。 例如 "content":"# 标题\n**加粗**\n普通文字"。

怎么 @成员 / @所有人？

在请求体加 "atMobiles":["138xxxx"] @指定手机号成员， 加 "isAtAll":true @所有人，两者可同时使用。

hostname 字段有什么用？

多台服务器共用同一推送服务时，用它区分消息来源。 text 消息在内容前加 [hostname]，markdown 消息顶部加红色加粗来源标题。

部署与运行

启动时端口被占用？

先清理残留进程再启动：lsof -ti:3000 | xargs kill。 也可在 .env 中改 PORT 换一个端口。

启动报 DINGTALK_WEBHOOK_URL is required？

未配置 DINGTALK_WEBHOOK_URL。检查 .env 是否已填写， 或确认环境变量已 export 到当前 shell。

怎么让服务后台运行、开机自启？

生产环境推荐用 systemd 托管，崩溃自动重启、开机自启。详见 部署运维。

监控与日志

monitor.sh 从不推送告警？

• 确认 CHECK_SERVICES、CHECK_PORTS 不为空，否则没有可检查项
• 确认 PUSH_ENDPOINT 指向正确的推送服务地址
• 若推送服务开了鉴权，确认 DINGTALK_API_TOKEN 已配置
• 确认 cron 已正确写入：crontab -l 查看

改了 monitor.conf 要重启吗？

不需要。配置在每次 cron 执行时重新加载，下次运行自动生效。

请求日志和监控日志在哪？

• 请求日志：由 DINGTALK_ACCESS_LOG 指定路径，超过 1MB 自动轮转
• 监控日志：由 monitor.conf 的 LOG_FILE 指定，超过 5000 行自动截断