nebula/docs/ASSET_API.md

Asset API 使用示例

服务器地址: http://localhost:9050

📦 存储架构

可扩展的存储接口设计

项目采用接口化设计，支持多种存储后端：

type Storage interface {
    Save(filename string, content io.Reader) (string, error)
    Delete(path string) error
    GetURL(path string) string
    Exists(path string) bool
}

当前实现：

• ✅ LocalStorage - 本地文件系统存储
• 🔲 OSSStorage - 阿里云 OSS（预留）
• 🔲 S3Storage - AWS S3（预留）

切换存储方式只需：

1. 实现 Storage 接口
2. 在配置中修改 STORAGE_TYPE
3. 无需修改业务代码

配置

通过环境变量配置存储：

# 本地存储（默认）
STORAGE_TYPE=local
STORAGE_BASE_PATH=./uploads
STORAGE_BASE_URL=http://localhost:9050/files

# 未来支持
# STORAGE_TYPE=oss
# STORAGE_TYPE=s3

📝 API 端点

1. 上传文件并创建资源

重要： 这是最常用的方式，上传文件并自动创建记录。

# 使用 curl
curl -X POST http://localhost:9050/api/releases/1/assets/upload \
  -F "file=@path/to/app.exe" \
  -F "platform=windows" \
  -F "arch=amd64"

# PowerShell 示例
$file = "D:\app.exe"
$uri = "http://localhost:9050/api/releases/1/assets/upload"

$form = @{
    file = Get-Item -Path $file
    platform = "windows"
    arch = "amd64"
}

Invoke-RestMethod -Uri $uri -Method Post -Form $form

支持的文件类型：

• Windows: .exe, .msi, .zip
• macOS: .dmg, .pkg, .app
• Linux: .deb, .rpm, .appimage, .tar.gz

响应：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 1,
    "releaseId": 1,
    "platform": "windows",
    "arch": "amd64",
    "url": "http://localhost:9050/files/releases/1/windows-amd64/app.exe",
    "checksum": "sha256哈希值",
    "createdAt": "2026-03-10T12:00:00Z"
  }
}

2. 获取所有资源列表

curl http://localhost:9050/api/assets

# PowerShell
Invoke-RestMethod -Uri "http://localhost:9050/api/assets"

3. 获取指定版本的资源列表

curl http://localhost:9050/api/releases/1/assets

# PowerShell
Invoke-RestMethod -Uri "http://localhost:9050/api/releases/1/assets"

4. 获取单个资源详情

curl http://localhost:9050/api/assets/1

# PowerShell
Invoke-RestMethod -Uri "http://localhost:9050/api/assets/1"

5. 创建资源记录（外部 URL）

如果文件托管在其他地方（如 GitHub Releases、CDN），可以只创建记录：

curl -X POST http://localhost:9050/api/assets \
  -H "Content-Type: application/json" \
  -d '{
    "releaseId": 1,
    "platform": "windows",
    "arch": "amd64",
    "url": "https://github.com/user/repo/releases/download/v1.0.0/app.exe",
    "checksum": "sha256...",
    "signature": "签名数据"
  }'

# PowerShell
$body = @{
    releaseId = 1
    platform = "windows"
    arch = "amd64"
    url = "https://github.com/user/repo/releases/download/v1.0.0/app.exe"
    checksum = "sha256..."
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:9050/api/assets" `
  -Method Post -Body $body -ContentType "application/json"

6. 更新资源信息

curl -X PUT http://localhost:9050/api/assets/1 \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "windows",
    "arch": "arm64",
    "signature": "新签名"
  }'

# PowerShell
$body = @{
    platform = "windows"
    arch = "arm64"
    signature = "新签名"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:9050/api/assets/1" `
  -Method Put -Body $body -ContentType "application/json"

7. 删除资源

注意： 会同时删除文件和数据库记录。

curl -X DELETE http://localhost:9050/api/assets/1

# PowerShell
Invoke-RestMethod -Uri "http://localhost:9050/api/assets/1" -Method Delete

8. 下载资源文件

# 方式1：通过API端点下载
curl http://localhost:9050/api/assets/1/download -o app.exe

# 方式2：直接访问文件URL
curl http://localhost:9050/files/releases/1/windows-amd64/app.exe -o app.exe

# PowerShell - 方式1
Invoke-WebRequest -Uri "http://localhost:9050/api/assets/1/download" -OutFile "app.exe"

# PowerShell - 方式2（推荐，支持断点续传）
Invoke-WebRequest -Uri "http://localhost:9050/files/releases/1/windows-amd64/app.exe" -OutFile "app.exe"

🔄 完整工作流程

# 1. 创建应用
$app = Invoke-RestMethod -Method POST -Uri "http://localhost:9050/api/apps" `
  -ContentType "application/json" `
  -Body '{"id":"my-app","name":"我的应用","description":"测试"}'

# 2. 创建版本
$release = Invoke-RestMethod -Method POST -Uri "http://localhost:9050/api/releases" `
  -ContentType "application/json" `
  -Body '{"appID":"my-app","version":"1.0.0","notes":"初始版本","channel":"stable","pubDate":"2026-03-10T10:00:00Z"}'

# 3. 上传 Windows 版本
$winForm = @{
    file = Get-Item -Path "D:\builds\app-windows.exe"
    platform = "windows"
    arch = "amd64"
}
$winAsset = Invoke-RestMethod -Uri "http://localhost:9050/api/releases/1/assets/upload" `
  -Method Post -Form $winForm

# 4. 上传 macOS 版本
$macForm = @{
    file = Get-Item -Path "D:\builds\app-macos.dmg"
    platform = "darwin"
    arch = "arm64"
}
$macAsset = Invoke-RestMethod -Uri "http://localhost:9050/api/releases/1/assets/upload" `
  -Method Post -Form $macForm

# 5. 上传 Linux 版本
$linuxForm = @{
    file = Get-Item -Path "D:\builds\app-linux"
    platform = "linux"
    arch = "amd64"
}
$linuxAsset = Invoke-RestMethod -Uri "http://localhost:9050/api/releases/1/assets/upload" `
  -Method Post -Form $linuxForm

# 6. 查看该版本的所有资源
$assets = Invoke-RestMethod -Uri "http://localhost:9050/api/releases/1/assets"
$assets.data | Format-Table id, platform, arch, url

📊 API 路由列表

方法	路径	说明
GET	/api/assets	获取所有资源列表
GET	/api/assets/:id	获取单个资源详情
POST	/api/assets	创建资源记录（外部URL）
PUT	/api/assets/:id	更新资源信息
DELETE	/api/assets/:id	删除资源（含文件）
GET	/api/assets/:id/download	下载资源文件
GET	/api/releases/:id/assets	获取版本的资源列表
POST	/api/releases/:id/assets/upload	上传文件并创建资源
GET	/files/*	静态文件访问

🔧 文件存储结构

uploads/
  └── releases/
      └── {releaseID}/
          ├── windows-amd64/
          │   └── app.exe
          ├── darwin-arm64/
          │   └── app.dmg
          └── linux-amd64/
              └── app

🔐 安全特性

1. 文件校验和：自动计算 SHA256，确保文件完整性
2. 文件类型限制：只允许特定扩展名的文件
3. 平台唯一性：同一版本的同一平台+架构只能有一个资源
4. 级联删除：删除资源时自动删除文件

🚀 扩展到云存储

未来要切换到 OSS/S3，只需：

1. 实现新的存储适配器

// internal/storage/oss.go
type OSSStorage struct {
    client *oss.Client
    bucket string
}

func (s *OSSStorage) Save(filename string, content io.Reader) (string, error) {
    // OSS 上传逻辑
}
// ... 实现其他接口方法

2. 在 main.go 中添加分支

switch cfg.Storage.Type {
case "local":
    stor, err = storage.NewLocalStorage(...)
case "oss":
    stor, err = storage.NewOSSStorage(...)
case "s3":
    stor, err = storage.NewS3Storage(...)
}

3. 业务代码无需修改 ✨

所有 Service 和 Handler 代码都基于接口编程，自动支持新的存储方式！