# ByteNexus

**Repository Path**: llakcs/byte-nexus

## Basic Information

- **Project Name**: ByteNexus
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ByteNexus

一个基于 Go + Gin 构建的轻量级对象存储服务，支持普通上传、分段上传（Multipart Upload）、SSE 加密、访问控制与并发限流。

## 功能特性

### 文件操作

| 功能 | 接口 | 说明 |
|------|------|------|
| 普通上传 | `POST /api/open/file/upload` | 单次上传，默认限制 64MB |
| 文件下载 | `GET /api/open/file/download` | 支持 SSE 自动解密 |
| 文件删除 | `DELETE /api/open/file/delete` | 物理删除 + 索引清理 |
| 文件列表 | `GET /api/open/file/list` | 按前缀 + 分页标记查询 |

### 分段上传（Multipart Upload）

| 步骤 | 接口 | 说明 |
|------|------|------|
| 初始化 | `POST /api/open/file/multipart/init` | 返回 `uploadId` |
| 上传分段 | `PUT /api/open/file/multipart/part` | 单分段最大 5GB（可配） |
| 合并完成 | `POST /api/open/file/multipart/complete` | 合并分段 + 索引入库 |
| 取消上传 | `DELETE /api/open/file/multipart/abort` | 清理临时文件 |

> **大文件上传判断**：当 `Content-Length` 超过 `multipartThreshold`（默认 100MB）时，`POST /upload` 会返回错误码 `10018`，提示客户端改用分段上传。

### 安全特性

- **AccessKey 鉴权**：Open API 统一使用 AppID/AppSecret
- **SSE 加密**：AES-256-GCM 流式加密，支持上传加密、下载自动解密
- **并发限流**：CAS 原子自旋锁 + 队列，默认最大并发 100
- **路径穿越防护**：`SanitizeObjectKey()` 过滤 `..` 和绝对路径
- **JWT 鉴权**：管理后台路由使用 JWT + RBAC 权限控制

### 管理后台

- 用户管理（CRUD）
- 角色管理（RBAC）
- 策略管理（Policy）
- 存储桶管理（Bucket）
- AccessKey 管理
- 审计日志

## 技术栈

- **语言**：Go 1.21+
- **HTTP 框架**：[Gin](https://github.com/gin-gonic/gin)
- **数据库**：MySQL（GORM）
- **配置**：Viper（支持 `${ENV:default}` 占位符）
- **日志**：Zap + Lumberjack（日志轮转）
- **加密**：AES-256-GCM（SSE）、SM4

## 项目结构

```
ByteNexus/
├── api/            # HTTP 处理器（路由 Handler）
├── config/         # 配置加载与管理
├── constant/       # 常量定义
├── ds/             # 数据源（数据库连接）
├── encrypt/        # 加密模块（SSE、SM4）
├── frontend/       # 管理后台前端（原生 HTML + JS）
├── log/            # 日志模块（Zap）
├── middleware/      # 中间件（限流、Body 限制、审计）
├── resources/      # 嵌入资源（SQL 脚本、配置文件模板）
├── server/         # HTTP 服务启动与路由注册
├── service/        # 业务逻辑层
├── utils/          # 工具函数
├── application.go  # 程序入口
└── init.go         # 数据库初始化
```

## 快速开始

### 1. 配置

编辑 `byteNexus/config/byteNexus.yml`：

```yaml
server:
  port: "8080"
  readTimeout: 300s
  writeTimeout: 600s

database:
  driver: mysql
  dsn: "user:password@tcp(127.0.0.1:3306)/bytenexus?charset=utf8mb4&parseTime=True"

upload:
  maxBodySize: 67108864          # 普通上传限制 64MB
  multipartThreshold: 104857600  # 超过 100MB 提示走分段上传
  partMaxSize: 5368709120        # 单个分段最大 5GB

sseKey: ""                       # AES SSE 加密密钥，空则不加密
```

### 2. 运行

```bash
go run .
```

### 3. 访问

- 管理后台：`http://localhost:8080/admin/`
- 健康检查：`http://localhost:8080/monitor/health/check/ping`

## 分段上传流程图

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: POST /upload (Content-Length > 100MB)
    Server-->>Client: 413 | 10018 - file too large, use multipart

    Client->>Server: POST /multipart/init {objectKey}
    Server-->>Client: {uploadId, objectKey}

    loop 上传每个分段
        Client->>Server: PUT /multipart/part?uploadId=xxx&partNumber=N
        Server-->>Client: {partNumber, size}
    end

    Client->>Server: POST /multipart/complete {uploadId, parts}
    Server-->>Client: {objectKey, fileSize, eTag}
```

## License

MIT