1. 本地部署前的思路为什么我选 Uptime Kuma 做网站监控讲真的网站监控这件事市面上商业方案一抓一大把比如 UptimeRobot、Pingdom 这些免费额度看着挺香真用起来就难受了——监控频率最低 5 分钟一次想要 1 分钟级别的探测就得掏钱而且监控节点都在公网上对纯内网环境、家庭宽带或者公司服务器根本无能为力。更别说数据都在别人手里状态页、告警、历史记录这些核心资产全绑在第三方平台上哪天平台改个政策或者服务挂了你连个替代方案都来不及找。Uptime Kuma 是我比较了一圈之后确定下来的方案。这个项目本质上是一个开源的、支持自托管的监控看板界面是用 Vue 写的后端跑 Node.js数据库用的 SQLite整体非常轻。它解决的最大痛点就是“监控这个动作本身得可控”部署在你的本地服务器上监控频率自己定数据完全私有通知渠道几乎覆盖了主流 IMTelegram、Discord、钉钉、飞书、邮件、Webhook 全都支持而且自带一个非常漂亮的状态页可以直接拿来做服务公开展示。我这次是在一台局域网内的 Ubuntu 服务器上部署的Docker 方式安装前后不到半小时就跑起来了。这篇文章我会把整个搭建过程、配置细节、踩过的坑全部记录下来如果你也想在自己的本地服务器上搭一套私有监控照着做基本能一次成功。适合的人群很明确家里有 NAS 或小主机的折腾党、公司内部有业务系统需要盯着的运维、以及不想为监控服务付费的独立开发者。2. 部署前必须想清楚的几个选型问题2.1 裸机装还是 Docker 装官方仓库的 README 提供了两种主流的安装方式直接 Node.js 跑源码或者用 Docker 跑官方镜像。个人强烈建议用 Docker原因有几个。Uptime Kuma 的依赖其实不算复杂但它依赖的 Node.js 版本是有要求的太老或太新的系统自带 Node 版本很容易踩坑。Docker 镜像把整个运行时环境都打包好了你不需要在宿主机上装 Node、装 npm、处理版本冲突一条 docker run 命令搞定一切。还有一个更实际的原因升级。Uptime Kuma 的迭代速度非常快基本每个月都有新版本加了不少实用功能。Docker 方式升级只需要拉新镜像、重建容器旧容器删掉即可数据都存在 volume 里不会丢。裸机方式升级要手动拉代码、装依赖、重启服务操作步骤多了出错概率自然也就上去了。2.2 要不要加反向代理如果只在局域网内访问完全不需要反向代理直接 IP 加端口就行。但如果你的监控服务需要暴露到公网比如人在外面想随时看状态页那强烈建议在前面套一层 Nginx 或者 Caddy。原因不只是 HTTPS 证书的问题还有安全层面的考虑——Uptime Kuma 虽然本身有登录认证但任何暴漏到公网的管理后台都是攻击面用反向代理加一层访问控制、加一层 TLS能挡掉很多无差别扫描。我自己的部署场景比较特殊监控目标既有公网网站也有内网其他服务器的端口连通性。这种情况下如果监控服务部署在内网公网网站能正常探测到但反过来如果部署在公网就探测不到内网服务的真实状态了。所以“本地服务器”这个定位并不是妥协而是这种混合监控场景下最合理的方案。2.3 网络拓扑的确认清单部署之前建议先确认几件事避免装到一半发现网络不通本地服务器的 IP 是否固定建议在路由器或 DHCP 里做 MAC 地址绑定否则后面配置通知、回调地址容易出问题。服务器上的防火墙是否放行了对应端口Docker 默认映射端口、反向代理端口都要放行。能否访问外网Uptime Kuma 的 Docker 镜像需要从 Docker Hub 拉取如果服务器在纯内网环境需要先解决镜像源的访问问题。3. Docker 部署全流程从零开始把服务跑起来3.1 先装 Docker 环境如果你的服务器上还没有 Docker这一步得先补上。以 Ubuntu 为例直接按官方文档来sudo apt update sudo apt install ca-certificates curl gnupg lsb-release sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin装完以后执行sudo systemctl enable --now docker然后docker --version确认一下版本。这里多说一句Docker 安装包在部分网络环境下可能拉取比较慢如果遇到超时可以考虑配置国内镜像加速器这里就不展开讲具体配置了网上方案很多关键是让docker pull能正常跑通。3.2 用 docker-compose 部署 Uptime Kuma我不太建议直接敲一长串docker run命令来部署因为参数实在太多一旦写错或者以后想改配置还得去翻历史命令。用 docker-compose 把配置固化下来一劳永逸。新建一个目录比如mkdir -p ~/uptime-kuma cd ~/uptime-kuma然后创建docker-compose.ymlversion: 3.8 services: uptime-kuma: image: louislam/uptime-kuma:1 container_name: uptime-kuma restart: always ports: - 3001:3001 volumes: - ./data:/app/data然后启动sudo docker compose up -d启动后执行sudo docker ps看到uptime-kuma容器处于Up状态就说明服务起来了。浏览器访问http://服务器IP:3001第一次打开会让你创建管理员账号用户名和密码尽量设置得复杂一点因为这个页面理论上谁都能访问如果暴露到公网弱口令非常危险。关于镜像版本我习惯用louislam/uptime-kuma:1这个标签它会跟随 1.x 的最新版本走既能及时获得功能更新又不会出现像latest那样的大版本跳变风险。3.3 数据目录和备份策略注意看我在 compose 文件里映射的./data:/app/data这个目录是 Uptime Kuma 存放 SQLite 数据库、配置文件、上传图片的地方。所有监控配置、通知配置、状态页设置全在这个目录里。备份的方式非常简单定期把data目录打包拷贝走就可以了。tar -czvf uptime-kuma-backup-$(date %Y%m%d).tar.gz data/我实际用下来整个 data 目录即便配置了十几个监控项、几十条通知记录大小也就几 MB备份成本几乎可以忽略不计。建议配合 crontab 写个定时任务每天凌晨备份一次保留最近 7 天的备份文件。数据库文件虽然 SQLite 支持并发读写但备份时最好先停一下容器docker compose stop或者在容器内先做 SQLite 的在线备份避免备份到一半写入引起的文件不一致。我偷懒的做法是直接 tar 打包实测没有出过问题但如果你有完美主义倾向可以多加一步sudo docker exec uptime-kuma node -e const db require(./server/database); db.close();不过这条命令在不同版本上可能不太兼容所以我最终觉得直接打包整个 data 目录加上频率够高是容错性最好的方案。4. 核心环节监控项的创建与配置细节Uptime Kuma 最核心的用法就是添加监控项。登录后台后点击 “Add New Monitor”这里会看到非常多的监控类型接下来逐个讲。4.1 HTTP(s) 监控——最常用的一类对于网页服务最简单也最关键的就是 HTTP 监控。它的原理就是定时向你的目标 URL 发送 HTTP 请求根据返回的状态码判断服务是否正常。配置时有几个关键参数URL填你要监控的完整地址比如https://example.com/index.html。这里有个容易忽略的点如果你是监控 API 接口URL 里可以直接带路径和查询参数如果你监控的是浏览器渲染后的页面要清楚 Uptime Kuma 并不会执行 JavaScript 渲染它只看 HTTP 响应。想监控动态渲染的页面要么用后面的“Browser Script”类型要么就退而求其次监控静态资源文件。Expected Status Codes预期状态码。默认是 200-299比较宽松。如果服务本身会返回 302 重定向你需要把 302 加进去或者保证重定向的最终落地页是正常的如果服务有自定义的状态码比如有的网关返回 499也需要在这里配置。Interval探测间隔。Uptime Kuma 的最小间隔是 20 秒Pro 计划支持到 20 秒自托管可以自己改实际跑 20 秒没问题再短意义不大了。个人建议公网网站用 60 秒或 5 分钟内网服务可以适当缩短到 30 秒或 20 秒但要注意——如果被监控的服务是生产系统过于频繁的探测可能会增加不必要的负载尤其是一些老旧的业务系统扛不住高频请求刷新缓存。Timeout超时时间。默认 49 秒意味着如果请求超过 49 秒没有响应就判定失败。对大多数 Web 服务来说这个值太长了建议改成 10-15 秒否则一旦服务响应变慢你也只能干等到超时才能感知到“异常”。4.2 Ping 监控和端口监控除了 HTTPUptime Kuma 还支持 Ping、TCP 端口、DNS、关键字等监控方式。Ping 监控适合探测服务器是否在线原理就是发送 ICMP 包。这里提醒一下很多云服务器和部分内网设备默认禁 ping 或者对 ICMP 限流如果发现 Ping 监控老是不稳定先手动在服务器上 ping 一下目标 IP确认是不是防火墙的锅。TCP 端口监控非常实用比如你想监控某个数据库的 3306 端口、Redis 的 6379 端口、SSH 的 22 端口是否是开放的。这类监控不需要任何 HTTP 层的能力只要端口能建立 TCP 连接就算正常。我在公司内部就用这个方法监控了好几台内网服务器的 SSH 端口和一些自建中间件。配置端口监控时有一个小技巧把 Resolve DNS 选项和 IP 版本设置搞清楚。如果域名解析本身有问题端口监控会直接失败这时候可能并不是端口不通而是 DNS 解析挂了。建议内网服务直接用 IP 地址公网服务可以同时选择 “Resolve hostname to IPv4” 选项来确保走 IPv4 解析。4.3 关键字监控——检测页面内容是否正确HTTP 状态码 200 只能说明“服务还活着”但没法告诉你“服务逻辑正不正常”。比如一个登录页如果数据库挂了可能页面还能返回 200只是页面上的数据会加载失败。这种情况下关键字监控就派上用场了。在 HTTP 监控的高级设置里有一个“Keyword”选项填一个关键字和一个类型存在或不存在。比如你监控一个搜索接口返回的 JSON 里应该包含success: true那就把success填进去选择 “Keyword exists”。如果页面上有一个错误提示文案Internal Server Error你可以填进去并选择 “Keyword should not exist”这样一旦页面返回了错误提示监控会直接告警。关键字监控有一个坑HTTP 响应体的大小。如果页面内容非常大几 MB每次抓取响应体来做关键字匹配会消耗额外流量和 CPU。Uptime Kuma 对此的处理还可以实际跑下来对小站点完全没有压力但如果你监控的是大文件下载地址就别用关键字监控了直接用 HTTP 状态码就行。4.4 证书监控——防止 HTTPS 证书过期HTTPS 证书过期这种事故我相信搞过网站的人都经历过。Uptime Kuma 自带Certificate Info监控类型可以检测一个域名的 SSL 证书还有多少天过期。这个功能非常省心配置好以后证书剩余天数会显示在监控项上快过期了还能收到通知。证书监控有一点要注意如果域名是通过 CDN 或反向代理访问的检测到的证书可能是 CDN 节点的证书而不是源站证书。这种情况下证书监控依然有效因为最终用户访问的也是这个证书。但如果你想监控源站证书就得填源站 IP 加 Host 头或者干脆在 CDN 和源站之间做单独的内网证书监控。配置很简单URL 填域名不需要加协议端口默认 443如果你想监控非标准端口的 HTTPS 证书记得把端口改掉。5. 通知配置与分组管理告警不能只发到一个地方5.1 配置 Telegram 通知监控配好了最关键的其实是通知。如果平台监控到服务宕机、却没法把信息推送到你手上那这监控基本等于白做。Uptime Kuma 的通知渠道非常丰富我最常用的是 Telegram。配置 Telegram 通知需要三步第一步在 Telegram 里创建自己的 Bot拿到 Bot Token通过 BotFather 创建格式大概是123456:ABC-DEF...第二步获取接收告警的 Chat ID可以给 Bot 发一条消息后通过 getUpdates 接口拿到第三步在 Uptime Kuma 的 “Setup Notification” 里把 Token 和 Chat ID 填进去保存后可以点 “Test” 按钮测试。Telegram 通知的优点在于Uptime Kuma 天然支持 Markdown 格式化告警消息可以带上监控项名称、当前状态、响应时间这些信息一眼就能看明白是哪个服务出了问题。而且手机客户端推送很及时基本是秒级到达。5.2 Webhook 通知——打通任意系统如果你的团队用的是自建 IM 或者内部工单系统Webhook 是万能的。Uptime Kuma 在通知配置里提供 Webhook 类型你可以把请求发到任意 HTTP 接口。配置时注意 Custom Headers 里可以加上认证 TokenBody 里支持变量模板比如{ monitor: {{NAME}}, status: {{STATUS}}, url: {{URL}} }这里{{NAME}}、{{STATUS}}、{{URL}}是 Kuma 内置的变量会在请求发出时自动替换成实际值。官方文档里列出所有变量的说明你按需拼接即可。如果你的通知系统要求 GET 请求而不是 POST把 Method 改掉就行非常灵活。5.3 按监控分组管理监控项多了以后如果没有分组仪表盘会越来越乱。Uptime Kuma 支持给监控项打标签Tag你可以把“官网”、“API”、“数据库”、“内网服务”分别打上不同的标签然后在主页按标签筛选查看。这个功能特别适合有几十个监控项的场景。我自己的习惯是标签不仅做分类还用来做告警路由。比如“TeamA”标签关联 Telegram 群组 A“TeamB”标签关联企业微信群组 B这样每个团队只会收到自己负责的那部分服务的告警不会造成全体轰炸。实现方式就是在添加监控项时在 Tags 里选好对应标签然后在通知配置页面把每个通知渠道绑定到你想要的标签上。这样既实现了告警分流又能保留一个全局视角的仪表盘。5.4 使用状态页对外展示服务状态Uptime Kuma 自带的 Status Page 功能个人觉得是被很多人低估的亮点。你可以配置一个公开的状态页展示所有监控项的实时状态包括可用率、响应时间、历史事件。这个页面完全不需要登录就能访问适合挂在你公司官网的/status路径上或者分享给客户、用户群体。配置状态页时把选好的监控项拖进去设置好公开访问的 slug一个简洁的英文标识再美化一下标题和 logo 就行。如果状态页面向公网用户建议给它套一层 HTTP 认证或者 Cloudflare Access 之类的访问控制避免监控数据被无关人员看到——当然如果你就是想公开透明那就不设限制直接发布。6. 常见问题排查部署和运行中遇到的坑一次性讲完6.1 端口冲突导致服务起不来Docker 启动容器时如果3001端口被宿主机上其他进程占用了容器会报错退出。排查方法很简单sudo lsof -i:3001 sudo netstat -tunlp | grep 3001找到占用进程后要么换 Uptime Kuma 的映射端口比如3002:3001要么处理掉那个进程。注意容器内端口始终是 3001宿主机端口可以随便映射。6.2 邮件通知无法发送很多人配置 SMTP 通知时遇到问题明明服务器 25/465/587 端口都是通的但邮件就是发不出去。我的经验是先确认邮箱服务商是否开启了 SMTP 服务、是否用了授权码而不是邮箱密码。QQ 邮箱、163 邮箱都需要单独开启 SMTP 并生成授权码直接用客户端密码登录是会被拒绝的。另外如果用 465 端口SSL或 587 端口STARTTLS注意 Uptime Kuma 的邮件配置里选择对应的加密方式。选错了照样连不上。6.3 监控项频繁误报如果你发现服务明明好好的Uptime Kuma 却经常告警首先怀疑是超时时间配置得太短。特别是一些性能不稳定的 API平时响应 200ms高峰期突然涨到 2 秒如果超时设成 1 秒就会误报。建议先在监控项的 “HTTP Timeout” 里把时间放宽一点稳定运行一段时间后再逐步调小。还有一个常见原因是代理导致的。如果 Uptime Kuma 部署在某个网络环境下HTTP 请求必须走代理才能访问公网但 Kuma 默认不走系统代理需要配置环境变量HTTP_PROXY、HTTPS_PROXY才能正常探测。不配置的话所有公网监控项都会报错。6.4 Docker 重启后监控数据丢失这个问题遇到过一次起因是 compose 文件里忘了挂载 volume。如果不挂./data:/app/data容器每次重建后数据就回滚到镜像初始状态所有监控项和配置都会丢。检查一下 compose 文件里有没有这段volumes: - ./data:/app/data如果之前已经踩坑了但容器还没删可以试试从容器里把数据拷贝出来sudo docker cp uptime-kuma:/app/data ./data然后再改 compose 文件把 volume 挂上手动恢复。6.5 不能删除内置管理员账号Uptime Kuma 的数据库里第一个创建的管理员账号是系统内置的除非你主动修改否则很多权限操作都依赖它。如果你在测试时不小心创建了多个账号不要试图直接删除第一个管理员否则可能会导致后续无法登录。安全起见第一任管理员密码一定要记好。7. 性能调优与高可用方案让监控服务本身更靠谱7.1 监控实例本身不能成为单点故障监控系统最重要的属性就是“自己不能挂”。如果你只在一个台机器上跑了 Uptime Kuma那你监控所有服务的底气完全系于这台机器的稳定性。对于不重要的小项目一台小主机足够用了但对于真正重要的业务建议部署两个实例分别放在不同网络环境比如一个在家里一个在云服务器上用状态页把两个实例合在一起展示。如果做双实例需要注意数据库同步的问题。Uptime Kuma 官方不推荐两个实例直接共享同一个 SQLite 数据文件SQLite 在多写场景下容易锁库。可以退而求其次让两个实例的监控项各自维护状态页只做展示聚合。7.2 资源占用极低适合跑在低配设备上Uptime Kuma 的资源占用非常友好。我实测在 1 核 1G 的小鸡上跑 10 个监控项、1 分钟探测间隔内存占用大约 150MB 左右CPU 基本在 1% 以下。在树莓派、群晖 NAS 甚至一些软路由上跑都毫无压力。如果你手头有吃灰的 ARM 小盒子装 Docker 后直接部署很香。7.3 状态页缓存与公网安全如果把状态页开放到公网建议在反向代理层加一个缓存策略避免每次用户刷新状态页都触发 Kuma 的实时检查。例如 Caddy 的静态文件缓存配置或者 Nginx 的proxy_cache。不过 Uptime Kuma 本身已经做了连接复用和轻量查询实际压力很小加缓存更多是锦上添花。公网暴露安全方面有几个亲测有效的习惯务必设置强密码最好开两步验证Uptime Kuma 支持 TOTP 二次认证。不要在默认端口 3001 上直接裸奔换一个高位随机端口或者通过反向代理只暴露状态页管理后台只允许内网访问。如果管理后台必须公网访问用 Nginx 加一层 basic auth 做前置拦截就算 Kuma 有漏洞也能挡住一部分扫描攻击。定期更新镜像docker compose pull docker compose up -d一行命令的事别偷懒。8. 最终的使用心得和一些容易忽略的细节最后再分享几个我实际使用过程中的体会。Uptime Kuma 的监控日志和历史数据是很有价值的但很多人配完告警就不管了。建议每周末花两分钟看一遍每个监控项的可用率趋势有些问题不是“宕机”级别的而是“响应时间逐步劣化”——比如每天响应时间上涨 50ms连续涨了一个月说明上游服务或数据库可能出现了隐患。Uptime Kuma 的图表虽然不算华丽但这种趋势分析足够用了。另一个容易忽略的细节是监控项的分组逻辑。很多人一开始把所有监控项堆在同一个仪表盘下时间久了很难定位问题。建议一开始就按照业务系统维度或网络区域维度来分组比如“核心电商站群”、“内部OA系统”、“第三方API依赖”。这样一旦告警进来你能第一时间判断影响范围而不是看到一堆红色条目不知道从哪里开始排查。比如说你可以利用 Uptime Kuma 的 “Group” 功能有些版本叫 “Parent”把多个子监控项聚合到一个父级监控下。如果你的服务是多个依赖组成的整体父级挂了可以先告警子级再往下钻取定位具体问题。这种层级化管理在监控数量超过 20 个以后帮你省下大把时间。还有一个只有长期用才会发现的点Uptime Kuma 自带的 “Maintenance” 功能一定要用起来。每次发布上线或维护窗口期提前把对应的监控项设置为维护状态否则你会在发布过程中收到一堆假告警久而久之对告警就麻木了真出问题时反而没人关心。设置维护时间段之后状态页会显示这个监控项“Under Maintenance”很规范也方便团队协作。我个人目前跑了三个实例分别管家里的 NAS、公司的几个核心业务系统和几个客户的公网网站。用了快一年稳定性没得说告警通知几乎没有漏报过。如果你还在用第三方监控平台被限制频率和节点建议花半小时搭一套自己的 Uptime Kuma上手非常简单用了就回不去了。