v1.4.9 — 桌面连不上可诊断 + Tailscale/内网 IPv6 放行 + 输入体验改进

桌面连不上，终于能查了（issue #124）

有用户反馈「一直卡在桌面正在启动 / 重连中…」，但导出诊断里什么线索都没有。查下来发现是我们自己的锅：面板处理 WebSocket 连接时有三道校验（Host 白名单 / URL 解析 / 会话权限），任何一道不通过都是静默断开，不留任何日志。于是用户只看到「重连中」，我们也无从下手。

• 三条拒绝路径全部留痕，写入对应实例日志 + 面板日志，导出诊断即可看到：
  • Host 被拒时回显实际收到的 Host / X-Forwarded-Host，并提示加 PANEL_ALLOWED_HOSTS
  • 会话失败细分为「没带 cookie / 会话过期 / 用户不存在 / 被禁用 / 无权限」——反代吞 Cookie 头是常见成因
• 同一实例同一原因 60 秒只记一条，避免 2 秒一次的重连把日志刷爆

Tailscale / 内网 IPv6 现在能直接访问了

这两种此前会被直接 400 拒绝（实测确认）：

• Tailscale / Headscale 的 CGNAT 段 100.64.0.0/10
• 内网 IPv6：fc00::/7（ULA，含 Tailscale 的 fd7a::/48）与 fe80::/10（链路本地）—— 此前只放行 ::1，纯 IPv6 内网用户完全进不来

安全性与原有的 RFC1918 放行同理：校验的是 Host 头字面量，DNS-rebinding 攻击者的 Host 是自己的域名，匹配不上。

微信装不上时不再误导你去查网络

盘写满时 curl 以退出码 23（本地写失败）反复卡在同一字节，连进度文件都写不进去（面板显示无下载进度），此前的报错却提示「请检查网络」—— 真实案例里用户为此查了半天代理。现在下载前先 df 预检、失败后按退出码复查，直接报「磁盘空间不足」并给出清理指引。

输入体验（issue #125）

• 自动回车开关：转发输入条右侧新增 ↵ 开关。关掉后只把文字填进应用输入框、不代发，方便先编辑再自己发（按钮文案随之变「填入」）。默认保持原有行为。
• 功能键排：左侧 Fn 展开 Esc Tab 退格 Del ↵ ← ↑ ↓ →，这些键在 VNC 里常被浏览器吞掉，手机端更是没有。
• 齿轮图标：旧图标路径混进了绝对指令，有两颗齿走形（右下最明显），已换成对称版本。
• 子用户文案：「重启实例」按钮本就按权限隐藏，但提示文字没跟着改，子用户会照着找一个不存在的按钮，现改为提示联系管理员。

---

镜像：ghcr.io/gloridust/{woc-panel,wechat-on-cloud}:1.4.9、gloridust/{woc-panel,wechat-on-cloud}:1.4.9（amd64 + arm64）。升级方式不变：面板「检查更新」一键升级，再「一键升级全部实例」。

如果你之前遇到过「桌面一直重连中」，升级后请重新复现一次并重新导出诊断包 —— 这次日志里会直接写明卡在哪一段。

v1.4.8 — 修复微信「反复卡进度、永远装不完」+ 诊断包收录安装状态

本次修复

微信下载/安装：断点续传，装得完

此前网络半路被掐断时，下次触发会删掉下到一半的包从 0 重来，且多次点安装会互相踩，表现为反复卡在同一百分比后退出、永远装不完（用户实测卡 28%）。现在：

• 断点续传（curl -C -）：中断后从已下字节继续，而非重下
• 并发锁：已有安装在跑时，二次触发直接跳过，不再互相删包
• 完整性校验：dpkg-deb 读得出版本才算完整包，半包/损坏包自动清理并提示重下
• 安装日志：全过程写入 install.log（curl 退出码、已下字节、续传轮次）

导出诊断：装不上有据可查

「导出诊断」此前只有面板/容器日志，看不到安装为何失败。现在每个实例段追加：

• status.json：安装 phase / percent / 错误信息，一眼看出卡在哪一步
• install.log 尾 50 行：下载每一步的实况（v1.4.8 起的实例才有）

配合断点续传修复，形成「装不上 → 导诊断 → 定位根因」闭环。

---

镜像：ghcr.io/gloridust/{woc-panel,wechat-on-cloud}:1.4.8、gloridust/{woc-panel,wechat-on-cloud}:1.4.8（amd64 + arm64）。升级方式不变：面板「检查更新」一键升级。

v1.4.7 — 修复「永久卡在旧版本、更新无效」+ 受限网络误判

修复两个会让面板「更新了却没变化 / 实例永远停在老镜像」的问题，尤其影响国内 NAS 用户。建议升级。

🔴 修复：更新面板后仍是旧版本、反复更新无效（#107）

少数用户「一键更新面板」后，版本号仍停在很旧的值（如 v1.2.7），再点更新也没用。根因是自更新重建时错误地把旧容器里的版本号继承了下来，且会自我延续（每次更新都再次保留旧版本号），只能手动删容器才能逃出。已修复：版本号永远取新镜像自带的值。

已卡住的用户无需手删容器——升级到本版后，下次点「一键更新面板」即可自动恢复正常。

🟠 修复：受限网络下误判「镜像不存在」、实例卡在老镜像（#114）

国内 NAS 常见：docker pull 走加速镜像能拉到，但面板直连镜像仓库的校验请求不通。旧逻辑把「连不上」误当成「该版本不存在」，于是回退到本地可能几周前的旧镜像——表现为面板是新版、实例却一直连不上桌面/停在老镜像，还会显示误导性的「该版本可能未成功发布」。已修复：只有仓库明确回答不存在才回退；连不上时保持版本并交给 docker pull（走你的加速镜像）去拉，真拉不到才用本地镜像兜底并如实说明。

---

升级：设置 → 关于 →「一键更新面板」到 v1.4.7；随后「管理 → 一键升级全部实例」。
回滚：.env 设 WOC_VERSION=1.4.6（不带 v）后 docker compose up -d。

v1.4.6 — 升级后自动清理旧版本镜像（省磁盘）

很多用户反馈「历史镜像占满磁盘」。本版让面板在升级后自动清理不再使用的旧版本镜像。

修复

• 此前只清理「悬空镜像」（无 tag 的 <none>）。但自 v1.4.4 起面板拉取带版本号的镜像 tag（如 :1.4.5），升级到新版后旧版本镜像仍带 tag、不算悬空 → 每个历史版本（实例镜像约 4GB、面板约 0.5GB）长期堆积。
• 现在升级实例 / 一键升级 / 面板更新后，会自动删除不再被任何容器使用的旧版本 woc 镜像，只保留当前版本与正在使用（含未升级实例）的镜像。
• 安全：绝不删除正在运行或已停止实例所用的镜像；WOC_KEEP_OLD_IMAGES=1 可关闭（想保留旧镜像便于回滚）。

说明：本次清理逻辑在面板里，升级到 v1.4.6 后，之后的每次升级都会自动清理；面板启动约 30 秒后也会清一次历史堆积。

升级

设置 → 关于 →「一键更新面板」到 v1.4.6；随后到「管理」→「一键升级全部实例」。

v1.4.5 — 修复实例镜像版本号显示为 876361b9

v1.4.4 起，实例卡上的「镜像版本」角标会错误显示为 876361b9（那是底层 base 镜像的版本号），让人以为没升级成功、也分不清版本。本版修复。功能与 v1.4.4 相同。

修复

• 实例/面板镜像补回 org.opencontainers.image.version 标签（v1.4.4 改用原生构建时漏了），实例卡现在会正确显示 镜像 vX.Y.Z。

拿到修复（两步，都在面板里）

1. 设置 → 关于 →「一键更新面板」→ 确认版本 v1.4.5。
2. 管理 →「一键升级全部实例」→ 实例卡角标应显示 镜像 v1.4.5。

提示：请先更新面板、再升级实例（面板负责检测实例是否有新版）。

回滚：.env 设 WOC_VERSION=1.4.2（不带 v）后 docker compose up -d。

v1.4.4 — 实例镜像恢复正常发布（原生 arm64 构建）+ v1.4.3 全部改进

v1.4.1/v1.4.3 的实例镜像因 CI 的 arm64 构建（QEMU 模拟）内存溢出而未能发布。本版改用原生 arm64 构建彻底解决，实例镜像恢复正常发布。之前只更新了面板、实例升级不到新版的用户，现在可以正常升级了。

本版要点

• 实例镜像恢复发布（含 arm64）：CI 改用 GitHub 原生 arm64 runner 分架构构建，不再走 QEMU 模拟——根治此前反复的构建内存溢出。已验证多架构镜像（amd64 + arm64）正常发布到 GHCR 与 Docker Hub。
• 包含 v1.4.3 的全部改进（此前实例镜像没发出去，等于没生效）：
  • 公网/NAS 访问加固：登录限速（防爆破）、会话滑动续期（常挂着的面板不再频繁重登）、反代部署文档（nginx WebSocket + 空闲超时示例）。
  • 管理页三 Tab 重构（实例 / 用户 / 系统）+ 实例卡片布局修复（名字不再被截断、徽标不再竖排）。
  • 无障碍基线：键盘焦点环、尊重系统「减弱动态效果」。
  • 设计系统文档 doc/dev/design.md。

升级（两步，都在面板里）

1. 设置 → 关于 →「一键更新面板」→ 确认版本 v1.4.4。
2. 管理 →「一键升级全部实例」→ 实例卡角标应显示 镜像 v1.4.4。

回滚：.env 设 WOC_VERSION=1.4.2（不带 v）后 docker compose up -d。

v1.4.3 — 公网访问加固 + 管理页重构 + 设计系统文档

本版聚焦「体验 + 稳定性 + 公网安全」，无破坏性变更，建议升级。

🔒 公网 / NAS 访问加固

• 登录限速：面板常被直接暴露公网，此前登录接口无限速可被爆破。现加入限速（同源 15 分钟内失败 5 次即暂时锁定，返回 429 并记面板日志）。
• 会话滑动续期：常年挂着的面板不再因「固定到期」隔三差五要求重登——活跃会话自动续期，闲置超时才需重登。
• 反代文档：新增「公网访问 / 反代部署」章节（nginx 完整示例：WebSocket 升级头 + proxy_read_timeout 调大治「挂着不动就断线」+ 大文件上传；含 Caddy/frp/Cloudflare 注意事项）。

🎨 管理页重构 + 卡片布局修复

• 三 Tab 信息架构：管理页从「7 个区块一条长滚动」重组为 实例 / 用户 / 系统 三个 Tab（牛奶布艺分段选择器），Tab 上有红点提示待处理事项（可升级 / 有残留资源），记住上次停留位置。
• 实例卡片不再拥挤：标题行只保留「名字 + 状态」，可升级/镜像版本下沉到独立元数据行，长名字优雅省略不再被截断、徽标不再竖排。

♿ 无障碍基线

• 键盘焦点环（:focus-visible，仅键盘导航时出现）、尊重系统「减弱动态效果」。

📐 设计系统文档

• 新增 doc/dev/design.md：把牛奶布艺设计语言正式沉淀为可执行规范（令牌 / 组件 / 动效 / 无障碍 / 反例 / 落地清单），令牌与代码一一对应。

🛠️ 构建稳定性

• 实例镜像构建期精简 apt 源，根治 CI arm64（QEMU）下偶发的 apt OOM，让实例镜像更稳定地发布。

---

升级：面板「设置 → 关于」→「一键更新面板」；实例镜像如需更新，到「管理」→「一键升级全部实例」。
回滚：.env 设 WOC_VERSION=1.4.2（不带 v）后 docker compose up -d。

v1.4.2 — 修复 v1.4.1 实例镜像未发布（浏览器黑屏根治真正生效）

⚠️ v1.4.1 的实例镜像因 CI 构建失败未能发布，导致升级实例后浏览器仍黑屏、且升级指示器消失。本版修复该问题。v1.4.0/v1.4.1 用户请升级到 v1.4.2。

修复内容

① 实例镜像现在能正常构建发布（arm64）
v1.4.1 的实例镜像在 CI 的 arm64 构建阶段内存溢出（OOM）失败，导致只发布了面板、没发布实例镜像。已优化镜像构建流程消除该问题——本次已在原生 arm64 环境完整验证（Chromium 149 锚定、浏览器两次启动无崩溃、桌面窗口正常）。

② 面板不再因「找不到对应版本实例镜像」而卡死
版本耦合功能在实例镜像缺失时会让升级检测失效、升级拉不到。现增加安全兜底：对应版本不可用时自动回退到 latest，功能永不瘫痪。

升级步骤（两步，都在面板里）

1. 设置 → 关于 →「一键更新面板」→ 确认版本显示 v1.4.2。
2. 管理 →「一键升级全部实例」→ 升级后实例卡角标应显示 镜像 v1.4.2。

若升级后浏览器实例（Chromium）能正常打开网页、微信能打开公众号/附件，即修复成功。仍有问题请导出诊断包（管理 → 导出诊断）反馈。

回滚：.env 设 WOC_VERSION=1.4.0（不带 v）后 docker compose up -d。

v1.4.1 — 浏览器实例黑屏根治（Chromium 锚定）+ 声音重连 + 实例版本可见

接续 v1.4.0：v1.4.0 修好了微信（DPI），但浏览器（Chromium）实例仍会黑屏——本版根治，并修复声音、让实例镜像版本可见。建议所有用户升级。

🔴 浏览器实例黑屏根治：Chromium 版本锚定

根因：实例镜像的 Chromium 由 Debian 源提供、没有锁版本，每次 CI 构建都可能拉到更新的版本。近期 Debian 把 Chromium 升到 150，它在本容器环境下「非首次启动」必崩（SIGTRAP），表现为浏览器实例升级后先白屏再退出 / 一直占用需重启。

修复：从 snapshot.debian.org 固定快照锚定安装 Chromium 149（本容器栈上稳定的版本），不再跟随 Debian 滚动。并新增 CI 产物门禁：镜像推送前先在流水线上跑「DPI / 浏览器两次启动 / 崩溃循环 / 微信模式」四项探针，全过才发布——杜绝「本地验证 OK、线上却拉到坏版本」。

🔊 声音大概率放不出 → 已修

音频连接的内部标志在断线后未复位，导致重连（实例升级/重启/面板更新/网络抖动后）不再重新推流 → 全程静音。已修复：断线自动复位，重连即恢复出声。

🔎 实例镜像版本现在看得见了

• 每个实例卡显示**「镜像 vX.Y.Z」**角标——一眼确认实例到底跑的哪版，不用再猜「升级到底生效没有」。
• 升级失败不再假装成功：拉取新镜像失败时明确报错（原先会静默用本地旧镜像重建、还提示「完成」）。

🔗 面板与实例版本对应

正式版面板会拉取与自身相同版本的实例镜像（而非永远 latest），避免「低版本面板 × 高版本实例」的未验证组合。

---

升级步骤（两步，都在面板里）：

1. 设置 → 关于 →「一键更新面板」（完成后确认版本显示 v1.4.1）。
2. 管理 →「一键升级全部实例」（这一步才更新实例镜像；升级后看实例卡角标应变为 镜像 v1.4.1）。

回滚：把 .env 的 WOC_VERSION 设为上一版本号（不带 v，如 WOC_VERSION=1.4.0）后 docker compose up -d。

v1.4.0 — 修复微信/浏览器黑屏白屏（严重）+ 更新与稳定性大修

强烈建议所有 v1.2.9~v1.3.1 用户升级。 本版修复导致微信打不开公众号/附件、浏览器黑屏的总根因，并对更新与远程桌面稳定性做了系统性加固。

🔴 严重修复：微信公众号/附件秒关、浏览器黑屏

根因：早前版本的 xsettingsd 把 Xft/DPI 写成了 96，而 XSETTINGS 规范单位是「DPI×1024」（应为 98304）。这让所有 Chromium 内核应用（微信内嵌浏览器 CEF、系统 Chromium）把缩放算成 ≈0 → 显示变换矩阵不可逆 → GPU 进程崩溃 → 窗口秒关/黑屏。

表现：微信聊天正常，但点公众号/附件/小程序窗口一闪就关或白屏；Chromium 实例整体黑屏。amd64/arm64 均受影响。

✅ 如何拿到修复（两步，都在面板里，不用命令行）

⚠️ 关键：更新面板 ≠ 更新实例。 黑屏的修复在实例镜像里，只更新面板不会生效，必须做第②步。

1. 更新面板：设置 → 关于 →「一键更新面板」（约十几秒自动重启刷新）。
2. 升级实例（治病的一步）：管理 →「一键升级全部实例」（或对每个实例点「升级实例」）。

先①后②：先把面板更到 v1.4.0，实例升级就会走新版的异步流程（带进度、不会误报失败）。

🟠 更新机制大修

• 一键升级全部实例：检测落后实例并一键升级；改为后台异步 + 进度显示，不再「卡死」；先拉镜像再判定、镜像只拉一次。
• 远端新版检测：即便本地还没拉新镜像，也能提示「有新版可升级」（补上旧版「更新面板后检测不到实例可升级」的盲区）。
• 单实例升级异步化：不再因反代超时误报失败、避免重复点击导致并发重建。
• 面板自更新加固：拉取加停滞超时（不再无限卡死）、版本锚定、失败可重试。

🛡️ 稳定性加固（远程桌面 & 磁盘）

• 重启/自愈幂等：重启、卡死自愈、看门狗自愈绝不再隐式更换镜像版本——你没点升级，系统就不会给你换版。
• 磁盘防护：实例/面板容器日志封顶（20MB×2）、微信崩溃转储定期清理、升级后回收悬空镜像——根治「群晖磁盘被吃光」。
• 连接回收：面板↔实例双侧 TCP keepalive，及时清理断网/切网留下的半开死连接。

📐 开发规范（doc/dev/）

新增架构守则（R1~R10）、发布门禁清单、P0 复盘簿、稳定性设计文档，把历次事故的教训固化为硬约束。

---

升级面板：「设置 → 关于」点「一键更新面板」，或 docker compose pull && docker compose up -d。
回滚：把 .env 里的 WOC_VERSION 设为上一版本号（镜像 tag 不带 v，例如 WOC_VERSION=1.3.1），再 docker compose up -d；面板与实例镜像会一起回到该版本。留空/latest 为最新版。