FAQ
FAQ
安装与运行
Q: 第一个用户为什么是管理员？
A: 空库引导：首个注册账号提升为管理员，便于单人快速开箱。公网请尽快收紧注册策略。
Q: 默认端口？
A: 8686。用 IMGLI_LISTEN 或 YAML listen 修改。
Q: 数据在哪？
A: 默认 ./data（Docker 多为 /data），含 SQLite 与本地对象。改 IMGLI_DATA_DIR。
Q: 必须 Postgres 吗？
A: 不必。默认 SQLite 即可；规模或运维习惯需要时再切 Postgres。
链接与反代
Q: 复制出来的链接域名不对？
A: 设置正确的 IMGLI_BASE_URL（用户浏览器访问的 https 源），重启服务。
Q: 限速 IP 全是反代地址？
A: 在可信反代后打开 IMGLI_TRUST_PROXY=true，并确保转发了客户端 IP 头。
Q: 反代（1Panel / Nginx / Caddy）后注册登录提示「跨站请求被拒绝」，IP:端口却正常？
A: 浏览器写请求会做 CSRF Origin 校验。TLS 在反代终止时，应用侧不能单靠 Host 当成 https 同源；若 IMGLI_BASE_URL 仍是默认 http://localhost:8686 或 http://IP:端口，而用户访问 https://域名，就会 403。
处理：设为用户浏览器地址的公网源并重启，例如 IMGLI_BASE_URL=https://你的域名，可信反代后同时 IMGLI_TRUST_PROXY=true。v0.7+ 管理员可在 系统 / 运维 直接看到 base_url 与浏览器源是否一致。详见 配置 · 安全加固；仓库 security-hardening.md。
上传与 API
Q: PicGo 一直 401？
A: 检查 Authorization: Bearer … 是否完整、Token 是否作废、是否复制了多余空格。先 curl 再配插件。
Q: 413 / 415？
A: 413 是用户组单文件大小上限。415 看 data.code：ext_not_allowed 是组策略不允许该后缀（存量组默认没有 heic/heif，要管理员加上）；heic_unsupported 是当前构建没有 HEIF 解码器（GitHub 纯 Go 包；请换官方 Docker 或 make build-vips）。
Q: iPhone 的 HEIC 传不上去？
A: v0.9.17 起，官方 Docker 会把 HEIC/HEIF 转成 JPEG（或站点开了原图 WebP 则为 WebP），直链不是 .heic。需要同时满足：（1）构建能解码（Docker / vips+libheif；纯 Go Release 会 heic_unsupported）；（2）用户组允许 heic 与/或 heif——升级不会改已有组名单，新装默认组已带上。imgli import-dir 会发送 .heic/.heif，解码仍在服务端。
Q: 429？
A: 触发限速；看 Retry-After，或调整用户组 / 换登录 Token。
Q: imgli doctor 是干什么的？
A: 自检 base_url、数据目录可写、数据库连通、本地存储策略，以及（若配置了 CDN）提醒管理端流量为源站可见而非边缘全量。生产升级后建议跑一次。v0.7+ 亦可在管理后台 系统 / 运维 查看同源报告（无需 SSH）。
Q: 管理后台「系统 / 运维」是什么？
A: v0.7+ 的运维入口：内嵌 doctor 健康表、运行时摘要（base_url / trust_proxy / 安装形态）、浏览器 vs base_url 错配提示、版本升级与生命周期清理、搬迁/备份文档链接。产品设置（SMTP、机审）仍在「系统设置」。
Q: 系统设置里的「外观」是什么？（v0.9.5）
A: 实例级强调色、整站背景图、遮罩与面板不透明度。公开配置经 /api/v1/config 下发。用户个人深浅色偏好仍可本地切换；不能替换鲤鱼 BrandMark。详见 站点外观。
存储与安全
Q: 上了 CDN 私有图还能被打开？
A: 立刻检查桶 ACL 与 CDN 源站是否匿名可读 private/*。跑 probe-private-object-anon.sh。应用 302 不会故意给 private 拼公开 CDN，但桶公开仍会出事。
Q: 管理后台流量为什么比 CDN 账单少？
A: 正常。仪表盘统计的是应用 /i 门禁命中；cdn_domain 302 后边缘缓存命中不会回源计数。看成本用 CDN/桶账单，看盗链线索用 Referer Top。
Q: 可以只开对象存储、关掉应用门禁直链吗？
A: 不推荐。门禁承担鉴权、私有检查、（可选）流量计量；CDN 应是门禁之后的卸流量层。
Q: Docker 把命名卷改成绑定挂载后 SQLite 报 out of memory？
A: 常见于低内存 ARM 主机。优先：改回命名卷 imgli-data:/data；确认挂载在本地盘而非 NFS；上传处理可设 VIPS_CONCURRENCY=1；需要时改用 Postgres。程序默认已关闭 SQLite mmap 以降低内存映射压力（新版本）。见 配置 · Docker 数据目录。
Q: 支持 FTP 吗？为什么读图很慢？
A: v0.4+ 支持 FTP 兼容驱动（非默认热存储）。优先用 OpenList/rclone 转 WebDAV 或同步到 local/S3。内置 FTP 无 S3 级 CDN/预签名；大图慢多半是 应用↔FTP 带宽（DevTools 若 TTFB 短、下载长即此）。见 FTP。
Q: 从 oneimg 等旧图床怎么迁？
A: 拷出 uploads 目录后 imgli import-dir（API Token）。不必先做专用 migrator。见 上传 API。
许可
Q: 公司内网自用要付费吗？
A: 遵守 AGPL 的自托管通常不强制商业许可；若法务要求非 AGPL 或做闭源 SaaS，见 商业授权。
Q: v0.1.0 是 MIT？现在呢？
A: 历史 tag v0.1.0 / v0.1.1 仍为 MIT。现行主干与 v0.2.0+ 默认 AGPL-3.0-only（可另询商业授权，见 商业授权）。
文档与产品
Q: 文档站和 GitHub 不一致？
A: 以 GitHub 最新 README / CHANGELOG / Release 为准；本站文档滚动同步（最近校对 2026-08-27，示例版本钉 v0.9.17）。
Q: 公共站额度在哪看？
A: 登录 img.li 后于个人中心 / 配额展示（以线上 UI 为准）。
分享 · SSO · 集成（v0.3）
Q: 链接贴到聊天里没有预览图？
A: 使用 分享页 /s/{key} 或公开相册 /a/{id}（不是裸 /i/）。确认 IMGLI_BASE_URL 正确；口令图故意不给 OG 图。见 分享与外链。
Q: 如何用公司账号登录？
A: 配置 OIDC，在 IdP 登记回调 {BASE_URL}/api/v1/auth/oidc/callback。
Q: 如何批量迁入本地相册？
A: imgli import-dir ./photos（需 IMGLI_BASE_URL + Token）。见 上传 API。
Q: 上传后如何通知外部系统？
A: 配置 Webhook 订阅 image.uploaded / image.moderated。
最后更新: 2026-08-27