1. 项目概述：为什么你需要一个专属的状态站点？

在数字化协作成为常态的今天，无论是个人项目、创业团队还是企业内部系统，服务的可用性都是生命线。想象一下，你的用户或团队成员突然发现网站打不开了，API调用失败了，数据库连接超时了，第一反应是什么？是疯狂刷新页面，还是在群里@你，或者直接打电话？这种被动的、混乱的响应方式，不仅消耗信任，更浪费宝贵的排查时间。一个公开、透明、自动化的状态站点，就是解决这个痛点的最佳实践。它就像你服务的“健康仪表盘”，7x24小时不间断地告诉所有人：“我现在一切正常”，或者“我这里出了点问题，正在修复”。

你可能会说，市面上不是有Statuspage、Better Uptime这些成熟服务吗？没错，但它们通常是付费的，对于个人项目或小团队来说是一笔额外的开销。而今天要聊的Upptime，则是一个基于GitHub生态的、完全免费的开源解决方案。它的核心逻辑极其巧妙：利用GitHub Actions实现定时监控，将监控结果（状态、响应时间）提交到仓库，并通过GitHub Issues自动创建和管理故障事件，最后用GitHub Pages免费托管生成一个美观的状态页面。整个流程，从监控到展示，完全在GitHub内闭环，无需服务器，无需信用卡，真正意义上的零成本。

我自己在维护几个开源项目和内部工具时，就全面切换到了Upptime。最直接的感受是，它把“状态透明”这件事从一项需要手动维护的负担，变成了一个全自动的、可追溯的流程。当服务出现波动时，Upptime会自动创建Issue，记录下故障开始时间、持续时长，并在恢复后自动关闭Issue。这个Issue日志本身就是一份宝贵的故障报告。对于用户而言，他们访问一个固定的网址就能看到所有服务的状态历史，焦虑感会大大降低。接下来，我就带你从零开始，一步步搭建并深度定制属于你自己的Upptime状态站。

2. 核心原理与架构拆解：Upptime是如何工作的？

在动手之前，彻底理解Upptime的工作机制至关重要。这能帮助你在后续配置和排错时心中有数，而不是机械地复制粘贴命令。Upptime的架构可以概括为“一个仓库，四大组件”的协同工作流。

2.1 核心组件联动解析

整个系统的运转完全依赖于GitHub提供的免费自动化能力：

1. GitHub Actions (引擎)：这是Upptime的“大脑”和“双手”。我们在仓库中配置一个工作流（Workflow）文件，通常是.github/workflows/uptime.yml。这个工作流被设定为定时任务（例如每5分钟运行一次）。当它触发时，会启动一个临时的虚拟服务器（Runner），执行我们定义好的监控脚本。
2. 监控脚本 (逻辑)：在工作流中，Upptime会运行其核心的Node.js脚本。这个脚本会读取仓库根目录下的.upptimerc.yml配置文件，根据里面定义的站点列表，依次去访问（发送HTTP/HTTPS请求）每一个目标URL。它会记录响应状态码、响应时间，并检查返回内容是否包含我们预设的关键词（用于验证服务功能是否正常，而不仅仅是能连通）。
3. GitHub仓库 (数据库)：监控脚本执行后，会将结果写入仓库中的两个核心目录：
   • history/：这里存放着每个被监控站点的详细历史记录，是一系列YAML文件。每次检查的结果都会追加进去，包括时间戳、状态码、响应时间等。这是生成图表和历史数据的基础。
   • api/：这里存放着汇总后的JSON数据，是状态页面直接读取的数据源。Upptime会在这里生成一个summary.json，包含所有站点的最新状态、平均响应时间等聚合信息。
4. GitHub Issues (事件日志)：这是Upptime的“事件管理系统”。监控脚本在发现一个站点从“正常运行”变为“故障”时，会自动创建一个新的Issue，标题包含站点名和故障时间。这个Issue会作为该次故障事件的跟踪工单。当站点恢复后，脚本会自动在Issue下添加恢复的评论并关闭它。所有历史故障一目了然。
5. GitHub Pages (展示层)：最后，Upptime利用GitHub Pages的静态站点托管功能。它基于仓库里的api/数据和内置的静态页面模板，生成最终的HTML、CSS、JavaScript文件。你只需要在仓库设置中开启GitHub Pages并指定源分支（通常是gh-pages或根目录），一个可通过https://[你的用户名].github.io/[仓库名]访问的专业状态页面就诞生了。

2.2 免费性与可靠性探讨

很多人会担心“免费的是否可靠”。Upptime的可靠性建立在GitHub Actions的可用性上。GitHub Actions为公开仓库提供每月2000分钟的免费额度。对于一个每5分钟检查10个站点的配置，一个月大约需要5分钟 * 24小时 * 30天 * 10个站点 / 60分钟 ≈ 600分钟，远低于免费额度。即使监控频率更高，也完全够用。

更重要的是，Upptime的监控是“去中心化”的。GitHub Actions的Runner在全球多个地区都有节点，这意味着你的监控请求是从云端发起的，不受你本地网络的影响。即使你的家庭网络或办公室网络断了，Upptime依然能正常工作并记录下“站点从外部看是否可访问”的真实状态。当然，它的局限性在于监控频率受限于Actions的调度，无法实现秒级监控，但对于绝大多数Web服务和API的可用性监控来说，分钟级已经完全足够。

3. 从零开始：手把手搭建你的第一个状态站

理论清晰后，我们进入实战环节。请跟随以下步骤，大约10分钟就能拥有一个运行中的状态页面。

3.1 前期准备与仓库创建

首先，你需要一个GitHub账号，这应该是基础。登录后，我们开始创建核心仓库。

1. 访问模板仓库：在浏览器中打开 Upptime 的官方模板仓库：github.com/upptime/upptime。
2. 使用模板：不要直接Fork！点击绿色的 “Use this template” 按钮，然后选择 “Create a new repository”。这是关键的一步，使用模板创建会保留所有必要的工作流文件和配置，而Fork可能会带来一些不必要的提交历史。
3. 命名仓库：在新页面中，为你的仓库起一个名字。例如my-status-page。仓库描述可以写 “Public status page powered by Upptime”。确保仓库是Public（公开）的，因为私有仓库的GitHub Actions免费额度较少，且GitHub Pages对私有仓库支持不同。
4. 创建仓库：点击 “Create repository from template”。稍等片刻，一个包含Upptime所有初始文件的仓库就创建好了。

3.2 核心配置文件详解与定制

仓库创建完成后，你需要修改核心配置文件.upptimerc.yml。这是Upptime的“总指挥中心”，所有行为都由它定义。点击仓库中的这个文件，然后点击编辑（铅笔图标）。

下面是一个详细配置示例及解读：

# 站点所有者信息，会显示在状态页脚 owner: your-github-username # 替换为你的GitHub用户名 repo: my-status-page # 替换为你的仓库名 # 状态网站的标题和描述 site: name: "我的服务状态中心" # 你状态页的标题 description: "所有核心服务的实时运行状态与历史记录" # 页面的描述文字 logoUrl: "https://example.com/your-logo.png" # 可选，页面左上角Logo的URL footer: "由 ❤️ 使用 Upptime 驱动" # 可选，页面底部的自定义脚注 # 状态页面的访问网址（创建后才知道，可先占位） status-website: https://your-github-username.github.io/my-status-page/ # 监控的站点列表，这是核心部分 sites: - name: "个人博客" url: "https://blog.example.com" # 可选：检查返回内容是否包含特定文本，确保不是错误页 expectedStatusCodes: [200] # 可选：匹配关键词，比如检查页面标题里是否有“Home” expectedBodyText: "Home" # 可选：请求方法，默认为GET method: GET # 可选：请求头，比如设置User-Agent headers: - key: "User-Agent" value: "Upptime-Monitor/1.0" # 可选：设置超时时间（毫秒） maxRedirects: 3 requestTimeout: 30000 - name: "API 网关" url: "https://api.example.com/health" expectedStatusCodes: [200] # 对于API，常检查返回的JSON中的一个字段 expectedBodyText: "\"status\":\"ok\"" method: GET - name: "数据库管理面板" url: "https://admin.example.com" expectedStatusCodes: [200] # 如果该站点需要登录，Upptime无法直接处理，需配合其他健康检查接口 method: GET # GitHub Issues 相关配置 issue: # 当站点下线时，自动创建Issue autoCreateIssues: true # 故障解决后，自动关闭Issue autoCloseIssues: true # 为Issue打上标签，便于分类 labels: ["status"] # 故障持续多久后创建Issue？默认0秒（立即创建） issueCreationThreshold: 0 # 恢复后多久关闭Issue？默认0秒（立即关闭） issueResolutionThreshold: 0 # 监控频率与重试策略 schedule: # 监控工作流每5分钟运行一次 interval: "*/5 * * * *" # 如果一次检查失败，在创建工作流内重试2次 retries: 2 # 重试间隔（秒） retryInterval: 60 # 通知配置（高级功能，后续可扩展） # notifications: # - type: slack # webhookUrl: ${{ secrets.SLACK_WEBHOOK_URL }}

编辑完成后，在页面底部填写提交信息，例如 “Initial config: add my services”，然后提交更改。这次提交会触发GitHub Actions的首次运行。

3.3 触发工作流与开启页面托管

提交配置文件后，你需要手动触发一次监控，以初始化数据。

1. 进入你的仓库，点击上方的 “Actions” 标签页。
2. 在左侧边栏，你应该能看到一个名为 “Uptime” 的工作流。点击它。
3. 在右侧，点击 “Run workflow” 按钮，然后在下拉菜单中选择你的主分支（通常是main或master），再次点击 “Run workflow”。
4. 工作流开始运行。你可以点击正在运行的任务查看实时日志。首次运行会耗时稍长，因为它需要安装依赖、执行监控、生成初始数据并提交回仓库。

等待工作流运行完成（所有步骤显示绿色对勾）。完成后，你需要开启GitHub Pages：

1. 进入仓库的 “Settings” 标签页。
2. 在左侧边栏找到 “Pages”。
3. 在 “Source” 部分，选择 “Deploy from a branch”。
4. 在 “Branch” 下拉菜单中，选择gh-pages分支，并保持文件夹为/(root)。如果还没有gh-pages分支，Upptime的首次工作流成功运行后会创建它。
5. 点击 “Save”。

稍等一两分钟，GitHub会显示你的站点已经发布，并提供一个https://[你的用户名].github.io/[仓库名]的链接。点击这个链接，你的专属状态页面就映入眼帘了！

4. 深度定制与高级配置指南

基础搭建完成后，一个白底黑字的状态页可能无法满足你的品牌或功能需求。Upptime提供了丰富的定制选项。

4.1 状态页面UI与品牌化定制

Upptime的状态页面基于静态生成，其样式和结构可以通过覆盖默认模板来修改。最简单的方式是自定义site配置项。

• 主题与颜色：Upptime默认支持亮色和暗色主题，会根据用户系统偏好自动切换。你可以通过修改site下的theme相关配置进行微调，但这需要一定的CSS知识。更直接的方法是，在仓库中创建.github/upptime/目录，然后放置自定义的status.css文件来覆盖默认样式。
• 多语言支持：状态页面的文本可以本地化。在.upptimerc.yml中配置i18n选项，例如i18n: zh-cn，可以让页面部分元素显示中文。Upptime社区提供了一些翻译文件，你可以参考其文档进行配置。
• 自定义域名：如果你有自己的域名，不想使用github.io的子域名，可以绑定自定义域名。
  1. 在域名DNS管理后台，添加一条CNAME记录，指向[你的用户名].github.io。
  2. 在你的Upptime仓库根目录下，创建一个名为CNAME的文件（无后缀），内容就是你的域名，例如status.yourdomain.com。
  3. 提交这个文件。下次工作流运行时，会将其部署到gh-pages分支。
  4. 回到仓库的 GitHub Pages 设置（Settings -> Pages），在 “Custom domain” 处填写你的域名并保存。GitHub会为你验证DNS记录。

4.2 监控策略精细化配置

针对不同的服务，监控策略需要差异化。

• 敏感服务与告警延迟：对于一些偶尔有短暂波动的服务，你可能不希望一次5分钟的失败就创建Issue“报警”。这时可以调整issueCreationThreshold（单位：秒）。例如设置为300（5分钟），意味着只有连续失败超过5分钟，才会创建故障工单。
• 关键服务与快速发现：对于核心服务，你可能希望检查更频繁。但注意，GitHub Actions的调度并非精确到秒，且频繁调度（如每分钟）会快速消耗免费额度。更实用的方法是增加监控维度。例如，不仅监控首页，还监控登录接口、健康检查接口（/health）、核心API接口等，形成一个监控矩阵。
• TCP端口与关键词断言：Upptime主要进行HTTP(S)检查。对于只开放TCP端口的服务（如数据库的3306端口），原生不支持。但你可以通过一个简单的“中间层”来解决：编写一个微服务（例如用Python Flask或Node.js Express），部署在某个云函数（如Vercel、Cloudflare Workers）上，这个微服务的唯一功能就是去连接你的TCP服务，根据连接成功与否返回HTTP 200或503。然后让Upptime去监控这个微服务的URL。expectedBodyText是一个强大的功能，可以确保返回的内容符合预期，避免“页面能打开但功能已挂”的情况。

4.3 集成外部通知（如钉钉、飞书、微信）

Upptime默认的故障通知是创建GitHub Issue。但对于需要实时告警的场景，这不够。我们可以通过GitHub Actions的Secrets和自定义工作流步骤来实现。

核心思路是：在Upptime的工作流执行完毕后，如果发现有新创建的Issue（即发生了新的故障），就触发一个额外的步骤，调用外部Webhook发送通知。

你需要修改.github/workflows/uptime.yml文件（操作前建议先备份）。在文件末尾，jobs部分，找到名为update-template的job，在其steps之后，可以添加一个新的step。以下是一个发送到钉钉机器人的示例思路：

1. 在钉钉群添加一个自定义机器人，获取其Webhook地址。
2. 在你的GitHub仓库中，进入 “Settings” -> “Secrets and variables” -> “Actions”，新建一个Repository secret，名称例如DINGTALK_WEBHOOK_URL，值为你的钉钉机器人Webhook地址。
3. 在uptime.yml中，添加一个步骤来发送通知。这通常需要一些脚本逻辑来判断是否有新Issue，并格式化消息。一个更简单通用的方法是利用已有的GitHub Actions市场插件，例如appleboy/telegram-action用于Telegram，或自己编写一个调用Webhook的curl命令步骤。

注意：直接修改工作流文件有一定风险，可能导致监控中断。建议先在个人测试仓库中尝试，或者仔细阅读Upptime官方文档关于工作流扩展的部分。

5. 运维实践、故障排查与经验心得

即使全自动化，作为维护者，你仍需了解如何运维和排查问题。

5.1 日常维护检查清单

• 监控GitHub Actions运行状态：定期（比如每周）看一眼仓库的 “Actions” 标签页，确保 “Uptime” 工作流都在成功运行（绿色对勾）。如果出现红色叉号，需要点击查看失败原因。
• 关注仓库提交记录：Upptime会自动向history/和api/目录提交数据。频繁的提交是它正常工作的标志。如果长时间没有自动提交，可能是工作流被禁用了或配置有误。
• 审查自动创建的Issue：故障Issue不仅是给用户看的，更是给你的复盘材料。定期回顾故障记录，分析根因，思考是否有优化架构或监控策略的空间。
• 额度监控：在GitHub账号的 “Settings” -> “Billing and plans” 页面，可以查看GitHub Actions的分钟数使用情况，确保不会意外超限（对于公开仓库，基本不可能）。

5.2 常见问题与解决方案实录

以下是我在长期使用中踩过的坑和解决方案：

• 问题1：工作流运行失败，错误提示“Resource not accessible by integration”

  • 现象：在Actions日志中，可能在提交代码步骤报错。
  • 原因：这是最常见的权限问题。创建仓库时自动生成的GITHUB_TOKEN权限不足。
  • 解决：进入仓库 “Settings” -> “Actions” -> “General”。在 “Workflow permissions” 部分，选择 “Read and write permissions”。保存后，重新运行失败的工作流。

• 问题2：状态页面显示“全部服务运行正常”，但我知道某个服务已经挂了

  • 现象：页面显示绿色，但直接访问服务失败。
  • 排查：
    1. 检查.upptimerc.yml中该站点的配置，特别是url是否正确。
    2. 去 “Actions” 里查看最近一次工作流运行的日志，找到对应站点的检查步骤，看具体的响应状态码和响应内容是什么。可能服务返回了非200状态码，但Upptime配置的expectedStatusCodes包含了它。
    3. 检查是否配置了expectedBodyText而内容不匹配。
  • 解决：根据日志调整配置。可以临时将expectedStatusCodes只设为[200]来严格检查。

• 问题3：GitHub Pages 页面打开空白或样式错乱

  • 现象：自定义域名或路径后，页面无法正常加载。
  • 排查：
    1. 检查CNAME文件是否已正确提交并存在于gh-pages分支根目录。
    2. 检查浏览器控制台（F12）是否有加载资源的网络错误（如CSS、JS文件404）。
    3. 可能是浏览器缓存。尝试强制刷新（Ctrl+F5）或隐身模式访问。
  • 解决：确保site配置中的status-website地址与最终访问地址完全一致。清除GitHub Pages缓存（在Pages设置底部有清除按钮）。

• 问题4：监控频率感觉不够快

  • 现象：服务中断后，状态页面需要几分钟后才变红。
  • 分析：这是由schedule.interval决定的。GitHub Actions的定时任务并非精确执行，可能有几分钟的延迟。这是免费方案的权衡。
  • 建议：对于需要近实时告警的核心服务，不应只依赖Upptime。可以将其作为“状态记录与展示”平台，同时搭配其他更实时的监控告警工具（如自建的Prometheus Alertmanager，或云厂商的告警服务）进行互补。Upptime的核心价值在于历史记录和公开透明。

5.3 个人实操心得与进阶建议

经过一年多的生产环境使用，我总结了几点心得：

1. 监控点选择比数量更重要：不要只监控首页。监控一个专门的、轻量的健康检查端点（/health或/status）是最佳实践。这个端点应该检查应用的核心依赖，如数据库连接、缓存连接、第三方关键API连通性等，并返回一个包含这些组件状态的JSON。然后让Upptime去检查这个端点，并断言返回的JSON中包含"overallStatus": "OK"。这样一次检查就能反映服务的真实健康度。
2. 利用Issue进行故障复盘：Upptime自动创建的Issue是一个完美的故障报告起点。我们团队的习惯是，一旦收到告警（我们集成了Slack），负责人会立即响应，并在这个自动创建的Issue下进行沟通。修复后，除了Upptime自动关闭，我们还会手动在Issue评论中追加一份简短的根因分析（RCA）和后续行动项。这个Issue线程就成了可搜索的故障知识库。
3. 将状态页作为DevOps文化的一部分：把状态页的链接放在官网页脚、登录页面、文档首页，甚至API的响应头里。这传递出一种对稳定性和透明度的承诺。当出现问题时，主动引导用户查看状态页，可以极大减少客服压力和用户的负面情绪。
4. 备份你的配置：你的监控列表和配置是宝贵的资产。定期备份.upptimerc.yml文件。可以考虑将其同步到另一个私有仓库或配置管理工具中。

最后，Upptime的魅力在于它用极简的方式，将开源生态中的免费工具串联起来，解决了一个实际且普遍的需求。它可能不是功能最强大的，但一定是性价比最高、最易于上手和维护的方案之一。当你看到那个自动更新、记录着服务每一天脉搏的状态页面时，你会感受到自动化运维带来的那份踏实与从容。