20260713_2 落地升级环境变量优先级契约（#114 主工作树收口）

deploy/docker-installer/docs/README.en.md

@@ -80,7 +80,7 @@ Supported values:
 - `rfc6487`: switch back to the original RFC 6487 resource containment behavior.
 
 The installer / soak runner passes `--resource-validation-mode` to every `rpki` child start.
-When an upgraded deployment reuses an older `.env` that does not contain this key, the installer appends the new default `validation-update-03` automatically.
+When an upgraded deployment reuses an older `.env` that does not contain this key, the new package `.env.example` default `validation-update-03` remains in the final `.env`; an empty final value fails before Docker operations.
 
 ## Architecture Guardrails
 

deploy/docker-installer/docs/README.zh-CN.md

@@ -80,7 +80,7 @@ RESOURCE_VALIDATION_MODE=validation-update-03
 - `rfc6487`：切换为 RFC 6487 原始资源包含判定语义。
 
 installer / soak runner 每次启动 `rpki` 子进程时都会显式传入 `--resource-validation-mode`。
-如果升级时复用旧 `.env` 且缺少该变量，installer 会自动补入默认值 `validation-update-03`，不会破坏旧 `.env` 复用流程。
+如果升级时复用旧 `.env` 且缺少该变量，新包 `.env.example` 中的默认值 `validation-update-03` 会保留在最终 `.env` 中；最终值为空时升级会在 Docker 操作前失败。
 
 ## 架构检查
 

deploy/docker-installer/docs/operations.en.md

@@ -89,9 +89,26 @@ Extract the new package into a new directory and explicitly reuse the existing `
 ./scripts/upgrade.sh --reuse-env-from /path/to/old-installer/.env
 ```
 
-If the new package directory already has a `.env`, the upgrade script keeps it.
+Configuration is merged in this order, with a key on the right overriding the same key on the left:
 
-If an older `.env` does not contain `METRICS_IMAGE` or `METRICS_PLATFORM`, the install/upgrade flow backfills package-matched defaults automatically.
+```text
+new .env.example < old .env < environment variables on this upgrade command
+```
+
+For example, override the next-run interval and Grafana password for this upgrade:
+
+```bash
+INTERVAL_SECS=300 GRAFANA_ADMIN_PASSWORD='new-password' \
+  ./scripts/upgrade.sh --reuse-env-from /path/to/old-installer/.env
+```
+
+Before any image is loaded or container is started, upgrade verifies that every key declared by the new template is present and non-empty in the final `.env`. An explicit empty assignment fails, for example `INTERVAL_SECS= ./scripts/upgrade.sh ...`. Removed keys from an old `.env` are not copied, and the script reports key names only, never password-like values.
+
+The installer reads `.env` as Compose-compatible dotenv assignments. Do not put shell command substitutions or environment references such as `$HOME` in the file; use concrete values or command-level overrides instead.
+
+If the new package directory already has a `.env`, the upgrade script keeps it. In that case `--reuse-env-from` is not imported again, but environment variables from the current command still override the existing `.env`.
+
+When an older `.env` lacks a key introduced by the new package, the new `.env.example` default remains in the final `.env`. Upgrade fails before Docker operations if any final declared value is empty.
 
 Upgrade does not delete:
 

deploy/docker-installer/docs/operations.zh-CN.md

@@ -89,9 +89,26 @@ curl -s "http://127.0.0.1:${METRICS_PORT:-9556}/metrics" | grep '^ours_rp_rtr_'
 ./scripts/upgrade.sh --reuse-env-from /path/to/old-installer/.env
 ```
 
-如果新目录已经存在 `.env`，升级脚本会保留它，不覆盖。
+配置按以下优先级合并，右侧同名键覆盖左侧：
 
-如果旧 `.env` 缺失 `METRICS_IMAGE` 或 `METRICS_PLATFORM`，升级/安装链路会按当前包架构自动补齐默认值。
+```text
+新包 .env.example < 旧 .env < 本次 upgrade 命令的环境变量
+```
+
+例如，临时调整下轮触发间隔和 Grafana 密码：
+
+```bash
+INTERVAL_SECS=300 GRAFANA_ADMIN_PASSWORD='new-password' \
+  ./scripts/upgrade.sh --reuse-env-from /path/to/old-installer/.env
+```
+
+升级会在加载镜像或启动容器前检查：新模板声明的所有变量在最终 `.env` 中都必须存在且非空。显式传入空值会失败，例如 `INTERVAL_SECS= ./scripts/upgrade.sh ...`。旧 `.env` 中已不在新模板内的键不会复制，脚本只输出相关键名而不会输出密码等值。
+
+installer 按与 Compose 一致的 dotenv 赋值格式读取 `.env`。不要在文件中使用 Shell 命令替换或 `$HOME` 一类环境变量引用；请使用确定的值，或在执行 upgrade 时通过命令环境变量覆盖。
+
+如果新目录已经存在 `.env`，升级脚本会保留它，不覆盖；此时 `--reuse-env-from` 不会再次导入旧配置，但本次命令的环境变量仍会覆盖已存在的 `.env`。
+
+旧 `.env` 缺少新版本新增的键时，新包 `.env.example` 的默认值会保留在最终 `.env` 中；任一最终值为空则升级会在 Docker 操作前失败。
 
 升级不会删除以下数据：