配置（运维层）

本文只讲 进程怎么跑（监听、数据目录、数据库、反代）。
站点名、注册、存储策略、SMTP、外观等业务项在 管理后台，不在这里。

要不要写配置文件？

多数人 只用环境变量 即可（Docker Compose / systemd Environment=）。

方式	何时用
环境变量 `IMGLI_*`	Docker / 面板部署；优先
YAML（`imgli serve -config …`）	二进制裸机、想把多项写在一个文件里

优先级： 默认值 → YAML → 环境变量（环境变量覆盖 YAML）。

上线时通常只改 1～2 项

场景	必改
本机试玩 `localhost:8686`	不用改（默认即可）
域名 + HTTPS 反代	`IMGLI_BASE_URL` = 浏览器里的 `https://你的域名`；并设 `IMGLI_TRUST_PROXY=true`
自定义数据盘	`IMGLI_DATA_DIR`（Docker 镜像内默认已是 `/data`，配合卷挂载即可）

其它变量都有合理默认值，不是每个都要填。

环境变量说明

变量	是否必需	默认	说明
`IMGLI_BASE_URL`	公网部署必需	`http://localhost:8686`	用户浏览器打开的站点地址（含 `https://`）。用于生成外链、邮件链接、Cookie、登录注册的 CSRF 校验。填错时反代后常出现「跨站请求被拒绝」；本机试玩可保持默认。
`IMGLI_TRUST_PROXY`	有反代时必需为 true	`false`	是否信任反代传来的 `X-Forwarded-For` 等头。仅在前面有 Nginx/Caddy/1Panel 等可信反代时打开；直连公网不要开。
`IMGLI_LISTEN`	可选	`:8686`	进程监听地址。Docker 内一般保持 `:8686`，由端口映射/反代暴露。
`IMGLI_DATA_DIR`	可选	`./data`（镜像内常为 `/data`）	本地文件与默认 SQLite 库所在目录。用 Docker 时挂卷到这里即可，不必再改。
`IMGLI_DATABASE_DRIVER`	可选	`sqlite`	`sqlite`（默认，单机省事）或 `postgres`。
`IMGLI_DATABASE_DSN`	用 Postgres 时必需	（SQLite 自动用 `<data_dir>/imgli.db`）	Postgres 连接串。SQLite 请留空，让程序写默认路径与安全参数。若自写 DSN，需自行加 pragma。
`IMGLI_FETCH_ALLOW`	可选	空	仅在启用「URL 抓取上传」且要访问内网地址时，用逗号追加 host/CIDR。默认拒绝内网，一般不用动。
`IMGLI_RATE_LIMIT_MULT`	可选	`1`	限速倍率。生产保持 1；只给 e2e/压测用。
`IMGLI_SERVE_CACHE_DISABLED`	可选	未设 / false	v0.9.12：设为 `true` 关闭源站缓存。默认对公开（无口令、无次数上限）的 `/t` 与未 302 的 `/i` 缓存在 `{data_dir}/.serve-cache`。
`IMGLI_SERVE_CACHE_MAX_BYTES`	可选	`0`（= 512MiB）	源站缓存上限（字节）。`0` 表示默认 512MiB。

反代登录 403 优先查 IMGLI_BASE_URL。见 FAQ · 安全加固。

YAML 示例（可选）

不写文件也可以。若要用文件，仓库示例：deploy/imgli.example.yaml。精简示意：

listen: ":8686"
base_url: "https://img.example.com"   # 与浏览器地址一致
data_dir: "/opt/imgli/data"
database:
  driver: sqlite                      # 或 postgres + dsn
trust_proxy: true                     # 仅反代后
# serve_cache_disabled: false         # v0.9.12 公开 /t 与未 302 的 /i
# serve_cache_max_bytes: 0            # 0 = 512MiB；目录 <data_dir>/.serve-cache

启动：

imgli serve
# 或
imgli serve -config /opt/imgli/imgli.yaml

SQLite 还是 PostgreSQL？

	SQLite（默认）	PostgreSQL
适合	单机、个人/小团队、运维简单	已有 PG、要更大规模或运维规范
怎么开	默认即可	`IMGLI_DATABASE_DRIVER=postgres` + `IMGLI_DATABASE_DSN=…`
备份	备份 `data_dir`（库 + 本地图）	`pg_dump` + 对象存储/本地盘

两种驱动都在同一二进制里，无需额外安装数据库客户端。

Docker：数据目录怎么挂

方式	建议
命名卷 `imgli-data:/data`	推荐。Compose 默认；权限与 SQLite 最省心。
绑定挂载 `/var/lib/imgli:/data`	可用，但须是本机本地磁盘；目录预先建好且可写。不要把 SQLite 放到 NFS/CIFS/网盘。

低内存 ARM 板子若把命名卷改成绑定挂载后出现 out of memory：
1）先改回命名卷试一下；
2）上传/转码时设 VIPS_CONCURRENCY=1；
3）仍不稳可改用 Postgres。说明见 FAQ。

运维配置 vs 后台业务

本文（运维层）	管理后台
监听、数据目录、数据库、base_url、trust_proxy	站名、外观、注册、用户组、存储策略、SMTP、机审…

改完运维参数后重启进程。v0.7+ 可在后台 系统 / 运维 看 doctor 与 base_url 是否和浏览器一致。

配置（运维层）

配置（运维层）

要不要写配置文件？

上线时通常只改 1～2 项

环境变量说明

YAML 示例（可选）

SQLite 还是 PostgreSQL？

Docker：数据目录怎么挂

运维配置 vs 后台业务

相关文档