v0.2.5

v0.2.5

日期：2026-10-15

这是 v0.2.4 之后的起始店面打包修复。公开页面、设备码、授权范围、买家注册、买入开关、支付成功条件、店面缓存、文本压缩范围、Caddy 匹配和安装回滚都没有改。没有新的数据库迁移。compose.yaml 与 v0.2.4 相同。install.sh 与 v0.2.4 相同。

v0.2.4 把 storefront/ 放进了运行镜像，但还没有发布记录时，下载仍要现场生成默认 HTML。生成步骤会执行 scripts/render-starter.mjs，再用 TypeScript 编译页面模板。v0.2.4 的运行镜像没有这个脚本，也没有编译器。异常被收成 50301，正文是「店面下载暂时不可用。」首页仍是内置页。txpearl.cn 上 storefront_releases 是 0 行，所以每次下载都走这里。

这一版在应用构建之后渲染两次，分别得到买入关闭和开启的起始页，再合成 /app/storefront-starter.json。运行镜像没有渲染脚本时，下载按进程已有的买入开关选择其中一份，不再启动渲染脚本。工作目录里仍有脚本时，继续执行脚本，不用这份 JSON。三份样式文件由 Dockerfile 显式复制，不靠 standalone 追踪。已有发布仍下载该发布自己的源码包。发布构建不接收 MERCLINK_PURCHASE，也不为它增加 build-arg。

生产应用镜像是 docker.io/<用户名>/merclink:0.2.5。正式版同时推送 0.2.5 和 latest。只换应用镜像即可。不需要换 compose.yaml。往正在运行的 v0.2.4 容器里补文件没有用，那一版的代码不读这份 JSON。

中文

这一版能做什么

• 构建阶段在 pnpm run build 之后复制 scripts/render-starter.mjs，再分别以 MERCLINK_PURCHASE=0 和 MERCLINK_PURCHASE=1 执行它。这两个赋值只属于构建命令，不写入镜像 ENV 或 ARG。结果合并为 storefront-starter.json，里面是 "0" 和 "1" 两份六个页面。任一份缺非空页面，构建失败。runner 把该文件复制到 /app/storefront-starter.json，不复制渲染脚本。
• runner 在 standalone 复制之后，显式复制 src/app/globals.css、src/public-discovery/public.css 和 src/app/authorize/authorize.css。
• 工作目录没有渲染脚本时，GET /api/v1/storefront/source 按 currentPurchaseEnabled() 选择 "0" 或 "1"，并继续打包 /app/storefront 里的 accept.mjs、preview.mjs、render-slots.mjs 和 README.md。两份六个片段都必须是非空字符串，否则仍是 50301。
• 工作目录有 scripts/render-starter.mjs 时，开发和测试执行该脚本，即使留下了 storefront-starter.json 也不读它。该 JSON 不提交。
• 已经接受过发布时，下载的仍是该发布保存的源码包。没有激活的发布时，公开页仍是内置页。

这一版不做

• 不把 TypeScript、页面模板源码或 scripts/render-starter.mjs 放进运行镜像。
• 不把 MERCLINK_PURCHASE 写成镜像 ENV 或 Docker ARG。同一镜像同时带上买入关闭和开启的起始页。
• 不改公开页的店名、货架、二维码和执照尺寸、页脚或规格轴显示。
• 不改设备码流程、scope、买家注册或支付成功条件。只有订单状态 paid 表示支付成功。
• 不改店面 HTML 的 no-store，也不改 CSS、JS 的 10 分钟新鲜期和之后最多 24 小时的后台校验。
• 不改公开图片按 id 缓存一年的规则。缺失图片仍是 404。
• 不改 Caddy 的五行 Content-Type 匹配，也不改镜像标签。仍是 caddy:2.11.7-alpine。
• 不改一键安装询问的字段，不安装系统包，也不默认打开买入。安装和升级未完成时的回滚与 v0.2.4 相同。
• 不改 50301 的文案。JSON 或样式缺失时仍返回「店面下载暂时不可用。」已有发布的对象缺失时，文案仍是「店面源码暂时无法读取。」
• 不激活店面，不补写历史发布，也不把 Docker Hub 用户名、令牌、域名或证书写进仓库。

升级注意

修复在应用镜像里。compose.yaml 和 install.sh 与 v0.2.4 相同。不要删 .env，也不要删 caddy_data。不要在 v0.2.4 容器里手工放入 storefront-starter.json。

一键安装过的机器，等这个正式版发布后执行：

curl -fsSL -o /tmp/merclink-install.sh https://github.com/ptonlix/MercLink/releases/latest/download/install.sh && bash /tmp/merclink-install.sh upgrade

upgrade 会下载这个 tag 的 compose.yaml，保留已有密钥和后来手工打开的买入配置，然后 pull。它不打印已保存的密码。这次 compose.yaml 没有变化。升级如果没有完成，部署文件和版本号会回到升级前；已经换上的容器要再执行 docker compose up -d 才和文件一致。

手工部署的机器不要再跑一键安装。把 MERCLINK_IMAGE 改为 docker.io/<用户名>/merclink:0.2.5，然后执行：

docker compose pull && docker compose up -d

不要加 --build。拉取完成后，用带 storefront:write 的商家令牌再请求 GET /api/v1/storefront/source。还没有发布记录时，压缩包里应有 accept.mjs 和 static/index.html。

回滚时把应用镜像改回 docker.io/<用户名>/merclink:0.2.4，再 pull。不要把 latest 当作回滚点。latest 会在这个正式版发布时移到 0.2.5。退回 0.2.4 会再次缺少渲染结果，第一次下载又会返回 50301。

English

Date: 2026-10-15

This is the starter storefront packaging fix after v0.2.4. The public pages, device-code flow, authorization scopes, buyer registration, purchase switch, the rule that only paid means payment success, storefront caching, the set of compressed types, the Caddy matchers, and install rollback are unchanged. There is no new database migration. compose.yaml is the same file as v0.2.4. install.sh is the same file as v0.2.4.

v0.2.4 places storefront/ in the runner image, but a download with no accepted release still generates the default HTML at request time. That step executes scripts/render-starter.mjs and compiles the page templates with TypeScript. The v0.2.4 runner has neither the script nor the compiler. The error becomes 50301 with the message 店面下载暂时不可用。 The home page stays on the built-in page. On txpearl.cn, storefront_releases has no rows, so every download takes this path.

This version renders twice after the application build, once for purchase off and once for purchase on, and combines them into /app/storefront-starter.json. When the runner has no renderer script, a download selects one payload with the process purchase switch and does not start the renderer. When that script is still in the working directory, it runs and the JSON is ignored. The three stylesheets are copied by the Dockerfile, not by standalone tracing. A release that has already been accepted is still downloaded as that release's own source archive. The release build does not receive MERCLINK_PURCHASE and does not add a build-arg for it.

The production image is docker.io/<namespace>/merclink:0.2.5. The stable release also publishes latest. Replacing the application image is enough. compose.yaml does not need to change. Copying files into a running v0.2.4 container does nothing. That version does not read this JSON.

What this version does

• After pnpm run build, the build stage copies scripts/render-starter.mjs and runs it once with MERCLINK_PURCHASE=0 and once with MERCLINK_PURCHASE=1. Those assignments belong only to the build command, not to image ENV or ARG. The combined storefront-starter.json holds a "0" payload and a "1" payload, each with six pages. The build fails if either payload is missing a non-empty page. The runner copies that file to /app/storefront-starter.json and does not copy the renderer script.
• After the standalone copy, the runner explicitly copies src/app/globals.css, src/public-discovery/public.css, and src/app/authorize/authorize.css.
• When the working directory has no renderer script, GET /api/v1/storefront/source selects "0" or "1" with currentPurchaseEnabled() and still packs accept.mjs, preview.mjs, render-slots.mjs, and README.md from /app/storefront. Both payloads must contain six non-empty strings; otherwise the download is still 50301.
• When scripts/render-starter.mjs is in the working directory, development and tests run that script and do not read a leftover storefront-starter.json. That JSON is not committed.
• After a release has been accepted, the download remains that release's stored source archive. With no active release, public pages remain the built-in pages.

What this version does not do

• It does not put TypeScript, the template sources, or scripts/render-starter.mjs in the runner image.
• It does not set MERCLINK_PURCHASE as an image ENV or Docker ARG. One image carries both the purchase-off and purchase-on starter pages.
• It does not change the public store name, shelf, contact-QR or license size, footer, or variant-axis display.
• It does not change the device-code flow, scopes, buyer registration, or the payment-success rule. Only order status paid means payment succeeded.
• It does not change no-store on storefront HTML, or the 10-minute freshness window and later 24-hour background revalidation for CSS and JS.
• It does not change the one-year cache for a public image id. A missing image is still 404.
• It does not change Caddy's five Content-Type lines or the image tag. It remains caddy:2.11.7-alpine.
• It does not change what one-click install asks for, it does not install system packages, and it does not turn purchase on by default. Rollback of an unfinished install or upgrade stays as it was in v0.2.4.
• It does not change the 50301 wording. A missing JSON file or stylesheet still returns 店面下载暂时不可用。 A missing object for an accepted release still returns 店面源码暂时无法读取。
• It does not activate a storefront, backfill old releases, or store a Docker Hub username, token, domain, or certificate in the repository.

Upgrade note

The fix is in the application image. compose.yaml and install.sh match v0.2.4. Do not delete .env or caddy_data. Do not place storefront-starter.json into a running v0.2.4 container by hand.

After this stable release is published, a host installed by the script should run:

curl -fsSL -o /tmp/merclink-install.sh https://github.com/ptonlix/MercLink/releases/latest/download/install.sh && bash /tmp/merclink-install.sh upgrade

upgrade downloads compose.yaml for this tag, keeps generated secrets and any later purchase settings, then pulls. It does not print stored passwords. This compose.yaml is unchanged. If this upgrade does not finish, the deploy files and version pin return to their previous values. Containers already recreated from the new image match those files only after another docker compose up -d.

Do not run a fresh one-click install over a deployment that was created by hand. Set MERCLINK_IMAGE to docker.io/<namespace>/merclink:0.2.5, then run:

docker compose pull && docker compose up -d

Do not add --build. After the pull, request GET /api/v1/storefront/source again with a merchant token that has storefront:write. When no release row exists, the archive contains accept.mjs and static/index.html.

To roll back, set the application image to docker.io/<namespace>/merclink:0.2.4 and pull again. Do not use latest as the rollback point. latest moves to 0.2.5 when this stable release is published. Returning to 0.2.4 removes the rendered fragments again, and the first download returns 50301.