v0.2.1

v0.2.1

日期：2026-10-13

这是 v0.2.0 之后的部署和店面传输修复版。店、授权范围、公开发现、买入规则和支付成功条件没有改。这一版给新机器一条正式版安装入口，并让已发布店面的静态资源和公开图片可以被复用、文本可以被压缩。商品和店铺事实仍每次现算。生产应用镜像是 docker.io/<用户名>/merclink:0.2.1。正式版同时推送 0.2.1 和 latest。

中文

这一版能做什么

• 正式版 GitHub Release 附带 install.sh。永久入口是 https://github.com/ptonlix/MercLink/releases/latest/download/install.sh。这个地址跳过预发布，和镜像规则一致：只有正式 tag 才移动 latest。
• 新机器执行该脚本后，在 /opt/merclink 下载同一 tag 的 compose.yaml，生成权限为 600 的 .env，再执行已有的 docker compose pull && docker compose up -d。不带 --build，不在部署机编译。
• 一键安装把应用镜像写成 docker.io/<用户名>/merclink:latest，不用填写版本号。用户名只在发布时盖进 Release 资源，不进 git，也不写进这份说明。
• 安装只询问公网域名、证书通知邮箱和管理员手机号。已导出的 APEX_DOMAIN 才会写入。数据库、Redis、对象存储、管理员和签名密钥在本机生成。管理员初始密码只在安装结束时打印一次。固定打开 Caddy，应用只监听 127.0.0.1:3000，APP_BASE_URL 是 https:// 加该域名。不写 MERCLINK_PURCHASE，买入仍默认关闭。
• 已有 .env 时拒绝再次安装，避免覆盖密码。TCP 80 或 443 已被占用时，在写配置前退出，不停掉现有网站。没有 Docker 或 Compose 插件时退出，不安装系统包，也不关闭 TLS 校验。
• upgrade 只替换镜像和 release tag，并重新下载同一 tag 的 compose.yaml，然后 pull。已有密钥，以及后来手工打开的买入配置，都保留。不打印已保存的密码。
• 已发布店面里的 CSS、JS 和其他非 HTML 文件允许浏览器缓存 10 分钟，之后最多再把旧文件当作过期响应使用 24 小时，同时在后台用对象键做弱校验。对象键变了才算新文件。重复且未变化的请求返回 304，不再读对象存储。
• 含商品或店铺事实的 HTML 继续 cache-control: no-store。路径不是小写 .html 但内容类型是 HTML 的文件同样不缓存。
• 店面文本在客户端接受 gzip 且压缩后更小时再压缩。图片和字体保持原字节。公开媒体按图片 id 缓存一年；id 不存在时仍是 404，条件请求不能把缺失图片变成 304。
• 正式 Compose 的 Caddy 只压缩文本、JSON、XML、JavaScript 和 SVG，不再压缩 WebP、PNG、JPEG 或 GIF。

这一版不做

• 不改设备码流程、scope、买家注册或支付成功条件。没有新的数据库迁移。
• 不在脚本里安装 Docker、Python 或 openssl，不收集支付宝、短信或验证码密钥，不默认打开买入。
• 不把 Docker Hub 用户名、令牌、域名或生成的密钥写进仓库。
• 不把店面搬到 CDN，不给 CSS 加指纹，不缓存商品查询结果，也不让 HTML 带 max-age。
• 不在应用进程内缓存对象字节。不压缩已经压缩过的图片和字体。

升级注意

已经手工部署的机器不要再跑一键安装。一键安装固定打开 Caddy，并要求 80 和 443 空闲。它也不会接管别的目录里的现有 .env。

这类机器先换成这一版的 compose.yaml，再把 MERCLINK_IMAGE 改为 docker.io/<用户名>/merclink:0.2.1，然后执行：

docker compose pull && docker compose up -d

不要加 --build。只改镜像也能让应用自己压缩店面文本并带上缓存头。换成这一版 Compose 后，Caddy 才会按内容类型压缩文本，并跳过商品图。

新机器用：

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

域名要先解析到这台机器，并放行 TCP 80 和 443。安装写到一半失败时不要删 .env。应执行 upgrade，或在该目录重新 pull。以后换成更新的正式版：

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

店主激活新店面后，已经打开过页面的浏览器在 10 分钟内可以继续使用旧 CSS 和 JS，之后最多再使用 24 小时并在后台重新校验。新访客立即看到新文件。价格、库存和店铺资料不从旧 HTML 复用。

回滚应用镜像到 0.2.0 时使用版本号标签，不使用 latest。latest 会被下一个正式版覆盖。只改镜像不会把 Compose 里的 Caddy 压缩规则退回去；要退回旧代理配置，还得换回那一版的 compose.yaml。

English

Date: 2026-10-13

This is a deployment and storefront transfer fix after v0.2.0. The store, authorization scopes, public discovery, purchase rules, and the rule that only paid means payment success are unchanged. This version adds a stable installer for a new machine, and lets released storefront assets and public images be reused while text can be compressed. Product and shop facts are still calculated on each request. The production image is docker.io/<namespace>/merclink:0.2.1. The stable release also publishes latest.

What this version does

• The stable GitHub Release includes install.sh. The permanent entry is https://github.com/ptonlix/MercLink/releases/latest/download/install.sh. That URL skips prereleases, matching the image rule: only a stable tag moves latest.
• On a new machine the script creates /opt/merclink, downloads compose.yaml from the same tag, writes .env with mode 600, and runs the existing docker compose pull && docker compose up -d. It does not pass --build and does not compile on the deploy host.
• A one-click install sets the application image to docker.io/<namespace>/merclink:latest. The operator does not choose a version. The registry username is stamped into the Release asset at publish time. It is not committed and is not written in these notes.
• Install asks only for the public hostname, certificate email, and admin phone number. APEX_DOMAIN is written only when the caller has already exported it. Database, Redis, object-storage, admin, and signing secrets are generated on the host. The initial admin password is printed once at the end. Caddy is enabled, the app binds to 127.0.0.1:3000, and APP_BASE_URL is https:// plus that hostname. MERCLINK_PURCHASE is not set, so purchase stays off.
• If .env already exists, install exits without changing it. If TCP 80 or 443 is already in use, it exits before writing config and does not stop the existing site. If Docker or the Compose plugin is missing, it exits without installing packages and without disabling TLS verification.
• upgrade replaces only the image and release tag, downloads compose.yaml for that same tag, and pulls. Generated secrets and any later purchase settings are kept. Stored passwords are not printed.
• Released storefront CSS, JS, and other non-HTML files may be cached for 10 minutes. After that, a browser may reuse the stale file for up to 24 hours while revalidating in the background. The weak validator is the object key, so a new release is a new file. An unchanged repeat request returns 304 and does not read object storage again.
• HTML that contains product or shop facts stays cache-control: no-store. A file whose content type is HTML is treated the same way even when the path does not end in lowercase .html.
• Released text is gzipped when the client accepts gzip and the compressed body is smaller. Images and fonts stay as stored bytes. Public media is cached for one year by image id. An unknown id is still 404. A conditional request cannot turn a missing image into 304.
• Production Caddy compresses only text, JSON, XML, JavaScript, and SVG. It does not compress WebP, PNG, JPEG, or GIF.

What this version does not do

• It does not change the device-code flow, scopes, buyer registration, or the payment-success rule. There is no new database migration.
• It does not install Docker, Python, or openssl, collect Alipay, SMS, or captcha secrets, or turn purchase on by default.
• It does not store a Docker Hub username, token, domain, or generated secret in the repository.
• It does not move the storefront to a CDN, fingerprint CSS URLs, cache product queries, or put max-age on HTML.
• It does not cache object bytes in the application process, and it does not compress images or fonts.

Upgrade note

Do not run a fresh one-click install over a deployment that was created by hand. That installer always enables Caddy and requires ports 80 and 443 to be free. It also does not take over an existing .env in another directory.

On those machines, replace compose.yaml with this version, set MERCLINK_IMAGE to docker.io/<namespace>/merclink:0.2.1, then run:

docker compose pull && docker compose up -d

Do not add --build. Changing only the image is enough for the application to gzip storefront text and send the new cache headers. The Caddy content-type rules, including skipping product images, arrive only with this version of Compose.

For a new machine:

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

Point the domain at the machine first, and open TCP 80 and 443. If install fails after writing config, do not delete .env. Run upgrade, or pull again in that directory. To move an installed host to a later stable release:

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

After a merchant activates a new storefront, a browser that already opened the shop may keep the old CSS and JS for 10 minutes, then for up to 24 hours while revalidating. A new visitor sees the new files immediately. Price, stock, and profile facts are not reused from old HTML.

Roll the application image back to 0.2.0 by version tag, not by latest. latest moves again on the next stable release. Changing only the image does not remove the Caddy compression rules. To restore the old proxy config, also restore that version of compose.yaml.