摘要:
本文记录一次基于 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 发来的
/feishuJSON 请求。 - 通过代理把 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 的团队来说,这种方式不会推翻现有监控体系,却能显著改善告警治理、值班协作和通知可靠性。