企业官网建设流程全解析

OneUptime 自托管架构全解：从 NGINX 入口、探针监控到三大数据存储的完整数据流

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

导读

本文基于 OneUptime 官方自托管架构文档（西班牙语版，英文原版）展开，逐层拆解 OneUptime 部署在你自己的 Kubernetes 集群或 Docker 主机上时的整体拓扑：边缘入口、Web/API 层、后台 Worker、五大摄取通道、探针（Probe）以及 PostgreSQL / ClickHouse / Valkey 三大数据存储。读完本文，你将理解一条监控结果从探针采集、经队列调度、最终落库的全链路，掌握各个组件的职责边界与关键配置项，并能在自行部署时按需替换外部数据存储或扩展探针副本。

一、架构总览：一张图看懂自托管部署

OneUptime 的自托管架构可以概括为四层：边缘入口层（NGINX Ingress）→ Web/API 与 Worker 核心服务层 → 摄取管道层（Ingest Pipeline）→ 数据存储层，外加可分布在集群内外、直接面向被监控目标的探针层。官方文档用一张 Mermaid 流程图完整描绘了这种典型形态：

这张图蕴含的核心结论（也是原文档「Qué muestra esto / What this shows」一节的要点）如下：

• 最终用户通过集群的NGINX Ingress（TLS）访问 OneUptime，Ingress 负责把流量路由到 UI 与 API；
• 核心服务将状态读写到PostgreSQL、Valkey（Redis 7.2 的 BSD 许可分支）与 ClickHouse三个数据存储；
• 探针既可以运行在集群内部（官方推荐），也可以部署在网络的其它位置（独立 VM/容器），能同时监控防火墙后的内部/私有服务与互联网上的外部/公共资源；
• 探针结果发送到集群内的Probe Ingest，经Valkey 队列排队后由后台Worker写入数据存储；
• 遥测数据（指标/追踪/日志）以及服务器/Agent 数据，通过各自的专用摄取服务进入系统并最终落到ClickHouse。

二、边缘入口：NGINX Ingress 的职责与关键路径

在架构图中，NGINX 是唯一的对外门户，所有 HTTP(S) 流量都从它进入。仓库中的 Nginx/default.conf.template 完整呈现了这个入口的落地实现，从中可以看到几个关键设计：

1. 多服务路由。Ingress 不只转发 API，还承担着将流量分发到 Home/Dashboard UI、Status Pages 以及 API Server 的角色。当BILLING_ENABLED=true时，兜底的location /会 301 跳转到 HTTPS；而/otlp、/telemetry、/session-replay、/kubernetes-cost、/pyroscope、/security-events等摄取路径需要独立的 location 块，确保在计费启用时这些摄取 URL 不会被兜底规则 404 掉（见 Nginx/default.conf.template）。

2. 高吞吐摄取路径的连接复用。对于/telemetry、/incoming-request-ingest等高流量路径，模板显式启用proxy_http_version 1.1与Connection $connection_upgrade来复用上游连接，并为 session replay 块单独放宽了client_max_body_size 4M（默认 1M 会直接导致大 chunk 返回 413）。

3. WebSocket 与 gRPC 支持。/otlp路径开启了 WebSocket 升级头（proxy_set_header Upgrade $http_upgrade）；同时模板中还预留了指向app:4317的 gRPC 上游（backend_app_grpc），用于 OpenTelemetry gRPC 协议接入。从源码结构看，OneUptime 的 Telemetry 模块 自带 GrpcServer.ts 与 MqttServer.ts，分别提供 OTLP gRPC 端点与 IoT 设备 MQTT 摄取，后者默认走 Ingress 的/mqttWebSocket 通道。

4. 压缩与安全头。模板默认开启gzip（压缩级别 5，针对大体积 JS/CSS/JSON），并附加X-Content-Type-Options: nosniff、X-Frame-Options: DENY等安全响应头。

在 Docker Compose 部署中，Ingress 容器将主机的ONEUPTIME_HTTP_PORT（默认 80）映射到容器内 7849 端口、STATUS_PAGE_HTTPS_PORT（默认 443）映射到 7850 端口（见 docker-compose.base.yml）。值得留意的是，模板为 Ingress 容器设置了net.ipv4.ip_local_port_range、net.ipv4.tcp_tw_reuse等 sysctl——因为 Ingress 要代理大量短生命周期上游连接，若不扩大临时端口范围并允许 TIME_WAIT 复用，nginx 会出现99: Address not available的 502 错误。

三、Web/API 与 Worker：核心服务层

架构图的 Web 层包含四个组件：

• Home / Dashboard（UI）：面向管理员/团队的控制面板前端；
• Status Pages（UI）：对外公开的、可绑定自定义域名的状态页；
• API Server：承载 REST 与 gRPC 接口的后端服务；
• Background Worker：消费队列、执行后台任务的处理进程。

从仓库源码看，API 与 Worker 共用同一套应用代码：App/Index.ts 是 API 进程的入口（APP_NAME = "api"），App/FeatureSet/Workers/Index.ts 对应 Worker 进程。API 启动时依次连接三大存储（App/Index.ts）：

await PostgresAppInstance.connect(); // PostgreSQL await Redis.connect(); // Valkey（缓存/队列） await ClickhouseAppInstance.connect(...); // ClickHouse（应用查询） await ClickhouseIngestInstance.connect(...); // ClickHouse（摄取写入）

并注册 Identity、Notification、BaseAPI、MCP、Frontend、Docs、APIReference、Workers、Telemetry、Workflow、Runbook 等全部 FeatureSet 路由。启动前还会做依赖健康检查（checkClickhouseStatus/checkPostgresStatus/checkRedisStatus，重试 3 次），任一存储不可用都会阻止服务就绪。

Worker 端的任务覆盖面极广。App/FeatureSet/Workers/Jobs 下按业务领域组织了几十个 Job 目录，包括 Incident、Alert、Monitor、Slo、StatusPage、OnCallDutyPolicy、Workflow、Runbook、SecurityEvents、TelemetryMonitor、Traces、ServerMonitor、Kubernetes、NetworkDeviceDiscovery 等——这印证了架构图中 Worker 同时读写 PostgreSQL（业务状态）、Valkey（队列）与 ClickHouse（分析数据）的角色。队列基于BullMQ构建（可在 docker-compose.base.yml 的ENABLE_QUEUE_DASHBOARD/QUEUE_DASHBOARD_SECRET配置项中看到 Bull Board 支持），任务通过 Valkey 中转分发。

四、数据存储层：PostgreSQL、ClickHouse 与 Valkey 的分工

架构图中三个存储节点各司其职，这一分工在 docker-compose.base.yml 与官方容量规划文档（App/FeatureSet/Docs/Content/zh-CN/installation/sizing.md）中有更细致的描述：

几个值得展开的实现细节：

ClickHouse 的集群化设计。OneUptime 的分析 schema 始终基于ReplicatedMergeTree + Distributed表引擎，即使单节点部署也通过挂载 Clickhouse/config.d/cluster.xml 启用内嵌 Keeper 与 1 节点的oneuptime集群，让单机环境与生产多分片环境的行为保持一致；Clickhouse/config.d/system-log-ttl.xml 则为 ClickHouse 自身的 query_log/trace_log 等系统日志设置 6 小时 TTL，防止其无限增长占满磁盘。

Valkey 的兼容性。自 13.0.0 起配置名从REDIS_*改为VALKEY_*，但代码仍保留:-${REDIS_*}回退；compose 中 valkey 服务还以redis作为网络别名，旧配置无需改动即可继续工作。官方文档明确：任何实现 Redis 协议的服务器都可以替代它，只需把VALKEY_HOST指向托管 Redis 即可（见 docker-compose.base.yml）。

保留期（TTL）机制。遥测保留期以 ClickHouse TTL 形式按项目、按信号（日志/指标/追踪/性能剖析）分别配置，硬编码默认值为 15 天。OneUptime 不会自动把旧遥测数据归档到对象存储（S3/MinIO 仅可选用于备份），因此长期合规保留需要直接扩大 ClickHouse 容量或自行导出归档。

外部存储替换。架构文档末尾的 Note 特别强调：如果使用外部的 PostgreSQL、Redis 或 ClickHouse 替代内置实例，只需把 config.example.env 中的DATABASE_*、VALKEY_*、CLICKHOUSE_*连接参数指向外部端点（含 SSL 证书配置项DATABASE_SSL_CA/KEY/CERT、CLICKHOUSE_PORT等），逻辑数据流完全不变——API、Worker、Ingest 依然按相同路径读写。这也是自托管迁移到托管数据库服务（如云上 RDS、托管 ClickHouse）时的官方路径。

五、探针层：内部与外部资源的统一监控单元

架构图中，探针（Probe）是唯一与「被监控目标」直接交互的组件，并且明确支持两种部署形态：

• 集群内的 Probe Pod（推荐）：随主集群一起调度；
• 网络其它位置的 Probe VM/容器：可放在被监控网络内部，从而直连防火墙后的私有服务。

探针与目标的交互协议覆盖HTTPS / TCP / Ping / DNS / Custom（自定义脚本），因此既能监控公共网站与 SaaS，也能监控私有应用、数据库等内部服务。仓库中的 Probe 模块即对应此组件：Probe/Jobs/Monitor/FetchList.ts 按周期拉取分配给本探针的监控任务列表，Probe/Jobs/Monitor/FetchMonitorTest.ts 处理测试请求；此外还有 Probe/Jobs/Alive.ts（心跳保活）、Probe/Jobs/Discovery（网络发现）与 Probe/Jobs/NetworkDevice（网络设备 SNMP 轮询）。

从 docker-compose.base.yml 可以看到探针容器的安全设计：默认network_mode: host（直接使用宿主网络栈）、cap_drop: ALL后仅保留 CHOWN、DAC_OVERRIDE、KILL、NET_RAW（供 ping/traceroute 使用）、SETGID、SETUID，并挂载专用的 Probe/seccomp_profile.json 以允许 Chromium/Firefox 沙箱在用户命名空间内执行 chroot。探针内置 Playwright 运行时执行合成监控（Synthetic Monitor），每个监控执行体使用独立 UID 运行，并通过GLOBAL_PROBE_n_SYNTHETIC_MONITOR_MAX_PROCESS_TREE_RSS_BYTES（默认 1.5 GiB）与GLOBAL_PROBE_n_SYNTHETIC_MONITOR_MAX_DISK_BYTES（默认 256 MiB）限制资源占用。

探针注册与私有网络策略。探针通过REGISTER_PROBE_KEY向ONEUPTIME_URL注册（compose 默认内置两个全局探针probe-1/probe-2）。内置全局探针强制只允许公网出站（PROBE_ALLOW_PRIVATE_NETWORK_MONITORS=false）；私有网络监控需要单独配置，相关说明见官方文档 private-network-access.md。当探针数量需随监控器规模扩展时，Helm 部署可启用 KEDA 按队列深度自动伸缩探针副本。

六、摄取管道：五类数据通道如何汇入系统

架构图中部的 Ingest Pipeline 是自托管形态与纯 SaaS 形态差异最大的部分——所有数据都在你的集群内落地。仓库的 App/FeatureSet/Telemetry/Index.ts 就是这条管道的实现入口，它把多条摄取 API 挂载到指定路径前缀上（L57-L93）：

除上述五类主通道外，摄取层还包含 Syslog、Security Events（SIEM）、Change Events、Pyroscope（性能剖析）、Source Map（前端源码映射上传）、Session Replay、Kubernetes Cost（成本分配）以及 Telemetry Writer 等端点——Ingress 模板中/otlp、/telemetry、/session-replay、/kubernetes-cost、/pyroscope、/security-events的独立 location 块与之一一对应。

两条关键的落库路径差异：Probe Ingest 的结果先入 Valkey 队列，由 Worker 异步消费后写入数据存储（架构图中PROBEINGEST --> REDIS与REDIS --> WORKER两条边）；而 OTel / 日志 / Server Monitor / Incoming Request 摄取则直接写入 ClickHouse（--> CH四条边）。这条差异解释了为什么 Worker 是监控事件处理链的必经环节，而遥测管道可以绕过队列直写分析库。

摄取性能调优（见 config.example.env）：遥测写入采用 fan-in 批处理写入器，默认每表缓冲 100000 行或 5 秒强制刷盘一次，最大并发插入 4，挂起行数上限 200000 触发背压；session replay 因单行体量大，单独下调为 2000 行/批。DISABLE_TELEMETRY_INGESTION=true时所有摄取端点保持可达并快速返回成功（避免客户端重试），但不入队、不落库。

七、端到端数据流：一条监控结果的生命周期

综合以上各层，一条监控数据从采集到可查询的完整链路如下（与架构图逐条对应）：

1. 调度：Worker 通过 BullMQ 队列向已注册的探针下发监控任务（探针周期性调用FetchList拉取任务）；
2. 采集：探针按监控器类型（HTTPS/TCP/Ping/DNS/自定义脚本）探测目标，无论目标是集群内部的私有服务还是公网资源；
3. 回传：探针把监控结果 POST 到集群内的 Probe Ingest 端点；
4. 排队：Probe Ingest 将结果写入 Valkey 队列（非直写存储）；
5. 处理：Worker 从队列消费结果，结合 PostgreSQL 中的监控器配置与告警规则做判定；
6. 落库：处理结果与事件写入 PostgreSQL（配置/状态/元数据）；与此同时，OTel、日志、性能剖析等遥测数据经专用摄取端点直接批量写入 ClickHouse（metrics/traces/logs）；
7. 呈现：用户通过 UI（Dashboard / Status Pages）经 API Server 从三个存储读取数据并可视化展示。

部署与扩展时可直接对号入座：Web/API、Worker、探针都是可水平扩展的无状态工作负载（官方容量文档建议至少 1 副本并显式设置资源；KEDA 可按队列深度自动伸缩 Worker 与探针），只有三个数据存储是有状态组件（PostgreSQL 建议 CloudNativePG 3 实例高可用、ClickHouse 建议每分片 ≥2 副本 + 3 Keeper 节点、Valkey 高可用需指向外部托管 Redis）。

八、源码指引与延伸阅读

• 本文核心依据：自托管架构（西班牙语）、自托管架构（英文原版）
• 部署编排：docker-compose.yml、docker-compose.base.yml
• 环境配置：config.example.env（所有连接参数、探针参数、摄取调优参数）
• 入口实现：Nginx/default.conf.template
• 核心进程：App/Index.ts（API 入口）、App/FeatureSet/Workers（Worker Job 全集）
• 摄取管道：App/FeatureSet/Telemetry/Index.ts（各摄取 API 挂载）
• 探针实现：Probe（监控执行、网络发现、设备轮询）
• 容量规划：installation/sizing.md（三大存储的档位建议与高可用配置）
• 自托管专题：官方self-hosted目录下还包含 Slack、Twilio、Microsoft Teams、GitHub、SendGrid 等集成指南，可与本文架构配合阅读（如 private-network-access.md）。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime