# 在线更新

服务器可从 GitHub Releases 检查最新版本并在线下载应用，替换自身二进制后自动重启服务。

## 版本约定

`Cargo.toml` 使用 semver 构建号写法（如 `1.4.2-4`），运行时 / API 展示统一转换为下划线写法（如 `1.4.2_4`）；解析时两种写法等价。版本解析支持 `1.4.2`、`1.4.2_1`、`1.4.2-1`、`v1.4.2`、`V1.4.2_1` 等格式。

## 检查更新

`GET /api/update/check` 请求 GitHub Releases API（匿名限流 60 次/小时/IP），返回：

| 字段 | 说明 |
|---|---|
| `current_version` | 当前版本 |
| `latest_version` | 最新发行版 tag |
| `latest_name` | release 标题 |
| `update_available` | 是否存在更新（语义版本比较） |
| `release_notes` | release 说明正文（Markdown） |
| `release_url` | release 网页地址 |
| `download_url` | linux x86_64 资产直链（无匹配资产时为 `null`） |

网络 / 解析失败时不抛 500，返回 `current_version` 与 `error`，前端仍可展示当前版本。

## 应用更新

`POST /api/update/apply`，请求体 `download_url`（GitHub 发行版资产直链）。

**安全白名单**：只允许从以下域名下载，防止服务端被灌入任意二进制：

- `https://github.com/`
- `https://objects.githubusercontent.com/`
- `https://release-assets.githubusercontent.com/`

### 替换流程（仅 Linux 实际生效）

1. 下载新二进制到 `<exe>.new`（300 秒超时）；
2. `chmod 755` 赋予执行权限；
3. 旧文件改名 `<exe>.bak`（Linux 允许重命名正在运行的可执行文件）；
4. `.new` 原子 `rename` 为当前路径；
5. `sleep 1 && systemctl restart astral-server`（`nohup` 脱离父进程执行，确保 HTTP 响应已发出）。

Windows 等非 Unix 平台暂不支持自动重启。

## 相关页面

- [REST API 参考](rest-api.md)
- [项目概述](introduction.md)
- [从源码编译](build-from-source.md)