Star-Office-UI 2026-03-05 更新深度解读：CDN 缓存 404、异步生图防 524 超时与移动端侧边栏的稳定性修复实践

前端后端AI 应用数据可视化【免费下载链接】Star-Office-UIA pixel office for your OpenClaw: turn invisible work states into a cozy little space with characters, daily notes, and guest agents. Code under MIT; art assets for non-commercial learning only.项目地址https://gitcode.com/gh_mirrors/st/Star-Office-UI点击查看免费下载本篇技术指南围绕 Star-Office-UI 2026-03-05 的 8 个 commit 展开核心聚焦「稳定性修复 移动端体验 安全收尾」三大主题如何修复 CDN 缓存 404 导致整站无法加载的故障、如何通过后台线程 前端轮询规避 Cloudflare 524 生图超时、如何用遮罩层 100dvh解决移动端抽屉侧边栏滚动穿透以及如何为 join key 增加过期时间与并发上限。读完本文你将掌握这套像素风办公室项目由 Flask 后端 backend/app.py 与单页前端 frontend/index.html 构成在生产环境中的缓存策略、异步任务模式、移动端滚动锁定与接入密钥治理的完整实现方案。变更概览一次「小而全」的稳定性收尾本次更新共覆盖 8 个 commit可以归类为三组#Commit分类说明1878793d fix修复 CDN 缓存 404 导致页面无法加载2cc22403 fix修复fetchStatus()中多余的else块导致 JS 语法错误3103f944 fix生图接口改为异步任务模式避免 Cloudflare 524 超时4ee141de chore清理本地测试时意外提交的文件583e61ff chore将join-keys.json加入.gitignore运行时数据不入库6899f27e fix移动端/iPad 侧边栏修复遮罩层 body 滚动锁定 100dvh75aef430 fix移动端 drawer 关闭时完全移出屏幕right: -100vw802a731e✨ feat新增 join key 级别过期时间 并发上限支持下文逐条拆解实现细节并给出当前仓库源码中的可验证证据。1. 修复 CDN 缓存 404一个缓存头策略引发的「整站宕机」问题根因Flask 后端对/static/路径下的所有响应包括 404都设置了一年长缓存头。Cloudflare 于是把phaser.js的 404 响应也缓存了长达 2.7 天导致office.hyacinth.im的 HTML 能加载、静态资源却全部 404页面完全无法启动。修复方案缓存策略改为「按响应状态码区分」在 backend/app.py 中add_no_cache_headers作为全局app.after_request钩子现在按路径与状态码双重判断app.after_request def add_no_cache_headers(response): Apply cache policy by path: - HTML/API/state: no-cache (always fresh) - /static assets (2xx only): long cache (filenames are versioned with ?vVERSION_TIMESTAMP) - /static assets (non-2xx, e.g. 404): no-cache to prevent CDN from caching errors path (request.path or ) if path.startswith(/static/) and 200 response.status_code 300: response.headers[Cache-Control] public, max-age31536000, immutable response.headers.pop(Pragma, None) response.headers.pop(Expires, None) else: response.headers[Cache-Control] no-cache, no-store, must-revalidate, max-age0 response.headers[Pragma] no-cache response.headers[Expires] 0 return response关键改动点只有 2xx 响应才允许一年长缓存max-age31536000, immutable非 2xx尤其是 404/500一律no-cache, no-store, must-revalidate从源头杜绝 CDN 缓存错误页同时清掉Pragma/Expires遗留头避免与Cache-Control语义冲突HTML、API、状态类接口始终走 no-cache保证每次刷新都能拿到最新数据。静态资源加版本化查询参数仅靠缓存头还不够——文件名不变的前提下CDN 仍可能命中旧缓存。修复同时在服务端生成了一个进程级的版本时间戳# Generate a version timestamp once at server startup for cache busting VERSION_TIMESTAMP datetime.now().strftime(%Y%m%d_%H%M%S)对应实现位于 backend/app.py服务启动时生成一次。随后在返回 HTML 时把模板占位符替换为真实时间戳见 backend/app.py_INDEX_HTML_CACHE raw_html.replace({{VERSION_TIMESTAMP}}, VERSION_TIMESTAMP)而 frontend/index.html 中对phaser.js等静态脚本的引用均携带?v{{VERSION_TIMESTAMP}}。这样每次部署服务重启后时间戳变化CDN 就会重新回源拉取新资源实现了「长缓存 部署即失效」的组合效果。运维要点此方案要求每次发布都重启服务或至少保证VERSION_TIMESTAMP更新。这也是为什么项目把静态资源长期缓存与版本化参数配套使用——两者缺一都可能复现本次的 CDN 404 事故。2. 修复fetchStatus()语法错误一个孤立的else块卡死整个页面问题根因frontend/index.html 的fetchStatus()是前端轮询/status的核心函数其内部try/catch之间残留了一个孤立的} else { ... }块破坏了 JS 语法结构。浏览器解析时报Missing catch or finally after try脚本整体失效页面永远卡在 loading。修复方案移除多余的else块——其中的打字机逻辑已被前面的if/else分支完整覆盖。修复后的函数结构源码证据为function fetchStatus() { return fetch(/status, { cache: no-store }) .then(response response.json()) .then(data { try { if (data.officeName) { window.officeNameFromServer data.officeName; ... } const nextState normalizeState(data.state); const stateInfo STATES[nextState] || STATES.idle; const changed (pendingDesiredState null) (nextState ! currentState); ... if (changed) { typewriterTarget nextLine; typewriterText ; typewriterIndex 0; } else { if (!typewriterTarget || typewriterTarget ! nextLine) { typewriterTarget nextLine; typewriterText ; typewriterIndex 0; } } } catch (err) { console.error(fetchStatus apply error, err); typewriterTarget 状态更新异常正在恢复...; typewriterText ; typewriterIndex 0; } }); }修复后try块内部是「如果状态变化则重置打字机、否则仅在文本不同时重置」的完整分支catch兜底恢复提示结构自洽。值得注意的是这份更新报告明确标注此 bug 是 GitHub 上 PR #49、#51、#52 同时在修的问题本次修复后三个 PR 均可以关闭。这也提醒我们单页应用的「整页卡 loading」类故障优先级最高的排查项是浏览器控制台里的 JS 语法错误语法级 bug 往往比逻辑 bug 更容易被快速定位。3. 生图接口异步化后台线程 前端轮询绕开 Cloudflare 524问题根因原POST /assets/generate-rpg-background是同步接口生图通常耗时 30~120 秒而 Cloudflare 的代理超时限制为 100 秒。公网用户一旦生图超过 100 秒就会触发 HTTP 524 超时请求被断开但后端可能仍在继续生成前端也无法得知结果。后端改动拆分为「提交任务 轮询结果」源码证据位于 backend/app.py 的异步任务注册表# Async background task registry for long-running operations (e.g. image generation) # Avoids Cloudflare 524 timeout (100s limit) by letting frontend poll for completion. _bg_tasks {} # task_id - {status: pending|done|error, result: ..., error: ..., created_at: ...} _bg_tasks_lock threading.Lock()任务提交POST /assets/generate-rpg-background见 backend/app.py核心流程校验资产编辑器权限_require_asset_editor_auth检查生图脚本环境GEMINI_PYTHON/GEMINI_SCRIPT是否存在缺失则直接返回 500 提示「gemini-image-generate 未安装」防重入在锁内扫描_bg_tasks若已有status pending的任务直接返回已有task_id提示「已有生图任务进行中请等待完成」生成唯一task_idgen_ 毫秒时间戳 4 位随机小写字母数字登记为pending启动守护线程执行_bg_generate_worker立即返回{ok, async, task_id}。任务 ID 生成方式task_id gen_ str(int(datetime.now().timestamp() * 1000)) _ .join(random.choices(_string.ascii_lowercase _string.digits, k4))后台 worker_bg_generate_worker见 backend/app.py。worker 在后台线程中完成真正的生图逻辑调用 Gemini 生成底图、产出office_bg_small.webp、把历史版本快照备份到assets/bg-history/目录然后在锁内把任务标记为done并写入结果含path。异常分支会把任务标记为error并将常见错误归类为MISSING_API_KEY/MODEL_NOT_AVAILABLE等可识别 code附带detail供前端精确提示。结果轮询GET /assets/generate-rpg-background/poll见 backend/app.pystatus pending返回「生图进行中...」前端继续轮询status done返回结果并在锁内_bg_tasks.pop(task_id, None)立即清理任务status error同样 pop 清理并根据是否携带code决定返回 400 还是 500。「poll 消费即清理」正是本次风险评估中「异步任务内存泄漏风险为低」的底气所在。前端改动_startAndPollGeneration()统一轮询见 frontend/index.htmlasync function _startAndPollGeneration(body, out, progressMsg) { const res await fetch(/assets/generate-rpg-background, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(body), }); ... // 每 3 秒轮询一次 while (true) { await sleep(3000); const poll await fetch(/assets/generate-rpg-background/poll?task_id taskId, ...); if (poll.status done) { ... return result; } if (poll.status error) { ... return {ok:false, ...}; } } return { ok: false, msg: 生图超时超过5分钟请重试 }; }要点提交任务后每 3 秒轮询一次实时更新等待进度文案超时上限 5 分钟超过则提示重试同时抽取了统一的_handleGenError()见 frontend/index.html 附近做错误处理按MISSING_API_KEY、MODEL_NOT_AVAILABLE等 code 给出针对性提示属于典型的 DRY 优化。「搬家」moveRoom与「中介方案生图」broker 生图两条业务路径均已切换到该异步模式调用示例见 frontend/index.html。4-5. 清理与 gitignore运行时密钥数据不入库ee141de清理了本地测试时意外提交的文件83e61ff将join-keys.json加入.gitignore。join-keys.json是项目的运行时接入密钥库包含每个 key 的明文与使用状态见示例 join-keys.sample.json属于典型的「敏感但非配置」数据——一旦入库任何 clone 仓库的人都能拿到密钥。将其加入.gitignore后仓库只保留.sample模板实际密钥在服务器本地维护。该改动对应的风险评估在报告中单独列为「 已解决」但仍强调如果历史上曾有 commit 包含join-keys.jsonGit 历史中依然存在该文件需要确认远端历史是否干净必要时需改写历史。6-7. 移动端/iPad 侧边栏修复遮罩层 滚动锁定 100dvh问题根因在移动端/iPad 上打开资产侧边栏drawer时背后的页面仍可滚动滚动穿透关闭后 drawer 只偏移-320px在视口宽度更大的移动设备上仍能看到抽屉露出体验割裂。修复方案遮罩层 点击关闭新增#asset-drawer-backdrop遮罩层见 frontend/index.html固定覆盖全屏inset: 0半透明黑背景点击即调用toggleAssetDrawer(false)关闭#asset-drawer-backdrop { position: fixed; inset: 0; background: rgba(0, 0, 0, 0.5); display: none; -webkit-tap-highlight-color: transparent; } #asset-drawer-backdrop.open { display: block; }对应 DOM 结构位于 frontend/index.html。body 滚动锁定与滚动位置恢复打开 drawer 时给body加drawer-openclass配合overflow:hidden; position:fixed锁定背景滚动关闭时恢复scrollY避免页面跳回顶部。JS 实现见 frontend/index.htmlasync function toggleAssetDrawer(force) { const drawer document.getElementById(asset-drawer); const backdrop document.getElementById(asset-drawer-backdrop); const next (typeof force boolean) ? force : !assetDrawerOpen; assetDrawerOpen next; drawer.classList.toggle(open, next); if (next) { _drawerScrollY window.scrollY; document.body.style.top -${_drawerScrollY}px; } document.body.classList.toggle(drawer-open, next); if (!next) { document.body.style.top ; window.scrollTo(0, _drawerScrollY); } ... }移动端媒体查询内的锁定样式见 frontend/index.htmlbody.drawer-open { overflow: hidden !important; position: fixed; width: 100%; ... }完全移出视口 100dvh 滚动穿透抑制关闭状态改为right: -100vw无论设备视口多宽抽屉都能完全移出屏幕从根本上解决「-320px 偏移在宽屏设备上仍可见」的问题高度改用100dvh适配移动端动态视口iOS Safari 地址栏收起/展开时视口高度变化桌面端保留100vh作为兜底见 frontend/index.html 的height: 100vh; height: 100dvh;双声明写法overscroll-behavior: contain阻止抽屉内部滚动穿透到背景页面见 frontend/index.html 及抽屉 body 的 L1094-L1098同时配合#main-stage的视口动态左移body.drawer-open #main-stage规则见 frontend/index.html确保抽屉与主舞台之间至少保留 20px 间隔。8. 新功能Join Key 级别过期时间 并发上限这是本次更新中唯一的 feature 类改动目标是让「邀请 guest agent 参与活动」具备更强的治理能力。数据结构expiresAtmaxConcurrent在 join-keys.sample.json 中可以看到 key 的完整字段{ keys: [ { key: ocj_example_team_01, used: false, reusable: true, maxConcurrent: 3, usedBy: null, usedByAgentId: null, usedAt: null } ] }本次更新为每个 key 新增两个可选字段字段类型含义默认值expiresAtstringISO 8601 时间戳该 key 的绝对过期时间过期后拒绝一切接入不设置则永不过期maxConcurrentint同一个 key 同时在线approved 且在 5 分钟内有心跳的 agent 数上限3源码中的默认值过期检查join-agent与agent-push双端点两个端点在执行前都会读取key_item.get(expiresAt)并与当前时间比对过期则返回 403 与友好提示key_expires_at_str key_item.get(expiresAt) if key_expires_at_str: try: key_expires_at datetime.fromisoformat(key_expires_at_str) if datetime.now() key_expires_at: return jsonify({ok: False, msg: 该接入密钥已过期活动已结束 }), 403 except Exception: pass接入端点join_agent见 backend/app.py状态推送端点agent_push见 backend/app.py。并发上限锁内二次读取 在线判定并发控制的关键设计见 backend/app.pyjoin_lock全局互斥锁 锁内重新读取避免多个并发请求基于同一旧快照同时通过校验check-then-act 竞态在线判定基于 5 分钟窗口lastPushAt/updated_at距今超过 300 秒的 agent 被标记为offline不占用并发额度_age_seconds辅助函数实现同类 agent 去重同一name已存在时只更新记录不重复计数超过上限返回429该接入密钥当前并发已达上限{max_concurrent}请稍后或换另一个 key。max_concurrent int(key_item.get(maxConcurrent, 3)) ... if active_count max_concurrent: save_agents_state(agents) return jsonify({ok: False, msg: f该接入密钥当前并发已达上限{max_concurrent}请稍后或换另一个 key}), 429配套说明agent_push端点允许offline过期的在线状态而非撤销的授权状态的 agent 恢复推送并自动升级回approved见 backend/app.py这保证了「guest agent 短暂离线后重连」不会被误拒。密钥文件的加载与保存join-keys.json的读写统一走 backend/store_utils.py 中的 JSON 加载/保存工具UTF-8 indent2持久化密钥文件的路径常量JOIN_KEYS_FILE定义于 backend/app.py。潜在风险评估与结论原报告对四个风险点做了明确评级这里结合源码逐一给出可验证结论风险点等级说明与源码依据异步任务内存泄漏 低_bg_tasks在任务完成并被 poll 消费后即pop清理见 backend/app.py若前端从不 poll如用户中途关页任务对象会残留。当前生图频率低、风险极低后续可考虑加定期清理。join-keys.json历史泄露 已解决已加入.gitignore但若历史 commit 曾包含该文件Git 历史中仍存在建议确认远端历史是否干净。前端fetchStatus修复 已验证修复后的try/catch结构完整见 frontend/index.html本地运行正常。移动端 drawerposition:fixed 低iOS Safari 下position:fixed100dvh组合偶有兼容问题但已是业界最佳实践双声明100vh; 100dvh做了降级兜底。结论无新增 bug 风险可以安全推送。文件变更统计.gitignore | 1 backend/app.py | 166 ------ frontend/index.html | 162 -------- frontend/join-office-skill.md | 102 ------ frontend/office-agent-push.py | 286 office-agent-push.py | 2 - 共 6 个文件589 行-130 行变更分布符合本次主题改动高度集中在后端 API 层backend/app.py的缓存头、异步任务、join key 校验与前端单页frontend/index.html的移动端 drawer、轮询逻辑、fetchStatusfrontend/office-agent-push.py与根目录 office-agent-push.py 的变动则与 join key 过期/并发特性的对接有关。给维护者的实践清单结合本次更新的全部经验可以沉淀出四条可直接复用的运维/开发规则CDN 场景下缓存头必须按状态码区分永远不要对 404/5xx 设置长缓存静态资源务必配合版本化参数如?v{{VERSION_TIMESTAMP}}否则「长缓存」会成为故障放大器长耗时接口一律异步化凡是可能超过网关超时本例为 Cloudflare 100 秒的操作都应以「提交任务 task_id 轮询」模式实现并在消费后清理任务对象防止内存泄漏移动端抽屉/侧边栏的标准三件套遮罩层点击关闭、body滚动锁定记录并恢复scrollY、right: -100vw100dvhoverscroll-behavior: contain接入密钥要具备生命周期expiresAt让活动密钥自动失效maxConcurrent防止单一密钥被并发滥用涉及计数校验的临界区务必加锁并在锁内重新读取数据。赞分享前端后端AI 应用数据可视化【免费下载链接】Star-Office-UIA pixel office for your OpenClaw: turn invisible work states into a cozy little space with characters, daily notes, and guest agents. Code under MIT; art assets for non-commercial learning only.项目地址https://gitcode.com/gh_mirrors/st/Star-Office-UI点击查看免费下载相关推荐Star Office UI 2026-03-04 P0/P1 更新全解析安全加固、状态同步修复与 systemd 稳定性治理Star Office UI 2026 03 04 P0/P1 更新全解析安全加固、状态同步修复与 systemd 稳定性治理 本篇技术指南以 Star Of前端后端AI 应用数据可视化Star-Office-UI 2026-03 更新解读端口治理、资产编辑工作流、同步动画修复与生产安全收尾Star Office UI 2026 03 更新解读端口治理、资产编辑工作流、同步动画修复与生产安全收尾 本文以 Star Office UI 仓库 doc前端后端AI 应用数据可视化vue-vben-admin 修复侧边栏移动端 Hover 状态污染vben-core/layout-ui 补丁深度解析vue vben admin 修复侧边栏移动端 Hover 状态污染 vben core/layout ui 补丁深度解析 导读 本文基于 vue vben前端上一篇Yuxi-Know技术选型分析为什么选择LangGraph和LightRAG下一篇Open-AutoGLM终极指南如何用AI自动化完成日常手机操作创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考