Document CStoneCloud panel handoff

README.md

@@ -15,20 +15,19 @@ One shared proxy core. The active path configures an existing CStoneCloud or oth
 
 ### CStoneCloud / 已有 Debian/Ubuntu VPS
 
-新机安装 Debian/Ubuntu 后，若 CStoneCloud 面板只提供 root 密码，可用一条命令交互式安装本机公钥、复制旧 cstone 的非密钥配置、生成全新凭据并部署：
+新机安装 Debian/Ubuntu 后，优先在 CStoneCloud 面板的「SSH 密钥」页面绑定本机公钥，然后复制旧 cstone 的非密钥配置、生成全新凭据并部署：
 
 ```bash
 ./deploy-vps.sh \
   --profile cstone-next \
   --host <VPS_PUBLIC_IP> \
   --ssh-key "$HOME/.ssh/cstone_ed25519" \
-  --install-key \
   --copy-config-from cstone
 ```
 
-`--install-key` 只在首次使用，它会调用系统 `ssh-copy-id` 并在终端中提示输入面板给出的一次性 root 密码；密码不会写入项目、参数或日志。该私钥旁需要存在同名 `.pub` 公钥文件。
+绑定后先用一个新终端验证 root 公钥登录。若面板没有注入公钥，再加 `--install-key`：它会调用系统 `ssh-copy-id` 并交互式提示输入 root 密码；密码不会写入项目、参数或日志。该私钥旁需要存在同名 `.pub` 公钥文件。
 
-如果面板已经注入本机公钥，去掉 `--install-key` 即可。部署前也可先做不改远端、不创建 profile 的 readiness 检查：
+部署前也可先做不改远端、不创建 profile 的 readiness 检查：
 
 ```bash
 ./deploy-vps.sh --profile cstone-next --host <VPS_PUBLIC_IP> \

deploy-vps.sh

@@ -23,7 +23,7 @@ usage() {
 
 示例：
   ./deploy-vps.sh --profile cstone-next --host 203.0.113.10 \
-    --ssh-key "$HOME/.ssh/cstone_ed25519" --install-key \
+    --ssh-key "$HOME/.ssh/cstone_ed25519" \
     --copy-config-from cstone
 USAGE
 }

docs/provider-onboarding.md

@@ -5,16 +5,16 @@ Use one profile per server. A profile name is a local namespace for the server's
 ## Existing Debian/Ubuntu VPS
 
 1. Install Debian 12/13 64-bit or Ubuntu 24.04 LTS.
-2. Confirm root SSH access with a public key, or use the provider's one-time root password with `--install-key`. Keep the private key on the local machine only.
+2. Prefer binding a saved public key in the provider panel, then verify root key login from a new terminal. If that fails, use the provider's root password interactively with `--install-key`. Keep the private key on the local machine only.
 3. Run the generic VPS entry point with an explicit, unique profile name. For a CStoneCloud replacement that should inherit cstone's non-secret settings:
 
 ```bash
 ./deploy-vps.sh --profile cstone-next --host <VPS_PUBLIC_IP> \
   --ssh-key "$HOME/.ssh/cstone_ed25519" \
-  --install-key --copy-config-from cstone
+  --copy-config-from cstone
 ```
 
-Omit `--install-key` if the provider already installed the public key. Use a different profile for every server, for example `cstone`, `cstone-next`, or `new-york-01`. Do not run `./deploy-vps.sh` without a profile.
+Add `--install-key` only if the provider did not install the public key. Use a different profile for every server, for example `cstone`, `cstone-next`, or `new-york-01`. Do not run `./deploy-vps.sh` without a profile.
 
 The first run creates `profiles/<profile>/deploy.conf` and `.secrets.env`, secures the host, creates the `mt` sudo user, installs the shared protocols, and writes:
 

docs/repository-guide.md

@@ -43,10 +43,10 @@ docs/                          架构、排障和运维说明
 ```bash
 ./deploy-vps.sh --profile cstone-next --host <VPS_PUBLIC_IP> \
   --ssh-key "$HOME/.ssh/cstone_ed25519" \
-  --install-key --copy-config-from cstone
+  --copy-config-from cstone
 ```
 
-VPS 适配器负责可选的交互式公钥安装、远端 readiness、创建 `mt` 管理员、UFW 和文件上传。每台 VPS 必须使用唯一 profile，避免误读另一台服务器的状态。迁移时只复制旧 profile 的非密钥 `deploy.conf`，不会复制凭据或客户端 YAML。
+优先在商家面板绑定 SSH 公钥；只有面板注入失败时才加 `--install-key`。VPS 适配器负责可选的交互式公钥安装、远端 readiness、创建 `mt` 管理员、UFW 和文件上传。每台 VPS 必须使用唯一 profile，避免误读另一台服务器的状态。迁移时只复制旧 profile 的非密钥 `deploy.conf`，不会复制凭据或客户端 YAML。
 
 ### GCP（当前未使用）
 

docs/vps-migration.md

@@ -4,39 +4,56 @@ The migration contract is intentionally conservative: build a new isolated profi
 
 ## Current CStoneCloud boundary
 
-As checked on 2026-08-20, CStoneCloud's public site documents a panel-provided Linux `root` password and SSH on port 22, but its public help center does not expose a supported VPS API or CLI for reinstalling the OS, injecting a key, or reading lifecycle state:
+As checked in the authenticated panel on 2026-08-20, CStoneCloud provides:
+
+- power on/off, reboot, hard power actions, VNC, OS reinstall and rescue mode;
+- a reusable SSH-key list with an explicit bind action for the instance;
+- Debian 12 x64 and Ubuntu 24.04 x64 images;
+- an authentication selector and generated root password in the reinstall dialog.
+
+The password is displayed in clear text. Do not put it in screenshots, shell arguments, repository files or chat. If it is exposed before reinstall, cancel and generate another value; if it was already applied, rotate it.
+
+The public help center still does not expose a supported non-interactive VPS API or CLI for these operations:
 
 - <https://www.cstonecloud.com/index.php?rp=%2Fannouncements%2F1%2FTOSandAUP.html>
 - <https://www.cstonecloud.com/knowledgebase>
 
-Therefore this repository automates from the first stable provider boundary: a Debian/Ubuntu host with a public IP and working root SSH. It does not scrape the authenticated panel or drive an unknown interactive console.
+Therefore this repository automates from the first stable provider boundary: a Debian/Ubuntu host with a public IP and working root SSH. Power, reinstall, rescue and key binding remain explicit panel actions; the project does not scrape or browser-automate the authenticated panel.
+
+## Panel handoff
+
+1. Create or reuse an SSH public key in the panel. Never upload the private key.
+2. Reinstall with a supported Debian/Ubuntu x64 image. If the authentication selector offers the saved SSH key, prefer it; otherwise use a newly generated root password.
+3. Bind the saved key to the instance after reinstall if it is not already bound. Reinstall may replace `authorized_keys`, so do not assume an older binding survived.
+4. From a new local terminal, verify key-only root login before running this project. Do not close the panel/VNC recovery path until this succeeds.
+5. Use `--install-key` only when key binding did not produce a working login. Enter the root password interactively; never put it on the command line.
+
+Do not test reinstall or key-removal behavior on the active node merely to validate this runbook. Confirm it during a replacement-node migration where rollback remains available.
 
 ## One-command host handoff
 
 Prepare a local keypair once. Keep the private key local and ensure the matching `.pub` file exists beside it.
 
-For a replacement server that should use cstone's non-secret settings:
+For a replacement server with the panel-bound key already verified, use cstone's non-secret settings:
 
 ```bash
 ./deploy-vps.sh \
   --profile cstone-next \
   --host <NEW_PUBLIC_IP> \
   --ssh-key "$HOME/.ssh/cstone_ed25519" \
-  --install-key \
   --copy-config-from cstone
 ```
 
 This sequence:
 
-1. Uses `ssh-copy-id` to install the public key when the new host initially exposes only a root password. The password is entered interactively and is never stored by this project.
-2. Checks Debian/Ubuntu, x86_64/aarch64, root or passwordless sudo, and systemd before creating profile state.
-3. Copies only `profiles/cstone/deploy.conf`. It never copies `.secrets.env`, SSH keys, or generated client YAML.
-4. Generates independent credentials under `profiles/cstone-next/`.
-5. Creates and verifies the `mt` sudo user before disabling root/password SSH.
-6. Installs the server stack and fails the deployment if any required systemd unit is inactive.
-7. Generates `clash-configs/cstone-next-*.yaml` without changing cstone's files.
+1. Checks Debian/Ubuntu, x86_64/aarch64, root or passwordless sudo, and systemd before creating profile state.
+2. Copies only `profiles/cstone/deploy.conf`. It never copies `.secrets.env`, SSH keys, or generated client YAML.
+3. Generates independent credentials under `profiles/cstone-next/`.
+4. Creates and verifies the `mt` sudo user before disabling root/password SSH.
+5. Installs the server stack and fails the deployment if any required systemd unit is inactive.
+6. Generates `clash-configs/cstone-next-*.yaml` without changing cstone's files.
 
-If the public key is already installed, omit `--install-key`. To validate an already keyed host without changing it:
+If panel key binding is unavailable or unsuccessful, add `--install-key` to the deployment command. It uses `ssh-copy-id`; the root password is entered interactively and is never stored by this project. To validate an already keyed host without changing it:
 
 ```bash
 ./deploy-vps.sh --profile cstone-next --host <NEW_PUBLIC_IP> \
@@ -52,4 +69,4 @@ If the public key is already installed, omit `--install-key`. To validate an alr
 
 ## Provider lifecycle automation later
 
-A dedicated `providers/cstonecloud.sh` is justified only if the provider supplies a documented, non-interactive API/CLI for OS reinstall, SSH-key injection and instance/IP status. If the panel's "command-line tool" has a product name or a redacted help screen, capture that interface first; do not automate it with brittle keystroke scripts by default.
+A dedicated `providers/cstonecloud.sh` is justified only if the provider supplies a documented, non-interactive API/CLI for OS reinstall, SSH-key injection and instance/IP status. The current authenticated web controls are useful recovery and bootstrap tools, but their destructive actions and unstable UI contract make browser automation a poor default.

providers/vps.sh

@@ -48,7 +48,7 @@ provider_preflight() {
       'true' >/dev/null 2>&1; then
       ok "目标已接受当前 SSH key，跳过公钥安装"
     else
-      say "将交互式安装 SSH 公钥；请输入 CStoneCloud 面板中的一次性 root 密码"
+      say "将交互式安装 SSH 公钥；请输入商家面板中的 root 密码"
       ssh-copy-id -i "${VPS_SSH_KEY}.pub" -p "$VPS_SSH_PORT" \
         -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new \
         -o ConnectTimeout=10 "${VPS_BOOTSTRAP_USER}@${VPS_HOST}"