> ## Documentation Index
> Fetch the complete documentation index at: https://imageflowdoc.sakiko.de/llms.txt
> Use this file to discover all available pages before exploring further.

# 图片大小信息修复与迁移

> 修复早期版本图片列表 API 返回文件大小为 0B 的问题，并提供独立迁移工具及操作指南。

## 图片大小信息修复

### 问题描述

在 ImageFlow 的早期版本中，图片列表 API 返回的文件大小字段为 0B，导致前端显示不正确。

### 修复内容

1. 后端修复：修改 `handlers/list.go` 中的 `listImagesFromRedis` 函数，增加从文件系统读取实际文件大小的逻辑。
2. 独立迁移工具：在 `migrate-tool/` 目录提供可独立执行的二进制迁移工具，用于批量回填历史数据的文件大小。

## 使用方法

### 1. 重新构建应用

```bash theme={null}
go build -o imageflow
```

### 2. 构建并运行迁移工具

```bash theme={null}
# 进入迁移工具目录
cd migrate-tool/

# 构建所有平台的二进制文件
./build.sh

# 运行迁移（根据您的系统选择）
# Linux系统
./bin/run-linux.sh

# macOS系统  
./bin/run-macos.sh

# Windows系统
bin\\run-windows.bat
```

### 3. 重启 ImageFlow 服务

```bash theme={null}
# 如果使用 systemd
sudo systemctl restart imageflow

# 如果使用 Docker
docker-compose restart

# 如果直接运行
./imageflow
```

## 旧版本故障修复说明

以下说明适用于“图片列表 API 返回文件大小为 0B”的旧版本部署，帮助您在升级后正确修复历史数据并验证结果。

* 适用场景：
  * 管理界面或图片列表 API 中的 `size`/文件大小始终显示为 0B。
  * 历史图片的元数据中缺失或未填充文件大小信息。

* 修复路径：
  * 升级后端：先更新到包含“从文件系统读取文件大小”逻辑的后端版本并重新构建。
  * 迁移历史数据：按“使用方法”执行迁移工具以批量回填历史图片的文件大小。

* 推荐步骤：
  1. 可选：在业务低峰期暂停写入（上传/删除）以减少并发修改带来的不一致。
  2. 升级并重启后端服务（见上文“重新构建应用”“重启 ImageFlow 服务”）。
  3. 执行迁移工具，等待任务完成并检查输出日志是否存在失败项。
  4. 再次重启服务或刷新管理界面，验证最新数据已生效。

* 验证修复：
  * 通过前端管理页刷新列表，随机抽查图片的文件大小不应为 0B。
  * 可在服务器上对比文件系统实际大小（例如 `ls -lh`）与列表展示的大小。

* 注意事项：
  * 迁移前建议做好备份（Redis/元数据存储与图片目录）。
  * 迁移工具需要与生产环境一致的配置（例如 `.env`、`LOCAL_STORAGE_PATH` 或相同的存储访问参数），请在同一运行环境或容器内执行。
  * 如使用容器部署，请确保迁移容器挂载了与服务相同的数据卷与网络访问权限。

* 常见问题排查：
  * 迁移后仍为 0B：确认后端代码已包含读取文件大小的修复，清理前端缓存后重试。
  * 找不到文件/路径不匹配：检查 `LOCAL_STORAGE_PATH` 或存储配置是否与生产环境一致。
  * 迁移工具报连不上缓存/元数据存储：核对连接地址、凭据与网络可达性。