# docker-oss

**Repository Path**: orange_sunset/docker-oss

## Basic Information

- **Project Name**: docker-oss
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-20
- **Last Updated**: 2025-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dockerized 图像服务 (类 OSS)

本项目提供了一个 Docker 化的 Node.js 图像服务，用于图像上传、处理和存储，并使用 MongoDB 管理元数据。它旨在作为一个简单的图像对象存储服务 (OSS) 来运行。

## 功能特性

- **图像上传**: 支持通过 `multipart/form-data` 进行文件上传，以及从 URL 获取图像。
- **重复检测**: 使用 SHA256 校验和来避免存储重复图像。
- **即时图像处理**: 利用 `sharp` 库，通过查询参数实现图像的尺寸调整、质量修改和格式转换。
- **变体缓存**: 经过处理的图像变体会被缓存到磁盘，以加快后续访问速度。
- **MongoDB 元数据存储**: 存储图像元数据，包括原始文件名、大小、MIME 类型和使用引用。
- **自动化清理**: 定时任务（cron job）会定期删除临时和未使用的图像，以释放存储空间。
- **Docker 化**: 使用 `docker-compose` 完全容器化，便于设置和部署。

## 前提条件

- [Docker](https://www.docker.com/get-started)
- [Docker Compose](https://docs.docker.com/compose/install/)

## 快速开始

1.  **构建并运行服务：**

    ```bash
    docker-compose up --build
    ```

    此命令将构建 Node.js 镜像，拉取 MongoDB 镜像，并启动这两个服务。应用程序将在 `http://localhost:3000` 上可用。

2.  **本地安装依赖 (用于开发)：**

    如果您想在 Docker 外部运行服务器进行开发，您需要安装 Node.js 和 npm。

    ```bash
    npm install
    ```

    然后您可以通过以下命令运行服务器：

    ```bash
    npm run dev
    ```

    *注意：您需要一个正在运行的 MongoDB 实例，并相应地设置 `MONGO_URI` 环境变量。*

## API 端点

- `POST /upload`
  - 上传图像。使用 `multipart/form-data` 请求，其中包含一个 `file` 字段，或者一个包含 `url` 字段的 JSON 请求体。
  - **示例 (使用 form-data 的 curl 命令)：**
    ```bash
    curl -X POST -F "file=@/path/to/your/image.jpg" http://localhost:3000/upload
    ```
  - **示例 (使用 URL 的 curl 命令)：**
    ```bash
    curl -X POST -H "Content-Type: application/json" -d '{"url": "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"}' http://localhost:3000/upload
    ```

- `GET /images/:id`
  - 获取图像。支持通过查询参数进行图像处理。
  - **示例 (原始图像)：**
    `http://localhost:3000/images/635f...`
  - **示例 (处理后的图像 - 200px 宽度，80% 质量，webp 格式)：**
    `http://localhost:3000/images/635f...?w=200&q=80&format=webp`

- `POST /images/:id/mark-used`
  - 将图像标记为正在使用，以防止其被清理。在请求体中包含一个引用。
  - **示例 (curl 命令)：**
    ```bash
    curl -X POST -H "Content-Type: application/json" -d '{"ref": "user-profile-123"}' http://localhost:3000/images/635f.../mark-used
    ```

- `DELETE /images/:id`
  - 软删除图像，将其状态标记为 `deleted`。

- `GET /healthz`
  - 健康检查端点，用于验证服务器及其与 MongoDB 的连接状态。

## 清理任务

清理任务计划在每天凌晨 2:00 运行。您也可以手动触发它：

```bash
docker-compose exec app npm run cleanup
```