安装

系统要求

支持的平台

平台	支持状态	备注
Linux 发行版（Debian、Ubuntu、CentOS 等）	✅ 支持	推荐平台
Windows 10 (x64)	✅ 支持
Windows Server 2012 R2+ (x64)	✅ 支持
macOS	✅ 支持
FreeBSD / OpenBSD / NetBSD	❌ 不支持
Replit / Heroku	❌ 不支持

来源：README.md61-66

Docker 安装要求

系统上已安装 Docker CE
可以访问 Docker Hub 注册表

非 Docker 安装要求

Node.js 18 或 20.4
npm 9
Git
pm2（推荐用于后台运行）

来源：README.md67-70 CONTRIBUTING.md479-483

安装方法概述

Uptime Kuma 提供两种主要的安装方法，如下图所示

来源：README.md38-89 CONTRIBUTING.md445-460

Docker 安装（推荐）

Docker 是安装 Uptime Kuma 的最简单方法，它封装了所有依赖项并提供了便捷的更新。

Docker 容器架构

下图展示了 Uptime Kuma 在 Docker 容器中运行的方式

来源：README.md42-46 docker/dockerfile29-42 extra/healthcheck.js1-55

基本 Docker 安装

此命令将

创建一个名为 uptime-kuma 的容器
将主机上的端口 3001 映射到容器内的端口 3001
创建一个名为 uptime-kuma 的 Docker 卷，并将其挂载到 /app/data
设置容器自动重启
使用官方 Uptime Kuma Docker 镜像（版本 1）

运行此命令后，可以通过 http://YOUR_SERVER_IP:3001 访问 Uptime Kuma

来源：README.md42-46

Docker 卷注意事项

参数 -v uptime-kuma:/app/data 创建了一个 Docker 卷来持久化 Uptime Kuma 的数据，以确保您的配置和历史数据得以保留。

⚠️ 重要提示： 网络文件系统 (NFS) **不支持** 数据卷。请始终映射到本地目录或 Docker 卷。

来源：README.md48-49

限制网络暴露

如果您想将 Uptime Kuma 的访问限制在 localhost（用于反向代理）

来源：README.md51-56

Docker 标签

Uptime Kuma 提供不同的 Docker 镜像标签

标签	描述
`1`, `latest`	v1 的最新稳定版本
`2`, `latest-2`	v2 的最新稳定版本
`1.x.x`	v1 特定版本
`2.x.x`	v2 特定版本
`beta`	v1 最新 Beta 版本
`beta2`	v2 最新 Beta 版本
`nightly`, `nightly2`	开发版本

来源：CONTRIBUTING.md645-671

非 Docker 安装

对于没有 Docker 或不倾向于使用 Docker 的环境，您可以直接安装 Uptime Kuma。

非 Docker 架构

下图展示了直接安装涉及的组件

来源：README.md72-98

安装步骤

克隆仓库

安装依赖并构建应用程序

启动 Uptime Kuma

选项 1：直接运行（用于测试，不推荐用于生产环境）
选项 2（推荐）：使用 PM2 在后台运行

来源：README.md72-86

有用的 PM2 命令

监控您的 Uptime Kuma 实例

将 Uptime Kuma 添加到启动项（系统启动时自动启动）

来源：README.md92-97

数据存储架构

Uptime Kuma 将所有数据存储在数据目录下的 SQLite 数据库中。为了备份的目的，了解这一点至关重要。

来源：CONTRIBUTING.md586-596 CONTRIBUTING.md527-535

高级配置

环境变量

Uptime Kuma 支持多种环境变量来定制其行为

可变	描述	默认
`UPTIME_KUMA_PORT`	Web 服务器端口	3001
`UPTIME_KUMA_HOST`	Web 服务器主机	0.0.0.0
`DATA_DIR`	数据目录	./data
`UPTIME_KUMA_SSL_KEY`	SSL 密钥文件路径	-
`UPTIME_KUMA_SSL_CERT`	SSL 证书文件路径	-
`UPTIME_KUMA_IS_CONTAINER`	指示容器环境	1（在 Docker 中）

来源：docker/dockerfile34 extra/healthcheck.js15-33

在反向代理后面使用

Uptime Kuma 在 Nginx、Apache 或 Traefik 等反向代理后面运行良好。使用反向代理时

考虑将 Uptime Kuma 仅暴露给 localhost
配置您的反向代理以处理 SSL 终止
确保在您的反向代理配置中启用了 WebSocket 支持

来源：README.md51-56 README.md102-104

自定义数据目录

指定自定义数据目录

来源：extra/healthcheck.js33

故障排除

容器健康检查

Uptime Kuma Docker 容器包含一个健康检查，用于验证应用程序是否正常运行。如果容器看起来不健康

检查容器日志：docker logs uptime-kuma
验证端口可用性：确保没有其他进程在使用端口 3001
检查卷权限：确保数据卷具有适当的权限

来源： docker/dockerfile40 extra/healthcheck.js1-55

数据库问题

如果您遇到与数据库相关的错误

验证数据目录是否可写
确保您没有使用 NFS 或其他不支持的存储类型
检查 SQLite 数据库是否未损坏