<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <id>https://docs.skinloom.cn/devlog</id>
    <title>云织 SkinLoom Blog</title>
    <updated>2026-11-19T00:00:00.000Z</updated>
    <generator>https://github.com/jpmonette/feed</generator>
    <link rel="alternate" href="https://docs.skinloom.cn/devlog"/>
    <subtitle>云织 SkinLoom Blog</subtitle>
    <icon>https://docs.skinloom.cn/img/logo.svg</icon>
    <entry>
        <title type="html"><![CDATA[双轨插件平台、官方签名市场与首批官方扩展收官]]></title>
        <id>https://docs.skinloom.cn/devlog/dual-tier-plugins-and-market</id>
        <link href="https://docs.skinloom.cn/devlog/dual-tier-plugins-and-market"/>
        <updated>2026-11-19T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[云织 SkinLoom 插件与主题平台（P2-1 ~ P2-6）已全部完成基建验收、独立市场上线及首批官方扩展落地，apiVersion 1 正式冻结。]]></summary>
        <content type="html"><![CDATA[<p>云织 SkinLoom 插件与主题平台（P2-1 ~ P2-6）已全部完成基建验收、独立市场上线及首批官方扩展落地，<strong><code>apiVersion: 1</code></strong> 与 <strong><code>native.protocolVersion: 1</code></strong> 正式冻结。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="本期完成">本期完成<a href="https://docs.skinloom.cn/devlog/dual-tier-plugins-and-market#%E6%9C%AC%E6%9C%9F%E5%AE%8C%E6%88%90" class="hash-link" aria-label="本期完成的直接链接" title="本期完成的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>双轨插件运行时（ADR 0045–0049）</strong>：
<ul>
<li class=""><strong>Tier 1（<code>runtime: "js"</code>）</strong>：进程内 QuickJS/WASM 确定性沙箱池、指令燃料/内存硬限、25 组 <code>ctx.*</code> 宿主 API、47 个 Hook（21 Guard / 7 Filter / 19 Event）、20 个前端插槽、5 个声明式表单扩展点与 Level ⑤ 主题组件覆盖。</li>
<li class=""><strong>Tier 2（<code>runtime: "native"</code>）</strong>：基于 <code>hashicorp/go-plugin</code> 双向 gRPC 子进程、<code>sdk/go</code>、<code>sdk/go/plugindb</code> 三方言隔离 SQL 数据库（<code>plg_&lt;id&gt;_</code> 规范前缀）、<code>sdk/go/plugintest</code> 进程内测试套件、本地 HTTP/SSE/WebSocket 流式反代与 <code>Storage</code>/<code>Search</code>/<code>Render</code> 底层驱动扩展。</li>
</ul>
</li>
<li class=""><strong>官方静态签名插件市场（ADR 0050）</strong>：
<ul>
<li class="">独立维护 <a href="https://github.com/Entropy-Increase-Team/skinloom-registry" target="_blank" rel="noopener noreferrer" class=""><code>Entropy-Increase-Team/skinloom-registry</code></a>：纯源码 Commit SHA 登记、差量 PR 安全门禁、真实源码检出与 <code>plugin.json</code> 一致性核验、受保护环境 5 平台交叉编译 + 官方 Ed25519 私钥签名与 <code>blocked.yaml</code> 恶意包全网自动热禁用。</li>
<li class="">宿主侧完成 <code>RegistryClient</code>、五维环境兼容匹配、拓扑依赖级联安装、多架构集群按需回源、后台「插件市场」与外观页「浏览主题市场」UI 及 <code>skinloom plugin search / market-install / upgrade</code> CLI。</li>
</ul>
</li>
<li class=""><strong>独立官方插件库与首批 5 个官方扩展（<code>skinloom-plugins</code>）</strong>：
<ul>
<li class="">Tier 1 JS 沙箱插件：<code>invitation-codes</code>、<code>mojang-verification</code>、<code>texture-description</code>；</li>
<li class="">Level ⑤ 示范主题：<code>theme-atelier</code>（完整覆盖 L1–L5 与 <code>site.footer</code> / <code>texture.card</code> 组件覆盖）；</li>
<li class="">Tier 2 Native Go 插件：<code>bs-importer</code>（遵循方案 A，按需安装、迁完可卸载，直连 BS 数据库或对接升级后的 <code>blessing-skin-export-bridge</code> 补迁第三方 BS 插件扩展表）。</li>
</ul>
</li>
<li class=""><strong>文档站定稿</strong>：补齐 TS 插件快速入门、Go 原生插件进阶指南、主题 L1–L5 指南与 API v1.0 参考手册。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="关键架构决策">关键架构决策<a href="https://docs.skinloom.cn/devlog/dual-tier-plugins-and-market#%E5%85%B3%E9%94%AE%E6%9E%B6%E6%9E%84%E5%86%B3%E7%AD%96" class="hash-link" aria-label="关键架构决策的直接链接" title="关键架构决策的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><a class="" href="https://docs.skinloom.cn/adr/0045-plugin-storage-slots-and-jsrt-pool">ADR 0045</a> · <a class="" href="https://docs.skinloom.cn/adr/0046-plugin-host-extensions-and-sdk-toolchain">ADR 0046</a> · <a class="" href="https://docs.skinloom.cn/adr/0047-frontend-plugin-runtime-and-theme-overrides">ADR 0047</a> · <a class="" href="https://docs.skinloom.cn/adr/0048-plugin-package-signing-and-cluster-hot-reload">ADR 0048</a> · <a class="" href="https://docs.skinloom.cn/adr/0049-dual-tier-plugin-architecture-grpc-and-isolated-db">ADR 0049</a> · <a class="" href="https://docs.skinloom.cn/adr/0050-gitops-signed-plugin-market-and-multi-arch-distribution">ADR 0050</a>。</li>
<li class=""><strong>三仓职责解耦</strong>：<code>skinloom</code>（核心服务 + 前端 + SDK/CLI）、<code>skinloom-plugins</code>（官方插件与主题源码）、<code>skinloom-registry</code>（GitOps 静态签名索引与受控分发）。</li>
<li class=""><strong>Blessing Skin 迁移两层分离（方案 A）</strong>：核心账号/角色/材质/密钥/设置保留在主程序 Pre-Core 安装向导与离线 CLI（进入正常模式后零运行时开销）；BS 第三方插件扩展表迁移通过可卸载 Tier 2 插件 <code>bs-importer</code> + 跨插件服务闭环完成。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/dual-tier-plugins-and-market#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<ul>
<li class="">推送 <code>skinloom-plugins</code> 独立仓库并在 <code>skinloom-registry</code> 配置正式离线 Ed25519 签名密钥与 <code>production-signing</code> 环境；</li>
<li class="">通过 PR 将首批 5 个官方扩展上架至官方市场，完成云端 Runner 5 平台编译与线上实测闭环；</li>
<li class="">准备 SkinLoom v1.1.0 正式发布。</li>
</ul>]]></content>
        <category label="devlog" term="devlog"/>
        <category label="P2" term="P2"/>
        <category label="plugins" term="plugins"/>
        <category label="market" term="market"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 37 期 · 前端重构 P5：收尾、无障碍检查与首屏体积审计]]></title>
        <id>https://docs.skinloom.cn/devlog/frontend-p5</id>
        <link href="https://docs.skinloom.cn/devlog/frontend-p5"/>
        <updated>2026-11-17T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[前端重构系列收官阶段（P5 收尾，对应设计文档 07 §8–§10 与 ADR 0042）：完成全站无障碍盘点与修复、多宽度多主题 Playwright 冒烟脚本落地，以及对照 P0 前代码的首屏 JS 与中文字体真实传输体积审计。]]></summary>
        <content type="html"><![CDATA[<p>前端重构系列收官阶段（P5 收尾，对应<a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/docs/design/07-frontend-redesign.md" target="_blank" rel="noopener noreferrer" class="">设计文档 07</a> §8–§10 与 <a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/docs/adr/0042-frontend-design-system.md" target="_blank" rel="noopener noreferrer" class="">ADR 0042</a>）：完成全站无障碍盘点与修复、多宽度多主题 Playwright 冒烟脚本落地，以及对照 P0 前代码的首屏 JS 与中文字体真实传输体积审计。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="无障碍系统检查与修复">无障碍系统检查与修复<a href="https://docs.skinloom.cn/devlog/frontend-p5#%E6%97%A0%E9%9A%9C%E7%A2%8D%E7%B3%BB%E7%BB%9F%E6%A3%80%E6%9F%A5%E4%B8%8E%E4%BF%AE%E5%A4%8D" class="hash-link" aria-label="无障碍系统检查与修复的直接链接" title="无障碍系统检查与修复的直接链接" translate="no">​</a></h2>
<p>对照 WCAG 结构与键盘可达性规则对所有页面和 <code>@skinloom/ui</code> 组件做了一轮排查，修掉了以下问题：</p>
<ul>
<li class=""><strong>跳到正文与唯一 <code>&lt;main&gt;</code> 地标</strong>：在 <code>(site)</code>、<code>(app)</code> 外壳及 404 页面统一接入 <code>&lt;SkipLink /&gt;</code>（<code>#main</code>，使用 <code>bg-popover</code> / <code>--shadow-popover</code> token 与 <code>scroll-mt-14</code>）；修复之前 <code>&lt;SidebarInset&gt;</code> 与内层 <code>&lt;main&gt;</code> 嵌套渲染出两个 <code>&lt;main&gt;</code> 地标的错误。</li>
<li class=""><strong>地标与控件可读名称</strong>：<code>HeaderNav</code>、<code>MobileMenu</code>、<code>AppSidebar</code>、<code>AppTabNav</code> 与组件总览锚点导航补齐 <code>aria-label</code>；<code>AppSidebar</code> 菜单项补齐 <code>aria-current="page"</code>，后台设置中心分组切换按钮补 <code>aria-current</code>；<code>UsageMeter</code> 的 <code>role="meter"</code> 通过 <code>useId()</code> 关联可见标签（<code>aria-labelledby</code>）并提供格式化 <code>aria-valuetext</code>。</li>
<li class=""><strong>页面主标题层级</strong>：<code>CardTitle</code> 增加 <code>as</code> 属性支持，登录、注册、找回/重设密码、邮箱验证、第三方绑定、首次安装和 OAuth 授权页面全部以 <code>&lt;h1&gt;</code> 输出主标题；<code>SkinViewer</code> 已在上一阶段将 <code>role="img"</code> 移至 <code>&lt;canvas&gt;</code> 而不再包裹工具栏按钮。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="首屏-js-体积优化与-p0-前基线实测对比">首屏 JS 体积优化与 P0 前基线实测对比<a href="https://docs.skinloom.cn/devlog/frontend-p5#%E9%A6%96%E5%B1%8F-js-%E4%BD%93%E7%A7%AF%E4%BC%98%E5%8C%96%E4%B8%8E-p0-%E5%89%8D%E5%9F%BA%E7%BA%BF%E5%AE%9E%E6%B5%8B%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="首屏 JS 体积优化与 P0 前基线实测对比的直接链接" title="首屏 JS 体积优化与 P0 前基线实测对比的直接链接" translate="no">​</a></h2>
<p>在 Chromium 1228 无缓存冷启动下，使用 <code>1280×800</code> 视口对比了重构前基线提交（<code>7a7f569</code>）与当前版本的真实网络传输：</p>
<ol>
<li class=""><strong>发现并修复 <code>@skinloom/ui</code> 桶文件泄漏</strong>：排查 chunk 清单时发现 <code>/skinlib</code> 与所有用户/后台页因为同时引入未标注客户端边界的服务端/纯组件与 <code>export *</code> 桶文件，把未使用的 <code>cmdk</code>（<code>102.4 KB</code>）与 <code>Accordion</code>（<code>74.4 KB</code>）等模块一起打了进去。将 <a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/web/packages/ui/src/index.ts" target="_blank" rel="noopener noreferrer" class="">index.ts</a> 改为显式命名导出并在 <code>next.config.ts</code> 启用 <code>experimental.optimizePackageImports: ['@skinloom/ui']</code> 后，<code>/skinlib</code> 消除 6 个冗余 chunk，首屏 JS 从 <code>1148.5 KB</code> 降至 <strong><code>888.4 KB</code>（立减 <code>260.1 KB</code> / <code>-22.7%</code>）</strong>。</li>
<li class=""><strong>与重构前基线对比（原始字节 / gzip）</strong>：
<ul>
<li class=""><code>/</code>：<code>565.3 KB</code>（<code>167.6 KB</code> gzip） → <code>1594.4 KB</code>（<code>454.8 KB</code> gzip，新增了异步加载的 <code>three</code> + <code>skinview3d</code> 约 <code>620 KB</code> 用于 3D 走秀）；</li>
<li class=""><code>/skinlib</code>：<code>567.1 KB</code>（<code>168.3 KB</code> gzip） → <code>888.4 KB</code>（<code>276.0 KB</code> gzip，<code>+56.6%</code>）；</li>
<li class=""><code>/skinlib/show/1</code>：<code>1083.1 KB</code>（<code>295.9 KB</code> gzip） → <code>1633.0 KB</code>（<code>468.1 KB</code> gzip，<code>+50.8%</code>）；</li>
<li class=""><code>/about</code>：<code>559.4 KB</code>（<code>165.3 KB</code> gzip） → <code>876.6 KB</code>（<code>272.2 KB</code> gzip，<code>+56.7%</code>）；</li>
<li class=""><code>/auth/login</code>：<code>568.1 KB</code>（<code>168.8 KB</code> gzip） → <code>896.9 KB</code>（<code>279.8 KB</code> gzip，<code>+57.9%</code>）。</li>
<li class="">未启用 3D 的公开页多出的约 <code>317 KB</code> 原始 JS（约 <code>107 KB</code> gzip）主要来自 ADR 0042 选定的 Base UI 交互层、<code>@tanstack/react-query</code> 与 <code>sonner</code>（替换了原先原生 <code>&lt;select&gt;</code>、<code>window.confirm</code> 与手写状态请求），无法压在 <code>+20%</code> 以内，已如实记录在 <a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/docs/adr/0042-frontend-design-system.md" target="_blank" rel="noopener noreferrer" class="">ADR 0042</a> 中。</li>
</ul>
</li>
<li class=""><strong>中文字体评估结论</strong>：<code>@fontsource-variable/noto-sans-sc</code> 在冷启动各页面按 <code>unicode-range</code> 仅下载 <code>10–13</code> 片（<code>565.1–743.7 KB</code>，首页为 <code>12</code> 片 <code>688.8 KB</code>），全部字体（含 Inter 与 JetBrains Mono）共 <code>612.2–830.2 KB</code>。由于标题、按钮与正文同时用到 <code>400</code>、<code>500</code> 与 <code>600</code> 字重，若改用双档静态字重反而会产生双份切片请求，故继续保留可变字体按需分片方案。</li>
</ol>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="多宽度双主题与亮暗模式自动化冒烟">多宽度、双主题与亮暗模式自动化冒烟<a href="https://docs.skinloom.cn/devlog/frontend-p5#%E5%A4%9A%E5%AE%BD%E5%BA%A6%E5%8F%8C%E4%B8%BB%E9%A2%98%E4%B8%8E%E4%BA%AE%E6%9A%97%E6%A8%A1%E5%BC%8F%E8%87%AA%E5%8A%A8%E5%8C%96%E5%86%92%E7%83%9F" class="hash-link" aria-label="多宽度、双主题与亮暗模式自动化冒烟的直接链接" title="多宽度、双主题与亮暗模式自动化冒烟的直接链接" translate="no">​</a></h2>
<p>新增可复用的 <code>web/scripts/smoke.mjs</code>（<code>bun run smoke</code>），并在 <code>default</code> / <code>brocade</code> 两种主题 × <code>light</code> / <code>dark</code> 两种模式 × <code>375</code> / <code>768</code> / <code>1280</code> 三种宽度 × 28 个公开、404 与登录后路由上完成 <strong>336 个视图组合</strong> 自动化巡检：</p>
<ul>
<li class=""><code>scrollWidth &lt;= clientWidth</code> 横向零溢出；</li>
<li class="">顶栏、<code>SkinViewer</code> 与导航地标（<code>aria-label</code>、<code>aria-current</code>）合规，并实测 Skip Link Tab 聚焦跳转 <code>#main</code> 及 <code>375px</code> 移动端抽屉开关交互；</li>
<li class="">全流程无控制台错误、无未捕获异常及非预期 HTTP 错误。</li>
</ul>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="frontend" term="frontend"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 36 期 · 前端重构 P4：本地主题目录、清单扩展与主题工具链]]></title>
        <id>https://docs.skinloom.cn/devlog/frontend-p4</id>
        <link href="https://docs.skinloom.cn/devlog/frontend-p4"/>
        <updated>2026-11-10T22:00:00.000Z</updated>
        <summary type="html"><![CDATA[完成前端重构计划（设计文档 07 §7、ADR 0043）的第四阶段 P4：站长无需重新编译即可在 /themes/ 下创建、校验、热加载自己的主题，并可使用单层继承、主题设置项与新的布局变体。]]></summary>
        <content type="html"><![CDATA[<p>完成前端重构计划（<a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/docs/design/07-frontend-redesign.md" target="_blank" rel="noopener noreferrer" class="">设计文档 07</a> §7、<a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/docs/adr/0043-local-themes-and-manifest-extensions.md" target="_blank" rel="noopener noreferrer" class="">ADR 0043</a>）的第四阶段 P4：站长无需重新编译即可在 <code>&lt;数据目录&gt;/themes/</code> 下创建、校验、热加载自己的主题，并可使用单层继承、主题设置项与新的布局变体。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="本地主题目录与热加载">本地主题目录与热加载<a href="https://docs.skinloom.cn/devlog/frontend-p4#%E6%9C%AC%E5%9C%B0%E4%B8%BB%E9%A2%98%E7%9B%AE%E5%BD%95%E4%B8%8E%E7%83%AD%E5%8A%A0%E8%BD%BD" class="hash-link" aria-label="本地主题目录与热加载的直接链接" title="本地主题目录与热加载的直接链接" translate="no">​</a></h2>
<ul>
<li class="">启动时依次加载内置主题（<code>default</code>、<code>brocade</code>）和 <code>&lt;数据目录&gt;/themes/*/plugin.json</code>。</li>
<li class="">单个本地主题清单或资源有误时不会影响站点启动，错误会记录在日志并直接显示在后台「外观 → 主题」对应的卡片上；若当前启用的主题失效则自动回退到 <code>default</code>。</li>
<li class="">本地主题的静态资源使用内容哈希地址（<code>/themes-assets/&lt;id&gt;/&lt;哈希&gt;/&lt;文件&gt;</code>），修改 <code>theme.css</code> 或图片无需手动改版本号即可生效；资源扩展名限定为样式、字体与图片，SVG 自动附带 <code>Content-Security-Policy: sandbox</code>。</li>
<li class="">支持三种热加载入口：后台「重新扫描」按钮、<code>skinloom theme reload</code> 命令，以及 <code>web.mode = dev</code> 下的文件监听，重新扫描后递增 <code>config_version</code> 并通过 SSE 刷新已打开的页面。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="清单扩展与布局变体">清单扩展与布局变体<a href="https://docs.skinloom.cn/devlog/frontend-p4#%E6%B8%85%E5%8D%95%E6%89%A9%E5%B1%95%E4%B8%8E%E5%B8%83%E5%B1%80%E5%8F%98%E4%BD%93" class="hash-link" aria-label="清单扩展与布局变体的直接链接" title="清单扩展与布局变体的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><code>extends</code>：单层继承父主题的 token、样式表、布局、首页区块与设置项，只写差异即可完成一套新主题。</li>
<li class=""><code>screenshot</code> 与 <code>theme.colorScheme</code>：支持 16:10 预览图；当主题声明仅支持 <code>light</code> 或 <code>dark</code> 时，前端自动锁定该模式并隐藏访客的亮暗切换。</li>
<li class="">相对路径重写：<code>viewer.background</code>、token 值里的 <code>url(assets/...)</code>、首页区块图片属性与图片设置项默认值中的 <code>assets/...</code> 自动解析为该主题的资源地址。</li>
<li class="">新布局变体：用户中心支持 <code>user: "tabs"</code>（水平标签导航栏），材质详情页支持 <code>texture: "stacked"</code>（上下叠放）。</li>
<li class=""><code>theme.settings</code> 与新设置 <code>theme.settings</code>：支持 <code>color</code>、<code>image</code>、<code>choice</code>、<code>text</code>、<code>boolean</code> 五种类型；带 <code>token</code> 的设置项直接写入对应 token，其余输出为 <code>--sl-setting-&lt;名称&gt;</code> 变量与 <code>html[data-sl-setting-&lt;名称&gt;]</code> 属性，后台「外观 → 主题设置」自动生成表单。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="工具链契约测试与文档">工具链、契约测试与文档<a href="https://docs.skinloom.cn/devlog/frontend-p4#%E5%B7%A5%E5%85%B7%E9%93%BE%E5%A5%91%E7%BA%A6%E6%B5%8B%E8%AF%95%E4%B8%8E%E6%96%87%E6%A1%A3" class="hash-link" aria-label="工具链、契约测试与文档的直接链接" title="工具链、契约测试与文档的直接链接" translate="no">​</a></h2>
<ul>
<li class="">新增 <code>skinloom theme new &lt;id&gt; [--extends default]</code>、<code>skinloom theme check &lt;dir&gt;</code>（按 WCAG 2.1 检查文字与背景对比度并给出警告）与 <code>skinloom theme reload</code>。</li>
<li class="">后台「外观」页整理为六个标签页（主题、主题设置、颜色、首页、标识与页脚、自定义代码），「颜色」页支持将当前配色调整一键「导出为主题」下载 <code>.zip</code> 主题包。</li>
<li class="">前端新增 Cascade Layer 契约测试与挂钩契约测试（<code>web/design.md</code> §14），补齐 <code>website/static/schema/plugin.v1.json</code> 与文档站「开发主题」指南。</li>
</ul>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="frontend" term="frontend"/>
        <category label="theme" term="theme"/>
        <category label="cli" term="cli"/>
        <category label="design-system" term="design-system"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 33 期 · 前端重构 P1：组件库]]></title>
        <id>https://docs.skinloom.cn/devlog/frontend-p1</id>
        <link href="https://docs.skinloom.cn/devlog/frontend-p1"/>
        <updated>2026-11-10T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[上一期打好了设计系统的地基，这一期把组件库补齐：]]></summary>
        <content type="html"><![CDATA[<p>上一期打好了设计系统的地基，这一期把组件库补齐：</p>
<ul>
<li class="">shadcn/ui 的 44 个基础组件装进 <code>@skinloom/ui</code>，按设计系统调了尺寸、圆角和颜色；</li>
<li class="">皮肤站自己的十几个组件，包括首页那个"皮肤在走路"的展示区；</li>
<li class="">后台多了一个组件总览页，主题作者改完颜色可以在这里一眼核对。</li>
</ul>
<p>页面本身还是老样子，下一期开始换外壳（顶栏、侧栏、手机菜单）。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="基础组件用-cli-装再按规矩改">基础组件：用 CLI 装，再按规矩改<a href="https://docs.skinloom.cn/devlog/frontend-p1#%E5%9F%BA%E7%A1%80%E7%BB%84%E4%BB%B6%E7%94%A8-cli-%E8%A3%85%E5%86%8D%E6%8C%89%E8%A7%84%E7%9F%A9%E6%94%B9" class="hash-link" aria-label="基础组件：用 CLI 装，再按规矩改的直接链接" title="基础组件：用 CLI 装，再按规矩改的直接链接" translate="no">​</a></h2>
<p>基础组件用 <code>shadcn add</code> 一次装了 44 个，底层是 Base UI。shadcn 的组件代码就放在仓库里，可以随便改。不过我们只改尺寸、圆角、颜色、阴影和动效，代码风格保持上游的样子，以后能用 <code>shadcn add --diff</code> 对照上游的更新：</p>
<ul>
<li class="">按钮和输入框从 32px 高改为 36px，触屏上 40px；圆角从 10px 改为 8px；</li>
<li class="">按下时缩到 0.98，不再往下挪 1 像素；过渡写明属性，不用 <code>transition-all</code>；</li>
<li class="">浮层的阴影换成主题 token，遮罩换成新 token <code>overlay</code>；</li>
<li class="">徽章不再是胶囊形，加了"成功""警告"两种；</li>
<li class="">分段控件选中时用主色淡底，原来的灰底在白卡片上几乎看不出来。</li>
</ul>
<p>改的时候踩了几个坑，都在组件总览页上一眼看出来了：</p>
<ul>
<li class=""><strong>滑块没有轨道。</strong> 组件里写的是 <code>data-horizontal:h-1</code>，Tailwind 把它理解成 <code>[data-horizontal]</code> 属性，而 Base UI 实际设的是 <code>data-orientation="horizontal"</code>。这个对应关系在 <code>shadcn/tailwind.css</code> 里，<code>shadcn init</code> 会帮你引进来，手写样式表时就漏了。我们照 <code>shadcn eject</code> 的做法，把用到的几段抄进了 <code>globals.css</code>。</li>
<li class=""><strong>链接被读成按钮。</strong> 用 <code>&lt;Button render={&lt;Link /&gt;}&gt;</code> 渲染链接，Base UI 会加 <code>role="button"</code>。现在链接一律用新加的 <code>ButtonLink</code>。</li>
<li class=""><strong>CSP 拦了一段脚本。</strong> Base UI 会在页面里放一小段内联脚本，没有 nonce 就被我们的内容安全策略挡掉了。用 Base UI 自带的 <code>CSPProvider</code> 把 nonce 交给它就好了。</li>
<li class=""><strong>CLI 装错了地方。</strong> 依赖装进了应用而不是 <code>packages/ui</code>，还装了一个名叫 <code>cn</code> 的无关 npm 包，导入路径也写成了应用的别名。都已手工改正。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="皮肤站自己的组件">皮肤站自己的组件<a href="https://docs.skinloom.cn/devlog/frontend-p1#%E7%9A%AE%E8%82%A4%E7%AB%99%E8%87%AA%E5%B7%B1%E7%9A%84%E7%BB%84%E4%BB%B6" class="hash-link" aria-label="皮肤站自己的组件的直接链接" title="皮肤站自己的组件的直接链接" translate="no">​</a></h2>
<p>皮肤在列表里一律用<strong>双面视图</strong>：后端 <code>/preview</code> 画的正反面，同一行里人物一样高。需要"活"的地方用<strong>单面视图</strong>，也就是 3D。</p>
<p>最复杂的是首页展示区 <code>SkinCarousel</code>：</p>
<ul>
<li class="">三个角色放在同一个 3D 画布里：当前的在走路，前一个、后一个缩小、半透明地站在两边。只开一个 WebGL 上下文，比开三个预览省得多；</li>
<li class="">每 6 秒换下一个，头像下面的进度条同步走；悬停或键盘焦点在里面时暂停，手动切换后停止自动播放；</li>
<li class="">系统设置了"减少动效"时，不走路也不自动轮播；</li>
<li class="">滚出屏幕时停止渲染。</li>
</ul>
<p>调的时候发现，把三个人一起转 30° 会让左边那个转到中间那个身后去，最后只让当前的那个转身。另外，小一号的角色是绕身体中心缩放的，脚会悬空，要往下挪 16 ×（1 − 0.62）个单位才能和中间的站在同一个地面上。</p>
<p>其它组件：确认对话框 <code>useConfirm()</code>（代替浏览器自带的确认框，最严重的操作要先输入邮箱）、复制字段、拖放上传、未保存提示条、用量条、状态点、相对时间、材质选择器……共享组件自己要显示的字（"复制""取消"）由网站按访客的语言统一提供，插件拿到的是同一套。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="组件总览页">组件总览页<a href="https://docs.skinloom.cn/devlog/frontend-p1#%E7%BB%84%E4%BB%B6%E6%80%BB%E8%A7%88%E9%A1%B5" class="hash-link" aria-label="组件总览页的直接链接" title="组件总览页的直接链接" translate="no">​</a></h2>
<p><code>/admin/appearance/preview</code> 把上面这些全摆出来：颜色 token、字号、各种按钮、表单、弹层、皮肤组件和菜单图标，右上角可以切亮暗。在默认主题和织锦主题、桌面和 375px 宽度下都过了一遍。织锦主题里实心的"删除"（深红）和主色（朱红）离得有点近，记下了，收尾时再调。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下一期">下一期<a href="https://docs.skinloom.cn/devlog/frontend-p1#%E4%B8%8B%E4%B8%80%E6%9C%9F" class="hash-link" aria-label="下一期的直接链接" title="下一期的直接链接" translate="no">​</a></h2>
<p>P2 外壳：新顶栏（手机上收进菜单）、用户中心和后台的侧栏、认证页外壳。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="frontend" term="frontend"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 34 期 · 前端重构 P2：外壳]]></title>
        <id>https://docs.skinloom.cn/devlog/frontend-p2</id>
        <link href="https://docs.skinloom.cn/devlog/frontend-p2"/>
        <updated>2026-11-10T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[这一期换的是"框"：顶栏、页脚、用户中心和后台的侧栏、登录页的外框。页面内容还是旧的，下一期 P3 逐页重做。]]></summary>
        <content type="html"><![CDATA[<p>这一期换的是"框"：顶栏、页脚、用户中心和后台的侧栏、登录页的外框。页面内容还是旧的，下一期 P3 逐页重做。</p>
<ul>
<li class="">手机上顶栏不再溢出：375px 宽度下，页面宽度从 434px 变回 375px；</li>
<li class="">用户中心第一次有了导航，后台从一排文字链接换成了分组侧栏；</li>
<li class="">访客、登录用户、管理员看到的顶栏各不相同，各自只放用得到的东西。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="路由分组">路由分组<a href="https://docs.skinloom.cn/devlog/frontend-p2#%E8%B7%AF%E7%94%B1%E5%88%86%E7%BB%84" class="hash-link" aria-label="路由分组的直接链接" title="路由分组的直接链接" translate="no">​</a></h2>
<p>以前根布局给所有页面都套上同一个顶栏和页脚，用户中心和后台没法换成侧栏布局。现在用 Next.js 的路由分组拆开了，网址一个都没变：</p>

























<table><thead><tr><th>分组</th><th>页面</th><th>外框</th></tr></thead><tbody><tr><td><code>(site)</code></td><td>首页、皮肤库、关于、登录注册、首次安装</td><td>页宽 1200px 的顶栏 + 页脚</td></tr><tr><td><code>(app)/user</code></td><td>用户中心</td><td>全宽顶栏 + 侧栏</td></tr><tr><td><code>(app)/admin</code></td><td>管理后台</td><td>全宽顶栏 + 侧栏</td></tr></tbody></table>
<p>OAuth 授权页 <code>/user/oauth/authorize</code> 虽然在 <code>/user</code> 下面，却是给第三方应用跳转过来用的单独页面，放在 <code>(site)</code> 里，不带侧栏。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="顶栏">顶栏<a href="https://docs.skinloom.cn/devlog/frontend-p2#%E9%A1%B6%E6%A0%8F" class="hash-link" aria-label="顶栏的直接链接" title="顶栏的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>访客</strong>：网站链接，右边是"语言与外观"、文字链接"登录"、唯一的实心按钮"注册"。</li>
<li class=""><strong>登录后</strong>：铃铛（有未读时是一个主色小圆点）和头像菜单。头像菜单里是用户中心的各页、管理后台（管理员）、语言与外观、退出登录。</li>
<li class=""><strong>手机</strong>：只剩标志、站名和一个菜单按钮，点开是右侧滑出的面板。</li>
</ul>
<p>原型里顶栏有个放大镜，最后没放：皮肤库自己有搜索框，一个只会跳到皮肤库的放大镜是假按钮。以后有全站搜索或命令面板时再加。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="侧栏">侧栏<a href="https://docs.skinloom.cn/devlog/frontend-p2#%E4%BE%A7%E6%A0%8F" class="hash-link" aria-label="侧栏的直接链接" title="侧栏的直接链接" translate="no">​</a></h2>
<p>用的是 shadcn 的 Sidebar，放在 56px 顶栏下面：</p>
<ul>
<li class="">分组标题、一列图标、当前页用主色淡底；</li>
<li class="">可以收起成 56px 的图标栏，选择记在 Cookie 里，下次打开还是那样；</li>
<li class="">没有记录时，平板宽度（不到 1024px）默认收起，手机上从顶栏的按钮滑出；</li>
<li class="">插件加的菜单（bootstrap 的 <code>menus.user</code>、<code>menus.admin</code>）放在最后的"扩展"分组。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="顺手修的">顺手修的<a href="https://docs.skinloom.cn/devlog/frontend-p2#%E9%A1%BA%E6%89%8B%E4%BF%AE%E7%9A%84" class="hash-link" aria-label="顺手修的的直接链接" title="顺手修的的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>共享组件里的英文</strong>：shadcn 的对话框、抽屉、分页、侧栏里有几处只给读屏软件看的英文（"Close"、"Toggle Sidebar"……），现在都跟着访客的语言走。</li>
<li class=""><strong>登录页面板</strong>：默认主题是像素格底板加上最近上传的三个皮肤，织锦主题保留朱红面板。第一版在平板宽度下三个皮肤放不下，最左边那个被挤出了面板，改成了随面板缩放。</li>
<li class=""><strong>首页布局被挤窄</strong>：给 <code>&lt;main&gt;</code> 加了 <code>flex-col</code> 之后，里面 <code>mx-auto</code> 的区块不再撑满宽度，首页的功能介绍被挤成了细长条。改回普通的块级元素就好了。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下一期">下一期<a href="https://docs.skinloom.cn/devlog/frontend-p2#%E4%B8%8B%E4%B8%80%E6%9C%9F" class="hash-link" aria-label="下一期的直接链接" title="下一期的直接链接" translate="no">​</a></h2>
<p>P3 页面：公开区（首页展示区、皮肤库、材质详情）→ 用户中心 → 后台，按原型和设计规则逐页重做，同时去掉所有浏览器自带的确认框和下拉框。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="frontend" term="frontend"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 35 期 · 前端重构 P3：重做全部页面]]></title>
        <id>https://docs.skinloom.cn/devlog/frontend-p3</id>
        <link href="https://docs.skinloom.cn/devlog/frontend-p3"/>
        <updated>2026-11-10T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[前三期把配色字体、组件库和顶栏侧栏立了起来，这一期把里面的页面全部重做一遍：]]></summary>
        <content type="html"><![CDATA[<p>前三期把配色字体、组件库和顶栏侧栏立了起来，这一期把里面的页面全部重做一遍：</p>
<ul>
<li class="">首页换上了"皮肤在走路"的展示区，其它区块去掉了模板化的卡片堆叠；</li>
<li class="">皮肤库、材质详情、上传页、用户中心和管理后台全部换用新组件；</li>
<li class="">全站 14 处浏览器自带的确认框、14 处原生下拉框全部清零，中英文文案按设计规则重写了一遍。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="公开区把位置让给皮肤">公开区：把位置让给皮肤<a href="https://docs.skinloom.cn/devlog/frontend-p3#%E5%85%AC%E5%BC%80%E5%8C%BA%E6%8A%8A%E4%BD%8D%E7%BD%AE%E8%AE%A9%E7%BB%99%E7%9A%AE%E8%82%A4" class="hash-link" aria-label="公开区：把位置让给皮肤的直接链接" title="公开区：把位置让给皮肤的直接链接" translate="no">​</a></h2>
<p>首页的 <code>hero</code> 区块现在有三种版式：</p>
<ul>
<li class=""><strong>左文右图（<code>split</code>，默认）</strong>：左边是站点名称、简介和按钮，右边是展示区，站内最新上传的 3 个公开皮肤轮流走出来。刚装好的空站还没有公开皮肤，会自动退回居中文字版式；</li>
<li class=""><strong>居中文字（<code>centered</code>）</strong>：不显示展示区；</li>
<li class=""><strong>背景大图（<code>banner</code>）</strong>：织锦主题用的就是这一种，保留它自己的朱红底色。</li>
</ul>
<p>版式和展示区的数据来源（最新、最受欢迎、不显示）都加进了后端的区块目录，站长在"外观 → 首页"里就能直接选。</p>
<p>首页其余几个区块也做了减法：公告不再是大卡片，改成顶栏下面的一条横幅；站点数据是一行安静的数字；功能介绍从四张等宽卡片改成左导语、右两栏列表；启动器引导改成带编号的三步，认证地址直接点按钮复制。</p>
<p>皮肤库的分类和排序换成了分段控件，仍然是普通链接，没有 JavaScript 也能筛选，手机上分类可以横向划动。材质详情页左边是占满高度的 3D 预览，右边除了收藏、穿到角色上、下载和哈希复制，还加了一块后端渲染的正反双面图——启动器和分享链接里看到的就是这张图。上传者的改名、改类型、设为私有和删除收进了右上角的菜单。上传页在大屏幕上左边实时显示 3D 预览，右边拖放图片并自动识别经典皮肤、纤细皮肤和披风。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="用户中心与管理后台">用户中心与管理后台<a href="https://docs.skinloom.cn/devlog/frontend-p3#%E7%94%A8%E6%88%B7%E4%B8%AD%E5%BF%83%E4%B8%8E%E7%AE%A1%E7%90%86%E5%90%8E%E5%8F%B0" class="hash-link" aria-label="用户中心与管理后台的直接链接" title="用户中心与管理后台的直接链接" translate="no">​</a></h2>
<p>用户中心概览不再写"欢迎，xxx"，顶部是四个统计卡（积分带金线图标）、最多三个角色的双面卡片、签到卡和站点公告。</p>
<p>角色页把原来的下拉框换成了衣柜选择器：点"选择皮肤"会弹出衣柜里的材质网格，看着正反面挑。衣柜页的每张卡片右上角有一个菜单按钮，可以设为头像、重命名（只改自己衣柜里的称呼）或移出衣柜。</p>
<p>个人资料页拆成了左说明、右卡片的几个分组；开发者页面用标签页分成"我的应用""已授权的应用""个人访问令牌"三块，新建密钥和令牌后只显示一次，配复制框。</p>
<p>后台的变化集中在表格和表单上：</p>
<ul>
<li class=""><strong>手机上不硬塞宽表格</strong>：用户和角色列表在手机宽度下变成卡片列表，桌面宽度下是表格；编辑用户和编辑角色都从行内展开改成了右侧滑出的面板；</li>
<li class=""><strong>底部保存条</strong>：外观的颜色与首页编辑器、翻译覆盖、站点设置中心，只要有改动，页面底部就会浮出"有未保存的修改 · 放弃 · 保存"；</li>
<li class=""><strong>确认框</strong>：所有 <code>window.confirm</code> 都换成了 <code>useConfirm()</code>，标题直接问要做的事，正文写清楚后果（比如删角色写明退不退积分，把材质设为私有写明会从别人的衣柜和角色上撤下）。注销账号和删除用户这两项不可恢复的操作，必须先输入邮箱才能点确认。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下一期">下一期<a href="https://docs.skinloom.cn/devlog/frontend-p3#%E4%B8%8B%E4%B8%80%E6%9C%9F" class="hash-link" aria-label="下一期的直接链接" title="下一期的直接链接" translate="no">​</a></h2>
<p>P4 主题系统：支持在 <code>data/themes/</code> 放本地主题并热加载，扩展主题清单（继承、主题设置、新布局变体），加上 <code>skinloom theme</code> 命令行工具和主题开发文档。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="frontend" term="frontend"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 32 期 · 前端重构开工：设计系统的地基]]></title>
        <id>https://docs.skinloom.cn/devlog/frontend-p0</id>
        <link href="https://docs.skinloom.cn/devlog/frontend-p0"/>
        <updated>2026-11-09T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[1.0 的前端功能齐全，但看起来像拼起来的：组件库只有 5 个组件，14 个地方弹浏览器自带的确认框，中文用的是各平台的系统字体，手机上顶栏会溢出。这期开始重做前端，先打地基：]]></summary>
        <content type="html"><![CDATA[<p>1.0 的前端功能齐全，但看起来像拼起来的：组件库只有 5 个组件，14 个地方弹浏览器自带的确认框，中文用的是各平台的系统字体，手机上顶栏会溢出。这期开始重做前端，先打地基：</p>
<ul>
<li class="">一套设计规则（<code>web/design.md</code>）和一份重构方案（设计文档 07），配了 Pencil 画的高保真原型；</li>
<li class="">新的配色与字体，换进两个内置主题；</li>
<li class="">TanStack Query、菜单图标表和一个拦住"写死颜色"的检查。</li>
</ul>
<p>页面本身这期还没动，下一期是组件库。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="先定方向再画原型">先定方向，再画原型<a href="https://docs.skinloom.cn/devlog/frontend-p0#%E5%85%88%E5%AE%9A%E6%96%B9%E5%90%91%E5%86%8D%E7%94%BB%E5%8E%9F%E5%9E%8B" class="hash-link" aria-label="先定方向，再画原型的直接链接" title="先定方向，再画原型的直接链接" translate="no">​</a></h2>
<p>方向一句话：<strong>界面安静克制，颜色和细节留给皮肤</strong>。皮肤站最好看的东西是皮肤本身，按钮、导航、表格都应该退到后面。</p>
<ul>
<li class="">颜色只有五种：中性灰、靛蓝（主色，取自蓝染布，呼应"云织"）、金线（积分、签到、警告）、成功绿、危险红。</li>
<li class="">标志性的细节是<strong>像素格</strong>：皮肤预览一律放在淡淡的棋盘格上，像图像编辑器显示透明区域，皮肤的镂空和第二层一眼就能看出来。</li>
<li class="">列表里的皮肤用<strong>双面视图</strong>（正面和背面并排，就是后端 <code>/preview</code> 现在画的样子），首页展示区和详情页用<strong>单面视图</strong>（skinview3d 的 3D 角色）。</li>
</ul>
<p>原型画了首页（桌面和手机）、用户中心、后台概览，评审时改了三处：列表改用双面视图；手机首页的展示区压矮；首页展示区改成"当前皮肤在走路、前后两个半透明陪衬、每 6 秒轮播"。动画规则写在原型旁边的说明板和 <code>design.md</code> §9.5 里。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="配色是算出来的">配色是算出来的<a href="https://docs.skinloom.cn/devlog/frontend-p0#%E9%85%8D%E8%89%B2%E6%98%AF%E7%AE%97%E5%87%BA%E6%9D%A5%E7%9A%84" class="hash-link" aria-label="配色是算出来的的直接链接" title="配色是算出来的的直接链接" translate="no">​</a></h2>
<p>每个颜色都用 OKLCH 写，再换算成 sRGB 算对比度。新加的测试会读两个内置主题的 <code>plugin.json</code>，逐对检查文字与底色（正文 7:1，其余 4.5:1）。</p>
<p>测试第一次跑就抓到了我自己的错：设计稿里成功绿配纯白字是 4.56:1，但实际用的"白字"是带一点蓝的 <code>primary-foreground</code>，只有 4.37:1。把绿色压暗一点（亮度 0.55 → 0.52）才过。</p>
<p>另一个测试检查 <code>globals.css</code> 里的兜底值和默认主题完全一致，两边以后不会各改各的。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="字体可商用能随开源包分发">字体：可商用、能随开源包分发<a href="https://docs.skinloom.cn/devlog/frontend-p0#%E5%AD%97%E4%BD%93%E5%8F%AF%E5%95%86%E7%94%A8%E8%83%BD%E9%9A%8F%E5%BC%80%E6%BA%90%E5%8C%85%E5%88%86%E5%8F%91" class="hash-link" aria-label="字体：可商用、能随开源包分发的直接链接" title="字体：可商用、能随开源包分发的直接链接" translate="no">​</a></h2>





















<table><thead><tr><th>用途</th><th>字体</th></tr></thead><tbody><tr><td>英文与数字</td><td>Inter</td></tr><tr><td>中文</td><td>思源黑体（Noto Sans SC）</td></tr><tr><td>哈希、UUID、令牌</td><td>JetBrains Mono</td></tr></tbody></table>
<p>三种都是 SIL OFL，从 npm 装、随前端构建，由站点自己提供，国内访问不依赖 Google Fonts。MiSans、HarmonyOS Sans 的协议限制单独再分发或修改（网页切片就算修改），没有选。</p>
<p>中文字体按 <code>unicode-range</code> 切了一百多片，页面用到哪些字只下载哪几片。实测首页第一次打开下载 842 KB 字体（思源黑体 13 片），之后浏览器缓存。比预想的多，记在了风险里，收尾阶段再评估要不要换静态字重或常用字子集。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="其它几件小事">其它几件小事<a href="https://docs.skinloom.cn/devlog/frontend-p0#%E5%85%B6%E5%AE%83%E5%87%A0%E4%BB%B6%E5%B0%8F%E4%BA%8B" class="hash-link" aria-label="其它几件小事的直接链接" title="其它几件小事的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>token 搬进 <code>@skinloom/ui</code></strong>：插件以后用 Tailwind 时引入同一份 <code>@skinloom/ui/globals.css</code>，跟着主题变色。兜底值放进 <code>@layer base</code>，主题的 CSS 不在任何 layer 里，所以总能盖过站点自己的样式，主题作者不用写 <code>!important</code>。</li>
<li class=""><strong>TanStack Query</strong>：orval 在原来的 fetch 函数之外，再生成一份 Query 钩子（<code>@skinloom/api-client/query</code>），走同一个 <code>apiFetch</code>。服务端组件仍用 fetch 函数，因为 TanStack Query 在服务端组件里加载不了。通知铃铛先换成了钩子，每分钟数一次未读。</li>
<li class=""><strong>菜单图标表</strong>：后端下发的菜单图标是 lucide 的名字，前端只映射一张允许的表，不会把整个图标库打进首屏。测试会读 <code>site.go</code>，确认后端用到的名字都在表里。这次还发现 lucide 1.70 把 <code>circle-alert</code> 改名成了 <code>circle-exclamation-point</code>，旧名字留作别名。</li>
<li class=""><strong>样式检查</strong>：<code>bun run test</code> 会拒绝 <code>text-white</code>、<code>bg-slate-900</code>、<code>bg-[#fff]</code> 这类绕过 token 的写法，现有的 9 处已经改掉。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下一期">下一期<a href="https://docs.skinloom.cn/devlog/frontend-p0#%E4%B8%8B%E4%B8%80%E6%9C%9F" class="hash-link" aria-label="下一期的直接链接" title="下一期的直接链接" translate="no">​</a></h2>
<p>P1 组件库：用 shadcn CLI 把基础组件装进 <code>packages/ui</code>，再做皮肤站自己的组件（双面预览、展示区轮播、确认对话框……），以及一个后台里的组件总览页，给主题作者核对用。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="frontend" term="frontend"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 31 期 · 1.0 收尾：整理代码与文档]]></title>
        <id>https://docs.skinloom.cn/devlog/v1-cleanup</id>
        <link href="https://docs.skinloom.cn/devlog/v1-cleanup"/>
        <updated>2026-11-09T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[1.0 之前的一次大扫除，这期没有新功能：]]></summary>
        <content type="html"><![CDATA[<p>1.0 之前的一次大扫除，这期没有新功能：</p>
<ul>
<li class="">后端目录分了层，一眼能看出哪些是业务、哪些是基础设施；</li>
<li class="">九份各写各的事务辅助函数合成一份，顺手修掉一个会让 SQLite 站点卡死的问题；</li>
<li class="">文档按玩家、站长、开发者重新组织，README 从 276 行减到不到 80 行。</li>
</ul>
<p>接下来是前端优化，然后是 1.x 与 2.0。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="目录分层adr-0040">目录分层（ADR 0040）<a href="https://docs.skinloom.cn/devlog/v1-cleanup#%E7%9B%AE%E5%BD%95%E5%88%86%E5%B1%82adr-0040" class="hash-link" aria-label="目录分层（ADR 0040）的直接链接" title="目录分层（ADR 0040）的直接链接" translate="no">​</a></h2>
<p>以前 <code>internal/</code> 下 33 个包平铺。现在：</p>
<ul>
<li class=""><code>internal/modules/</code>：账号、材质、角色、积分、举报、外置登录等 18 个业务模块；</li>
<li class=""><code>internal/platform/</code>：数据库、任务队列、存储、日志等基础设施，不认识任何业务；</li>
<li class="">顶层只剩进程级的包：装配、命令行、网关、前端启动器、系统服务、备份，以及 HTTP 层和扩展总线。</li>
</ul>
<p>依赖方向是 <code>cli → app → httpapi → modules → platform</code>。这次只改了导入路径，没有改代码逻辑。</p>
<p>几个太长的文件也拆开了。<code>texture/manage.go</code> 有 894 行，衣柜、编辑删除、加锁、文件清理都在里面，现在分成四个文件；<code>account/service.go</code> 和 <code>cli/root.go</code> 也一样。拆分用一个小工具按声明搬移，然后逐行比对搬移前后的代码，确认一个字都没改。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一个藏得很深的问题">一个藏得很深的问题<a href="https://docs.skinloom.cn/devlog/v1-cleanup#%E4%B8%80%E4%B8%AA%E8%97%8F%E5%BE%97%E5%BE%88%E6%B7%B1%E7%9A%84%E9%97%AE%E9%A2%98" class="hash-link" aria-label="一个藏得很深的问题的直接链接" title="一个藏得很深的问题的直接链接" translate="no">​</a></h2>
<p><code>withTx</code> 在九个包里各复制了一份，写法还不完全一样。统一的时候发现，这九份都没有处理回调 panic 的情况：</p>
<ul>
<li class="">处理函数里的 panic 会被 HTTP 服务器恢复，请求返回 500；</li>
<li class="">但事务没人回滚，一直占着数据库连接和锁；</li>
<li class="">SQLite 只有一个写者，之后站点的所有写入都在等这个永远不会结束的事务，最后超时失败，只能重启。</li>
</ul>
<p>按 TDD 的做法，先写测试：在三种数据库上制造一次 panic，再写一笔。旧写法在 SQLite 上等了 10 秒超时，确认问题存在；<code>db.WithTx</code> 加上 panic 回滚后测试通过。</p>
<p>统一的过程中，测试还拦住了一个回归。一开始统一成的版本无论如何都用 <code>errors.Join</code> 把错误包一层，结果 <code>player</code> 的测试失败了：调用方写的是 <code>err != ErrNotFound</code>，被包过的错误对不上。最后定下的语义是原样返回回调的错误，只有回滚本身也失败时才合并。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="文档">文档<a href="https://docs.skinloom.cn/devlog/v1-cleanup#%E6%96%87%E6%A1%A3" class="hash-link" aria-label="文档的直接链接" title="文档的直接链接" translate="no">​</a></h2>
<ul>
<li class="">文档站分成三块：
<ul>
<li class=""><strong>玩家指南</strong>：只讲怎么做（注册、上传、换皮肤、在启动器里登录），不出现设置键；</li>
<li class=""><strong>站长指南</strong>：部署、配置文件、站点设置、后台管理、迁移；</li>
<li class=""><strong>开发</strong>：环境、架构、接口。</li>
</ul>
</li>
<li class="">站点设置速查表照着 <code>skinloom settings get</code> 的输出逐项核对，全部 80 个设置都在。</li>
<li class="">使用文档里去掉了 Blessing Skin 缺陷编号和实现细节。它们对开发者有用，但对玩家和站长是干扰，现在留在设计文档和 ADR 里。</li>
<li class="">README 只留介绍、快速开始和文档入口，部署细节都在文档站。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="终端日志adr-0041">终端日志（ADR 0041）<a href="https://docs.skinloom.cn/devlog/v1-cleanup#%E7%BB%88%E7%AB%AF%E6%97%A5%E5%BF%97adr-0041" class="hash-link" aria-label="终端日志（ADR 0041）的直接链接" title="终端日志（ADR 0041）的直接链接" translate="no">​</a></h2>
<p>以前终端里每行都以 <code>time=2026-11-09T15:39:33.541+08:00 level=INFO msg=</code> 开头，级别没有颜色。新站点首次启动先刷 11 行迁移记录，安装链接埋在中间。现在：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">16:03:29 INFO  [migrate] database migrated  applied=11 version=20261030040409</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">16:03:29 NOTE  SkinLoom is running  url=http://localhost:17546/ database=sqlite</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">16:03:29 WARN  unknown keys in config file (typo?); they are ignored  keys=[log.levle]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">16:03:29 NOTE  first run: open this one-time link to create the administrator account  url=…</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">16:03:30 INFO  [web] ✓ Ready in 897ms</span><br></div></code></pre></div></div>
<ul>
<li class="">级别带颜色：错误红、警告黄，站点地址和安装链接用新的 NOTE 级别，绿色加粗，<code>log.level = warn</code> 时也会显示。</li>
<li class="">日志文件、Docker、systemd 拿到的仍是完整时间戳的 <code>key=value</code>，<code>grep setup</code> 照常可用。</li>
<li class="">前端每个请求一行的记录降到 debug；Next.js 打印的内部端口地址不再转发，免得有人去访问它。</li>
</ul>
<p>调试时踩了一个坑：用 <code>FORCE_COLOR</code> 测试彩色输出时，这个变量也传给了 Next.js，它自己的颜色码让请求行认不出来，还会混进日志文件。现在先去掉子进程输出里的颜色码，再分级、上色。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="验证">验证<a href="https://docs.skinloom.cn/devlog/v1-cleanup#%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="验证的直接链接" title="验证的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><code>go vet</code>、staticcheck、govulncheck 无告警；</li>
<li class="">全部测试在 SQLite 和本地 PostgreSQL 上通过，生成的 OpenAPI 文档没有变化；</li>
<li class="">在本机启动完整站点，手动走了一遍主要流程；</li>
<li class="">文档站构建通过，站内链接全部有效。</li>
</ul>
<p>MySQL 本地没有环境，交给 CI。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="v1.0" term="v1.0"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 27 期 · M5 导入站点设置与密钥]]></title>
        <id>https://docs.skinloom.cn/devlog/m5-bs-settings</id>
        <link href="https://docs.skinloom.cn/devlog/m5-bs-settings"/>
        <updated>2026-11-05T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M5 第二部分完成。skinloom import bs 现在还会带过来站点设置、邮件设置、改过的常用称呼、OAuth 应用和 Yggdrasil 签名密钥。导入后不用再到后台重填一遍，游戏服务器也不用重启。]]></summary>
        <content type="html"><![CDATA[<p>M5 第二部分完成。<code>skinloom import bs</code> 现在还会带过来站点设置、邮件设置、改过的常用称呼、OAuth 应用和 Yggdrasil 签名密钥。导入后不用再到后台重填一遍，游戏服务器也不用重启。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="带过来什么adr-0036">带过来什么（ADR 0036）<a href="https://docs.skinloom.cn/devlog/m5-bs-settings#%E5%B8%A6%E8%BF%87%E6%9D%A5%E4%BB%80%E4%B9%88adr-0036" class="hash-link" aria-label="带过来什么（ADR 0036）的直接链接" title="带过来什么（ADR 0036）的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>站点设置</strong>：站点名称、简介、公告、地址、版权文字、注册与邮箱验证、reCAPTCHA、角色名规则、积分与签到、材质大小与命名规则、自定义 CSS、关键词、Yggdrasil 选项。BS 给每种语言单独存的版本（<code>site_name_en</code> 这类），中文和英文分别导入。</li>
<li class=""><strong>邮件</strong>：BS 的邮件设置在 <code>.env</code> 里，用 <code>--env</code> 导入时一起带过来。加密方式按 Laravel 的规则换算：465 端口用 TLS，其它端口用 STARTTLS。</li>
<li class=""><strong>改过的称呼</strong>：站长最常改的是"积分"（改成"金币"之类）、"皮肤库"、"衣柜"这些词。导入器有一张人工整理的对照表，这些词在 SkinLoom 里每个单独显示的地方都会换掉。</li>
<li class=""><strong>OAuth 应用</strong>：ID、所有者、密钥、回调地址都不变，第三方应用不用改配置。BS 存的是明文密钥，SkinLoom 只存它的哈希。</li>
<li class=""><strong>签名密钥</strong>：yggdrasil-api 插件的私钥原样导入，公钥不变，用 authlib-injector 的服务器不用重启。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="几个决定">几个决定<a href="https://docs.skinloom.cn/devlog/m5-bs-settings#%E5%87%A0%E4%B8%AA%E5%86%B3%E5%AE%9A" class="hash-link" aria-label="几个决定的直接链接" title="几个决定的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>每个值都过一遍 SkinLoom 自己的校验。</strong> 映射出来的值交给目标设置的校验器检查，与后台保存时一样。超出范围的改为最接近的允许值，比如材质宽度 4096 改为 2048；不合格的保留 SkinLoom 的默认值。两种情况都写进报告。</li>
<li class=""><strong>PHP 的取值规则照搬。</strong> BS 默认的 <code>score_per_storage</code> 存的是字符串 <code>'true'</code>，PHP 转成整数是 1，导入后也是 1。BS 实际怎么用这个值，SkinLoom 就怎么用。</li>
<li class=""><strong>翻译不做自动匹配。</strong> SkinLoom 的界面文字是重写的。按文字自动匹配，BS 的 824 个键里只有几十个对得上，而且多是巧合，错配会悄悄改掉不相关的地方。所以只换对照表里的常用词，其它改过的文字逐条列在报告里，到翻译页重新改。</li>
<li class=""><strong>BS 的正则换成 Go 的写法。</strong> 自定义的角色名、材质名规则是 PCRE，SkinLoom 用 RE2。分隔符和 <code>i</code>、<code>m</code>、<code>s</code> 标志会转换，用了反向引用、环视的保留默认规则，并警告。</li>
<li class=""><strong>只报告站点改过的选项。</strong> 与 BS 默认值相同的选项，SkinLoom 即使没有对应的设置也不出现在报告里，报告只留站长需要看的东西。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="测试">测试<a href="https://docs.skinloom.cn/devlog/m5-bs-settings#%E6%B5%8B%E8%AF%95" class="hash-link" aria-label="测试的直接链接" title="测试的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>密码兼容向量</strong>（02 §6 第 3 条）：BS 的十种密码方法，分别配空盐、普通盐、带逗号和中文的盐，一共 30 组。每组都要能登录、要求升级到 argon2id、拒绝错误的密码。</li>
<li class=""><strong>迁移回归库</strong>（第 4 条）：上一期的脏数据站点加上设置、翻译和 OAuth 应用，整份导入报告与一个黄金文件比较。导入器行为的任何变化都会显示为这个文件的 diff。</li>
<li class="">PostgreSQL 与 MySQL 源加上了 <code>language_lines</code> 和 <code>oauth_clients</code>：<code>group</code>、<code>key</code> 在 MySQL 里是保留字，要加反引号。</li>
<li class=""><strong>端到端</strong>：编译好的程序把一个 SQLite 的 BS 站导入 PostgreSQL，导入前 SkinLoom 先启动过一次，已经生成了自己的密钥。之后启动后端：
<ul>
<li class="">Yggdrasil 元数据的公钥与 BS 的私钥配对；</li>
<li class="">中英文的站点名称、公告、"金币"都对；</li>
<li class="">论坛应用用原来的密钥通过了客户端认证，错误的密钥被拒绝；</li>
<li class="">BS 的加盐 MD5 密码能登录。</li>
</ul>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="测试发现的问题">测试发现的问题<a href="https://docs.skinloom.cn/devlog/m5-bs-settings#%E6%B5%8B%E8%AF%95%E5%8F%91%E7%8E%B0%E7%9A%84%E9%97%AE%E9%A2%98" class="hash-link" aria-label="测试发现的问题的直接链接" title="测试发现的问题的直接链接" translate="no">​</a></h2>
<ul>
<li class="">选项表里没有 <code>announcement</code> 时，BS 的默认值是带 <code>{version}</code> 占位符的原文，以前会被当成公告导入。PostgreSQL 的测试库里残留的一行暴露了这个问题，顺带发现测试清理没有清空设置表。</li>
<li class="">没有一种语言有文字的多语言设置，以前写成空值：保留了 BS 默认简介的站点，导入后 SkinLoom 的简介是空的。现在保留默认值。回归报告里的设置数由 8 变成 7，正是这一处。</li>
<li class="">发件人名字是中文时，Go 的地址格式化会编码成 <code>=?utf-8?q?...?=</code>，后台就显示成这样。现在存成 <code>"老皮肤站" &lt;noreply@example.com&gt;</code>，发信时再编码。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="还没有的">还没有的<a href="https://docs.skinloom.cn/devlog/m5-bs-settings#%E8%BF%98%E6%B2%A1%E6%9C%89%E7%9A%84" class="hash-link" aria-label="还没有的的直接链接" title="还没有的的直接链接" translate="no">​</a></h2>
<ul>
<li class="">其它插件的表（邀请码、正版验证等）以后按插件逐个提供转换。</li>
<li class="">02 §6 要的是一个真实 BS 库的脱敏副本，拿到之前先用这份构造的回归库。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m5-bs-settings#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M5 第三部分：契约测试全量，包括黄金文件、authlib-injector 端到端和渲染快照。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M5" term="M5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 28 期 · M5 契约测试]]></title>
        <id>https://docs.skinloom.cn/devlog/m5-contract-tests</id>
        <link href="https://docs.skinloom.cn/devlog/m5-contract-tests"/>
        <updated>2026-11-05T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M5 第三部分完成。游戏接口的每个回答都固定在一个黄金文件里，authlib-injector 的完整登录流程由一个真正的 Java 客户端检查，头像渲染有了像素快照。另外新增了一条命令，迁移时用它把 SkinLoom 和原来的 BS 站逐条对比。]]></summary>
        <content type="html"><![CDATA[<p>M5 第三部分完成。游戏接口的每个回答都固定在一个黄金文件里，authlib-injector 的完整登录流程由一个真正的 Java 客户端检查，头像渲染有了像素快照。另外新增了一条命令，迁移时用它把 SkinLoom 和原来的 BS 站逐条对比。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="黄金文件adr-0037">黄金文件（ADR 0037）<a href="https://docs.skinloom.cn/devlog/m5-contract-tests#%E9%BB%84%E9%87%91%E6%96%87%E4%BB%B6adr-0037" class="hash-link" aria-label="黄金文件（ADR 0037）的直接链接" title="黄金文件（ADR 0037）的直接链接" translate="no">​</a></h2>
<ul>
<li class="">测试站点有五个角色：Steve（经典皮肤加披风）、Alex（slim）、Naked（什么都没穿）、Hidden（穿着私有皮肤）、Banned（主人被封禁），另有一个不存在的名字。</li>
<li class="">45 个请求覆盖 CSL、USM、旧版 PNG、材质文件、<code>/raw</code> 和 Yggdrasil 的全部端点。回答先规范化：
<ul>
<li class="">JSON 按键排序；</li>
<li class="">时间戳、令牌换成标记；</li>
<li class=""><code>textures</code> 属性解开 base64，签名用站点公钥验证，写成 <code>&lt;signature valid&gt;</code>；</li>
<li class="">PNG 写成尺寸加 SHA-256。</li>
</ul>
</li>
<li class="">文件逐条对照 BS 和插件的源码审过。审的时候发现 yggdrasil-api 的 <code>textures</code> 里有 <code>"isPublic": true</code>，SkinLoom 原来没有，已经补上。</li>
<li class="">有意与 BS 不同的几处写进了 ADR，比如角色名在所有数据库上都不区分大小写、CSL 回答可以被 CDN 缓存。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="和真实的-bs-站对比">和真实的 BS 站对比<a href="https://docs.skinloom.cn/devlog/m5-contract-tests#%E5%92%8C%E7%9C%9F%E5%AE%9E%E7%9A%84-bs-%E7%AB%99%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="和真实的 BS 站对比的直接链接" title="和真实的 BS 站对比的直接链接" translate="no">​</a></h2>
<p>02 §6 原本要求在真实的 BS 6 环境里录黄金文件，可开发环境里没有 PHP，也没有可用的 BS 站。于是把对比做成了命令：</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">skinloom </span><span class="token function" style="color:#d73a49">import</span><span class="token plain"> compare </span><span class="token parameter variable" style="color:#36acaa">--bs</span><span class="token plain"> https://old.example.com </span><span class="token parameter variable" style="color:#36acaa">--skinloom</span><span class="token plain"> http://127.0.0.1:17546 Steve Alex Notch</span><br></div></code></pre></div></div>
<ul>
<li class="">它像启动器和游戏服务器那样向两边提同样的问题，每边的签名用各自的公钥验证。</li>
<li class="">只比客户端读的东西：状态码、媒体类型和成功回答的正文。</li>
<li class="">迁移指南把它列为切换域名之前的一步，所以每次真实迁移都会对着真实的 BS 跑一遍。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="authlib-injector-端到端">authlib-injector 端到端<a href="https://docs.skinloom.cn/devlog/m5-contract-tests#authlib-injector-%E7%AB%AF%E5%88%B0%E7%AB%AF" class="hash-link" aria-label="authlib-injector 端到端的直接链接" title="authlib-injector 端到端的直接链接" translate="no">​</a></h2>
<p><code>internal/httpapi/testdata/authlib/Harness.java</code> 是一个只用 JDK 的小程序，Java 11 以上直接用 <code>java Harness.java</code> 运行。测试会启动真实的服务器，程序依次检查：</p>
<ul>
<li class="">元数据里的公钥；</li>
<li class="">authenticate、refresh、validate；</li>
<li class="">按 Minecraft 的算法计算 serverId，走一遍 join 和 hasJoined；</li>
<li class="">每个属性的签名；</li>
<li class=""><code>skinDomains</code> 白名单；</li>
<li class="">材质文件的 hash 是否与地址一致。</li>
</ul>
<p>CI 的 Linux 任务要求有 Java，缺了就失败，而不是跳过。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="渲染快照">渲染快照<a href="https://docs.skinloom.cn/devlog/m5-contract-tests#%E6%B8%B2%E6%9F%93%E5%BF%AB%E7%85%A7" class="hash-link" aria-label="渲染快照的直接链接" title="渲染快照的直接链接" translate="no">​</a></h2>
<ul>
<li class="">参考皮肤是合成的：每个像素的颜色都不同，帽子层半透明。错位一个像素、取错一块、混合算错，快照都会不一样。</li>
<li class="">覆盖经典、旧版 64×32、高清三种皮肤，以及 slim 预览和披风预览。</li>
<li class="">阈值：差值超过 2 的像素不超过 0.5%，用来容纳 arm64 上融合乘加造成的边缘误差。</li>
<li class="">验证过快照确实有效：把 3D 头像侧面的明暗从 0.86 改成 0.80，三个 3D 快照全部失败。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m5-contract-tests#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M5 第四部分：k6 压测，验证 04 §5.4 的性能目标。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M5" term="M5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 29 期 · M5 压测]]></title>
        <id>https://docs.skinloom.cn/devlog/m5-load-tests</id>
        <link href="https://docs.skinloom.cn/devlog/m5-load-tests"/>
        <updated>2026-11-05T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M5 第四部分完成。我们在一个有一百万个材质的站点上用 k6 压测，04 §5.4 的目标在 SQLite 和 PostgreSQL 上全部达到。压测还找出了两个慢点，都已修正。]]></summary>
        <content type="html"><![CDATA[<p>M5 第四部分完成。我们在一个有一百万个材质的站点上用 k6 压测，04 §5.4 的目标在 SQLite 和 PostgreSQL 上全部达到。压测还找出了两个慢点，都已修正。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="怎么测adr-0038">怎么测（ADR 0038）<a href="https://docs.skinloom.cn/devlog/m5-load-tests#%E6%80%8E%E4%B9%88%E6%B5%8Badr-0038" class="hash-link" aria-label="怎么测（ADR 0038）的直接链接" title="怎么测（ADR 0038）的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>种子数据</strong>：一万个账号，一百万个材质，十万个角色，用 ent 直接写入。写完立刻执行 <code>ANALYZE</code>（PostgreSQL 上是 <code>VACUUM ANALYZE</code>）。</li>
<li class=""><strong>k6 按固定速率请求</strong>：CSL 每秒 500 次，材质文件和缓存命中的头像各 200 次，USM 与旧版 PNG 100 次，join 加 hasJoined、皮肤库列表各 50 次。在这之前先把每个头像渲染一次，测缓存未命中的情况。</li>
<li class=""><strong>阈值就是目标</strong>，达不到时 k6 以非零状态退出。<code>bench/run.sh</code> 把编译、种子数据、冷启动、内存测量和 k6 串在一起；GitHub Actions 里有手动触发的 <code>Load test</code> 工作流。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="结果p99">结果（p99）<a href="https://docs.skinloom.cn/devlog/m5-load-tests#%E7%BB%93%E6%9E%9Cp99" class="hash-link" aria-label="结果（p99）的直接链接" title="结果（p99）的直接链接" translate="no">​</a></h2>















































<table><thead><tr><th>场景</th><th>目标</th><th>SQLite</th><th>PostgreSQL 18</th></tr></thead><tbody><tr><td>CSL</td><td>&lt; 5 ms</td><td>0.89 ms</td><td>1.05 ms</td></tr><tr><td>USM 与旧版 PNG</td><td>&lt; 5 ms</td><td>1.18 ms</td><td>1.23 ms</td></tr><tr><td>头像命中</td><td>&lt; 10 ms</td><td>1.03 ms</td><td>1.09 ms</td></tr><tr><td>头像未命中</td><td>&lt; 50 ms</td><td>31.85 ms</td><td>29.15 ms</td></tr><tr><td>hasJoined</td><td>&lt; 20 ms</td><td>1.16 ms</td><td>1.55 ms</td></tr><tr><td>皮肤库（一百万材质）</td><td>&lt; 50 ms</td><td>1.66 ms</td><td>1.59 ms</td></tr></tbody></table>
<ul>
<li class="">空闲内存 33 MB，压测后约 70 MB，其中最多 64 MiB 是渲染缓存。</li>
<li class="">冷启动 143 ms。</li>
</ul>
<p>数字来自一台 Windows 开发机，k6 和服务器跑在同一台机器上。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="压测找出的问题">压测找出的问题<a href="https://docs.skinloom.cn/devlog/m5-load-tests#%E5%8E%8B%E6%B5%8B%E6%89%BE%E5%87%BA%E7%9A%84%E9%97%AE%E9%A2%98" class="hash-link" aria-label="压测找出的问题的直接链接" title="压测找出的问题的直接链接" translate="no">​</a></h2>
<ul>
<li class="">
<p><strong>大头像编码太慢。</strong> 纯 Go 的 WebP 编码器处理 512 像素的 3D 头像要 200 ms 以上，缓存未命中的 p99 是 230 ms。现在：</p>
<ul>
<li class="">超过 300×300 像素的图输出 PNG；</li>
<li class="">128 像素以上用最快的压缩级别；</li>
<li class="">渲染并发数等于 CPU 数。</li>
</ul>
<p>改完以后 p99 约 30 ms。小头像照旧是 WebP。</p>
</li>
<li class="">
<p><strong>PostgreSQL 上翻页慢。</strong> 皮肤库按点赞数翻页的游标条件是一个 OR，PostgreSQL 换成通用计划后用不上点赞数的索引，p99 是 238 ms。加上一个等价的 <code>likes &lt;= L</code> 之后降到 1.6 ms。</p>
</li>
<li class="">
<p><strong>自动清理。</strong> PostgreSQL 第一轮压测全部超标：种子数据刚写完，自动清理正好在压测中途开始。所以种子工具写完就执行 <code>VACUUM ANALYZE</code>。</p>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m5-load-tests#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M5 第五部分：安全自查，包括 CSP、自定义 JavaScript，以及 M4 审查时记下的遗留问题。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M5" term="M5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 30 期 · M5 安全自查]]></title>
        <id>https://docs.skinloom.cn/devlog/m5-security</id>
        <link href="https://docs.skinloom.cn/devlog/m5-security"/>
        <updated>2026-11-05T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M5 第五部分完成：]]></summary>
        <content type="html"><![CDATA[<p>M5 第五部分完成：</p>
<ul>
<li class="">所有页面都带上了内容安全策略（CSP），注入的脚本不再执行；</li>
<li class="">站长终于可以加自定义 JavaScript；</li>
<li class="">M4 审查时记下的四个遗留问题全部解决。</li>
</ul>
<p>至此 M5 的开发工作完成，接下来是真实站点 beta。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="csp-与自定义-javascriptadr-0039">CSP 与自定义 JavaScript（ADR 0039）<a href="https://docs.skinloom.cn/devlog/m5-security#csp-%E4%B8%8E%E8%87%AA%E5%AE%9A%E4%B9%89-javascriptadr-0039" class="hash-link" aria-label="CSP 与自定义 JavaScript（ADR 0039）的直接链接" title="CSP 与自定义 JavaScript（ADR 0039）的直接链接" translate="no">​</a></h2>
<ul>
<li class="">
<p><strong>每个页面请求生成一个随机 nonce。</strong> 只有带 nonce 的脚本，以及由它们加载的脚本才能运行（<code>'strict-dynamic'</code>）。Next.js 自己的脚本、主题切换脚本和验证码脚本都走这条路。</p>
<ul>
<li class="">评论、材质名里如果混进了 <code>&lt;script&gt;</code> 或 <code>onerror=</code>，浏览器不会执行。</li>
<li class="">页面只能被本站嵌入，表单只能提交到本站。</li>
</ul>
</li>
<li class="">
<p><strong>后端的回答带一个什么都不允许的策略。</strong> JSON、图片、材质文件都不是页面，即使被当成页面打开也执行不了任何东西。</p>
</li>
<li class="">
<p><strong>自定义 JavaScript。</strong> BS 把它直接塞进页面，所以管理员账号被盗就等于全站存储型 XSS。SkinLoom 的做法和自定义 CSS 一样：</p>
<ul>
<li class="">只有超级管理员能改；</li>
<li class="">作为单独的文件提供，由带 nonce 的 <code>&lt;script&gt;</code> 加载。</li>
</ul>
<p>它可以再加载统计代码之类的脚本。站点切换页面时不刷新，所以脚本在打开网站时运行一次；要改页面内容，就得监听页面变化。导入 BS 时，<code>custom_js</code> 也会带过来，报告里会说明这一点。</p>
</li>
<li class="">
<p><strong>端到端验证。</strong> 在构建好的站点上逐项确认：</p>
<ul>
<li class="">17 个脚本都带 nonce；</li>
<li class="">注入的事件和外站 iframe 被拦下；</li>
<li class="">三家验证码都能显示；</li>
<li class="">3D 预览和皮肤库搜索正常。</li>
</ul>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="m4-的遗留问题">M4 的遗留问题<a href="https://docs.skinloom.cn/devlog/m5-security#m4-%E7%9A%84%E9%81%97%E7%95%99%E9%97%AE%E9%A2%98" class="hash-link" aria-label="M4 的遗留问题的直接链接" title="M4 的遗留问题的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>恢复时检查站点是否在运行。</strong> 运行中的站点对 <code>data/skinloom.lock</code> 持有共享锁，<code>skinloom restore</code> 拿不到独占锁就拒绝，<code>--force</code> 也不行。锁由操作系统管理，进程崩溃时自动释放，不会出现"锁文件残留、什么都做不了"的情况。</li>
<li class=""><strong>Windows 上的私密文件。</strong> 密钥、备份和日志只允许运行 SkinLoom 的账户、SYSTEM 和 Administrators 访问，不再继承上级目录的权限。Unix 上本来就是 0600 和 0700。</li>
<li class=""><strong>封禁会刷新 CDN。</strong> 封禁、解封、注销、恢复、删除账号时，在同一个事务里为每个角色发出 <code>player.updated</code> 或 <code>player.deleted</code>。CDN 刷新本来就监听这两个事件。</li>
<li class=""><strong>翻译覆盖的完整校验。</strong> 服务器端以前只检查花括号是否配对，现在按 ICU 消息格式完整解析。为了保证它和浏览器里 formatjs 的判断一致，我们用 formatjs 判定了两千多条文字（大部分是随机生成的），Go 的结果必须与它完全相同。前端自带的全部文字也必须通过。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m5-security#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M5 剩下的是真实站点 beta：需要一个真实的 BS 站导入并运行两周，稳定后发布 v1.0。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M5" term="M5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 26 期 · M5 从 Blessing Skin 导入]]></title>
        <id>https://docs.skinloom.cn/devlog/m5-bs-importer</id>
        <link href="https://docs.skinloom.cn/devlog/m5-bs-importer"/>
        <updated>2026-11-04T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M5 开始了。第一部分是 skinloom import bs：把一个 Blessing Skin 站点的账号、角色、材质、衣柜、举报和未读通知搬进全新的 SkinLoom，密码、UUID、皮肤链接都不变。]]></summary>
        <content type="html"><![CDATA[<p>M5 开始了。第一部分是 <code>skinloom import bs</code>：把一个 Blessing Skin 站点的账号、角色、材质、衣柜、举报和未读通知搬进全新的 SkinLoom，密码、UUID、皮肤链接都不变。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="m5-的安排adr-0035">M5 的安排（ADR 0035）<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#m5-%E7%9A%84%E5%AE%89%E6%8E%92adr-0035" class="hash-link" aria-label="M5 的安排（ADR 0035）的直接链接" title="M5 的安排（ADR 0035）的直接链接" translate="no">​</a></h2>
<p>M5 是"迁移与发布"，分五部分：</p>
<ol>
<li class="">BS 导入器：账号、角色与 UUID、材质与文件、衣柜、举报、通知（本期）。</li>
<li class="">BS 导入器：站点设置、翻译覆盖、OAuth 应用、Yggdrasil 签名密钥，以及一份脏数据迁移回归库。</li>
<li class="">契约测试全量：黄金文件、authlib-injector 端到端、渲染快照。</li>
<li class="">k6 压测。</li>
<li class="">安全自查：CSP 与自定义 JS，以及 M4 审查记下的遗留问题。</li>
</ol>
<p>之后找一个真实的 BS 站做 beta，稳定运行两周后发布 v1.0。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="怎么用">怎么用<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#%E6%80%8E%E4%B9%88%E7%94%A8" class="hash-link" aria-label="怎么用的直接链接" title="怎么用的直接链接" translate="no">​</a></h2>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">skinloom </span><span class="token function" style="color:#d73a49">import</span><span class="token plain"> bs </span><span class="token parameter variable" style="color:#36acaa">--env</span><span class="token plain"> /var/www/blessing-skin/.env --dry-run   </span><span class="token comment" style="color:#999988;font-style:italic"># 先试</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">skinloom </span><span class="token function" style="color:#d73a49">import</span><span class="token plain"> bs </span><span class="token parameter variable" style="color:#36acaa">--env</span><span class="token plain"> /var/www/blessing-skin/.env             </span><span class="token comment" style="color:#999988;font-style:italic"># 再导</span><br></div></code></pre></div></div>
<p>从 BS 的 <code>.env</code> 读出数据库、表前缀、密码算法和盐，材质从 <code>storage/textures</code> 读。MySQL、PostgreSQL、SQLite 都支持。完整的步骤见文档<a class="" href="https://docs.skinloom.cn/docs/deployment/from-blessing-skin">从 Blessing Skin 迁移</a>。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="几个决定">几个决定<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#%E5%87%A0%E4%B8%AA%E5%86%B3%E5%AE%9A" class="hash-link" aria-label="几个决定的直接链接" title="几个决定的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>只导入到全新的站点，整个导入是一个事务。</strong> 试运行就是同一个导入最后撤销，所以试运行的报告和正式导入完全一样，连写库时才会暴露的约束冲突都能提前看到。失败的导入什么也不留，修好原因直接重跑。导入成功后不能再导一次：那时站点可能已经有了新数据，和 BS 合并没有安全的默认做法。</li>
<li class=""><strong>ID 保持不变。</strong> 用户、角色、材质、举报都沿用 BS 的 ID，<code>/skinlib/show/123</code> 这样的链接继续有效。PostgreSQL 的自增序列在同一个事务里、提交之前往前移。</li>
<li class=""><strong>源库只读。</strong> SQLite 用只读方式打开，测试会比较导入前后的数据库文件。MySQL、PostgreSQL 在一个只读事务里读，BS 没停也能读到一致的快照。</li>
<li class=""><strong>邮箱只差大小写的两个账号会阻止导入。</strong> BS 的邮箱区分大小写，SkinLoom 不区分。自动改掉其中一个，那个人就用原来的邮箱登录不了，所以交给站长决定。</li>
<li class=""><strong>其余的脏数据按默认规则处理，并写进报告。</strong> 重名的角色（BS 并发注册的产物）加 <code>_2</code> 后缀，并给主人发一条站内通知。同一用户重复上传的材质合并。指向已删除材质的皮肤清空。衣柜里的重复行去掉。</li>
<li class=""><strong>材质文件逐个检查。</strong> 每个文件都算一遍 SHA-256、读一遍 PNG 头。内容和文件名对不上的，按内容的 hash 存。缺失的文件不影响导入：材质照样导入，访问时和 BS 一样返回 404。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="密码">密码<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#%E5%AF%86%E7%A0%81" class="hash-link" aria-label="密码的直接链接" title="密码的直接链接" translate="no">​</a></h2>
<p>BS 支持的算法都认得：<code>password_hash()</code> 的结果按前缀识别，十六进制摘要按长度区分 MD5、SHA256、SHA512，是否加盐看 <code>PWD_METHOD</code>。启用了 password-algorithm-transition 插件的站点同时有几种格式，导入器按插件的 <code>PASSWORD_METHODS</code> 和对应的盐逐个识别。首次登录成功后，统一升级为 argon2id。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="验证">验证<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="验证的直接链接" title="验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">测试用一个故意弄脏的 BS 站：重名角色、重复邮箱、重复上传、悬空引用、缺失和被改过的文件、重复的衣柜行和举报。先导入 SkinLoom 的 SQLite 和 PostgreSQL，再分别从 PostgreSQL 和 MySQL 的 BS 库读一遍（MySQL 在 CI 里跑）。</li>
<li class="">端到端：编译好的程序导入一个 SQLite 的 BS 站，启动后端。之后：
<ul>
<li class="">用 BS 的加盐 MD5 密码登录成功（邮箱换了大小写），密码随即升级为 argon2id；</li>
<li class="">CSL 和 Yggdrasil 返回原来的材质 hash 和 UUID，材质文件能正常下载；</li>
<li class="">改名的角色主人收到了通知。</li>
</ul>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="审查后的修正">审查后的修正<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#%E5%AE%A1%E6%9F%A5%E5%90%8E%E7%9A%84%E4%BF%AE%E6%AD%A3" class="hash-link" aria-label="审查后的修正的直接链接" title="审查后的修正的直接链接" translate="no">​</a></h2>
<p>导入器写完后做了一次完整审查，下面这些都补了回归测试：</p>
<ul>
<li class="">启用 password-algorithm-transition 插件的站点，旧方法的加盐密码以前全部按不加盐存，这些用户登不上。现在按 <code>PASSWORD_METHODS</code> 和拆开的 <code>SALT</code> 配对识别。</li>
<li class="">材质目录与 BS 共用时，内容被改过的文件以前不复制，材质一导入就是 404。现在这些文件按内容的 hash 复制进去。文档改为推荐复制：共用之后，定期清理会删掉目录里没有材质用到的 BS 文件。</li>
<li class="">角色的 UUID 以前逐个匹配，前面只差大小写的角色会抢走后面角色精确匹配的 UUID，名字带首尾空格的角色拿不到原来的 UUID。现在先全部精确匹配，再做不区分大小写的匹配，最后才生成。</li>
<li class="">文字里的 NUL 和无效 UTF-8 以前会让 PostgreSQL 拒绝整个导入，现在会被清理并记入报告。</li>
<li class=""><code>.env</code> 的读法与 Laravel 对齐：不带引号的值在 <code>#</code> 处截断，<code>null</code>、<code>(empty)</code> 等都当作空。</li>
<li class="">读可选表时，只有数据库明确回答"表不存在"才当作没有，权限或网络错误会让导入停下。</li>
<li class="">PostgreSQL 的序列以前在提交之后才移，那一步失败时站点已经导入，新注册的账号会撞上已有 ID。现在挪进了事务。</li>
<li class="">同时运行两个导入，以前可能都通过"站点为空"的检查。现在事务先占一行锁，第二个等它结束，然后拒绝。</li>
<li class="">复制或写库失败时报告照样写出；<code>--report</code> 指向已有文件时权限也改成 0600；连接串和盐可以放在 <code>SKINLOOM_BS_DSN</code>、<code>SKINLOOM_BS_SALT</code> 里。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="还没有的">还没有的<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#%E8%BF%98%E6%B2%A1%E6%9C%89%E7%9A%84" class="hash-link" aria-label="还没有的的直接链接" title="还没有的的直接链接" translate="no">​</a></h2>
<ul>
<li class="">站点设置、翻译覆盖、OAuth 应用、Yggdrasil 签名密钥在下一期。在那之前，用 authlib-injector 的游戏服务器在切换后要重启一次，才会取到新的签名公钥。</li>
<li class="">其它插件的表（邀请码、正版验证等）以后按插件逐个提供转换。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m5-bs-importer#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M5 第二部分：导入站点设置、翻译覆盖、OAuth 应用和 Yggdrasil 密钥，并整理一份脱敏的迁移回归库。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M5" term="M5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 23 期 · M4 CDN 刷新与备份]]></title>
        <id>https://docs.skinloom.cn/devlog/m4-cdn-and-backup</id>
        <link href="https://docs.skinloom.cn/devlog/m4-cdn-and-backup"/>
        <updated>2026-10-31T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M4 第四部分：玩家换了皮肤，CDN 会自动丢掉旧缓存；站点可以用一条命令备份，再用一条命令恢复。]]></summary>
        <content type="html"><![CDATA[<p>M4 第四部分：玩家换了皮肤，CDN 会自动丢掉旧缓存；站点可以用一条命令备份，再用一条命令恢复。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="cdn-刷新adr-0032">CDN 刷新（ADR 0032）<a href="https://docs.skinloom.cn/devlog/m4-cdn-and-backup#cdn-%E5%88%B7%E6%96%B0adr-0032" class="hash-link" aria-label="CDN 刷新（ADR 0032）的直接链接" title="CDN 刷新（ADR 0032）的直接链接" translate="no">​</a></h2>
<p>BS 用 refresh-ali-cdn、refresh-qcloud-cdn 等插件做这件事。SkinLoom 内置了它，而且直接用上了上一轮审查加的领域事件：角色创建、改名、换装、删除都会发出事件，CDN 模块订阅这几个事件，刷新这个角色的 6 个地址（CustomSkinLoader、UniSkinMod、旧版 PNG 和头像），改名时新旧名字都刷新。材质被删除或改为私有时，被脱下的角色本来就会发出"角色已更新"，不用另外处理。</p>
<p>支持 Cloudflare、阿里云 CDN、腾讯云 CDN，其它 CDN 可以用 Webhook 接入。两家云厂商的签名是最容易出错的部分，测试直接用了官方文档里的示例：阿里云比对最终签名；腾讯云示例的 SecretKey 打了码，就从请求体哈希、规范请求哈希、派生密钥到最终签名逐步核对。写测试时还发现，起初按记忆写的腾讯云示例数据是错的，最后按文档页面上的原始数据改正。</p>
<p>刷新失败时返回错误，由任务队列按 1、5、15、60 分钟重试。只有配置了 CDN 才注册事件处理器：没有处理器时事件根本不会写进队列，所以不用 CDN 的站点没有任何额外开销。在后台改设置就能开关，不用重启。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="备份与恢复">备份与恢复<a href="https://docs.skinloom.cn/devlog/m4-cdn-and-backup#%E5%A4%87%E4%BB%BD%E4%B8%8E%E6%81%A2%E5%A4%8D" class="hash-link" aria-label="备份与恢复的直接链接" title="备份与恢复的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><code>skinloom backup</code> 把 SQLite 数据库、配置、密钥和材质打成一个 <code>.tar.gz</code>。数据库用 <code>VACUUM INTO</code> 复制，站点不用停；打开数据库时不执行迁移，升级前做的备份保持原样。<code>--keep N</code> 只保留最新几份，定时备份交给 cron 或计划任务。</li>
<li class="">MySQL 和 PostgreSQL 不导出数据库，交给它们自己的 <code>mysqldump</code> / <code>pg_dump</code>，那些工具更可靠。</li>
<li class=""><code>skinloom restore</code> 只认识清单、配置、密钥、数据库和材质这几种条目，带 <code>../</code> 的条目会被拒绝，写不到数据目录以外。目标已经有站点时要加 <code>--force</code>。材质通过存储层写入，本地备份可以恢复到 S3，反过来也行。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="验证">验证<a href="https://docs.skinloom.cn/devlog/m4-cdn-and-backup#%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="验证的直接链接" title="验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">新测试：两家云的签名示例；四个服务商的假服务端（分批、鉴权失败、签名错误）；CDN 模块随设置注册与移除处理器；手动刷新接口（未配置 409、服务商拒绝 502）；在运行中的站点上备份，恢复到空目录后设置、材质、密钥都一致，重复恢复被拒绝，<code>--force</code> 可以覆盖；<code>--keep</code> 清理旧文件；恶意条目名被拒绝。</li>
<li class=""><code>go fmt</code>、<code>go vet</code>，完整的 <code>go test ./...</code>（SQLite 与 PostgreSQL）；前端类型检查、单元测试与生产构建。</li>
<li class="">实际跑了一遍：用一个本地 HTTP 服务充当 CDN 的 Webhook，在运行中的站点上创建角色 Steve、改名为 Alex。几秒内通过任务队列先后收到 6 个和 12 个地址的刷新请求，手动刷新又收到 6 个，每个请求都带签名。随后在站点运行时执行 <code>skinloom backup</code>，恢复到新目录，恢复出来的站点名、CDN 设置和管理员令牌都与原站一致；再恢复一次被拒绝。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="仍未验证">仍未验证<a href="https://docs.skinloom.cn/devlog/m4-cdn-and-backup#%E4%BB%8D%E6%9C%AA%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="仍未验证的直接链接" title="仍未验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">没有接真实的 Cloudflare、阿里云、腾讯云账号，只用官方示例和假服务端验证了签名与请求格式。</li>
<li class="">实际运行的站点里没有材质，材质的备份恢复只在测试里验证过。</li>
<li class="">MySQL、staticcheck、govulncheck 交给 CI。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m4-cdn-and-backup#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M4 最后一部分：Helm、<code>skinloom service install</code>，以及四种部署方式按文档从零部署一遍。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M4" term="M4"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 24 期 · M4 系统服务、Helm 与部署冒烟测试]]></title>
        <id>https://docs.skinloom.cn/devlog/m4-deploy</id>
        <link href="https://docs.skinloom.cn/devlog/m4-deploy"/>
        <updated>2026-10-31T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M4 最后一部分：skinloom service install 一条命令注册为系统服务；Kubernetes 可以用 Helm 安装；每种部署方式在 CI 里都会按文档从零部署一遍。]]></summary>
        <content type="html"><![CDATA[<p>M4 最后一部分：<code>skinloom service install</code> 一条命令注册为系统服务；Kubernetes 可以用 Helm 安装；每种部署方式在 CI 里都会按文档从零部署一遍。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="系统服务adr-0033">系统服务（ADR 0033）<a href="https://docs.skinloom.cn/devlog/m4-deploy#%E7%B3%BB%E7%BB%9F%E6%9C%8D%E5%8A%A1adr-0033" class="hash-link" aria-label="系统服务（ADR 0033）的直接链接" title="系统服务（ADR 0033）的直接链接" translate="no">​</a></h2>
<p>以前发行包带一个 <code>service/</code> 目录，里面是手写的 systemd 单元、launchd plist 和 Windows 计划任务脚本，用之前要自己改路径。Windows 上那其实是计划任务，不是服务。</p>
<p>现在由程序自己注册（用 kardianos/service）：</p>
<ul>
<li class=""><code>skinloom service install</code>，然后 <code>start</code>。另有 <code>stop</code>、<code>restart</code>、<code>status</code>、<code>uninstall</code>。</li>
<li class="">Linux 生成 systemd 单元，保留了原来的全部沙箱选项：系统目录只读，只能写 <code>data/</code> 和前端缓存。默认以 <code>skinloom</code> 用户运行，安装时把 <code>data/</code> 交给它。</li>
<li class="">macOS 是 <code>/Library/LaunchDaemons</code> 下的守护进程，开机运行，不用登录。</li>
<li class="">Windows 是真正的服务，以 LOCAL SERVICE 运行，延迟自动启动，失败后 5 秒重启。安装时用 icacls 只给它 <code>data\</code> 和前端缓存的写权限。</li>
<li class="">没有管理员权限时直接失败，并提示用管理员终端或 sudo。权限设置失败时把刚注册的服务删掉，不留半装的状态。</li>
<li class="">站点自己退出（比如配置写错）时进程也退出，交给服务管理器重启，不会出现"服务在运行、网站却打不开"。</li>
</ul>
<p>服务的控制台没人看，首次启动的一次性安装链接会丢，所以加了 <code>log.file</code>：以服务运行时默认把日志写到 <code>data/logs/skinloom.log</code>，超过 20 MB 时在启动时轮换一份。Windows 服务的标准错误可能是无效句柄，所以先写文件、再尽力写控制台；<code>io.MultiWriter</code> 遇到第一个错误就会停，不能直接用。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="readyz-等前端"><code>/readyz</code> 等前端<a href="https://docs.skinloom.cn/devlog/m4-deploy#readyz-%E7%AD%89%E5%89%8D%E7%AB%AF" class="hash-link" aria-label="readyz-等前端的直接链接" title="readyz-等前端的直接链接" translate="no">​</a></h2>
<p>用发行包测试时发现，启动后约一秒内 <code>/readyz</code> 已经返回 200，首页却是 502：前端子进程还在启动。现在前端由本进程启动时（managed / dev），<code>/readyz</code> 还要能连上前端端口才算就绪。前后端分离部署时前端有自己的探针，后端不管。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="helm-chart">Helm Chart<a href="https://docs.skinloom.cn/devlog/m4-deploy#helm-chart" class="hash-link" aria-label="Helm Chart的直接链接" title="Helm Chart的直接链接" translate="no">​</a></h2>
<p><code>deploy/helm/skinloom</code>：</p>
<ul>
<li class=""><code>mode: allInOne</code>（默认）：单 Pod、SQLite、5 Gi 数据卷，和 <code>skinloom</code> 镜像一样。</li>
<li class=""><code>mode: split</code>：后端加前端，前端可以多副本，带 PDB，可开 HPA。</li>
<li class="">外部数据库的 DSN 从已有的 Secret 读取，不写进 values。</li>
<li class="">另有 Ingress、可信代理、<code>server.extraEnv</code>（比如 S3 配置）、资源与调度。卸载 Chart 时保留数据卷。</li>
<li class="">安全设置和 Kustomize 清单一致：非 root、只读根文件系统（split 模式的后端）、去掉全部 capabilities、seccomp、不挂载 ServiceAccount 令牌。</li>
</ul>
<p>互相矛盾的参数在安装时就报错并说明原因，而不是装上之后才出问题：SQLite 配多个后端副本、多副本用 ReadWriteOnce 卷、allInOne 想扩容、外部数据库没给 Secret。不需要迁移 Job，后端启动时带锁执行迁移。Kustomize 清单保留，给不想装 Helm 的人用。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="部署冒烟测试">部署冒烟测试<a href="https://docs.skinloom.cn/devlog/m4-deploy#%E9%83%A8%E7%BD%B2%E5%86%92%E7%83%9F%E6%B5%8B%E8%AF%95" class="hash-link" aria-label="部署冒烟测试的直接链接" title="部署冒烟测试的直接链接" translate="no">​</a></h2>
<p>以前 CI 只检查部署文件的语法，从来没真正启动过。<code>deploy/smoke/smoke.sh</code> 像新站长一样走一遍：</p>
<ol>
<li class="">等待就绪，检查首页能渲染。</li>
<li class="">从日志里找出安装链接，完成安装。</li>
<li class="">登录，创建角色。</li>
<li class="">用 CustomSkinLoader 接口取回这个角色，不存在的角色返回 404。</li>
<li class="">后台的系统状态里没有错误。</li>
</ol>
<p>新工作流 <code>deploy-smoke.yml</code> 对每种部署方式都跑这个脚本，镜像全部从当前提交构建：</p>
<ul>
<li class="">Compose 的 minimal、standard、postgres 三个变体。</li>
<li class="">在 kind 集群里用 Helm 安装：allInOne + SQLite，split + PostgreSQL。</li>
<li class="">Linux 发行包：先按文档前台启动，再用 <code>skinloom service install</code> 注册为 systemd 服务，确认状态是 running，冒烟测试通过后停止并卸载。</li>
</ul>
<p>原来的部署文件检查也加上了 Helm：lint、几组参数的渲染、kubeconform 校验，以及非法参数确实会被拒绝。</p>
<p>顺带修了一个打包问题：在没有 <code>zip</code> 的 Windows 上，发行包由 PowerShell 的 <code>Compress-Archive</code> 压缩，路径分隔符是 <code>\</code>，<code>unzip</code> 会警告，macOS 会解压出错。现在改用 Windows 10 起自带的 <code>tar.exe</code>。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="验证">验证<a href="https://docs.skinloom.cn/devlog/m4-deploy#%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="验证的直接链接" title="验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">新测试：生成的 systemd 单元（带空格的路径会加引号）、服务命令行、拒绝安装 <code>go run</code> 产生的临时程序、日志轮换、控制台写失败时日志文件照常写入、<code>/readyz</code> 等前端。</li>
<li class=""><code>go fmt</code>、<code>go vet</code>（Windows、Linux），macOS 交叉编译；完整的 <code>go test ./...</code>（SQLite 与 PostgreSQL）。</li>
<li class="">Helm：lint 与多组参数渲染通过，矛盾的参数都被拒绝。</li>
<li class="">在本机用当前代码打出 Windows 发行包，解压到空目录，按文档启动，用和 <code>smoke.sh</code> 相同的步骤走完一遍，日志里没有警告。</li>
<li class="">普通权限下执行 <code>skinloom service install</code>，按预期失败并提示用管理员终端；<code>service status</code> 显示 not installed。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="仍未验证">仍未验证<a href="https://docs.skinloom.cn/devlog/m4-deploy#%E4%BB%8D%E6%9C%AA%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="仍未验证的直接链接" title="仍未验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">Compose、Helm 和 systemd 服务的从零部署只在新的 CI 工作流里跑，本机不运行 Docker，需要推送后看结果。</li>
<li class="">真实的 Windows 服务与 macOS launchd 安装还没跑过（CI 只覆盖 systemd），需要在有管理员权限的机器上手动验证一次。</li>
<li class="">kubeconform 只在 CI 里跑。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m4-deploy#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M4 的功能全部完成，等 CI 上的部署冒烟测试通过后就可以关闭 M4。之后是 M5：BS 导入器、契约测试全量、k6 压测、安全自查和真实站点 beta。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M4" term="M4"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 25 期 · M4 全量审查]]></title>
        <id>https://docs.skinloom.cn/devlog/m4-review</id>
        <link href="https://docs.skinloom.cn/devlog/m4-review"/>
        <updated>2026-10-31T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M4 五个部分完成后，对全部改动（157 个文件）做了一次审查，分五个方向：设置中心与邮箱验证、外观与系统状态、CDN/备份/系统服务、前端、部署文件。每个疑似问题先写出失败的测试，确认后再修；这些测试留下来作为回归测试。设计上的变化记在 ADR 0034。]]></summary>
        <content type="html"><![CDATA[<p>M4 五个部分完成后，对全部改动（157 个文件）做了一次审查，分五个方向：设置中心与邮箱验证、外观与系统状态、CDN/备份/系统服务、前端、部署文件。每个疑似问题先写出失败的测试，确认后再修；这些测试留下来作为回归测试。设计上的变化记在 ADR 0034。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="最严重的几个">最严重的几个<a href="https://docs.skinloom.cn/devlog/m4-review#%E6%9C%80%E4%B8%A5%E9%87%8D%E7%9A%84%E5%87%A0%E4%B8%AA" class="hash-link" aria-label="最严重的几个的直接链接" title="最严重的几个的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>被拒绝的恢复已经改了东西。</strong> 归档里配置和密钥排在数据库前面，以前遇到数据库条目才检查"目标已有站点"，被拒绝时管理员令牌已经换成了归档里的。现在所有检查都在写入之前完成。名为 <code>secrets/..</code> 的条目会写到数据目录外面，也一并堵上。</li>
<li class=""><strong>保留的密钥可以被送到别处。</strong> 管理员不知道 SMTP 密码，但可以只改 SMTP 主机、保留密码，再发一封测试邮件，密码就到了自己的服务器。社交登录的密钥同理（把 issuer 改成自己的）。现在改了密钥的去处就必须重新填写密钥。</li>
<li class=""><strong>"需要验证邮箱"管不住启动器。</strong> 未验证账号的启动器令牌每次刷新都会拿到新的刷新期限，可以一直用下去，还能通过 Yggdrasil 上传材质。</li>
<li class=""><strong>systemd 单元可以被注入指令。</strong> 路径或用户名里的换行会原样写进由 root 运行的单元。</li>
<li class=""><strong>部署冒烟测试里有一个注定失败的任务。</strong> <code>package.sh</code> 在 git 里没有可执行权限；还有两处 CI 检查无论如何都不会失败（bash 的 <code>! cmd</code> 不触发 <code>set -e</code>）。</li>
<li class=""><strong>split 模式上传较大的材质会失败。</strong> 后端是只读根文件系统，multipart 的临时文件写不进 <code>/tmp</code>。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="其它">其它<a href="https://docs.skinloom.cn/devlog/m4-review#%E5%85%B6%E5%AE%83" class="hash-link" aria-label="其它的直接链接" title="其它的直接链接" translate="no">​</a></h2>
<ul>
<li class="">一个带未闭合引号的主题变量会吞掉后面所有变量和整个暗色模式；前后端改用同一套检查。</li>
<li class="">翻译覆盖改用 ICU 解析器校验，以前只数花括号：格式错误的文字会让页面显示键名，合法的复数写法反而被拒。</li>
<li class="">MySQL 上两个管理员同时第一次保存带密钥的设置会死锁。设置保存改为先锁配置版本行，保存一个接一个地进行。</li>
<li class="">系统状态会拿迁移锁：另一个节点正在迁移时，状态页会卡住最多 5 分钟。</li>
<li class="">积分比率没有上限，乘以上传的 KB 数会溢出，"花费"变成进账。</li>
<li class="">首页区块随每个页面发给浏览器；最坏情况下每页多 500 KB。</li>
<li class="">CDN 配置填到一半时，每个玩家事件都会失败并重试约 80 分钟。</li>
<li class="">在站点旁边执行 CLI 命令会轮换服务器正在写的日志文件。</li>
<li class="">文档里 Kubernetes 的命令先建 Secret 后建命名空间；升级发行包后忘了把目录交还给服务用户。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="验证">验证<a href="https://docs.skinloom.cn/devlog/m4-review#%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="验证的直接链接" title="验证的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><code>go fmt</code>、<code>go vet</code>（Windows、Linux、macOS）；完整的 <code>go test ./...</code>，SQLite 与 PostgreSQL（英文和中文错误信息各一遍）；设置的并发测试在 PostgreSQL 上重复 10 次。</li>
<li class="">前端类型检查与 80 个单元测试；<code>bun install --frozen-lockfile</code> 确认 lockfile 一致。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="中文-postgresql-上的-500">中文 PostgreSQL 上的 500<a href="https://docs.skinloom.cn/devlog/m4-review#%E4%B8%AD%E6%96%87-postgresql-%E4%B8%8A%E7%9A%84-500" class="hash-link" aria-label="中文 PostgreSQL 上的 500的直接链接" title="中文 PostgreSQL 上的 500的直接链接" translate="no">​</a></h2>
<p>验证时还发现一个 M4 之前就有的问题。第一次跑 PostgreSQL 测试时，新建的测试数据库用了系统的中文区域设置，账号、角色、举报、材质的十几个测试都失败了：邮箱已被使用、角色名已被占用，返回的不是对应的提示而是 500。</p>
<p>原因是 ent 的 <code>IsConstraintError</code> 靠匹配英文错误信息（"violates unique constraint"）识别冲突，而 PostgreSQL 用服务器的语言写错误信息。装在中文系统上的 PostgreSQL 默认就是中文，这在国内并不少见。</p>
<p>改为按 SQLSTATE 错误码识别（<code>db.IsConstraint</code>），错误码不随语言变化。所有调用方都改用它，并加了一个测试，禁止再直接使用 <code>ent.IsConstraintError</code>。之后在一个报错为中文的 PostgreSQL 上跑完整测试，全部通过。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="仍未验证">仍未验证<a href="https://docs.skinloom.cn/devlog/m4-review#%E4%BB%8D%E6%9C%AA%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="仍未验证的直接链接" title="仍未验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">MySQL 只在 CI 里跑，设置保存的死锁修复要等 CI 结果。</li>
<li class="">Compose、Helm、systemd 的部署冒烟测试要推送后在 CI 里跑。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m4-review#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>进入 M5：BS 导入器、契约测试全量、k6 压测、安全自查和真实站点 beta。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M4" term="M4"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 22 期 · M4 翻译覆盖与系统状态]]></title>
        <id>https://docs.skinloom.cn/devlog/m4-texts-and-status</id>
        <link href="https://docs.skinloom.cn/devlog/m4-texts-and-status"/>
        <updated>2026-10-31T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M4 第三部分：后台多了"翻译"和"系统状态"两页。站长可以改写界面上的任何文字，也能一眼看出服务器哪里需要处理。]]></summary>
        <content type="html"><![CDATA[<p>M4 第三部分：后台多了"翻译"和"系统状态"两页。站长可以改写界面上的任何文字，也能一眼看出服务器哪里需要处理。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="翻译覆盖adr-0031">翻译覆盖（ADR 0031）<a href="https://docs.skinloom.cn/devlog/m4-texts-and-status#%E7%BF%BB%E8%AF%91%E8%A6%86%E7%9B%96adr-0031" class="hash-link" aria-label="翻译覆盖（ADR 0031）的直接链接" title="翻译覆盖（ADR 0031）的直接链接" translate="no">​</a></h2>
<p>BS 用 <code>language_lines</code> 表让站长改文字。设计文档原本也规划了一张 <code>translation_overrides</code> 表，最后改成放在设置 <code>i18n.overrides</code> 里：</p>
<ul>
<li class="">设置本来就能热加载到所有节点和已打开的页面，修改也会写进审计日志；</li>
<li class="">改写的文字一般只有几十条，单独建表还得给 SQLite、PostgreSQL、MySQL 各写一份迁移，换不来什么。</li>
</ul>
<p>bootstrap 只带访客语言的那一份，前端把它覆盖到自带的消息上。只替换已经存在的文字：键名写错，或者改版后某条文字被删了，都只是不生效，不会让页面报错。覆盖时复制沿途的对象，不改动所有请求共享的消息模块。</p>
<p>翻译页可以按键名或文字搜索，分语言改写。原文里花括号中的占位符（例如 <code>登录到 {site}</code> 里的 <code>{site}</code>）要原样保留，漏了或者花括号不成对都不能保存，服务端也会检查花括号。</p>
<p>目前只覆盖网页界面。邮件、兼容 BS 的接口提示和启动器登录的错误信息由服务端生成，以后后端接入消息目录时再加。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="系统状态">系统状态<a href="https://docs.skinloom.cn/devlog/m4-texts-and-status#%E7%B3%BB%E7%BB%9F%E7%8A%B6%E6%80%81" class="hash-link" aria-label="系统状态的直接链接" title="系统状态的直接链接" translate="no">​</a></h2>
<p><code>GET /api/v1/admin/status</code> 和后台页面显示：</p>
<ul>
<li class="">服务端：版本、Go 版本与系统、运行方式、启动时间；</li>
<li class="">数据库：类型与版本、迁移版本、响应时间。BS 会显示数据库用户名，这里连接串、用户名和文件路径都不显示；</li>
<li class="">材质存储：存储方式、文件数与占用空间；</li>
<li class="">后台任务：等待中、超时、已失败的数量；</li>
<li class="">邮件与配置。</li>
</ul>
<p>最上面是检查结果：数据库、迁移、任务积压、任务失败、邮件、站点地址，有问题的会说明影响。数据分别由数据库、迁移、任务队列、统计模块提供，接口只负责汇总；后台概览的存储统计也改用同一个函数。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="验证">验证<a href="https://docs.skinloom.cn/devlog/m4-texts-and-status#%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="验证的直接链接" title="验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">新测试：翻译覆盖的校验与 bootstrap、系统状态接口（包括积压任务的告警，以及不泄露数据库位置）；前端的覆盖合并、占位符检查与清理。</li>
<li class=""><code>go fmt</code>、<code>go vet</code>，完整的 <code>go test ./...</code>（SQLite 与 PostgreSQL）；前端类型检查与单元测试。</li>
<li class="">用 <code>skinloom up --dev</code> 在浏览器里走了一遍：
<ul>
<li class="">把"皮肤库"改成"皮肤广场"、英文改成"Gallery"，页头立即生效，英文访客看到 Gallery；</li>
<li class="">把"登录到 {site}"改成"欢迎回来"会提示缺少占位符、不能保存，改成"欢迎回到 {site}"后登录页显示了站点名；</li>
<li class="">系统状态在没设站点地址、没配邮件时给出两条提醒，其余四项正常，接口里没有数据库文件路径。</li>
</ul>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="仍未验证">仍未验证<a href="https://docs.skinloom.cn/devlog/m4-texts-and-status#%E4%BB%8D%E6%9C%AA%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="仍未验证的直接链接" title="仍未验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">MySQL、staticcheck、govulncheck 交给 CI。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m4-texts-and-status#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M4 第四部分：CDN 刷新与备份。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M4" term="M4"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 19 期 · 对照 BS 的全量审查与修复]]></title>
        <id>https://docs.skinloom.cn/devlog/full-review</id>
        <link href="https://docs.skinloom.cn/devlog/full-review"/>
        <updated>2026-10-30T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[进入 M4 之前，对照 Blessing Skin 的源码和设计文档 01–06、ADR 0001–0026，把 SkinLoom 的架构和代码从头审查了一遍。对外协议（CSL、USM、Legacy、Yggdrasil、OAuth 与 /api/*）的路由和 BS 逐条对得上，整体方向没有要回退的地方。问题集中在并发：六个问题都用并发测试在 SQLite 和 PostgreSQL 上复现，然后一并修掉。]]></summary>
        <content type="html"><![CDATA[<p>进入 M4 之前，对照 Blessing Skin 的源码和设计文档 01–06、ADR 0001–0026，把 SkinLoom 的架构和代码从头审查了一遍。对外协议（CSL、USM、Legacy、Yggdrasil、OAuth 与 <code>/api/*</code>）的路由和 BS 逐条对得上，整体方向没有要回退的地方。问题集中在并发：六个问题都用并发测试在 SQLite 和 PostgreSQL 上复现，然后一并修掉。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="复现了什么">复现了什么<a href="https://docs.skinloom.cn/devlog/full-review#%E5%A4%8D%E7%8E%B0%E4%BA%86%E4%BB%80%E4%B9%88" class="hash-link" aria-label="复现了什么的直接链接" title="复现了什么的直接链接" translate="no">​</a></h2>
<p>审查时临时写了几个并发测试，基于修复前的接口，复现后删除：</p>

































<table><thead><tr><th>场景</th><th>修复前</th></tr></thead><tbody><tr><td>同时发出几次"改为私有"（双击）</td><td>6 个请求扣了 6 次差价</td></tr><tr><td>给角色穿上材质，同时把它移出衣柜</td><td>角色穿着不在衣柜里的材质（SQLite 150 轮 149 次）</td></tr><tr><td>删除角色，同时把它穿着的材质移出衣柜</td><td>PostgreSQL 60 轮 59 次死锁</td></tr><tr><td>删除上传者账号，同时有人收藏他的材质</td><td>死锁；收藏常因给已删除的上传者发奖励而报 500</td></tr><tr><td>两位管理员同时保存有重叠键的设置</td><td>PostgreSQL 200 次保存 130 次死锁</td></tr><tr><td>同一时刻发出一批错误密码</td><td>200 个请求全部做了密码校验，限额是 10</td></tr></tbody></table>
<p>前五个的根源相同：事务里的判断用的是事务开始前读到的数据；ADR 0026 的加锁顺序只覆盖改积分的事务，删角色、删用户、保存设置都不在里面。最后一个是"先检查、做完密码哈希再计数"，并发请求都在计数之前通过了检查。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="怎么修的adr-0027">怎么修的（ADR 0027）<a href="https://docs.skinloom.cn/devlog/full-review#%E6%80%8E%E4%B9%88%E4%BF%AE%E7%9A%84adr-0027" class="hash-link" aria-label="怎么修的（ADR 0027）的直接链接" title="怎么修的（ADR 0027）的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>加锁之后再判断</strong>：材质先锁住再重读，可见性、上传者、类型都按锁里读到的值。穿戴和转移角色先锁住相关材质，再查衣柜。</li>
<li class=""><strong>加锁层级扩展</strong>：材质 → 用户 → 角色 → 其它。删角色先锁主人。删用户的钩子挪进删号事务，先锁他的材质、再锁用户；期间账号被恢复时整个事务回滚，私有材质不会被提前删掉。</li>
<li class=""><strong>设置按键名顺序写入。</strong></li>
<li class=""><strong>限流一步完成</strong>：<code>Limiter.Take</code> 检查和计数在同一把锁里，成功登录再撤回。所有"检查、做事、计数"的地方都换成了它。</li>
<li class="">顺带修的同类问题：删号时衣柜被外键删除，收藏数没减（BS C04 回来了）；删除材质时上传者自己角色的槽位由外键清空，<code>Last-Modified</code> 不变，<code>/{name}.json</code> 一直回 304；SQLite 的 DSN 带参数时外键被静默关闭。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="补上的地基adr-0028">补上的地基（ADR 0028）<a href="https://docs.skinloom.cn/devlog/full-review#%E8%A1%A5%E4%B8%8A%E7%9A%84%E5%9C%B0%E5%9F%BAadr-0028" class="hash-link" aria-label="补上的地基（ADR 0028）的直接链接" title="补上的地基（ADR 0028）的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>领域事件</strong>：Hook 总线原来只有 <code>settings.changed</code>。现在按设计文档 05 §4.4 的目录声明了用户、角色、材质、衣柜、举报五类共 15 个事件，在变更的事务里写进任务队列（outbox），提交后投递，至少一次。没有监听者时不写任何东西，所以现在零开销。Guard 和 Filter 随插件运行时一起做。</li>
<li class=""><strong>审计和变更同事务</strong>：管理操作原来先调用服务、再在事务外写审计。现在服务直接接收审计记录，在自己的事务里写入。管理员同时改名和转移角色也合成了一个事务，原来可能只成功一半。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="暂存代码复查">暂存代码复查<a href="https://docs.skinloom.cn/devlog/full-review#%E6%9A%82%E5%AD%98%E4%BB%A3%E7%A0%81%E5%A4%8D%E6%9F%A5" class="hash-link" aria-label="暂存代码复查的直接链接" title="暂存代码复查的直接链接" translate="no">​</a></h2>
<p>修完之后又把暂存的全部改动从头复查了一遍，逐个列出每个改动过的事务的加锁顺序。又找到三处问题，都先写测试、确认失败，再修：</p>
<ul>
<li class="">处理举报仍是先读举报、再开事务。举报人在这期间被删除时，奖励会发给已删除的账号，返回 500。现在加锁之后重读。</li>
<li class="">删除材质时清空穿戴槽位用的是 <code>IN (所有角色 id)</code>，7 万个角色穿着的材质删不掉（SQLite 报 "too many SQL variables"）。现在按条件更新。</li>
<li class="">加锁覆盖不到删号的同一瞬间账号主人新收藏的那一条。补上设计文档里一直有、ADR 0019 推迟了的每日被收藏数校准。</li>
</ul>
<p>两点记进 ADR 0028，留到上线插件之前处理：事件和邮件共用一个顺序执行的任务执行器；材质事件里有私有材质的 hash。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="验证">验证<a href="https://docs.skinloom.cn/devlog/full-review#%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="验证的直接链接" title="验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">每个问题都有对应的回归测试：并发改私有只扣一次、收藏与改私有并发、穿戴与移出衣柜并发、删角色与移出衣柜并发、删用户与收藏并发、并发保存设置、成批错误密码、删号钩子回滚、事件只在提交后存在、SQLite DSN、举报人已被删除、7 万个角色穿着的材质、被收藏数校准。在 SQLite 和 PostgreSQL 上全部通过，并发测试在 PostgreSQL 上用 <code>-count=10</code> 重复。</li>
<li class=""><code>go vet</code>、完整的 <code>go test ./...</code>（SQLite + PostgreSQL）、前端类型检查与单测。</li>
<li class="">用 <code>skinloom serve</code> 起了真实服务，走了登录爆破、改私有、穿戴、删号等流程。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="仍未验证">仍未验证<a href="https://docs.skinloom.cn/devlog/full-review#%E4%BB%8D%E6%9C%AA%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="仍未验证的直接链接" title="仍未验证的直接链接" translate="no">​</a></h2>
<ul>
<li class="">MySQL 只在 CI 里跑：本机没有 Docker。</li>
<li class="">staticcheck、govulncheck 交给 CI。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/full-review#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>进入 M4。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M3" term="M3"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 16 期 · M3 第三部分：管理类兼容接口]]></title>
        <id>https://docs.skinloom.cn/devlog/m3-admin-api</id>
        <link href="https://docs.skinloom.cn/devlog/m3-admin-api"/>
        <updated>2026-10-30T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M3 第三部分补上了 Blessing Skin OAuth 资源 API 的最后一块：/api/admin/*。管理员的脚本和面板可以用应用令牌或个人访问令牌管理用户、角色、衣柜、举报，发送通知。到这里，BS 第三方应用能调用的接口都已兼容。]]></summary>
        <content type="html"><![CDATA[<p>M3 第三部分补上了 Blessing Skin OAuth 资源 API 的最后一块：<code>/api/admin/*</code>。管理员的脚本和面板可以用应用令牌或个人访问令牌管理用户、角色、衣柜、举报，发送通知。到这里，BS 第三方应用能调用的接口都已兼容。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="本期完成">本期完成<a href="https://docs.skinloom.cn/devlog/m3-admin-api#%E6%9C%AC%E6%9C%9F%E5%AE%8C%E6%88%90" class="hash-link" aria-label="本期完成的直接链接" title="本期完成的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>用户</strong>：列表（<code>q</code> 搜索、<code>page</code> 翻页）、改邮箱、切换邮箱验证、改昵称、改密码、改积分、改权限（-1 / 0 / 1）、删除。</li>
<li class=""><strong>角色</strong>：列表（<code>q=uid:N</code> 查某个用户的角色）、改名、转移、换材质、删除。</li>
<li class=""><strong>衣柜</strong>：查看某个用户的衣柜、免费放入、取出。</li>
<li class=""><strong>举报</strong>：列表（<code>q=status:0</code> 等）、处理（删除材质、封禁上传者、驳回）。</li>
<li class=""><strong>通知</strong>：发给所有人、普通用户、某个 ID 或邮箱。</li>
<li class="">设计记录：<a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/docs/adr/0024-bs-admin-resource-api.md" target="_blank" rel="noopener noreferrer" class="">ADR 0024</a>；<a class="" href="https://docs.skinloom.cn/docs/development/api">开放平台</a>页面增加了管理类接口。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一套逻辑两种接口">一套逻辑，两种接口<a href="https://docs.skinloom.cn/devlog/m3-admin-api#%E4%B8%80%E5%A5%97%E9%80%BB%E8%BE%91%E4%B8%A4%E7%A7%8D%E6%8E%A5%E5%8F%A3" class="hash-link" aria-label="一套逻辑，两种接口的直接链接" title="一套逻辑，两种接口的直接链接" translate="no">​</a></h2>
<p>BS 的管理端页面、用户端和 OAuth API 各写一份逻辑，行为不一样：OAuth API 换材质不检查类型，发通知后返回一个 302 跳转。这次兼容层不直接查库，而是调用后台页面用的同一批服务：</p>
<ul>
<li class="">处理举报、发通知、角色改名与转移原来写在 <code>/api/v1</code> 的处理函数里，抽成共用函数，两套接口都调用，审计日志里看到的是同样的记录；</li>
<li class="">权限规则不变：管理员只管普通用户，超级管理员管所有人，谁都不能改自己的权限；</li>
<li class="">管理类 scope 只有管理员能授予；令牌主人被降为普通用户后，令牌立即不能再调用这些接口。</li>
</ul>
<p>为了 BS 的分页格式（页码加总数），用户、角色、举报三个列表的过滤条件增加了偏移量和计数，后台页面仍然用游标翻页。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="开发中的小插曲">开发中的小插曲<a href="https://docs.skinloom.cn/devlog/m3-admin-api#%E5%BC%80%E5%8F%91%E4%B8%AD%E7%9A%84%E5%B0%8F%E6%8F%92%E6%9B%B2" class="hash-link" aria-label="开发中的小插曲的直接链接" title="开发中的小插曲的直接链接" translate="no">​</a></h2>
<ul>
<li class="">测试里封禁 alice 之后，她的个人访问令牌返回 401 而不是预期的 403。原因是封禁会吊销用户的全部令牌（上一期的改动），令牌已经不存在了，这是对的，改的是测试。同理，她的网页登录也被退出了，测试要重新登录。</li>
<li class="">跑测试时 C 盘被占满（VS Code 的更新下载占了约 1 GB），工具输出开始被截断。征得同意清理后继续，之后的测试临时文件都放在 E 盘。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="本地实测skinloom-up---dev">本地实测（<code>skinloom up --dev</code>）<a href="https://docs.skinloom.cn/devlog/m3-admin-api#%E6%9C%AC%E5%9C%B0%E5%AE%9E%E6%B5%8Bskinloom-up---dev" class="hash-link" aria-label="本地实测skinloom-up---dev的直接链接" title="本地实测skinloom-up---dev的直接链接" translate="no">​</a></h2>
<p>初始化站点后，超级管理员创建一个带管理类 scope 的个人访问令牌，alice 注册并创建角色 Steve。用 curl：</p>
<ol>
<li class=""><code>GET /api/admin/users?q=alice</code>：Laravel 分页格式，用户对象带 <code>ip</code>。</li>
<li class="">把 alice 的积分设为 321：返回 <code>{"code":0}</code>，alice 自己看到的积分是 321。</li>
<li class=""><code>GET /api/admin/players?q=uid:2</code> 列出 Steve；改名为 <code>Steve_Admin</code> 成功。</li>
<li class="">alice 的衣柜和举报列表为空时返回空数组和空分页。</li>
<li class="">给 alice 发通知：返回 <code>{"code":0}</code>，alice 的未读数是 1。</li>
<li class="">修改自己的权限：403，<code>{"code":1,"message":"你没有权限这么做。"}</code>。</li>
</ol>
<p>服务端日志没有警告或错误。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="测试">测试<a href="https://docs.skinloom.cn/devlog/m3-admin-api#%E6%B5%8B%E8%AF%95" class="hash-link" aria-label="测试的直接链接" title="测试的直接链接" translate="no">​</a></h2>
<ul>
<li class="">HTTP（SQLite 与 PostgreSQL 都跑）：
<ul>
<li class="">普通用户不能创建管理类令牌，普通用户的令牌调用管理接口 403；</li>
<li class="">用户列表的搜索与翻页，昵称、积分、验证状态、封禁与解封、设为管理员，不能设超级管理员；管理员不能改自己、不能改超级管理员，可以改普通用户；</li>
<li class="">角色按主人筛选、改名、不存在的材质、不存在的新主人、转移、删除；</li>
<li class="">衣柜放入、重复放入、查看、取出、重复取出；</li>
<li class="">举报列表的形状与筛选、驳回、重复处理；</li>
<li class="">通知按 ID、按不存在的邮箱、给普通用户；</li>
<li class="">被降级的管理员的令牌 403；审计日志里有对应记录。</li>
</ul>
</li>
<li class="">全量回归：
<ul>
<li class="">Go：<code>go test ./...</code>（SQLite 与 PostgreSQL）、vet、staticcheck、govulncheck；</li>
<li class="">生成代码无差异、迁移无漂移。</li>
</ul>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="问题与风险">问题与风险<a href="https://docs.skinloom.cn/devlog/m3-admin-api#%E9%97%AE%E9%A2%98%E4%B8%8E%E9%A3%8E%E9%99%A9" class="hash-link" aria-label="问题与风险的直接链接" title="问题与风险的直接链接" translate="no">​</a></h2>
<ul>
<li class="">BS 完整的 search-string 语法（排序、比较、多个条件）不支持，只认第一个 <code>字段:值</code> 和普通文字。</li>
<li class="">和前两部分一样，没有用真实的 BS 管理面板或脚本实际接过。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m3-admin-api#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M3 最后一部分：社交登录（GitHub、Microsoft 等通用 OAuth2 / OIDC 登录）。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M3" term="M3"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[第 15 期 · M3 第二部分：OAuth 2.0 与开放 API]]></title>
        <id>https://docs.skinloom.cn/devlog/m3-oauth</id>
        <link href="https://docs.skinloom.cn/devlog/m3-oauth"/>
        <updated>2026-10-30T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[M3 第二部分让其它网站和程序可以"用云织账号登录"：云织现在是一个 OAuth 2.0 授权服务器，资源接口与 Blessing Skin 相同，为 BS 写的应用换个地址就能用。用户也可以创建个人访问令牌，给自己的脚本使用。]]></summary>
        <content type="html"><![CDATA[<p>M3 第二部分让其它网站和程序可以"用云织账号登录"：云织现在是一个 OAuth 2.0 授权服务器，资源接口与 Blessing Skin 相同，为 BS 写的应用换个地址就能用。用户也可以创建个人访问令牌，给自己的脚本使用。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="本期完成">本期完成<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E6%9C%AC%E6%9C%9F%E5%AE%8C%E6%88%90" class="hash-link" aria-label="本期完成的直接链接" title="本期完成的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>授权服务器</strong>（<code>internal/oauth</code>）：
<ul>
<li class="">授权码流程，支持 PKCE（<code>S256</code>、<code>plain</code>）、刷新令牌（每次使用都换新的）、吊销（RFC 7009）、服务器元数据（RFC 8414）；</li>
<li class="">令牌端点接受表单或 JSON，客户端凭据放 HTTP Basic 或表单都行；错误是 RFC 6749 的格式，再加 Passport 客户端读的 <code>message</code>。</li>
</ul>
</li>
<li class=""><strong>授权确认页</strong>：显示应用、创建者和每一项权限的说明；已经允许过的应用不再询问。</li>
<li class=""><strong>应用与令牌</strong>页面（<code>/user/oauth/manage</code>，BS 的同名页面）：
<ul>
<li class="">我的应用：服务端应用（密钥只显示一次，可以重置）或公开客户端（必须用 PKCE）；</li>
<li class="">已授权的应用：查看、撤销；</li>
<li class="">个人访问令牌：选权限和有效期，显示最近使用时间。</li>
</ul>
</li>
<li class=""><strong>兼容 BS 的资源 API</strong>：<code>/api</code>、<code>/api/user</code>、通知、角色、衣柜的读写，模型字段、<code>{code, message, data}</code>、Laravel 的 422 格式都与 BS 一致。</li>
<li class="">改密码、找回密码、封禁、注销、退出其它设备时，应用的令牌和个人访问令牌一起失效。</li>
<li class="">设计记录：<a href="https://github.com/Entropy-Increase-Team/skinloom/blob/main/docs/adr/0023-oauth-provider-and-resource-api.md" target="_blank" rel="noopener noreferrer" class="">ADR 0023</a>；文档站新增<a class="" href="https://docs.skinloom.cn/docs/development/api">开放平台</a>。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="为什么没有用-oidc-库">为什么没有用 OIDC 库<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E4%B8%BA%E4%BB%80%E4%B9%88%E6%B2%A1%E6%9C%89%E7%94%A8-oidc-%E5%BA%93" class="hash-link" aria-label="为什么没有用 OIDC 库的直接链接" title="为什么没有用 OIDC 库的直接链接" translate="no">​</a></h2>
<p>设计文档原本选了 zitadel/oidc。真正需要的只是授权码 + PKCE、刷新、吊销，状态全在自己的四张表里，还要和网页会话在同一个事务里吊销。这个库以 OIDC 为中心，要实现一整套存储接口，还会带进不少依赖。所以先自己实现这一小块，等做 Yggdrasil Connect（OIDC）时再决定是在这套表上加 ID Token，还是引入库。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="修掉的-bs-问题">修掉的 BS 问题<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E4%BF%AE%E6%8E%89%E7%9A%84-bs-%E9%97%AE%E9%A2%98" class="hash-link" aria-label="修掉的 BS 问题的直接链接" title="修掉的 BS 问题的直接链接" translate="no">​</a></h2>
<ul>
<li class="">应用密钥明文保存，并一直显示在页面上；访问令牌默认一年。</li>
<li class="">衣柜写权限注册成了拼错的 <code>Closet.ReadWrtie</code>，路由却要 <code>Closet.ReadWrite</code>，第三方应用永远拿不到；现在两种写法都接受。</li>
<li class="">改密码、找回密码不吊销 OAuth 令牌；删除用户留下孤儿令牌。</li>
<li class="">读不存在的通知报 500；衣柜分页 <code>perPage</code> 没有上限。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="开发中发现的问题">开发中发现的问题<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E5%BC%80%E5%8F%91%E4%B8%AD%E5%8F%91%E7%8E%B0%E7%9A%84%E9%97%AE%E9%A2%98" class="hash-link" aria-label="开发中发现的问题的直接链接" title="开发中发现的问题的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>PostgreSQL 事务里的唯一冲突</strong>：最早的写法是在一个事务里先 <code>SELECT … FOR UPDATE</code> 授权记录，没有就插入、冲突了当作已存在，然后写授权码。编译时发现这一版 ent 没有开行锁；而且这个写法在 PostgreSQL 上本来就不成立：事务里一旦有语句出错，整个事务作废，后面写授权码也会失败。改成先写授权记录（不放事务里，冲突时重读再合并），再单独写授权码。</li>
<li class=""><strong>Huma 不展开请求体里的嵌入结构体</strong>：确认授权的请求体复用了查询参数的结构体，结果每个字段都被报"unexpected property"。改为把字段逐个写出来。</li>
<li class=""><strong>兼容接口里的 HTML</strong>：Go 的 JSON 默认把 <code>&lt;</code> 转义成 <code>&lt;</code>。通知正文是 HTML，PHP 的 <code>json_encode</code> 不会这样转义，兼容接口里关掉了。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="本地实测skinloom-up---dev">本地实测（<code>skinloom up --dev</code>）<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E6%9C%AC%E5%9C%B0%E5%AE%9E%E6%B5%8Bskinloom-up---dev" class="hash-link" aria-label="本地实测skinloom-up---dev的直接链接" title="本地实测skinloom-up---dev的直接链接" translate="no">​</a></h2>
<ol>
<li class="">用 API 初始化站点，注册 dev 和 alice；dev 注册一个服务端应用，回调地址指向本站一个不存在的页面，方便看跳转结果。</li>
<li class="">浏览器未登录时打开 <code>/oauth/authorize?…&amp;scope=User.Read Player.ReadWrite Closet.ReadWrtie&amp;state=…</code>：先跳到登录页，<code>next</code> 带着完整的授权参数；alice 登录后回到确认页，页面显示"Forum 想要访问你的账号，由 dev 创建"和三项权限，拼错的 scope 显示为 <code>Closet.ReadWrite</code>。</li>
<li class="">点"授权"，浏览器回到回调地址，带着 <code>code</code> 和原来的 <code>state</code>。</li>
<li class="">用 curl 以 HTTP Basic 兑换授权码，得到 <code>slo_</code> / <code>slr_</code> 令牌，有效期 86400 秒；同一个授权码再兑换一次返回 <code>invalid_grant</code>。</li>
<li class="">用访问令牌：
<ul>
<li class=""><code>/api/user</code> 返回 BS 格式的用户；</li>
<li class="">添加角色 Steve 返回 <code>{"code":0,…}</code>，列表里有它；</li>
<li class="">没有 <code>Notification.Read</code> 时读通知返回 403；</li>
<li class="">空衣柜返回 Laravel 分页格式。</li>
</ul>
</li>
<li class="">刷新令牌换到新的一对，旧的访问令牌立即 401。<code>/api</code> 和元数据端点正常。</li>
<li class="">再次打开授权地址（只要 <code>User.Read</code>），没有出现确认页，直接带着新的 <code>code</code> 回到应用。</li>
<li class="">"应用与令牌"页面：已授权的应用里有 Forum 和三项权限；普通用户的权限列表里没有管理类权限。在页面上创建一个只有 <code>Player.Read</code> 的个人访问令牌：读角色 200，读用户和写角色都是 403；列表显示了最近使用时间。服务端日志没有警告或错误。</li>
</ol>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="测试">测试<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E6%B5%8B%E8%AF%95" class="hash-link" aria-label="测试的直接链接" title="测试的直接链接" translate="no">​</a></h2>
<ul>
<li class="">服务层（SQLite 与 PostgreSQL）：
<ul>
<li class="">scope 解析、旧拼写、<code>ReadWrite</code> 包含 <code>Read</code>、管理类过滤；</li>
<li class="">应用的增删改、回调地址校验、只有主人能改、重置密钥后旧密钥失效；</li>
<li class="">授权请求：不跳转的错误（未知应用、未登记的回调、有多个回调却没指明）与跳回应用的错误（<code>state</code> 保留），已授权时跳过确认，主人被封禁后停用；</li>
<li class="">授权码：客户端认证、另一个应用拿不到、回调地址不一致、只能用一次、5 个并发兑换只有 1 个成功；PKCE 校验失败后授权码作废，公开客户端不能带密钥；</li>
<li class="">刷新：轮换、缩小、不能扩大、只能由原应用刷新、过期；</li>
<li class="">撤销授权、RFC 7009 吊销、个人访问令牌（权限、过期、最近使用、清理）、封禁与注销的账号；</li>
<li class="">退出其它设备后应用令牌与个人访问令牌全部失效。</li>
</ul>
</li>
<li class="">HTTP：从注册应用、授权、兑换到每个兼容接口、个人访问令牌、撤销、元数据、CORS 预检走一遍。</li>
<li class="">全量回归：
<ul>
<li class="">Go：<code>go test ./...</code>（SQLite 与 PostgreSQL）、vet、staticcheck、govulncheck；</li>
<li class="">生成代码无差异、迁移无漂移；</li>
<li class="">前端：类型检查、单元测试、生产构建、<code>bun audit</code>。</li>
</ul>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="问题与风险">问题与风险<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E9%97%AE%E9%A2%98%E4%B8%8E%E9%A3%8E%E9%99%A9" class="hash-link" aria-label="问题与风险的直接链接" title="问题与风险的直接链接" translate="no">​</a></h2>
<ul>
<li class="">没有拿真实的 Blessing Skin 第三方应用（比如论坛插件）实际接一次，只按 Passport 的协议和 BS 的代码对照验证。</li>
<li class="">资源 API 的限流和登录限流一样在每个实例的内存里。</li>
<li class="">访问令牌默认 1 天，比 BS 的一年短很多；从不刷新令牌的旧应用会在一天后失效，需要时站长可以调长。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="下期计划">下期计划<a href="https://docs.skinloom.cn/devlog/m3-oauth#%E4%B8%8B%E6%9C%9F%E8%AE%A1%E5%88%92" class="hash-link" aria-label="下期计划的直接链接" title="下期计划的直接链接" translate="no">​</a></h2>
<p>M3 第三部分：兼容 BS 的管理类接口（<code>/api/admin/*</code>）；之后是社交登录。</p>]]></content>
        <author>
            <name>熵增项目组 · SkinLoom 维护者</name>
            <uri>https://github.com/Entropy-Increase-Team</uri>
        </author>
        <category label="devlog" term="devlog"/>
        <category label="M3" term="M3"/>
    </entry>
</feed>