摘要:
本文记录一次基于 OneUptime 搭建统一事件管理和值班通知平台的实践。方案使用 Docker Compose 单机部署 OneUptime,通过 Alertmanager 接入 Prometheus 告警,再借助 Python 转发服务将 OneUptime Workflow 通知稳定发送到飞书群,解决重复告警、通知分散和容器代理不稳定等问题。

背景:告警不是发出去就结束了

很多监控系统最初都是这样演进的:Prometheus 负责指标和告警,Grafana 负责看板,Alertmanager 直接发飞书,某些业务系统又自己发机器人消息。

短期看很方便,长期就会出现几个典型问题:

  • 同一个故障会从多个入口重复通知。
  • 告警被谁确认、谁处理、是否升级,没有统一记录。
  • 飞书群里只有消息,没有完整事件生命周期。
  • 告警恢复后,通知链路不一定能自动关闭事件。
  • 后续接入 SkyWalking、日志、APM 时,入口会越来越乱。

这次实践的目标不是替换 Prometheus 或 Grafana,而是引入 OneUptime 作为统一的事件管理和值班通知平台。

最终职责拆分如下:

Prometheus: 指标采集、规则计算、告警产生
Grafana: 监控看板展示
Alertmanager: 告警分组、收敛,并转发到 OneUptime
OneUptime: 事件管理、去重、值班、升级、状态页、通知编排
飞书: 最终通知入口
SkyWalking: 后续作为 APM、Trace、服务拓扑平台

告警链路的核心原则是:只保留一个最终通知出口。在这套方案中,飞书只接收 OneUptime 发出的通知。

整体架构

OneUptime 采用单机 Docker Compose 部署,外部使用 OpenResty 做 HTTPS 反向代理。

访问链路如下:

浏览器 / Alertmanager / 飞书消息链接
  -> https://oneuptime.example.com
  -> OpenResty HTTPS 反向代理
  -> http://127.0.0.1:8080
  -> oneuptime-ingress
  -> oneuptime-app
  -> PostgreSQL / ClickHouse / Redis

告警通知链路如下:

PrometheusRule
  -> Prometheus
  -> Alertmanager
  -> OneUptime Webhook / Integration
  -> OneUptime Alert / Incident
  -> OneUptime Workflow
  -> Python feishu-forwarder
  -> 飞书自定义机器人
  -> 飞书群

这里额外加了一层 Python feishu-forwarder,主要是为了解决 OneUptime 容器内 Workflow 直接访问飞书公网 Webhook 时遇到的代理不稳定问题。

OneUptime 部署关键配置

OneUptime 使用 Docker Compose 单机部署,版本固定为 10.5.37。生产环境不建议继续使用 release 这类滚动标签,否则后续升级和回滚都不好追踪。

核心目录规划如下:

/data/oneuptime                 当前版本软链接
/data/oneuptime-10.5.37         OneUptime 部署目录
/data/oneuptime-backups         备份目录
/data/docker                    Docker 数据目录

config.env 中几个关键配置如下:

HOST=oneuptime.example.com
PROVISION_SSL=false
HTTP_PROTOCOL=https
ONEUPTIME_HTTP_PORT=8080
APP_TAG=10.5.37
ENVIRONMENT=production
IS_ENTERPRISE_EDITION=false
BILLING_ENABLED=false

这些配置的含义很关键:

  • HOST 必须是正式访问域名,不建议生产环境使用 IP。
  • HTTP_PROTOCOL=https 决定 OneUptime 生成的页面链接、API 地址、Webhook 地址使用 HTTPS。
  • PROVISION_SSL=false 表示证书不由 OneUptime 自动申请,而是交给外部 OpenResty。
  • ONEUPTIME_HTTP_PORT=8080 表示 OneUptime 只在宿主机本地暴露 HTTP 入口。
  • APP_TAG=10.5.37 用来固定镜像版本。

启动方式如下:

cd /data/oneuptime

export $(grep -v '^#' config.env | xargs)
docker compose up --remove-orphans -d

日常检查容器状态:

cd /data/oneuptime

docker compose ps
docker compose logs --tail=100 app
docker compose logs --tail=100 ingress

OpenResty 反向代理

OneUptime 容器不直接占用宿主机 80 和 443,这两个端口交给 OpenResty。OneUptime 内部入口只监听 8080。

OpenResty 示例配置如下:

server {
    listen 80;
    server_name oneuptime.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name oneuptime.example.com;

    ssl_certificate     /usr/local/openresty/nginx/conf/certs/oneuptime.example.com.crt;
    ssl_certificate_key /usr/local/openresty/nginx/conf/certs/oneuptime.example.com.key;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

检查并重启 OpenResty:

/usr/local/openresty/nginx/sbin/nginx -t
systemctl restart openresty
systemctl status openresty

Alertmanager 接入 OneUptime

OneUptime 部署完成后,可以在项目中创建 Prometheus / Alertmanager 类型的 Integration 或 Webhook,然后把 Alertmanager 的 receiver 指向 OneUptime。

Alertmanager 示例配置如下:

receivers:
  - name: oneuptime
    webhook_configs:
      - url: https://oneuptime.example.com/<oneuptime-webhook-path>
        send_resolved: true

route:
  group_by:
    - alertname
    - cluster
    - job
    - instance
    - severity
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  receiver: oneuptime

这里一定要开启:

send_resolved: true

否则 Prometheus 告警恢复后,OneUptime 中对应事件可能无法自动变为 resolved。

接入时建议先只接一条测试告警,确认 OneUptime 能创建事件、飞书能收到通知、告警恢复后事件能自动关闭,再逐步切换更多规则。

为什么加一层飞书转发服务

理论上,OneUptime Workflow 可以直接用 API Post (JSON) 请求飞书机器人 Webhook。但实际联调时遇到了几个问题:

  • 容器内 curl 通过代理访问飞书可以成功。
  • OneUptime Workflow 直接请求飞书时仍然可能报 socket hang up。
  • 给容器配置 HTTP_PROXY / HTTPS_PROXY 后,OneUptime 内部服务调用也可能被代理影响。
  • 即使配置 NO_PROXY,Workflow HTTP 组件经过代理链路仍不稳定。

最终采用更稳的方案:

OneUptime 只请求内网 HTTP 地址
Python 转发服务负责通过宿主机代理访问飞书
飞书真实 Webhook 只保存在宿主机环境变量中

这样 OneUptime 页面里不再保存飞书真实 Webhook,也避免容器级代理影响 OneUptime 内部组件通信。

Python 飞书转发服务核心实现

服务目录:

/data/feishu-forwarder

环境变量文件:

LISTEN_HOST=0.0.0.0
LISTEN_PORT=18080

FEISHU_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/替换为真实机器人Webhook

HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080

feishu-forwarder.env 包含飞书机器人 Webhook,权限建议设置为 600:

chmod 600 /data/feishu-forwarder/feishu-forwarder.env

核心 Python 代码如下:

#!/usr/bin/env python3
import json
import os
import urllib.error
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

LISTEN_HOST = os.getenv("LISTEN_HOST", "0.0.0.0")
LISTEN_PORT = int(os.getenv("LISTEN_PORT", "18080"))
FEISHU_WEBHOOK = os.getenv("FEISHU_WEBHOOK", "")
MAX_BODY_SIZE = int(os.getenv("MAX_BODY_SIZE", str(1024 * 1024)))

HTTP_PROXY = os.getenv("HTTP_PROXY") or os.getenv("http_proxy")
HTTPS_PROXY = os.getenv("HTTPS_PROXY") or os.getenv("https_proxy")


class Handler(BaseHTTPRequestHandler):
    server_version = "FeishuForwarder/1.0"

    def send_json(self, status, payload):
        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self):
        if self.path == "/healthz":
            self.send_json(200, {"status": "ok"})
            return

        self.send_json(404, {"error": "not found"})

    def do_POST(self):
        if self.path != "/feishu":
            self.send_json(404, {"error": "not found"})
            return

        if not FEISHU_WEBHOOK:
            self.send_json(500, {"error": "FEISHU_WEBHOOK is not configured"})
            return

        content_length = int(self.headers.get("Content-Length", "0"))

        if content_length <= 0:
            self.send_json(400, {"error": "empty request body"})
            return

        if content_length > MAX_BODY_SIZE:
            self.send_json(413, {"error": "request body too large"})
            return

        body = self.rfile.read(content_length)

        try:
            json.loads(body.decode("utf-8"))
        except Exception as exc:
            self.send_json(400, {"error": "invalid json", "detail": str(exc)})
            return

        try:
            status, response = forward_to_feishu(body)
            self.send_json(200, {
                "status": "forwarded",
                "feishu_status": status,
                "feishu_response": response,
            })
        except Exception as exc:
            self.send_json(502, {
                "error": "failed to forward to feishu",
                "detail": str(exc),
            })


def forward_to_feishu(body):
    proxies = {}

    if HTTP_PROXY:
        proxies["http"] = HTTP_PROXY

    if HTTPS_PROXY:
        proxies["https"] = HTTPS_PROXY

    opener = urllib.request.build_opener(urllib.request.ProxyHandler(proxies))

    request = urllib.request.Request(
        FEISHU_WEBHOOK,
        data=body,
        method="POST",
        headers={
            "Content-Type": "application/json",
            "User-Agent": "OneUptime-Feishu-Forwarder/1.0",
        },
    )

    try:
        with opener.open(request, timeout=15) as response:
            response_body = response.read().decode("utf-8", errors="replace")
            return response.status, response_body
    except urllib.error.HTTPError as exc:
        error_body = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"Feishu HTTP {exc.code}: {error_body}") from exc


def main():
    httpd = ThreadingHTTPServer((LISTEN_HOST, LISTEN_PORT), Handler)
    print(f"Feishu forwarder listening on {LISTEN_HOST}:{LISTEN_PORT}", flush=True)
    httpd.serve_forever()


if __name__ == "__main__":
    main()

这个服务只做三件事:

  • 对外提供 /healthz 健康检查。
  • 接收 OneUptime 发来的 /feishu JSON 请求。
  • 通过代理把 JSON 原样转发给飞书机器人 Webhook。

使用 systemd 托管转发服务

systemd 服务文件如下:

[Unit]
Description=Feishu Webhook Forwarder for OneUptime
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/data/feishu-forwarder
EnvironmentFile=/data/feishu-forwarder/feishu-forwarder.env
ExecStart=/usr/bin/python3 /data/feishu-forwarder/feishu_forwarder.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

启动服务:

systemctl daemon-reload
systemctl enable --now feishu-forwarder
systemctl status feishu-forwarder

健康检查:

curl --noproxy '*' http://127.0.0.1:18080/healthz

发送测试消息:

curl --noproxy '*' -X POST http://127.0.0.1:18080/feishu \
  -H 'Content-Type: application/json' \
  -d '{"msg_type":"text","content":{"text":"【OneUptime】Python 转发服务测试"}}'

如果返回 status: forwarded,并且飞书群收到消息,说明转发服务已经正常。

OneUptime Workflow 配置

在 OneUptime 中进入对应 Project,例如:

基础设施监控

创建 Workflow,使用 API Post (JSON) 组件。

URL 填写 Python 转发服务地址:

http://10.0.0.25:18080/feishu

不要填写飞书真实 Webhook,也不要把 /open-apis/bot/v2/hook/... 拼到这个 URL 后面。

Headers:

{
  "Content-Type": "application/json"
}

Body 示例:

{
  "msg_type": "text",
  "content": {
    "text": "【OneUptime】基础设施监控告警测试:通过 Python 转发服务发送。"
  }
}

飞书机器人如果启用了关键词安全策略,消息内容中必须包含关键词,例如:

OneUptime

否则飞书会拒收消息。

避雷指南

不要让 Alertmanager 和 Grafana 继续直接发飞书

接入 OneUptime 后,Alertmanager 和 Grafana 如果继续发送同类飞书告警,会导致重复通知。

推荐链路是:

Alertmanager -> OneUptime -> Workflow -> 飞书

而不是:

Alertmanager -> 飞书
Grafana -> 飞书
OneUptime -> 飞书

OneUptime 直连飞书报 socket hang up

如果 Workflow 直接请求:

https://open.feishu.cn/open-apis/bot/v2/hook/...

可能出现:

socket hang up
ECONNRESET

这种情况下,不建议继续折腾容器代理,而是改为访问内网转发器:

http://10.0.0.25:18080/feishu

本机 curl 访问 127.0.0.1 也可能走代理

如果执行健康检查时出现:

curl: (52) Empty reply from server

并且 curl -v 里看到它访问了代理服务器,说明本机地址也被代理劫持了。

处理方式:

curl --noproxy '*' http://127.0.0.1:18080/healthz

同时建议在系统代理配置中加入:

export no_proxy="localhost,127.0.0.1,::1"
export NO_PROXY="localhost,127.0.0.1,::1"

OneUptime 页面报 Network Error

如果临时通过 http://oneuptime.example.com:8080 访问 OneUptime,但 config.env 中 HOST=oneuptime.example.com 没带端口,前端生成 API 地址时可能缺少 8080,导致 Network Error。

正式环境建议统一通过 HTTPS 反向代理访问:

https://oneuptime.example.com

此时配置保持:

HOST=oneuptime.example.com
HTTP_PROTOCOL=https
ONEUPTIME_HTTP_PORT=8080

OpenResty 80 或 443 端口被占用

如果 OpenResty 启动时报:

bind() to 0.0.0.0:80 failed (98: Address already in use)

先检查端口:

ss -lntp | egrep ':80|:443|:8080|:18080'

最终应保证:

OpenResty: 80/443
OneUptime: 8080
feishu-forwarder: 18080

飞书收不到消息的排查顺序

建议按链路从近到远排查:

systemctl status feishu-forwarder
curl --noproxy '*' http://127.0.0.1:18080/healthz

再测试宿主机到飞书:

curl --noproxy '*' -X POST http://127.0.0.1:18080/feishu \
  -H 'Content-Type: application/json' \
  -d '{"msg_type":"text","content":{"text":"【OneUptime】Python 转发服务测试"}}'

最后从 OneUptime 容器内测试到转发器:

cd /data/oneuptime

docker compose exec app curl --noproxy '*' -X POST http://10.0.0.25:18080/feishu \
  -H 'Content-Type: application/json' \
  -d '{"msg_type":"text","content":{"text":"【OneUptime】app 容器访问转发器测试"}}'

如果宿主机测试成功、容器测试失败,重点检查 Docker 网络、防火墙和 18080 端口访问策略。

安全与运维建议

feishu-forwarder.env 中保存了飞书机器人 Webhook,必须当作敏感文件处理:

chmod 600 /data/feishu-forwarder/feishu-forwarder.env

建议同时做到:

  • 不在 OneUptime 页面中保存飞书真实 Webhook。
  • 不在文档截图、日志、Git 仓库中暴露 Webhook。
  • 已经泄露过的 Webhook 立即在飞书机器人中重新生成。
  • 防火墙限制 18080 只允许 OneUptime 容器网段、本机或运维网段访问。
  • feishu-forwarder 使用 systemd 托管并设置开机自启。
  • 后续正式告警继续统一从 OneUptime 发出,不恢复 Alertmanager 或 Grafana 直接飞书通知。

OneUptime 侧需要重点备份:

/data/oneuptime/config.env
/data/oneuptime/docker-compose.yml
/data/oneuptime/docker-compose.base.yml
/data/oneuptime-backups
PostgreSQL 数据
ClickHouse 数据
OpenResty 证书和配置

PostgreSQL 备份示例:

cd /data/oneuptime

docker compose exec -T postgres pg_dump -U postgres oneuptimedb \
  > /data/oneuptime-backups/oneuptimedb-$(date +%F).sql

总结

这套 OneUptime + 飞书通知方案的关键价值,是把“告警消息”提升成了“事件管理”。

Prometheus 仍然专注指标和规则,Grafana 仍然专注看板,Alertmanager 只负责把告警转给 OneUptime。OneUptime 统一处理事件、确认、恢复、升级和值班,再通过 Python 转发服务稳定发送到飞书。

最终形成的闭环是:

监控发现问题
  -> Alertmanager 收敛
  -> OneUptime 生成事件
  -> Workflow 编排通知
  -> Python 转发器解决代理问题
  -> 飞书触达人
  -> 恢复后事件自动关闭

对于已经有 Prometheus + Grafana 的团队来说,这种方式不会推翻现有监控体系,却能显著改善告警治理、值班协作和通知可靠性。