From 203cd05fbbb99c76421325c09765be38f99708af Mon Sep 17 00:00:00 2001
From: HomeDash Bot <bot@example.com>
Date: Sat, 12 Sep 2026 10:31:46 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8E=A5=E5=8F=A3=E6=B3=A8=E6=84=8F?=
 =?UTF-8?q?=E4=BA=8B=E9=A1=B9=EF=BC=88=E5=89=8D=E7=BC=80=20/=20=E6=95=B4?=
 =?UTF-8?q?=E8=A1=A8=E6=9B=BF=E6=8D=A2=20/=20=E5=BF=85=E9=A1=BB=20apply=20?=
 =?UTF-8?q?/=20reload=20=E9=9C=80=E7=AD=89=E5=BE=85=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

验证过程中实际踩到的四点，写进 README 便于 agent 与人复用：
1. 管理接口前缀是 /admin/api；打根 /api/ 会拿到 200 + Dashy HTML 的假成功，
   判断是否命中要看返回体类型而非状态码
2. 路由表是整表替换，必须提交完整 {routes:[...]}；清空非空表需 force:true
3. 改完必须 apply（内部 nginx -t 校验，失败保留旧配置并回显 nginx 报错）
4. apply 是异步 reload：立刻探测会得到旧结果（表现为'apply 了却 404'），
   给出轮询等待入口就绪的示例脚本
---
 README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/README.md b/README.md
index dc155dd..9073e3f 100644
--- a/README.md
+++ b/README.md
@@ -590,6 +590,28 @@ curl -s http://127.0.0.1:18080/api/schema | jq        # 人读：items + resourc
 | 图标上传 | `POST /api/icon`（multipart，字段 `file`） |
 | 重建导航分区 | `POST /api/reload` |
 
+### 接口注意事项（agent 最容易踩的四点）
+
+1. **前缀是 `/admin/api`**（经统一入口）；容器内也可直连 `http://127.0.0.1:3005/api`。
+   根路径 `/api/` 不是管理接口：打到那里会得到 **200 + Dashy 的 HTML**，看着像成功其实什么都没改。
+   判断是否命中看返回体类型（JSON vs `<!DOCTYPE html>`），别只看状态码。
+2. **路由表是整表替换**：必须提交完整 `{"routes":[…]}`。只给单个路由对象会被 400 拒绝并提示；
+   清空非空表要显式 `force:true`。该接口只改路由表，**不会**动入口端口/TLS/认证地址等其它字段。
+3. **改完必须 apply**：`POST /admin/api/gateway/apply` 先做 `nginx -t` 校验，不通过则保留上一份
+   可用配置，并把 nginx 报错原文返回给你（不会把入口改坏）。
+4. **apply 之后是异步 reload**，不是同步生效：立刻探测可能拿到旧结果（表现为"明明 apply 了却 404"）。
+   正确做法是轮询等入口就绪：
+
+   ```bash
+   HOST=app.example.com
+   for i in $(seq 1 20); do
+     code=$(curl -s -o /dev/null -w '%{http_code}' -m 3 --resolve "$HOST:3080:127.0.0.1" "https://$HOST:3080/")
+     [ "$code" != "000" ] && break
+     sleep 0.5
+   done
+   echo "$code"
+   ```
+
 **示例：让 agent 一次性把站点改成你要的样子**
 
 ```bash