41 lines
2.1 KiB
Markdown
41 lines
2.1 KiB
Markdown
# 实例自定义图标需求
|
||
|
||
## 背景
|
||
|
||
用户在多台机器部署 cc-web。当前各实例使用相同图标，浏览器和 cc-web 界面中难以快速区分，需要每个实例可独立设置图标。
|
||
|
||
## 用户故事
|
||
|
||
作为 cc-web 管理者，我希望在设置页从本机选择实例图标，以便多实例并行使用时能直观看出当前机器；升级源码后，该选择仍应保留。
|
||
|
||
## 功能要求
|
||
|
||
1. 设置页新增实例图标设置项，展示当前图标。
|
||
2. 用户可选择受支持的本地图片并保存，保存成功后当前页面使用新图标。
|
||
3. 用户可恢复默认图标。
|
||
4. 未配置自定义图标的安装保持当前默认外观。
|
||
5. 自定义图标文件及选择状态存储在 Git 管理之外，`git pull` 不覆盖。
|
||
6. 服务端校验文件类型与大小，拒绝非法或超限输入并返回明确错误。
|
||
7. 图标更新后避免浏览器继续显示旧缓存。
|
||
|
||
## 非目标
|
||
|
||
- 不实现在线图标市场、URL 抓取、裁剪编辑器或多套图标历史。
|
||
- 不改变现有主题系统和品牌名称。
|
||
- 不自动修改操作系统桌面快捷方式或已安装 PWA 的原生图标。
|
||
|
||
## 验收标准
|
||
|
||
- 默认、上传、刷新后持久化、覆盖更新、恢复默认、非法类型和超限文件均有自动化覆盖。
|
||
- 侧栏/品牌入口与浏览器页签等现有运行时图标消费点按实际架构统一接入。
|
||
- 自定义图标数据未出现在 `git status` 的已跟踪/未跟踪源码改动中。
|
||
- 相关测试与构建通过，未破坏既有设置保存行为。
|
||
|
||
## 技术约束
|
||
|
||
- 浏览器接受 PNG/JPEG/WebP 选择，居中裁剪为 512×512 PNG 后上传；服务端最大接收 4 MiB。
|
||
- 自定义图片固定写入 `CC_WEB_CONFIG_DIR/instance-icon.png`（未设置环境变量时为 `config/instance-icon.png`），通过原子替换保存。
|
||
- 公开读取使用 `/api/instance-icon`；写入和恢复默认必须 Bearer 鉴权。
|
||
- 图标内容哈希作为版本，设置成功后更新 favicon、登录 Logo、通知图标和动态 Manifest。
|
||
- 默认行为继续使用现有源码图标；不保证操作系统对已安装 PWA 图标的即时刷新。
|