企业官网建设流程全解析

Shots Studio 是一款 AI 驱动的 Android 截图管理应用。它有一个巧妙的“服务器消息系统”：不搭建任何后端服务器，仅靠 GitHub Pages 托管的静态 JSON 文件，就能向所有用户推送版本公告、更新提醒和紧急通知。本文将带你完整理解这套轻量级消息推送架构的设计思路与实现细节。

为什么用 GitHub Pages 做消息推送？

传统 App 推送公告需要后端 API、数据库、鉴权、运维，成本不低。而 Shots Studio 的思路是：公告本身就是一个静态文件。

• 🆓零成本：GitHub Pages 对公开仓库免费，无需运维；
• 🔒更安全：没有后端接口，就不存在接口被攻击、用户数据被采集的问题；
• 📝有版本记录：公告内容通过 git 提交，每次修改都有历史记录，改错了随时回滚；
• ⚡高可用：静态文件托管的稳定性远高于自建服务。

对独立开发者来说，这套方案几乎是"零基础设施"的优雅解法。项目仓库页面中，docs目录就是消息文件的托管位置：

系统架构：三个核心组件

整个消息系统由三个部分组成，职责清晰：

其中核心逻辑都集中在 ServerMessageService 这个类里：它负责发起请求、解析 JSON、按规则筛选出"该展示给当前用户的那一条消息"。官方架构文档见 SERVER_MESSAGES.md。

消息文件怎么组织：按版本分目录

消息文件的组织方式是这套架构的亮点。根目录下有一个全局兜底文件：

docs/ ├── messages.json # 全局兜底消息（所有版本通用） ├── 1.8.115/ │ └── messages.json # 专属于 1.8.115 版本的消息 ├── 1.9.70/ │ └── messages.json # 专属于 1.9.70 版本的消息 └── [版本号]/ └── messages.json

App 启动后，会根据自身版本拼接出动态 URL，例如 1.8.115 版本会先请求.../shots-studio/1.8.115/messages.json。这样做的好处：

1. 精准投放：可以给 1.8.90 用户单独推送"该版本不再支持，请立即升级"的警告，而不打扰新版用户；
2. 自动兜底：如果版本专属文件不存在（404），系统自动回退到全局 messages.json，老版本用户依然能收到通用公告；
3. 渐进迁移：新版本启用专属目录后，旧版本继续走兜底文件，平滑过渡。

这套机制的详细说明见 VERSION_SPECIFIC_MESSAGES.md，实际消息文件可以在 docs/messages/ 目录下看到按版本归档的完整记录。

一条消息能配置哪些能力？

打开 docs/messages.json 可以看到真实的消息配置，每条消息支持这些关键字段：

过滤逻辑在 _processMessages 中执行：服务会按show→beta_only→platform→version→valid_until→show_once的顺序逐条检查，命中全部条件的第一条消息才会被展示。这意味着一条公告可以从"发布"到"过期"完全自动管理，无需人工下线。

版本定向的匹配规则非常灵活，相关实现在 _isVersionTargeted：

{ "version": "ALL" } // 推送给所有版本 { "version": "1.8.115" } // 只推给 1.8.115 { "version": "1.8.*" } // 通配符，推给整个 1.8.x 系列

请求时机与防打扰设计

消息检查并不是无节制地发起的，系统有多层防打扰机制：

• 触发时机：App 启动时（在隐私弹窗和 API 配置完成后）检查一次；从后台恢复前台时，由 background_service.dart 触发后台检查；
• 30 分钟冷却：两次请求间隔不足 30 分钟直接跳过，见 _requestCooldown；
• show-once 持久化：标记为只展示一次的消息，展示后会把message_shown_{id}写入本地偏好，用户不会被反复弹窗骚扰；
• 用户总开关：设置页的"Advanced"区域提供了 Server Messages 开关（见 server_messages_toggle.dart），用户可以一键关闭所有服务器消息；
• 优雅降级：网络错误、超时、JSON 格式错误等情况只记录日志，绝不打断用户正常使用。

双源容灾：GitHub Pages + GitLab 兜底

这套系统还有一个容易被忽略的细节——消息源本身做了双活容灾。服务里维护了一个 URL 列表，依次尝试：

static const List<String> baseUrls = [ 'https://ansahmohammad.github.io/shots-studio/messages', 'https://gitlab.com/mohdansah10/shots-studio/-/raw/main/docs/messages', ];

如果 GitHub Pages 源不可用（例如仓库维护期间），系统会自动切换到 GitLab 镜像源，保证公告通道始终畅通——项目里确实出现过 GitHub 仓库临时下线、通过 GitLab 镜像维持公告推送的真实案例：

总结

Shots Studio 的服务器消息系统证明了：小团队做用户公告，不一定要造轮子搭后端。它的核心经验可以概括为四句话：

1. 静态文件即接口——一个 JSON 文件就是整个"消息服务"；
2. 按版本分目录——精准投放 + 自动兜底，兼顾新老用户；
3. 声明式配置——过期时间、展示次数、目标渠道全部写在文件里，自动化管理；
4. 多源 + 冷却 + 总开关——容灾、防打扰、尊重用户选择一个不少。

如果你想为自己的 App 实现类似功能，这套"GitHub Pages + JSON + 版本目录 + 客户端过滤链"的架构，是一个非常值得抄的作业。