From b7f7e4f12101569db5bb76af9d836043eefc342b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Wed, 14 Oct 2026 11:17:35 +0800 Subject: [PATCH] =?UTF-8?q?fix(deploy):=20=E4=B8=8A=E7=BA=BF=E5=89=8D?= =?UTF-8?q?=E6=A0=A1=E9=AA=8C=20.env=20=E9=94=AE=E5=80=BC=E5=BD=A2?= =?UTF-8?q?=E7=8A=B6=EF=BC=88=E4=B8=A4=E8=A1=8C=E7=B2=98=E6=88=90=E4=B8=80?= =?UTF-8?q?=E8=A1=8C=E7=9A=84=E5=9D=8F=E5=80=BC=E4=B8=8D=E5=86=8D=E8=83=BD?= =?UTF-8?q?=E4=B8=8A=E7=BA=BF=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 事故复盘(2026-10-14,测试实例 p1 整体不可用约 6 分钟): - 我用 `rstrip("\n") + 新行` 往 `.env` 追加 `VERSION_HISTORY_LINK_ORIGIN`,而 `.env` 最后一行 当时没有结尾换行 ⇒ 两行**粘成一行**: `VERSION_HISTORY_GITEA_BASE_URL=http://192.168.50.223:3000VERSION_HISTORY_LINK_ORIGIN=https://gitea.zheromiku.top` - 配置校验按设计拒绝这个非法 origin ⇒ `cmd/api`/`cmd/worker` 启动即退出 ⇒ 容器 crash-loop (fail-closed 是对的,但代价是平台起不来)。 修复: - `scripts/deploy-api-web.sh` 新增 **1a 步护栏**:上线前解析 `.env`,只要某行的值里又出现 `KEY=` (两行粘连)或键名不合法 ⇒ 打印 `ENV_VALUE_LOOKS_MERGED` 并**拒绝部署**(不动线上); - `internal/appconfig` 在校验失败时补线索:值里含 `=` ⇒ 提示"`.env` 里两行可能粘成了一行"; - 回归用例 `TestLoadRejectsMergedVersionHistoryEnvValue`(粘行必拒 + 线索文案 + 合法值仍放行)。 验证:护栏对"粘行样例/键名非法"退出码 1、对"正常样例/当前真实 .env"退出码 0;Go 用例通过; make verify 15/15。线上已修 `.env` 并重启 api+worker(healthy),重新同步后页面链接已全部走公网 origin。 --- CHANGELOG.md | 1 + internal/appconfig/config.go | 12 +++++++++++- internal/appconfig/config_test.go | 32 +++++++++++++++++++++++++++++++ scripts/deploy-api-web.sh | 31 ++++++++++++++++++++++++++++++ 4 files changed, 75 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 260cb0c..d9e7f17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ - `index.html` 此前**没有缓存头**,CDN/浏览器按启发式缓存它 ⇒ 页面会一直停在旧构建上(实测被腾讯云 EdgeOne 卡住:源站已是新包,公网入口仍发旧包)。现在 `index.html` 每次回源校验(`no-cache, must-revalidate`); - 带内容哈希的 `/assets/` 长缓存(`immutable`),但**未命中时先回退到"上一版构建的资源"目录、再 404**(`deploy/legacy-assets` 由部署脚本在每次重建前落盘并只读挂载):CDN/浏览器仍持有旧 `index.html` 时,它引用的旧 JS/CSS 依旧能取到 ⇒ 不会出现"JS 404 白屏"或"CSS 404 只有文字没样式"; - 明确 404 时不再回退成 `index.html`(否则浏览器把 HTML 当 JS 执行,报一堆语法错误)。 +- **上线前护栏 + 事故复盘**:`scripts/deploy-api-web.sh` 现在先校验 `.env` 的键值形状(值里再出现 `KEY=` 或键名不合法 ⇒ **拒绝上线**),配置校验失败时也会给出"两行粘成一行"的线索。事故:`.env` 最后一行没有结尾换行、又被追加新键 ⇒ 两行粘成一行 ⇒ `VERSION_HISTORY_GITEA_BASE_URL` 变成非法值 ⇒ api/worker 按设计拒绝启动、崩溃重启(平台整体不可用)。已修数据、加护栏、加回归用例。 - 「版本记录」页的链接改为**抓取与链接分离**:抓取仍走配置的(内网)地址,页面上的「查看提交 / 查看 tag」用 `VERSION_HISTORY_LINK_ORIGIN`(公网 origin)拼 —— 原先两者共用内网地址,内网外的浏览器点开是空白;另外 tag 记录原先不带链接(空 `href` 点下去没反应),现在补上链接、没有链接就不渲染该按钮。 ### Security diff --git a/internal/appconfig/config.go b/internal/appconfig/config.go index 14aa71b..8a72748 100644 --- a/internal/appconfig/config.go +++ b/internal/appconfig/config.go @@ -206,7 +206,8 @@ func Load(getenv func(string) string) (Config, error) { // 版本记录来源:给了 origin 就必须是干净的 http(s) origin;白名单留空则默认只许自己。 if config.VersionHistoryGiteaBaseURL != "" { if err := validateHTTPBaseURL(config.VersionHistoryGiteaBaseURL); err != nil { - return Config{}, fmt.Errorf("VERSION_HISTORY_GITEA_BASE_URL: %w", err) + return Config{}, fmt.Errorf("VERSION_HISTORY_GITEA_BASE_URL: %w%s", err, + envHint(config.VersionHistoryGiteaBaseURL)) } if len(config.VersionHistoryAllowedOrigins) == 0 { config.VersionHistoryAllowedOrigins = []string{config.VersionHistoryGiteaBaseURL} @@ -321,6 +322,15 @@ func validateHTTPBaseURL(value string) error { return nil } +// envHint 给"值明显不像一个地址"的情况补一句线索:最常见的成因是 `.env` 里两行粘在一起 +// (新键被追加到没有结尾换行的上一行后面)—— 值里就会出现第二个 `KEY=`。 +func envHint(value string) string { + if strings.Contains(value, "=") { + return "(值里出现了 `=`:`.env` 里两行可能粘成了一行,改成一行一值再上线)" + } + return "" +} + // splitOrigins 解析逗号分隔的 origin 白名单(空项丢弃)。 func splitOrigins(value string) []string { parts := strings.Split(value, ",") diff --git a/internal/appconfig/config_test.go b/internal/appconfig/config_test.go index 438f82a..893bbe8 100644 --- a/internal/appconfig/config_test.go +++ b/internal/appconfig/config_test.go @@ -1,6 +1,7 @@ package appconfig import ( + "strings" "testing" "time" ) @@ -290,3 +291,34 @@ func TestProductionWeKnoraEndpointIsConfigurableAndFailsClosed(t *testing.T) { t.Fatalf("production endpoint must default to unconfigured: %#v", unset) } } + +// 回归用例(2026-10-14 线上事故):`.env` 两行粘成一行时,base URL 会变成 +// "http://host:3000VERSION_HISTORY_LINK_ORIGIN=…" —— 必须被拒,并给出线索文案, +// 而不是让 api/worker 带着坏值崩溃重启(或者更糟:静默按坏值跑起来)。 +func TestLoadRejectsMergedVersionHistoryEnvValue(t *testing.T) { + values := map[string]string{ + "DATABASE_URL": "postgres://example", + "VERSION_HISTORY_GITEA_BASE_URL": "http://192.168.50.223:3000VERSION_HISTORY_LINK_ORIGIN=https://gitea.example", + } + _, err := Load(func(key string) string { return values[key] }) + if err == nil { + t.Fatal("粘在一起的值必须被拒绝") + } + if !strings.Contains(err.Error(), "粘成了一行") { + t.Fatalf("错误里应给出线索(.env 粘行):%v", err) + } + + // 正常值仍然放行,且链接 origin 可为空(退回抓取 origin) + good := map[string]string{ + "DATABASE_URL": "postgres://example", + "VERSION_HISTORY_GITEA_BASE_URL": "http://192.168.50.223:3000", + "VERSION_HISTORY_LINK_ORIGIN": "https://gitea.example", + } + config, err := Load(func(key string) string { return good[key] }) + if err != nil { + t.Fatalf("合法配置不该被拒:%v", err) + } + if config.VersionHistoryLinkOrigin != "https://gitea.example" || len(config.VersionHistoryAllowedOrigins) != 1 { + t.Fatalf("配置解析不对:%+v", config) + } +} diff --git a/scripts/deploy-api-web.sh b/scripts/deploy-api-web.sh index 3400110..314f467 100644 --- a/scripts/deploy-api-web.sh +++ b/scripts/deploy-api-web.sh @@ -9,6 +9,37 @@ echo "=== 1. 打回滚标签 ($TS)" docker tag knowledge-governance-p1-api:latest "knowledge-governance-p1-api:rollback-$TS" || exit 1 docker tag knowledge-governance-p1-web:latest "knowledge-governance-p1-web:rollback-$TS" || exit 1 +echo "=== 1a. 上线前校验 .env 的键值形状(一行一值)" +# 2026-10-14 实测事故:`.env` 最后一行没有结尾换行、又被追加新键 ⇒ 两行粘成一行 +# ⇒ VERSION_HISTORY_GITEA_BASE_URL 变成 "http://host:3000VERSION_HISTORY_LINK_ORIGIN=…" +# ⇒ 配置校验按设计拒绝启动 ⇒ api/worker 崩溃重启(平台整体不可用)。 +# 这里在**上线前**用形状判定拦住:值里再出现 `KEY=` 或键名不合法,直接拒绝部署。 +if [ -f .env ]; then + python3 - <<'ENVCHECK' || exit 1 +import pathlib +import re +import sys + +problems = [] +for number, raw in enumerate(pathlib.Path(".env").read_text(encoding="utf-8").splitlines(), 1): + line = raw.strip() + if not line or line.startswith("#") or "=" not in line: + continue + key, value = line.split("=", 1) + if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key.strip()): + problems.append((number, line, "键名不合法")) + elif re.search(r"[A-Z][A-Z0-9_]{3,}=", value): + # 不能用 \b:粘行处是 "…:3000VERSION_HISTORY_…",数字紧邻字母,没有词边界。 + problems.append((number, line, "值里又出现 KEY=(两行粘在一起)")) +if problems: + print("ENV_VALUE_LOOKS_MERGED(.env 有坏值,拒绝上线)") + for number, line, why in problems: + print(f" line {number}: {why}: {line[:120]}") + sys.exit(1) +print(" .env 键值形状 OK") +ENVCHECK +fi + echo "=== 1b. 构建身份(构建期注入:页面「当前运行」只认产物里的完整 SHA 精确匹配)" # 唯一来源是 scripts/version.py --identity(与 Makefile、CI 同一份规则):不注入 ⇒ 页面只能显示"未知"。 IDENTITY_ARGS=()