# 服务端设置与外置存储调研

## 架构与持久化

- `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 带内容版本，避免同页更新仍显示旧图。