@wdyy/skills 0.1.12 → 0.1.14

package/.well-known/skills/wdyy-deployment-standard/templates/deploy.sh.template

@@ -3,11 +3,11 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -P)"
 SCRIPT_PATH="$SCRIPT_DIR/$(basename -- "${BASH_SOURCE[0]}")"
-CHECKSUM_TOOL=
 BUILD_LOCK=
+STAGING_ROOT=
 DEPLOY_ROOT=
-RELEASE_VERSION=
 OPERATION=
+CHECKSUM_TOOL=
 
 fail() {
   echo "$*" >&2
@@ -15,8 +15,10 @@ fail() {
 }
 
 usage() {
-  echo "usage: ./deploy.sh build  # local project root" >&2
-  echo "       ./deploy.sh        # server project root menu" >&2
+  echo "usage: ./deploy.sh build   # local project root" >&2
+  echo "       ./deploy.sh         # server: deploy the complete stack" >&2
+  echo "       ./deploy.sh stop    # server: stop the complete stack" >&2
+  echo "       ./deploy.sh status  # server: inspect stack status" >&2
   exit 2
 }
 
@@ -24,8 +26,17 @@ require_command() {
   command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
 }
 
-assert_version() {
-  [[ "${1:-}" =~ ^[0-9]{8}-[0-9]{3}$ ]] || fail "version must match YYYYMMDD-NNN"
+select_checksum_tool() {
+  if command -v sha256sum >/dev/null 2>&1; then CHECKSUM_TOOL=sha256sum
+  elif command -v shasum >/dev/null 2>&1; then CHECKSUM_TOOL=shasum
+  else fail "required SHA-256 command not found"
+  fi
+}
+
+checksum_value() {
+  if [[ "$CHECKSUM_TOOL" == sha256sum ]]; then sha256sum "$1" | awk '{print $1}'
+  else shasum -a 256 "$1" | awk '{print $1}'
+  fi
 }
 
 assert_port() {
@@ -34,336 +45,304 @@ assert_port() {
   (( value >= 1 && value <= 65535 )) || fail "$name must be between 1 and 65535"
 }
 
+validate_env_permissions() {
+  local file="$1" mode
+  if stat -c '%a' "$file" >/dev/null 2>&1; then mode="$(stat -c '%a' "$file")"
+  else mode="$(stat -f '%Lp' "$file")"
+  fi
+  [[ "$mode" == 400 || "$mode" == 600 ]] || fail "root .env permissions must be 400 or 600; got $mode"
+}
+
 reset_configuration() {
-  unset PROJECT_NAME DOCKER_BIND_IP
   unset FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT
-  unset FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE
-  unset FRONTEND_DOCKERFILE BACKEND_DOCKERFILE DOCKERIGNORE_FILE
-  unset DEPLOY_CONFIG_DIR COMPOSE_SOURCE
+  unset API_PREFIX VITE_API_BASE_URL
+  unset DB_URL DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SCHEMA
+  unset PROJECT_NAME DOCKER_BIND_IP DOCKER_PLATFORM FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE
 }
 
-is_deployment_key() {
+is_configuration_key() {
   case "$1" in
-    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|PROJECT_NAME|DOCKER_BIND_IP|\
-    FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE|FRONTEND_DOCKERFILE|BACKEND_DOCKERFILE|\
-    DOCKERIGNORE_FILE|DEPLOY_CONFIG_DIR|COMPOSE_SOURCE)
+    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|API_PREFIX|VITE_API_BASE_URL|DB_URL|DB_PORT|DB_USER|DB_PASSWORD|DB_NAME|DB_SCHEMA|PROJECT_NAME|DOCKER_BIND_IP|DOCKER_PLATFORM|FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE)
       return 0 ;;
     *) return 1 ;;
   esac
 }
 
-is_removed_configuration_key() {
+is_removed_key() {
   case "$1" in
-    PROJECT_HTTP_PORT|FRONTEND_BLUE_PORT|FRONTEND_GREEN_PORT|BACKEND_BLUE_PORT|BACKEND_GREEN_PORT|\
-    SERVER_PROJECTS_ROOT|NGINX_SOURCE|LOG_DIR|HOST_LOG_DIR|FRONTEND_CONTAINER_PORT|\
-    BACKEND_CONTAINER_PORT|BACKEND_LISTEN_HOST|DATABASE_MIGRATION_MODE|MIGRATIONS_SOURCE|\
-    MIGRATION_RUNNER_SOURCE|*_HEALTH_URL|*_VERSION_URL)
+    PROJECT_HTTP_PORT|FRONTEND_BLUE_PORT|FRONTEND_GREEN_PORT|BACKEND_BLUE_PORT|BACKEND_GREEN_PORT|SERVER_PROJECTS_ROOT|NGINX_SOURCE|LOG_DIR|HOST_LOG_DIR|FRONTEND_CONTAINER_PORT|BACKEND_CONTAINER_PORT|BACKEND_LISTEN_HOST|DATABASE_MIGRATION_MODE|MIGRATIONS_SOURCE|MIGRATION_RUNNER_SOURCE|RELEASE_VERSION|*_HEALTH_URL|*_VERSION_URL)
       return 0 ;;
     *) return 1 ;;
   esac
 }
 
-validate_env_permissions() {
-  local file="$1" mode
-  if stat -c '%a' "$file" >/dev/null 2>&1; then mode="$(stat -c '%a' "$file")"; else mode="$(stat -f '%Lp' "$file")"; fi
-  [[ "$mode" == 400 || "$mode" == 600 ]] || fail "root .env permissions must be 400 or 600; got $mode"
-}
-
 load_dotenv() {
-  local file="$1" raw line key value first last loaded_key
+  local file="$1" raw line key value first last loaded
   local -a loaded_keys=()
-  [[ -r "$file" ]] || fail "required root environment file is missing: $file"
+  [[ -r "$file" && -f "$file" && ! -L "$file" ]] || fail "required root environment file is missing or unsafe: $file"
   validate_env_permissions "$file"
   reset_configuration
   while IFS= read -r raw || [[ -n "$raw" ]]; do
     line="${raw%$'\r'}"
     [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
     [[ "$line" =~ ^([A-Za-z_][A-Za-z0-9_]*)=(.*)$ ]] || fail "invalid .env line; expected KEY=VALUE"
-    key="${BASH_REMATCH[1]}"; value="${BASH_REMATCH[2]}"
-    ! is_removed_configuration_key "$key" || fail "removed deployment configuration is forbidden: $key"
-    for loaded_key in "${loaded_keys[@]:-}"; do [[ "$loaded_key" != "$key" ]] || fail "duplicate .env key: $key"; done
+    key="${BASH_REMATCH[1]}"
+    value="${BASH_REMATCH[2]}"
+    ! is_removed_key "$key" || fail "removed deployment configuration is forbidden: $key"
+    [[ "$value" != *'$('* && "$value" != *'`'* ]] || fail "executable syntax is forbidden in .env: $key"
+    for loaded in "${loaded_keys[@]:-}"; do [[ "$loaded" != "$key" ]] || fail "duplicate .env key: $key"; done
     loaded_keys+=("$key")
     if [[ ${#value} -ge 2 ]]; then
-      first="${value:0:1}"; last="${value: -1}"
+      first="${value:0:1}"
+      last="${value: -1}"
       if [[ "$first" == "'" || "$first" == '"' ]]; then
         [[ "$last" == "$first" ]] || fail "unclosed quoted .env value: $key"
         value="${value:1:${#value}-2}"
       fi
     fi
-    if is_deployment_key "$key"; then printf -v "$key" '%s' "$value"; export "$key"; fi
+    if is_configuration_key "$key"; then printf -v "$key" '%s' "$value"; fi
   done < "$file"
 }
 
 validate_configuration() {
-  local name
-  local -a required=(FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT PROJECT_NAME DOCKER_BIND_IP FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE)
-  for name in "${required[@]}"; do [[ -n "${!name:-}" ]] || fail "$name is required in root .env"; done
+  local key value
+  for key in FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT API_PREFIX VITE_API_BASE_URL DB_URL DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SCHEMA PROJECT_NAME DOCKER_BIND_IP DOCKER_PLATFORM FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE; do
+    value="${!key:-}"
+    [[ -n "$value" ]] || fail "required configuration is missing: $key"
+  done
   [[ "$PROJECT_NAME" =~ ^[a-z][a-z0-9_]*$ ]] || fail "PROJECT_NAME must match ^[a-z][a-z0-9_]*$"
-  for name in DOCKER_BIND_IP FRONTEND_URL BACKEND_URL; do [[ "${!name}" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "$name contains unsafe characters"; done
+  [[ "$FRONTEND_URL" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "FRONTEND_URL contains unsafe characters"
+  [[ "$BACKEND_URL" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "BACKEND_URL contains unsafe characters"
+  [[ "$API_PREFIX" =~ ^[A-Za-z][A-Za-z0-9_-]*$ ]] || fail "API_PREFIX must be one safe path segment"
+  [[ "$VITE_API_BASE_URL" == "/$API_PREFIX" ]] || fail "VITE_API_BASE_URL must equal /$API_PREFIX"
+  [[ "$DOCKER_BIND_IP" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "DOCKER_BIND_IP contains unsafe characters"
+  [[ "$DOCKER_PLATFORM" =~ ^linux/(amd64|arm64)$ ]] || fail "DOCKER_PLATFORM must be linux/amd64 or linux/arm64"
+  [[ "$DB_URL" =~ ^[A-Za-z0-9._:/?@\&=%-]+$ ]] || fail "DB_URL contains unsafe characters"
+  [[ "$FRONTEND_BASE_IMAGE" =~ ^[A-Za-z0-9._/:@-]+$ ]] || fail "FRONTEND_BASE_IMAGE is not a valid image reference"
+  [[ "$BACKEND_BASE_IMAGE" =~ ^[A-Za-z0-9._/:@-]+$ ]] || fail "BACKEND_BASE_IMAGE is not a valid image reference"
   assert_port FRONTEND_PORT "$FRONTEND_PORT"
   assert_port BACKEND_PORT "$BACKEND_PORT"
-  [[ "$FRONTEND_PORT" != "$BACKEND_PORT" ]] || fail "FRONTEND_PORT and BACKEND_PORT must be different"
-}
-
-probe_host() {
-  case "$1" in
-    0.0.0.0) printf '127.0.0.1\n' ;;
-    ::) printf '[::1]\n' ;;
-    *:*) printf '[%s]\n' "$1" ;;
-    *) printf '%s\n' "$1" ;;
-  esac
-}
-
-endpoint_url() {
-  local host
-  host="$(probe_host "$1")"
-  printf 'http://%s:%s%s\n' "$host" "$2" "$3"
-}
-
-resolve_project_path() {
-  local project_root="$1" candidate="$2"
-  if [[ "$candidate" = /* ]]; then printf '%s\n' "$candidate"; else printf '%s/%s\n' "$project_root" "$candidate"; fi
+  assert_port DB_PORT "$DB_PORT"
+  [[ "$FRONTEND_PORT" != "$BACKEND_PORT" ]] || fail "FRONTEND_PORT and BACKEND_PORT must differ"
 }
 
-select_checksum_tool() {
-  if command -v sha256sum >/dev/null 2>&1; then CHECKSUM_TOOL=sha256sum
-  elif command -v shasum >/dev/null 2>&1; then CHECKSUM_TOOL=shasum
-  else fail "sha256sum or shasum is required"
-  fi
+assert_image_platform() {
+  local image="$1" actual
+  actual="$(docker image inspect --platform "$DOCKER_PLATFORM" --format '{{.Os}}/{{.Architecture}}' "$image" 2>/dev/null)" || fail "image platform is unavailable for $image: $DOCKER_PLATFORM"
+  [[ "$actual" == "$DOCKER_PLATFORM" ]] || fail "image platform mismatch for $image: expected $DOCKER_PLATFORM, got $actual"
 }
 
-checksum_value() {
-  if [[ "$CHECKSUM_TOOL" == sha256sum ]]; then sha256sum "$1" | awk '{print $1}'; else shasum -a 256 "$1" | awk '{print $1}'; fi
+assert_server_platform() {
+  local actual
+  actual="$(docker version --format '{{.Server.Os}}/{{.Server.Arch}}' 2>/dev/null)" || fail "Docker Server platform is unavailable"
+  [[ -n "$actual" ]] || fail "Docker Server platform is empty"
+  [[ "$actual" =~ ^linux/(amd64|arm64)$ ]] || fail "unsupported Docker Server platform: $actual"
+  [[ "$actual" == "$DOCKER_PLATFORM" ]] || fail "Docker Server platform mismatch: expected $DOCKER_PLATFORM, got $actual"
 }
 
-release_ledger() {
-  node --input-type=module - "$@" <<'NODE'
-import fs from 'node:fs';
-const [mode, agentsPath, value, timestamp, outputPath] = process.argv.slice(2);
-const heading = '## 发布记录';
-const header = '| 版本号 | 构建时间 |';
-const separator = '|---|---|';
-const rowPattern = /^\| (\d{8}-\d{3}) \| (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{2}:\d{2}) \|$/;
-function fail(message) { throw new Error(message); }
-function validDate(text) { const y=Number(text.slice(0,4)),m=Number(text.slice(4,6)),d=Number(text.slice(6,8)),date=new Date(Date.UTC(y,m-1,d)); return date.getUTCFullYear()===y&&date.getUTCMonth()===m-1&&date.getUTCDate()===d; }
-function inspect(text) {
-  const lines=text.replace(/\r\n/g,'\n').split('\n');
-  const headings=lines.flatMap((line,index)=>line===heading?[index]:[]);
-  if(headings.length>1) fail('AGENTS.md contains multiple release record sections');
-  if(!headings.length) return {lines,headingIndex:-1,endIndex:lines.length,versions:[]};
-  const headingIndex=headings[0]; let endIndex=lines.length;
-  for(let index=headingIndex+1;index<lines.length;index+=1){if(/^## /.test(lines[index])){endIndex=index;break;}}
-  const section=lines.slice(headingIndex+1,endIndex); while(section[0]==='')section.shift(); while(section.at(-1)==='')section.pop();
-  if(section[0]!==header||section[1]!==separator) fail('AGENTS.md release record table is invalid');
-  const unique=new Set(),versions=[];
-  for(const row of section.slice(2)){const match=row.match(rowPattern);if(!match||!validDate(match[1].slice(0,8)))fail(`invalid AGENTS.md release record row: ${row}`);if(unique.has(match[1]))fail(`duplicate release version: ${match[1]}`);unique.add(match[1]);versions.push(match[1]);}
-  return {lines,headingIndex,endIndex,versions};
-}
-function nextVersion(ledger,date){if(!/^\d{8}$/.test(date)||!validDate(date))fail(`invalid current release date: ${date}`);const max=ledger.versions.filter(item=>item.startsWith(`${date}-`)).reduce((result,item)=>Math.max(result,Number(item.slice(-3))),0);if(max>=999)fail(`release sequence exhausted for ${date}`);return `${date}-${String(max+1).padStart(3,'0')}`;}
-const original=fs.readFileSync(agentsPath,'utf8'); const ledger=inspect(original);
-if(mode==='next') process.stdout.write(`${nextVersion(ledger,value)}\n`);
-else if(mode==='prepare'){
-  if(!/^\d{8}-\d{3}$/.test(value)||!validDate(value.slice(0,8)))fail(`invalid release version: ${value}`);
-  if(!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{2}:\d{2}$/.test(timestamp))fail('invalid build time');
-  const expected=nextVersion(ledger,value.slice(0,8));if(value!==expected)fail(`release ledger changed: expected ${expected}, got ${value}`);
-  const row=`| ${value} | ${timestamp} |`;let updated;
-  if(ledger.headingIndex===-1){const gap=original.length===0?'':original.endsWith('\n')?'\n':'\n\n';updated=`${original}${gap}${heading}\n\n${header}\n${separator}\n${row}\n`;}
-  else{const lines=[...ledger.lines];let insertAt=ledger.endIndex;while(insertAt>ledger.headingIndex+1&&lines[insertAt-1]==='')insertAt-=1;lines.splice(insertAt,0,row);updated=lines.join('\n');}
-  fs.writeFileSync(outputPath,updated,{mode:fs.statSync(agentsPath).mode});
-} else fail(`unknown release ledger mode: ${mode}`);
-NODE
+validate_dockerignore() {
+  local file="$1" pattern line
+  [[ -f "$file" && ! -L "$file" ]] || fail "required Docker ignore file is missing: $file"
+  for pattern in '.env' '.env.*' '*.pem' '*.key' id_rsa id_ed25519 credentials 'credentials.*' 'deploy/' 'logs/' '.git/' 'node_modules/' 'venv/' '.pnpm-store/' '.deploy-build.lock/' '.deploy-build.*/'; do
+    grep -Fxq "$pattern" "$file" || fail "Docker ignore file is missing required pattern: $pattern"
+  done
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ "$line" != !* || "$line" == '!.env.example' ]] || fail "Docker ignore file contains forbidden reverse include: $line"
+  done < "$file"
 }
 
 create_manifest() {
-  local version_root="$1" file relative checksum
-  (cd "$version_root"; find . -type f ! -name manifest.sha256 -print | LC_ALL=C sort | while IFS= read -r file; do relative="${file#./}"; checksum="$(checksum_value "$file")"; printf '%s  %s\n' "$checksum" "$relative"; done > manifest.sha256)
+  local root="$1" file checksum
+  : > "$root/manifest.sha256"
+  for file in .env backend-image.tar deploy.sh docker-compose.yml frontend-image.tar; do
+    checksum="$(checksum_value "$root/$file")"
+    printf '%s  %s\n' "$checksum" "$file" >> "$root/manifest.sha256"
+  done
 }
 
 verify_manifest() {
-  local root="$1" line checksum relative actual
-  [[ -s "$root/manifest.sha256" ]] || fail "missing or empty manifest.sha256"
+  local root="$1" line checksum relative actual count=0
+  [[ -s "$root/manifest.sha256" && ! -L "$root/manifest.sha256" ]] || fail "missing or unsafe manifest.sha256"
   while IFS= read -r line; do
-    checksum="${line%%  *}"; relative="${line#*  }"
-    [[ "$checksum" =~ ^[0-9a-f]{64}$ && "$relative" != "$line" && "$relative" != /* && "$relative" != ../* && "$relative" != *'/../'* ]] || fail "invalid manifest entry"
+    checksum="${line%%  *}"
+    relative="${line#*  }"
+    [[ "$checksum" =~ ^[0-9a-f]{64}$ && "$relative" != "$line" && "$relative" != /* && "$relative" != *'/'* ]] || fail "invalid manifest entry"
     [[ -f "$root/$relative" && ! -L "$root/$relative" ]] || fail "manifest path is missing: $relative"
-    actual="$(checksum_value "$root/$relative")"; [[ "$actual" == "$checksum" ]] || fail "checksum mismatch: $relative"
+    actual="$(checksum_value "$root/$relative")"
+    [[ "$actual" == "$checksum" ]] || fail "checksum mismatch: $relative"
+    count=$((count + 1))
   done < "$root/manifest.sha256"
-  local actual_paths declared_paths
-  actual_paths="$(cd "$root"; find . -type f ! -name manifest.sha256 -print | sed 's|^./||' | LC_ALL=C sort)"
-  declared_paths="$(sed -n 's/^[0-9a-f]\{64\}  //p' "$root/manifest.sha256" | LC_ALL=C sort)"
-  [[ "$actual_paths" == "$declared_paths" ]] || fail "manifest coverage is incomplete"
+  [[ "$count" == 5 ]] || fail "manifest must contain exactly five entries"
+  [[ "$(sed -n 's/^[0-9a-f]\{64\}  //p' "$root/manifest.sha256" | LC_ALL=C sort | tr '\n' '|')" == '.env|backend-image.tar|deploy.sh|docker-compose.yml|frontend-image.tar|' ]] || fail "manifest coverage is incomplete"
 }
 
-reject_version_secrets() {
-  local root="$1" file base
-  ! find "$root" -type l -print -quit | grep -q . || fail "symbolic links must not be packaged"
-  while IFS= read -r file; do base="${file##*/}"; case "$base" in .env|.env.*|*.pem|*.key|id_rsa|id_ed25519|credentials|credentials.*) fail "secret file must not enter version directory: ${file#"$root"/}" ;; esac; done < <(find "$root" -type f -print)
+validate_package_layout() {
+  local root="$1" entry name
+  for name in .env backend-image.tar deploy.sh docker-compose.yml frontend-image.tar manifest.sha256; do
+    [[ -f "$root/$name" && ! -L "$root/$name" ]] || fail "required package file is missing or unsafe: $name"
+  done
+  while IFS= read -r entry; do
+    name="${entry##*/}"
+    case "$name" in
+      .env|backend-image.tar|deploy.sh|docker-compose.yml|frontend-image.tar|manifest.sha256) ;;
+      logs) [[ -d "$entry" && ! -L "$entry" ]] || fail "logs must be a regular directory" ;;
+      *) fail "unexpected package entry: $name" ;;
+    esac
+  done < <(find "$root" -mindepth 1 -maxdepth 1 -print | LC_ALL=C sort)
 }
 
-validate_dockerignore() {
-  local file="$1" pattern line
-  [[ -f "$file" ]] || fail "required Docker ignore file is missing: $file"
-  for pattern in '.env' '.env.*' '*.pem' '*.key' id_rsa id_ed25519 credentials 'credentials.*' 'deploy/' 'logs/' '.git/' 'node_modules/' 'venv/' '.pnpm-store/' '.deploy-build.lock/' '.deploy-build.*'; do grep -Fxq "$pattern" "$file" || fail "Docker ignore file is missing required pattern: $pattern"; done
-  while IFS= read -r line || [[ -n "$line" ]]; do [[ "$line" != !* || "$line" == '!.env.example' ]] || fail "Docker ignore file contains forbidden reverse include: $line"; done < "$file"
+archive_has_tag() {
+  local archive="$1" tag="$2" manifest compact count
+  [[ -f "$archive" && ! -L "$archive" ]] || fail "image archive is missing: $archive"
+  manifest="$(tar -xOf "$archive" manifest.json 2>/dev/null)" || fail "image archive is missing manifest.json: $archive"
+  compact="$(tr -d '[:space:]' <<< "$manifest")"
+  count="$(grep -o '"RepoTags"' <<< "$compact" | wc -l | tr -d ' ')"
+  [[ "$count" == 1 && "$compact" == *"\"RepoTags\":[\"$tag\"]"* ]] || fail "image archive must contain exactly the expected tag: $tag"
+}
+
+acquire_build_lock() {
+  BUILD_LOCK="$SCRIPT_DIR/.deploy-build.lock"
+  mkdir "$BUILD_LOCK" 2>/dev/null || fail "another build is active or a stale lock exists: $BUILD_LOCK"
 }
 
-validate_local_package() {
-  local output_root="$1" version="$2" version_root="$1/$2" compose="$1/$2/docker/docker-compose.yml"
-  [[ -x "$output_root/deploy.sh" ]] || fail "generated deploy.sh is missing or not executable"
-  cmp -s "$SCRIPT_PATH" "$output_root/deploy.sh" || fail "generated deploy.sh differs from its source"
-  cmp -s "$SCRIPT_DIR/.env" "$output_root/.env" || fail "generated root .env differs from project .env"
-  [[ "$(cat "$output_root/release.env")" == "RELEASE_VERSION=$version" ]] || fail "invalid release.env"
-  [[ -f "$version_root/frontend-image.tar" && -f "$version_root/backend-image.tar" && -f "$compose" ]] || fail "dual image package is incomplete"
-  [[ "$(grep -Ec '^  (frontend|backend):$' "$compose")" == 2 ]] || fail "Compose must define frontend and backend only"
-  [[ "$(grep -Fc '../../logs:/app/logs' "$compose")" == 2 ]] || fail "both services must mount root logs"
-  ! grep -Eqi 'blue|green|nginx-upstream|PROJECT_HTTP_PORT' "$compose" || fail "blue-green or host Nginx configuration is forbidden"
-  [[ ! -e "$version_root/database" ]] || fail "release package must not contain database migration files"
-  reject_version_secrets "$version_root"; verify_manifest "$version_root"
+cleanup_build() {
+  local status=$?
+  if [[ -n "${STAGING_ROOT:-}" && -d "$STAGING_ROOT" ]]; then rm -rf -- "$STAGING_ROOT"; fi
+  if [[ -n "${BUILD_LOCK:-}" && -d "$BUILD_LOCK" ]]; then rmdir "$BUILD_LOCK" 2>/dev/null || true; fi
+  return "$status"
 }
 
-acquire_build_lock() { BUILD_LOCK="$SCRIPT_DIR/.deploy-build.lock"; mkdir "$BUILD_LOCK" 2>/dev/null || fail "another build is active or stale lock exists: $BUILD_LOCK"; }
-release_build_lock() { [[ -n "${BUILD_LOCK:-}" && -d "$BUILD_LOCK" ]] && rmdir "$BUILD_LOCK"; }
+ensure_deploy_output_scope() {
+  local deploy_dir="$1" archive_name="$2" entry
+  mkdir -p "$deploy_dir"
+  [[ -d "$deploy_dir" && ! -L "$deploy_dir" ]] || fail "deploy output must be a regular directory"
+  while IFS= read -r entry; do
+    [[ "${entry##*/}" == "$archive_name" && -f "$entry" && ! -L "$entry" ]] || fail "deploy directory contains unexpected entry: ${entry##*/}"
+  done < <(find "$deploy_dir" -mindepth 1 -maxdepth 1 -print)
+}
 
 build_release() {
-  local project_root="$SCRIPT_DIR" agents_file="$SCRIPT_DIR/AGENTS.md" today version raw_time build_time frontend_image backend_image
-  local frontend_dockerfile backend_dockerfile dockerignore_file deploy_config_dir compose_source staging_parent output_root version_root agents_prepared old_deploy
-  acquire_build_lock; staging_parent=; agents_prepared=; old_deploy=
-  trap 'rm -rf -- "${staging_parent:-}" "${old_deploy:-}"; rm -f -- "${agents_prepared:-}"; release_build_lock' EXIT
-  [[ -r "$agents_file" && -w "$agents_file" ]] || fail "project AGENTS.md must be readable and writable"
-  load_dotenv "$project_root/.env"; validate_configuration
-  frontend_dockerfile="$(resolve_project_path "$project_root" "${FRONTEND_DOCKERFILE:-src/frontend/Dockerfile}")"
-  backend_dockerfile="$(resolve_project_path "$project_root" "${BACKEND_DOCKERFILE:-src/backend/Dockerfile}")"
-  dockerignore_file="$(resolve_project_path "$project_root" "${DOCKERIGNORE_FILE:-.dockerignore}")"
-  deploy_config_dir="$(resolve_project_path "$project_root" "${DEPLOY_CONFIG_DIR:-scripts/deployment}")"
-  compose_source="$(resolve_project_path "$project_root" "${COMPOSE_SOURCE:-${deploy_config_dir#"$project_root"/}/docker-compose.yml}")"
-  for command in node pnpm docker install find sort cmp awk sed grep; do require_command "$command"; done
+  local project_root="$SCRIPT_DIR" frontend_dockerfile backend_dockerfile compose_source dockerignore_file
+  local frontend_image backend_image package_root deploy_dir archive_name candidate
+  for command in docker tar install find sort grep sed awk mktemp; do require_command "$command"; done
   select_checksum_tool
-  [[ -f "$frontend_dockerfile" && -f "$backend_dockerfile" && -f "$compose_source" ]] || fail "Dockerfiles and deployment Compose are required"
+  load_dotenv "$project_root/.env"
+  validate_configuration
+  frontend_dockerfile="$project_root/src/frontend/Dockerfile"
+  backend_dockerfile="$project_root/src/backend/Dockerfile"
+  compose_source="$project_root/scripts/deployment/docker-compose.yml"
+  dockerignore_file="$project_root/.dockerignore"
+  for file in "$frontend_dockerfile" "$backend_dockerfile" "$compose_source"; do
+    [[ -f "$file" && ! -L "$file" ]] || fail "required generated deployment file is missing: ${file#"$project_root"/}"
+  done
   validate_dockerignore "$dockerignore_file"
-  today="$(date +%Y%m%d)"; version="$(release_ledger next "$agents_file" "$today")"; assert_version "$version"
-  frontend_image="${PROJECT_NAME}_frontend:$version"; backend_image="${PROJECT_NAME}_backend:$version"
-  echo "release gate: pnpm test"; pnpm test
-  echo "release gate: pnpm lint"; pnpm lint
-  echo "release gate: pnpm typecheck"; pnpm typecheck
-  echo "release gate: pnpm build"; RELEASE_VERSION="$version" pnpm build
-  docker build --build-arg "FRONTEND_BASE_IMAGE=$FRONTEND_BASE_IMAGE" --build-arg "RELEASE_VERSION=$version" --tag "$frontend_image" --file "$frontend_dockerfile" "$project_root"
-  docker build --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "RELEASE_VERSION=$version" --build-arg "BACKEND_PORT=$BACKEND_PORT" --tag "$backend_image" --file "$backend_dockerfile" "$project_root"
-  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$frontend_image")" == "$version" ]] || fail "frontend image version label mismatch"
-  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$backend_image")" == "$version" ]] || fail "backend image version label mismatch"
-  staging_parent="$(mktemp -d "$project_root/.deploy-build.XXXXXX")"; output_root="$staging_parent/deploy"; version_root="$output_root/$version"; agents_prepared="$project_root/.AGENTS.md.release.$$.tmp"
-  mkdir -p "$version_root/docker"; install -m 0755 "$SCRIPT_PATH" "$output_root/deploy.sh"; install -m 0600 "$project_root/.env" "$output_root/.env"
-  printf 'RELEASE_VERSION=%s\n' "$version" > "$output_root/release.env"
-  docker save -o "$version_root/frontend-image.tar" "$frontend_image"; docker save -o "$version_root/backend-image.tar" "$backend_image"
-  install -m 0644 "$compose_source" "$version_root/docker/docker-compose.yml"; cmp -s "$compose_source" "$version_root/docker/docker-compose.yml" || fail "generated Compose is not deterministic"
-  create_manifest "$version_root"; validate_local_package "$output_root" "$version"
-  raw_time="$(date '+%Y-%m-%d %H:%M:%S %z')"; build_time="${raw_time%?????}${raw_time: -5:3}:${raw_time: -2}"
-  release_ledger prepare "$agents_file" "$version" "$build_time" "$agents_prepared"
-  if [[ -e "$project_root/deploy" ]]; then old_deploy="$project_root/.deploy.previous.$$"; [[ ! -e "$old_deploy" ]] || fail "temporary deploy replacement path already exists"; mv "$project_root/deploy" "$old_deploy"; fi
-  if ! mv "$output_root" "$project_root/deploy"; then [[ -n "$old_deploy" ]] && mv "$old_deploy" "$project_root/deploy"; fail "failed to publish deploy directory"; fi
-  if ! mv "$agents_prepared" "$agents_file"; then rm -rf -- "$project_root/deploy"; [[ -n "$old_deploy" ]] && mv "$old_deploy" "$project_root/deploy"; fail "failed to write AGENTS.md release record"; fi
-  [[ -n "$old_deploy" ]] && rm -rf -- "$old_deploy" && old_deploy=
-  rm -rf -- "$staging_parent"; staging_parent=; release_build_lock; BUILD_LOCK=; trap - EXIT
-  echo "release package created: deploy/$version"
+  docker image inspect "$FRONTEND_BASE_IMAGE" >/dev/null 2>&1 || fail "required local frontend base image is missing: $FRONTEND_BASE_IMAGE"
+  docker image inspect "$BACKEND_BASE_IMAGE" >/dev/null 2>&1 || fail "required local backend base image is missing: $BACKEND_BASE_IMAGE"
+  assert_image_platform "$FRONTEND_BASE_IMAGE"
+  assert_image_platform "$BACKEND_BASE_IMAGE"
+  frontend_image="${PROJECT_NAME}_frontend:latest"
+  backend_image="${PROJECT_NAME}_backend:latest"
+  acquire_build_lock
+  trap cleanup_build EXIT
+  docker build --pull=false --platform "$DOCKER_PLATFORM" --build-arg "FRONTEND_BASE_IMAGE=$FRONTEND_BASE_IMAGE" --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "VITE_API_BASE_URL=$VITE_API_BASE_URL" --tag "$frontend_image" --file "$frontend_dockerfile" "$project_root"
+  docker build --pull=false --platform "$DOCKER_PLATFORM" --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "BACKEND_PORT=$BACKEND_PORT" --tag "$backend_image" --file "$backend_dockerfile" "$project_root"
+  docker image inspect "$frontend_image" >/dev/null 2>&1 || fail "frontend image build did not create $frontend_image"
+  docker image inspect "$backend_image" >/dev/null 2>&1 || fail "backend image build did not create $backend_image"
+  assert_image_platform "$frontend_image"
+  assert_image_platform "$backend_image"
+  STAGING_ROOT="$(mktemp -d "$project_root/.deploy-build.XXXXXX")"
+  package_root="$STAGING_ROOT/package"
+  mkdir -p "$package_root"
+  install -m 0600 "$project_root/.env" "$package_root/.env"
+  install -m 0755 "$SCRIPT_PATH" "$package_root/deploy.sh"
+  install -m 0644 "$compose_source" "$package_root/docker-compose.yml"
+  docker save -o "$package_root/frontend-image.tar" "$frontend_image"
+  docker save -o "$package_root/backend-image.tar" "$backend_image"
+  archive_has_tag "$package_root/frontend-image.tar" "$frontend_image"
+  archive_has_tag "$package_root/backend-image.tar" "$backend_image"
+  create_manifest "$package_root"
+  validate_package_layout "$package_root"
+  verify_manifest "$package_root"
+  deploy_dir="$project_root/deploy"
+  archive_name="${PROJECT_NAME}-docker.tar.gz"
+  ensure_deploy_output_scope "$deploy_dir" "$archive_name"
+  candidate="$STAGING_ROOT/$archive_name"
+  env COPYFILE_DISABLE=1 tar --no-xattrs -czf "$candidate" -C "$package_root" .
+  tar -tzf "$candidate" >/dev/null || fail "generated delivery archive is invalid"
+  mv -f "$candidate" "$deploy_dir/$archive_name"
+  rm -rf -- "$STAGING_ROOT"
+  STAGING_ROOT=
+  rmdir "$BUILD_LOCK"
+  BUILD_LOCK=
+  trap - EXIT
+  echo "delivery archive created: deploy/$archive_name"
 }
 
-read_release_pointer() {
-  local file="$DEPLOY_ROOT/release.env" line
-  [[ -f "$file" && "$(wc -l < "$file" | tr -d ' ')" == 1 ]] || fail "release.env must contain exactly one line"
-  line="$(cat "$file")"; [[ "$line" =~ ^RELEASE_VERSION=([0-9]{8}-[0-9]{3})$ ]] || fail "invalid release.env"
-  RELEASE_VERSION="${BASH_REMATCH[1]}"; assert_version "$RELEASE_VERSION"
+initialize_server_context() {
+  DEPLOY_ROOT="$SCRIPT_DIR"
+  for command in docker tar find sort grep sed awk; do require_command "$command"; done
+  select_checksum_tool
+  load_dotenv "$DEPLOY_ROOT/.env"
+  validate_configuration
+  [[ -f "$DEPLOY_ROOT/docker-compose.yml" && ! -L "$DEPLOY_ROOT/docker-compose.yml" ]] || fail "docker-compose.yml is missing"
+  mkdir -p "$DEPLOY_ROOT/logs"
 }
 
-initialize_server_context() {
-  DEPLOY_ROOT="$SCRIPT_DIR"; load_dotenv "$DEPLOY_ROOT/.env"; validate_configuration; read_release_pointer
-  for command in docker curl tar find sort awk sed grep; do require_command "$command"; done
-  select_checksum_tool; mkdir -p "$DEPLOY_ROOT/logs"
+compose() {
+  docker compose --env-file "$DEPLOY_ROOT/.env" --project-name "$PROJECT_NAME" -f "$DEPLOY_ROOT/docker-compose.yml" "$@"
 }
 
 record_operation() {
   local result="$1" timestamp
   [[ -n "$DEPLOY_ROOT" && -d "$DEPLOY_ROOT/logs" && -n "$OPERATION" ]] || return 0
   timestamp="$(date '+%Y-%m-%d %H:%M:%S %z')"
-  printf '%s version=%s operation=%s result=%s\n' "$timestamp" "${RELEASE_VERSION:-unknown}" "$OPERATION" "$result" >> "$DEPLOY_ROOT/logs/deploy.log"
-}
-
-validate_uploaded_package() {
-  local root="$DEPLOY_ROOT/$RELEASE_VERSION"
-  [[ -f "$root/frontend-image.tar" && -f "$root/backend-image.tar" && -f "$root/docker/docker-compose.yml" ]] || fail "uploaded dual image package is incomplete"
-  [[ ! -e "$root/database" ]] || fail "release package must not contain database migration files"
-  reject_version_secrets "$root"; verify_manifest "$root"
-  tar -tf "$root/frontend-image.tar" >/dev/null || fail "invalid frontend image archive"
-  tar -tf "$root/backend-image.tar" >/dev/null || fail "invalid backend image archive"
-}
-
-archive_has_tag() {
-  local archive="$1" tag="$2" manifest compact count
-  manifest="$(tar -xOf "$archive" manifest.json 2>/dev/null)" || fail "image archive is missing manifest.json: $archive"
-  compact="$(tr -d '[:space:]' <<< "$manifest")"; count="$(grep -o '"RepoTags"' <<< "$compact" | wc -l | tr -d ' ')"
-  [[ "$count" == 1 && "$compact" == *"\"RepoTags\":[\"$tag\"]"* ]] || fail "image archive must contain exactly one expected tag: $tag"
-}
-
-image_names() { FRONTEND_IMAGE="${PROJECT_NAME}_frontend:$RELEASE_VERSION"; BACKEND_IMAGE="${PROJECT_NAME}_backend:$RELEASE_VERSION"; export FRONTEND_IMAGE BACKEND_IMAGE RELEASE_VERSION; }
-
-load_frontend_image() {
-  local archive="$DEPLOY_ROOT/$RELEASE_VERSION/frontend-image.tar"
-  archive_has_tag "$archive" "$FRONTEND_IMAGE"; docker load -i "$archive" >/dev/null
-  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$FRONTEND_IMAGE")" == "$RELEASE_VERSION" ]] || fail "frontend loaded image version mismatch"
-}
-
-load_backend_image() {
-  local archive="$DEPLOY_ROOT/$RELEASE_VERSION/backend-image.tar"
-  archive_has_tag "$archive" "$BACKEND_IMAGE"; docker load -i "$archive" >/dev/null
-  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$BACKEND_IMAGE")" == "$RELEASE_VERSION" ]] || fail "backend loaded image version mismatch"
-}
-
-compose() {
-  FRONTEND_IMAGE="$FRONTEND_IMAGE" BACKEND_IMAGE="$BACKEND_IMAGE" RELEASE_VERSION="$RELEASE_VERSION" docker compose --env-file "$DEPLOY_ROOT/.env" --project-name "$PROJECT_NAME" -f "$DEPLOY_ROOT/$RELEASE_VERSION/docker/docker-compose.yml" "$@"
+  printf '%s operation=%s result=%s\n' "$timestamp" "$OPERATION" "$result" >> "$DEPLOY_ROOT/logs/deploy.log"
+}
+
+deploy_stack() {
+  local frontend_image="${PROJECT_NAME}_frontend:latest" backend_image="${PROJECT_NAME}_backend:latest"
+  validate_package_layout "$DEPLOY_ROOT"
+  verify_manifest "$DEPLOY_ROOT"
+  archive_has_tag "$DEPLOY_ROOT/frontend-image.tar" "$frontend_image"
+  archive_has_tag "$DEPLOY_ROOT/backend-image.tar" "$backend_image"
+  assert_server_platform
+  docker load -i "$DEPLOY_ROOT/frontend-image.tar" >/dev/null
+  docker load -i "$DEPLOY_ROOT/backend-image.tar" >/dev/null
+  assert_image_platform "${PROJECT_NAME}_frontend:latest"
+  assert_image_platform "${PROJECT_NAME}_backend:latest"
+  docker image inspect "$frontend_image" >/dev/null 2>&1 || fail "loaded frontend image is missing: $frontend_image"
+  docker image inspect "$backend_image" >/dev/null 2>&1 || fail "loaded backend image is missing: $backend_image"
+  compose up -d --force-recreate --no-build --pull never --wait frontend backend
+}
+
+run_logged_operation() {
+  local operation="$1"
+  shift
+  OPERATION="$operation"
+  trap 'status=$?; if [[ $status -eq 0 ]]; then record_operation success; else record_operation failure; fi' EXIT
+  "$@"
+  trap - EXIT
+  record_operation success
 }
 
-verify_service() {
-  local service="$1" port health version_url actual
-  if [[ "$service" == frontend ]]; then port="$FRONTEND_PORT"; else port="$BACKEND_PORT"; fi
-  health="$(endpoint_url "$DOCKER_BIND_IP" "$port" /health)"; version_url="$(endpoint_url "$DOCKER_BIND_IP" "$port" /version)"
-  curl --fail --silent --show-error --retry 12 --retry-delay 2 --retry-connrefused "$health" >/dev/null
-  actual="$(curl --fail --silent --show-error "$version_url")"
-  [[ "$actual" == "$RELEASE_VERSION" ]] || fail "$service version mismatch: expected $RELEASE_VERSION, got $actual"
+server_deploy() {
+  initialize_server_context
+  run_logged_operation deploy deploy_stack
 }
 
-run_or_replace() {
-  local target="$1"
-  validate_uploaded_package; image_names
-  case "$target" in
-    frontend) load_frontend_image; compose up -d --force-recreate --no-deps frontend; verify_service frontend ;;
-    backend) load_backend_image; compose up -d --force-recreate --no-deps backend; verify_service backend ;;
-    both) load_frontend_image; load_backend_image; compose up -d --force-recreate frontend backend; verify_service frontend; verify_service backend ;;
-    *) fail "invalid deployment target: $target" ;;
-  esac
+server_stop() {
+  initialize_server_context
+  run_logged_operation stop compose stop frontend backend
 }
 
-stop_services() { image_names; compose stop frontend backend; }
-
-server_menu() {
-  local choice status
+server_status() {
   initialize_server_context
-  printf '%s\n' '1. 运行或替换前端' '2. 运行或替换后端' '3. 运行或替换前后端' '4. 停止'
-  IFS= read -r choice || fail "failed to read deployment menu selection"
-  case "$choice" in
-    1) OPERATION=run-or-replace-frontend ;;
-    2) OPERATION=run-or-replace-backend ;;
-    3) OPERATION=run-or-replace-both ;;
-    4) OPERATION=stop-both ;;
-    *) OPERATION=invalid-selection; record_operation failure; fail "invalid deployment menu selection: $choice" ;;
-  esac
-  trap 'status=$?; if [[ $status -eq 0 ]]; then record_operation success; else record_operation failure; fi' EXIT
-  case "$choice" in
-    1) run_or_replace frontend ;;
-    2) run_or_replace backend ;;
-    3) run_or_replace both ;;
-    4) stop_services ;;
-  esac
+  compose ps frontend backend
 }
 
-if [[ "$#" -eq 0 ]]; then server_menu
+if [[ "$#" -eq 0 ]]; then server_deploy
 elif [[ "$#" -eq 1 && "$1" == build ]]; then build_release
+elif [[ "$#" -eq 1 && "$1" == stop ]]; then server_stop
+elif [[ "$#" -eq 1 && "$1" == status ]]; then server_status
 else usage
 fi