From 890af22b95f35a94b14c8d711006281bd1e0a279 Mon Sep 17 00:00:00 2001 From: HomeDash Bot Date: Sat, 12 Sep 2026 11:17:05 +0800 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=E6=B8=85=E9=99=A4=20AGENTS.md=20?= =?UTF-8?q?=E9=87=8C=E7=9A=84=E7=9C=9F=E5=AE=9E=E4=BB=A4=E7=89=8C/?= =?UTF-8?q?=E5=8F=A3=E4=BB=A4/=E5=A4=87=E6=A1=88=E5=8F=B7=EF=BC=88?= =?UTF-8?q?=E6=88=91=E8=87=AA=E5=B7=B1=E5=86=99=E8=BF=9B=E5=8E=BB=E7=9A=84?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E5=B9=B6=E4=BF=AE=E6=AD=A3=E7=AB=AF=E5=8F=A3?= =?UTF-8?q?=E5=86=99=E6=AD=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 机械式 runbook 验证（照抄文档命令执行）抓到两个真问题： 1) 严重：AGENTS.md §6 脱敏自检把**真实令牌前缀、真实口令、真实备案号**当作 "示例模式"写了进去 —— 等于把凭据与备案信息提交进仓库。 改为特征检测（长度/字符集/格式），并排除文档自身；同时写明"不要用真实值当模式"。 2) §5 验收与 §4.3 验证把端口写死 3080：非默认端口部署（如 NAVI_ENTRY_PORT=13080） 照抄会全部得到 000（实测）。改为 PORT=${NAVI_ENTRY_PORT:-3080} 等变量， 并注明 NAVI_TLS=0 的部署没有跳转端口（该项 000 属预期）。 已知坑表补两条对应的现象与处理。 --- AGENTS.md | 41 +++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d2287fd..d45a80c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -193,8 +193,9 @@ curl -s -X DELETE -H "Authorization: Bearer $TOK" "$A/history/item?url=<编码 ```bash HOST=<刚改的域名> +PORT=${NAVI_ENTRY_PORT:-3080}; SCHEME=${NAVI_TLS_SCHEME:-https} for i in $(seq 1 20); do # apply 后 reload 是异步的 - code=$(curl -sk -o /dev/null -w '%{http_code}' -m 3 --resolve "$HOST:3080:127.0.0.1" "https://$HOST:3080/") + code=$(curl -sk -o /dev/null -w '%{http_code}' -m 3 --resolve "$HOST:$PORT:127.0.0.1" "$SCHEME://$HOST:$PORT/") [ "$code" != "000" ] && break; sleep 0.5 done echo "$code" # 期望：200（门户）或 302（受保护） @@ -204,17 +205,23 @@ echo "$code" # 期望：200（门户）或 302 ## 5. 验收清单（部署后 / 改配置后都跑一遍） -把 `` 换成路由表里任一已配置域名。**每一项都要看实际输出，不要假定通过。** +把 `` 换成路由表里任一已配置域名。**端口必须用变量**：写死 3080 时，非默认端口 +部署（例如 `NAVI_ENTRY_PORT=13080`）会全部探测到 `000` —— 这是实测踩过的坑。 ```bash -T=$(curl -sk -o /dev/null -w '%{http_code}' -m 8 --resolve "$HOST:3080:127.0.0.1" "https://$HOST:3080/") -U=$(curl -sk -o /dev/null -w '%{http_code}' -m 8 --resolve nobody.invalid:3080:127.0.0.1 https://nobody.invalid:3080/) -H=$(curl -s -o /dev/null -w '%{http_code}' -m 8 http://127.0.0.1:18080/healthz) -S=$(curl -s -o /dev/null -w '%{http_code}' -m 8 http://127.0.0.1:18080/admin/api/schema) -R=$(curl -s -o /dev/null -w '%{http_code}' -m 8 -H "Host: $HOST" http://127.0.0.1:3081/) +PORT=${NAVI_ENTRY_PORT:-3080} # 入口端口（非 3080 部署必须设） +RT=${NAVI_REDIRECT_PORT:-3081} # http→https 跳转端口 +SCHEME=${NAVI_TLS_SCHEME:-https} # NAVI_TLS=0 的部署用 http +T=$(curl -sk -o /dev/null -w '%{http_code}' -m 8 --resolve "$HOST:$PORT:127.0.0.1" "$SCHEME://$HOST:$PORT/") +U=$(curl -sk -o /dev/null -w '%{http_code}' -m 8 --resolve nobody.invalid:$PORT:127.0.0.1 "$SCHEME://nobody.invalid:$PORT/") +H=$(curl -s -o /dev/null -w '%{http_code}' -m 8 http://127.0.0.1:18080/healthz) +S=$(curl -s -o /dev/null -w '%{http_code}' -m 8 http://127.0.0.1:18080/admin/api/schema) +R=$(curl -s -o /dev/null -w '%{http_code}' -m 8 -H "Host: $HOST" http://127.0.0.1:$RT/) printf '已配置域名=%s 未知域名=%s healthz=%s schema=%s 跳转=%s\n' "$T" "$U" "$H" "$S" "$R" ``` +> `跳转=302` 只在**启用 TLS** 的部署上适用；`NAVI_TLS=0` 的安装没有跳转端口，该项会得到 `000`，属预期。 + | 项 | 期望 | 不符合时的含义 | | --- | --- | --- | | 已配置域名 | `200` 或 `302` | `404`＝不在路由表；`000`＝没监听/证书问题；`5xx`＝上游或配置坏了 | @@ -235,15 +242,19 @@ docker exec navi sh -c 'ls /app/data/portal-auth.json' # 存在 → 登录凭 ## 6. 提交前脱敏清单（把仓库发布出去之前必跑） ```bash -# 期望：全部为 0 -git grep -cIE 'REDACTED_TOKEN|REDACTED_TOKEN|PORTAL_PASSWORD_REDACTED' | wc -l # 真实令牌/口令 -git grep -cIE '10.0.0.[0-9]+' | wc -l # 真实内网地址 -git grep -cIE 'example.com' | wc -l # 真实域名 -git grep -cIE '豫ICP备00000000|豫公网安备00000000000000' | wc -l # 真实备案号 -git ls-files | grep -cE '(^|/)(conf\.yml|gateway\.yml|history\.json|portal-auth\.json|\.env)$' # 数据卷文件 -git ls-files | grep -ciE '\.(pem|key|crt|p12|pfx)$' # 私钥/证书 +# 期望：全部为 0（本文件自身含检测用的正则，故排除自身） +git grep -nIE '(NAVI_(SYNC|ADMIN)_TOKEN|PORTAL_PASSWORD|PORTAL_SESSION_SECRET)=[0-9A-Za-z_-]{12,}' | grep -v '^AGENTS.md' | wc -l # 真实令牌/口令（按长度+字符集识别，不写具体值） +git grep -nIE '192\.168\.[0-9]+\.[0-9]+' | wc -l # 内网地址 +git grep -nIE '[京沪粤豫苏浙川鲁闽湘鄂]ICP备[0-9]{6,}' | grep -v '^AGENTS.md' | wc -l # 备案号（省简称+ICP备+数字） +git grep -nIE '公网安备[0-9]{8,}' | grep -v '^AGENTS.md' | wc -l # 公网安备 +git grep -nIE '(^|[^a-z])([a-z0-9-]+\.)+(xyz|top|club|vip)([^a-z]|$)' | grep -v '^AGENTS.md' | wc -l # 真实域名后缀（按需保留白名单） +git ls-files | grep -cE '(^|/)(conf\.yml|gateway\.yml|history\.json|portal-auth\.json|\.env)$' # 数据卷文件必须为 0 +git ls-files | grep -ciE '\.(pem|key|crt|p12|pfx)$' # 私钥/证书必须为 0 ``` +> ⚠️ **不要把真实令牌、口令、备案号、域名当作"示例模式"写进任何文档**（本手册初版就犯过： +> 把真实值写进自检命令，等于把凭据提交进仓库）。检测一律用"长度/字符集/格式"特征来写。 + **绝不可提交**：`conf.yml`、`gateway.yml`、`history.json`、`portal-auth.json`、`.env`、 `*.pem|key|crt`、任何真实令牌与口令、真实域名/内网地址/备案号。 @@ -279,4 +290,6 @@ docker start navi | 脚本报 `HOST: unbound variable` | 必填校验写在赋值之前 + `set -u` | 升级脚本（已修）；或先给变量赋值再校验 | | 容器名叫 `navi-next` | 切换中途中断 | 验收通过后 `docker rename navi-next navi` | | `no space left on device` | `/tmp` 是 tmpfs，构建包 ~222M | 构建前 `rm -rf /tmp/homedash-*` | +| 照抄验收命令却全是 000 | 文档里的端口写死 3080，而部署用了别的端口 | 用 `PORT=${NAVI_ENTRY_PORT:-3080}`（本手册已改） | +| 脱敏自检把文档自己判为"命中" | 自检命令里写了真实值当模式 | 用长度/字符集特征检测，并排除文档自身（本手册已改） | | 部署脚本用 `bash -s` 传参不生效 | 远端 heredoc 是引号形式，不展开本地变量 | 在 ssh 命令行显式传（脚本已处理） |