PicHost
个人轻量图床 · 图片放好，管理也要顺手
自托管图床 / 多用户 / Docker / API / Twikoo · 本地磁盘或对象存储
分支 ·
快速开始 ·
预览 ·
特性 ·
技术栈 ·
路线图 ·
English
---
## 分支
| 分支 | 说明 |
| ---- | ---- |
| [**main**](https://github.com/O96u/PicHost/tree/main)（默认） | **v1.1.2** 主线：本地磁盘 + 多对象存储后端（R2 / COS / OSS / AWS）、[`/storage`](docs/README.md) 存储管理、混合直链 |
| [**cloudflare**](https://github.com/O96u/PicHost/tree/cloudflare) | **Cloudflare R2 专用线**：面向「只用 R2」的部署，预设与配置更聚焦 R2 |
日常使用、需要管理多种存储后端，请直接用 **main**。
若图床**只接 Cloudflare R2**、希望更简化的 R2 专用版本，可切换分支：
```bash
git clone https://github.com/O96u/PicHost.git
cd PicHost
git checkout cloudflare
```
---
## 界面预览
| 上传 | 存储管理 |
| :-----------------------------------: | :-------------------------------------: |
|  |  |
| 统计与图库 | 系统设置 |
| :---------------------------------: | :-------------------------------------: |
|  |  |
## 特性
- **拖拽 / 点击 / Ctrl+V 粘贴**上传；管理员可自定义 `folder` 目录
- **服务端 WebP 压缩**（sharp）、Referer 防盗链、可配置访问域名
- **多用户**：账号密码登录；管理员可开放注册；普通用户仅见自己的图片
- **上传偏好**（首页卡片翻转）：客户端预压缩、自动复制链接、按用户自动删除
- **多后端存储**：本地磁盘 + S3 兼容（Cloudflare R2 / 腾讯云 COS / 阿里云 OSS / AWS S3）；管理员在 **存储**（`/storage`）页管理，新上传写入默认后端
- **混合直链**：`proxy`（PicHost 同源代理）或 `public`（302 到 CDN / 桶公网地址）
- **图库**：浏览、搜索、批量删除；管理员可查看上传者标签
- **统计**：上传/删除趋势、目录分布；管理员额外显示注册用户数量
- **API**：全局 Token（管理员）+ 每用户个人 Token；后台可复制 cURL
- **Twikoo**：`POST /api/index.php`（`image` + `token`）
- **Docker 零配置**：首次访问 Web 引导创建管理员，无需预先写密钥
## 快速开始
### Docker（推荐）
```bash
docker run -d \
--name pichost \
-p 6892:6892 \
-v ./data:/data \
--restart unless-stopped \
muxui/pichost:latest
```
默认端口 **6892**。浏览器打开 `http://<主机IP>:6892`，按引导创建管理员即可。
**忘记密码**（需能执行 `docker exec`，相当于服务器权限）：
```bash
# 无参数：重置管理员（仅当系统中只有一个管理员时）
docker exec pichost reset-password
# 指定用户名：可重置管理员或普通用户
docker exec pichost reset-password 用户名
```
终端会打印随机新密码；用户不存在时会报错。登录后请到「修改密码」更换。
本地：`npm run reset-password` 或 `npm run reset-password -- 用户名`
已克隆仓库时也可用 `docker compose up -d`（见仓库内 `docker-compose.yml`）。
### 本地开发
```bash
npm install
cp .env.example .env # 可选
npm run dev
```
访问 `http://localhost:3000/setup` 创建管理员；数据目录默认 `./data`。
## 技术栈
| 层级 | 技术 |
| -------- | ------------------------------------------ |
| 前端 | Nuxt 4、Vue 3、Nuxt UI 4、Tailwind CSS 4 |
| 后端 | Nitro（Node.js）、SQLite |
| 图片处理 | sharp（WebP 转码与压缩） |
| 鉴权 | Session Cookie、scrypt 密码哈希、API Token |
| 存储 | 本地磁盘 + S3 兼容后端（R2 / COS / OSS / AWS）；`images` 索引在 SQLite |
| 部署 | Docker（amd64 / arm64）、docker compose |
| 测试 | Vitest |
## 用户与权限
| 场景 | 鉴权 | 图片归属 / 可见范围 |
| -------------------------- | -------------------- | -------------------------- |
| 网页上传 | Session | 当前登录用户 |
| API 上传 + **个人 Token** | `Auth-Token` | 该 Token 所属用户 |
| API 上传 + **全局 Token** | `Auth-Token` | 管理员（`userId` 为空） |
| Twikoo `/api/index.php` | 表单 `token` | 与全局 Token 相同 |
| 图库列表 / 搜索 / 删除 | Session 或 Token | 普通用户仅自己；管理员全部 |
| 图片直链 `GET /images/...` | 无（Referer 防盗链） | 知道 URL 即可访问 |
普通用户上传目录固定为 `images/`；自定义 `folder` 仅管理员或全局 Token 可用。
## 存储结构
```
/data
├── pichost.db # SQLite：用户、会话、设置、storage_backends、images 索引
├── images/ # 默认上传目录（本地后端时）
├── blog/ # 管理员自定义 folder 示例
└── twikoo/ # Twikoo 评论图片
```
路径规则：`目录/年/月/随机ID.webp` + 同名 `.meta.json`。云存储时文件在对应桶内，SQLite `images` 表记录 `backend_id` 与 `key`。备份请包含整个 `/data` 与云桶数据。
## API 概览
| 方法 | 路径 | 说明 |
| ------ | -------------------- | ---------------------- |
| POST | `/api/images/upload` | 上传图片 |
| GET | `/api/images` | 分页列表 |
| DELETE | `/api/images` | 删除单张（`key`） |
| POST | `/api/index.php` | Twikoo / EasyImage 2.0 |
上传示例：
```bash
curl -X POST "https://pic.example.com/api/images/upload" \
-H "Auth-Token: YOUR_TOKEN" \
-F "folder=blog" \
-F "image=@./demo.png"
```
完整接口与可复制 cURL 见部署后后台 **API** 页。
## Twikoo
| 配置项 | 值 |
| ----------------- | -------------------------------- |
| `IMAGE_CDN` | `easyimage` |
| `IMAGE_CDN_URL` | `https://你的域名/api/index.php` |
| `IMAGE_CDN_TOKEN` | 与 `API_UPLOAD_TOKEN` 相同 |
## 反向代理
- 反代到容器 **6892** 端口，建议 HTTPS
- Nginx：`client_max_body_size` ≥ 12m
- 公网访问请配置 `IMAGE_BASE_URL`
## 开发
```bash
npm run dev # 开发服务器
npm run build # 生产构建
npm run start # 运行 .output
npm run lint # ESLint
npm run typecheck # 类型检查
npm test # 单元测试
```
## 路线图
| 版本 | 说明 |
| ---------- | ------------------------------------------------- |
| **v1.1.2** | 操作日志、图库存储筛选、上传限流（当前 main） |
| **v1.1.1** | 会话校验与存储占位修复、Docker 日志增强 |
| **v1.1.0** | S3 / R2 多后端对象存储、混合直链、存储管理页 |
| **v1.0.4** | 密码显示切换、遗留 ADMIN_SECRET 迁移对齐 |
| **v1.0.3** | CI 与 Docker 多架构构建修复 |
| **v1.0.2** | 中英文、移动端菜单、统计/上传 UI、Docker 重置密码 |
| **v1.0.1** | 设置页版本展示、移动端上传偏好布局修复 |
| **v1.0.0** | 本地存储、多用户、API、Twikoo |
## License
[MIT](LICENSE)
## 友链
[LINUX DO](https://linux.do/)