English ｜ 简体中文
ImageSilo
给图片一个轻量、稳定的自托管归处。
ImageSilo 是一个 Docker 优先的自托管图床：单个 Go 进程、SQLite 元数据和本地文件存储。它提供安全上传、稳定公开 URL、历史别名、具名 API Token、图片处理和响应式 React 管理界面，不依赖 Redis、外部数据库或后台任务服务。
> 发布镜像使用不可变版本标签和可变的 `latest` 标签；生产部署应固定不可变版本标签或 digest。
## 界面预览
## 功能特性
- 严格解码 JPEG、PNG、WebP 和 GIF，并设置 16 MP 像素安全边界
- 默认保持原始字节，也可明确压缩或将静态图片转换为 WebP
- 标准公开 URL、历史别名和保留路径的迁移文件支持 Range、条件请求与 HEAD
- 图片交付热路径完全使用内存索引，每次读取不查询 SQLite
- 支持公开/私密可见性、管理员 Session、CSRF、防登录爆破和分 Scope API Token
- 内置管理界面可上传、搜索、筛选、查看详情、批量修改和永久删除图片
- 支持旧 URL 导入、SHA-256 字节校验、存储巡检和内存索引重建
- 以非 root 多架构容器运行，图片处理并发默认固定为 `1`
## 快速开始
Docker 是唯一支持的生产运行方式。以下命令使用 named volume 启动一个本地体验实例：
```bash
export IMAGESILO_IMAGE=ghcr.io/willxup/imagesilo:latest
docker pull "$IMAGESILO_IMAGE"
docker volume create imagesilo-data
docker run --detach \
--name imagesilo \
--restart unless-stopped \
--publish 127.0.0.1:8080:8080 \
--env IMAGESILO_COOKIE_SECURE=false \
--env IMAGESILO_PROCESSING_CONCURRENCY=1 \
--volume imagesilo-data:/data \
"$IMAGESILO_IMAGE"
```
首次启动后执行 `docker logs -f imagesilo`，复制 ImageSilo 日志中的 `bootstrap_token`。打开 `http://127.0.0.1:8080/admin/setup`，填写该 token 后创建管理员账号。token 只保存在内存中；未初始化时重启会重新生成，初始化成功后立即清除。自动化部署仍可使用 `imagesilo admin create` 命令。
生产环境应在反向代理终止 HTTPS、保持 `IMAGESILO_COOKIE_SECURE=true`，并在停止写入时完整备份 `/data`。对外开放前请先阅读[部署指南](./docs/deployment.md)。
如果需要完整保留旧图床的 URL 目录树，可以将原目录只读挂载到 `/data/migrations`，无需逐条创建历史路径。例如 `/data/migrations/i/2022/04/example.jpg` 会直接通过 `/i/2022/04/example.jpg` 访问。相同路径同时存在时，后台管理的历史路径映射优先；该目录只公开 JPEG、PNG、WebP 和 GIF 文件。后台“迁移管理”可以在只读模式下浏览和复制这些直链；文件列表使用 30 分钟惰性快照，也可手动刷新，图片直链不受列表缓存影响。仅对专用迁移副本启用永久删除时，才将挂载改为可写并设置 `IMAGESILO_MIGRATION_MUTATIONS=true`。
## 开启迁移删除管理
迁移删除默认关闭，并且只建议对有独立备份的专用迁移副本开启。环境变量、挂载模式和宿主机权限必须同时满足要求；只设置环境变量但保留只读挂载仍然无法删除。
在 `docker-compose.yaml` 中设置删除开关，并确保 `/data/migrations` 使用可写挂载：
```yaml
services:
imagesilo:
image: ghcr.io/willxup/imagesilo:latest
environment:
IMAGESILO_MIGRATION_MUTATIONS: "true"
volumes:
- ./data:/data
- ./migration:/data/migrations:rw
```
如果当前迁移挂载以 `:ro` 结尾，必须将其改为 `:rw` 或省略挂载模式。如果迁移文件直接位于可写的 `./data/migrations` 中，则不需要再增加单独的迁移挂载。
容器固定使用 UID/GID `10001:10001`。仅对专用迁移副本执行以下权限设置：
```bash
sudo chown -R 10001:10001 ./migration
sudo find ./migration -type d -exec chmod 750 {} +
sudo find ./migration -type f -exec chmod 640 {} +
```
验证配置并重建容器；普通 `docker compose restart` 不会应用新的环境变量：
```bash
docker compose config --quiet
docker compose up -d --force-recreate
docker compose exec imagesilo sh -c \
'test "$IMAGESILO_MIGRATION_MUTATIONS" = true && test -w /data/migrations'
```
删除操作不可恢复。删除图片后，ImageSilo 还会递归移除真正为空的父目录，包括空的顶层 `i` 或 `images`，但不会删除 `/data/migrations` 根目录。不要对旧图床唯一原件开启此能力。
## 设计边界
| 范围 | 实现方式 |
| --- | --- |
| 运行时 | 一个容器内的单个 Go 进程 |
| 元数据 | `/data/db` 中的 SQLite |
| 图片 | `/data/images` 中的本地文件 |
| 保留路径迁移 | `/data/migrations` 中默认只读、可显式开启删除管理的图片目录树 |
| 缓存 | `/data/cache` 中的本地缩略图 |
| 图片处理 | libvips，默认并发 `1` |
| 图片读取 | 文件流式交付与 ETag 复验，默认不限制（`0`），可选配置上限 |
| 平台 | `linux/amd64`、`linux/arm64` |
| 生产存储 | Docker named volume 或本地 bind mount |
不支持 NFS 和 SMB，也不能让两个 ImageSilo 容器同时写入同一个 `/data`。
## 本地开发
### 前置依赖
- Go >=1.26.10
- Node.js >=24.22.1
- npm
本地工具链只需满足最低版本，不固定精确版本；npm 安装依赖时会强制检查 Node.js 最低版本。CI 使用最新 Go 1.26.x 和 Node.js 24.x；Docker 构建使用 Debian Bookworm 滚动镜像标签，并通过 `--pull` 刷新基础镜像。
### 构建与验证
```bash
npm --prefix web ci
make check
make build
```
创建管理员并运行本地二进制：
```bash
IMAGESILO_DATA_DIR="$PWD/data" \
./bin/imagesilo admin create --email admin@example.com
IMAGESILO_DATA_DIR="$PWD/data" \
IMAGESILO_COOKIE_SECURE=false \
./bin/imagesilo serve
```
`/healthz` 用于存活检查，`/readyz` 用于 SQLite 就绪检查。
界面或浏览器行为变更按需使用现有浏览器，通过人工或 computer-use 工具验收，不要求项目安装或维护专用浏览器及浏览器测试框架。CI 执行 `make check`（构建、Lint、类型检查、单元/集成测试），不执行浏览器验收。请遵循[浏览器验收清单](./docs/browser-acceptance.md)，记录实际结果并明确标注未验证场景。
## 文档导航
| 主题 | 文档 |
| --- | --- |
| Docker 部署、备份、升级与回滚 | [部署指南](./docs/deployment.md) |
| API Token、curl、PicGo 与 ShareX | [API Token 使用](./docs/api-token-usage.md) |
| 旧图片与历史 URL 迁移 | [导入指南](./docs/imports.md) |
| 巡检、清理与索引重建 | [运维指南](./docs/operations.md) |
| 架构与数据模型 | [架构](./docs/architecture.md) · [数据模型](./docs/data-model.md) |
| 安全与性能 | [安全审计](./docs/security-audit.md) · [性能基线](./docs/performance-baseline.md) |
| 发布流程与验证 | [发布指南](./docs/release.md) |
| HTTP API 契约 | [OpenAPI](./api/openapi.yaml) |
| 随附的第三方许可证 | [第三方声明](./THIRD_PARTY_NOTICES.md) |
## 许可证
本项目基于 [MIT License](./LICENSE) 开源。
