# FNA 静态配图副本

用户2026-10-30确认：Resource保留素材/图池/固定分配，FNA保存公开展示副本，由本站Nginx提供图片。仅猫狗资源栏目，教程图片沿原路径不改；不改变Resource的其他调用方。

## 数据与请求路径

- `public/images/illustrations/<sha256>.<ext>`：图片本体，按内容去重，同图多篇只存一份。运行数据不进入Git。
- `storage/app/private/illustrations/manifest.json`：资产元数据和pool→slug→asset映射，0600；只含已公开图片地址，不含消费者密钥。写入加锁并通过rename原子切换，读取不加写锁。
- `LOCAL_ILLUSTRATIONS_MIRROR_ENABLED=true`：启用本地展示；Resource原开关与精确环境基址仍用于接收/同步。
- 文章模型读取只读本地清单，请求内复用解析结果；不发Resource请求、不查图片数据库、不算文件hash，也不在用户访问时下载或补图。
- 浏览器请求固定哈希地址，Nginx直接返回文件，支持ETag/Last-Modified/304，缓存一年且immutable；规则见[静态配置](../deployment/illustrations-static.nginx)。staging还须在该location保留noindex头。不存在或格式不符的路径直接404，不能回落Laravel动态路由。

## 创建文章和同步

新文章接收仍先向Resource取得持久分配，然后下载副本；核对注册域名/公开media UUID、大小上限20MiB、SHA-256及真实图片格式/像素上限，最后原子发布文件/清单，成功后才返回本地URL交给文章保存。相同内容复用文件，重试沿用原配图；下载失败不写入无效清单或返回远程URL。

```sh
php artisan illustrations:sync-local
# 仅在确需为既有公开文章补建Resource分配、且持有write权限时：
php artisan illustrations:sync-local --assign-missing
```

命令强制读取Resource实时快照，不采用失败回退缓存；预存池内图片和固定选择，整批校验完成后切换清单，并清站点响应/点赞侧栏缓存。清单切换前失败保留旧清单，未被引用的完整文件可留待后续复用，不自动清理。同步不发布/修改文章正文，不影响点赞计划、URL或计数。不新增服务器cron/后台任务。

## 不满意、撤回与删除

要替换图片，先在Resource修改受影响文章的selection，再同步FNA并刷新页面缓存；新哈希URL自然换图。仅移出pool不改变旧selection，扩池也不洗牌旧文章。

Resource物理文件丢失时，已验证的FNA副本仍可继续展示；本地文件丢失时浏览器会404，运行同步可重新下载，访问请求不负责修复。主动撤回/取消授权等明确状态在同步后从页面映射停止展示。同步不自动删除任何共享副本；退役需先确认无文章/正文引用，再清理指定副本及相关CDN缓存。

长期公开缓存意味着不能承诺撤销Resource后立即让所有历史URL失效。FNA副本是独立公开发布物，需单独处理引用、源站文件及缓存；不要把Resource的即时撤回语义套到FNA静态副本。

## 部署与恢复

先备份代码、环境、Nginx及旧清单；基于当前正式提交构造仅本次文件的Git提交并推送，保留已上线点赞功能和并行生成模板。先test检出→同步→核对覆盖和哈希→启用开关/静态location→验收，再沿同一提交更新正式并执行相同迁移。test和正式各保存一份副本/清单，不共享私有凭据。

回退仅关闭LOCAL_ILLUSTRATIONS_MIRROR_ENABLED并清配置/响应缓存，恢复原Resource显示路径；保留副本及Resource引用，不删除资产或回灌整库。新接收文章原始sThumb可能已经是本地URL，回退时继续保留静态文件和location。不要通过直接删除图片测试生产修复。

## 2026-10-30 执行与验收

功能提交`ce27dbdd1eb206a9b7e7ac9b5a1c77778ed75e03`，基于最新正式`f315215f6f64cf1b200d67fc426a9071ff557a09`隔离构造并已推送`codex/static-illustrations-20261030`。保留已上线年度点赞及并行生成模板；没有复制本地旧Git历史或广告实现。

本地已启用，37张副本覆盖160篇；35项测试/277断言通过，涵盖下载校验、去重、失败原子性、并发分配、无网络读取，以及camelCase `sThumb`在模型/数组/JSON中的一致性。对外返回本站绝对URL，清单只存相对路径；侧栏缓存随同步清理。

test与正式均按同一功能提交部署。test 37张覆盖174篇，283项服务器检查通过，含关闭Resource客户端后的无缓存页面验证。正式37张覆盖176篇，246项服务器检查通过，正文/标题/slug/原始缩略图及年度点赞参数的部署前后摘要一致。最终HTTP、完整文件SHA、缓存/304/404、全量模型与数组同源图片、页面及真实接收helper既有分配重放结果见[本次发布回执](STATIC_ILLUSTRATIONS_RELEASE_2026-10-30.json)。未执行真实新文章接收、通知或IndexNow，未做线上页面验收。

VPS-003私有恢复点`/root/backups/cfn-static-illustrations-20261030/`保存原环境、Nginx、部署前身份摘要和逐项验收JSON。运行位置：正式`/www/wwwroot/clashfreenode-new.com`，test`/www/wwwroot/fna-v3-test`；两者独立目录和清单，静态location分别引入`/etc/nginx/snippets/fna-illustrations-production.conf`和`fna-illustrations-staging.conf`。新增目录由nginx写入，公开文件0644/目录0755，私有清单0600/目录0700。Source代码及其37张原文件保持原位；未新增定时同步或清理任务。