feat: add graceful shutdown endpoint and cli service management
- Add /shutdown endpoint for graceful server shutdown - Add 'aha ps' command to list running services - Add comprehensive API documentation for shutdown endpoint - Enhance CLI with --allow-remote-shutdown flag - Implement process management module with service discovery - Add graceful shutdown handling for Ctrl+C signals
This commit is contained in:
XiaoYang
+61
@@ -438,6 +438,67 @@ Returns the processed image in base64 PNG format.
|
||||
|
||||
- `rmbg2.0`
|
||||
|
||||
### Graceful Shutdown
|
||||
|
||||
Gracefully shut down the AHA server. This endpoint initiates a graceful shutdown process that:
|
||||
1. Stops accepting new connections
|
||||
2. Waits for existing requests to complete (up to 1 second)
|
||||
3. Cleans up PID files
|
||||
4. Exits the process
|
||||
|
||||
#### Endpoint
|
||||
```
|
||||
POST /shutdown
|
||||
```
|
||||
|
||||
#### Request Body
|
||||
|
||||
None (empty request)
|
||||
|
||||
#### Response
|
||||
|
||||
**Success (HTTP 200):**
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Shutting down..."
|
||||
}
|
||||
```
|
||||
|
||||
**Forbidden (HTTP 403):**
|
||||
|
||||
When remote shutdown is not allowed:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Remote shutdown not allowed. Use --allow-remote-shutdown flag to enable (not recommended)."
|
||||
}
|
||||
```
|
||||
|
||||
#### Security
|
||||
|
||||
By default, the shutdown endpoint only allows requests from localhost (127.0.0.1). To enable remote shutdown, start the server with the `--allow-remote-shutdown` flag:
|
||||
|
||||
```bash
|
||||
aha serv -m qwen3-0.6b --allow-remote-shutdown
|
||||
```
|
||||
|
||||
**Warning:** Enabling remote shutdown is not recommended for production use unless properly secured.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:10100/shutdown
|
||||
```
|
||||
|
||||
#### Logging
|
||||
|
||||
All shutdown requests are logged to stderr with the format:
|
||||
|
||||
```
|
||||
[SHUTDOWN] Shutdown requested (remote_allowed: false)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Codes
|
||||
|
||||
@@ -438,6 +438,67 @@ curl http://127.0.0.1:10100/images/remove_background \
|
||||
|
||||
- `rmbg2.0`
|
||||
|
||||
### 优雅关机
|
||||
|
||||
优雅地关闭 AHA 服务器。此端点启动优雅关闭流程：
|
||||
1. 停止接受新连接
|
||||
2. 等待现有请求完成（最多 1 秒）
|
||||
3. 清理 PID 文件
|
||||
4. 退出进程
|
||||
|
||||
#### 端点
|
||||
```
|
||||
POST /shutdown
|
||||
```
|
||||
|
||||
#### 请求体
|
||||
|
||||
无（空请求）
|
||||
|
||||
#### 响应
|
||||
|
||||
**成功 (HTTP 200):**
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Shutting down..."
|
||||
}
|
||||
```
|
||||
|
||||
**禁止访问 (HTTP 403):**
|
||||
|
||||
当不允许远程关闭时：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Remote shutdown not allowed. Use --allow-remote-shutdown flag to enable (not recommended)."
|
||||
}
|
||||
```
|
||||
|
||||
#### 安全性
|
||||
|
||||
默认情况下，关机端点仅允许来自 localhost (127.0.0.1) 的请求。要启用远程关闭，请使用 `--allow-remote-shutdown` 标志启动服务器：
|
||||
|
||||
```bash
|
||||
aha serv -m qwen3-0.6b --allow-remote-shutdown
|
||||
```
|
||||
|
||||
**警告：** 除非有适当的安全措施，否则不建议在生产环境中启用远程关闭。
|
||||
|
||||
#### 示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:10100/shutdown
|
||||
```
|
||||
|
||||
#### 日志记录
|
||||
|
||||
所有关机请求都会记录到 stderr，格式如下：
|
||||
|
||||
```
|
||||
[SHUTDOWN] Shutdown requested (remote_allowed: false)
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 错误代码
|
||||
|
||||
+60
-5
@@ -113,11 +113,11 @@ aha run -m qwen3asr-0.6b -i "audio.wav" --weight-path /path/to/model
|
||||
|
||||
### serv - Start service
|
||||
|
||||
Start HTTP service only, without downloading models. Must specify local model path via `--weight-path`.
|
||||
Start HTTP service with a model. The `--weight-path` is optional - if not specified, it defaults to `~/.aha/{model_id}`.
|
||||
|
||||
**Syntax:**
|
||||
```bash
|
||||
aha serv [OPTIONS] --model <MODEL> --weight-path <WEIGHT_PATH>
|
||||
aha serv [OPTIONS] --model <MODEL> [--weight-path <WEIGHT_PATH>]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
@@ -127,21 +127,69 @@ aha serv [OPTIONS] --model <MODEL> --weight-path <WEIGHT_PATH>
|
||||
| `-a, --address <ADDRESS>` | Service listen address | 127.0.0.1 |
|
||||
| `-p, --port <PORT>` | Service listen port | 10100 |
|
||||
| `-m, --model <MODEL>` | Model type (required) | - |
|
||||
| `--weight-path <WEIGHT_PATH>` | Local model weight path (required) | - |
|
||||
| `--weight-path <WEIGHT_PATH>` | Local model weight path (optional) | ~/.aha/{model_id} |
|
||||
| `--allow-remote-shutdown` | Allow remote shutdown requests (not recommended) | false |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Start service with default model path (~/.aha/{model_id})
|
||||
aha serv -m qwen3vl-2b
|
||||
|
||||
# Start service with local model
|
||||
aha serv -m qwen3vl-2b --weight-path /path/to/model
|
||||
|
||||
# Start with specified port
|
||||
aha serv -m qwen3vl-2b --weight-path /path/to/model -p 8080
|
||||
aha serv -m qwen3vl-2b -p 8080
|
||||
|
||||
# Specify listen address
|
||||
aha serv -m qwen3vl-2b --weight-path /path/to/model -a 0.0.0.0
|
||||
aha serv -m qwen3vl-2b -a 0.0.0.0
|
||||
|
||||
# Enable remote shutdown (not recommended for production)
|
||||
aha serv -m qwen3vl-2b --allow-remote-shutdown
|
||||
```
|
||||
|
||||
### ps - List running services
|
||||
|
||||
List all currently running AHA services with their process IDs, ports, and status.
|
||||
|
||||
**Syntax:**
|
||||
```bash
|
||||
aha ps [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `-c, --compact` | Compact output format (show service IDs only) | false |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# List all running services (table format)
|
||||
aha ps
|
||||
|
||||
# Compact output (service IDs only)
|
||||
aha ps -c
|
||||
```
|
||||
|
||||
**Output Format:**
|
||||
|
||||
```
|
||||
Service ID PID Model Port Address Status
|
||||
-------------------------------------------------------------------------------------
|
||||
56860@10100 56860 N/A 10100 127.0.0.1 Running
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `Service ID`: Unique identifier in format `pid@port`
|
||||
- `PID`: Process ID
|
||||
- `Model`: Model name (N/A if not detected)
|
||||
- `Port`: Service port number
|
||||
- `Address`: Service listen address
|
||||
- `Status`: Service status (Running, Stopping, Unknown)
|
||||
|
||||
### download - Download model
|
||||
|
||||
Download the specified model only, without starting the service.
|
||||
@@ -254,6 +302,13 @@ After the service starts, the following API endpoints are available:
|
||||
- **Format**: OpenAI Chat Completion format
|
||||
- **Streaming Support**: No
|
||||
|
||||
### Shutdown Endpoint
|
||||
- **Endpoint**: `POST /shutdown`
|
||||
- **Function**: Gracefully shut down the server
|
||||
- **Security**: Localhost only by default, use `--allow-remote-shutdown` flag to enable remote access (not recommended)
|
||||
- **Format**: JSON response
|
||||
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
To maintain compatibility with older versions, the following two usage methods are equivalent:
|
||||
|
||||
+59
-5
@@ -113,11 +113,11 @@ aha run -m qwen3asr-0.6b -i "audio.wav" --weight-path /path/to/model
|
||||
|
||||
### serv - 启动服务
|
||||
|
||||
仅启动 HTTP 服务，不下载模型。必须通过 `--weight-path` 指定本地模型路径。
|
||||
使用指定模型启动 HTTP 服务。`--weight-path` 是可选的 - 如果不指定，默认使用 `~/.aha/{model_id}`。
|
||||
|
||||
**语法：**
|
||||
```bash
|
||||
aha serv [OPTIONS] --model <MODEL> --weight-path <WEIGHT_PATH>
|
||||
aha serv [OPTIONS] --model <MODEL> [--weight-path <WEIGHT_PATH>]
|
||||
```
|
||||
|
||||
**选项：**
|
||||
@@ -127,21 +127,69 @@ aha serv [OPTIONS] --model <MODEL> --weight-path <WEIGHT_PATH>
|
||||
| `-a, --address <ADDRESS>` | 服务监听地址 | 127.0.0.1 |
|
||||
| `-p, --port <PORT>` | 服务监听端口 | 10100 |
|
||||
| `-m, --model <MODEL>` | 模型类型（必选） | - |
|
||||
| `--weight-path <WEIGHT_PATH>` | 本地模型权重路径（必选） | - |
|
||||
| `--weight-path <WEIGHT_PATH>` | 本地模型权重路径（可选） | ~/.aha/{model_id} |
|
||||
| `--allow-remote-shutdown` | 允许远程关机请求（不推荐） | false |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 使用默认模型路径启动服务 (~/.aha/{model_id})
|
||||
aha serv -m qwen3vl-2b
|
||||
|
||||
# 使用本地模型启动服务
|
||||
aha serv -m qwen3vl-2b --weight-path /path/to/model
|
||||
|
||||
# 指定端口启动
|
||||
aha serv -m qwen3vl-2b --weight-path /path/to/model -p 8080
|
||||
aha serv -m qwen3vl-2b -p 8080
|
||||
|
||||
# 指定监听地址
|
||||
aha serv -m qwen3vl-2b --weight-path /path/to/model -a 0.0.0.0
|
||||
aha serv -m qwen3vl-2b -a 0.0.0.0
|
||||
|
||||
# 启用远程关机（不推荐用于生产环境）
|
||||
aha serv -m qwen3vl-2b --allow-remote-shutdown
|
||||
```
|
||||
|
||||
### ps - 列出运行中的服务
|
||||
|
||||
列出所有当前正在运行的 AHA 服务，显示进程 ID、端口和状态。
|
||||
|
||||
**语法：**
|
||||
```bash
|
||||
aha ps [OPTIONS]
|
||||
```
|
||||
|
||||
**选项：**
|
||||
|
||||
| 选项 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `-c, --compact` | 紧凑输出格式（仅显示服务 ID） | false |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 列出所有运行中的服务（表格格式）
|
||||
aha ps
|
||||
|
||||
# 紧凑输出（仅服务 ID）
|
||||
aha ps -c
|
||||
```
|
||||
|
||||
**输出格式：**
|
||||
|
||||
```
|
||||
Service ID PID Model Port Address Status
|
||||
-------------------------------------------------------------------------------------
|
||||
56860@10100 56860 N/A 10100 127.0.0.1 Running
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `Service ID`: 服务唯一标识符，格式为 `pid@port`
|
||||
- `PID`: 进程 ID
|
||||
- `Model`: 模型名称（如果未检测到则显示 N/A）
|
||||
- `Port`: 服务端口号
|
||||
- `Address`: 服务监听地址
|
||||
- `Status`: 服务状态（Running、Stopping、Unknown）
|
||||
|
||||
### download - 下载模型
|
||||
|
||||
仅下载指定模型，不启动服务。
|
||||
@@ -254,6 +302,12 @@ aha -m qwen3vl-2b -a 0.0.0.0 -p 8080
|
||||
- **格式**: OpenAI Chat Completion 格式
|
||||
- **流式支持**: 不支持
|
||||
|
||||
### 关机接口
|
||||
- **端点**: `POST /shutdown`
|
||||
- **功能**: 优雅地关闭服务器
|
||||
- **安全性**: 默认仅允许本地访问，使用 `--allow-remote-shutdown` 标志启用远程访问（不推荐）
|
||||
- **格式**: JSON 响应
|
||||
|
||||
## 向后兼容性
|
||||
|
||||
为了保持与旧版本的兼容性，以下两种使用方式是等效的：
|
||||
|
||||
Reference in New Issue
Block a user