cstb/cstb-next

Fork 0

Files

purp1e 41008cf13c [feat] better installer + changelog test version switch + better video config view

2025-11-05 11:19:43 +08:00

6.4 KiB

Raw Permalink Blame History

更新 API 文档

本文档说明 CS工具箱的更新检查接口格式和配置方法。

功能概述

CS工具箱支持两种更新检查方式：

自定义更新服务器（优先）
GitHub Release（作为备用方案）

配置方法

方式一：环境变量（推荐）

在项目根目录创建 .env.local 文件：

NEXT_PUBLIC_UPDATE_ENDPOINT=https://your-server.com/api/update/check
NEXT_PUBLIC_GITHUB_REPO=your-username/your-repo

方式二：代码中配置

在 src/app/(main)/preference/general/page.tsx 中修改：

const customEndpoint = "https://your-server.com/api/update/check"
const githubRepo = "your-username/your-repo"

自定义更新服务器接口格式

请求

方法: GET
URL: 你配置的 customEndpoint
Headers: 无特殊要求

响应格式

服务器应返回 JSON 格式的更新信息：

{
  "version": "0.0.7",
  "notes": "## 更新内容\n\n- 修复了已知问题\n- 添加了新功能",
  "pub_date": "2025-01-15T10:00:00Z",
  "download_url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-x86_64.exe",
  "signature": "可选：安装包签名",
  "platforms": {
    "windows-x86_64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-windows-x86_64.exe",
      "signature": "可选：Windows 安装包签名"
    },
    "darwin-x86_64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-darwin-x86_64.dmg",
      "signature": "可选：macOS x86_64 安装包签名"
    },
    "darwin-aarch64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-darwin-aarch64.dmg",
      "signature": "可选：macOS Apple Silicon 安装包签名"
    },
    "linux-x86_64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-linux-x86_64.AppImage",
      "signature": "可选：Linux 安装包签名"
    }
  }
}

字段说明

字段	类型	必填	说明
`version`	string	是	新版本号，格式：`主版本.次版本.修订版本`（如 `0.0.7`）
`notes`	string	否	更新说明，支持 Markdown 格式
`pub_date`	string	否	发布时间，ISO 8601 格式（如 `2025-01-15T10:00:00Z`）
`download_url`	string	是	默认下载链接（如果未指定平台特定链接时使用）
`signature`	string	否	默认安装包签名
`platforms`	object	否	平台特定的下载信息

平台特定配置

如果提供了 platforms 对象，系统会优先使用当前平台的特定链接。支持的平台标识：

windows-x86_64: Windows 64位
darwin-x86_64: macOS Intel
darwin-aarch64: macOS Apple Silicon
linux-x86_64: Linux 64位

简化格式（仅 Windows）

如果你只需要支持 Windows，可以简化响应：

{
  "version": "0.0.7",
  "notes": "更新说明",
  "download_url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7.exe"
}

GitHub Release 格式

仓库要求

在 GitHub 上创建 Release
Release 标签格式：v0.0.7 或 0.0.7（系统会自动移除 v 前缀）
Release 标题和说明会作为更新说明显示

资源文件命名

系统会自动识别以下格式的安装包：

Windows:

.exe
.msi
文件名包含 windows 和 x86_64

macOS:

.dmg
文件名包含 darwin 和架构标识（x86_64 或 aarch64）

Linux:

.deb
.rpm
.AppImage
文件名包含 linux 和 x86_64

版本比较逻辑

系统使用简单的版本号比较：

按 .、-、_ 分割版本号
逐段比较数字部分
如果新版本号大于当前版本，则提示更新

例如：

0.0.7 > 0.0.6 ✓
0.0.6-beta.4 与 0.0.6 视为相等（简单比较）

更新流程

检查更新：用户点击"检查更新"按钮
下载更新：如果有新版本，用户确认后开始下载
安装更新：
- Windows: 自动运行 NSIS 安装程序（静默模式）
- macOS: 打开 DMG 文件（需用户手动安装）
- Linux: 根据文件类型执行相应安装命令

示例服务器实现

Node.js/Express 示例

app.get('/api/update/check', (req, res) => {
  const platform = req.headers['user-agent'] || '';
  
  const updateInfo = {
    version: "0.0.7",
    notes: "## 更新内容\n\n- 修复了已知问题",
    pub_date: new Date().toISOString(),
    download_url: "https://your-server.com/releases/v0.0.7/cstb-0.0.7.exe",
    platforms: {
      "windows-x86_64": {
        url: "https://your-server.com/releases/v0.0.7/cstb-0.0.7-windows-x86_64.exe"
      }
    }
  };
  
  res.json(updateInfo);
});

Python/Flask 示例

from flask import Flask, jsonify
from datetime import datetime

app = Flask(__name__)

@app.route('/api/update/check')
def check_update():
    return jsonify({
        "version": "0.0.7",
        "notes": "## 更新内容\n\n- 修复了已知问题",
        "pub_date": datetime.now().isoformat() + "Z",
        "download_url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7.exe",
        "platforms": {
            "windows-x86_64": {
                "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-windows-x86_64.exe"
            }
        }
    })

注意事项

HTTPS: 建议使用 HTTPS 协议以确保安全
CORS: 如果从浏览器访问，需要配置 CORS 头
超时: 请求超时时间为 10 秒
下载超时: 下载超时时间为 5 分钟
缓存: 系统不会缓存更新信息，每次检查都会请求最新数据

故障排查

自定义服务器检查失败

检查服务器是否可访问
检查响应格式是否正确
检查 HTTP 状态码是否为 200
查看应用日志中的错误信息

GitHub Release 检查失败

确认仓库名称格式正确（owner/repo）
确认仓库是公开的
确认已创建 Release
确认 Release 中有适合当前平台的资源文件

下载失败

检查下载链接是否有效
检查网络连接
检查磁盘空间是否充足
检查文件权限

测试

可以使用以下 curl 命令测试自定义服务器：

curl https://your-server.com/api/update/check

应该返回符合格式的 JSON 响应。

6.4 KiB Raw Permalink Blame History Unescape Escape