Webamp 皮肤博物馆 SQLite 数据库设计全解:Winamp Skin Museum 的表结构、数据流与迁移实践
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 演进也印证了文档的"废弃"标记:
- 迁移 archive_file_content.ts 曾为
archive_files追加uncompressed_size与text_content; - 迁移 add_file_contents_table.ts 新建
file_info表承接这些数据; - 迁移 add_archive_file_timestamp.ts 与 archive_file_is_directory.ts 分别补充
file_date、is_directory字段。
文件溯源: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 表
博物馆允许用户直接上传皮肤,但其架构刻意做成"异步 + 任务队列"式,以应对流量尖峰:
- 用户先按皮肤 md5 请求一个上传 URL(状态
URL_REQUESTED); - 文件直传 S3(R2)后通知服务端(状态
UPLOAD_REPORTED); - 服务端按空闲容量下载并截图/入库,最终落到
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):
- 人工策展皮肤(
museum_sort_overrides.score DESC,默认皮肤排最前); - 已推文皮肤按 Twitter 热度
(likes + retweets * 1.5)排序(tweet_score DESC); - NSFW 压底(
review = 'NSFW' ASC); - 已 APPROVED 优于未审核(
review = 'APPROVED' DESC); - 被 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 的数据流可以概括为:
- 入库:用户上传 →
skin_uploads状态机(URL_REQUESTED → UPLOAD_REPORTED → ARCHIVED/ERRORED)→addSkin()写入skins+files; - 解析:
setHashesForSkin()解包 zip 写入archive_files与去重后的file_info,setContentHash()生成内容指纹; - 截图:Puppeteer 经 shooter.js 拍图上传 S3/R2,结果回写
screenshot_updates; - 审核:Discord 机器人在 discord-bot 中审查,结果写入
skin_reviews(NSFW 会额外写一条REJECTED); - 外发:通过审核的皮肤经
getSkinToTweet()交给 Twitter/Instagram/Mastodon/Bluesky 机器人,发帖索引写入对应平台表,tweets表记录点赞/转发; - 搜索:字段级推送 Algolia 并登记到
algolia_field_updates,同时 FTS5 虚拟表skin_search承担本地全文检索; - 归档:每日同步到 Internet Archive,
ia_items缓存元数据; - 刷新与排序:
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 落地。