docs: update docs

Author: soulteary

README-zhCN.md

@@ -185,7 +185,9 @@ http://yourserver:9000/hooks/redeploy-webhook
 
 ## 关于此 Fork
 
-本项目是原始 [webhook](https://github.com/adnanh/webhook) 项目的维护分支，专注于：
+本项目是原始 [webhook](https://github.com/adnanh/webhook) 项目的维护分支。当前支持版本为 5.x，版本支持情况见 [SECURITY.md](SECURITY.md)。
+
+该分支专注于：
 
 - **安全性**：定期安全更新、漏洞修复和增强的安全功能
 - **维护性**：积极开发、依赖更新和错误修复

README.md

@@ -185,7 +185,9 @@ For more examples and use cases, check out [Hook Examples](docs/en-US/Hook-Examp
 
 ## About This Fork
 
-This project is a maintained fork of the original [webhook](https://github.com/adnanh/webhook) project, focused on:
+This project is a maintained fork of the original [webhook](https://github.com/adnanh/webhook) project. Current supported versions are 5.x; see [SECURITY.md](SECURITY.md) for the version support table.
+
+The fork is focused on:
 
 - **Security**: Regular security updates, vulnerability fixes, and enhanced security features
 - **Maintenance**: Active development, dependency updates, and bug fixes

SECURITY.md

@@ -6,23 +6,23 @@ Current support status of each version.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 3.4.x   | :white_check_mark: |
-| < 3.4.1   | :x:                |
+| 5.x     | :white_check_mark: |
+| < 5.0   | :x:                |
 
 ## Security Features
 
 ### Command Injection Protection
 
 Webhook includes several security features to help prevent command injection attacks:
 
-1. **Command Path Whitelist**: Use `--allowed-command-paths` (or `ALLOWED_COMMAND_PATHS` environment variable) to restrict which commands can be executed. Only commands from the whitelist will be allowed to run.
+1. **Command Path Whitelist**: Use `-allowed-command-paths` (or `ALLOWED_COMMAND_PATHS` environment variable) to restrict which commands can be executed. Only commands from the whitelist will be allowed to run.
 
 2. **Argument Validation**: 
-   - `--max-arg-length`: Limit the maximum length of a single argument (default: 1MB)
-   - `--max-total-args-length`: Limit the total length of all arguments (default: 10MB)
-   - `--max-args-count`: Limit the maximum number of arguments (default: 1000)
+   - `-max-arg-length`: Limit the maximum length of a single argument (default: 1MB)
+   - `-max-total-args-length`: Limit the total length of all arguments (default: 10MB)
+   - `-max-args-count`: Limit the maximum number of arguments (default: 1000)
 
-3. **Strict Mode**: Enable `--strict-mode` to reject arguments containing potentially dangerous characters (shell special characters like `;`, `|`, `&`, `` ` ``, `$`, etc.)
+3. **Strict Mode**: Enable `-strict-mode` to reject arguments containing potentially dangerous characters (shell special characters like `;`, `|`, `&`, `` ` ``, `$`, etc.)
 
 4. **Secure Logging**: All command executions are logged with sensitive information (passwords, tokens, keys) automatically sanitized.
 
@@ -31,8 +31,8 @@ Webhook includes several security features to help prevent command injection att
 - Enable strict mode for enhanced security
 - Set appropriate limits for argument length and count
 - Regularly review and update your whitelist
-- Never enable `--allow-auto-chmod` in production (it's a security risk)
-- Do not enable `--openapi` or `--config-ui` on publicly reachable servers (they have no authentication; use only for debugging or intranet). Config UI is mounted on the webhook server; restrict access with firewall/reverse proxy.
+- Never enable `-allow-auto-chmod` in production (it's a security risk)
+- Do not enable `-openapi` or `-config-ui` on publicly reachable servers (they have no authentication; use only for debugging or intranet). Config UI is mounted on the webhook server; restrict access with firewall/reverse proxy.
 
 For more details, see the [Webhook Parameters (English)](docs/en-US/Webhook-Parameters.md) or [配置参数 (中文)](docs/zh-CN/Webhook-Parameters.md).
 

cmd/README.md

@@ -65,7 +65,7 @@ go build -o webhook .
 
 - 本程序复用 [internal/configui](../internal/configui) 包，静态资源与页面配置仅在该包内维护一份（`internal/configui/config/`、`internal/configui/static/`），通过包内 `embed` 打入二进制，单二进制即可运行。
 - 页面配置来自 `internal/configui/config/page.yaml`（i18n 与表单结构）。
-- 生成 API：`POST /api/generate`，请求体为表单对应 JSON，响应为 `{ "yaml", "json", "callUrl", "curlExample" }`；错误时返回 `{ "error": "..." }` 及 4xx 状态码。
+- 生成 API：`POST {config-ui-path}/api/generate`，请求体为表单对应 JSON，响应为 `{ "yaml", "json", "callUrl", "curlExample" }`；错误时返回 `{ "error": "..." }` 及 4xx 状态码。此外还有 `GET {config-ui-path}/api/capabilities`（返回是否支持保存到目录）与 `POST {config-ui-path}/api/save`（将配置写入 hooks 目录）。完整端点说明见 [API 参考](../docs/zh-CN/API-Reference.md)（Config UI 章节）。
 
 ## 故障排查
 

docs/en-US/API-Reference.md

@@ -12,6 +12,8 @@ http://your-server:9000
 
 You can customize the IP address and port using the `-ip` and `-port` command-line arguments or environment variables.
 
+**Reserved paths and path conflicts:** Do not set `-openapi-path` or `-config-ui-path` to a path that conflicts with reserved endpoints. Reserved paths include `/`, `/health`, `/livez`, `/readyz`, `/version`, `/metrics`, and the hook base path (e.g. `/hooks`). If a conflict is detected at startup, the server will skip registering that route and log a warning.
+
 ## Endpoints
 
 ### 1. Root Endpoint
@@ -53,9 +55,48 @@ curl http://localhost:9000/
 curl http://localhost:9000/health
 ```
 
+**Note:** The exact JSON structure is defined by the health check library (e.g. it may include multiple check results). For the precise schema, see the OpenAPI spec when `-openapi` is enabled.
+
+---
+
+### 3. Liveness and Readiness Endpoints
+
+**Endpoints:** `GET /livez`, `GET /readyz`
+
+**Description:** Kubernetes-style liveness and readiness probes. `/livez` indicates the process is running; `/readyz` reports whether the server is ready to accept traffic (e.g. after loading hooks).
+
+**Response:**
+- **Status Code:** `200 OK` when healthy/ready; non-2xx when not.
+- **Content-Type:** `application/json`
+- **Body:** Implementation-defined JSON (see OpenAPI spec for schema when `-openapi` is enabled).
+
+**Example:**
+```bash
+curl http://localhost:9000/livez
+curl http://localhost:9000/readyz
+```
+
+---
+
+### 4. Version Endpoint
+
+**Endpoint:** `GET /version`
+
+**Description:** Returns server version and build information in JSON format, with optional `X-`-prefixed response headers for version details.
+
+**Response:**
+- **Status Code:** `200 OK`
+- **Content-Type:** `application/json`
+- **Body:** JSON with version fields (e.g. `version`, `commit`, `buildDate`, `branch`). Exact structure is defined by the version library; use the OpenAPI spec when `-openapi` is enabled for the full schema.
+
+**Example:**
+```bash
+curl http://localhost:9000/version
+```
+
 ---
 
-### 3. Metrics Endpoint
+### 5. Metrics Endpoint
 
 **Endpoint:** `GET /metrics`
 
@@ -81,7 +122,7 @@ curl http://localhost:9000/metrics
 
 ---
 
-### 4. OpenAPI Specification Endpoint (Optional)
+### 6. OpenAPI Specification Endpoint (Optional)
 
 **Endpoint:** `GET /openapi` (or custom path via `-openapi-path`)
 
@@ -107,7 +148,7 @@ You can also print the spec to stdout at startup with `-openapi-print` (e.g. `./
 
 ---
 
-### 5. Config UI (Optional)
+### 7. Config UI (Optional)
 
 **Endpoints:** `GET /config-ui`, `GET /config-ui/`, `POST /config-ui/api/generate` (or custom path via `-config-ui-path`)
 
@@ -130,7 +171,7 @@ You can also print the spec to stdout at startup with `-openapi-print` (e.g. `./
 
 ---
 
-### 6. Hook Execution Endpoint
+### 8. Hook Execution Endpoint
 
 **Endpoint:** `POST|GET|PUT|DELETE /hooks/{hook-id}`
 

docs/en-US/Hook-Definition.md

@@ -8,13 +8,13 @@ Hooks are defined as objects in the JSON or YAML hooks configuration file. Pleas
  * `execute-command` - specifies the command that should be executed when the hook is triggered
  * `command-working-directory` - specifies the working directory that will be used for the script when it's executed
  * `response-message` - specifies the string that will be returned to the hook initiator
- * `response-headers` - specifies the list of headers in format `{"name": "X-Example-Header", "value": "it works"}` that will be returned in HTTP response for the hook
+ * `response-headers` - list of header objects returned in the HTTP response for the hook; each object has `"name"` and `"value"` (e.g. `{"name": "X-Example-Header", "value": "it works"}`)
  * `success-http-response-code` - specifies the HTTP status code to be returned upon success
  * `incoming-payload-content-type` - sets the `Content-Type` of the incoming HTTP request (ie. `application/json`); useful when the request lacks a `Content-Type` or sends an erroneous value
  * `http-methods` - a list of allowed HTTP methods, such as `POST` and `GET`
  * `include-command-output-in-response` - boolean whether webhook should wait for the command to finish and return the raw output as a response to the hook initiator. If the command fails to execute or encounters any errors while executing the response will result in 500 Internal Server Error HTTP status code, otherwise the 200 OK status code will be returned.
  * `stream-command-output` - boolean whether webhook should stream the command output to the HTTP response. When enabled, the command's `stdout` and `stderr` are streamed in real-time to the client, rather than waiting for the command to finish before returning. This is useful for long-running commands.
- * `include-command-output-in-response-on-error` - boolean whether webhook should include command stdout & stderror as a response in failed executions. It only works if `include-command-output-in-response` is set to `true`.
+ * `include-command-output-in-response-on-error` - boolean whether webhook should include command stdout & stderr as a response in failed executions. It only works if `include-command-output-in-response` is set to `true`.
  * `parse-parameters-as-json` - specifies the list of arguments that contain JSON strings. These parameters will be decoded by webhook and you can access them like regular objects in rules and `pass-arguments-to-command`.
  * `pass-arguments-to-command` - specifies the list of arguments that will be passed to the command. Check [Referencing request values page](Referencing-Request-Values.md) to see how to reference the values from the request. If you want to pass a static string value to your command you can specify it as
 `{ "source": "string", "name": "argumentvalue" }`

docs/en-US/Migration-Guide.md

@@ -332,26 +332,26 @@ docker run -d \
 ### New Configuration Options
 
 1. **Security:**
-   - `--allowed-command-paths`
-   - `--strict-mode`
-   - `--max-arg-length`
-   - `--max-total-args-length`
-   - `--max-args-count`
+  - `-allowed-command-paths`
+  - `-strict-mode`
+  - `-max-arg-length`
+  - `-max-total-args-length`
+  - `-max-args-count`
 
 2. **Performance:**
-   - `--rate-limit-enabled`
-   - `--rate-limit-rps`
-   - `--rate-limit-burst`
-   - `--max-concurrent-hooks`
-   - `--hook-timeout-seconds`
-   - `--hook-execution-timeout`
+  - `-rate-limit-enabled`
+  - `-rate-limit-rps`
+  - `-rate-limit-burst`
+  - `-max-concurrent-hooks`
+  - `-hook-timeout-seconds`
+  - `-hook-execution-timeout`
 
 3. **HTTP Server:**
-   - `--read-header-timeout-seconds`
-   - `--read-timeout-seconds`
-   - `--write-timeout-seconds`
-   - `--idle-timeout-seconds`
-   - `--max-header-bytes`
+  - `-read-header-timeout-seconds`
+  - `-read-timeout-seconds`
+  - `-write-timeout-seconds`
+  - `-idle-timeout-seconds`
+  - `-max-header-bytes`
 
 ### Enhanced Features
 

docs/en-US/Security-Best-Practices.md

@@ -19,7 +19,7 @@ This document provides comprehensive security best practices for deploying and u
 
 ### 1. Use Command Path Whitelist
 
-**Always** use the `--allowed-command-paths` flag in production to restrict which commands can be executed.
+**Always** use the `-allowed-command-paths` flag in production to restrict which commands can be executed.
 
 ```bash
 webhook -allowed-command-paths="/usr/bin,/opt/scripts"
@@ -77,7 +77,7 @@ webhook \
 
 ### 4. Never Enable Auto-Chmod
 
-**Never** use `--allow-auto-chmod` in production. This is a security risk that can lead to privilege escalation.
+**Never** use `-allow-auto-chmod` in production. This is a security risk that can lead to privilege escalation.
 
 ```bash
 # ❌ BAD - Never do this in production
@@ -245,7 +245,7 @@ chown webhook:webhook hooks.json
 ### 3. Use Least Privilege
 
 - Run webhook with a dedicated, non-privileged user
-- Use `--setuid` and `--setgid` to drop privileges after binding to port
+- Use `-setuid` and `-setgid` to drop privileges after binding to port
 
 ```bash
 # Create dedicated user
@@ -494,13 +494,13 @@ If you discover a security vulnerability, please report it responsibly:
    - Suggested fix (if you have one)
 4. Allow time for the issue to be addressed before public disclosure
 
-For more information, see the [Security Policy](../SECURITY.md).
+For more information, see the [Security Policy](../../SECURITY.md).
 
 ---
 
 ## Additional Resources
 
-- [Security Policy](../SECURITY.md)
+- [Security Policy](../../SECURITY.md)
 - [Hook Rules](Hook-Rules.md) - Authentication and authorization rules
 - [Configuration Parameters](Webhook-Parameters.md) - Security-related parameters
 - [API Reference](API-Reference.md) - API security considerations

docs/en-US/Webhook-Parameters.md

@@ -11,7 +11,7 @@ This document describes all available command-line parameters and environment va
 | `-ip string` | IP address the webhook should serve hooks on | `0.0.0.0` |
 | `-port int` | Port the webhook should serve hooks on | `9000` |
 | `-hooks value` | Explicit single-file mode: path to JSON/YAML hook definitions (can be used multiple times) | - |
-| `-hooks-dir string` | Directory mode: scan hook config files (*.json, *.yaml, *.yml); if empty, watch for new files; use with Config UI to enable save-to-dir | `./hooks` |
+| `-hooks-dir string` | Directory to scan for hook config files (*.json, *.yaml, *.yml). Default `./hooks`. If explicitly set to an empty string, directory mode is not used; when set to a non-empty path, that directory is scanned and (with `-hotreload` or directory watch) can be watched for new files. With Config UI, enables save-to-dir when in directory mode. | `./hooks` |
 | `-urlprefix string` | URL prefix for served hooks (protocol://yourserver:port/PREFIX/:hook-id); also used by Config UI for the generated call URL | `hooks` |
 
 ### Logging and Debugging

docs/zh-CN/API-Reference.md

@@ -12,6 +12,8 @@ http://your-server:9000
 
 您可以使用 `-ip` 和 `-port` 命令行参数或环境变量来自定义 IP 地址和端口。
 
+**保留路径与路径冲突**：请勿将 `-openapi-path` 或 `-config-ui-path` 设置为与保留端点冲突的路径。保留路径包括 `/`、`/health`、`/livez`、`/readyz`、`/version`、`/metrics` 以及 hook 前缀（如 `/hooks`）。若启动时检测到冲突，服务将跳过该路由注册并记录警告。
+
 ## 端点
 
 ### 1. 根端点
@@ -53,9 +55,48 @@ curl http://localhost:9000/
 curl http://localhost:9000/health
 ```
 
+**说明**：实际 JSON 结构由健康检查库定义（可能包含多项检查结果）。精确结构请在使用 `-openapi` 时查看 OpenAPI 规范。
+
+---
+
+### 3. 存活与就绪端点
+
+**端点:** `GET /livez`、`GET /readyz`
+
+**描述:** 类 Kubernetes 的存活与就绪探针。`/livez` 表示进程在运行；`/readyz` 表示服务是否就绪接收流量（如已加载 hooks）。
+
+**响应:**
+- **状态码:** 健康/就绪时为 `200 OK`；否则为非 2xx。
+- **Content-Type:** `application/json`
+- **响应体:** 由实现定义的 JSON（启用 `-openapi` 时可查看 OpenAPI 规范中的 schema）。
+
+**示例:**
+```bash
+curl http://localhost:9000/livez
+curl http://localhost:9000/readyz
+```
+
+---
+
+### 4. 版本端点
+
+**端点:** `GET /version`
+
+**描述:** 以 JSON 格式返回服务版本与构建信息，响应头中可能包含以 `X-` 为前缀的版本相关头。
+
+**响应:**
+- **状态码:** `200 OK`
+- **Content-Type:** `application/json`
+- **响应体:** 包含版本相关字段的 JSON（如 `version`、`commit`、`buildDate`、`branch`）。具体结构由版本库定义；启用 `-openapi` 时可查看 OpenAPI 规范获取完整 schema。
+
+**示例:**
+```bash
+curl http://localhost:9000/version
+```
+
 ---
 
-### 3. 指标端点
+### 5. 指标端点
 
 **端点:** `GET /metrics`
 
@@ -81,7 +122,7 @@ curl http://localhost:9000/metrics
 
 ---
 
-### 4. OpenAPI 规范端点（可选）
+### 6. OpenAPI 规范端点（可选）
 
 **端点:** `GET /openapi`（或通过 `-openapi-path` 自定义路径）
 
@@ -107,7 +148,7 @@ curl http://localhost:9000/openapi
 
 ---
 
-### 5. Config UI（可选）
+### 7. Config UI（可选）
 
 **端点:** `GET /config-ui`、`GET /config-ui/`、`POST /config-ui/api/generate`（或通过 `-config-ui-path` 自定义路径）
 
@@ -130,7 +171,7 @@ curl http://localhost:9000/openapi
 
 ---
 
-### 6. Hook 执行端点
+### 8. Hook 执行端点
 
 **端点:** `POST|GET|PUT|DELETE /hooks/{hook-id}`