# Miyo 虚拟主机部署 API 参考

Base URL：`https://vhost.xn--yfrs56bche.top`
认证：所有请求带请求头 `Authorization: Bearer <部署令牌>`（令牌以 `miyo_dep_` 开头，面板「账号设置 → AI 部署助手」生成/撤销）。

通用约定：

- 响应都是 JSON；出错时 `{ "error": "原因", "code": "错误码" }`，HTTP 状态码 4xx/5xx。
- 网站根目录 `/var/www/html` 对应 API 里的路径 `/`。
- 限流按令牌计：读类 240 次/10 分钟，写类 120 次/10 分钟，exec 40 次/5 分钟，环境切换 10 次/10 分钟。超限返回 429。
- 所有写操作（写文件、删文件、执行命令、切环境）都会记入主机审计日志。

## 基线

### GET /api/deploy/me

主机全量信息。每次接管会话先调用。

```bash
curl -s -H "Authorization: Bearer $MIYO_TOKEN" https://vhost.xn--yfrs56bche.top/api/deploy/me
```

返回（节选）：`host.id`、`host.status`、`host.plan_name`、`host.runtime`（php/node/python）、`host.runtime_entry`、`host.app_port`、`host.plan_runtimes`（该套餐支持的环境）、`host.domains[]`（绑定域名及状态）、`host.temp_domain`/`host.temp_url`（临时域名）、`host.credentials`（面板用户名、数据库库名/用户/密码——给应用连库用）、`host.disk_used/disk_mb`、`container_stats`、`app_running`。

## 文件管理

路径一律从网站根 `/` 起算。

### GET /api/deploy/files?path=/

列目录。返回 `entries[]`：`name`、`type`（file/dir）、`size`、`mtime`、`mode`。

### POST /api/deploy/files/read `{ "path": "/server.js" }`

读文本文件（限代码/文本类型，单文件 ≤ 2MB）。

### POST /api/deploy/files/write `{ "path": "/app.js", "content": "..." }`

写文本文件（整个 body ≤ 2MB）。目录不存在会报错，先 mkdir。

### POST /api/deploy/files/mkdir `{ "path": "/", "name": "assets" }`

### POST /api/deploy/files/rename `{ "path": "/a.js", "name": "b.js" }`

同目录重命名；传 `"to": "/sub/b.js"` 则移动。

### POST /api/deploy/files/chmod `{ "path": "/run.sh", "mode": "755" }`

### POST /api/deploy/files/delete `{ "path": "/old" }`

删除文件或目录（目录连带内容）。**危险操作，先和用户确认。**

### POST /api/deploy/files/upload?path=/ （multipart/form-data，字段名 file）

上传文件，单个 ≤ 64MB。`curl -F "file=@dist.zip" ".../api/deploy/files/upload?path=/"`。

### POST /api/deploy/files/unzip `{ "path": "/dist.zip" }`

解压到同目录。

## 运行环境与应用

### POST /api/deploy/runtime `{ "runtime": "node", "entry": "app.js" }`

切换运行环境。`runtime` ∈ `php` / `node` / `python`（以 me 里 `plan_runtimes` 为准）；非 PHP 必须带 `entry`（网站根目录下的单个文件名）。切换会重建容器并重启（文件与数据库保留），PHP 之外的环境由入口文件启动常驻进程。

### GET /api/deploy/log?lines=200

应用日志（容器 /tmp/miyo-app.log 的尾部，最多 400 行）。PHP 环境无应用日志。

### POST /api/deploy/app/restart

按当前入口文件重启 Node/Python 应用。

## 命令执行（终端等价物）

### POST /api/deploy/exec `{ "cmd": "...", "timeout_sec": 120 }`

在主机容器内执行 shell 命令，等价于用户打开网页终端敲命令。返回：

```json
{ "ok": true, "exit_code": 0, "stdout": "...", "stderr": "...", "duration_ms": 164, "truncated": false }
```

- 每次执行相互独立（无 cd、无环境变量残留），长命令用 `cd /var/www/html && ...` 连接。
- `timeout_sec` 默认 120，最大 600；输出上限 1MB。
- 容器内可用的运行时：Node 24、Python 3、php、git、zip/unzip、curl、npm/pip（预装常用依赖，缺的可以现场装）。
- 交互式程序（vim、top、需要输入确认的）不适用此接口；需要确认的命令加 `-y` / `-f` 等参数。
- 容器以 root 运行，但注意：网站文件属主是 `www-data`，应用进程也以容器默认用户跑，改文件权限时不要破坏。

## 网页终端（WebSocket）

`wss://vhost.xn--yfrs56bche.top/api/panel/terminal?token=<部署令牌>`（或 `Authorization: Bearer` 头）。
TTY 交互式 bash（Node/Python 环境）或 ash（PHP 环境），需要长驻会话时才用；日常部署用 `exec` 更稳。

## 错误码速查

| code | 含义 | 处理 |
|---|---|---|
| NO_TOKEN / TOKEN_INVALID | 令牌缺失/无效/过期/已撤销 | 让用户到面板重新生成 |
| HOST_INACTIVE | 主机未运行 | 让用户在面板恢复主机 |
| ENTRY_MISSING / ENTRY_INVALID | 入口文件不存在或名字不合法 | 传好文件再切环境 |
| PLAN_LIMIT | 套餐不支持该环境 | 只有 PHP；告知用户升级套餐 |
| 429 | 限流 | 稍等重试 |
