jianf/HomeDash
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

fix(docs): 清除 AGENTS.md 里的真实令牌/口令/备案号（我自己写进去的），并修正端口写死

Browse Source 
机械式 runbook 验证（照抄文档命令执行）抓到两个真问题：

1) 严重：AGENTS.md §6 脱敏自检把**真实令牌前缀、真实口令、真实备案号**当作
   "示例模式"写了进去 —— 等于把凭据与备案信息提交进仓库。
   改为特征检测（长度/字符集/格式），并排除文档自身；同时写明"不要用真实值当模式"。

2) §5 验收与 §4.3 验证把端口写死 3080：非默认端口部署（如 NAVI_ENTRY_PORT=13080）
   照抄会全部得到 000（实测）。改为 PORT=${NAVI_ENTRY_PORT:-3080} 等变量，
   并注明 NAVI_TLS=0 的部署没有跳转端口（该项 000 属预期）。

已知坑表补两条对应的现象与处理。
This commit is contained in:
HomeDash Bot
2026-09-12 11:17:05 +08:00
parent 5ba7789e30
commit 890af22b95
1 changed files with 27 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
AGENTS.md
View File

@ -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. 验收清单（部署后 / 改配置后都跑一遍）
把 `<HOST>` 换成路由表里任一已配置域名。**每一项都要看实际输出，不要假定通过。**
把 `<HOST>` 换成路由表里任一已配置域名。**端口必须用变量**：写死 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 命令行显式传（脚本已处理） |