fix(agent): recover OpenResty runtime after invalid PID (#45)

* fix(agent): recover OpenResty runtime after invalid PID

* fix(agent): scope OpenResty shutdown to instance processes

---------

Co-authored-by: Noru Wyrms <wyrmsnoru@gmail.com>

docs/changelog/index.md

@@ -12,6 +12,7 @@ sidebar: false
 
 ### 🛠 修复
 
+- 修复节点配置自动重试时，OpenResty PID 文件异常导致重复启动和端口占用的问题；自动识别并恢复现有 master，串行执行配置应用与重启，仅跟踪本实例的旧 master 及子进程，等待其退出后再启动，避免其他 nginx 实例阻塞启动与重启。配置回滚后继续按指数退避重试目标版本。
 - 默认信任 Cloudflare 官方 IPv4/IPv6 网段，并允许管理员追加或覆盖可信代理 CIDR；显式 `[]` 可关闭信任。客户端地址恢复后统一用于访问日志、WAF、`X-Real-IP` 和 `X-Forwarded-For` 追加项，旧版自定义 OpenResty 主模板也会自动补入相关指令。
 - 修复 Casdoor 等认证源返回字符串 `id` 时 OIDC 登录回调失败的问题；自动注册独立生成本地用户 ID，避免第三方数字 ID 与已有用户或其他认证源冲突，已有用户及绑定不受影响。
 

docs/deployment/agent.md

@@ -156,4 +156,6 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
 | --- |---------------------------------------------------------------------------------------------------------|
 | `agent_token 和 discovery_token 不能同时为空` | 检查 `agent.json` 至少配置了一个 Token                                                                           |
 | 节点一直离线 | 在 Agent 节点执行 `curl -I http://your-server:3000`，确认 Server 地址可达                                           |
-| 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；在节点详情页点击「强制同步」，或重新发布新版本 |
+| 发布后重复失败 | Agent 会按指数退避自动强制同步，初始间隔 10 秒，最长间隔 5 分钟，直到目标版本应用成功；回滚至旧配置也会继续重试。可在节点详情页点击「强制同步」立即触发 |
+| PID 文件为空或失效，但端口仍被占用 | Agent 会核对 OpenResty master 的进程身份，恢复 PID 文件并重载现有进程；按配置路径和进程父子关系识别本实例，其他 nginx 实例不会阻塞启动。若出现多个匹配的 master，会报告错误并拒绝重复启动 |
+| OpenResty 重启等待超时 | 重启会先发送优雅退出信号，最多等待 10 秒让本实例旧 master 和 worker 退出（持续跟踪已识别的 worker，即使其被重新托管）；超时会保留错误，不会启动第二个实例。检查仍未结束的连接及进程后再重试 |