news 2026/9/18 14:02:42

OneUptime 单机部署完全指南：使用 Docker Compose 免费搭建开源可观测性平台

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
OneUptime 单机部署完全指南：使用 Docker Compose 免费搭建开源可观测性平台

OneUptime 单机部署完全指南：使用 Docker Compose 免费搭建开源可观测性平台

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

本文以 OneUptime 官方 Docker Compose 部署文档为主线，面向希望在自有服务器上免费自托管 OneUptime 的开发者与运维人员，完整覆盖系统选型、安装步骤、TLS/SSL 反向代理配置、生产就绪检查清单、更新与卸载等全部环节，并结合仓库源码剖析npm start、npm run update、npm run down等命令背后的实际执行逻辑，帮助读者在 Debian、Ubuntu 或 RHEL 上独立完成一套可长期运行的单机监控与可观测性平台。

一、单机部署栈概览：Compose 启动后你会得到什么

OneUptime 是一套完整的开源监控与可观测性平台。使用 Docker Compose 部署时，并不是启动"一个服务"，而是拉起一组相互依赖的容器。以仓库根目录的 docker-compose.yml 与 docker-compose.base.yml 为证，一次docker compose up至少会创建以下核心服务：

服务名镜像/说明职责
postgrespostgres:15主关系型数据库，存放项目、用户、监控配置等业务数据
clickhouseclickhouse/clickhouse-server:26.7列式分析数据库，承载遥测数据（日志、Trace、指标等）
valkeyvalkey/valkey:9.1-alpine缓存与任务队列（Redis 协议兼容，详见后文"缓存与队列"小节）
apponeuptime/app:${APP_TAG}核心 API 服务，同时消费后台与遥测任务队列
ingressoneuptime/nginx:${APP_TAG}Nginx 网关，统一对外暴露 HTTP/HTTPS 入口
probe-1/probe-2oneuptime/probe:${APP_TAG}内置全球探针，负责执行各类监控检查
runneroneuptime/runner:${APP_TAG}AI/Runner 执行器，支持代码修复等自动化能力

从 docker-compose.yml 可以看到，app、probe-1、runner、ingress都通过x-common-depends-on等待postgres、valkey、clickhouse三个基础服务健康检查通过后才启动；ingress将${ONEUPTIME_HTTP_PORT}（默认80）映射到容器内7849端口、将${STATUS_PAGE_HTTPS_PORT}（默认443）映射到容器内7850端口，同时为高并发场景预置了更宽的本地端口范围与tcp_tw_reuse内核参数。理解这套拓扑，有助于排查后续部署中的端口冲突与依赖启动顺序问题。

二、选择系统要求：推荐配置与 Homelab 最低配置

Docker Compose 单机部署方式下，整个平台（包含数据库、网关、探针）都跑在同一台服务器上，因此资源要求明显高于只部署单个组件的场景。官方文档根据用途与预算给出两档选型：

  • 推荐系统要求（追求最优性能）

    • 16 GB 内存
    • 8 核 CPU
    • 400 GB 磁盘
    • Ubuntu 22.04
    • 已安装 Docker 与 Docker Compose

  • 家庭环境 / 最低配置（个人或实验用途）

    • 8 GB 内存
    • 4 核 CPU
    • 20 GB 磁盘
    • 已安装 Docker 与 Docker Compose

官方文档特别指出，有用户甚至在树莓派（RaspberryPi）上跑过 OneUptime，说明最低档仍有不小的下探空间。但需要结合源码理解磁盘要求为何偏高：postgres与clickhouse分别挂载了独立命名卷（见 docker-compose.base.yml 中的volumes: postgres:与clickhouse:），遥测数据会长期累积；同时Clickhouse/config.d/system-log-ttl.xml这类 TTL 策略只约束 ClickHouse 自身的系统日志，不会替你清理业务数据。因此 20 GB 磁盘仅适合短期的个人实验，长期运行请预留充足空间。

三、部署前置条件

开始部署前，请确认服务器满足：

  • 操作系统为 Debian、Ubuntu 或 RHEL 衍生发行版；
  • 已安装 Docker 与 Docker Compose；
  • 具备sudo权限（后续拉取镜像、绑定 80/443 等低端口都需要）。

如果服务器尚未安装 Docker/Docker Compose/Node.js，可以借助仓库根目录的 configure.sh 完成环境准备——它是npm run prerun实际调用的脚本，会按发行版自动安装git、curl，通过 nvm 安装 Node.js（要求不低于 14.0.0），安装 Docker（要求不低于 20.0.0）、Docker Compose 插件与模板渲染工具gomplate，最后克隆仓库并生成config.env。这也解释了为什么官方推荐路径以npm start一键启动：npm start本身就会先触发prerun钩子完成环境校验与配置文件生成。

四、完整安装步骤（两种方式任选其一）

方式一：使用 npm 一键安装

# 仅克隆 release 分支，减少下载体积 git clone --depth 1 --single-branch --branch release https://github.com/OneUptime/oneuptime.git cd oneuptime # 复制环境配置模板 cp config.example.env config.env # 重要：编辑 config.env 文件，务必替换为随机密钥（见下文"生产就绪检查清单"） # 启动整个平台 npm start

npm start并非简单的docker compose up。对照根目录 package.json 中的 scripts 定义，其完整链路是：

  1. 触发prerun：执行 configure.sh（环境准备 + 生成config.env）与SyncPackageVersions.js（同步各子包版本号）；
  2. 执行export $(grep -v '^#' config.env | xargs)：把config.env中所有非注释行加载为环境变量，供 Docker Compose 插值使用；
  3. 执行docker compose up --remove-orphans -d：后台启动全部容器，--remove-orphans会清理不在当前 Compose 文件定义中的残留容器；
  4. 最后执行npm run status-check：调用 Tests/Scripts/status-check.sh 检查各服务健康状态。

方式二：不使用 npm，直接调用 Docker Compose

若服务器没有 Node.js/npm，或你更习惯直接控制容器编排，可以跳过 npm 完全等价地执行：

# 读取 config.env 中的环境变量并后台启动全部服务 (export $(grep -v '^#' config.env | xargs) && docker compose up --remove-orphans -d) # 若因端口绑定权限不足，改用 sudo 执行 sudo bash -c "(export $(grep -v '^#' config.env | xargs) && docker compose up --remove-orphans -d)"

两种方式的底层命令完全一致，区别仅在于npm start额外做了环境自检与状态检查。首次启动需要拉取多个镜像，耗时取决于网络状况；期间可另开终端用docker compose ps观察各容器是否进入 healthy 状态。

五、访问 OneUptime 并注册账户

部署完成后，OneUptime 应运行在：

http://localhost

打开浏览器访问该地址，注册一个新账户即可开始使用。首任注册的管理员账户会拥有后续创建项目、添加监控的权限。注意此时仍是 HTTP 明文访问，若要对外提供服务并启用 HTTPS，请先完成下一节的 TLS/SSL 配置。

六、配置 TLS/SSL 证书：通过反向代理终止 HTTPS

官方文档明确说明：OneUptime 自身不负责签发或配置 SSL/TLS 证书，证书的申请与终止由部署方自行完成。若需要 HTTPS 访问，标准做法是在 OneUptime 前置一层反向代理：

  1. 使用 Nginx 或 Caddy 作为反向代理；
  2. 使用 Let's Encrypt 申请并续期证书；
  3. 将反向代理指向 OneUptime 服务器；
  4. 更新以下环境变量：
    • 将HTTP_PROTOCOL设为https；
    • 将HOST改为反向代理所在服务器的域名。

这两项配置的作用可从 config.example.env 与 docker-compose.base.yml 中确认：HOST与HTTP_PROTOCOL通过x-common-variables注入到所有服务，平台内部据此生成正确的回调地址、Webhook 地址与页面链接；如果HTTP_PROTOCOL仍为http而前面挂着 HTTPS 代理，会出现"页面已加密但站内链接仍是 http"的混合内容问题。

补充说明：config.example.env中还预留了PROVISION_SSL开关，注释指出当其为true时 OneUptime 可为HOST自动从 Let's Encrypt 申请证书，但要求 80/443 端口可达且域名已解析到本机。这是平台内部（配合LETS_ENCRYPT_ACCOUNT_KEY、LETS_ENCRYPT_NOTIFICATION_EMAIL）的自动化路径；若你选择在外部反向代理上终止 TLS，则保持PROVISION_SSL=false并自行管理证书，两种方式按部署拓扑择一使用。

反向代理场景下的额外调优项

若反向代理会继续向X-Forwarded-For头部追加自身地址，需要同步调整config.env中的TRUSTED_PROXY_HOPS。该变量的语义（见 config.example.env 注释）：它表示 OneUptime 前方有几层"由你自己运行的、会向X-Forwarded-For追加地址的代理"。默认值1对应原生安装（只有 OneUptime 自带的 Nginx 网关）；若前端再有 Nginx、Cloudflare、AWS ALB 等代理，则应递增为2。设置过低会让所有访客看起来都来自代理地址，设置过高则访客可伪造客户端 IP，绕过状态页与公开面板的 IP 白名单和限流。

七、生产就绪检查清单

官方文档明确建议：生产环境优先考虑 Kubernetes 而非 docker-compose 单机部署。仓库中提供了完整的 Helm Chart（见 HelmChart/Public/oneuptime），支持滚动更新、水平伸缩与云原生运维。如果仍坚持使用 docker-compose 承载生产流量，请逐项核对以下清单。

1. SSL/TLS：必须启用 HTTPS

参照上一节，通过反向代理 + Let's Encrypt 为对外域名启用 HTTPS，并将HTTP_PROTOCOL=https、HOST=你的域名写入 config.env。裸 HTTP 下账号密码、探针密钥、Webhook 载荷都会明文传输，属于生产环境不可接受的风险。

2. Secrets：替换全部默认密钥

config.example.env中明确标注了# Secrets - PLEASE CHANGE THESE. Please change these to something random. All of these can be different values.，模板里预置了如下占位密钥，部署前必须替换为足够长的随机字符串（各值可彼此不同）：

密钥变量默认占位值用途
ONEUPTIME_SECRETplease-change-this-to-random-value平台签名/加密主密钥
REGISTER_PROBE_KEYplease-change-this-to-random-value探针注册密钥
DATABASE_PASSWORDplease-change-this-to-random-valuePostgres 数据库密码
CLICKHOUSE_PASSWORDplease-change-this-to-random-valueClickHouse 数据库密码
VALKEY_PASSWORDplease-change-this-to-random-value缓存/队列密码
ENCRYPTION_SECRETplease-change-this-to-random-value数据加密密钥
GLOBAL_PROBE_1_KEY/GLOBAL_PROBE_2_KEYprobe-1-please-change-.../probe-2-please-change-...两个内置探针的认证密钥

这些变量会通过x-common-runtime-variables注入所有运行容器（见 docker-compose.base.yml），任何一个保持默认值都等于把后门敞给扫描器。可用openssl rand -hex 32等工具生成随机串。

3. 备份：定期备份 Postgres 与 ClickHouse

postgres与clickhouse的数据都写在命名卷中，是唯一需要持久化的部分；缓存（Valkey）为无状态服务，可安全跳过。仓库根目录的 backup.sh 提供了现成的每日备份方案：

  • 通过pg_dump --format=custom生成压缩的自定义格式备份文件，文件名形如db-{当月日期}.backup，存放在DATABASE_BACKUP_DIRECTORY（默认/Backups）下，并保留最近 30 天；
  • 执行前需在config.env中正确填写DATABASE_BACKUP_*系列变量（默认DATABASE_BACKUP_HOST=localhost、DATABASE_BACKUP_PORT=5400——该端口正是 docker-compose.yml 中postgres对外映射的5400:5432，专门用于备份访问）；
  • 建议通过 crontab 每天至少执行一次：npm run backup（对应 package.json 中的"backup": "bash backup.sh"）。

对应的恢复脚本为仓库根目录的 restore.sh，其使用DATABASE_RESTORE_*系列变量（默认DATABASE_RESTORE_HOST=host.docker.internal），且DATABASE_RESTORE_FILENAME必须与备份产出的db-*.backup文件名保持一致。

4. 缓存与队列：理解 Valkey 与 REDIS_* 的兼容关系

valkey服务运行Valkey——Redis 7.2 的 BSD 许可分叉，与 Redis 完全兼容线缆协议。这意味着：

  • 平台通过VALKEY_*系列变量（VALKEY_HOST、VALKEY_PORT、VALKEY_DB、VALKEY_USERNAME、VALKEY_PASSWORD等）配置缓存与队列；
  • 任何 Redis 协议服务器都可替代内置的 Valkey 容器——若已有托管的 Redis 服务，只需把VALKEY_HOST指向它；
  • 这些变量在13.0.0 之前名为REDIS_*。从源码看，docker-compose.base.yml 通过VALKEY_HOST: ${VALKEY_HOST:-${REDIS_HOST}}这类回退语法同时兼容新旧变量名；valkey 服务在网络别名中仍响应redis主机名（aliases: [redis]）；且 package.json 中npm run update不会重写config.env。因此老版本遗留的REDIS_*配置无需任何修改即可继续工作，升级不会破坏既有部署。

5. 更新：保持平台与依赖最新

官方每天发布更新，生产环境建议至少每周更新一次。更新命令如下：

git checkout release # 确保处于 release 分支 git pull npm run update

npm run update在 package.json 中的定义是npm run prerun && export $(grep -v '^#' config.env | xargs) && docker compose pull && npm run start——即依次完成环境自检、拉取所有服务的最新镜像（docker compose pull），再走一遍npm start的启动与健康检查流程，实现滚动式的原地升级。

八、日志存储控制：避免磁盘被探针与摄取日志写满

在 Compose 默认配置中，所有服务使用json-file日志驱动，且各容器（见 docker-compose.base.yml）已统一设置了max-size: "1000m"的单文件上限。官方文档特别提醒：探针（probe）与遥测摄取（ingest）容器会产生大量日志，仅靠单文件上限仍不足以防止存储被写满，强烈建议在 Docker 守护进程层面进一步限制日志总量，例如使用local日志驱动并配置max-size/max-file参数，或为 json-file 驱动同时设置max-file。

九、卸载 OneUptime

当不再需要自托管实例时，执行：

npm run down

其底层调用docker compose down --remove-orphans（见 package.json 中"down": "npm run stop"），会停止并删除 OneUptime 创建的所有容器、网络与卷。注意：

  • 它不会删除config.env文件，也不会删除克隆下来的仓库目录；
  • 若需要彻底清除数据，需在确认备份无误后手动删除 compose 命名卷（docker volume rm oneuptime_postgres oneuptime_clickhouse等）；
  • 仓库还提供了交互式脚本 uninstall.sh（bash uninstall.sh），会二次确认后执行docker compose down与docker compose rm，适合需要更完整清理的场景。

十、总结

Docker Compose 是 OneUptime 门槛最低的自托管方案：克隆 release 分支、配置config.env、npm start，三步即可在本机获得完整的开源监控与可观测性平台。但生产使用必须补齐四件事——HTTPS 反向代理、随机密钥、数据库定期备份、每周例行更新；若追求更高的可用性与弹性，则应转向仓库自带的 Helm Chart 走 Kubernetes 部署路线。无论选择哪种方式，config.example.env 中每一条变量的注释、docker-compose.base.yml 中每个服务的定义，都是排障与调优时的第一手资料。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/18 14:02:29

Vaultwarden：轻量级 Bitwarden 兼容服务端实战指南

1. Vaultwarden 是什么：一个被严重低估的 Bitwarden 兼容服务端实现Vaultwarden 这个名字，第一次看到时我下意识以为是 Bitwarden 官方推出的某个新组件——毕竟后缀 “warden” 和 Bitwarden 高度一致，连 logo 都用相似的盾牌钥匙视觉语言。…

作者头像 李华
网站建设 2026/9/18 14:01:38

注意力机制如何赋能街景语义分割？从SE到CBAM实践

简介：面向自动驾驶感知中的街景语义分割任务，提出基于注意力机制的改进方法，聚焦现有模型分割精度不足与参数量大的痛点。文档从问题分析入手，给出残差网络提取特征、空间注意力模块与通道注意力模块并行细化特征图的设计&#xf…

作者头像 李华
网站建设 2026/9/18 14:01:31

Objx 详解：用 Go 优雅读写 map、slice 与 JSON 数据的实用指南

Objx 详解：用 Go 优雅读写 map、slice 与 JSON 数据的实用指南 【免费下载链接】karmada Open, Multi-Cloud, Multi-Cluster Kubernetes Orchestration 项目地址: https://gitcode.com/GitHub_Trending/ka/karmada Objx 是一个专注于简化 map[string]interfa…

作者头像 李华
网站建设 2026/9/18 13:58:16

DNN-GOP3抗噪口语评测：中学生英语发音鲁棒性建模

简介：本资源是一篇聚焦教育智能化落地的学术论文，面向英语教学研究者、语音技术开发者及中高考考试系统建设者，着力解决大规模口语考试中因设备差异、环境噪音与非母语发音特征导致的自动评分不准问题。论文提出两种基于深度神经网络声学模型…

作者头像 李华