安装

支持：安装脚本、Docker 预构建镜像、Docker Compose、从源码构建。产物为 单二进制（前端 go:embed），默认 SQLite。

GitHub Release 二进制：纯 Go（无 CGO），便于通用安装。不能解码 HEIC（上传返回 415 heic_unsupported）。
官方 Docker 镜像（v0.9.4+）：默认带 libvips，支持 WebP 缩略图与（可选）原图转 WebP。v0.9.17+ 运行时另含 libheif / vips-heif，可解 HEIC/HEIF。
当前文档钉 v0.9.17。

系统要求

方式	要求
二进制 / Docker	无编译依赖；Linux amd64/arm64、macOS amd64/arm64；Windows 有 Release zip
源码构建	Go ≥ 1.26、Node ≥ 24、`make`

默认监听 :8686，数据目录默认 ./data（Docker 镜像内为 /data）。

1. 安装脚本（推荐自托管）

脚本从 GitHub Release 下载对应平台产物，默认装到 ~/.local/bin：

curl -fsSL https://raw.githubusercontent.com/yixian-huang/imgli/main/scripts/install.sh | sh

变量 / 参数	含义
`sh -s -- v0.9.17`	固定 tag（推荐生产钉死版本）
`PREFIX=/path` 或 `IMGLI_INSTALL_DIR`	安装目录
`IMGLI_REPO`	默认 `yixian-huang/imgli`（一般不用改）

验证：

imgli version
imgli doctor -config /path/to/imgli.yaml   # 可选：自检
imgli serve -config /path/to/imgli.yaml   # 可选配置文件

Windows：从 Releases 下载 Windows_*.zip，或在 Git Bash 下跑同一脚本。

2. Docker 预构建镜像

docker run -d --name imgli --restart unless-stopped \
  -p 8686:8686 \
  -v imgli-data:/data \
  -e IMGLI_BASE_URL=https://img.example.com \
  -e IMGLI_TRUST_PROXY=true \
  ghcr.io/yixian-huang/imgli:v0.9.17

健康检查：容器内对 http://127.0.0.1:8686/healthz 探测（镜像已带 HEALTHCHECK）。

3. Docker Compose

仓库根目录：

git clone https://github.com/yixian-huang/imgli && cd imgli
# 生产建议改 compose 使用固定 image tag，而不是本地 build
docker compose up -d

docker-compose.yml 默认挂载 imgli-data volume、暴露 8686。可按注释打开 Postgres 与 IMGLI_TRUST_PROXY。

4. 源码构建

git clone https://github.com/yixian-huang/imgli && cd imgli
make build          # 产出 ./imgli
./imgli version     # ldflags 注入的 git tag
./imgli serve

开发测试：

make test           # go vet + go test（可选 IMGLI_TEST_PG_DSN）
make test-web       # vitest
cd web && npm run e2e

5. systemd 示例（Linux）

# /etc/systemd/system/imgli.service
[Unit]
Description=imgli image host
After=network.target

[Service]
Type=simple
User=imgli
Group=imgli
WorkingDirectory=/opt/imgli
ExecStart=/usr/local/bin/imgli serve -config /opt/imgli/imgli.yaml
Restart=on-failure
RestartSec=3
# 若不用 yaml，可直接 Environment=
# Environment=IMGLI_BASE_URL=https://img.example.com
# Environment=IMGLI_DATA_DIR=/opt/imgli/data
# Environment=IMGLI_TRUST_PROXY=true

[Install]
WantedBy=multi-user.target

sudo useradd -r -s /usr/sbin/nologin imgli
sudo mkdir -p /opt/imgli/data
sudo chown -R imgli:imgli /opt/imgli
sudo systemctl daemon-reload
sudo systemctl enable --now imgli

6. 反代要点（Caddy / Nginx）

TLS 在反代终止。
IMGLI_BASE_URL 必须是用户浏览器看到的 https 公网源（与域名一致；否则登录/注册可能 403「跨站请求被拒绝」——常见于 1Panel 等面板反代后仍保留 localhost 或 IP 端口）。
反代把真实 IP 写入 X-Forwarded-For / X-Real-IP 后，再设 IMGLI_TRUST_PROXY=true。
v0.7+：管理员登录后台 → 系统 / 运维，查看 doctor 与「浏览器源 vs base_url」是否一致。
不要把 OCR / NSFW 旁路服务直接暴露到公网（见安全加固）。
排障见 FAQ · 仓库 security-hardening 反代 FAQ。

下一步

CLI 批量导入（v0.3）

安装 CLI 后可用 imgli import-dir <目录> 批量上传（环境变量 IMGLI_BASE_URL / IMGLI_TOKEN）。详见上传 API 与仓库 docs/integrations/README.md。