# Mirage

**Repository Path**: exyone/Mirage

## Basic Information

- **Project Name**: Mirage
- **Description**: Mirage —— 一个基于ASP.NET运行的图床软件
此仓库为Codeberg的镜像仓库
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mirage - 图片托管服务

<p align="center">
  <img src="https://img.shields.io/badge/.NET-8.0-512BD4?style=flat-square&logo=dotnet" alt=".NET 8.0">
  <img src="https://img.shields.io/badge/License-Apache%202.0%20%7C%20BSD-blue?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/Author-EXYONE%20Dev-green?style=flat-square" alt="Author">
</p>

一个基于 ASP.NET Core 8.0 构建的高性能图片托管服务，支持多种云存储后端。

## 功能特性

- **多存储后端支持**：本地存储、AWS S3、Cloudflare R2、阿里云 OSS
- **图片处理**：缩放、裁剪、水印、格式转换（基于 ImageSharp）
- **上传方式**：单文件、多文件、分片上传（断点续传）
- **访问控制**：防盗链、IP 限流、时间戳签名 URL
- **认证授权**：JWT Token + API Key 双重认证、RBAC 权限系统
- **数据库支持**：SQLite（开发）、MariaDB/MySQL（生产）
- **缓存系统**：内存缓存 + Redis 分布式缓存
- **安装向导**：可视化安装配置、开发模式支持

## 项目结构

```
Mirage/
├── src/
│   ├── Mirage.Api/           # 展示层 - API 控制器和中间件
│   ├── Mirage.Application/   # 业务层 - 服务和业务逻辑
│   ├── Mirage.Domain/        # 领域层 - 实体、接口、枚举
│   └── Mirage.Infrastructure/# 基础设施层 - 数据库、存储实现
├── front-end/                # 前端管理界面
├── API_DOCUMENTATION.md      # API 接口文档
├── BACKEND_TODO.md           # 待开发功能清单
├── FUNCTIONALITY_REPORT.md   # 功能状态报告
├── IMPROVEMENT_ROADMAP.md    # 改进路线图
└── Mirage.sln
```

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 运行时 | .NET | 8.0 |
| Web框架 | ASP.NET Core | 8.0 |
| ORM | Entity Framework Core | 8.0 |
| 图片处理 | ImageSharp | 3.x |
| 认证 | JWT Bearer | 8.0 |
| 缓存 | Redis (StackExchange) | 2.x |
| 日志 | Serilog | 4.x |
| API文档 | Swagger/OpenAPI | 6.x |

## 快速开始

### 环境要求

- .NET 8.0 SDK
- SQLite（开发环境）或 MariaDB（生产环境）
- Redis（可选，用于分布式缓存）

### 运行项目

```bash
git clone https://codeberg.org/exyone/Mirage.git
cd Mirage
dotnet restore
cd src/Mirage.Api
dotnet run
```

首次运行将自动进入安装向导界面。

### 开发模式

开发模式下会自动创建默认账户：
- 用户名：`dev`
- 密码：`dev123456`

## 文档导航

| 文档 | 职责 | 内容说明 |
|------|------|----------|
| [API_DOCUMENTATION.md](API_DOCUMENTATION.md) | API接口文档 | 已实现的所有API端点、请求/响应格式、认证方式、错误码 |
| [BACKEND_TODO.md](BACKEND_TODO.md) | 开发任务清单 | 待开发功能列表、优先级排序、任务状态跟踪 |
| [FUNCTIONALITY_REPORT.md](FUNCTIONALITY_REPORT.md) | 功能状态报告 | 当前版本功能完成度、模块状态、技术债务 |
| [IMPROVEMENT_ROADMAP.md](IMPROVEMENT_ROADMAP.md) | 改进路线图 | 未来版本规划、功能增强方向、技术演进计划 |

## 开发进度

### 已完成 ✅

- [x] 项目架构设计（四层架构）
- [x] 数据库模型设计
- [x] 存储提供者（本地/S3/R2/OSS）
- [x] 图片处理服务
- [x] 上传服务（单文件/多文件/分片）
- [x] 访问控制（防盗链/IP限流）
- [x] 认证授权（JWT + API Key + RBAC）
- [x] 缓存系统（内存 + Redis）
- [x] 安装向导和开发模式
- [x] 用户资料管理 API
- [x] 图片批量操作 API
- [x] 相册管理增强

### 进行中 🚧

- [ ] 缩略图自动生成
- [ ] 回收站功能
- [ ] 标签系统
- [ ] 统计分析 API

## 许可证

本项目采用双重许可证：

- **后端代码**：Apache License 2.0
- **前端界面**：BSD 3-Clause License

详见 [LICENSE](LICENSE) 文件。

## 作者

**exyone** - 项目负责人
**智谱清言 GLM** - AI 辅助开发

---

<p align="center">
  Made with ❤️ by <a href="https://www.exyone.me/">exyone</a> and <a href="https://www.zhipuai.cn/">智谱清言 GLM</a>
</p>