HOTFIX_DOCKER_BUILD.md

🔧 紧急修复：Docker 构建失败

🐛 问题描述

Hugging Face Space 构建失败：

ERROR: failed to calculate checksum of ref: "/generated_images": not found

🔍 问题原因

1. Dockerfile 尝试复制 generated_images/ 目录
2. 但该目录在 GitHub 仓库中被 .github/workflows/sync.yml 删除了
3. Docker 构建时找不到该目录，导致失败

✅ 已修复

1. 简化 Dockerfile

文件：Dockerfile

修改前：

COPY generated_images/ ./generated_images/

修改后：

# 只创建空目录，不复制文件
RUN mkdir -p generated_images logs

2. 修改默认配置

文件：app/user_config.py 和 app/storage.py

修改前：

"image_url": "generated_images/default_character.jpeg",

修改后：

"image_url": "",  # 空字符串，前端会显示占位符

原因：

• 不依赖 Git 仓库中的图片文件
• 用户首次使用时可以生成自己的 AI 形象
• 或者前端显示一个默认占位符

🚀 部署步骤

1. 提交修复

git add Dockerfile app/user_config.py app/storage.py
git commit -m "Fix: Remove dependency on generated_images directory in Docker build"
git push origin main

2. 同步到 Hugging Face

1. 访问：https://huggingface.co/spaces/kernel14/Nora
2. Settings → Sync from GitHub → Sync now

3. 等待重新构建

• 查看 Logs 标签页
• 应该能看到构建成功

✅ 验证修复

构建成功后，访问：

https://kernel14-nora.hf.space/

应该能看到：

• ✅ 前端正常加载
• ✅ AI 形象位置显示占位符（或默认图标）
• ✅ 可以点击 ✨ 按钮生成自定义形象
• ✅ 所有功能正常工作

📝 技术说明

为什么不在 Docker 镜像中包含默认图片？

1. Git 仓库限制：

   • 图片文件较大（几百 KB）
   • 会增加仓库体积
   • 被 .github/workflows/sync.yml 清理

2. 更好的方案：

   • 用户首次使用时生成个性化形象
   • 或者使用 CDN 托管的默认图片
   • 或者前端显示 SVG 占位符

3. 运行时生成：

   • 用户可以随时生成新形象
   • 图片保存在容器的 generated_images/ 目录
   • 重启容器后会丢失（可以接受）

未来改进方向

1. 使用对象存储：

   • 将生成的图片上传到 S3/OSS
   • 持久化存储，不会丢失
   • 支持多实例共享

2. 内嵌默认图片：

   • 将默认图片转为 Base64
   • 直接写在代码中
   • 或者使用 SVG 矢量图

3. CDN 托管：

   • 将默认图片放在 CDN
   • 配置 URL 指向 CDN
   • 加载更快

🎉 修复完成

修复后，Docker 构建应该能成功，Space 可以正常运行。

---

修复时间：2026-01-18 影响范围：Hugging Face Space Docker 构建 严重程度：高（导致构建失败） 修复状态：✅ 已完成