Desktop update policy and installation
Desktop 更新策略与安装
Desktop usually runs a local dsh server, so remote business errors cannot reliably deliver mandatory-update policy. Users need automatic discovery, user-initiated downloads, visible preparation state, and separate restart approval that accounts for running tasks.
English
Problem
Desktop usually runs a local dsh server, so remote business errors cannot reliably deliver mandatory-update policy. Users need automatic discovery, user-initiated downloads, visible preparation state, and separate restart approval that accounts for running tasks.
Proposal
This proposal records outstanding release and backend work; the Desktop README owns current client behavior.
| Document | Owns |
|---|---|
| This proposal | Outstanding release, backend, CDN, and product decisions |
| Mandatory-update API | Request and response fields, server policy requirements, backend integration checklist |
| Deferred extensions | Independent Desktop revisions, channel switching, automatic installation, replacement of pending updates |
Release and backend qualification
Release owners must qualify signed Windows x64 and macOS x64/arm64 upgrades end to end: discovery, download, hash and signature checks, task-safe shutdown, installation, restart, new-version Host startup, and profile reconciliation. Publish immutable packages and blockmaps before the mutable Nightly feed. The packaging decision owns version and artifact rules. The API proposal owns policy fields; production integration must verify guest access, force/no-force responses, errors, platform selection, approved origins, and rate limits. Publish a resolving updater release before enabling mandatory policy.
Open product choices
Persisting a mandatory block across a same-version offline restart requires product confirmation. If newer C appears while A downloads or waits for installation, retain A until product owners approve replacement; never silently turn approval for A into installation of C. Installed Windows and macOS attention remains subject to notification permissions, focus modes, minimized windows, and stale clicks. The deferred extensions own automatic replacement and installation.
<a id="cdn-and-capacity-qualification"></a>
CDN and capacity qualification
The following release and operations choices are pending; they are not active CDN settings or completed load qualification.
- Operations: separate
/dsh-desk/feeds/*from/dsh-desk/bin/*; do not retain a blanket cache bypass for large production downloads. For feeds, evaluate client revalidation withmax-age=0, a 30–60-second edge TTL, and a purge on publication. Agree on the maximum propagation delay and measure fixed-URL replacement across regions; a purge is not a guarantee of immediate global visibility. - Operations and release owner: evaluate a 30-day to one-year edge TTL for versioned or hash-named packages and blockmaps, without overwriting their URLs. Upload and verify binaries, prewarm them, then publish the feed; confirm retention covers older clients' differential-update inputs.
- Operations and Desktop maintainers: verify node TTL separately from client Cache-Control, using repeat-request cache status, hit ratio, and COS origin metrics. Check whether updater-added query parameters fragment the cache key or bypass caching; ignore only parameters proven irrelevant to content. Verify Range/206, Content-Range, complete-file hashes, and feed freshness through the actual updater. See Tencent's node TTL, browser TTL, and cache configuration documentation.
- Desktop maintainers and product owner: confirm startup and overdue-resume burst handling. Periodic jitter and bounded failure backoff are implemented and tested; startup and overdue wakeups still check immediately. Adding a short randomized delay to those triggers needs product confirmation. Mandatory-policy polling remains a separate API and scheduling policy.
- Operations and release owner: size request and bandwidth budgets using online clients, startup/manual/retry peaks, package sizes, and expected download participation. At evenly distributed ten-minute polling, 100,000 online clients average about 167 checks/second and 1,000,000 about 1,667, before extra triggers. CDN caching reduces origin load, not client download traffic charges; a functional probe is not a load test.
- Operations: configure cache-hit, origin-QPS, error-rate, bandwidth, and cost alerts with agreed thresholds and an on-call owner. Qualify abuse protection without breaking updater requests or shared-NAT clients; updater endpoints must not require an interactive browser challenge. Record an incident response procedure before launch.
Alternatives considered
Automatic package predownload. This consumes bandwidth before the user requests a download. Automatic discovery remains useful, but every initial transfer and retry requires user action independently of later installation approval.
Automatic restart or installation on ordinary quit. This bypasses explicit task-impact approval. Automatic installation requires separate product authorization and platform verification.
One remote API controlling all updates. Mandatory policy and ordinary artifact discovery have different responsibilities. Keep the policy page separate from updater metadata and reuse only the installation coordinator when qualified.
Acceptance criteria
- Signed installed-version upgrades pass on Windows x64 and macOS x64/arm64, including new-version Host startup and retained data.
- Deployed policy integration passes the API proposal’s guest, force/no-force, error, and platform matrix without local fixtures.
- Release owners record CDN freshness, Range and hash behavior, request and bandwidth budgets, alert thresholds, and an incident owner.
- Product owners decide offline mandatory persistence and target replacement before either behavior is promised.
Risks
Local updater and UI checks do not prove installed-upgrade compatibility, deployed policy availability, or CDN performance. Enabling mandatory policy before a resolving artifact exists can block users without an in-app upgrade path.
中文
问题
Desktop 通常运行本地 dsh server，无法依靠远程业务错误可靠触达强制更新策略。用户需要自动发现、主动下载、可见的准备状态，以及考虑运行中任务影响的独立重启确认。
提案
本文记录尚未完成的发布与后端工作；桌面 README负责当前客户端行为。
| 文档 | 负责内容 |
|---|---|
| 本提案 | 未决发布、后端、CDN 与产品决策 |
| 强制更新接口 | 请求响应字段、服务端策略要求与后端联调清单 |
| 后续扩展 | Desktop 独立修订、通道切换、自动安装及待安装更新替换 |
发布与后端验收
发布负责人须端到端验收真实签名 Windows x64 与 macOS x64/arm64 升级：发现、下载、哈希与签名检查、任务安全的关闭、安装、重启、新版本 Host 启动及 profile 校准。先发布不可变安装包和 blockmap，再发布可变 Nightly 清单。打包决策负责版本与产物规则。接口提案负责策略字段；生产联调须验证游客访问、强制／无需强更响应、错误、平台选择、获准源站和速率限制。启用强更策略前先发布能解除要求的 updater 版本。
未决产品选择
同版本离线重启后持久保留强更阻断仍需产品确认。若 A 正在下载或等待安装时出现新版 C，在产品负责人批准替换前保留 A；不能把安装 A 的授权静默改为安装 C。已安装 Windows 与 macOS 的提醒仍受通知权限、专注模式、最小化窗口及过期点击影响。后续扩展负责自动替换和安装。
<a id="cdn-and-capacity-qualification"></a>
CDN 与容量验收
以下发布与运维选择尚待确认，不代表已生效的 CDN 配置或已完成的负载验收。
- 运维：分别配置
/dsh-desk/feeds/*与/dsh-desk/bin/*，生产大文件下载不应长期沿用全路径绕过缓存。清单建议评估客户端通过max-age=0重新验证、CDN 节点缓存 30～60 秒、发布时刷新。约定最长传播延迟，并跨区域测量固定 URL 覆盖后的可见时间；刷新不保证全球立即可见。 - 运维与发布负责人：对带版本号或哈希的安装包和 blockmap，评估 30 天至一年的节点缓存，不覆盖其 URL。先上传并验证安装包、完成预热，再发布清单；确认保留周期覆盖旧客户端差分更新所需的输入。
- 运维与 Desktop 维护者：将节点 TTL 与客户端 Cache-Control 分开验证，检查重复请求的缓存状态、命中率和 COS 回源指标。确认 updater 附加的查询参数是否分散缓存键或绕过缓存；只忽略已证明不影响内容的参数。通过实际 updater 验证 Range/206、Content-Range、完整文件哈希和清单及时更新。参阅腾讯云节点 TTL、浏览器 TTL 与缓存配置文档。
- Desktop 维护者与产品负责人：确认启动及到期恢复的突发请求处理。周期抖动和有上限的失败退避已实现并测试；启动和到期唤醒仍立即检查。为这些触发增加短暂随机延迟需要产品确认。强更策略轮询仍使用独立 API 与调度策略。
- 运维与发布负责人：依据在线客户端数、启动／手动／重试峰值、安装包大小和预计下载比例制定请求量与带宽预算。按均匀分布的十分钟轮询，10 万在线客户端平均约 167 次检查／秒，100 万约 1667 次，尚未计入额外触发。CDN 缓存减少回源压力，不消除客户端下载流量费用；功能探测不是负载测试。
- 运维：配置缓存命中率、回源 QPS、错误率、带宽及费用告警，约定阈值与值班负责人。验证异常请求防护不会破坏 updater 请求或误伤共享 NAT 客户端；updater 端点不能要求交互式浏览器验证。上线前记录故障处置流程。
考虑过的替代方案
自动预下载安装包。 会在用户请求下载前消耗流量。保留自动发现，但一期每次传输与重试都需要用户操作，与后续安装授权分开。
自动重启或普通退出时安装。 会绕过明确的任务影响确认。自动安装需要单独的产品授权与平台验证。
一个远程接口控制全部更新。 强制策略与普通产物发现职责不同。策略页面与 updater 元数据分离，验证通过后仅复用安装协调器。
验收标准
- 真实签名 Windows x64 与 macOS x64/arm64 安装版升级通过，包括新版本 Host 启动及数据保留。
- 已部署策略服务通过接口提案的游客、强制／无需强更、错误和平台矩阵，不以本地 fixture 替代。
- 发布负责人记录 CDN 及时更新、Range 与哈希行为、请求和带宽预算、告警阈值及故障负责人。
- 产品负责人在承诺离线强更持久化或目标替换前作出决定。
风险
本地 updater 与界面检查不能证明已安装升级兼容性、线上策略可用性或 CDN 性能。若在能解除要求的产物可用前启用强更策略，用户可能被阻断且无法在应用内升级。