OneUptime 自托管部署完全指南：用 Docker Compose 在单台服务器上免费搭建完整监控平台

OneUptime 自托管部署完全指南：用 Docker Compose 在单台服务器上免费搭建完整监控平台

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

本指南以 OneUptime 官方安装文档为主体，讲解如何在一台 Debian、Ubuntu 或 RHEL 系服务器上，使用 Docker Compose 部署一个完全免费、单机自托管的 OneUptime 实例。读完本文，你将掌握从服务器选型、环境变量配置、启动与访问，到 TLS/SSL 终结、生产环境加固、日常更新与卸载的完整闭环，并理解config.env中每个关键参数背后的实现逻辑（含 13.0.0 起 Valkey 取代 Redis 的迁移细节）。

一、部署方式概览：为什么选择 Docker Compose

OneUptime 是一套开源的一体化可观测性平台（监控、状态页、告警、日志与链路追踪等）。官方提供多种部署形态：Docker Compose、Kubernetes（Helm Chart）以及托管云服务。本文对应的官方文档App/FeatureSet/Docs/Content/fa/installation/docker-compose.md（英文原版见 App/FeatureSet/Docs/Content/en/installation/docker-compose.md）所描述的 Docker Compose 方式，适合以下场景：

• 希望数据完全保留在自己服务器上，追求最大控制权与自定义能力；
• 个人、实验或家庭环境（homelab）使用；
• 想先低成本跑起来、后续再平滑迁移到 Kubernetes。

需要明确的是：该方式需要更多技术技能与运维资源，官方在生产环境强烈建议使用 Kubernetes（对应 Helm Chart 位于 HelmChart/Public/oneuptime），Docker Compose 更适合中小规模与自托管控制需求。

二、服务器规格选型

官方文档给出了两档明确的硬件基线，可按使用量与预算选择：

• 推荐档适用于持续监控较多目标、保留较长历史数据的场景；
• 最小档适用于个人、实验用途；官方文档提到甚至有用户将其跑在 Raspberry Pi 上。注意磁盘容量应结合第七节的“日志与磁盘”建议评估，因为 probe 与 ingest 容器会产生大量日志。

三、部署前置条件

开始前请确认服务器具备：

• 运行 Debian、Ubuntu 或 RHEL 衍生版的服务器；
• 已安装 Docker 与 Docker Compose（Compose v2 插件形式docker compose或独立docker-compose均可）。

仓库根目录的 configure.sh 是安装阶段的环境检查脚本，它会在缺少依赖时自动补齐并校验版本：

• 最低 Docker 版本MINIMUM_DOCKER_VERSION="20.0.0"；
• Docker Compose 目标版本DOCKER_COMPOSE_VERSION="2.12.2"；
• 最低 Node.js 版本MINIMUM_NODE_VERSION="14.0.0"；
• 还会下载模板渲染工具 gomplate，用于把Dockerfile.tpl渲染成最终的 Dockerfile。

四、一键安装：clone、配置密钥、启动

官方文档给出的标准安装流程如下：

# 仅克隆 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

其中关键步骤的底层行为如下：

1. git clone --depth 1 --single-branch --branch release：只拉取release分支的最近一次提交，避免把庞大的开发分支全部下载到服务器。
2. cp config.example.env config.env：config.env是 Compose 栈读取的唯一环境变量来源，仓库根目录的 config.example.env 是官方模板，内含全部可调参数与详细注释。
3. 编辑config.env：模板中所有密钥都带please-change-this-to-random-value占位符，必须逐一替换为随机长字符串（详见第七节“密钥”）。
4. npm start：对应 package.json 中的脚本定义：

   "start": "export $(grep -v '^#' config.env | xargs) && docker compose up --remove-orphans -d $npm_config_services && npm run status-check"

   即：读取config.env中所有非注释行导出为环境变量 → 以分离模式启动全部服务（--remove-orphans会自动清理不再被编排文件引用的旧容器）→ 执行status-check检查各服务健康状态。

不依赖 npm 的等价启动方式

如果你不想安装 npm，或服务器上没有 npm，官方文档提供了完全等价的手写命令：

# 读取 config.env 中的环境变量并执行 docker compose up (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.yml 定义了单机版的服务拓扑，各服务通过extends复用 docker-compose.base.yml 中的完整定义：

postgres显式映射了5400:5432，注释说明这是为备份预留的端口——若不需要备份，可注释掉该行以减小攻击面。所有依赖基础存储的服务都通过condition: service_healthy等待postgres、valkey、clickhouse健康检查通过后才启动。

五、访问 OneUptime 与创建首个账号

启动完成后，平台应运行在：

• http://localhost（默认ONEUPTIME_HTTP_PORT=80，见 config.example.env）

首次访问需要注册一个全新账号。自托管实例的注册是完全独立的，与 OneUptime 官方云服务互不相通，所有用户、项目与数据都只存在于你这台服务器上。

六、TLS/SSL 证书配置：OneUptime 不代管证书

官方文档明确强调：OneUptime 不支持自行签发或托管 SSL/TLS 证书，证书必须由你自己解决。这与 config.example.env 中PROVISION_SSL=false的默认值一致——镜像内 Nginx 默认只监听 HTTP。

如果需要 HTTPS，官方给出的标准方案是反向代理 + Let's Encrypt：

1. 部署一个反向代理，如Nginx或Caddy；
2. 使用Let's Encrypt签发证书；
3. 将反向代理指向 OneUptime 服务器；
4. 修改config.env中以下两项设置：
   • HTTP_PROTOCOL=https：让应用内部生成的链接与重定向使用https://前缀；
   • HOST=<你的域名>：改为反向代理所承载的域名，替代默认的localhost。

注意 config.example.env 中还有一组与 TLS 相关的可选参数可供参考（STATUS_PAGE_HTTPS_PORT=443、STATUS_PAGE_CNAME_RECORD、DASHBOARD_CNAME_RECORD），它们用于把状态页/公开仪表盘绑定到自定义域名，此时 OneUptime 会自动通过 Let's Encrypt 为状态页域名签发证书——但主站点的 TLS 仍应由你的反向代理终结。

七、生产环境就绪清单（Production Readiness Checklist）

官方文档的态度很明确：理想情况下不要用 docker-compose 跑生产环境，强烈推荐 Kubernetes。但若你仍决定用它承载生产流量，以下检查项缺一不可：

1. SSL/TLS：必须自行配置

同第六节——在生产环境没有 HTTPS 是不可接受的，证书、自动续期与代理配置全部由你负责。

2. 密钥：替换所有默认占位符

config.example.env中带有默认值的密钥必须全部替换为随机长字符串，包括：

ONEUPTIME_SECRET=please-change-this-to-random-value REGISTER_PROBE_KEY=please-change-this-to-random-value DATABASE_PASSWORD=please-change-this-to-random-value CLICKHOUSE_PASSWORD=please-change-this-to-random-value VALKEY_PASSWORD=please-change-this-to-random-value ENCRYPTION_SECRET=please-change-this-to-random-value GLOBAL_PROBE_1_KEY=probe-1-please-change-this-to-random-value GLOBAL_PROBE_2_KEY=probe-2-please-change-this-to-random-value ONEUPTIME_RUNNER_KEY=please-change-this-to-random-value

这些密钥分别保护数据库、缓存、探针注册、AI Runner 注册与数据加密。尤其注意ONEUPTIME_RUNNER_KEY：它负责认证 AI 代码修复协议并参与签发仓库访问令牌，绝不能保留公开的占位符。从源码看，这些变量会通过 docker-compose.base.yml 的x-common-variables/x-common-runtime-variables锚点注入到各个容器，其中ONEUPTIME_SECRET、ENCRYPTION_SECRET等仅注入后端进程，不会出现在前端env.js响应里。

3. 备份：数据库必须定期备份

需要备份的是两个持久化数据库：

• Postgres：业务数据（用户、项目、监控配置、状态页等），对应卷postgres；
• ClickHouse：遥测数据（日志、链路、指标等），对应卷clickhouse；
• 缓存（Valkey）可安全忽略：它是无状态的（见下节），重启即清空。

仓库提供了开箱即用的备份脚本 backup.sh，它基于pg_dump --format=custom生成压缩的自定义格式备份文件，保留最近 30 天（文件名db-<日号>.backup）。运行前需在config.env中填好DATABASE_BACKUP_*系列变量：

DATABASE_BACKUP_DIRECTORY=/Backups DATABASE_BACKUP_HOST=localhost DATABASE_BACKUP_PORT=5400 DATABASE_BACKUP_NAME=oneuptimedb DATABASE_BACKUP_USERNAME=postgres DATABASE_BACKUP_PASSWORD=${DATABASE_PASSWORD}

注意DATABASE_BACKUP_PORT=5400正好对应docker-compose.yml中 postgres 暴露的备份端口。恢复则使用根目录的 restore.sh（对应DATABASE_RESTORE_*变量，默认连接host.docker.internal）。ClickHouse 的备份与运维细节可参考 Clickhouse/Docs/ClickhouseOps.md。

4. 缓存与队列：Valkey（原 Redis）的完整说明

这是自 13.0.0 起最重要的配置变化，也是官方文档花费篇幅最多的部分：

• config.env中的valkey服务运行的是Valkey——Redis 7.2 的 BSD 许可分支，兼容 Redis 线协议。任何支持 Redis 协议的服务器都能用：如果你更倾向于托管 Redis，只需把VALKEY_HOST指向它；
• 所有相关配置统一使用VALKEY_*前缀（VALKEY_HOST、VALKEY_PORT、VALKEY_DB、VALKEY_USERNAME、VALKEY_PASSWORD、VALKEY_IP_FAMILY、VALKEY_TLS_CA、VALKEY_TLS_SENTINEL_MODE等）；
• 兼容性保证：这些参数在 13.0.0 之前叫REDIS_*，旧名称至今仍会被读取（详见 App/FeatureSet/Docs/Content/en/installation/upgrading.md 的 12→13 升级章节）；npm run update不会覆写旧配置；容器仍同时响应redis与valkey两个主机名。因此旧版config.env无需任何手工修改即可升级。

源码层面可以印证这一兼容设计：在 docker-compose.base.yml 中，valkey 服务定义如下：

valkey: image: valkey/valkey:9.1-alpine command: valkey-server --requirepass "${VALKEY_PASSWORD:-${REDIS_PASSWORD}}" --save "" --appendonly no

• 密码读取使用${VALKEY_PASSWORD:-${REDIS_PASSWORD}}的默认值回退语法，REDIS_*旧变量依然生效；
• --save "" --appendonly no表示完全关闭持久化：缓存数据不落盘，容器重建后冷启动。因此 BullMQ 队列中等待中/延迟/退避中的任务会丢失，但可重复执行与 cron 类任务会在重连后自动重新注册——升级时建议选择业务低峰期；
• 同一文件中还维护了REDIS_*的“弃用镜像”变量（REDIS_HOST: ${VALKEY_HOST:-${REDIS_HOST}}），目的是让APP_TAG回退到旧镜像时（旧镜像只认REDIS_*）依然能工作。

5. 更新频率

官方每天发布更新，生产环境建议至少每周更新一次，以持续获得安全修复与功能演进（更新流程见下一节）。

八、日常更新 OneUptime

官方标准的更新流程：

git checkout release # 确保处于 release 分支 git pull # 拉取最新代码与编排文件 npm run update # 执行更新

npm run update对应 package.json 中的组合脚本：

"update": "npm run prerun && export $(grep -v '^#' config.env | xargs) && docker compose pull && npm run start"

它的执行链路是：prerun（同步各子包版本号 + 执行configure.sh补齐环境）→ 拉取最新镜像 →npm start（带--remove-orphans重新拉起整套栈）。--remove-orphans很重要：它负责移除旧的redis容器，若手工执行docker compose up而不带该参数，旧容器会与新的valkey容器同时应答redis主机名，导致连接随机落到过期容器上。

两个升级期间的易错点（详见 upgrading.md）：

• 大版本必须逐级升级（如 11 → 12 → 13），不可跨大版本跳跃；小版本可以跳级；
• 升级前务必完成备份并验证可恢复。12 → 13 升级中缓存会重启一次，属于预期行为；若你手工管理docker-compose.override.yml且里面设置了缓存变量，记得把REDIS_*重命名为VALKEY_*，因为应用现在优先读取VALKEY_HOST。

九、日志与磁盘：限制 probe/ingest 容器的日志体积

官方文档特别提醒：Docker 编排中使用了local 日志驱动（docker-compose.base.yml中为各服务配置的logging配置），而 OneUptime 的probe（探针）与 ingest（遥测接收）容器会产生大量日志。若不加以限制，日志会逐步占满磁盘，因此必须对 Docker 日志存储设上限。常见做法包括：

• 在daemon.json中为 local 驱动配置max-size/max-file轮转；
• 或改用json-file/journald驱动并配置轮转策略。

具体参数请查阅 Docker 官方关于 local 日志驱动的文档（在 Docker 配置章节下）。生产环境还应关注 config.example.env 中的LOG_LEVEL=ERROR——日志级别可取值ERROR、WARN、INFO、DEBUG，默认ERROR已是最小化输出，排查问题时才应临时调高，且 DEBUG 输出应视为敏感信息对待。

十、卸载 OneUptime

npm run down

它等价于npm run stop，即docker compose down --remove-orphans。此命令会：

• 停止并删除 OneUptime 创建的所有容器；
• 删除其网络；
• 删除其卷（postgres、clickhouse卷中的数据一并销毁）。

不会删除config.env文件或已克隆的仓库，因此执行前若仍需保留数据，务必先完成第七节所述的备份。彻底卸载还可参考根目录的 uninstall.sh。

十一、部署相关文件速查

以下是本指南涉及的关键仓库文件，可对照深入阅读：

结语

通过 Docker Compose，你可以在十几分钟内在一台自有服务器上跑起一整套免费的 OneUptime 监控与可观测性平台。掌握本文的规格选型、密钥管理、TLS 终结、Valkey 兼容语义、备份与更新节奏，即可让这套自托管实例稳定运行并安全承载生产流量；当规模增长超出单机承载能力时，官方提供的 Helm Chart 路线（HelmChart/Public/oneuptime）可以作为平滑迁移的下一站。

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