Agent image icon fails to load (404): AppIcon receives the raw file id instead of icon_url

快速结论：这个报错通常发生在自托管 Dify 开启 Agent v2（ENABLE_AGENT_V2=true）并给 Agent 使用上传图片作为图标后，页面渲染图标时拿到的不是后端签名预览地址而是原始 upload_files.id，因此浏览器请求该 UUID 路径返回 404。优先排查 Agent 相关的接口响应里是否有 icon_url、前端是否把 icon_url 传给了 AppIcon 的 imageUrl。

适用环境：Dify 1.16.1，Self Hosted（Docker）。Issue 未提供操作系统、Python、CUDA、显卡或依赖版本信息。

最快修复方案：暂无确认的一步修复方案。Issue 中给出的处理方向是：后端在 AgentRosterResponse 等模型上补 icon_url 计算字段（或在 serialize_agent() 中做 URL 转换），前端改用 agent.icon_url 渲染 imageUrl。

注意事项：该修复方向来自 Issue 讨论中的分析，未经原 Issue 明确标记为已验证。回退或修改前后端时需同时同步契约类型，避免生成类型与后端响应不一致；修改前建议先备份相关文件。

问题场景

在自托管 Dify 1.16.1 上启用 Agent v2 并创建 Agent，把 Agent 图标设为上传的图片（不是 emoji）。上传本身成功（POST /console/api/files/upload 返回 200 且 upload_files 表产生记录），但重新加载 Agents 列表页或 Agent 配置页后，图标不显示，开发者和 nginx 访问日志中可见对裸 UUID 路径的 404 请求。图标为 emoji 的 Agent 不受影响；Apps、datasets 和 webapp site icon 也不受影响，只有 type 为 image 的 Agent 图标有问题。

报错原文

Agent image icon fails to load (404): AppIcon receives the raw file id instead of icon_url

GET /29bdb007-4d8c-4888-83a2-7587abcafb26                                       404
GET /agents/019fd69e-7b20-79ee-8e15-b289e27928bc/29bdb007-4d8c-4888-83a2-7587abcafb26   404

原因分析

可能原因在前后端两侧的字段传递上：

后端 AgentRosterResponse 和 AgentInviteOptionResponse 模型不包含 icon_url 计算字段，而 AgentAppPartial、AgentAppDetailWithSite 是从 AppPartial/AppDetailWithSite 基类继承到 icon_url 的。
AgentRosterService 的 serialize_agent() 直接从数据库复制 agent.icon，未做 URL 转换，所以图片图标返回的是原始 upload_files.id UUID，而不是可用的预览 URL。
前端 AppIcon 直接把 imageUrl 用作 <img src>；agent-selector.tsx 和 agent-roster-field.tsx 把 agent.icon 传给了 imageUrl。由于 UUID 不是绝对路径，浏览器会相对于当前页面解析，于是在 /agents 和 /agents/<agent_id>/configure 上得到不同且都错误的 URL。
对比正确模式，其他地方的调用方传的是 app.icon_url。生产构建产物中同样的 imageUrl: X.icon 坏模式只出现在 Agent 相关 chunk 中，Agent 配置页头部组件可能还存在第三个调用点。

环境排查

确认 Dify 版本为 1.16.1，部署方式为 Self Hosted（Docker）。
确认 Agent v2 已开启：环境变量 ENABLE_AGENT_V2=true。
确认 Agent 图标类型为 image（上传图片）而非 emoji。
确认 upload_files 表中该文件记录存在，且 POST /console/api/files/upload 返回 200。
检查浏览器 DevTools 网络面板与 nginx 访问日志中是否出现对裸 UUID 路径的 404 请求。

解决步骤

先确认根因范围：检查 Agent 相关接口（如 AgentRosterResponse、AgentInviteOptionResponse）返回的字段中是否存在 icon_url。若只返回裸 icon id，即为本问题。
后端方向：为 AgentRosterResponse 增加 icon_url 计算字段，或在 serialize_agent() 中调用 build_icon_url() 做 URL 转换，使图片图标返回已签名的预览 URL（形如 /files/<id>/file-preview?timestamp=...&nonce=...&sign=...）。可参考 AgentAppPartial、AgentAppDetailWithSite 已有的 icon_url 行为。
前端方向：同步更新 TypeScript 契约类型，并把 agent-selector.tsx 与 agent-roster-field.tsx 中的 imageUrl={agent.icon ?? undefined} 改为 imageUrl={agent.icon_url}（以与 app/dataset/site 图标一致）。同时排查 Agent 配置页头部组件中可能存在的第三个调用点。
以上改动来自 Issue 讨论中的分析，可优先尝试，但尚未被标记为已验证的官方修复；如需自行修改，建议在测试环境验证后再上线。

验证方法

重新加载 Agents 列表页和 Agent 配置页，确认浏览器不再请求裸 upload_files.id 路径；网络面板中图片请求应为 /files/<id>/file-preview?... 形式并返回 200，Agent 图标正常渲染，不再出现 404 或破图占位符。emoji 图标的 Agent 应继续保持正常。