From 9501e03e197bef7fffc7d5a53f46e25516c96c68 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Mon, 2 Nov 2026 15:28:27 +0800
Subject: [PATCH] docs(deploy): distinguish runtime and source configuration
 updates

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 docs/09-deployment.md                | 21 ++++++++++++++++-----
 docs/skillhub/en/guide/deployment.md | 12 +++++++++---
 2 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/docs/09-deployment.md b/docs/09-deployment.md
index 34c9e648b..cf6a7a930 100644
--- a/docs/09-deployment.md
+++ b/docs/09-deployment.md
@@ -25,16 +25,27 @@ CLI 再轮询兑换 Token。完成后用 `skillhub whoami --registry https://ski
 - Compose 的空配置交由后端处理；Helm 的 `deviceAuthVerificationUri` 默认对应
   `<publicBaseUrl>/device`，也可显式覆盖。
 
-对已运行的单机交付栈，仅修改设备授权地址时，在原部署目录保留相同的项目名和 override，执行：
+对已运行的单机交付栈，仅修改设备授权地址时，先编辑原部署目录中的 `.env.release`：
+
+- 源码部署：在包含 `Makefile` 和 `scripts/validate-release-config.sh` 的仓库根目录，
+  先执行 `make validate-release-config`，修正错误后再重建。
+- 一键脚本部署：进入脚本输出的 `Runtime dir`（即该实例的 `--home` 目录）。脚本仅下载
+  Compose 清单和环境模板，不提供上述 Make 校验入口，不要在该目录执行 `make`。
+
+以下重建命令适用于未自定义项目名、未使用 override 的标准栈：
 
 ```bash
-make validate-release-config
 docker compose --env-file .env.release -f compose.release.yml up -d --no-deps --force-recreate server
 ```
 
-以上命令用于更新已有后端容器；首次部署仍使用完整栈的 `up -d`。若同时修改公开地址等
-其他服务也使用的配置，应一并重建相应服务。重新执行 CLI 登录并核对返回的授权地址，
-不要仅凭配置文件内容判断已生效。
+若原部署使用了 `-p`、`COMPOSE_PROJECT_NAME` 或额外的 `-f` 文件，重建时必须保留原项目名、
+环境文件及按原顺序排列的全部 `-f` 参数，不能直接照抄以上基础命令；否则可能操作另一实例
+或丢失 override 中的配置。此操作只重建已有后端容器，不重新下载部署文件。
+
+首次部署仍使用完整栈的 `up -d`。若同时修改公开地址等其他服务也使用的配置，
+应一并重建相应服务。验证设备授权地址时，使用未传 `--token`、未设置 `SKILLHUB_TOKEN`，
+且该 registry 没有保存凭据的 CLI 环境，再执行上述登录命令并核对返回地址；
+已有 Token 的登录成功不能证明设备授权地址已更新。不要仅凭配置文件内容判断已生效。
 
 `/cli/auth` 是旧版浏览器 loopback 回调入口，需要客户端附带回调参数；它不是输入设备码的页面。
 不要将设备授权地址设成这个旧入口。此次配置保护不改变旧客户端回调流程。
diff --git a/docs/skillhub/en/guide/deployment.md b/docs/skillhub/en/guide/deployment.md
index 111cc383e..a7201bac5 100644
--- a/docs/skillhub/en/guide/deployment.md
+++ b/docs/skillhub/en/guide/deployment.md
@@ -46,14 +46,20 @@ Suite review writes are enabled by default in the single-server release Compose
 - Without a public base URL, the compatibility fallback is `/device`, resolved by the CLI against the registry origin. Set the actual public Web URL for production, sub-path, or separate Web/API deployments.
 - An explicit valid HTTP(S) URL or root-relative path overrides the default. Invalid values prevent startup without echoing the configured value. `/cli/auth` is the legacy loopback callback, not the device-code entry page.
 
-After changing this setting in `.env.release`, recreate the backend in the existing deployment directory, preserving its Compose project name and overrides:
+Edit `.env.release` in the existing deployment directory before recreating the backend:
+
+- Source checkout: run `make validate-release-config` from the repository root containing `Makefile` and `scripts/validate-release-config.sh`, and resolve errors before recreation.
+- One-click script installation: use the `Runtime dir` printed by the script (the instance's `--home` directory). The script downloads the Compose file and environment template, not the Make validation tooling; do not run `make` in that directory.
+
+The following command applies to a standard stack without a custom project name or override files:
 
 ```bash
-make validate-release-config
 docker compose --env-file .env.release -f compose.release.yml up -d --no-deps --force-recreate server
 ```
 
-This updates an already running stack; use the full `up -d` for an initial deployment. A plain `restart` does not reload container environment variables. If other shared settings changed, recreate their affected services too. Retry device authorization and check the returned public URL without sharing codes or tokens. See the [operations reference](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md) for the full configuration contract.
+If the original deployment uses `-p`, `COMPOSE_PROJECT_NAME`, or additional `-f` files, retain its project name, environment file and every `-f` argument in the original order. Do not copy the base command unchanged: it could target another instance or omit override settings. This only recreates the existing backend; it does not download deployment files again.
+
+Use the full `up -d` for an initial deployment. A plain `restart` does not reload container environment variables. If other shared settings changed, recreate their affected services too. To verify the device URL, retry the login command without `--token`, `SKILLHUB_TOKEN`, or saved credentials for that registry, and check the returned public URL. Successful login with an existing token does not verify the device URL. Do not share codes or tokens. See the [operations reference](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md) for the full configuration contract.
 
 ## Upgrade, stop, and troubleshoot