Skip to content

Commit

Permalink
docs: update documents
Browse files Browse the repository at this point in the history
  • Loading branch information
vicanso committed Jan 1, 2025
1 parent c724a87 commit 776c293
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 11 deletions.
54 changes: 48 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,35 +40,66 @@ flowchart LR
- HTTP plugin system (caching, compression, auth, rate limiting)
- Detailed performance metrics

## Start
## Quick Start

Loads all configurations from `/opt/pingap/conf` or file `/opt/pingap/pingap.toml` and run in the background. Log appends to `/opt/pingap/pingap.log`.
Pingap can be started with either a configuration directory or a single TOML file:

```bash
# Using a config directory
RUST_LOG=INFO pingap -c=/opt/pingap/conf -d --log=/opt/pingap/pingap.log

# Using a single TOML file
RUST_LOG=INFO pingap -c=/opt/pingap/pingap.toml -d --log=/opt/pingap/pingap.log
```

## Graceful restart
Key flags:
- `-c`: Path to config directory or TOML file
- `-d`: Run in daemon/background mode
- `--log`: Path to log file (logs are appended)
- `RUST_LOG=INFO`: Set logging level (DEBUG, INFO, WARN, ERROR)

## Graceful Restart

Validate the configurations, send quit signal to pingap, then start a new process to handle all requests.
Performs a zero-downtime restart of Pingap by following these steps:
1. Validates the new configuration
2. Gracefully shuts down the existing process
3. Starts a new process to handle incoming requests

```bash
# Graceful restart command
RUST_LOG=INFO pingap -c=/opt/pingap/conf -t \
&& pkill -SIGQUIT pingap \
&& RUST_LOG=INFO pingap -c=/opt/pingap/conf -d -u --log=/opt/pingap/pingap.log
```

## Auto restart
Key flags:
- `-t`: Test/validate configuration before restart
- `-u`: Upgrade mode (ensures smooth handover from old process)
- `-d`: Run in daemon mode
- `SIGQUIT`: Signal for graceful shutdown

Watch the configurations, if one of them changes, graceful restart pingap. `autoreload` means if only the upstream and location configurations are updated, they will take effect about 10s without restarting.
## Auto Restart

Automatically monitors configuration files and handles changes in two ways:
- **Full Restart**: When core configurations change, performs a graceful restart
- **Hot Reload**: When only upstream or location configurations change, updates take effect within ~10 seconds without restart

```bash
# Enable auto-restart and hot reload
RUST_LOG=INFO pingap -c=/opt/pingap/conf \
-a -d --autoreload --log=/opt/pingap/pingap.log
```

Key flags:
- `-a`: Enable auto-restart on configuration changes
- `--autoreload`: Enable hot reload for upstream/location changes
- `-d`: Run in daemon mode
- `-c`: Path to configuration directory

## Docker

Run Pingap in a Docker container with auto-restart and admin interface enabled:

```bash
docker run -it -d --restart=always \
-v $PWD/pingap:/opt/pingap \
Expand All @@ -78,6 +109,17 @@ docker run -it -d --restart=always \
--admin=pingap:123123@0.0.0.0:3018
```

Key options:
- `-it`: Interactive terminal (allows input/output)
- `-d`: Run container in detached/background mode
- `--restart=always`: Automatically restart container if it stops
- `-v $PWD/pingap:/opt/pingap`: Mount local config directory into container
- `-p 3018:3018`: Expose admin interface port
- `--autoreload`: Enable hot reload for configuration changes
- `--admin=user:pass@host:port`: Enable admin interface with credentials

Note: Remember to change the default admin credentials (`pingap:123123`) in production environments.

## Dev

```bash
Expand Down
25 changes: 20 additions & 5 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,33 +39,48 @@ flowchart LR
- HTTP 插件系统(缓存、压缩、认证、限流)
- 详细的性能指标:包括upstream连接时间、处理时间、压缩时间、缓存查询时间等

## 启用程序
## 启动服务

`/opt/pingap/conf`目录中加载所有配置,并以后台程序的形式运行,日志写入至`/opt/pingap/pingap.log`
使用以下命令从指定配置目录启动 Pingap 服务:

```bash
RUST_LOG=INFO pingap -c=/opt/pingap/conf -d --log=/opt/pingap/pingap.log
```

参数说明:
- `-c`: 指定配置文件目录
- `-d`: 以守护进程(后台)模式运行
- `--log`: 指定日志文件路径

## 优雅重启

校验配置是否正确后,发送信号给pingap并启动新的程序接收原有的请求。
执行以下命令可实现零停机重启:

```bash
RUST_LOG=INFO pingap -c=/opt/pingap/conf -t \
&& pkill -SIGQUIT pingap \
&& RUST_LOG=INFO pingap -c=/opt/pingap/conf -d -u --log=/opt/pingap/pingap.log
```

## 自动重启
执行步骤:
1. 验证配置文件正确性 (`-t`)
2. 向现有进程发送退出信号
3. 启动新进程接管现有连接 (`-u`)

## 配置热重载

应用启动后,监听相关配置变化,若有变化则无中断式重启程序或热更新加载配置。`autoreload`参数表示如果只是upstream与location的配置变化,则准实时(10秒内)刷新对应配置生效,无需重启。
启用配置自动重载功能:

```bash
RUST_LOG=INFO pingap -c=/opt/pingap/conf \
-a -d --autoreload --log=/opt/pingap/pingap.log
```

特性:
- `-a`: 启用配置变更监听
- `--autoreload`: 支持 upstream 和 location 配置的热重载(10秒内生效)
- 配置变更时自动应用,无需手动重启

## 应用配置

```toml
Expand Down

0 comments on commit 776c293

Please sign in to comment.