# cdnserver

**Repository Path**: zhenghexcs/cdnserver

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# CDNServer

## 简介

CDNServer 是一个轻量级的 CDN 资源缓存节点。客户端请求会被转发到本服务，本服务再去上游 HTTPS 拉取资源并缓存到本地；同一资源的并发请求只会触发一次回源下载，并支持下载中直接对外提供 HTTP 响应。

## 工作流程

1. 客户端发起请求（通常由前置 Nginx 转发或劫持到本服务）。
2. 根据 `Host + RequestURI` 组装上游 HTTPS 地址。
3. 若缓存已存在，直接 `ServeFile`。
4. 若缓存不存在，启动下载任务，流式写入临时文件并同时对外输出数据流。
5. 下载完成后将临时文件重命名为缓存文件，后续请求直接命中缓存。

## 主要特性

- **并发去重**：同一资源只会建立一个下载任务，其它请求复用任务流。
- **边下边传**：下载未完成时即可响应客户端。
- **断点续传**：支持单区间 `Range` 请求，下载中也可正确处理。
- **缓存隔离**：缓存路径包含 query 的哈希，避免不同参数相互覆盖。
- **自动清理**：按最后访问时间删除过期文件。

## 快速开始

### 环境要求

- Go 1.16+

### 编译

Windows:
```bash
./build.bat
```

Linux/macOS:
```bash
go build -o cdnserver main.go
```

### 运行

```bash
./cdnserver
```

服务默认监听 `:80`。

## 配置参数

启动参数通过命令行指定：

- `-c` / `CACHE-DIR`：缓存目录，默认 `./res`
- `-d` / `CLEANUP-DAYS`：缓存过期天数，默认 `30`

示例：
```bash
./cdnserver -c ./res -d 30
```

## Range 行为说明

- 支持单区间 `Range` 请求（`bytes=start-end`、`bytes=start-`、`bytes=-suffix`）。
- 对非法 Range 返回 `416`，并尽可能带上 `Content-Range: bytes */<total>`。
- 下载中会按范围长度严格输出，避免超发。

## 缓存目录结构

缓存路径规则：
```
<cacheDir>/<host>/<path>__q<queryHash>
```
其中 `__q<queryHash>` 仅在存在 query 时追加。

## 回归脚本（Range）

提供自动断言脚本：
```
scripts/range-regression.ps1
```

用法示例：
```powershell
.
scripts\range-regression.ps1 -TargetHost "example.com" -TargetPath "/static/file.bin"
```

脚本会输出用例通过/失败并返回对应退出码，适合本地回归或 CI。

## 说明

- 仅回源 HTTPS（前置 Nginx 可进一步做域名/路径限制）。
- 该服务面向静态资源缓存，不处理动态业务逻辑。