picx-images-hosting

🐧 缘起

XPoet/picx 项目用于存放、管理 GitHub 图床虽然已经很便利了，但仍有一些个人觉得一些的痛点：

1. 因为是 https://picx.xpoet.cn/#/upload 作为驱动器，记住一个自己不熟悉的域名，显然不是太友好
2. 尤其作为图床来说，自己这边上传图片没有 GitHub Pages 图片预览，是很难受的一件事

以上，以及经历过不少组织、个人图床跑路，导致我的一些相关项目引用图片失效，所以必须拥有自己的图床。我的解决方案是: 自建 GitHub 图床 + picx 结合使用。

📋 项目介绍

picx-images-hosting 是一款基于 GitHub Pages 构建的 Web 图床管理系统，搭配 PicX 达成无缝衔接高度定制化的个人公共图片上传及管理。

网页版图床是图片资产的管理后台，而 PicGo、PicList 等图床扩展软件是写作时的快捷生产工具。它们共享一个 GitHub 数据仓库，既能享受批量管理的便利，也能拥有写作时一键插图的畅快。

项目地址： https://github.com/hoochanlon/picx-images-hosting

这也是我第一个 web 项目，没有做国际化，没有框架，纯 js、css、html，写了好久了，一直没有时间整理发上来。

核心特性

• 📤 图片上传管理: 支持批量上传、目录管理、文件重命名
• 🔐 多种认证方式: 支持 GitHub OAuth 和密码认证
• 🗜️ 图片压缩: 集成 TinyJPG/TinyPNG API，自动压缩图片
• 📊 API 健康监控: 实时监控 API 状态，快速定位问题
• 🌙 深色模式: 支持浅色/深色主题切换
• 📱 响应式设计: 适配桌面和移动设备

技术架构

• 前端: 纯 HTML/CSS/JavaScript，无需构建工具
• 后端: Vercel Serverless Functions
• 存储: GitHub 仓库（通过 GitHub API 管理）
• 认证: GitHub OAuth 2.0 或密码认证
• CDN: 支持 jsdelivr、statically.io 等 CDN 加速

在线教程: https://hoochanlon.github.io/picx-images-hosting/tutorial.html

截图

首页

上传

登录与 API 状态检查

教程页面

主要部署配置

🚀 使用方式

快速开始

1. 克隆仓库

git clone --filter=blob:none --no-checkout https://github.com/hoochanlon/picx-images-hosting.git
cd picx-images-hosting
git sparse-checkout set --no-cone '/*' '!/imgs/*'
git checkout master

2. 配置基础文件

config.js

修改以下配置：

• VERCEL_API_BASE：你的 Vercel 部署地址
• GITHUB_OAUTH_CLIENT_ID：GitHub OAuth Client ID（如果使用 OAuth）
• PASSWORD：操作密码（如果使用密码认证）

api-config.json

添加允许访问 API 的域名：

{
  "allowedOrigins": [
    "https://your-domain.com",
    "https://your-name.github.io",
    "https://your-vercel-app.vercel.app"
  ]
}

3. 配置 Vercel 环境变量

⚠️ 重要: 环境变量配置后必须重新部署才能生效！

4. GitHub OAuth 配置（推荐）

1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
2. 填写信息：
   • Application name：picx-images-hosting
   • Homepage URL：https://your-vercel-app.vercel.app
   • Authorization callback URL：https://your-vercel-app.vercel.app/api/github-oauth?action=callback
3. 记录 Client ID 和 Client Secret（Secret 只显示一次）
4. 将 Client ID 填入 config.js，将 Client ID 和 Secret 填入 Vercel 环境变量

5. 配置图片压缩（可选）

1. 访问 TinyPNG Developer API
2. 输入邮箱地址获取 API Key
3. 将 API Key 添加到 Vercel 环境变量 TINYJPG_API_KEY

部署到 Vercel

1. 登录 Vercel
2. 导入 GitHub 仓库
3. Settings → Environment Variables → 添加变量
4. 选择环境：Production、Preview、Development
5. Deployments → Redeploy

本地开发

安装依赖

pnpm add -D vercel

配置环境变量

复制 env.example 为 .env.local：

cp env.example .env.local

编辑 .env.local：

• GH_TOKEN：GitHub Personal Access Token
• API_BASE：http://localhost:3000（本地开发）

启动开发服务器

vercel dev

访问 http://localhost:3000 查看应用。

使用功能

图片上传

1. 点击右上角锁图标进行认证（密码或 GitHub OAuth）
2. 认证成功后，点击上传按钮
3. 选择图片文件（支持批量选择）
4. （可选）启用"图片压缩"开关
5. 选择上传目录
6. 点击上传

图片管理

• 查看图片: 首页显示所有图片，支持按目录筛选
• 重命名: 点击图片名称进行重命名
• 删除: 点击删除按钮删除图片
• 查看链接: 点击图片查看完整链接

API 健康监控

访问 /status.html 查看详细的健康状态信息：

• 实时监控: 自动每 30 秒刷新一次状态
• 详细检查: 显示 GitHub API、仓库树 API、环境配置等各项检查结果
• 响应时间: 显示每个 API 端点的响应时间

⚠️ 注意事项

存储限制

• GitHub 存储限制: 最多 5G
• 文件大小: 建议单个文件不超过 100MB
• 仓库大小: 定期清理不需要的图片，避免超出限制

部署要求

• GitHub Pages: 部署到 GitHub Pages 后才能使用 GitHub Pages 规则的图片链接
• CORS 配置: 确保 api-config.json 中包含所有需要访问的域名
• 环境变量: 修改环境变量后必须重新部署才能生效

访问优化

• 国内访问: 建议使用 jsdelivr 、 statically.io 等 CDN 加速
• GitHub Pages: 国内访问可能较慢，建议使用 CDN 代理

安全建议

认证方式

1. 优先使用 GitHub OAuth（最安全）

   • 使用 GitHub 官方 OAuth
   • 无需密码，用户使用 GitHub 账号授权
   • 权限可控

2. 密码认证（备用方案）

   • 使用强密码（至少 32 字符）
   • 优先使用 Vercel 环境变量，不要将密码写在 config.js 中
   • 密码会暴露在代码中，仅作为备用方案

API Key 安全

• TinyJPG API Key: 通过服务器端 API 代理，API Key 不会暴露在前端
• GitHub Token: 只存储在 Vercel 环境变量中，不要提交到代码仓库

常见问题

部署问题

认证问题

配置问题

API 健康状态问题

图片压缩功能

• 支持的格式: JPEG、PNG、WebP、AVIF
• 压缩方式: 通过服务器端 API 代理，保护 API Key 安全
• 降级处理: 如果压缩失败，自动使用原文件上传，不影响上传流程
• 使用方式: 在上传页面或快速上传弹窗中启用"图片压缩"开关

📝 注意: 图片压缩功能需要配置 TINYJPG_API_KEY 环境变量。未配置时，压缩开关会被禁用或跳过压缩步骤。

其他注意事项

1. 文件夹创建延迟: 文件夹创建失败但实际已创建是正常的，GitHub API 同步可能有延迟
2. .gitkeep 文件 404: 这是正常的，.gitkeep 文件用于保持空目录，首次创建时会返回 404
3. 图片链接无法访问:
   • 检查 GitHub Pages 是否已启用
   • 检查图片路径是否正确
   • 使用 CDN 链接（jsdelivr）可能更快

高级玩法

picx-images-hosting 可基于该项目进行二次开发，以支持七牛云、又拍云、B2、R2 等兼容 S3 的对象存储。以及通过 CF-Proxy-B2 来实现 100% 免流的目的。