249 lines
6.4 KiB
Markdown
249 lines
6.4 KiB
Markdown
# 更新 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 响应。
|