From 29c86509e971e933d55ec8b040b0fe68bc9ba940 Mon Sep 17 00:00:00 2001 From: Martin <60476606+mtmtian@users.noreply.github.com> Date: Thu, 20 Aug 2026 04:27:27 +0800 Subject: [PATCH] document CStoneCloud panel handoff --- README.md | 7 +++--- deploy-vps.sh | 2 +- docs/provider-onboarding.md | 6 +++--- docs/repository-guide.md | 4 ++-- docs/vps-migration.md | 43 ++++++++++++++++++++++++++----------- providers/vps.sh | 2 +- 6 files changed, 40 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 6df500b..466ee3c 100644 --- a/README.md +++ b/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 \ --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 \ diff --git a/deploy-vps.sh b/deploy-vps.sh index 47d5cb0..18b708e 100755 --- a/deploy-vps.sh +++ b/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 } diff --git a/docs/provider-onboarding.md b/docs/provider-onboarding.md index 7fdbbc9..d72b887 100644 --- a/docs/provider-onboarding.md +++ b/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 \ --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//deploy.conf` and `.secrets.env`, secures the host, creates the `mt` sudo user, installs the shared protocols, and writes: diff --git a/docs/repository-guide.md b/docs/repository-guide.md index b3be7b9..260c3d3 100644 --- a/docs/repository-guide.md +++ b/docs/repository-guide.md @@ -43,10 +43,10 @@ docs/ 架构、排障和运维说明 ```bash ./deploy-vps.sh --profile cstone-next --host \ --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（当前未使用） diff --git a/docs/vps-migration.md b/docs/vps-migration.md index b990eb4..4fcc838 100644 --- a/docs/vps-migration.md +++ b/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: - - -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 \ --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 \ @@ -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. diff --git a/providers/vps.sh b/providers/vps.sh index 01310e6..9168b5e 100755 --- a/providers/vps.sh +++ b/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}"