[优化] 添加节点 IP 手动覆盖功能，更新相关文档和测试用例

docs/design/architecture.md

@@ -58,6 +58,8 @@ Server 不直接 SSH 到节点，也不在线修改节点文件。它只保存
 
 Agent 通过 `openresty_path` 指向的 OpenResty 二进制统一执行校验、reload、启动与重启；未配置时默认调用 `openresty`。Docker 部署时，Agent 镜像内置 OpenResty 二进制，仍走同一套二进制控制逻辑。
 
+节点 IP 默认由 Agent 注册和心跳上报维护；如果管理端锁定节点 IP，Server 只更新运行状态、版本、观测等运行态字段，不再接受 Agent 上报覆盖该 IP。
+
 ## Frontend
 
 `openflare_server/web` 是正式管理端前端：

docs/en/design/architecture.md

@@ -58,6 +58,8 @@ The Server does not directly SSH into nodes, nor does it modify node files onlin
 
 The Agent uniformly executes validations, reloads, starts, and restarts via the OpenResty binary pointed to by `openresty_path`; it falls back to calling `openresty` by default when not configured. In Docker deployments, the Agent image includes the OpenResty binary and follows the same binary control logic.
 
+Node IPs are maintained by Agent registration and heartbeat reports by default; when the admin UI locks a node IP, the Server continues updating runtime fields such as status, versions, and observability, but no longer accepts Agent reports to overwrite that IP.
+
 ## Frontend
 
 `openflare_server/web` is the official management console frontend:

docs/en/guide/usage.md

@@ -106,6 +106,8 @@ Node pages answer three questions:
 | Which version is running? | Current version on the node detail page |
 | Did the last apply succeed? | Apply logs |
 
+Node IPs are filled automatically by Agent registration and subsequent heartbeats by default. When you enter or change an IP in the admin UI, the node editor enables "Lock node IP" by default; Agent reports will not overwrite the IP while the lock is enabled. After unlocking, the next Agent heartbeat or WebSocket status report can update it again.
+
 Access analytics and resource snapshots provide basic observability. OpenFlare only keeps access details for a controlled time window; it is not a general-purpose log platform. Use a dedicated logging system for long-term log search.
 
 ## Common Scenarios

docs/en/reference/configuration.md

@@ -198,6 +198,7 @@ Description:
 * If `agent.json` does not exist but environment variables such as `OPENFLARE_SERVER_URL` and tokens are sufficient, the Agent can start directly; environment variables take precedence when both exist.
 * When the Agent is not configured with `node_ip`, it first queries `https://realip.cc` for the real public egress IP, adapting to Docker/NAT scenarios; it falls back to local interface detection on failure, preferring a public IPv4 address.
 * When the Agent automatically detects a private `node_ip`, the Server prioritizes retaining the public address of the Agent's direct connection during registration/heartbeat phases, avoiding misregistering internal interface addresses in NAT or multi-interface scenarios.
+* When "Lock node IP" is enabled in the admin UI, the Server keeps the manually configured node IP and Agent registration, HTTP heartbeat, or WebSocket status reports will not overwrite that field; after unlocking, the next report can fill it again.
 
 ## Common Configuration Combinations
 

docs/guide/usage.md

@@ -108,6 +108,8 @@ WAF 或 PoW 配置修改后，都需要重新发布并激活配置版本，Agent
 | 当前运行哪个版本 | 节点详情中的当前版本 |
 | 最近一次应用是否成功 | 应用记录 |
 
+节点 IP 默认由 Agent 注册和后续心跳自动回填。若在管理端填写或修改 IP，节点编辑会默认开启“锁定节点 IP”；开启后 Agent 上报不会覆盖该 IP。关闭锁定后，下一次 Agent 心跳或 WebSocket 状态上报会重新按自动逻辑更新。
+
 访问分析和资源快照用于基础观测。OpenFlare 只保留受控时间窗口内的访问明细，不定位为通用日志平台。如果需要长期日志检索，应接入独立日志系统。
 
 ## 常见场景

docs/reference/configuration.md

@@ -198,6 +198,7 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
 * 如果 `agent.json` 不存在，但 `OPENFLARE_SERVER_URL` 与 Token 等环境变量足够，Agent 可以直接启动；两者同时存在时环境变量优先。
 * Agent 未配置 `node_ip` 时，会优先通过 `https://realip.cc` 获取真实出口公网 IP，适配 Docker/NAT 场景；该请求失败时，才退回本机网卡探测并优先选择公网 IPv4。
 * Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址。
+* 在管理端开启“锁定节点 IP”后，Server 会保留管理端填写的节点 IP，后续 Agent 注册、HTTP 心跳或 WebSocket 状态上报不会覆盖该字段；关闭锁定后，下一次上报可重新回填。
 
 ## 常见配置组合