Webamp 皮肤博物馆 SQLite 数据库设计全解:Winamp Skin Museum 的表结构、数据流与迁移实践

原创2026-09-22 19:46:561,904 阅读
文章标签:前端音视频

Webamp 皮肤博物馆 SQLite 数据库设计全解:Winamp Skin Museum 的表结构、数据流与迁移实践

导读

本文以 packages/skin-database/docs/database.md 为骨架,系统剖析驱动 Winamp Skin Museum(以及配套的 Twitter 机器人、Discord 机器人)的 SQLite 数据库:它不随仓库分发,而是独立维护的一份生产数据副本。你将掌握每一张表的作用、关键字段与业务含义,理解"皮肤文件 + md5 指纹"如何串起截图、审核、推文、归档、搜索与排序等完整数据流,并从 migrations 与 data/ 的源码实现中获得可直接引用的调用链证据。

数据库整体定位:一份"不随仓库分发"的 SQLite 库

数据库是 Winamp Skin Museum 及周边项目(Twitter 机器人、Discord 机器人)的单一数据源。文档明确指出:

该 SQLite 数据库不包含在本仓库中,需要一份副本请直接联系维护者。

但它完全由本仓库中的代码驱动:连接配置、表结构迁移、读写逻辑全部开源。连接方式见 knexfile.ts:

  • 生产/开发环境:client: "sqlite3",数据库文件为 process.cwd() 下的 ./skins.sqlite3;
  • 测试环境:使用内存库 connection: ":memory:",并在 seeds/test_data.ts 中灌入 a_fake_md5、an_approved_md5、a_nsfw_md5 等假数据,覆盖各类审核/推文状态;
  • 迁移表名固定为 knex_migrations,迁移目录为 migrations;
  • 运行入口 db.ts 依据 NODE_ENV(默认 production)选择配置,其余密钥(Algolia、Twitter、Discord、Bluesky 等)统一来自 .env,见 config.ts。

贯穿全局的主键设计:几乎所有业务表都通过 skin_md5(skins.md5)关联皮肤,而非自增 id。 文档作者也坦承这是一处待改进的设计("We should probably fix that and use id"),在 SkinModel.ts 的注释里同样能看到这类自嘲(如 getMd5() 注释 "This is not the md5 of the file itself. Consider renaming this to getSkinMd5")。理解这一点,是读懂后续所有表的前提。

核心表:skins——博物馆的"主表"

skins 表是整座博物馆的入口:博物馆中每个条目对应一行 skin_type = 1(classic)的记录。

字段 类型/取值 说明
id INTEGER PK 自增主键,但"没怎么被真正使用"(文档原话)
md5 TEXT UNIQUE 皮肤文件的 md5 哈希,其余表通过 skin_md5 引用它
skin_type 1 / 2 / 3 / 4 1=classic,2=modern,3=pack,4=invalid
emails BLOB/TEXT 从皮肤文本文件中提取的邮箱列表(空格分隔)
readme_text BLOB/TEXT 用启发式识别出的 readme 类文本内容
average_color TEXT 已废弃,见迁移 remove_average_color.ts
content_hash TEXT 后续迁移追加的内容指纹(见下文)

源码侧 SKIN_TYPE 枚举定义在 data/skins.ts:CLASSIC: 1, MODERN: 2, PACK: 3, INVALID: 4。而 SkinModel.ts 的 getSkinType() 目前只处理 1 与 2,其余类型会抛错——这与"博物馆只展映 classic 皮肤"一致。

content_hash 是一个值得注意的衍生字段:setContentHash()(data/skins.ts)将皮肤压缩包内每个文件按 文件名:文件md5 排序后拼接再取 md5,用于判断"内容是否真正变化"(例如重传同款皮肤)。同时 SkinRow 类型定义在 types.ts,readme_text 在其中已被注释掉,提示该项目正在逐步把 readme 相关的取值逻辑转移到 file_info 表(见下文)。

皮肤压缩包解析:archive_files 与 file_info

每款皮肤本质是一个 zip 压缩包(.wsz/.wal/.zip)。数据库会解包并记录包内每个文件:

archive_files(每个皮肤压缩包中的每个文件一行):

字段 说明
id 文件记录的唯一 ID
skin_md5 所属皮肤的 md5
file_name 文件在压缩包内的路径
file_md5 文件解压后的 md5
file_date zip 元数据中的创建日期
uncompressed_size 解压后大小 已废弃,改查 file_info
text_content 文本文件内容 已废弃,改查 file_info
is_directory (bool) 是否为目录

file_info(按文件内容去重后的归一化元数据):

字段 说明
id 唯一 ID
file_md5 文件 md5(对应 archive_files.file_md5)
file_date zip 元数据中的创建日期
size_in_bytes 解压后大小
text_content 文本文件内容

设计动机:大量皮肤包含相同的资源文件(如 main.bmp),因此将文件级信息按 file_md5 归一化到 file_info,一份数据服务所有皮肤。写入逻辑在 skinHash.ts 的 setHashesForSkin():先用 getFileData 遍历 zip(通过扩展名启发式 mightBeText 判断是否提取文本,见 skinHash.ts),先清空该皮肤的旧 archive_files 再逐行插入;随后将非目录文件按 file_md5 去重写入 file_info(skinHash.ts)。读取侧 ArchiveFileModel.ts 通过 _getFileInfo() 把两个表串起来,对外暴露 size、text_content、is_directory 等 GraphQL 字段。

schema 演进也印证了文档的"废弃"标记:

文件溯源:files 表

files 表记录"皮肤文件本身"的来源:同一份皮肤(按内容 md5 去重)可能以不同文件名出现多次,此表保存我们见过的每一种文件名及获取途径。

字段 说明
id 唯一 ID
file_path 皮肤文件的目录+文件名
skin_md5 皮肤 md5
source_attribution 文件来源(如上传者),可能缺失

写入路径在 data/skins.ts 的 addSkin():向 skins 插入一行(md5 + skin_type),再向 files 插入 file_path 与 source_attribution(上传者)。seeds/test_data.ts 中可见 Zelda_Amp_3.wsz 这类示例文件名。

用户上传流水线:skin_uploads 表

博物馆允许用户直接上传皮肤,但其架构刻意做成"异步 + 任务队列"式,以应对流量尖峰:

  1. 用户先按皮肤 md5 请求一个上传 URL(状态 URL_REQUESTED);
  2. 文件直传 S3(R2)后通知服务端(状态 UPLOAD_REPORTED);
  3. 服务端按空闲容量下载并截图/入库,最终落到 ERRORED(失败)或 ARCHIVED(成功)。
字段 说明
id 本次上传尝试的唯一 ID,同时用作 S3 文件名
skin_md5 上传文件的 md5;注意并非所有记录都会进入 skins 表(上传未完成/处理失败/根本不是皮肤)
status ERRORED / UPLOAD_REPORTED / URL_REQUESTED / ARCHIVED
filename 用户上传时的原始文件名(S3 上以 id 命名,故需在此记录原名)

状态机操作全部集中在 data/skins.ts:

  • recordUserUploadRequest() 插入 URL_REQUESTED 并返回 id;
  • recordUserUploadComplete() 将 URL_REQUESTED 更新为 UPLOAD_REPORTED;
  • getReportedUpload() 轮询 UPLOAD_REPORTED 记录作为待处理队列;
  • 消费方 api/processUserUploads.ts 中的 processUserUploads() 逐条从 S3 取文件,调用 addSkin.ts 的 addSkinFromBuffer() 完成截图与入库,成功调 recordUserUploadArchived(),失败调 recordUserUploadErrored();reprocessFailedUploads() 则会重新捞起 ERRORED 记录重试。

截图流水线:screenshot_updates 表

博物馆的核心特色是每款 classic 皮肤的"统一截图"。截图由 shooter.js 驱动:它启动 Puppeteer 打开 webamp.org(?screenshot=1 模式),把 .wsz 皮肤上传进 Webamp 页面后对 #main-window 截图,再用 optipng 压缩后上传 S3/R2。

screenshot_updates 表记录每次重拍的结果,供系统判断"哪些皮肤需要重拍/哪些渲染失败":

字段 说明
id 唯一 ID
update_timestamp 截图拍摄时间
skin_md5 被更新的皮肤 md5
success (bool) 是否成功
error_message (string) 截图失败时的错误信息

写入逻辑在 data/skins.ts 的 recordScreenshotUpdate():errorMessage 为 null 时记 success: 1,否则记 0 与错误信息。Shooter.takeScreenshot() 内部把超时(默认 30s)、页面 dialog、页面 error 都捕获并调用该函数回写(shooter.js)。配套的 getSkinsToShoot()(data/skins.ts)通过 LEFT JOIN screenshot_updates 找出"从未拍过"的皮肤批量补拍。截图文件最终存于 https://r2.webampskins.org/screenshots/{md5}.png(见 data/skins.ts 的 URL 构造与 tasks/screenshotSkin.ts 的 screenshot() 完整流程:校验 md5 → 临时文件 → 拍摄 → 上传 S3 → 清理 CloudFlare 缓存)。

审核与推文准入:skin_reviews 表

Twitter 机器人在推文前,皮肤必须先经过 Discord 服务器中的人工审核,以控制内容质量并避免在 Twitter 上分享 NSFW 皮肤。同时被标记 NSFW 的皮肤在博物馆会被模糊处理并降权。

字段 说明
id 唯一 ID
skin_md5 被审核皮肤 md5
review REJECTED / APPROVED / NSFW 之一
reviewer 审核人(经常缺失)

特别注意:当皮肤被标记为 NSFW 时,机器人会同时写入 NSFW 与 REJECTED 两条审核记录。这一点在 Discord 机器人的实现中可以直接验证——discord-bot/utils.ts 中处理 🔞 表情时先调用 Skins.markAsNSFW()(写入 NSFW 并更新 Algolia 的 nsfw 字段),紧接着调用 Skins.reject()(写入 REJECTED)。👍/👏 对应 approve(),👎/😔 对应 reject(),三种操作均把 ctx.username 作为 reviewer 写入(data/skins.ts)。

审核状态如何驱动推文流水线?data/skins.ts 的 getSkinToTweet() 用四表 JOIN(skins ⋈ skin_reviews ⋈ tweets ⋈ files ⋈ refreshes)挑选"已 APPROVED、未推过、刷新无错误"的 classic 皮肤,随机取一条交给 tasks/tweet.ts 推送。SkinModel.getTweetStatus()(SkinModel.ts)则按优先级 TWEETED > NSFW > REJECTED > APPROVED > UNREVIEWED 推导状态,供 Discord 展示(discord-bot/utils.ts)。

推文数据:tweets 表(与 Instagram/Mastodon/Bluesky 表)

Twitter 机器人 @winampskins 的推文数据存放在 tweets 表:

字段 说明
id 本地唯一 ID
likes 点赞数
retweets 转发数
skin_md5 被推皮肤的 md5(注意:并非所有推文都关联皮肤)
tweet_id Twitter 分配的 ID,可用于拼接推文 URL

文档明确提示两点数据质量边界:点赞/转发每天夜间抓取,且 Twitter API 只能回溯最近推文,因此这些数字是下界(lower bound);另外机器人也发过人工推文/转推,不一定都有 skin_md5。对应地,TweetModel.ts 的 getUrl() 由 tweet_id 拼出 https://twitter.com/winampskins/status/{tweet_id}(早期只记录"推过哪些皮肤",没有 tweet_id 时 URL 为 null),getLikes()/getRetweets() 缺省返回 0。抓取与更新逻辑(upsertTweet 风格,有则更新 likes/retweets,无则插入)位于 data/skins.ts 附近。迁移 unique_tweet_ids.ts 为 tweet_id 建立了唯一索引,remove_tweet_url.ts 则删除了最初的 url 列(因为可由 tweet_id 推导)。

类似的"发帖索引"表还有三张同构的 instagram_posts、mastodon_posts、bluesky_posts:

字段 说明
id 本地唯一 ID
skin_md5 所发皮肤的 md5
post_id 平台分配的帖子 ID(唯一)
url 帖子链接(唯一)

文档提到 Instagram 机器人(@winampskins 创建该表,missing_instagram_posts.ts 回填了 14 条历史发帖数据;mastodon_posts.ts 与 bluesky_posts.ts 则对应后起平台。写入函数 markAsTweeted / markAsPostedToInstagram / markAsPostedToMastodon / markAsPostedToBlueSky 并排定义在 data/skins.ts,体现了"同构表,多平台适配"的演进脉络。

搜索与 Algolia 同步:algolia_field_updates 表

博物馆站内搜索由第三方 Algolia 驱动,皮肤数据在变化时被推送上去。为了支持"按字段级失效与重建索引",每次向 Algolia 推送某个字段都会在此记录一条:

字段 说明
id 本次更新的唯一 ID
update_timestamp 字段推送时间
field 被更新的搜索索引字段名
skin_md5 皮肤 md5

写入侧:recordSearchIndexUpdates() 把本次推送的每个字段名各插一行(data/skins.ts);updateSearchIndexes() 用 Algolia 的 partialUpdateObjects 批量推送并记录(data/skins.ts)。Algolia 客户端在 algolia.ts 中初始化,索引名来自 ALGOLIA_INDEX 环境变量。可查询侧 searchIndexUpdatesForSkin() 按时间倒序返回该皮肤的历史字段更新(data/skins.ts)。搜索索引对象 SearchIndex(data/skins.ts)的字段非常丰富:nsfw、tweetStatus、fileName、twitterLikes、equalizer、playlist、browser、media、general、video、cur、ani、transparentPixels、mikro、vidamp、avs——这些布尔能力均由 SkinModel 的正则探测方法(hasEqualizer()、hasAVS() 等,见 SkinModel.ts)计算得出。

值得一提:2025 年的迁移 search_index.ts 额外引入了一张本地 SQLite FTS5 虚拟表 skin_search(skin_md5, readme_text, file_names),并创建 5 个触发器在 skins/files 增删改时自动维护,用于本地全文检索 readme 与文件名——这是文档成文后新增的演进证据。

归档与存档:ia_items 表

博物馆中每款皮肤都会被定期(每日)持久化到 Internet Archive 以便长期保存,ia_items 是本地缓存:

字段 说明
id 本地唯一 ID
skin_md5 皮肤 md5
identifier 归档条目的唯一标识(用于条目 URL 与 API 查询)
metadata Internet Archive 返回的元数据 JSON blob
metadata_timestamp 上次抓取元数据的时间

读写逻辑见 IaItemModel.ts:getMetadataJSON() 读取缓存 JSON,updateMetadata() 先通过 hasRunningTasks() 判断归档侧是否仍有运行中的任务,确认空闲后才调用 fetchMetadata() 更新缓存并写 metadata_timestamp(IaItemModel.ts);invalidateMetadata() 会把缓存置空以便强制重抓。元数据列与时间戳列分别由迁移 ia_metadata.ts 与 ai_metadata_timestamp.ts 追加。批次补抓任务见 tasks/syncFromArchive.ts 的 fillMissingMetadata()(筛选 metadata 为空的行逐个更新)。

周期刷新:refreshes 表

数据库中有大量数据是从皮肤压缩包中派生出来的(文件清单、readme、截图等),但皮肤原文件存放在 S3/R2 而非本地,因此只能周期性下载并重新抽取。refreshes 记录每次刷新:

字段 说明
id 唯一 ID
skin_md5 皮肤 md5
error 刷新时遇到的错误
timestamp 刷新时间(默认当前时间)

任务实现见 tasks/refresh.ts:

  • getSkinsToRefresh() 用 skins LEFT JOIN refreshes,按 refreshes.timestamp 升序取最久未刷新的 N 个 classic 皮肤(neverDone 参数可只取从未刷新过的);
  • refreshSkins() 通过 Shooter.withShooter() 批量处理并在处理完一处删除模型引用以释放内存(皮肤 zip 会被整体缓存);
  • _refresh() 依次执行:验证 zip 可解压 → setHashesForSkin()(重算 archive_files/file_info)→ setContentHash() → 校验 skin_type(必须为 CLASSIC,否则抛 "Skin type mismatch")→ 重拍截图 → 写一条成功记录;
  • 任何异常都在 refresh() 中被捕获并以 error: e.message 写入 refreshes(tasks/refresh.ts),后续查询即可据 refreshes.error IS NULL 过滤掉"截图无效"的皮肤。

轻量状态存储:key_value 表

对某些 cron 任务与异步任务,需要跟踪任意状态且对效率不敏感,于是提供一个整块覆盖的 KV 存储:

字段 说明
key 键(唯一)
value 值(通常是整个覆盖的 JSON blob)

封装类 data/KeyValue.ts 提供 get<T>()(JSON.parse 反序列化)与 set()(存在则 update、不存在则 insert,均以 JSON 字符串存储)。典型用法见 SkinModel.ts:抓不到某款 modern 皮肤时,把 md5 追加进 missingModernSkins 键,实现"问题清单"的持久化。对应迁移为 key_value_store.ts。

博物馆排序:museum_sort_overrides 与 museum_sort_order

museum_sort_overrides 用于人工编辑决策,影响皮肤在博物馆主滚动流中的位置:

字段 说明
id 本地唯一 ID
skin_md5 被覆盖的皮肤 md5
score 排名分:负数表示隐藏该皮肤
comment 排名原因说明

用途有两类(文档原话):提升默认皮肤(如 Base、Winamp3/5 Classified、Bento),以及手动剔除重复皮肤(如 Garfield、Vault-tec、Fallout、Microchip、Doom、Mtn Dew 的重复款)。迁移 museum_overrides.ts 在创建表的同时预置了这批人工数据(13 条,score 从 5 到 -1)。hideSkin()(data/skins.ts)即插入一条 score: -1 的覆盖记录。

排序的"秘密配方"在 museumOrder.sql 中(由 computeMuseumOrder() 在事务里先清空 museum_sort_order 再整体重算,见 data/skins.ts):

  1. 人工策展皮肤(museum_sort_overrides.score DESC,默认皮肤排最前);
  2. 已推文皮肤按 Twitter 热度 (likes + retweets * 1.5) 排序(tweet_score DESC);
  3. NSFW 压底(review = 'NSFW' ASC);
  4. 已 APPROVED 优于未审核(review = 'APPROVED' DESC);
  5. 被 REJECTED 垫底(review = 'REJECTED' ASC)。

同时 WHERE 条件会过滤掉 museum_sort_overrides.score <= 0 与 refreshes.error IS NOT NULL 的皮肤。museum_sort_order 表(迁移 museum_sort.ts)保存这份预计算结果;博物馆分页 getMuseumPage() 直接按序切片(data/skins.ts),而新式滚动流 getScrollPage() 则混入 20% 随机皮肤(FRESHNESS_PERCENTAGE = 0.2,每页 50 条)并借助 session/session_skin 表去重(data/skins.ts)。

会话与行为日志:session / session_skin / user_log_events(文档之后的新表)

文档成文后,仓库又通过迁移引入了三张面向"新式滚动流个性化"的表,可以作为理解该项目演进方向的补充:

  • session(id, start_time) 与 session_skin(session_id, skin_md5)(session_tables.ts):记录每个浏览会话看过哪些皮肤,用于滚动流去重;
  • user_log_events(id, session_id, timestamp, metadata)(user_log_events.ts):以 JSON 记录 skin_view_end、readme_expand、skin_download、skin_like、share_success 等用户事件。消费方 tasks/computeScrollRanking.ts 按会话聚合这些事件,并用加权公式 viewDuration*0.1/s + like*10 + download*5 + share*15 + readmeExpand*2 计算皮肤排名分数,为滚动流排序提供行为学依据。

迁移基础设施:knex_migrations 与 knex_migrations_lock

这两张表由 Knex 自动维护:knex_migrations 记录已执行迁移的元数据,knex_migrations_lock 保证迁移被串行、正确地应用。全套 23 个迁移文件按时间戳命名,位于 migrations,从 2020 年的 init 一路演进到 2025 年的搜索索引与会话表,既是 schema 变更史,也是理解每张表字段来源的第一手资料。初始建表 SQL 见 20201118171554_init.ts(含 files、ia_items、tweets、skins、skin_reviews、nsfw_predictions、algolia_field_updates、archive_files、skin_uploads、screenshot_updates 及若干 skin_md5 索引),被删除的 nsfw_predictions 表(机器学习 NSFW 预测,见 remove_predictions.ts)也印证了文档"这些均为人工审核"的现状。

结语:一张图看懂整条数据流

把所有表串起来,Winamp Skin Museum 的数据流可以概括为:

  1. 入库:用户上传 → skin_uploads 状态机(URL_REQUESTED → UPLOAD_REPORTED → ARCHIVED/ERRORED)→ addSkin() 写入 skins + files;
  2. 解析:setHashesForSkin() 解包 zip 写入 archive_files 与去重后的 file_info,setContentHash() 生成内容指纹;
  3. 截图:Puppeteer 经 shooter.js 拍图上传 S3/R2,结果回写 screenshot_updates;
  4. 审核:Discord 机器人在 discord-bot 中审查,结果写入 skin_reviews(NSFW 会额外写一条 REJECTED);
  5. 外发:通过审核的皮肤经 getSkinToTweet() 交给 Twitter/Instagram/Mastodon/Bluesky 机器人,发帖索引写入对应平台表,tweets 表记录点赞/转发;
  6. 搜索:字段级推送 Algolia 并登记到 algolia_field_updates,同时 FTS5 虚拟表 skin_search 承担本地全文检索;
  7. 归档:每日同步到 Internet Archive,ia_items 缓存元数据;
  8. 刷新与排序:refreshes 驱动周期性重解析/重截图,museum_sort_overrides + museum_sort_order 决定展示顺序,session/user_log_events 支撑个性化滚动流。

这套以 md5 为全局主键、以"异步任务 + 状态表"解耦重活、以 Knex 迁移管理 schema 演进的 SQLite 设计,是理解 skin-database 包(以及其配套 GraphQL 查询入口 api/graphql 与测试种子 seeds/test_data.ts)的完整地图。读者若需在生产中部署或复刻同类"内容库型"数据库,可直接参照本文各表结构与 migrations 的建表 SQL 落地。

登录后查看全文
webamp