Wallpaper Gallery Architecture
01 / 12
Open Source Architecture Briefing

WALLPAPER GALLERY

Wallpaper Gallery

开源壁纸网站架构

围绕最终成品站，拆解上传后台、自动化工作流与图床仓库如何协同支撑内容生产、版本发布和前端展示。

展示重点 为什么前台网站能持续更新、可追踪版本、可统计热门。
核心视角 以 Wallpaper Gallery 为中心，反向拆解背后 3 个支撑项目。
前台主角 Wallpaper Gallery

统一承接浏览、筛选、下载、SEO 与热门排行展示。

上传入口 Studio

AI 分类、批量上传、权限控制、工作流触发。

自动化中枢 Workflow

缩略图生成、时间戳维护、元数据处理、发布与回滚。

内容源头 nuanXinProPic

原图、预览图、metadata、data、Bing 数据与版本历史。

支撑能力

上传、处理、分发、统计 四条能力链共同服务同一个网站。

Wallpaper Gallery
02 / 12

先看主角：Wallpaper Gallery 到底负责什么

它面向的是最终用户，所以它的设计重点不是“怎么上传”，而是“怎么稳定展示、怎么快、怎么利于 SEO、怎么把内容消费掉”。

用户入口 浏览、搜索、筛选、预览、下载统一发生在这里。
内容消费层 消费图床仓库导出的 `data/` 与 `bing/meta/`，而不是动态拼主内容。
统计上报层 把浏览和下载行为写入 Supabase，再反哺热门排行。

网站直接承担的职责

  • 渲染桌面、手机、头像、Bing 四个系列页面。
  • 在部署阶段拉取图床仓库的 `data/` 和 `bing/meta/` 作为静态数据源。
  • 生成对搜索引擎友好的静态页面与可访问路由。
  • 把浏览与下载行为写入 Supabase，支撑热门排行功能。
  • 负责用户可见的交互体验，包括筛选、弹窗、预览、下载与 SEO 页面组织。

网站刻意不做的事情

  • 不直接处理上传，不做原图生产。
  • 不在运行时现算主内容数据，而是消费预先生成好的 JSON。
  • 不承担图片衍生资源生成，不负责发版 tag 与 release。
  • 不把动态统计数据库反向作为主内容源。
  • 不把“内容真相”保存在当前仓库，而是把展示站严格限制为消费层。
用户输入 访问与下载
→
前端行为 拉取 JSON + 渲染页面
→
后台配合 上报 Supabase 统计
→
最终结果 稳定展示和热门排行
System Overview
03 / 12

整体协作关系

从内容生产视角看，这是一套四层系统：操作入口、自动化编排、内容源仓库、前端展示站。

操作入口

Studio

接住人类上传动作，把文件、AI 分类与任务信息送进系统。

外部补充源

Gitee / Bing

并行提供每日内容与额外图源，补充图床仓库。

自动化编排 Workflow

负责图片处理、时间戳、metadata 合并、版本发布、回滚治理。

内容真相 nuanXinProPic

保存原图、衍生图、metadata、data、bing/meta 与 stats，作为单一事实来源。

用户可见层

Wallpaper Gallery

消费图床数据，构建页面、承接浏览下载、输出最终网站体验。

行为统计层

Supabase

只管记录行为与聚合排行，不反向承担主内容数据职责。

主链路 Studio → Workflow → nuanXinProPic → Wallpaper Gallery
并行支线 Bing / Gitee 补内容，Supabase 补统计，但两者都不取代主内容源。
wallpaper-gallery-studio
04 / 12

Studio：把人工上传变成结构化输入

这个项目的价值在于，它把“同事上传图片”这件原本很随意的事情，变成可控、可追踪、可接入工作流的标准化流程。

输入

用户选择图片

上传前先做格式、大小、权限和重复记录校验。

处理

AI 与本地预处理

做压缩、Hash 去重、类型识别，再调用 AI 生成系列、分类、关键词、描述与文件名建议。

输出

原图 + pending metadata

原图进入目标目录，批量生成 `metadata-pending/*.json` 作为工作流输入。

协同

触发 Workflow

用 GitHub `repository_dispatch` 把这次上传正式送进自动化链路。

Studio 实际解决的业务问题

  • 把人工上传动作转成标准化、可追踪的任务。
  • 把高交互的 AI 分类前置到后台，而不是留给离线工作流瞎猜。
  • 把原图提交与元数据提交拆成“同一次操作、两类产物”，便于后续处理。
  • 把工作流触发交给后台用户，而不是要求人工再去 GitHub 页面补一步。
上传前 压缩、查重、预览、路径选择。
上传中 文件逐个写入图床仓库，支持失败重试。
上传后 生成 pending metadata，留给 workflow 合并进正式体系。
边界约束 不直接生成缩略图、不直接发布、不承担前端部署。

为什么这样设计

  • AI 分类是高交互环节，适合放在可视化后台，而不是工作流里盲跑。
  • 先上传原图，再生成 metadata-pending，能把“文件提交”和“结构化描述”绑定成一次任务。
  • Studio 只负责发起，不负责长任务执行，减少页面阻塞与失败面。

它的边界

  • 不生成缩略图和预览图。
  • 不负责最终 metadata 合并。
  • 不负责前端部署。
  • 不负责图床版本号和 release 管理。
wallpaper-gallery-workflow
05 / 12

Workflow：整个发布链的自动化中枢

如果没有这个项目，Studio 上传之后就只是“文件进仓库了”。真正把新图加工成正式内容版本、并保证能追踪和回滚的，是 Workflow。

它接收的输入

  • 来自 Studio 的 `process-wallpapers` 触发事件。
  • 图床仓库里的新增原图。
  • `metadata-pending` 里的 AI 分类结果。
  • 历史 tag、timestamps、metadata、stats.json。

它产出的结果

  • 缩略图和预览图。
  • 新的版本 tag 与 GitHub Release。
  • 更新后的 timestamps、metadata、data、stats.json。
  • 可回滚、可追踪的正式发布状态。
repository_dispatch → process-new-images → create-tag → update-timestamps → verify → process-metadata → publish-release
自动化价值 把图片处理、版本创建和数据补齐从人工步骤变成稳定流水线。
治理价值 支持中断恢复、重复运行、回滚和发布者记录，适合长期维护。
开源价值 上传后台和前端站都不需要掌握完整发布细节，只需要接入它。
Workflow Deep Dive
06 / 12

Workflow 的具体业务步骤

这些脚本不是随便排顺序的，而是围绕“版本基线、内容补全、数据一致性”三个目标设计出来的。

process-new-images.sh 通过 Git diff 只处理新增图片，生成 thumbnail 和 preview，避免全量扫描。随着仓库变大，仍能把耗时控制在新增文件范围内。
create-tag.sh 先提交和打 tag，建立版本基线，并带有中断恢复逻辑。后面所有 metadata、release、首发记录都会引用这个版本。
update-timestamps.sh 把新图写入 `timestamps-backup-all.txt`，记录首次出现时间与首发 tag。它是内容追溯和回滚的重要索引。
verify-*.sh 校验时间戳与数据完整性，减少缩略图漏生成、元数据漏补齐的问题，让自动化流程更像“可治理系统”而不是“脚本拼盘”。
process-metadata.js 一方面合并 Studio 写入的 `metadata-pending`，另一方面从 timestamps 同步直接进仓库的图片，再生成 `data/`。它同时统一“后台上传流”和“直接同步流”。
publish-release.sh 回写 `stats.json`，记录发布者，提交统计文件，并创建 GitHub Release。到这一步内容才真正成为正式版本。

为什么先打 tag 再处理 metadata

这样生成 metadata 时就能写入正确的 `cdnTag` 和首发版本信息，前端以后追溯某张图属于哪个版本时不会丢上下文。

为什么 process-metadata 要读 timestamps

因为不只有 Studio 会写入图片，Gitee 同步或其他直接入仓方式也会产生新图。读 timestamps 能把“绕过后台”的内容补进统一 metadata 体系。

nuanXinProPic
07 / 12

nuanXinProPic：整个系统的单一事实来源

这里不只是放原图，还保存衍生资源、元数据、前端 JSON、Bing 数据、发布时间线和版本历史。前端和工作流都把它当作最终内容状态。

资产层

  • `wallpaper/` 原图
  • `thumbnail/` 列表缩略图
  • `preview/` 详情预览图
  • 为前端提供所有图片资源的最终来源。

元数据层

  • `metadata/` 最终元数据
  • `metadata-pending/` 中间态元数据
  • `timestamps-backup-all.txt` 首发记录
  • 支持从 AI 上传流和外部同步流统一补齐。

消费层

  • `data/` 前端 JSON 分片
  • `bing/meta/` Bing 系列元数据
  • `stats.json` 发布统计与历史
  • 提供给前端部署与开源使用者直接消费。

为什么叫“单一事实来源”

  • 前端部署时拉的是它。
  • 工作流处理完成后写回的是它。
  • Bing 定时同步沉淀的是它。
  • 回滚时删除和恢复的也是它。

为什么不把 data 直接放前端仓库维护

  • 前端仓库应专注界面与构建，不应承载主内容真相。
  • 图床仓库更适合作为版本化内容源，方便 CDN、tag、release 和回滚。
  • 内容与界面分离后，排障边界会清晰很多。
Wallpaper Gallery Deploy
08 / 12

Wallpaper Gallery 的部署流程

前端站点的部署流程，核心思想是“构建时吃入图床数据”，而不是“运行时依赖后端接口”。这非常适合静态站点、CDN 和 SEO。

步骤 1 获取最新 CDN 版本

读取 `nuanXinProPic` 最新 tag，并同步到前端常量配置。

步骤 2 checkout 图床仓库

在 GitHub Actions 中直接拉取图床内容源，建立构建时数据基线。

步骤 3 复制 `data/` 与 `bing/meta/`

把主系列和 Bing 的 JSON 分片复制到 `public/data/`，让前端构建产物自带内容。

步骤 4 构建 SEO 页面并发布

执行 `build:seo` 后发布到 Cloudflare Pages，生成最终可访问站点。

这样做的好处

  • 对搜索引擎更友好，静态内容可直接被抓取。
  • 站点运行时不依赖图床仓库接口，降低外部波动影响。
  • 页面首次打开更快，内容可借助 Pages 和 CDN 分发。
  • Bing 与主系列都能在同一套静态数据体系里管理。

用户视角的结果

  • 访问时看到的是已经就绪的数据和资源。
  • 即使内容源临时不可访问，已部署站点仍能正常浏览。
  • 站点更稳定，缓存命中率更高，SEO 页面也更完整。
Analytics Pipeline
09 / 12

热门统计是另一条并行链路

Wallpaper Gallery 既展示内容，也记录用户行为。但行为统计不会反过来成为主内容源，而是独立写入 Supabase，再定时导出成静态排行 JSON。

统计链路怎么走

  • 用户浏览预览图或下载壁纸时，前端上报行为事件。
  • Supabase 存储下载、浏览及聚合统计。
  • `export-stats.yml` 定时调用 `export-stats.js`。
  • 生成 `public/data/stats/*.json`，由前端页面读取并展示热门排行。
  • 前端依然消费静态排行 JSON，不让数据库直接侵入页面主内容链。

为什么不用统计系统直接当内容数据库

  • 统计数据是动态的、行为驱动的，不适合承载全量内容结构。
  • 图床数据强调稳定和可版本化，统计数据库强调查询和聚合。
  • 两者解耦后，即使统计服务异常，网站主内容仍然可用。
内容链路 nuanXinProPic → public/data → 页面展示
统计链路 用户行为 → Supabase → stats JSON → 热门排行
End-to-End Flow
10 / 12

从同事上传，到用户看到新壁纸

这一页把四个项目真正串成一条业务链路，方便第一次接触系统的人快速建立完整心智模型。

1

Studio 上传并 AI 分类

2

原图与 pending metadata 写入 nuanXinProPic

3

Workflow 生成缩略图、时间戳、metadata、data

4

Workflow 创建 tag / release / stats

5

Wallpaper Gallery 部署时拉取最新内容

6

用户浏览下载，统计数据回流 Supabase

内容生产 Studio 和 Workflow 负责让图片从“文件”变成“正式版本内容”。
内容消费 Wallpaper Gallery 只消费图床已准备好的稳定 JSON 与资源。
行为回流 Supabase 记录用户行为，补充热门排行，而不改动主内容链路。
Why This Design
11 / 12

为什么这套系统要拆成四个项目

从开源视角看，这种拆分不是为了“做复杂”，而是为了让每一层都可以独立维护、独立替换、独立部署。

这样拆的收益

  • 前端展示和内容生产解耦，任何一边出问题不会直接拖垮另一边。
  • 图床仓库天然适合做 CDN、tag、release 和内容版本管理。
  • Workflow 可以重跑和回滚，便于运维与自动化审计。
  • Studio 可以单独演进 AI 能力，而不影响内容源结构。
  • 内容与界面分离后，开源用户也更容易按需裁剪和组合。

对开源用户意味着什么

  • 可以替换图床仓库实现，但保留前端站。
  • 可以替换 AI Provider，但上传后台流程仍成立。
  • 可以只部署前端 + 图床，后续再接入 Workflow。
  • 也可以把 Supabase 换成自己的统计实现，而不动主内容链路。
  • 每一层都更容易单独阅读、单独 Fork、单独替换。
前端层 保证用户体验与 SEO。
后台层 承接 AI 与上传交互。
工作流层 保证发布治理和自动化。
图床层 保证内容真相与版本沉淀。
一句话总结设计思想

让 Wallpaper Gallery 始终保持“面向用户的纯展示站”定位，把复杂性有意识地下沉到支撑项目里。

Open Source Showcase
12 / 12

感谢观看，这个开源壁纸系统架构展示

Wallpaper Gallery 是面向用户的成品站，Studio、Workflow、nuanXinProPic 是背后的内容生产系统。你可以直接访问网站体验，也可以按需 Fork 任意一层进行二次开发。

如果这套开源系统对你有帮助

欢迎访问项目主页，点一个 Star 支持，或者直接 Fork 开始你的二次开发。你的反馈、Issue 和 PR 都会帮助这个项目继续成长。

Star Wallpaper Gallery Fork 主仓库