ModelEngine-Group · WMC001 · Jun 27, 2026 · Jun 27, 2026
@@ -52,7 +52,7 @@ bash deploy.sh docker
 
 The root `deploy.sh` only forwards to the target deploy script; the native Docker implementation is `bash deploy/docker/deploy.sh`. The Docker and Kubernetes deploy scripts share the same deployment configuration model. Interactive runs show Bash TUI menus for component selection, port policy, and image source. `infrastructure` is required; `application`, `data-process`, and `supabase` are selected by default and can be disabled when you want a smaller deployment. Use `b`/Backspace to return to the previous TUI step and `q` to quit. Non-interactive runs can pass the same choices with `--version`, `--components`, `--port-policy development|production`, and `--image-source general|mainland|local-latest`. Successful deployments save non-sensitive choices to each deploy directory's `deploy.options` for reuse on the next run.
 
-Docker and Kubernetes both use `deploy/env/.env` as the runtime configuration file. Existing `deploy/env/.env` is kept as-is. If it does not exist, the deploy scripts first reuse an existing legacy root `.env` or `docker/.env`, then fall back to `deploy/env/.env.example` or legacy templates.
+Docker and Kubernetes both use `deploy/env/.env` as the runtime configuration file. Existing `deploy/env/.env` is kept as-is. If it does not exist, the deploy scripts first reuse `docker/.env`, then fall back to `deploy/env/.env.example`.
 
 Docker uninstall is handled by `bash uninstall.sh docker`. It can preserve or delete data volumes: run it interactively, pass `--delete-volumes true|false`, or use `bash uninstall.sh docker delete-all` to remove containers and persistent data.
 

@@ -52,7 +52,7 @@ bash deploy.sh docker
 
 根目录 `deploy.sh` 只负责转发到目标部署脚本；Docker 真实实现为 `bash deploy/docker/deploy.sh`。Docker 和 Kubernetes 使用同一套部署配置模型；交互式运行会通过 Bash TUI 选择组件、端口策略和镜像源。`infrastructure` 必选，`application`、`data-process`、`supabase` 默认选中，也可以取消以部署更小的组合。非交互部署可传入 `--version`、`--components`、`--port-policy development|production`、`--image-source general|mainland|local-latest`。
 
-Docker 与 Kubernetes 统一使用 `deploy/env/.env` 作为运行配置文件；已有 `deploy/env/.env` 会原样保留。如果`deploy/env/.env` 不存在，部署脚本会优先复用已有的 `docker/.env`，再回退到 `deploy/env/.env.example` 或 `docker/.env.example`。
+Docker 与 Kubernetes 统一使用 `deploy/env/.env` 作为运行配置文件；已有 `deploy/env/.env` 会原样保留。如果 `deploy/env/.env` 不存在，部署脚本会优先复用已有的 `docker/.env`，再回退到 `deploy/env/.env.example`。
 
 Docker 卸载入口为 `bash uninstall.sh docker`，默认交互确认是否删除持久化数据；也可以通过 `--delete-volumes true|false` 控制，或使用 `bash uninstall.sh docker delete-all` 同时删除容器和持久化数据。
 

@@ -91,10 +91,7 @@
   local env_dir="$project_root/deploy/env"
   local root_env="$env_dir/.env"
   local root_example="$env_dir/.env.example"
-  local legacy_root_env="$project_root/.env"
-  local legacy_root_example="$project_root/.env.example"
-  local legacy_docker_env="$docker_dir/.env"
-  local legacy_docker_example="$docker_dir/.env.example"
+  local docker_env="$docker_dir/.env"
 
   mkdir -p "$env_dir"
   DEPLOYMENT_ROOT_ENV="$root_env"
@@ -104,15 +101,9 @@
     return 0
   fi
 
-  if [ -f "$legacy_root_env" ]; then
-    cp "$legacy_root_env" "$root_env"
-    deployment_log "✅ Created deploy/env/.env from legacy root .env"
-    return 0
-  fi
-
-  if [ -f "$legacy_docker_env" ]; then
-    cp "$legacy_docker_env" "$root_env"
-    deployment_log "✅ Created deploy/env/.env from legacy docker/.env"
+  if [ -f "$docker_env" ]; then
+    cp "$docker_env" "$root_env"
+    deployment_log "✅ Created deploy/env/.env from docker/.env"
     return 0
   fi
 
@@ -122,19 +113,7 @@
     return 0
   fi
 
-  if [ -f "$legacy_root_example" ]; then
-    cp "$legacy_root_example" "$root_env"
-    deployment_log "✅ Created deploy/env/.env from legacy root .env.example"
-    return 0
-  fi
-
-  if [ -f "$legacy_docker_example" ]; then
-    cp "$legacy_docker_example" "$root_env"
-    deployment_log "✅ Created deploy/env/.env from legacy docker/.env.example"
-    return 0
-  fi
-
-  deployment_error "deploy/env/.env not found and no .env.example template is available"
+  deployment_error "deploy/env/.env not found and no docker/.env or deploy/env/.env.example template is available"
   return 1
 }
 

@@ -51,19 +51,9 @@ def get_env(key: str, default: str = "") -> str:
 def load_environment_from_host():
     """
     Load environment variables from host .env file.
-    Looks for deploy/env/.env first, with legacy .env locations as fallbacks.
+    Looks for DEPLOYMENT_ROOT_ENV, deploy/env/.env, then docker/.env.
     """
-    script_dir = Path(__file__).resolve().parent
-    candidates = []
-    explicit_env = os.environ.get("DEPLOYMENT_ROOT_ENV")
-    if explicit_env:
-        candidates.append(Path(explicit_env))
-    candidates.extend([
-        script_dir.parent.parent.parent / "env" / ".env",  # deploy/env/.env
-        script_dir.parent.parent.parent / ".env",
-        script_dir.parent.parent / ".env",
-        script_dir.parent / ".env",
-    ])
+    candidates = get_host_env_candidates()
     env_file = next((candidate for candidate in candidates if candidate.is_file()), candidates[0])
 
     if env_file.is_file():
@@ -88,17 +78,7 @@ def get_root_dir() -> str:
     """Get ROOT_DIR from environment, normalized for the current OS."""
     root_dir = get_env("ROOT_DIR")
     if not root_dir:
-        script_dir = Path(__file__).resolve().parent
-        candidates = []
-        explicit_env = os.environ.get("DEPLOYMENT_ROOT_ENV")
-        if explicit_env:
-            candidates.append(Path(explicit_env))
-        candidates.extend([
-            script_dir.parent.parent.parent / "env" / ".env",
-            script_dir.parent.parent.parent / ".env",
-            script_dir.parent.parent / ".env",
-            script_dir.parent / ".env",
-        ])
+        candidates = get_host_env_candidates()
         env_file = next((candidate for candidate in candidates if candidate.is_file()), candidates[0])
         if env_file.is_file():
             with open(env_file, 'r') as f:
@@ -113,6 +93,27 @@ def get_root_dir() -> str:
     return root_dir
 
 
+def get_host_env_candidates():
+    """Return allowed host env files without consulting the project root .env."""
+    script_dir = Path(__file__).resolve().parent
+    candidates = []
+    explicit_env = os.environ.get("DEPLOYMENT_ROOT_ENV")
+    if explicit_env:
+        candidates.append(Path(explicit_env))
+
+    if len(script_dir.parents) >= 4:
+        deploy_root = script_dir.parents[2]
+        project_root = script_dir.parents[3]
+        candidates.extend([
+            deploy_root / "env" / ".env",
+            project_root / "docker" / ".env",
+        ])
+
+    if not candidates:
+        candidates.append(script_dir / "deploy" / "env" / ".env")
+    return candidates
+
+
 def check_container_running():
     """Check if nexent-config container is running."""
     try:

@@ -60,7 +60,7 @@ fi
 # deploy/docker/assets/scripts or from the copied ROOT_DIR/scripts directory.
 ENV_FILE="${DEPLOYMENT_ROOT_ENV:-}"
 if [ -z "$ENV_FILE" ]; then
-    for candidate in "${SCRIPT_DIR}/../../../env/.env" "${SCRIPT_DIR}/../../../../.env" "${SCRIPT_DIR}/../../../.env" "${SCRIPT_DIR}/../../.env"; do
+    for candidate in "${SCRIPT_DIR}/../../../env/.env" "${SCRIPT_DIR}/../../../../docker/.env"; do
         if [ -f "$candidate" ]; then
             ENV_FILE="$candidate"
             break

@@ -8,10 +8,7 @@
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 ENV_FILE="${DEPLOYMENT_ROOT_ENV:-$DEPLOY_ROOT/env/.env}"
 ENV_EXAMPLE="$DEPLOY_ROOT/env/.env.example"
-LEGACY_ROOT_ENV="$PROJECT_ROOT/.env"
-LEGACY_ROOT_EXAMPLE="$PROJECT_ROOT/.env.example"
-LEGACY_ENV="$PROJECT_ROOT/docker/.env"
-LEGACY_ENV_EXAMPLE="$PROJECT_ROOT/docker/.env.example"
+DOCKER_ENV="$PROJECT_ROOT/docker/.env"
 
 if [ "${NEXENT_GENERATE_ENV_SKIP_MAIN:-false}" != "true" ]; then
   echo "   📁 Target .env location: $ENV_FILE"
@@ -47,28 +44,16 @@
 
   if [ -f "$ENV_FILE" ]; then
     echo "   ✅ Using existing deploy/env/.env"
-  elif [ -f "$LEGACY_ROOT_ENV" ]; then
-    echo "   deploy/env/.env not found, copying legacy root .env..."
-    cp "$LEGACY_ROOT_ENV" "$ENV_FILE"
-    echo "   Created deploy/env/.env from legacy root .env"
-  elif [ -f "$LEGACY_ENV" ]; then
+  elif [ -f "$DOCKER_ENV" ]; then
     echo "   deploy/env/.env not found, copying docker/.env..."
-    cp "$LEGACY_ENV" "$ENV_FILE"
+    cp "$DOCKER_ENV" "$ENV_FILE"
     echo "   Created deploy/env/.env from docker/.env"
   elif [ -f "$ENV_EXAMPLE" ]; then
     echo "   📋 deploy/env/.env not found, copying .env.example..."
     cp "$ENV_EXAMPLE" "$ENV_FILE"
     echo "   ✅ Created deploy/env/.env from .env.example"
-  elif [ -f "$LEGACY_ROOT_EXAMPLE" ]; then
-    echo "   📋 deploy/env/.env not found, copying legacy root .env.example..."
-    cp "$LEGACY_ROOT_EXAMPLE" "$ENV_FILE"
-    echo "   ✅ Created deploy/env/.env from legacy root .env.example"
-  elif [ -f "$LEGACY_ENV_EXAMPLE" ]; then
-    echo "   📋 deploy/env/.env not found, copying docker/.env.example..."
-    cp "$LEGACY_ENV_EXAMPLE" "$ENV_FILE"
-    echo "   ✅ Created deploy/env/.env from docker/.env.example"
   else
-    echo "   ERROR Neither deploy/env/.env nor deploy/env/.env.example nor legacy .env files exist"
+    echo "   ERROR Neither deploy/env/.env nor docker/.env nor deploy/env/.env.example exists"
     ERROR_OCCURRED=1
     return 1
   fi

@@ -69,7 +69,7 @@ bash uninstall.sh k8s delete-all
 bash uninstall.sh k8s delete-all --keep-local-data
 ```
 
-K8s deployments read runtime configuration from `deploy/env/.env`, the same file used by Docker. Existing `deploy/env/.env` is kept as-is. If it is missing, the deploy script first reuses an existing legacy root `.env` or `docker/.env`, then falls back to `deploy/env/.env.example` or legacy templates. Do not edit generated Helm values by hand; they are recreated from `deploy/env/.env` and deployment options.
+K8s deployments read runtime configuration from `deploy/env/.env`, the same file used by Docker. Existing `deploy/env/.env` is kept as-is. If it is missing, the deploy script first reuses `docker/.env`, then falls back to `deploy/env/.env.example`. Do not edit generated Helm values by hand; they are recreated from `deploy/env/.env` and deployment options.
 
 When `--persistence-mode local` is used, Nexent renders static PVs with `hostPath` and `DirectoryOrCreate`; node affinity is not required. Shared workspace data uses `/var/lib/nexent`, shared skills use `/var/lib/nexent-data/skills`, and service data uses `/var/lib/nexent-data/nexent-*` by default.
 

@@ -202,10 +202,28 @@
 
 ENV_TEST_ROOT="$TMP_DIR/env-root"
 mkdir -p "$ENV_TEST_ROOT/docker" "$ENV_TEST_ROOT/deploy/env"
+printf 'FROM_ROOT_SHOULD_NOT_COPY=yes\n' > "$ENV_TEST_ROOT/.env"
+printf 'FROM_ROOT_EXAMPLE_SHOULD_NOT_COPY=yes\n' > "$ENV_TEST_ROOT/.env.example"
 printf 'FROM_DOCKER=yes\n' > "$ENV_TEST_ROOT/docker/.env"
 printf 'FROM_EXAMPLE=yes\n' > "$ENV_TEST_ROOT/deploy/env/.env.example"
 deployment_ensure_root_env "$ENV_TEST_ROOT" "$ENV_TEST_ROOT/docker"
 assert_contains "$(cat "$ENV_TEST_ROOT/deploy/env/.env")" "FROM_DOCKER=yes" "deploy/env/.env should migrate from docker/.env first"
+if grep -q "FROM_ROOT_SHOULD_NOT_COPY" "$ENV_TEST_ROOT/deploy/env/.env"; then
+  echo "FAIL: deploy/env/.env should not migrate from root .env"
+  exit 1
+fi
+
+DOCKER_EXAMPLE_ONLY_ROOT="$TMP_DIR/docker-example-only-root"
+mkdir -p "$DOCKER_EXAMPLE_ONLY_ROOT/docker" "$DOCKER_EXAMPLE_ONLY_ROOT/deploy/env"
+printf 'FROM_DOCKER_EXAMPLE_SHOULD_NOT_COPY=yes\n' > "$DOCKER_EXAMPLE_ONLY_ROOT/docker/.env.example"
+if deployment_ensure_root_env "$DOCKER_EXAMPLE_ONLY_ROOT" "$DOCKER_EXAMPLE_ONLY_ROOT/docker" 2>/dev/null; then
+  echo "FAIL: deploy/env/.env should not migrate from docker/.env.example"
+  exit 1
+fi
+if [ -f "$DOCKER_EXAMPLE_ONLY_ROOT/deploy/env/.env" ]; then
+  echo "FAIL: docker/.env.example should not create deploy/env/.env"
+  exit 1
+fi
 
 printf 'ROOT_ONLY=yes\n' > "$ENV_TEST_ROOT/deploy/env/.env"
 deployment_ensure_root_env "$ENV_TEST_ROOT" "$ENV_TEST_ROOT/docker"
@@ -228,6 +246,8 @@
 
 GENERATE_ENV_TEST_ROOT="$TMP_DIR/generate-env-root"
 mkdir -p "$GENERATE_ENV_TEST_ROOT/docker" "$GENERATE_ENV_TEST_ROOT/deploy/env"
+printf 'FROM_GENERATE_ROOT_SHOULD_NOT_COPY=yes\n' > "$GENERATE_ENV_TEST_ROOT/.env"
+printf 'FROM_GENERATE_ROOT_EXAMPLE_SHOULD_NOT_COPY=yes\n' > "$GENERATE_ENV_TEST_ROOT/.env.example"
 printf 'FROM_GENERATE_DOCKER=yes\n' > "$GENERATE_ENV_TEST_ROOT/docker/.env"
 printf 'FROM_GENERATE_EXAMPLE=yes\n' > "$GENERATE_ENV_TEST_ROOT/deploy/env/.env.example"
 (
@@ -236,11 +256,32 @@
   source "$SCRIPT_DIR/../docker/generate_env.sh"
   ENV_FILE="$GENERATE_ENV_TEST_ROOT/deploy/env/.env"
   ENV_EXAMPLE="$GENERATE_ENV_TEST_ROOT/deploy/env/.env.example"
-  LEGACY_ROOT_ENV="$GENERATE_ENV_TEST_ROOT/.env"
-  LEGACY_ROOT_EXAMPLE="$GENERATE_ENV_TEST_ROOT/.env.example"
-  LEGACY_ENV="$GENERATE_ENV_TEST_ROOT/docker/.env"
-  LEGACY_ENV_EXAMPLE="$GENERATE_ENV_TEST_ROOT/docker/.env.example"
+  DOCKER_ENV="$GENERATE_ENV_TEST_ROOT/docker/.env"
   prepare_env_file >/dev/null
 )
 assert_contains "$(cat "$GENERATE_ENV_TEST_ROOT/deploy/env/.env")" "FROM_GENERATE_DOCKER=yes" "generate_env should migrate docker/.env before deploy/env/.env.example"
+if grep -q "FROM_GENERATE_ROOT_SHOULD_NOT_COPY" "$GENERATE_ENV_TEST_ROOT/deploy/env/.env"; then
+  echo "FAIL: generate_env should not migrate from root .env"
+  exit 1
+fi
+
+GENERATE_DOCKER_EXAMPLE_ONLY_ROOT="$TMP_DIR/generate-docker-example-only-root"
+mkdir -p "$GENERATE_DOCKER_EXAMPLE_ONLY_ROOT/docker" "$GENERATE_DOCKER_EXAMPLE_ONLY_ROOT/deploy/env"
+printf 'FROM_GENERATE_DOCKER_EXAMPLE_SHOULD_NOT_COPY=yes\n' > "$GENERATE_DOCKER_EXAMPLE_ONLY_ROOT/docker/.env.example"
+if (
+  NEXENT_GENERATE_ENV_SKIP_MAIN=true
+  # shellcheck source=/dev/null
+  source "$SCRIPT_DIR/../docker/generate_env.sh"
+  ENV_FILE="$GENERATE_DOCKER_EXAMPLE_ONLY_ROOT/deploy/env/.env"
+  ENV_EXAMPLE="$GENERATE_DOCKER_EXAMPLE_ONLY_ROOT/deploy/env/.env.example"
+  DOCKER_ENV="$GENERATE_DOCKER_EXAMPLE_ONLY_ROOT/docker/.env"
+  prepare_env_file >/dev/null 2>&1
+); then
+  echo "FAIL: generate_env should not migrate from docker/.env.example"
+  exit 1
+fi
+if [ -f "$GENERATE_DOCKER_EXAMPLE_ONLY_ROOT/deploy/env/.env" ]; then
+  echo "FAIL: generate_env should not create deploy/env/.env from docker/.env.example"
+  exit 1
+fi
 echo "All deployment common tests passed."
@@ -26,7 +26,7 @@ bash deploy.sh docker --components infrastructure --port-policy development
 ```
 
 :::: info Important Notes
-Infrastructure mode launches PostgreSQL, Redis, Elasticsearch, and MinIO. The script generates required credentials and saves them in the project root `.env`. URLs are configured as localhost endpoints for easy local development.
+Infrastructure mode launches PostgreSQL, Redis, Elasticsearch, and MinIO. The script generates required credentials and saves them in `deploy/env/.env`. URLs are configured as localhost endpoints for easy local development.
 ::::
 
 ### 2. Backend Setup

@@ -21,7 +21,7 @@ git clone https://github.com/ModelEngine-Group/nexent.git
 cd nexent
 ```
 
-> **Tip**: Docker and Kubernetes use `deploy/env/.env`. Existing `deploy/env/.env` is kept as-is. If it does not exist, the deploy scripts first reuse an existing legacy root `.env` or `docker/.env`, then fall back to `deploy/env/.env.example` or legacy templates. If you need to configure voice models (STT/TTS), update the related values in `deploy/env/.env` before or after deployment.
+> **Tip**: Docker and Kubernetes use `deploy/env/.env`. Existing `deploy/env/.env` is kept as-is. If it does not exist, the deploy scripts first reuse `docker/.env`, then fall back to `deploy/env/.env.example`. If you need to configure voice models (STT/TTS), update the related values in `deploy/env/.env` before or after deployment.
 
 ### 2. Deployment Options
 

@@ -57,7 +57,7 @@ After running the command, the script opens Bash TUI menus for configuration. Us
 - **mainland**: uses mainland China mirrors
 - **local-latest**: uses local `latest` images and local-friendly pull policies for Nexent application images
 
-Kubernetes uses the same `deploy/env/.env` file as Docker. Existing `deploy/env/.env` is kept as-is. If it does not exist, the deploy scripts first reuse an existing legacy root `.env` or `docker/.env`, then fall back to `deploy/env/.env.example` or legacy templates.
+Kubernetes uses the same `deploy/env/.env` file as Docker. Existing `deploy/env/.env` is kept as-is. If it does not exist, the deploy scripts first reuse `docker/.env`, then fall back to `deploy/env/.env.example`.
 
 After a successful deployment, non-sensitive choices are saved to `deploy/k8s/deploy.options`. The next interactive deployment can reuse the local config or run a full reconfiguration.
 

@@ -41,7 +41,7 @@ bash deploy.sh docker
 If deploy.options is missing, the script will prompt you to select deployment settings again, such as components, port policy, and image source. Choose the same options you used for the previous deployment.
 
 >💡 Tip
-> Existing `deploy/env/.env` is kept as-is. If it is missing, the deploy script first reuses an existing legacy root `.env` or `docker/.env`, then falls back to `deploy/env/.env.example` or legacy templates.
+> Existing `deploy/env/.env` is kept as-is. If it is missing, the deploy script first reuses `docker/.env`, then falls back to `deploy/env/.env.example`.
 > If you need to configure voice models (STT/TTS), add the relevant variables to `deploy/env/.env`. We will provide a front-end configuration interface as soon as possible.
 
 

@@ -21,7 +21,7 @@ git clone https://github.com/ModelEngine-Group/nexent.git
 cd nexent
 ```
 
-> **💡 提示**: `deploy.sh` 使用 `deploy/env/.env` 作为运行配置。已有 `deploy/env/.env` 会原样保留；如果不存在，会优先复用旧的根目录 `.env` 或 `docker/.env`，再回退到 `deploy/env/.env.example` 或旧模板。若需要配置语音模型（STT/TTS），请部署前或部署后修改 `deploy/env/.env` 中的相关参数。
+> **💡 提示**: `deploy.sh` 使用 `deploy/env/.env` 作为运行配置。已有 `deploy/env/.env` 会原样保留；如果不存在，会优先复用 `docker/.env`，再回退到 `deploy/env/.env.example`。若需要配置语音模型（STT/TTS），请部署前或部署后修改 `deploy/env/.env` 中的相关参数。
 
 ### 2. 部署选项
 

@@ -57,7 +57,7 @@ bash deploy.sh k8s
 - **mainland**: 使用中国大陆镜像源
 - **local-latest**: 使用本地 `latest` 镜像，并将 Nexent 应用镜像的拉取策略设为本地优先
 
-Kubernetes 使用与 Docker 相同的`deploy/env/.env`。已有 `deploy/env/.env` 会原样保留；如果不存在，部署脚本会优先复用旧的根目录 `.env` 或 `docker/.env`，再回退到 `deploy/env/.env.example` 或旧模板。
+Kubernetes 使用与 Docker 相同的 `deploy/env/.env`。已有 `deploy/env/.env` 会原样保留；如果不存在，部署脚本会优先复用 `docker/.env`，再回退到 `deploy/env/.env.example`。
 
 部署成功后，非敏感部署选项会保存到 `deploy/k8s/deploy.options`。下次交互部署时可选择复用本地配置或重新全量配置。