# AI SSH 客户端云端备份对接说明

## 基址

- 官方云端：`https://ssh.scdn.io/backup/api.php`
- 自建云端：`https://你的域名/api.php`（或 `http://IP:端口/api.php`）

客户端应支持配置**自定义 API 基址**；协议与官方完全一致，仅主机不同。

## 自建部署

在 Linux 主机上执行（推荐先下载再运行，以便交互输入域名）：

```bash
curl -fsSL https://ssh.scdn.io/backup/install.sh -o install.sh
sudo bash install.sh
```

脚本会安装 Nginx + PHP-FPM、绑定你输入的域名（或 IP+端口）、生成自建配置，并打印首把 `aiss_*` 与 API 地址。

程序以压缩包形式下载：`https://ssh.scdn.io/backup/selfhost/aissh-selfhost.tar.gz`（脱敏包，不含官方密钥）。更新分发包时在 `backup/selfhost` 执行 `bash pack.sh`。

安装脚本会探测主机网络栈（纯 IPv4 / 双栈 / 纯 IPv6），按需配置 Nginx `listen`；IP 模式下 IPv6 地址会以 `[地址]:端口` 形式展示。

## 流程

1. 官方：在 `https://ssh.scdn.io/backup/key.php` 生成密钥；自建：安装结束已给出密钥，或打开 `/key.php` 再生成
2. 客户端保存密钥到本地安全存储，并填写 API 基址（官方或自建）
3. 内存 JSON → gzip → AES-256-GCM → 打包为 `backup.enc` 上传
4. 恢复时下载 `backup.enc` 解密/解压后合并到本地

## backup.enc 二进制格式（服务端会校验）

```
[5B] 魔数 "AISSH"
[1B] 版本号 = 1
[12B] nonce
[...] 密文 + GCM tag
```

服务端**仅接受**上述 AISSH 加密二进制包，以下一律 400/415 拒绝：

| 校验项 | 规则 |
|--------|------|
| 体积 | ≤ 5MB |
| Content-Type | `application/octet-stream` 或留空；拒绝 `application/json` / `text/*` |
| 明文 | 正文以 `{` / `[` 开头 → 拒绝 |
| 魔数 | 前 5 字节 = `AISSH` |
| 版本 | 第 6 字节 = `1` |
| 长度 | ≥ 20 字节 |
| 鉴权 | Header `X-Backup-Key` |

**不是**「只允许 JSON」；明文 JSON、乱传文件、错误魔数都无法上传。

## 安全要求（客户端必读）

1. **密钥只放 Header** `X-Backup-Key`，不要拼进 URL（避免进访问日志、CDN、Referer）
2. 上传体必须是上述 **AISSH 加密包**，禁止明文 JSON
3. 下载响应已设 `Cache-Control: no-store`

## API

### 上传备份

```
POST {API基址}
Header: X-Backup-Key: aiss_xxxxxxxx   （必须，勿用 ?key=）
Header: X-Backup-Device: windows | android  （可选）
Body: 二进制 backup.enc（AISSH 加密包，≤ 5MB）
Content-Type: application/octet-stream（推荐）
```

成功响应 JSON：

```json
{ "success": true, "size": 12345, "last_modified": "2026-06-09T12:00:00+08:00" }
```

### 下载备份

```
GET {API基址}
Header: X-Backup-Key: aiss_xxxxxxxx
Header: X-Backup-Device: windows  （可选）
```

成功：二进制流 `application/octet-stream`  
无数据：404 JSON

### 查询状态

```
GET {API基址}?action=info
Header: X-Backup-Key: aiss_xxxxxxxx
```

```json
{
  "success": true,
  "has_backup": true,
  "size": 12345,
  "last_modified": "...",
  "created_at": "...",
  "last_device": "windows"
}
```

注意：`action=info` 为只读查询，不会刷新 `last_modified`；响应带 `Cache-Control: no-store` 避免 CDN 缓存旧数据。

## 配置 JSON Schema（加密前）

```json
{
  "schema": 1,
  "exported_at": "ISO8601",
  "device": "windows|android",
  "hosts": [],
  "categories": [],
  "quick_commands": [],
  "ssh_keys": [],
  "ai_settings": {},
  "proxy": {},
  "app_settings": {}
}
```

当前产品同步范围以客户端为准；官网说明为：主机列表、快捷提示词、快捷命令（不含 AI 对话记录与 API Key）。

## 密钥格式

`aiss_` + 48 位小写 hex，共 53 字符。

## 注意

- 密钥须先在网站生成（或自建安装脚本创建），否则 API 返回 404
- 默认 365 天未上传/下载的目录会被服务端自动删除（自建可将 `BACKUP_EXPIRE_DAYS` 设为 0 禁用）
- 密钥泄露等于备份槽位可被读写；请客户端加密后再上传（`enc_*` 不上服务器）