升级

imgli 升级的核心原则：先备份数据目录（与数据库），再换二进制 / 镜像，再启动。库表由进程启动时迁移；一般不需要手工 SQL。

当前稳定发行 v0.9.17。自 v0.6 起，管理后台可 探测更新；二进制自托管可 一键升级（checksum 校验后替换可执行文件，需重启）。Docker 请改镜像 tag 后 compose pull && up -d，不要用一键二进制替换。

v0.7+：升级前后可在 系统 / 运维 运行健康检查（与 imgli doctor 同源），并查看运行时 base_url / 安装形态。

近期小版本提示（完整列表见 CHANGELOG）：

版本	运维注意
v0.9.17	HEIC/HEIF：官方 Docker 解 HEIC 后存 JPEG；纯 Go Release 二进制不解（`415 heic_unsupported`）。新默认组含 `heic`/`heif`，存量组不自动加。`/t?w=` 白名单变为 120/200/240/400/480/800/960/1600。无 schema 迁移。Release v0.9.17
v0.9.13	前端上传拖放：一次松开只入队一次；拖出页面清 overlay；投放区内移动不再闪高亮。无 schema / 存储迁移。Release v0.9.13
v0.9.12	私密相册强制图为 private（schema v8 + 启动时 surface 纠偏，首次启动可能有对象搬迁 I/O）；公开源站缓存 `{data_dir}/.serve-cache`（`IMGLI_SERVE_CACHE_DISABLED` 可关）；口令图不进广场；父相册私密时 `/s` 404。完整说明见 Release v0.9.12
v0.9.6	系统设置新增外观；暗色依赖新前端 bundle（部署后确认 SPA hash 刷新）
v0.9.4	回收站可恢复；原图 WebP 需 Docker/vips 镜像；纯 Go 二进制可能无 WebP encode
v0.9.0	用户组生命周期字段 AutoMigrate；游客组可能 Seed 默认有效期

升级前检查

阅读目标版本的 CHANGELOG 与 Release 说明。
确认当前 imgli version 与部署路径。
备份：
- SQLite：停服或热拷贝 data_dir 下数据库（及 -wal/-shm 若存在）+ 对象文件（本地盘或对象存储本身的备份策略）。仓库示例：deploy/ops/backup-sqlite.sh。
- Postgres：pg_dump + 对象存储备份。
计划回滚：保留旧二进制 / 旧镜像 tag。

仓库提供示例脚本：deploy/ops/backup-sqlite.sh（按你的路径改）。

二进制升级

curl -fsSL https://raw.githubusercontent.com/yixian-huang/imgli/main/scripts/install.sh | sh -s -- v0.9.17
imgli version   # 期望 v0.9.17

安装脚本会覆盖 PREFIX 下的 imgli 可执行文件；配置文件与 data 目录不会被脚本改动。

Docker / Compose 升级

docker pull ghcr.io/yixian-huang/imgli:v0.9.17
docker run --rm ghcr.io/yixian-huang/imgli:v0.9.17 version
# 或固定 compose 的 image: 后
docker compose pull && docker compose up -d

Compose：

# 在 compose 中改 image: ghcr.io/yixian-huang/imgli:vX.Y.Z
docker compose pull
docker compose up -d

不要删除 volume，否则丢库。

源码部署升级

git fetch --tags
git checkout v0.9.17   # 或 main
make build
# 替换运行中的二进制后重启服务

数据库与存储迁移命令

CLI 子命令（运维向）：

命令	用途
`imgli serve`	正常服务（含自动 migrate）
`imgli migrate`	仅跑库迁移（不启 HTTP）
`imgli storage-migrate`	跨策略对象搬迁（CLI；也可用 Admin 任务）
`imgli doctor`	自检 base_url / 数据目录 / 存储 / CDN 计量提示
管理后台系统 / 运维	v0.7+ 同源 doctor + runtime 摘要 + 清理/升级入口
`imgli upload` / `import-dir`	CLI 上传 / 目录导入
`imgli version`	打印构建版本

生产变更窗口建议：

imgli migrate -config /opt/imgli/imgli.yaml
# 确认无错误后再 systemctl start

回滚

systemctl stop / 停容器。
换回旧二进制或旧镜像 tag。
若新版本已写不可逆库变更：用升级前的 DB 备份恢复（先读 CHANGELOG；多数小版本向前兼容）。
启动 → /healthz → 抽样打开一张旧图与一张新上传。

升级后验收

imgli version 为目标版本（如 v0.9.17）
GET /healthz 200
浏览器打开首页：非白屏（校验 HTML 引用的 index-*.js 为新包）
imgli doctor 无 FAIL（WARN 按需处理）
登录后台 → 系统 / 运维：健康表与运行时摘要正常；浏览器源与 base_url 一致；HEIC 解码 在 Docker 上应为可用
登录后台，站点设置仍在；外观可打开
仪表盘可见运行版本；可探测更新
上传一张图，直链可打开；拖放同一文件只出现一条队列
（Docker）HEIC 上传成功且 links.url 为 .jpg 或 .webp，不是 .heic；纯 Go 二进制上传 HEIC 得到 heic_unsupported
私密相册内的图：广场不可见；匿名 /i 401；/s 404（v0.9.12）
数据目录出现 .serve-cache（若未设 IMGLI_SERVE_CACHE_DISABLED）
API Token / 设置页 三步接入 与客户端片段仍可用
（若用 S3/CDN）公开图 302 目标正确；私有图匿名不可下

相关：安装 · 配置 · 分享与外链 · CHANGELOG · Release v0.9.17

最后更新: 2026-08-27