66 lines
9.8 KiB
Markdown
66 lines
9.8 KiB
Markdown
# 本地插画资源与配图
|
||
|
||
2026-10-27修正此前错误的本地配图实现。当前状态（2026-10-29）：本地、独立test与正式cfn均已接入；正式资源为https://resource-v2.gemcook.net，22猫/15狗，84/90篇固定分配与test逐项一致。正式消费者仅fna-v3项目read/write，test仍独立只读。部署、备份、权限与323项服务器验收统一见[正式切换](RELEASE_PREFLIGHT_2026-10-28.md#正式切换2026-10-29)。下文“仅本地/正式未切换”为此前历史状态。
|
||
|
||
素材及图池事实由 [Resource V2 插画集合说明](/Users/hellcat/Documents/GemCodes/resource.loc/v2/docs/CFN_ILLUSTRATIONS.md) 维护，本页维护FNA_V3消费方式。仅本地，未提交、推送或部署。此前“只用12张猫图替换显示”没有完成原图池扩充；旧哈希算法也没有避免连续重复，相关旧验收不足以证明需求已完成。
|
||
|
||
## 当前规则
|
||
|
||
免费节点当前22张猫图（含乔治此前2张猫图，已排除毛线球旧试画）；免费苹果ID（原免费小火箭ID，分类9、shadowrocketids）当前15张狗图。2026-10-28本批追加12张狗图，猫图去重保留。图池与每篇文章的固定分配都保存在本地Resource V2的项目引用中。首次按文章创建时间从旧到新通过HTTP批量分配；每次依次轮换一张图，一轮用完后再循环。重复发送同一文章键复用原图，不推进游标；之后扩充图池也不重新洗牌已有文章。
|
||
|
||
`config/illustrations.php`只维护分类1→freenode、分类9→shadowrocketids，以及V2基址和私有凭据文件路径，不保存图片URL清单。`app/Services/IllustrationPool.php`通过鉴权HTTP接口读取图池与分配；`app/Models/Articles.php`的sThumb读取器统一用于列表、侧栏、详情和OG。快照在file cache缓存60秒，最近成功快照另保留供短暂故障使用。没有成功快照时回退原字段；故障期间不创建新配图，不自动调用旧线上接口。
|
||
|
||
`ArticlesController`的免费节点、免费苹果ID接收方法，以及通用receive针对这两个分类，均在启用本地V2时走同一分配接口。调用失败中止配图阶段，不伪造成功。其他分类不变；非local或关闭开关时保留既有逻辑，未迁移生产调用方。
|
||
|
||
## 接口与凭据
|
||
|
||
环境绑定已扩展：local只接受`http://resource.loc:8612`，staging只接受`https://test.clashfreenode.com/resource-v2`，production只接受`https://resource-v2.gemcook.net`；均需显式启用且凭据project/base_url匹配。正式cfn已切换，其他同代码实例尚未自动迁移。开关RESOURCE_V2_ILLUSTRATIONS_ENABLED兼容旧LOCAL_ILLUSTRATIONS_ENABLED。FNA_V3专用客户端项目为fna-v3，作用域read/write；私有JSON由RESOURCE_V2_CREDENTIAL_FILE指定，位于resource/v2/.local/clients，不进入浏览器或Git。新图片导入用一次性所有者凭据，完成后已撤销。真实接口：
|
||
|
||
- GET `/api/v2/pools/{pool}`：取回有序成员和已分配文章。
|
||
- POST `/api/v2/pools/{pool}/selections`：JSON keys数组，首次分配/重复交付均幂等。
|
||
- 图片浏览器仍读取V2返回的 `/media/{publication}`，不带Bearer。
|
||
|
||
API契约、上限、项目隔离和图池维护见[Resource V2 API](/Users/hellcat/Documents/GemCodes/resource.loc/v2/docs/API.md)。新增素材先在V2上传、发布、授权消费者，再用pool引用扩充成员，不在FNA_V3写死图片地址。原160篇文章数据库sThumb未改写；本地原稿与生产旧文件均保留。未来上线另核对生产素材和服务配置，不能直接发布本地URL。
|
||
|
||
## 本地运行
|
||
|
||
固定入口 `http://fna-v3.loc/`；栏目为 `/freenode` 与 `/shadowrocketids`。本机 hosts 指向127.0.0.1，前端 Nginx 配置 `/usr/local/etc/nginx/servers/fna-v3.loc.conf` 仅监听回环80端口；转发至 GemCodesAccess 后端18882，PHP FPM9000，根目录为本项目 public。后端虚拟主机位于 GemCodesAccess 的 `service.conf`，由 `BEGIN/END FNA_V3 local virtual host` 标记界定。
|
||
|
||
Resource V2 开发服务监听127.0.0.1:8612。FNA_V3 使用 Vite dev，当前内部端口5187，启动命令 `npm run dev -- --port 5187 --host 127.0.0.1 --strictPort`；未执行发布构建。应用URL为固定域名，内部端口不替代日常入口。服务重启后按各项目运维说明恢复开发进程。
|
||
|
||
## 2026-10-27 旧版细节补齐
|
||
|
||
V2现会跳过缺失/损坏/符号链接/未发布等不可用候选；同一文章原图因物理故障不可用时，GET以unavailable标记，FNA_V3调用分配接口修复并保持其他文章分配不动。全池坏时该图留空，不用数据库旧URL伪装恢复。明确撤回发布/权限或资产停用则停止展示，不自动替换或重新公开。图池读取支持next游标，消费者读完所有页，60秒缓存/最近成功快照保留。
|
||
|
||
调用方本轮故障测试使用独立内存cache与fake HTTP，不污染真实缓存或文章；服务端真实HTTP测试使用一次性隔离实例，未触碰本地猫狗素材。完整接口和旧版对应关系以[Resource V2核对正文](/Users/hellcat/Documents/GemCodes/resource.loc/v2/docs/LEGACY_PARITY.md)为准。本地21猫/3狗、160篇文章配图保留，未上线。
|
||
|
||
## 验收与回退
|
||
|
||
2026-10-28用户明确不要早期试画 `freenode-cat-yarn-20261023`（粉底薄荷绿小猫玩毛线球）。通过本地V2 API移除消费者fna-v3的`pool:freenode:009`，并为fn20260808、fn20260903、fn20260925、fn20261016四篇替换固定配图，避开各自相邻文章；其他固定分配逐项对照未变。图池现场原有23项（含后续新增图），移除后22项。已刷新配图快照和页面缓存；源文件、私有归档与其他使用方未删除，生产未改。该图片不再纳入本地FNA_V3图池；不要根据历史导入清单重新加回。可恢复回执：`/private/tmp/fna-remove-yarn-receipt.json`。
|
||
|
||
2026-10-27：真实鉴权HTTP导入9张旧猫图、授权及创建图池、为78篇免费节点和82篇免费小火箭ID建立固定分配。160篇按当前栏目排序逐条检查：21张猫图/3张狗图均被使用，相邻配图重复为0。数据库原配图字段、其他7篇文章均未改变；重复投递、关闭开关、production保护、服务503保留最近配图与拒绝新分配均通过。
|
||
|
||
Resource V2隔离测试19项/154断言通过，包含轮换、项目隔离、只读凭据拒绝写、非法键、已撤回图片和失败保护。两栏目、两篇详情在1280/390宽度下图片加载、无相邻重复、无横向溢出；测试只放行本地来源。没有执行包含通知/索引外发的完整文章接收请求，接收方法的配图路径用相同服务方法真实HTTP重试验证。
|
||
|
||
证据位于 `/Users/hellcat/Documents/Codex/2026-10-23/cfn/outputs/fna-v3-pool-fix-verification.json`、`fna-v3-fixed-page-verification.json` 和 `fna-v3-fixed-*.png`。旧版截图和报告只作历史，不作为修正后验收。
|
||
|
||
回退展示：本地.env设置LOCAL_ILLUSTRATIONS_ENABLED=false，执行本项目 `php artisan config:clear` 与 `php artisan responsecache:clear`。原字段重新显示，不恢复整库、不删除resource引用/图池/素材。仅回退页面不撤销已被其他方使用的发布。代码备份和9张旧图SSH来源清单在工作目录work/illustration-fix；域名回退只移除独立server块及hosts条目，不覆盖其他聊天配置。
|
||
|
||
## 2026-10-28 两张插画追加
|
||
|
||
用户指定「蓝椅上的橘白猫」「窗台与蓝花」加入免费节点。原PNG及完整提示词已并入Resource V2原集合清单，WebP88展示图经真实本地HTTP上传、发布、授权并追加两个pool引用。FNA_V3实际IllustrationPool回读23张且包含两张新图，原78篇免费节点文章及其他消费者引用、游标均逐项保持不变；扩池供后续新文章轮换使用，不重分配旧文章。栏目本地HTTP200；未做本轮浏览器页面验收，未提交、推送或部署。
|
||
|
||
证据：`/Users/hellcat/Documents/Codex/2026-10-28/new-chat/outputs/fna-v3-two-cats-integration-20261028.json`；素材、备份与撤销凭据见Resource V2集合说明。本次没有修改FNA_V3代码或文章数据库字段。
|
||
|
||
## 栏目显示名称（2026-10-28）
|
||
|
||
用户要求将“免费小火箭ID”改为“免费苹果ID”。本地fna_v3.categories仅更新ID9的sName；sSlug仍为shadowrocketids，URL、文章归属、正文和狗图池不变。直接限定字段更新，未触发分类模型关联文章touch；清除global_nav_tree和页面响应缓存后，浏览器回读四个导航/栏目链接均为新名，列表卡片分类同步显示新名。原值备份 `codex/output/category-apple-id-rename-before-20261028.json`，截图 `codex/output/category-apple-id-rename-preview-20261028.png`。未发布生产；后续上线须将该栏目名作为定点数据变更处理，不以整库覆盖迁移。历史验收段中的旧名保留其原时点含义。
|
||
|
||
## 2026-10-28 本聊天剩余素材入池
|
||
|
||
用户指定猫→免费节点、狗→免费小火箭ID，并明确第一张截图排除整组三猫三狗，另三张截图分别排除早期光滑蓝椅猫、黄月黑猫、浅蓝背景坐猫；共9张排除，不导入且不删除原文件。剩余两张猫此前已入池，去重保留；新导入12张狗图（两组各5张，加闻雏菊史宾格、编号001叼拖鞋梗犬）。
|
||
|
||
Resource V2原图、完整提示词私有归档及WebP88公开展示/授权/池引用追加均通过真实本地HTTP完成。FNA_V3实际服务回读猫22/狗15，78+82篇原固定配图及游标逐项未变，新素材供后续文章轮换。先前明确移除的毛线球猫未恢复。两栏目本地HTTP200，未做本轮浏览器页面验收，未提交、推送或部署。
|
||
|
||
证据：`/Users/hellcat/Documents/Codex/2026-10-28/new-chat/outputs/fna-v3-remaining-art-integration-20261028.json`；每项排除hash、素材清单、备份与临时客户端撤销见资源集合正文及回执。本次未修改文章数据库字段或网站代码。
|