PicHost

简体中文

English

简体中文

English

主题

存储 ​

PicHost 支持 本地磁盘、S3 兼容对象存储（Cloudflare R2、腾讯云 COS、阿里云 OSS、AWS S3 等）与 Telegram 频道/群组。管理员在 存储（/storage）页管理后端；新上传写入 默认后端。页面顶部展示 存储总览（总量、已用、剩余、使用率与容量分布），下方为各后端卡片与支持的后端类型说明。

存储管理

存储结构（本地） ​

/data
├── pichost.db          # SQLite：用户、会话、设置、storage_backends、images 索引
└── images/             # 本地后端时的全部图片文件
  • 新上传：images/随机ID.webp 或 images/年/月/随机ID.webp（可在设置中切换扁平模式）
  • 迁移遗留：images/blog/... 等子路径
  • 云存储时文件在对应桶内，索引仍在 SQLite images 表

所有图片 key 以 images/ 开头。上传 API 不再接受 folder 参数。

图片分类使用每用户 标签（tags / image_tags 表），不改变磁盘路径。图库页按标签筛选；详见 API 文档。

添加存储后端 ​

  1. 以管理员登录，打开 存储 → 添加存储。
  2. 选择类型：本地磁盘、S3 兼容（含 R2 / COS / OSS 预设）或 Telegram 频道。
  3. 填写连接信息（桶名、Endpoint、Access Key，或 Bot Token / Chat ID 等）。
  4. 保存后可 设默认，新上传将写入该后端。

新建后端的 存储标识 按类型自动生成前缀：本地为 local；R2 为 r2-*；COS 为 cos-*；OSS 为 oss-*；AWS S3 及自定义 S3 兼容为 s3-*；Telegram 为 tg-*（创建后不可修改，图片索引会引用该 ID）。

Cloudflare R2 要点 ​

项值
Endpointhttps://<account_id>.r2.cloudflarestorage.com
Regionauto
桶你的 R2 桶名
密钥R2 API Token 的 Access Key / Secret Key

若仓库 cloudflare 分支专用于「仅 R2」部署，也可用环境变量预设，见 文档首页 分支说明。

Telegram 频道 / 群组 ​

用 Bot 把图片发进指定频道或群组（含私有频道），访客仍通过 PicHost 直链访问，不会跳到 Telegram 文件地址。

  1. 在 @BotFather 创建 Bot，取得 Token。
  2. 把 Bot 设为频道或群组管理员（需要发消息；若希望图库删除时同步删掉群消息，还需要删除消息权限）。
  3. 在存储页选择 Telegram 频道，填写 Chat ID（超级群组/频道多为 -100…）、Bot Token，以及套餐配额。
  4. 服务器若不能直连 api.telegram.org，可填写可选的 HTTP/HTTPS API 代理（如 http://127.0.0.1:7890）。

限制与行为：

  • 单文件实际上限约 20MB（超过站点上传限制时，以更小者为准）
  • 同一频道大约 20 条消息/分钟；批量上传过快会失败并提示稍后重试
  • 直链固定为 proxy，不能改为公开 URL
  • 图库删除会尝试删除对应的 Telegram 消息；上传失败且未记下文件编号时，会尽量撤回刚发出的消息
  • 整站备份会经 Bot 拉取文件，耗时并受上述频率限制；备份包不含 Bot Token，恢复后需重新填写。恢复到 Telegram 默认后端时，会把图片重新发进频道

环境变量（可选） ​

部分部署用环境变量初始化默认 S3 后端（如 STORAGE_BACKEND=s3、S3_ENDPOINT、S3_BUCKET、S3_ACCESS_KEY、S3_SECRET_KEY、S3_REGION）。UI 中配置的后端信息存于 SQLite，与环境变量并存时以管理界面为准管理多后端。

直链模式 ​

每个后端可配置公开 URL 行为：

模式说明
proxy通过 PicHost 同源代理出图（GET /images/...）
public302 重定向到桶/CDN 公网地址

复制链接时使用 图片域名（IMAGE_BASE_URL）拼接路径。开启「隐藏 images 前缀」后 URL 可能更短，服务按文件名或路径反查索引。

用量与筛选 ​

  • 存储页展示各后端用量（本地扫描目录，对象存储查询 API）
  • 图库可按 存储后端、上传来源、标签 筛选，支持网格/列表视图切换；点击图片打开详情弹窗（尺寸、存储路径、标签、多格式链接复制）

图库网格 图库列表 图片详情

备份与迁移（v1.3.0+） ​

存储页 备份与迁移 面板包含三张功能卡与下方 最近任务 列表：

能力说明
创建站点备份导出 .phost.tar.gz，含 pichost.db 与全部图片（含云存储中的对象）；展示预计体积与备份包含项
从备份恢复本地上传或选择 data/backups/ 内已有包，预检后确认；可选跳过/覆盖冲突图片
跨后端同步在已配置后端间拷贝图片并更新索引；展示待迁移数量与体积，支持预检、删源、设默认

备份与迁移

  • 导出文件保存在 data/backups/；后端同一时间仅允许一个进行中的备份/迁移任务
  • 任务列表支持分页，可下载导出包、查看恢复结果、重试失败的同步任务
  • 备份包 不含 云存储 Access Key / Secret Key，恢复后请在存储页重新填写
  • 未初始化实例可在 setup 页 从备份恢复 标签上传整站包（始终覆盖模式）

从备份恢复（setup）

CLI ​

bash
# 导出整站备份
docker exec pichost backup-export

# 从备份恢复（默认跳过冲突图片）
docker exec pichost backup-restore /data/backups/pichost-xxx.phost.tar.gz
docker exec pichost backup-restore /data/backups/pichost-xxx.phost.tar.gz --overwrite

# 跨后端同步
docker exec pichost storage-sync --from local --to s3-xxx --dry-run
docker exec pichost storage-sync --from local --to s3-xxx --set-default

本地开发（项目根目录）：

bash
npm run backup-export
npm run backup-restore -- data/backups/pichost-xxx.phost.tar.gz
npm run storage-sync -- --from local --to s3-xxx --dry-run

手动备份 ​

仍可同时备份 data/images/（本地后端）、data/pichost.db 与各云桶中的对象；推荐使用上文整站导出。

相关 ​