58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
# Previewer 调用契约
|
|
|
|
## 输入
|
|
|
|
```text
|
|
node scripts/serve_file.js FILE [--host IP] [--port PORT] [--ttl SECONDS]
|
|
```
|
|
|
|
- FILE：存在的普通文件；解析为规范绝对路径，服务其父目录。
|
|
- --host：默认 127.0.0.1；支持 IP 或 localhost（等价于 127.0.0.1）。0.0.0.0 表示所有 IPv4 接口。
|
|
- --port：默认 0，自动选择空闲端口；显式端口范围为 1..65535。
|
|
- --ttl：默认 3600 秒，允许 1..2147483；过期关闭该服务。
|
|
|
|
旧的 --mount-path、--local-port、--tailscale-port 参数不再接受。--port 现在仅表示 Node
|
|
静态服务的监听端口。脚本不读取或改写任何外部网络配置。
|
|
|
|
## 输出
|
|
|
|
成功时 stdout 输出单个 JSON，退出码为 0：
|
|
|
|
```json
|
|
{
|
|
"file": "/workspace/preview/index.html",
|
|
"directory": "/workspace/preview",
|
|
"host": "127.0.0.1",
|
|
"port": 43721,
|
|
"pid": 12345,
|
|
"ttl": 3600,
|
|
"expiresAt": "2026-10-19T13:00:00.000Z",
|
|
"url": "http://127.0.0.1:43721/index.html",
|
|
"urls": ["http://127.0.0.1:43721/index.html"],
|
|
"reused": false,
|
|
"stopCommand": "kill -TERM 12345"
|
|
}
|
|
```
|
|
|
|
url 是该服务器的本地可访问入口。绑定所有接口时，urls 还列出系统网络接口的 IPv4 候选链接；
|
|
脚本不判断访问者在哪个网络，也不保证远端可达。路径含空格和中文时 URL 自动编码。
|
|
根路径 / 同样返回输入文件；HTML 的相对 CSS/JS/图片按原目录提供。
|
|
|
|
失败时 stderr 输出单个 JSON，例如：
|
|
|
|
```json
|
|
{ "code": "PORT_IN_USE", "message": "listen EADDRINUSE ..." }
|
|
```
|
|
|
|
错误码包括 ARGUMENT、FILE_INVALID、PORT_IN_USE、START_FAILED、START_TIMEOUT、
|
|
VERIFY_FAILED、BUSY；退出码为 2。成功 JSON 不包含认证探测 token。
|
|
|
|
## 重复调用和生命周期
|
|
|
|
脚本按规范化文件路径、host、请求端口和 ttl 建立服务标识。在系统临时目录内保存当前用户
|
|
的进程记录，启动通过目录锁串行化。调用时会以服务标识和探测 token 验证原进程；仍可用则
|
|
返回 reused: true，且不续期。否则重新启动并更新记录，不凭 PID 盲目停止进程。
|
|
|
|
服务在 ttl 到期或接到 SIGTERM/SIGINT 后停止。重复调用不意味着续期；要改变有效期可使用
|
|
新的 --ttl 参数或先停止原服务。调用方保存一次成功结果，之后直接使用 URL。
|