3.8 KiB
3.8 KiB
Star Office UI 更新文档（P0 / P1）
更新时间：2026-03-04
分支：feat/office-art-rebuild
1. 更新目标
本轮更新目标分为两层：
- P0：安全与可发布性（防泄漏、防弱配置、上线前可自检）
- P1：结构与稳定性优化（不减功能、提升状态同步与加载体验）
同时处理了线上关键问题：
- 服务偶发 502（进程/服务启动方式不稳定）
- 角色状态与真实工作状态不一致（尤其“回复结束仍在工位”）
2. P0 已完成项
2.1 后端安全基线加固
- 增加生产模式安全校验（弱密钥/弱口令阻止启动）
- Session Cookie 安全参数加固（HttpOnly / SameSite / Secure）
runtime-config.json写入后自动尝试收紧文件权限（600）
2.2 敏感文件治理
.gitignore补充运行态文件与高风险文件- 引入样例文件替代运行态文件：
join-keys.sample.json.env.example
join-keys.json改为运行时初始化，不再作为仓库内固定配置
2.3 上线前安全自检能力
- 新增
scripts/security_check.py - 可检查：
- 弱 secret / 弱口令
- 风险文件是否被 git 跟踪
- 常见敏感 token 模式
3. P1 已完成项（不改业务能力）
3.1 后端结构拆分
在不改变现有 API 行为前提下，把 backend/app.py 拆出：
backend/security_utils.pybackend/memo_utils.pybackend/store_utils.py
收益：
- 降低单文件复杂度
- 降低后续功能改动时的回归风险
- 提升可读性与维护效率
3.2 状态同步修复（核心）
- 修复状态源路径优先级（避免读取错误状态文件）
- 增加 stale 状态自动回
idle机制（避免假工作中） - 前端状态轮询改为更快节奏并强制视觉对齐，避免动画卡旧状态
3.3 生图模型策略收敛
按需求收敛为两种用户模型语义：
nanobanana-pronanobanana-2
并补充 provider 映射与错误细节透出，提升可诊断性。
3.4 首屏性能与体感优化
- 首页 HTML 缓存（后端进程内缓存）
- 非关键初始化延后（先出画面）
- 加入画布骨架屏，减少“黑屏 + 长时间加载中”体感
- 加速 loading overlay 淡出
4. 线上稳定性修复（本轮重点）
4.1 502 根因
Cloudflare 正常，但 18888 源站进程存在不稳定/启动方式不一致，导致偶发 connection refused。
4.2 已处理
- 修复并统一
star-office-ui.service启动方式（systemd 常驻） - 清理手工临时启动造成的端口抢占
- 重启并验证：
star-office-ui.service运行正常star-office-push.service运行正常
5. 当前已知风险 / 待跟进
-
状态策略仍需完全事件化
- 目前已大幅收敛误判，但建议后续做单一状态控制器（显式事件优先，彻底禁用隐式推断）
-
进程模型仍是 Flask 开发服务器
- 当前可用但不理想，后续建议迁移为 gunicorn/uvicorn 等生产进程模型
-
动画状态同步仍建议增加端到端回归脚本
- 尤其 writing / syncing / error / idle 切换链路
6. 验收建议（人工）
验收地址：https://simonoffice.hyacinth.im/
建议至少覆盖：
- 首页进入速度与骨架屏体验
- 状态切换（writing / syncing / error / idle）
- 回复结束后是否回到待命区
- 生图两入口（搬新家 / 找中介）
- 断网或服务短时波动后是否自动恢复
7. 提交范围（摘要）
本轮主要覆盖：
- 安全与配置：P0
- 后端重构：P1
- 状态同步与动画一致性修复
- 生图模型策略与错误诊断
- 加载性能与体验优化
- systemd 常驻与稳定性修复
如需 PR 附件，可直接将本文件作为“更新说明 / Release Notes”。