diff --git a/deploy/zd-host.sh b/deploy/zd-host.sh
index 56c2e65..db83122 100644
--- a/deploy/zd-host.sh
+++ b/deploy/zd-host.sh
@@ -156,6 +156,14 @@ w200 "http://127.0.0.1:18080/healthz"
 w200 "http://127.0.0.1:18080/conf.yml"
 w200 "http://127.0.0.1:18080/admin"
 
+# apply 触发的 nginx reload 是异步的：不等就绪直接探测会拿到 404，
+# 造成"明明升级成功却判失败"（本次真实踩到，与 README 接口注意事项第 4 条同因）。
+for _w in $(seq 1 20); do
+  _c=$(curl -sk -o /dev/null -w "%{http_code}" -m 3 --resolve "$CHECK_HOST:${ENTRY_PORT:-3080}:127.0.0.1" \
+        "https://$CHECK_HOST:${ENTRY_PORT:-3080}/" 2>/dev/null || echo 000)
+  [ "$_c" != "000" ] && break
+  sleep 0.5
+done
 # 入口自检：受保护域名应 302、公开域名应非 5xx、未知域名应 404（自定义页）
 CODE=$(curl -sk -o /dev/null -w '%{http_code}' -m 8 --resolve dashy.example.com:3080:127.0.0.1 https://dashy.example.com:3080/conf.yml)
 [ "$CODE" = "302" ] || { echo "!! 受保护域名应 302，实际 $CODE" >&2; false; }
@@ -175,7 +183,13 @@ if [ -n "$ADMIN_TOK" ]; then
 
 # ③ 旧容器用过明文 PORTAL_PASSWORD 时，换成强随机口令并只打印一次
 #    （失败不影响升级：可在后台「统一登录账号」自行设置）
-if [ "${CLEAN_PORTAL_PW:-0}" = "1" ]; then
+# 只清理明文 env（生效凭据来自数据卷 portal-auth.json，删掉 env 不影响登录）。
+# 重置口令会造成"所有受保护域名都要用新口令登录"，属高风险操作，
+# 因此必须显式开启 NAVI_ROTATE_PORTAL_PASSWORD=1 才执行。
+if [ "${CLEAN_PORTAL_PW:-0}" = "1" ] && [ "${NAVI_ROTATE_PORTAL_PASSWORD:-0}" != "1" ]; then
+  echo "  已丢弃旧容器 env 里的明文 PORTAL_PASSWORD；门户口令保持不变（如确需更换，后台可改，或传 NAVI_ROTATE_PORTAL_PASSWORD=1）"
+fi
+if [ "${CLEAN_PORTAL_PW:-0}" = "1" ] && [ "${NAVI_ROTATE_PORTAL_PASSWORD:-0}" = "1" ]; then
   NEWPW="$( (openssl rand -base64 24 2>/dev/null || head -c 24 /dev/urandom | base64) | tr -d '/+=' | cut -c1-20)"
   RESP=$(curl -s -X POST -H "Authorization: Bearer $ADMIN_TOK" -H 'Content-Type: application/json' \
     -d "{\"username\":\"admin\",\"password\":\"$NEWPW\"}" http://127.0.0.1:3005/api/portal-auth || true)