[feat] better installer + changelog test version switch + better video config view
This commit is contained in:
248
UPDATE_API.md
Normal file
248
UPDATE_API.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# 更新 API 文档
|
||||
|
||||
本文档说明 CS工具箱 的更新检查接口格式和配置方法。
|
||||
|
||||
## 功能概述
|
||||
|
||||
CS工具箱 支持两种更新检查方式：
|
||||
1. **自定义更新服务器**（优先）
|
||||
2. **GitHub Release**（作为备用方案）
|
||||
|
||||
## 配置方法
|
||||
|
||||
### 方式一：环境变量（推荐）
|
||||
|
||||
在项目根目录创建 `.env.local` 文件：
|
||||
|
||||
```env
|
||||
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` 中修改：
|
||||
|
||||
```typescript
|
||||
const customEndpoint = "https://your-server.com/api/update/check"
|
||||
const githubRepo = "your-username/your-repo"
|
||||
```
|
||||
|
||||
## 自定义更新服务器接口格式
|
||||
|
||||
### 请求
|
||||
|
||||
- **方法**: GET
|
||||
- **URL**: 你配置的 `customEndpoint`
|
||||
- **Headers**: 无特殊要求
|
||||
|
||||
### 响应格式
|
||||
|
||||
服务器应返回 JSON 格式的更新信息：
|
||||
|
||||
```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，可以简化响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.0.7",
|
||||
"notes": "更新说明",
|
||||
"download_url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7.exe"
|
||||
}
|
||||
```
|
||||
|
||||
## GitHub Release 格式
|
||||
|
||||
### 仓库要求
|
||||
|
||||
1. 在 GitHub 上创建 Release
|
||||
2. Release 标签格式：`v0.0.7` 或 `0.0.7`（系统会自动移除 `v` 前缀）
|
||||
3. Release 标题和说明会作为更新说明显示
|
||||
|
||||
### 资源文件命名
|
||||
|
||||
系统会自动识别以下格式的安装包：
|
||||
|
||||
**Windows:**
|
||||
- `.exe`
|
||||
- `.msi`
|
||||
- 文件名包含 `windows` 和 `x86_64`
|
||||
|
||||
**macOS:**
|
||||
- `.dmg`
|
||||
- 文件名包含 `darwin` 和架构标识（`x86_64` 或 `aarch64`）
|
||||
|
||||
**Linux:**
|
||||
- `.deb`
|
||||
- `.rpm`
|
||||
- `.AppImage`
|
||||
- 文件名包含 `linux` 和 `x86_64`
|
||||
|
||||
### 推荐命名格式
|
||||
|
||||
```
|
||||
cstb-{version}-{platform}-{arch}.{ext}
|
||||
```
|
||||
|
||||
例如：
|
||||
- `cstb-0.0.7-windows-x86_64.exe`
|
||||
- `cstb-0.0.7-darwin-x86_64.dmg`
|
||||
- `cstb-0.0.7-darwin-aarch64.dmg`
|
||||
- `cstb-0.0.7-linux-x86_64.AppImage`
|
||||
|
||||
## 版本比较逻辑
|
||||
|
||||
系统使用简单的版本号比较：
|
||||
- 按 `.`、`-`、`_` 分割版本号
|
||||
- 逐段比较数字部分
|
||||
- 如果新版本号大于当前版本，则提示更新
|
||||
|
||||
例如：
|
||||
- `0.0.7` > `0.0.6` ✓
|
||||
- `0.0.6-beta.4` 与 `0.0.6` 视为相等（简单比较）
|
||||
|
||||
## 更新流程
|
||||
|
||||
1. **检查更新**：用户点击"检查更新"按钮
|
||||
2. **下载更新**：如果有新版本，用户确认后开始下载
|
||||
3. **安装更新**：
|
||||
- Windows: 自动运行 NSIS 安装程序（静默模式）
|
||||
- macOS: 打开 DMG 文件（需用户手动安装）
|
||||
- Linux: 根据文件类型执行相应安装命令
|
||||
|
||||
## 示例服务器实现
|
||||
|
||||
### Node.js/Express 示例
|
||||
|
||||
```javascript
|
||||
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 示例
|
||||
|
||||
```python
|
||||
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"
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **HTTPS**: 建议使用 HTTPS 协议以确保安全
|
||||
2. **CORS**: 如果从浏览器访问，需要配置 CORS 头
|
||||
3. **超时**: 请求超时时间为 10 秒
|
||||
4. **下载超时**: 下载超时时间为 5 分钟
|
||||
5. **缓存**: 系统不会缓存更新信息，每次检查都会请求最新数据
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 自定义服务器检查失败
|
||||
|
||||
1. 检查服务器是否可访问
|
||||
2. 检查响应格式是否正确
|
||||
3. 检查 HTTP 状态码是否为 200
|
||||
4. 查看应用日志中的错误信息
|
||||
|
||||
### GitHub Release 检查失败
|
||||
|
||||
1. 确认仓库名称格式正确（`owner/repo`）
|
||||
2. 确认仓库是公开的
|
||||
3. 确认已创建 Release
|
||||
4. 确认 Release 中有适合当前平台的资源文件
|
||||
|
||||
### 下载失败
|
||||
|
||||
1. 检查下载链接是否有效
|
||||
2. 检查网络连接
|
||||
3. 检查磁盘空间是否充足
|
||||
4. 检查文件权限
|
||||
|
||||
## 测试
|
||||
|
||||
可以使用以下 curl 命令测试自定义服务器：
|
||||
|
||||
```bash
|
||||
curl https://your-server.com/api/update/check
|
||||
```
|
||||
|
||||
应该返回符合格式的 JSON 响应。
|
||||
Reference in New Issue
Block a user