OneUptime 免费自托管基于 Docker Compose 的单机部署完整实战指南【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本指南以官方文档 App/FeatureSet/Docs/Content/en/installation/docker-compose.md 为主体结合仓库内的 config.example.env、docker-compose.yml、docker-compose.base.yml 以及备份/恢复脚本等源码完整讲解如何在 Debian、Ubuntu、RHEL 系服务器上用 Docker Compose 部署一套免费的 OneUptime 单机实例。读完你将掌握系统资源配置与前置条件、三步快速部署、config.env全部关键参数、TLS/SSL 证书接入方式、生产就绪检查清单、日常升级与彻底卸载并能从源码层面理解这套编排中每个服务Postgres、ClickHouse、Valkey、Probe、Runner、Ingress的实际职责与配置原理。一、部署方式总览何时选择 Docker ComposeOneUptime 是一套完整的开源监控与可观测性平台仓库根目录 README.md 将其描述为 Complete open-source monitoring and observability platform。官方提供了多种部署路径其中Docker Compose 单机部署适合在自己的服务器上托管一套实例拥有更强的控制力与自定义空间但对运维技能和资源有一定要求Kubernetes Helm官方强烈建议生产环境使用 K8s仓库内提供了现成的 Helm ChartHelmChart/Public/oneuptime。本文聚焦前者。官方文档明确指出理想情况下不要用 Docker Compose 直接上生产生产首选 Kubernetes若坚持使用 Compose 部署生产必须仔细核对下文生产就绪检查清单中的每一条。二、系统资源配置建议部署前先根据预算与用途选定服务器规格。官方文档给出的两档参考如下档位RAMCPU磁盘系统推荐配置16 GB8 核400 GBUbuntu 22.04 Docker / Docker ComposeHomelab / 最低配置8 GB4 核20 GBDocker / Docker Compose家庭实验室场景下官方提到部分用户甚至把实例跑在 Raspberry Pi 上。需要注意本仓库的 configure.sh 在安装阶段会做环境自检其中对 Docker 版本有最低要求脚本头部定义MINIMUM_DOCKER_VERSION20.0.0因此请确保 Docker 版本不低于 20.0.0且已安装 Docker Compose v2 插件。三、部署前置条件一台运行Debian、Ubuntu 或 RHEL 衍生版的服务器服务器上已安装Docker 与 Docker Compose服务器可访问外网首次启动需要拉取镜像若部署在隔离网络可参考config.example.env中的LATEST_RELEASE_CHECK_URL与DISABLE_UPDATE_CHECK选项做离线化处理。四、快速开始三步完成部署官方推荐用 npm 脚本完成整个流程npm 脚本内部其实也是调用 docker compose见下文源码解析。执行以下命令# 1. 克隆本仓库的 release 分支浅克隆仅取最新提交 git clone --depth 1 --single-branch --branch release https://github.com/OneUptime/oneuptime.git cd oneuptime # 2. 复制环境配置模板 cp config.example.env config.env # 3. 重要编辑 config.env 文件务必填入随机生成的密钥见下一节 npm start如果你不想使用 npm或未安装 npm可以直接执行等价的 Compose 命令# 从 config.env 读取环境变量并后台启动全部服务 (export $(grep -v ^# config.env | xargs) docker compose up --remove-orphans -d) # 若因端口绑定权限不足如 80/443 端口使用 sudo 执行 sudo bash -c (export $(grep -v ^# config.env | xargs) docker compose up --remove-orphans -d)源码视角npm start到底做了什么查看仓库根目录 package.json 的 scripts 定义npm start实际展开为export $(grep -v ^# config.env | xargs) docker compose up --remove-orphans -d $npm_config_services npm run status-check即三个动作用grep -v ^#过滤掉config.env中的注释行再通过xargs将其余KEYVALUE全部导出为环境变量执行docker compose up --remove-orphans -d后台拉起全部服务可用npm start --servicesxxx形式只启动指定服务运行npm run status-check做健康探测。status-check对应 Tests/Scripts/status-check.sh脚本会依次探测 App 首页、/status、/status/ready、Dashboard、Admin Dashboard、Public Dashboard 等端点并提示首次启动需要等待约 5~10 分钟用于等待数据库迁移完成、TLS 证书签发等服务收敛。因此npm start之后如果立即访问不到页面属于正常现象。五、config.env关键配置项详解必读复制模板后第一件事就是替换默认密钥。config.example.env中所有please-change-this-to-random-value占位值都必须替换为随机长字符串否则实例存在严重安全风险。5.1 必须修改的密钥类配置环境变量用途默认值必须替换ONEUPTIME_SECRET平台主密钥please-change-this-to-random-valueREGISTER_PROBE_KEY探针注册共享密钥please-change-this-to-random-valueDATABASE_PASSWORDPostgres 数据库密码please-change-this-to-random-valueCLICKHOUSE_PASSWORDClickHouse 数据库密码please-change-this-to-random-valueVALKEY_PASSWORDValkey 缓存/队列密码please-change-this-to-random-valueENCRYPTION_SECRET数据加密密钥please-change-this-to-random-valueGLOBAL_PROBE_1_KEY/GLOBAL_PROBE_2_KEY两个内置全局探针的密钥probe-1/2-please-change-this-to-random-valueONEUPTIME_RUNNER_KEYRunnerAI 修复任务执行器密钥please-change-this-to-random-value从 docker-compose.base.yml 可以看到这些密钥会通过x-common-runtime-variables注入到 app、runner、probe 等容器的环境变量中贯穿所有服务。5.2 域名与端口配置# 服务器对外域名或 IP。部署时改为你的真实域名。 HOSTlocalhost # 是否由 OneUptime 自动申请 Lets Encrypt 证书默认关闭见TLS/SSL一节 PROVISION_SSLfalse # 对外 HTTP 端口默认 80。映射到 ingress 容器的 7849 端口。 ONEUPTIME_HTTP_PORT80 # 对外 HTTPS 端口默认 443。映射到 ingress 容器的 7850 端口状态页自定义域名场景使用。 STATUS_PAGE_HTTPS_PORT443对应关系见 docker-compose.yml 中 ingress 服务的ports声明${ONEUPTIME_HTTP_PORT}:7849与${STATUS_PAGE_HTTPS_PORT}:7850。5.3 反向代理信任层级重要安全参数# 位于 OneUptime 前面的、会向 X-Forwarded-For 追加内容的代理数量。 TRUSTED_PROXY_HOPS1config.example.env对它有详细注释IP 白名单状态页、公共仪表盘与 IP 限流都依赖这个值来判断真实客户端地址。1是标准安装的正确值OneUptime 自带 nginx 网关没有其他代理如果你在前面加了自己的 HTTP 代理Cloudflare、AWS ALB、自建 nginx 或 ingress controller应设为2每多一层代理加10表示完全忽略X-Forwarded-For仅当 OneUptime 直接暴露、前方没有任何代理时才设置。设置过低会导致所有访客看起来都像你的代理 IP设置过高则访客可自行伪造来源地址使白名单形同虚设。5.4 数据库配置Postgres业务主数据库镜像postgres:15DATABASE_PORT5432 DATABASE_USERNAMEpostgres DATABASE_NAMEoneuptimedb DATABASE_HOSTpostgres如需对接托管 Postgres可配置DATABASE_SSL_CA、DATABASE_SSL_KEY、DATABASE_SSL_CERT、DATABASE_SSL_REJECT_UNAUTHORIZED等 SSL 连接参数按供应商要求只填需要的项。ClickHouse遥测分析数据库镜像clickhouse/clickhouse-server:26.7CLICKHOUSE_USERdefault CLICKHOUSE_DATABASEoneuptime CLICKHOUSE_HOSTclickhouse CLICKHOUSE_PORT8123 # 每个容器的连接池上限ingest 池为空时继承该值 CLICKHOUSE_MAX_OPEN_CONNECTIONS100 CLICKHOUSE_INGEST_MAX_OPEN_CONNECTIONS5.5 缓存与队列Valkey 及 REDIS 兼容命名版本 13.0.0 起VALKEY_HOSTvalkey VALKEY_PORT6379 VALKEY_DB0 VALKEY_USERNAMEdefault VALKEY_PASSWORD请替换为随机值 VALKEY_IP_FAMILY VALKEY_TLS_CA VALKEY_TLS_SENTINEL_MODEfalse官方文档特别说明缓存/队列服务运行Valkey——Redis 7.2 的 BSD 许可证分支任何遵循 Redis 协议的服务器都能工作若你更倾向托管 Redis只需把VALKEY_HOST指向它。13.0.0 之前这些配置项名为REDIS_*旧名称依然会被读取docker-compose.base.yml中通过${VALKEY_HOST:-${REDIS_HOST}}形式做回退并保留REDIS_*作为镜像兼容镜像变量容器在 compose 网络内依然应答redis这个主机名docker-compose.base.yml中 valkey 服务的networks.oneuptime.aliases含redisnpm run update不会改写这些旧变量因此旧版config.env升级后无需任何修改。另外注意 docker-compose.base.yml 中 valkey 服务以--save --appendonly no启动即不开启持久化——这正是官方把缓存称为无状态、可放心忽略的原因它只承担缓存与任务队列数据全部落库在 Postgres / ClickHouse。5.6 其他常用开关节选变量默认值说明ENVIRONMENTproduction可选test / production / development / ciAPP_TAGrelease从 Docker Hub 拉取的镜像标签IS_ENTERPRISE_EDITIONfalse社区版保持 falseCOMPOSE_PROJECT_NAMEoneuptimeCompose 项目名用于容器命名前缀BILLING_ENABLEDfalse自托管默认关闭计费LOG_LEVELERROR可选ERROR / WARN / INFO / DEBUGDEBUG 输出敏感仅排障时开启DISABLE_UPDATE_CHECKfalse每日检查 GitHub 最新版本以提示升级置 true 则完全不发外呼请求LATEST_RELEASE_CHECK_URL空指向内部镜像源以替代 GitHub 检查DISABLE_TELEMETRY_FOR_APP/PROBE/INGRESS/RUNNERtrueCompose 部署默认关闭各服务遥测ALLOW_PRIVATE_NETWORK_WEBHOOKSfalse自托管 Webhook 出口策略默认禁止发往内网/回环地址六、Docker Compose 服务架构源码级部署启动后实际拉起的是 docker-compose.yml 定义的服务其底层服务细节全部extends自 docker-compose.base.yml。主要服务如下服务镜像职责postgrespostgres:15业务主数据库数据卷postgresclickhouseclickhouse/clickhouse-server:26.7遥测/分析数据库数据卷clickhousevalkeyvalkey/valkey:9.1-alpine缓存与 BullMQ 任务队列无持久化apponeuptime/app:${APP_TAG}API、后台 Worker、遥测摄取单容器模式同时处理全部后台任务probe-1/probe-2oneuptime/probe:${APP_TAG}内置全局探针负责主动监控HTTP、合成浏览器、SNMP 等runneroneuptime/runner:${APP_TAG}执行 AI 代码修复等 Runner 任务ingressoneuptime/nginx:${APP_TAG}自带的 nginx 网关对外暴露 80/443 端口fluentd/fluent-bit-日志采集管道test-server/e2e-仅测试环境使用几个值得注意的实现细节健康检查与依赖顺序docker-compose.yml 中app、probe-1、runner、ingress都通过x-common-depends-on声明了依赖要求postgres、valkey、clickhouse三个基础设施服务先通过健康检查service_healthy条件再启动业务容器。探针安全加固probe-1/probe-2以network_mode: host运行cap_drop: ALL后仅保留CHOWN/DAC_OVERRIDE/KILL/NET_RAW/SETGID/SETUID能力并挂载 Probe/seccomp_profile.json seccomp 配置与no-new-privileges:true用于安全运行浏览器合成监控Playwright/Firefox与自定义代码监控。ClickHouse 单节点集群compose 通过挂载 Clickhouse/config.d/cluster.xml嵌入式 Keeper 单节点oneuptime集群、Clickhouse/users.d/distributed-insert-tuning.xml批量分发插入调优、Clickhouse/config.d/system-log-ttl.xml系统日志 TTL防止查询日志无限膨胀占满磁盘来让单机也能运行 ReplicatedMergeTree 分析表。Postgres 备份端口docker-compose.yml 将 Postgres 的5400:5432端口映射到宿主机专门用于执行备份/恢复脚本官方注释建议不需要备份时注释掉该行以提高安全性。七、访问 OneUptime启动并等待几分钟迁移与初始化完成后在浏览器访问http://localhost首次使用需要注册一个新账户系统会引导创建项目与首个监控目标。如果你把HOST改成了域名则访问http://你的域名。八、TLS/SSL 证书配置官方文档明确指出OneUptime 自身不负责 SSL/TLS 证书的托管证书需要你自己解决。推荐的接入方式是使用反向代理使用 Nginx 或 Caddy 等反向代理用 Lets Encrypt 签发证书将反向代理指向 OneUptime 服务器修改config.env中两项配置将HTTP_PROTOCOL设为https将HOST改为反向代理所在的域名。改完后需要重启服务使配置生效见升级与维护一节的更新命令。补充说明当前仓库的 config.example.env 中保留了PROVISION_SSL开关默认false其注释描述当PROVISION_SSLtrue时 OneUptime 可以为HOST自动签发 Lets Encrypt 证书前提是 80/443 端口可达且域名已解析到本机。也就是说新版本已具备自动签发能力但该文档所描述、且生产上更稳妥的方案仍是外部反向代理终止 TLS。使用反向代理时保持PROVISION_SSLfalse即可。九、生产就绪检查清单官方文档强调理想情况下不要用 Docker Compose 直接上生产强烈建议使用 Kubernetes仓库已提供 HelmChart/Public/oneuptime 与相关 Helm 文档。如果仍要基于 Compose 跑生产请逐条核对9.1 SSL/TLS必须自行配置证书方式见上一节。没有 HTTPS 的监控平台会暴露凭据与监控数据。9.2 密钥Secretsconfig.env中带有默认值/占位值的密钥必须全部替换为随机长字符串见 5.1 表格尤其是ONEUPTIME_SECRET、ENCRYPTION_SECRET、各数据库密码与探针密钥。9.3 备份定期备份Postgres 与 ClickHouse两个数据库Valkey 缓存是无状态的可以安全忽略。仓库自带备份脚本 backup.sh 与恢复脚本 restore.sh。backup.sh使用pg_dump --formatcustom生成压缩的db-日期.backup归档默认保留最近 30 天需要先正确设置config.env中的DATABASE_BACKUP_*系列变量含DATABASE_BACKUP_DIRECTORY、DATABASE_BACKUP_HOST、DATABASE_BACKUP_PORT、DATABASE_BACKUP_NAME、DATABASE_BACKUP_USERNAME、DATABASE_BACKUP_PASSWORD并在备份目录挂载docker-compose.yml中映射的宿主机端口5400。恢复脚本restore.sh使用pg_restore --clean --if-exists执行破坏性恢复会先 DROP 目标库中所有同名对象再重建执行前务必确认DATABASE_RESTORE_*变量指向正确并先停止所有数据库容器脚本会打印警告并要求确认可用DATABASE_RESTORE_ASSUME_YES1跳过确认以支持无人值守。9.4 缓存与队列valkey服务运行 ValkeyRedis 7.2 的 BSD 许可证分支由VALKEY_*配置项控制任何 Redis 协议服务器均可替换只需将VALKEY_HOST指向托管 Redis。REDIS_*旧名称仍然有效见 5.5 节。9.5 更新频率OneUptime 几乎每天发布更新生产环境建议至少每周更新一次。十、升级与维护10.1 常规更新git checkout release # 确保在 release 分支上 git pull npm run update源码视角npm run update在 package.json 中展开为npm run prerun ... docker compose pull npm run start即先运行prerun同步包版本并执行 configure.sh 环境自检然后拉取最新镜像并重新up。因为config.env不会被改写你的密钥与自定义配置在升级后原样保留。10.2 磁盘与日志管理重要官方文档特别提醒compose 部署使用local logging driver而 OneUptime尤其是 probe 与 ingest 容器会产生大量日志。必须限制 Docker 的日志存储上限否则磁盘会被日志占满导致故障。仓库内所有服务默认使用了json-file驱动并设置max-size: 1000m见 docker-compose.base.yml 各服务logging段。如果自行调整或使用默认配置请务必参考 Docker 官方文档关于local/json-file日志驱动轮转max-size、max-file的说明进行设置并配合npm run save-logs/npm run logs/npm run follow-logs分别导出、查看、跟踪容器日志做排障。10.3 常用运维命令源码可查命令作用npm run ps查看容器状态docker compose psnpm run logs/npm run follow-logs查看 / 跟踪最近 100 行日志npm run save-logs导出最近 100000 行日志到logs.txtnpm run stop停止并移除容器docker compose down --remove-orphansnpm run pull拉取最新镜像npm run backup执行 backup.sh 数据库备份十一、卸载 OneUptimenpm run down源码视角npm run down实际就是npm run stop即执行docker compose down --remove-orphans停止并移除全部容器与网络。官方文档声明它不会删除config.env文件也不会删除克隆下来的仓库。一个值得注意的细节npm run down并未附加-v参数因此 Postgres 与 ClickHouse 的数据卷默认会保留。如果你确实需要连数据一起清除例如彻底重装需要手动追加执行docker compose down -v会永久删除数据库数据请先确认已备份。十二、注意事项与延伸阅读首次启动较慢迁移、初始化与证书流程可能需要 5~10 分钟期间访问异常属正常现象可用 Tests/Scripts/status-check.sh 持续探测就绪状态。资源规划服务器规格直接影响可用监控数量与遥测吞吐参考同目录的 sizing.md 按实际用量评估。版本升级路径跨版本升级细节见 upgrading.md。本地开发部署如需在本机跑开发环境参考 local-development.md。生产级部署强烈建议改用 Kubernetes Helm仓库内 HelmChart/Public/oneuptime 提供了完整 Chart 及 HelmChart/Docs 文档Helm 路径下还支持将 ClickHouse 与 Postgres 替换为托管实例并可通过telemetryWriter.enabled拆分遥测写入层对应config.example.env中的TELEMETRY_WRITER_URL等参数。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OneUptime 免费自托管基于 Docker Compose 的单机部署完整实战指南【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本指南以官方文档 App/FeatureSet/Docs/Content/en/installation/docker-compose.md 为主体结合仓库内的 config.example.env、docker-compose.yml、docker-compose.base.yml 以及备份/恢复脚本等源码完整讲解如何在 Debian、Ubuntu、RHEL 系服务器上用 Docker Compose 部署一套免费的 OneUptime 单机实例。读完你将掌握系统资源配置与前置条件、三步快速部署、config.env全部关键参数、TLS/SSL 证书接入方式、生产就绪检查清单、日常升级与彻底卸载并能从源码层面理解这套编排中每个服务Postgres、ClickHouse、Valkey、Probe、Runner、Ingress的实际职责与配置原理。一、部署方式总览何时选择 Docker ComposeOneUptime 是一套完整的开源监控与可观测性平台仓库根目录 README.md 将其描述为 Complete open-source monitoring and observability platform。官方提供了多种部署路径其中Docker Compose 单机部署适合在自己的服务器上托管一套实例拥有更强的控制力与自定义空间但对运维技能和资源有一定要求Kubernetes Helm官方强烈建议生产环境使用 K8s仓库内提供了现成的 Helm ChartHelmChart/Public/oneuptime。本文聚焦前者。官方文档明确指出理想情况下不要用 Docker Compose 直接上生产生产首选 Kubernetes若坚持使用 Compose 部署生产必须仔细核对下文生产就绪检查清单中的每一条。二、系统资源配置建议部署前先根据预算与用途选定服务器规格。官方文档给出的两档参考如下档位RAMCPU磁盘系统推荐配置16 GB8 核400 GBUbuntu 22.04 Docker / Docker ComposeHomelab / 最低配置8 GB4 核20 GBDocker / Docker Compose家庭实验室场景下官方提到部分用户甚至把实例跑在 Raspberry Pi 上。需要注意本仓库的 configure.sh 在安装阶段会做环境自检其中对 Docker 版本有最低要求脚本头部定义MINIMUM_DOCKER_VERSION20.0.0因此请确保 Docker 版本不低于 20.0.0且已安装 Docker Compose v2 插件。三、部署前置条件一台运行Debian、Ubuntu 或 RHEL 衍生版的服务器服务器上已安装Docker 与 Docker Compose服务器可访问外网首次启动需要拉取镜像若部署在隔离网络可参考config.example.env中的LATEST_RELEASE_CHECK_URL与DISABLE_UPDATE_CHECK选项做离线化处理。四、快速开始三步完成部署官方推荐用 npm 脚本完成整个流程npm 脚本内部其实也是调用 docker compose见下文源码解析。执行以下命令# 1. 克隆本仓库的 release 分支浅克隆仅取最新提交 git clone --depth 1 --single-branch --branch release https://github.com/OneUptime/oneuptime.git cd oneuptime # 2. 复制环境配置模板 cp config.example.env config.env # 3. 重要编辑 config.env 文件务必填入随机生成的密钥见下一节 npm start如果你不想使用 npm或未安装 npm可以直接执行等价的 Compose 命令# 从 config.env 读取环境变量并后台启动全部服务 (export $(grep -v ^# config.env | xargs) docker compose up --remove-orphans -d) # 若因端口绑定权限不足如 80/443 端口使用 sudo 执行 sudo bash -c (export $(grep -v ^# config.env | xargs) docker compose up --remove-orphans -d)源码视角npm start到底做了什么查看仓库根目录 package.json 的 scripts 定义npm start实际展开为export $(grep -v ^# config.env | xargs) docker compose up --remove-orphans -d $npm_config_services npm run status-check即三个动作用grep -v ^#过滤掉config.env中的注释行再通过xargs将其余KEYVALUE全部导出为环境变量执行docker compose up --remove-orphans -d后台拉起全部服务可用npm start --servicesxxx形式只启动指定服务运行npm run status-check做健康探测。status-check对应 Tests/Scripts/status-check.sh脚本会依次探测 App 首页、/status、/status/ready、Dashboard、Admin Dashboard、Public Dashboard 等端点并提示首次启动需要等待约 5~10 分钟用于等待数据库迁移完成、TLS 证书签发等服务收敛。因此npm start之后如果立即访问不到页面属于正常现象。五、config.env关键配置项详解必读复制模板后第一件事就是替换默认密钥。config.example.env中所有please-change-this-to-random-value占位值都必须替换为随机长字符串否则实例存在严重安全风险。5.1 必须修改的密钥类配置环境变量用途默认值必须替换ONEUPTIME_SECRET平台主密钥please-change-this-to-random-valueREGISTER_PROBE_KEY探针注册共享密钥please-change-this-to-random-valueDATABASE_PASSWORDPostgres 数据库密码please-change-this-to-random-valueCLICKHOUSE_PASSWORDClickHouse 数据库密码please-change-this-to-random-valueVALKEY_PASSWORDValkey 缓存/队列密码please-change-this-to-random-valueENCRYPTION_SECRET数据加密密钥please-change-this-to-random-valueGLOBAL_PROBE_1_KEY/GLOBAL_PROBE_2_KEY两个内置全局探针的密钥probe-1/2-please-change-this-to-random-valueONEUPTIME_RUNNER_KEYRunnerAI 修复任务执行器密钥please-change-this-to-random-value从 docker-compose.base.yml 可以看到这些密钥会通过x-common-runtime-variables注入到 app、runner、probe 等容器的环境变量中贯穿所有服务。5.2 域名与端口配置# 服务器对外域名或 IP。部署时改为你的真实域名。 HOSTlocalhost # 是否由 OneUptime 自动申请 Lets Encrypt 证书默认关闭见TLS/SSL一节 PROVISION_SSLfalse # 对外 HTTP 端口默认 80。映射到 ingress 容器的 7849 端口。 ONEUPTIME_HTTP_PORT80 # 对外 HTTPS 端口默认 443。映射到 ingress 容器的 7850 端口状态页自定义域名场景使用。 STATUS_PAGE_HTTPS_PORT443对应关系见 docker-compose.yml 中 ingress 服务的ports声明${ONEUPTIME_HTTP_PORT}:7849与${STATUS_PAGE_HTTPS_PORT}:7850。5.3 反向代理信任层级重要安全参数# 位于 OneUptime 前面的、会向 X-Forwarded-For 追加内容的代理数量。 TRUSTED_PROXY_HOPS1config.example.env对它有详细注释IP 白名单状态页、公共仪表盘与 IP 限流都依赖这个值来判断真实客户端地址。1是标准安装的正确值OneUptime 自带 nginx 网关没有其他代理如果你在前面加了自己的 HTTP 代理Cloudflare、AWS ALB、自建 nginx 或 ingress controller应设为2每多一层代理加10表示完全忽略X-Forwarded-For仅当 OneUptime 直接暴露、前方没有任何代理时才设置。设置过低会导致所有访客看起来都像你的代理 IP设置过高则访客可自行伪造来源地址使白名单形同虚设。5.4 数据库配置Postgres业务主数据库镜像postgres:15DATABASE_PORT5432 DATABASE_USERNAMEpostgres DATABASE_NAMEoneuptimedb DATABASE_HOSTpostgres如需对接托管 Postgres可配置DATABASE_SSL_CA、DATABASE_SSL_KEY、DATABASE_SSL_CERT、DATABASE_SSL_REJECT_UNAUTHORIZED等 SSL 连接参数按供应商要求只填需要的项。ClickHouse遥测分析数据库镜像clickhouse/clickhouse-server:26.7CLICKHOUSE_USERdefault CLICKHOUSE_DATABASEoneuptime CLICKHOUSE_HOSTclickhouse CLICKHOUSE_PORT8123 # 每个容器的连接池上限ingest 池为空时继承该值 CLICKHOUSE_MAX_OPEN_CONNECTIONS100 CLICKHOUSE_INGEST_MAX_OPEN_CONNECTIONS5.5 缓存与队列Valkey 及 REDIS 兼容命名版本 13.0.0 起VALKEY_HOSTvalkey VALKEY_PORT6379 VALKEY_DB0 VALKEY_USERNAMEdefault VALKEY_PASSWORD请替换为随机值 VALKEY_IP_FAMILY VALKEY_TLS_CA VALKEY_TLS_SENTINEL_MODEfalse官方文档特别说明缓存/队列服务运行Valkey——Redis 7.2 的 BSD 许可证分支任何遵循 Redis 协议的服务器都能工作若你更倾向托管 Redis只需把VALKEY_HOST指向它。13.0.0 之前这些配置项名为REDIS_*旧名称依然会被读取docker-compose.base.yml中通过${VALKEY_HOST:-${REDIS_HOST}}形式做回退并保留REDIS_*作为镜像兼容镜像变量容器在 compose 网络内依然应答redis这个主机名docker-compose.base.yml中 valkey 服务的networks.oneuptime.aliases含redisnpm run update不会改写这些旧变量因此旧版config.env升级后无需任何修改。另外注意 docker-compose.base.yml 中 valkey 服务以--save --appendonly no启动即不开启持久化——这正是官方把缓存称为无状态、可放心忽略的原因它只承担缓存与任务队列数据全部落库在 Postgres / ClickHouse。5.6 其他常用开关节选变量默认值说明ENVIRONMENTproduction可选test / production / development / ciAPP_TAGrelease从 Docker Hub 拉取的镜像标签IS_ENTERPRISE_EDITIONfalse社区版保持 falseCOMPOSE_PROJECT_NAMEoneuptimeCompose 项目名用于容器命名前缀BILLING_ENABLEDfalse自托管默认关闭计费LOG_LEVELERROR可选ERROR / WARN / INFO / DEBUGDEBUG 输出敏感仅排障时开启DISABLE_UPDATE_CHECKfalse每日检查 GitHub 最新版本以提示升级置 true 则完全不发外呼请求LATEST_RELEASE_CHECK_URL空指向内部镜像源以替代 GitHub 检查DISABLE_TELEMETRY_FOR_APP/PROBE/INGRESS/RUNNERtrueCompose 部署默认关闭各服务遥测ALLOW_PRIVATE_NETWORK_WEBHOOKSfalse自托管 Webhook 出口策略默认禁止发往内网/回环地址六、Docker Compose 服务架构源码级部署启动后实际拉起的是 docker-compose.yml 定义的服务其底层服务细节全部extends自 docker-compose.base.yml。主要服务如下服务镜像职责postgrespostgres:15业务主数据库数据卷postgresclickhouseclickhouse/clickhouse-server:26.7遥测/分析数据库数据卷clickhousevalkeyvalkey/valkey:9.1-alpine缓存与 BullMQ 任务队列无持久化apponeuptime/app:${APP_TAG}API、后台 Worker、遥测摄取单容器模式同时处理全部后台任务probe-1/probe-2oneuptime/probe:${APP_TAG}内置全局探针负责主动监控HTTP、合成浏览器、SNMP 等runneroneuptime/runner:${APP_TAG}执行 AI 代码修复等 Runner 任务ingressoneuptime/nginx:${APP_TAG}自带的 nginx 网关对外暴露 80/443 端口fluentd/fluent-bit-日志采集管道test-server/e2e-仅测试环境使用几个值得注意的实现细节健康检查与依赖顺序docker-compose.yml 中app、probe-1、runner、ingress都通过x-common-depends-on声明了依赖要求postgres、valkey、clickhouse三个基础设施服务先通过健康检查service_healthy条件再启动业务容器。探针安全加固probe-1/probe-2以network_mode: host运行cap_drop: ALL后仅保留CHOWN/DAC_OVERRIDE/KILL/NET_RAW/SETGID/SETUID能力并挂载 Probe/seccomp_profile.json seccomp 配置与no-new-privileges:true用于安全运行浏览器合成监控Playwright/Firefox与自定义代码监控。ClickHouse 单节点集群compose 通过挂载 Clickhouse/config.d/cluster.xml嵌入式 Keeper 单节点oneuptime集群、Clickhouse/users.d/distributed-insert-tuning.xml批量分发插入调优、Clickhouse/config.d/system-log-ttl.xml系统日志 TTL防止查询日志无限膨胀占满磁盘来让单机也能运行 ReplicatedMergeTree 分析表。Postgres 备份端口docker-compose.yml 将 Postgres 的5400:5432端口映射到宿主机专门用于执行备份/恢复脚本官方注释建议不需要备份时注释掉该行以提高安全性。七、访问 OneUptime启动并等待几分钟迁移与初始化完成后在浏览器访问http://localhost首次使用需要注册一个新账户系统会引导创建项目与首个监控目标。如果你把HOST改成了域名则访问http://你的域名。八、TLS/SSL 证书配置官方文档明确指出OneUptime 自身不负责 SSL/TLS 证书的托管证书需要你自己解决。推荐的接入方式是使用反向代理使用 Nginx 或 Caddy 等反向代理用 Lets Encrypt 签发证书将反向代理指向 OneUptime 服务器修改config.env中两项配置将HTTP_PROTOCOL设为https将HOST改为反向代理所在的域名。改完后需要重启服务使配置生效见升级与维护一节的更新命令。补充说明当前仓库的 config.example.env 中保留了PROVISION_SSL开关默认false其注释描述当PROVISION_SSLtrue时 OneUptime 可以为HOST自动签发 Lets Encrypt 证书前提是 80/443 端口可达且域名已解析到本机。也就是说新版本已具备自动签发能力但该文档所描述、且生产上更稳妥的方案仍是外部反向代理终止 TLS。使用反向代理时保持PROVISION_SSLfalse即可。九、生产就绪检查清单官方文档强调理想情况下不要用 Docker Compose 直接上生产强烈建议使用 Kubernetes仓库已提供 HelmChart/Public/oneuptime 与相关 Helm 文档。如果仍要基于 Compose 跑生产请逐条核对9.1 SSL/TLS必须自行配置证书方式见上一节。没有 HTTPS 的监控平台会暴露凭据与监控数据。9.2 密钥Secretsconfig.env中带有默认值/占位值的密钥必须全部替换为随机长字符串见 5.1 表格尤其是ONEUPTIME_SECRET、ENCRYPTION_SECRET、各数据库密码与探针密钥。9.3 备份定期备份Postgres 与 ClickHouse两个数据库Valkey 缓存是无状态的可以安全忽略。仓库自带备份脚本 backup.sh 与恢复脚本 restore.sh。backup.sh使用pg_dump --formatcustom生成压缩的db-日期.backup归档默认保留最近 30 天需要先正确设置config.env中的DATABASE_BACKUP_*系列变量含DATABASE_BACKUP_DIRECTORY、DATABASE_BACKUP_HOST、DATABASE_BACKUP_PORT、DATABASE_BACKUP_NAME、DATABASE_BACKUP_USERNAME、DATABASE_BACKUP_PASSWORD并在备份目录挂载docker-compose.yml中映射的宿主机端口5400。恢复脚本restore.sh使用pg_restore --clean --if-exists执行破坏性恢复会先 DROP 目标库中所有同名对象再重建执行前务必确认DATABASE_RESTORE_*变量指向正确并先停止所有数据库容器脚本会打印警告并要求确认可用DATABASE_RESTORE_ASSUME_YES1跳过确认以支持无人值守。9.4 缓存与队列valkey服务运行 ValkeyRedis 7.2 的 BSD 许可证分支由VALKEY_*配置项控制任何 Redis 协议服务器均可替换只需将VALKEY_HOST指向托管 Redis。REDIS_*旧名称仍然有效见 5.5 节。9.5 更新频率OneUptime 几乎每天发布更新生产环境建议至少每周更新一次。十、升级与维护10.1 常规更新git checkout release # 确保在 release 分支上 git pull npm run update源码视角npm run update在 package.json 中展开为npm run prerun ... docker compose pull npm run start即先运行prerun同步包版本并执行 configure.sh 环境自检然后拉取最新镜像并重新up。因为config.env不会被改写你的密钥与自定义配置在升级后原样保留。10.2 磁盘与日志管理重要官方文档特别提醒compose 部署使用local logging driver而 OneUptime尤其是 probe 与 ingest 容器会产生大量日志。必须限制 Docker 的日志存储上限否则磁盘会被日志占满导致故障。仓库内所有服务默认使用了json-file驱动并设置max-size: 1000m见 docker-compose.base.yml 各服务logging段。如果自行调整或使用默认配置请务必参考 Docker 官方文档关于local/json-file日志驱动轮转max-size、max-file的说明进行设置并配合npm run save-logs/npm run logs/npm run follow-logs分别导出、查看、跟踪容器日志做排障。10.3 常用运维命令源码可查命令作用npm run ps查看容器状态docker compose psnpm run logs/npm run follow-logs查看 / 跟踪最近 100 行日志npm run save-logs导出最近 100000 行日志到logs.txtnpm run stop停止并移除容器docker compose down --remove-orphansnpm run pull拉取最新镜像npm run backup执行 backup.sh 数据库备份十一、卸载 OneUptimenpm run down源码视角npm run down实际就是npm run stop即执行docker compose down --remove-orphans停止并移除全部容器与网络。官方文档声明它不会删除config.env文件也不会删除克隆下来的仓库。一个值得注意的细节npm run down并未附加-v参数因此 Postgres 与 ClickHouse 的数据卷默认会保留。如果你确实需要连数据一起清除例如彻底重装需要手动追加执行docker compose down -v会永久删除数据库数据请先确认已备份。十二、注意事项与延伸阅读首次启动较慢迁移、初始化与证书流程可能需要 5~10 分钟期间访问异常属正常现象可用 Tests/Scripts/status-check.sh 持续探测就绪状态。资源规划服务器规格直接影响可用监控数量与遥测吞吐参考同目录的 sizing.md 按实际用量评估。版本升级路径跨版本升级细节见 upgrading.md。本地开发部署如需在本机跑开发环境参考 local-development.md。生产级部署强烈建议改用 Kubernetes Helm仓库内 HelmChart/Public/oneuptime 提供了完整 Chart 及 HelmChart/Docs 文档Helm 路径下还支持将 ClickHouse 与 Postgres 替换为托管实例并可通过telemetryWriter.enabled拆分遥测写入层对应config.example.env中的TELEMETRY_WRITER_URL等参数。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
