feat: support custom instance icons and refresh release

This commit is contained in:
shiyue
2026-08-25 22:11:07 +08:00
parent bd20a79d4b
commit 05480e511d
20 changed files with 1104 additions and 23 deletions

View File

@@ -0,0 +1,33 @@
# 服务端设置与外置存储调研
## 架构与持久化
- `server.js` 使用 Node 原生 HTTP 与 `ws`,路由集中在 HTTP 回调和 WebSocket 消息 switch。
- `CONFIG_DIR = CC_WEB_CONFIG_DIR || APP_DIR/config`,现有运行配置均从该目录读写;测试会把它指向临时目录。
- 默认 `config/` 位于仓库内,但 `.gitignore` 对运行文件逐项忽略;实例图标必须新增精确规则,生产还可通过 `CC_WEB_CONFIG_DIR` 完全外置。
## 图片上传先例
- `POST /api/attachments` 已采用原始二进制 body,不使用 multipart;通过 Bearer token 鉴权。
- 既有逻辑包含大小上限、MIME 白名单、空内容拒绝、固定/清理后的文件名与读取鉴权。
- 实例图标上传可沿用“二进制 REST + 鉴权”,不应把大图片转 base64 塞入 WebSocket 配置消息。
## 静态响应与安全
- 现有静态资源响应使用 `no-store`,并检查解析后的路径仍位于 `PUBLIC_DIR`。
- 实例图标应只使用服务端固定文件名,写入临时文件后原子 rename;不接受客户端路径。
- 推荐只保存规范化 PNG,服务端检查 PNG 签名与 IHDR 尺寸,避免依赖声明 MIME。
## 推荐接口
- `GET /api/instance-icon/config`:返回是否自定义、版本、更新时间和图标 URL;不含敏感信息。
- `GET /api/instance-icon`:公开返回自定义 PNG;未配置时返回默认 `public/icon-192.png`。
- `POST /api/instance-icon`:Bearer 鉴权,接收固定尺寸 PNG,校验后原子写入。
- `DELETE /api/instance-icon`:Bearer 鉴权,恢复默认图标。
- `GET /api/site.webmanifest`:根据是否自定义返回默认或实例图标声明。
## 验证重点
- 默认回退、未鉴权写入、非法 MIME/签名/尺寸、超限、覆盖更新、恢复默认。
- 运行文件位于 `CONFIG_DIR`,不进入 `PUBLIC_DIR` 且被 Git 忽略。
- 自定义 URL 带内容版本,避免同页更新仍显示旧图。