# image2url-public-project

**Repository Path**: aylerh/image2url-public-project

## Basic Information

- **Project Name**: image2url-public-project
- **Description**: 介绍：（1）免配置图床：免配置上传图片到云端（2）sqlite数据库存储上传记录;功能:(1)image2url;(2)md2md-替换图片为url；缺点：（1）图片保存在公共网站；优点：（1）图片不占用本地空间；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 概览

Image2URL 是一款极速、轻量且具备现代美学设计的免登录图床与 Markdown 链接生成器。它专为博客作者、Markdown 编辑者和开发者设计，集成了单图代理上传与 Markdown 压缩包图片一键云端转换两大核心功能。

## 页面样式

### 主页

![1](./images/1.png)

## 功能概览
- image2url;
- md(zip)-》纯md（图片转为url直链）；
- html(zip)-》纯html（图片转为url直链）；

## 核心功能

1. **多图床单图上传**：支持将图片上传至 Freeimage、Imgur、vgy.me 和 Catbox。
2. **凭证快捷指引**：设置面板提供 Imgur Client-ID 和 vgy.me UserKey 的交互式弹窗申请与配置引导步骤。
3. **文件属性与分辨率检测**：在选择文件及上传结果中展示文件名、文件大小与图片像素（宽高比例）。
4. **Markdown 压缩包一键转换**：支持上传 `.zip` 压缩包（包含 `.md` 文件及相对路径引用的本地图片），后端自动将图片转存至云端 CDN，并更新 Markdown/HTML 图片链接，最终输出纯 `.md` 文件供一键复制或下载。
   - **永久转换**：基于 Freeimage.host 永久图床转换。
   - **临时转换**：基于 Catbox (Litterbox) 临时图床转换（3天有效）。
5. **HTML 压缩包一键转换**：支持上传 `.zip` 压缩包（包含 `.html/.htm` 文件及相对路径引用的本地图片，智能处理 `src=`、`href=` 以及 CSS `url()` 等多种资源引用），后端自动将图片转存至云端 CDN，并更新 HTML 图片链接，最终输出纯 `.html` 文件供一键复制或下载。
   - **永久转换**：基于 Freeimage.host 永久图床转换。
   - **临时转换**：基于 Catbox (Litterbox) 临时图床转换（3天有效）。
6. **上传历史记录与模糊查询**：记录成功上传并返回线上链接的所有图片信息，包括业务自增 ID、图片 MD5 校验码、上传时间戳、文件名、大小、格式、像素分辨率及上传后的 url 地址。支持以文件名和 url 进行实时模糊搜索，并支持分页（单页最多展示 10 条）。
7. **SQLite 高性能持久化存储**：采用 WAL 优化参数的 SQLite 数据库（`synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=5000`）存入上传记录，数据自动挂载到外部 `./data` 目录，保障容器重启/重建后数据不丢失。

## 支持的图传限制说明

| 图传平台 | 单张大小限制 | 有效期 | 数量限制 | 频率限制 / 速率限制 |
| :--- | :--- | :--- | :--- | :--- |
| **Freeimage.host** | 64 MB | 永久保存 | 无限制 | 无严格限制，高频请求将受 IP 限制 |
| **Imgur** | 20 MB (动图 200MB) | 长期保存 | 每个 Client-ID 1,250张/天 | 约 50次上传/小时/IP |
| **vgy.me** | 20 MB | 长期保存 | 无限制 | 过高频率会触发 429 限制 |
| **Catbox (Litterbox)** | 200 MB | 临时保存 (3天/72小时) | 无限制 | 无严格限制，受常规防火墙保护 |

# 构建与运行

本项目完全基于 Docker 容器化构建，无需在本地配置 Python 或 Node.js 环境。

### 1. 配置文件

复制或编辑项目根目录下的 `.env` 文件：
```env
INNER_PORT=8166
OUTER_PORT=8166
IMGUR_CLIENT_ID=           # （可选）Imgur 客户端 ID
VGYME_USER_KEY=            # （可选）vgy.me 用户 Key
DEFAULT_RECORDS_COUNT=10   # （可选）打开历史记录后默认展示的最近记录条数
```

### 2. 启动服务

使用 PowerShell 运行以下命令启动服务：
```powershell
$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; docker compose up --build -d
```

启动完成后，在浏览器中访问：`http://localhost:8166`。数据文件夹将自动挂载并创建在本地项目目录下的 `.\data` 文件夹内。

---

# API 接口说明

本项目提供了以下专有 API 接口：

1. **`POST /api/upload/permanent`**
   - **用途**：单图永久上传接口。
   - **参数**：表单数据 `file` (文件对象)，请求头 `X-Freeimage-Key` (可选)。
2. **`POST /api/upload/temporary`**
   - **用途**：单图临时上传接口 (72小时有效)。
   - **参数**：表单数据 `file` (文件对象)。
3. **`POST /api/convert/permanent`**
   - **用途**：ZIP 压缩包 Markdown 永久链接转换接口。
   - **参数**：表单数据 `file` (zip 压缩包)，请求头 `X-Freeimage-Key` (可选)。
4. **`POST /api/convert/temporary`**
   - **用途**：ZIP 压缩包 Markdown 临时链接转换接口。
   - **参数**：表单数据 `file` (zip 压缩包)。
5. **`POST /api/convert/html/permanent`**
   - **用途**：ZIP 压缩包 HTML 永久链接转换接口。
   - **参数**：表单数据 `file` (zip 压缩包)，请求头 `X-Freeimage-Key` (可选)。
6. **`POST /api/convert/html/temporary`**
   - **用途**：ZIP 压缩包 HTML 临时链接转换接口。
   - **参数**：表单数据 `file` (zip 压缩包)。
7. **`GET /api/records`**
   - **用途**：历史上传记录查询与分页接口。
   - **参数**：查询参数 `query` (可选，进行文件名或 URL 模糊匹配)，`page` (页码，默认 1)，`limit` (每页条数，默认读取配置或为 10)。

---

# 解决痛点与使用技术

### 解决痛点
1. **多格式手动拼接繁琐**：通常上传图床后需手动拼接成 Markdown 或 HTML 格式。本项目一键上传，并自动生成直链、Markdown 嵌入、HTML 代码和删除链接，支持一键复制。
2. **凭证管理不便**：将凭证硬编码在服务端会导致部署复杂。本项目支持在前端设置面板临时/永久保存 API 凭证到 `localStorage` 中，并在上传时动态传递，无需重启容器。
3. **上传操作不连贯**：通常需要先保存截图再上传。本项目支持直接使用快捷键 `Ctrl + V` 从剪贴板粘贴截图上传，并支持拖拽上传。
4. **直传速度与安全限制**：移除了不稳定的客户端直传，统一通过高稳定性的服务端代理代理上传，并实时反馈网络耗时。
5. **本地 Markdown 文档图床转换复杂**：传统的本地 Markdown 转换图床脚本复杂且易出错。本项目支持一键拖入 Zip 压缩包，自动提取并转换输出可以直接发布的纯 Markdown 文件。
6. **无历史追溯能力**：对于已上传的链接因刷新页面或清空缓存导致需要重新上传。本项目集成 SQLite 本地库自动记录所有成功上传的资源，并支持模糊速查及一键复制，数据通过 Docker volume 挂载防丢。

### 使用技术
- **数据库**：SQLite 3 (WAL 极速并发读写模式，无 TCP 延迟，自动挂载持久化)
- **后端**：Python 3.12-slim, FastAPI, HTTPX, Uvicorn, Python-Multipart, Dotenv, Pillow (用于提取并存入图片的真实宽高像素)
- **前端**：HTML5 Semantic tags, Vanilla CSS (Glassmorphism), Vanilla JS (Fetch API, Clipboard API, LocalStorage, Drag-and-drop API)
- **部署**：Docker, Docker Compose (多阶段构建，清华镜像源加速，数据目录外部挂载)

---

# 致谢

- [FastAPI](https://fastapi.tiangolo.com/): 极速高性能 Python 网页框架。
- [Imgur API](https://api.imgur.com/): 全球流行免费图片托管平台 API。
- [vgy.me](https://vgy.me/): 简洁快速的国外免费图片托管服务。
- [Freeimage](https://freeimage.host/): 永久免费的高清图片托管服务。 
- [Catbox](https://catbox.moe/): 简单快速的文件与图片分享平台。