最近在本地服务器上折腾了一套Uptime Kuma网站监控服务这东西解决了我一个特别头疼的问题以前好几个站点、服务挂了我都不知道往往是用户来问了才发现非常被动。现在用Uptime Kuma把线上和本地的关键服务全部盯起来一有异常告警就推送到手机基本实现了“服务挂了比自己看到还快”的效果。这篇文章我打算把整个搭建过程、配置细节和踩过的坑完整记录下来。不管你是个人站主、自托管爱好者还是给公司内部做服务巡检的IT人员这套方案都值得参考。我会从产品定位讲到环境准备再到监控项配置、告警通知和常见故障排查尽可能做到照着操作就能跑起来。1. 为什么建议把网站监控放在本地服务器里1.1 Uptime Kuma到底是干什么的Uptime Kuma是一个开源的监控工具界面长得很像Uptime Robot但数据完全掌握在自己手里。它能做的事包括HTTP/HTTPS检查、TCP端口检测、Ping、DNS解析、关键字匹配、证书到期提醒甚至还能对Docker容器、游戏服务器做针对性探测。我选择它的核心原因很简单免费开源无节点数和监控项数量限制自带Web界面配置直观不写代码也能用支持Telegram、钉钉、飞书、邮件、Webhook等几十种通知渠道内置状态页Status Page可以直接对外展示服务运行情况轻量Docker部署下占用资源很小普通家用NAS、小主机都带得动1.2 本地部署和云上监控服务的区别很多人会问既然有现成的在线监控服务为什么还要在本地服务器上自己搭一套我实际对比过两者的差异还是很明显的。用在线SaaS服务确实省事注册账号就能用但有几个痛点。首先是数据隐私监控记录会全部存在第三方平台包括服务器IP、探测频率、响应时间这类信息其次免费额度通常有限制监控项多了就要付费另外有些在线服务在国内访问并不稳定告警可能延迟甚至根本没收到。本地部署这套方案就完全规避了这些问题。监控数据和探测记录都在自己的服务器里存储没有隐私顾虑监控数量随便加主动权在自己手里想加什么脚本、什么检查逻辑都行。当然也有代价——你得自己维护探针服务本身做好备份监控的可用性取决于运行环境。这里要特别说一点如果你监控的是线上生产环境我建议一定要把本地服务器探针端和业务服务器的网络链路做冗余。比如业务服务器在A机房探针跑在公司内部网络那么这条内网链路断了探针自然也会误报。考虑到这点我后来加了外部Ping作为辅助判断两套信号交叉验证减少误报。1.3 什么人适合这么干我总结下来以下这些场景直接从Uptime Kuma获益最多个人站长手上几个网站、API服务需要7x24盯着一旦宕机能第一时间知道自托管玩家家里有NAS或小主机跑了Nextcloud、导航页、RSS服务等想统一监控小微企业IT公司内部有OA、ERP、图床等系统需要定期确认服务可用开发测试团队用GItLab、Jenkins等服务希望随时知道构建机状态、仓库服务是否正常2. 准备阶段硬件、系统与方案选型2.1 硬件门槛到底有多低先聊大家最关心的资源占用。Uptime Kuma本身是Node.js应用实时监控任务靠后台Worker跑整体内存占用很小。我在一台2核2G的云服务器上同时监控30多个服务内存占用在800MB以内如果只监控几个Web站点512MB内存的小主机也完全能跑。本地服务器可以是虚拟机、旧笔记本、树莓派也可以是NAS里的Docker。核心要求只有一个保持常开且网络稳定。我之前看到有人拿自己的主力电脑跑电脑一关机监控就全断了这就没意义了监控工具自己先不可用比不监控更尴尬。2.2 三种部署方式怎么选Uptime Kuma支持多运行方式我梳理了一下方式难度适用场景优点缺点Docker Compose低绝大多数人推荐环境隔离、升级回滚方便需要Docker基础npm直接运行中想省掉容器层的用户资源占用更小Node版本依赖自己维护二进制安装包中低Windows环境比较友好不用装Node环境更新流程较繁琐我个人推荐Docker Compose理由很实际升级Uptime Kuma时只需改镜像版本号后重新up数据卷不会动坏了也能秒回滚。npm方式虽然省资源但Node版本变动容易引发依赖问题后期维护成本更高。2.3 目录结构规划在正式动手前先想清楚数据目录放哪儿。我习惯把自托管应用统一放在一个目录下方便管理备份。以下是我的目录结构示例/opt/uptime-kuma/ ├── docker-compose.yml └── data/ # 挂载给容器存放SQLite数据库、配置和上传文件如果你是用NAS建议把data目录放在存储池里这样即使容器重建、系统重装监控配置和记录都能完整保留。3. 本地服务器上手把手搭建Uptime Kuma3.1 安装Docker环境如果你的服务器还没装Docker先按下面步骤装好。以下命令适用Debian/Ubuntu系列系统其他发行版可以自行查找对应安装方法。# 更新索引并安装依赖 sudo apt update sudo apt install -y apt-transport-https ca-certificates curl software-properties-common # 添加Docker官方GPG密钥和仓库 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin装完验证一下sudo docker --version sudo docker compose version如果你的机器已经装有Docker但版本较老建议升级再继续。我用过较老版本跑Uptime Kuma遇到过容器莫名退出的情况升级Docker后彻底消失。3.2 编写Docker Compose配置在目录里新建docker-compose.yml内容如下version: 3.8 services: uptime-kuma: image: louislam/uptime-kuma:1 container_name: uptime-kuma restart: always ports: - 3001:3001 volumes: - ./data:/app/data environment: - TZAsia/Shanghai这段配置有几个细节值得留意镜像标签用:1代表跟踪1.x大版本自动获取最新的1.x稳定版端口映射3001:3001是Uptime Kuma默认Web端口如果本地服务器上已有服务占用3001可以改成3002:3001TZAsia/Shanghai设置时区否则日志和监控记录显示UTC时间排查问题时会很混乱restart: always保证宿主机重启后容器自动拉起启动容器cd /opt/uptime-kuma sudo docker compose up -d第一次启动会拉取镜像耐心等一会儿。完成后执行docker ps确认容器状态是Up。3.3 访问并完成初始化打开浏览器访问http://你的服务器IP:3001第一次进入会让你创建管理员账号。这里提醒一句密码一定要用密码管理器生成并保存好后续找回密码比一般Web应用麻烦不少。登录以后会看到默认的“首页”状态页和一个示例监控项。这些都可以删掉后面按自己的实际服务来建。3.4 配置域名访问和HTTPS如果只用IP加端口访问其实已经能用了。但想要长期稳定使用建议用一个子域名加HTTPS来访问管理界面。我在本地的nginx服务器里加了这样一段反向代理配置server { listen 443 ssl http2; server_name status.example.com; ssl_certificate /etc/nginx/ssl/example.com.pem; ssl_certificate_key /etc/nginx/ssl/example.com.key; location / { proxy_pass http://127.0.0.1:3001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket支持 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_connect_timeout 60s; proxy_read_timeout 60s; } }注意proxy_set_header Connection upgrade这行不能省。Uptime Kuma界面会实时更新监控状态底层用了WebSocket缺少这行配置的话页面会一直转圈监控状态不自动刷新。为了这个配置我折腾了半小时后来发现就是少了这行。3.5 基础设置里这个选项必须动进入“设置”把语言切换为中文界面会友好很多。再检查一下“监控类型”里是否配置了正确的轮询间隔默认值后面创建监控项时可以单独覆盖。备份设置也建议在初始化阶段就配好。Uptime Kuma提供了一键备份功能可以生成JSON备份文件也可以把备份文件发送到外部存储。我自己是设置每周自动备份备份文件同步到另一台NAS和网盘防止服务器磁盘挂掉之后所有监控配置付之东流。4. 监控配置从一次HTTP检查到完整告警链路4.1 创建第一个监控项点击“添加监控项”选择“HTTP(S)”类型这是监控网站最基础也最重要的方式。表单里有几个关键字段名称建议用域名加功能来命名比如“官网首页”、“API健康检查”网址填写实际要监控的URL监控间隔默认60秒个人网站可以放宽到120秒或者300秒减少无意义请求超时设置默认会比较短我通常调到30秒避免弱网环境误报重试次数填2或3连续失败这么多次才触发告警状态码预期填200也可以填202、301等关键字检查如果页面里有一段固定文字可以填进去做内容校验“重试次数”这个是重点。我刚开始没注意设成了1次结果某天服务被防火墙临时拦截了一下20秒后又恢复了但告警已经发出去了半夜被短信吵醒。设置重试2次之后单次网络抖动不会立刻告警误报率明显下降。4.2 设置告警通知没有告警通知的监控意义减半。Uptime Kuma对通知渠道的支持相当全面我目前用的是Telegram和邮件。这里贴一个Telegram的配置思路作为示范。先在Uptime Kuma“设置”里找到“通知”点“设置通知”类型选Telegram填入Bot Token和Chat ID。然后点击“发送测试消息”如果配置成功几秒内会收到一条测试消息。各通知渠道的适用场景和建议通知渠道优点适用场景注意事项邮件/SMTP通用可靠正式告警、日报注意邮箱发送频率限制Telegram Bot实时性高、免费个人/团队日常告警需要科学网络国内可能不稳钉钉/飞书Webhook国内速度快国内团队协作在群组中添加Webhook机器人Webhook自定义灵活对接自建通知系统按需开发自由度最高Discord适合海外团队与海外群组联动同样需考虑网络因素4.3 使用状态页对外展示如果希望让用户、同事也能直接看到系统是否正常运行而不需要登录Uptime Kuma后台可以设置“状态页”。状态页可以设置分组比如“核心服务”、“辅助服务”然后勾选对应监控项。还支持自定义域名访问。我在公司内网就建了一个状态页开发同事自查服务状态直接在网页上看不需要再问运维省了不少沟通成本。4.4 高级HTTP检查技巧除了最基础的GET请求Uptime Kuma的HTTP(s)监控还支持自定义请求头、POST数据、Basic Auth这些在监控内部API时会用到。举一个实际例子我监控的后端接口要求POST请求才返回正常如果直接用GET去探测服务明明活着也会返回405错误码。正确的做法是在监控项里选“HTTP(S)”后把请求方法改成POST并填写对应的请求体和请求头。另外还有“关键字检查”功能需要勾选“关键字”选项。比如我监控一个文件上传接口正常响应里会包含status:success如果后端逻辑出错但返回还是200关键字检查能帮我发现这类半故障状态。未来像这类页面渲染异常、接口静默报错的情况监控工具的响应时间曲线也会暴露问题。5. 进阶玩法除了监控网页还能干很多事5.1 证书到期监控不怕SSL证书过期SSL证书过期是特别常见的故障原因早年我吃过不少亏。Uptime Kuma内置了“证书到期”监控类型只需要填域名和端口它会自动检测证书剩余天数。设置告警阈值也简单在监控项编辑里把“证书剩余天数不超过天”设成30意思是还剩30天时触发告警。这样证书快到期前就收到提醒通常留在续期上提前处理再也不会出现证书过期网站打不开的情况。5.2 用Ping和TCP检查本地的自托管服务对于内网服务比如NAS、路由器管理页面、GitLab容器不一定需要HTTP检查Ping或TCP端口检查就够了。Ping监控适合判定主机是否在线但对防火墙策略比较敏感某些服务器禁Ping的话会上报失败端口监听检查适合检查特定端口是否开放。比如监控sshd的22端口或者数据库的3306端口这两种监控在创建时选对类型就行配置很简单却能在HTTP层还没暴露问题时提前发现网络或主机的异常。5.3 API对接Prometheus类的监控平台Uptime Kuma自带了一些API接口可以输出拿到监控状态。比如/api/status-page/your-slug可以获取状态页的JSON数据方便对接自己做的看板。如果要更细粒度的监控指标Uptime Kuma的数据库是SQLite表结构相对清晰我写过几个Python脚本去读SQLite数据再把数据吐给Prometheus exporter这种方式适合对监控数据二次加工的场景。不过这种玩法的合理性要看你是否真的需要。大多数场景直接用自带功能就好避免过度设计。5.4 数据备份和迁移前面提到过备份这里把完整流程说清楚。Uptime Kuma的数据都存在data目录下的SQLite数据库文件kuma.db。备份数据最简单的方式就是压缩这个目录。我自己的备份脚本大致逻辑是#!/bin/bash BACKUP_DIR/backup/uptime-kuma mkdir -p $BACKUP_DIR cd /opt/uptime-kuma sqlite3 data/kuma.db .backup $BACKUP_DIR/kuma-$(date %F).db tar czf $BACKUP_DIR/upload-$(date %F).tar.gz data/upload/ find $BACKUP_DIR -mtime 30 -delete这段脚本会先通过SQLite的backup命令做一致性备份避免直接复制db文件导致数据不一致然后打包上传文件最后清理30天前的旧备份。迁移也不难新服务器上装好Uptime Kuma把备份的db文件放到data目录里启动容器就能看到原有监控项和记录完全无缝。6. 实操中常见问题与排查实录6.1 容器起不来或反复重启如果执行docker logs uptime-kuma后发现端口被占、数据库权限报错通常出在以下几个方面端口冲突宿主机上3001已被其他程序占用改映射端口即可data目录权限chmod -R 777 data有时能解决权限问题但更推荐用chown调整属主因为直接777在安全加固时是个隐患磁盘空间不足df -h确认空间剩余磁盘满了容器也会起不来6.2 Telegram通知收不到这个问题几乎所有人都遇到过。首先确认Bot Token和Chat ID是否填对Telegram的Chat ID不是用户名需要找BotFather或GetUpdates接口获取。其次是网络问题Telegram在国内不稳定建议尝试用Webhook方式对接企业微信、钉钉这类国内服务。也提醒一句如果你的服务器本身也在“有针对性地访问Telegram”那这个问题不算网络问题。但不管什么情况Uptime Kuma的告警链路不能依赖你的网络环境否则它自己也不可靠。6.3 告警风暴问题监控项一多某个基础网络抖动可能会导致几十个监控项同时触发告警通知轰炸非常吓人。解决办法有几个每个监控项单独设重试次数至少2次通知里设置“启动通知间隔”晴天时不会频繁重复提醒把不关键的监控项单独分组用低优先级的通知渠道对共享网络做一个“上游连通性”监控项只要这个监控项失败就自动抑制其他相关监控项的告警6.4 SQLite数据库损坏Uptime Kuma用的是SQLite非正常断电、磁盘故障等极端情况下数据库可能损坏表现是页面打开白屏或监控项加载不出。处理方式是先停容器然后备份损坏的db文件再用SQLite自带的恢复命令尝试修sudo docker stop uptime-kuma cd /opt/uptime-kuma/data cp kuma.db kuma.db.bak sqlite3 kuma.db .recover | sqlite3 recover_kuma.db mv recover_kuma.db kuma.db sudo docker start uptime-kuma这个方案不敢保证100%找回数据所以前面说的定期备份很重要。SQLite文件被破坏的情况下最后能救命的往往只有备份。6.5 管理员密码忘了怎么办Uptime Kuma目前没有图形化的“忘记密码”功能。如果你能通过命令修改数据库可以重置密码但操作起来比较复杂还要处理哈希。我的经验是与其折腾重置不如直接恢复备份。所以日常备份越勤快这类问题处理越轻松。6.6 为什么我的监控显示总是红色但网站能打开这类问题九成出在URL本身。网站能通过浏览器打开浏览器会在URL后自动补全协议。如果你在浏览器里输入example.com没问题但在Uptime Kuma里填URL时没写http://或https://就会出现连接失败。另一个常见原因是服务器返回的状态码不是200比如302重定向。此时需要看期望的状态码或干脆选“任何状态码都成功”再配合关键字检查。最后分享一点个人经验整个Uptime Kuma搭建过程并不复杂真正花时间的是理解自己的服务依赖和故障模式。我刚开始用的时候把能监控的都监控上了结果告警一天几十条慢慢的大家都把通知屏蔽了等于白搭。后来我学会做减法核心业务用高频监控加重试边缘服务低频轮询重要告警和一般告警分开渠道状态页只放真正需要给人看的内容。这套方案已经在我的本地服务器上稳定跑了几个月期间帮我发现了至少三次证书过期隐患、一次后端服务内存溢出导致的半宕机还有一次数据库连接池被打满的隐形故障。很多故障都不是“完全打不开”而是响应变慢、局部报错Uptime Kuma的响应时间和关键字检查恰恰能捕捉到这些细节。如果你的服务器还在“裸奔”真的建议花半小时装一个你会感谢当时的自己。