@h-ai/deploy 0.1.0-alpha.55 → 0.1.0-alpha.57

package/README.en.md

@@ -0,0 +1,243 @@
+# @h-ai/deploy
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
+
+An automated deployment module with two targets: deploy SvelteKit apps to Vercel with cloud infrastructure provisioning, or containerize and deploy to any Linux host over SSH (docker-ssh).
+
+## Deployment targets
+
+| Provider     | Target          | Description                                                   |
+| ------------ | --------------- | ------------------------------------------------------------- |
+| `vercel`     | Vercel platform | SvelteKit + adapter-vercel with cloud provisioners            |
+| `docker-ssh` | Any Linux host  | SvelteKit + adapter-node, containerized and deployed over SSH |
+
+## Cloud services (provisioners)
+
+| Service type | Provisioner   | Description                     |
+| ------------ | ------------- | ------------------------------- |
+| Database     | Neon          | PostgreSQL Serverless           |
+| Cache        | Upstash       | Redis TCP + TLS                 |
+| Storage      | Cloudflare R2 | S3-compatible object storage    |
+| Email        | Resend        | SMTP (existing verified domain) |
+| SMS          | Alibaba Cloud | Alibaba Cloud SMS               |
+
+## Quick start
+
+```typescript
+import { deploy } from '@h-ai/deploy'
+
+// 可选：从 ~/.hai/credentials.yml 注入 HAI_DEPLOY_* 环境变量
+deploy.credentials.load()
+
+// 初始化
+await deploy.init({
+  provider: { type: 'vercel', token: 'vel_xxx' },
+  services: {
+    db: { provisioner: 'neon', apiKey: 'neon_xxx' },
+    cache: { provisioner: 'upstash', email: 'a@b.com', apiKey: 'up_xxx' },
+  },
+})
+
+// 扫描应用依赖
+const scan = await deploy.scan('./apps/my-app')
+
+// 开通基础设施
+const provisions = await deploy.provisionAll('my-app')
+
+// 完整部署
+const result = await deploy.deployApp('./apps/my-app')
+
+await deploy.close()
+```
+
+## Configuration
+
+Keep Git-safe configuration in `config/_deploy.yml` and secrets in `~/.hai/credentials.yml`:
+
+```yaml
+# config/_deploy.yml
+provider:
+  type: vercel
+  token: ${HAI_DEPLOY_VERCEL_TOKEN}
+
+services:
+  db:
+    provisioner: neon
+    apiKey: ${HAI_DEPLOY_NEON_API_KEY}
+  cache:
+    provisioner: upstash
+    email: ${HAI_DEPLOY_UPSTASH_EMAIL}
+    apiKey: ${HAI_DEPLOY_UPSTASH_API_KEY}
+```
+
+These variables are explicit special mappings managed by `deploy.credentials`. If convention-based variables
+such as `HAI_DEPLOY_PROVIDER_TOKEN` are also set, the convention-based variables take precedence.
+
+Use `deploy.credentials.*` to manage credential files explicitly in scripts or the CLI:
+
+```typescript
+deploy.credentials.load()
+deploy.credentials.save('HAI_DEPLOY_VERCEL_TOKEN', 'vel_xxx')
+deploy.credentials.saveAll({
+  HAI_DEPLOY_NEON_API_KEY: 'neon_xxx',
+})
+```
+
+> `deploy.scan()` and `deploy.credentials.*()` use the local filesystem and do not require `deploy.init()`.
+
+## docker-ssh deployment
+
+Containerize the application and deploy over SSH to any Linux host; no cloud account is required.
+
+### Prerequisites
+
+- **Local**: install docker or podman (`auto` prefers podman).
+- **Remote host**: SSH access, docker/podman and compose installed, and a login user permitted to run containers.
+- **Application**: SvelteKit must use `@sveltejs/adapter-node` (covered by the supplied `Dockerfile`); otherwise `ADAPTER_MISSING` is returned.
+
+### Steps
+
+1. Store the SSH private key path in the credential file, outside the repository. Edit `~/.hai/credentials.yml` or use the API:
+
+```typescript
+deploy.credentials.save('HAI_DEPLOY_SSH_KEY', '~/.ssh/hai_deploy')
+```
+
+2. Declare the target host in `config/_deploy.yml`:
+
+```yaml
+provider:
+  type: docker-ssh
+  ssh:
+    host: 10.0.0.20 # 主机 IP 或 ~/.ssh/config 别名
+    port: 22
+    username: deploy
+    identityFile: ${HAI_DEPLOY_SSH_KEY} # 私钥文件路径，省略则用 ssh-agent
+  remote:
+    baseDir: /opt/hai/apps # 远程部署根目录
+    runtime: auto # 远程运行时；auto 优先 podman，其次 docker
+  expose:
+    type: port
+    containerPort: 3000 # 容器内端口（adapter-node 默认 3000）
+    hostPort: 18080 # 宿主机端口 → 访问地址 http://10.0.0.20:18080
+
+container:
+  runtime: auto # 本地构建运行时（可选）
+
+services: {} # 启用的服务会自动生成 compose sidecar，见下
+```
+
+3. Deploy and verify with the CLI or API (equivalent behavior):
+
+```bash
+hai deploy            # 读取 config/_deploy.yml，输出访问地址
+```
+
+```typescript
+import { deploy } from '@h-ai/deploy'
+
+deploy.credentials.load() // 注入 HAI_DEPLOY_* 环境变量
+await deploy.init(dockerSshConfig)
+const result = await deploy.deployApp('./apps/my-app')
+if (result.success) {
+  result.data.url // http://<host>:<hostPort>
+  result.data.healthCheck // 'passed'（HTTP 探测成功）
+}
+await deploy.close()
+```
+
+### How it works
+
+For docker-ssh, `deployApp()` runs these steps:
+
+1. **Scan**: read `package.json` and `config/*.yml` to identify `@sveltejs/adapter-node`, required services, and backend types.
+2. **Local build**: use the project's `Dockerfile` to build `hai-<app>:<deploymentId>` (podman adds `--format docker --jobs=1`).
+3. **Export**: save the image as tar with `docker/podman save`.
+4. **Preflight**: verify SSH connectivity and remote `docker/podman version` / `compose version`.
+5. **Transfer/load**: upload tar with `scp`, load remotely, and retag under `localhost/` to avoid accidental registry pulls.
+6. **Runtime files**: generate `compose.yml` (app + sidecars) and `.env.runtime` (including `HAI_*` overrides and credentials), upload to `<baseDir>/<app>/`, and set `.env.runtime` permissions to `600`.
+7. **Start**: `compose up -d` with fixed project name `hai-<app>` for idempotent redeployment.
+8. **Health check**: poll `http://<host>:<hostPort>/`; only HTTP 200 yields `ready`.
+
+> Images, `compose.yml`, and `.env.runtime` are stored in the application's `.hai/deploy/`, excluded by the template `.gitignore`.
+
+### Feature-based compose sidecars
+
+`deploy.scan()` identifies services and their **actual backend types** (`type` in `_db.yml` / `_vecdb.yml`, etc.), generates matching sidecars, and injects `HAI_*` overrides:
+
+| Detected service | Backend (`type`) | Added sidecar                   | Injected variables |
+| ---------------- | ---------------- | ------------------------------- | ------------------ |
+| `db`             | `postgresql`     | `postgres:16-alpine`            | `HAI_DB`           |
+| `db`             | `mysql`          | `mysql:8.4`                     | `HAI_DB`           |
+| `db`             | `sqlite`         | None (mount `/app/data` volume) | —                  |
+| `cache`          | `redis`          | `redis:7-alpine`                | `HAI_CACHE`        |
+| `storage`        | `s3`             | `minio` + bucket initialization | `HAI_STORAGE`      |
+| `vecdb`          | `qdrant`         | `qdrant/qdrant`                 | `HAI_VECDB`        |
+| `vecdb`          | `pgvector`       | `pgvector/pgvector`             | `HAI_VECDB`        |
+| `vecdb`          | `chroma`         | `chromadb/chroma`               | `HAI_VECDB`        |
+| `vecdb`          | `lancedb`        | None (mount `/app/data` volume) | —                  |
+
+- Memory `cache` and external email/SMS `reach` APIs do not generate sidecars.
+- Existing cloud provisioners take precedence (for example Neon providing `HAI_DB`); no duplicate sidecar is created.
+- Sidecar secrets such as passwords go only in remote `.env.runtime` (`600`), never `compose.yml`.
+
+> Security: `identityFile` is a private key **path**, not key content. `strictHostKeyChecking: true` (default)
+> uses accept-new: trust first use and reject changed keys. You may connect once manually with `ssh` for an unknown host.
+
+## Error handling
+
+```typescript
+import { HaiDeployError } from '@h-ai/deploy'
+
+const result = await deploy.deployApp('./apps/my-app')
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiDeployError.AUTH_FAILED.code:
+      // Vercel Token 无效
+      break
+    case HaiDeployError.BUILD_FAILED.code:
+      // 构建失败
+      break
+  }
+}
+```
+
+Common error codes:
+
+| Error code                        | code             | Description                           |
+| --------------------------------- | ---------------- | ------------------------------------- |
+| `HaiDeployError.DEPLOY_FAILED`    | `hai:deploy:001` | Deployment failed                     |
+| `HaiDeployError.BUILD_FAILED`     | `hai:deploy:003` | Build failed                          |
+| `HaiDeployError.AUTH_FAILED`      | `hai:deploy:006` | Authentication failed                 |
+| `HaiDeployError.PROVISION_FAILED` | `hai:deploy:007` | Provisioning failed                   |
+| `HaiDeployError.NOT_INITIALIZED`  | `hai:deploy:010` | Not initialized                       |
+| `HaiDeployError.ENV_VAR_FAILED`   | `hai:deploy:011` | Environment variable operation failed |
+
+docker-ssh-specific error codes:
+
+| Error code                                   | code             | Description                 |
+| -------------------------------------------- | ---------------- | --------------------------- |
+| `HaiDeployError.CONTAINER_RUNTIME_NOT_FOUND` | `hai:deploy:015` | Container runtime not found |
+| `HaiDeployError.CONTAINER_BUILD_FAILED`      | `hai:deploy:016` | Image build failed          |
+| `HaiDeployError.REMOTE_CONNECT_FAILED`       | `hai:deploy:017` | Remote connection failed    |
+| `HaiDeployError.REMOTE_COMMAND_FAILED`       | `hai:deploy:018` | Remote command failed       |
+| `HaiDeployError.IMAGE_TRANSFER_FAILED`       | `hai:deploy:019` | Image transfer failed       |
+| `HaiDeployError.HEALTH_CHECK_FAILED`         | `hai:deploy:020` | Health check failed         |
+
+## Tests
+
+```bash
+pnpm --filter @h-ai/deploy test
+```
+
+## License
+
+Apache-2.0
+
+Provisioned configuration: Neon emits HAI_DB (PostgreSQL JSON), Upstash HAI_CACHE (Redis rediss URL JSON), and R2 HAI_STORAGE (flat S3 JSON). Email/SMS emit HAI_REACH_PROVIDERS; deployApp merges both channels while preserving YAML message templates, replacing the original providers array. Core supports whole-object/array overrides, with parents preceding leaves and schema validation retained. Build subprocesses and target runtimes share provisioned values. R2 needs existing S3 accessKeyId/secretAccessKey, Resend a verified-domain from address, and Alibaba Cloud approved signName/templates. Applications need matching `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` loaded at startup; network clients require Node.
+
+Configuration references: [Upstash TLS](https://upstash.com/docs/redis/features/security), [Resend SMTP](https://resend.com/docs/send-with-smtp). Deterministic acceptance generates real applications and validates Core and module schemas. It does not create cloud resources or send email/SMS, so it does not establish cloud read/write acceptance.
+
+Deployment recovery: `ProvisionResult.resourceStatus` marks created/reused. `getDeployRecovery(result.error)` reads projectName, stage, platformProjectId, and resource lists; unknown means an uncertain request result that must first be checked in the provider console. Preserve returned IDs for failed resources. Recovery excludes envVars, raw exceptions, and credentials; the CLI shows resources and advice. Same-name retries reuse resources. Reused resources are never deleted automatically; clean up newly created resources only after manually confirming they are unused.

package/README.ja.md

@@ -0,0 +1,243 @@
+# @h-ai/deploy
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
+
+自動デプロイモジュールです。SvelteKit アプリをクラウド基盤の作成とともに Vercel へ展開する方式と、コンテナー化して任意の Linux ホストへ SSH で展開する方式（docker-ssh）に対応します。
+
+## 対応デプロイ方式
+
+| Provider     | 展開先              | 説明                                                    |
+| ------------ | ------------------- | ------------------------------------------------------- |
+| `vercel`     | Vercel              | SvelteKit + adapter-vercel、クラウド Provisioner と連携 |
+| `docker-ssh` | 任意の Linux ホスト | SvelteKit + adapter-node、コンテナー化して SSH で展開   |
+
+## 対応クラウドサービス（Provisioner）
+
+| サービス種別 | Provisioner   | 説明                           |
+| ------------ | ------------- | ------------------------------ |
+| データベース | Neon          | PostgreSQL Serverless          |
+| キャッシュ   | Upstash       | Redis TCP + TLS                |
+| ストレージ   | Cloudflare R2 | S3 互換オブジェクトストレージ  |
+| メール       | Resend        | SMTP（検証済みドメインが必要） |
+| SMS          | Alibaba Cloud | Alibaba Cloud SMS              |
+
+## クイックスタート
+
+```typescript
+import { deploy } from '@h-ai/deploy'
+
+// 可选：从 ~/.hai/credentials.yml 注入 HAI_DEPLOY_* 环境变量
+deploy.credentials.load()
+
+// 初始化
+await deploy.init({
+  provider: { type: 'vercel', token: 'vel_xxx' },
+  services: {
+    db: { provisioner: 'neon', apiKey: 'neon_xxx' },
+    cache: { provisioner: 'upstash', email: 'a@b.com', apiKey: 'up_xxx' },
+  },
+})
+
+// 扫描应用依赖
+const scan = await deploy.scan('./apps/my-app')
+
+// 开通基础设施
+const provisions = await deploy.provisionAll('my-app')
+
+// 完整部署
+const result = await deploy.deployApp('./apps/my-app')
+
+await deploy.close()
+```
+
+## 設定
+
+Git に保存できる設定は `config/_deploy.yml`、秘密情報は `~/.hai/credentials.yml` で管理します：
+
+```yaml
+# config/_deploy.yml
+provider:
+  type: vercel
+  token: ${HAI_DEPLOY_VERCEL_TOKEN}
+
+services:
+  db:
+    provisioner: neon
+    apiKey: ${HAI_DEPLOY_NEON_API_KEY}
+  cache:
+    provisioner: upstash
+    email: ${HAI_DEPLOY_UPSTASH_EMAIL}
+    apiKey: ${HAI_DEPLOY_UPSTASH_API_KEY}
+```
+
+ここでの変数は `deploy.credentials` が管理する明示的な特殊マッピングです。YAML パスから生成する
+`HAI_DEPLOY_PROVIDER_TOKEN` なども指定した場合、規約に沿う変数が優先されます。
+
+スクリプト・CLI で認証情報ファイルを明示的に管理するには `deploy.credentials.*` を使います：
+
+```typescript
+deploy.credentials.load()
+deploy.credentials.save('HAI_DEPLOY_VERCEL_TOKEN', 'vel_xxx')
+deploy.credentials.saveAll({
+  HAI_DEPLOY_NEON_API_KEY: 'neon_xxx',
+})
+```
+
+> `deploy.scan()` と `deploy.credentials.*()` はローカルファイルシステムの機能で、`deploy.init()` に依存しません。
+
+## docker-ssh デプロイ
+
+アプリをコンテナー化して SSH で任意の Linux ホストへ展開します。クラウドアカウントは不要です。
+
+### 前提条件
+
+- **ローカル**：docker または podman をインストール（`auto` は podman を優先）。
+- **リモート**：SSH 接続可能、docker/podman と compose が導入済み、ログインユーザーがコンテナーを実行可能。
+- **アプリ**：SvelteKit に `@sveltejs/adapter-node` を使用（付属 `Dockerfile` は対応済み）。不足時は `ADAPTER_MISSING`。
+
+### 使用手順
+
+1. SSH 秘密鍵のパスをリポジトリー外の認証情報ファイルに保存します。`~/.hai/credentials.yml` を編集するか API を使います：
+
+```typescript
+deploy.credentials.save('HAI_DEPLOY_SSH_KEY', '~/.ssh/hai_deploy')
+```
+
+2. `config/_deploy.yml` に対象ホストを定義します：
+
+```yaml
+provider:
+  type: docker-ssh
+  ssh:
+    host: 10.0.0.20 # 主机 IP 或 ~/.ssh/config 别名
+    port: 22
+    username: deploy
+    identityFile: ${HAI_DEPLOY_SSH_KEY} # 私钥文件路径，省略则用 ssh-agent
+  remote:
+    baseDir: /opt/hai/apps # 远程部署根目录
+    runtime: auto # 远程运行时；auto 优先 podman，其次 docker
+  expose:
+    type: port
+    containerPort: 3000 # 容器内端口（adapter-node 默认 3000）
+    hostPort: 18080 # 宿主机端口 → 访问地址 http://10.0.0.20:18080
+
+container:
+  runtime: auto # 本地构建运行时（可选）
+
+services: {} # 启用的服务会自动生成 compose sidecar，见下
+```
+
+3. CLI または API で展開・検証します（動作は同じ）：
+
+```bash
+hai deploy            # 读取 config/_deploy.yml，输出访问地址
+```
+
+```typescript
+import { deploy } from '@h-ai/deploy'
+
+deploy.credentials.load() // 注入 HAI_DEPLOY_* 环境变量
+await deploy.init(dockerSshConfig)
+const result = await deploy.deployApp('./apps/my-app')
+if (result.success) {
+  result.data.url // http://<host>:<hostPort>
+  result.data.healthCheck // 'passed'（HTTP 探测成功）
+}
+await deploy.close()
+```
+
+### 処理の流れ
+
+docker-ssh の `deployApp()` は次の順で処理します：
+
+1. **走査**：`package.json` と `config/*.yml` から `@sveltejs/adapter-node`、必要なサービス、バックエンド種別を判定。
+2. **ローカルビルド**：プロジェクトの `Dockerfile` で `hai-<app>:<deploymentId>` を作成（podman は `--format docker --jobs=1` を追加）。
+3. **出力**：`docker/podman save` で tar に保存。
+4. **事前確認**：SSH 接続とリモートの `docker/podman version` / `compose version` を確認。
+5. **転送・読み込み**：`scp` で tar を転送し、リモートで `load` 後、誤った registry 取得を防ぐため `localhost/` タグを付与。
+6. **実行定義**：走査結果から `compose.yml`（app + sidecar）と `.env.runtime`（`HAI_*` 上書き・認証情報）を生成し、`<baseDir>/<app>/` に転送。`.env.runtime` は `600` に設定。
+7. **起動**：固定プロジェクト名 `hai-<app>` で `compose up -d`。再展開は冪等。
+8. **ヘルスチェック**：`http://<host>:<hostPort>/` を監視し、200 応答でのみ `ready` と判定。
+
+> イメージ、`compose.yml`、`.env.runtime` はアプリの `.hai/deploy/` に保存し、テンプレートの `.gitignore` で除外済みです。
+
+### 機能に応じた compose sidecar
+
+`deploy.scan()` は必要なサービスと**実際のバックエンド種別**（`_db.yml` / `_vecdb.yml` などの `type`）を読み、対応する sidecar と `HAI_*` 上書き変数を生成します：
+
+| 検出サービス | バックエンド（`type`） | 追加 sidecar                             | 注入する変数  |
+| ------------ | ---------------------- | ---------------------------------------- | ------------- |
+| `db`         | `postgresql`           | `postgres:16-alpine`                     | `HAI_DB`      |
+| `db`         | `mysql`                | `mysql:8.4`                              | `HAI_DB`      |
+| `db`         | `sqlite`               | なし（`/app/data` ボリュームをマウント） | —             |
+| `cache`      | `redis`                | `redis:7-alpine`                         | `HAI_CACHE`   |
+| `storage`    | `s3`                   | `minio` + バケット初期化                 | `HAI_STORAGE` |
+| `vecdb`      | `qdrant`               | `qdrant/qdrant`                          | `HAI_VECDB`   |
+| `vecdb`      | `pgvector`             | `pgvector/pgvector`                      | `HAI_VECDB`   |
+| `vecdb`      | `chroma`               | `chromadb/chroma`                        | `HAI_VECDB`   |
+| `vecdb`      | `lancedb`              | なし（`/app/data` ボリュームをマウント） | —             |
+
+- `memory` の `cache` と外部 API の `reach`（メール・SMS）は sidecar を生成しません。
+- 同じサービスにクラウド Provisioner がある場合（Neon の `HAI_DB` など）、クラウドを優先し sidecar を重複作成しません。
+- sidecar のパスワードなどはリモートの `.env.runtime`（`600`）のみに保存し、`compose.yml` には含めません。
+
+> セキュリティ：`identityFile` は秘密鍵の**パス**で、内容ではありません。`strictHostKeyChecking: true`（既定）は
+> accept-new を使い、初回は信頼し、鍵変更は拒否します。未知のホストには先に手動で `ssh` 接続できます。
+
+## エラー処理
+
+```typescript
+import { HaiDeployError } from '@h-ai/deploy'
+
+const result = await deploy.deployApp('./apps/my-app')
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiDeployError.AUTH_FAILED.code:
+      // Vercel Token 无效
+      break
+    case HaiDeployError.BUILD_FAILED.code:
+      // 构建失败
+      break
+  }
+}
+```
+
+主なエラーコード：
+
+| エラーコード                      | code             | 説明                 |
+| --------------------------------- | ---------------- | -------------------- |
+| `HaiDeployError.DEPLOY_FAILED`    | `hai:deploy:001` | デプロイに失敗       |
+| `HaiDeployError.BUILD_FAILED`     | `hai:deploy:003` | ビルドに失敗         |
+| `HaiDeployError.AUTH_FAILED`      | `hai:deploy:006` | 認証に失敗           |
+| `HaiDeployError.PROVISION_FAILED` | `hai:deploy:007` | リソースの作成に失敗 |
+| `HaiDeployError.NOT_INITIALIZED`  | `hai:deploy:010` | 未初期化             |
+| `HaiDeployError.ENV_VAR_FAILED`   | `hai:deploy:011` | 環境変数の処理に失敗 |
+
+docker-ssh 専用エラーコード：
+
+| エラーコード                                 | code             | 説明                               |
+| -------------------------------------------- | ---------------- | ---------------------------------- |
+| `HaiDeployError.CONTAINER_RUNTIME_NOT_FOUND` | `hai:deploy:015` | コンテナーランタイムが見つからない |
+| `HaiDeployError.CONTAINER_BUILD_FAILED`      | `hai:deploy:016` | イメージのビルドに失敗             |
+| `HaiDeployError.REMOTE_CONNECT_FAILED`       | `hai:deploy:017` | リモート接続に失敗                 |
+| `HaiDeployError.REMOTE_COMMAND_FAILED`       | `hai:deploy:018` | リモートコマンドに失敗             |
+| `HaiDeployError.IMAGE_TRANSFER_FAILED`       | `hai:deploy:019` | イメージ転送に失敗                 |
+| `HaiDeployError.HEALTH_CHECK_FAILED`         | `hai:deploy:020` | ヘルスチェックに失敗               |
+
+## テスト
+
+```bash
+pnpm --filter @h-ai/deploy test
+```
+
+## License
+
+Apache-2.0
+
+クラウド設定の利用：Neon は HAI_DB（PostgreSQL JSON）、Upstash は HAI_CACHE（Redis rediss URL JSON）、R2 は HAI_STORAGE（フラットな S3 JSON）を出力します。メール・SMS は HAI_REACH_PROVIDERS を出力し、deployApp が両チャネルと YAML のメッセージテンプレートを統合して元の providers 配列を置換します。Core はオブジェクト・配列全体の上書きをサポートし、親ノードを末端より優先して Schema 検証を維持します。ビルド子プロセスと対象環境は同じ値を使います。R2 は既存の S3 accessKeyId/secretAccessKey、Resend は検証済みドメインの from、Alibaba Cloud は承認済み signName・テンプレートが必要です。アプリは対応する `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` を起動時に読み込み、ネットワーククライアントには Node が必要です。
+
+設定の参照：[Upstash TLS](https://upstash.com/docs/redis/features/security)、[Resend SMTP](https://resend.com/docs/send-with-smtp)。決定的な検証では実際のアプリを生成して Core・各モジュールの Schema を確認します。クラウドリソースの作成やメール・SMS 送信は行わず、クラウドの読み書き検証済みとは言えません。
+
+デプロイ失敗からの復旧：`ProvisionResult.resourceStatus` は created/reused を示します。`getDeployRecovery(result.error)` で projectName、stage、platformProjectId、リソース一覧を取得し、unknown は結果不明なので先にサービス側の管理画面で確認します。失敗リソースの ID が返った場合は保持します。復旧情報に envVars・元の例外・接続認証情報は含まれず、CLI が一覧と提案を表示します。同名の再試行は既存リソースを再利用し、自動削除しません。新規作成分も未使用を人が確認した後にのみ削除します。

package/README.md

@@ -1,12 +1,22 @@
 # @h-ai/deploy
 
-自动化部署模块，支持一键将 SvelteKit 应用部署到 Vercel，并自动开通所需的基础设施服务。
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
 
-## 支持的服务
+[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+
+自动化部署模块，支持两种部署方式：一键将 SvelteKit 应用部署到 Vercel（并自动开通云基础设施），或将应用容器化后通过 SSH 部署到任意 Linux 主机（docker-ssh）。
+
+## 支持的部署方式
+
+| Provider     | 目标            | 说明                                           |
+| ------------ | --------------- | ---------------------------------------------- |
+| `vercel`     | Vercel 平台     | SvelteKit + adapter-vercel，配合云 Provisioner |
+| `docker-ssh` | 任意 Linux 主机 | SvelteKit + adapter-node，容器化后经 SSH 部署  |
+
+## 支持的云服务（Provisioner）
 
 | 服务类型 | Provisioner   | 说明                   |
 | -------- | ------------- | ---------------------- |
-| 部署     | Vercel        | SvelteKit 应用部署     |
 | 数据库   | Neon          | PostgreSQL Serverless  |
 | 缓存     | Upstash       | Redis TCP + TLS        |
 | 存储     | Cloudflare R2 | S3 兼容对象存储        |
@@ -77,6 +87,105 @@ deploy.credentials.saveAll({
 
 > `deploy.scan()` 与 `deploy.credentials.*()` 都是本地文件系统能力，不依赖 `deploy.init()`。
 
+## docker-ssh 部署
+
+将应用容器化后通过 SSH 部署到任意 Linux 主机，无需云平台账号。
+
+### 前置条件
+
+- **本地**：安装 docker 或 podman（`auto` 优先 podman）。
+- **远程主机**：可 SSH 登录、已装 docker/podman 与 compose、登录用户可运行容器。
+- **应用**：SvelteKit 使用 `@sveltejs/adapter-node`（工程自带的 `Dockerfile` 已满足）；缺少时返回 `ADAPTER_MISSING`。
+
+### 使用步骤
+
+1）把 SSH 私钥路径存入凭证文件（不进仓库）。编辑 `~/.hai/credentials.yml`，或用 API：
+
+```typescript
+deploy.credentials.save('HAI_DEPLOY_SSH_KEY', '~/.ssh/hai_deploy')
+```
+
+2）在 `config/_deploy.yml` 声明目标主机：
+
+```yaml
+provider:
+  type: docker-ssh
+  ssh:
+    host: 10.0.0.20 # 主机 IP 或 ~/.ssh/config 别名
+    port: 22
+    username: deploy
+    identityFile: ${HAI_DEPLOY_SSH_KEY} # 私钥文件路径，省略则用 ssh-agent
+  remote:
+    baseDir: /opt/hai/apps # 远程部署根目录
+    runtime: auto # 远程运行时；auto 优先 podman，其次 docker
+  expose:
+    type: port
+    containerPort: 3000 # 容器内端口（adapter-node 默认 3000）
+    hostPort: 18080 # 宿主机端口 → 访问地址 http://10.0.0.20:18080
+
+container:
+  runtime: auto # 本地构建运行时（可选）
+
+services: {} # 启用的服务会自动生成 compose sidecar，见下
+```
+
+3）部署并验证（CLI 或 API，二者等价）：
+
+```bash
+hai deploy            # 读取 config/_deploy.yml，输出访问地址
+```
+
+```typescript
+import { deploy } from '@h-ai/deploy'
+
+deploy.credentials.load() // 注入 HAI_DEPLOY_* 环境变量
+await deploy.init(dockerSshConfig)
+const result = await deploy.deployApp('./apps/my-app')
+if (result.success) {
+  result.data.url // http://<host>:<hostPort>
+  result.data.healthCheck // 'passed'（HTTP 探测成功）
+}
+await deploy.close()
+```
+
+### 实现逻辑
+
+`deployApp()` 对 docker-ssh 依次执行：
+
+1. **扫描**：读取 `package.json` 与 `config/*.yml`，识别 `@sveltejs/adapter-node` 与所需服务及其后端类型。
+2. **本地构建**：用工程自带的 `Dockerfile` 构建镜像 `hai-<app>:<部署ID>`（podman 追加 `--format docker --jobs=1`）。
+3. **导出**：`docker/podman save` 导出为 tar。
+4. **预检**：SSH 连通性 + 远程 `docker/podman version` 与 `compose version`。
+5. **传输加载**：`scp` 上传 tar → 远程 `load` → 重打为 `localhost/` 本地标签（避免误从 registry 拉取）。
+6. **生成运行描述**：按扫描结果生成 `compose.yml`（app + sidecar）与 `.env.runtime`（含 `HAI_*` 覆盖变量与凭据），上传到 `<baseDir>/<app>/`，`.env.runtime` 设为 `600`。
+7. **启动**：`compose up -d`（Compose 项目名固定 `hai-<app>`，重复部署幂等）。
+8. **健康检查**：轮询 `http://<host>:<hostPort>/`，返回 200 才判定 `ready`。
+
+> 镜像、`compose.yml`、`.env.runtime` 落在应用 `.hai/deploy/`（已在模板 `.gitignore` 忽略）。
+
+### compose 按功能生成 sidecar
+
+`deploy.scan()` 会识别所需服务及其**实际后端类型**（读取 `_db.yml` / `_vecdb.yml` 等的 `type`），生成匹配的 sidecar 并注入对应 `HAI_*` 覆盖变量：
+
+| 扫描到的服务 | 后端 (`type`) | 追加的 sidecar                | 注入变量      |
+| ------------ | ------------- | ----------------------------- | ------------- |
+| `db`         | `postgresql`  | `postgres:16-alpine`          | `HAI_DB`      |
+| `db`         | `mysql`       | `mysql:8.4`                   | `HAI_DB`      |
+| `db`         | `sqlite`      | 无（挂载 `/app/data` 数据卷） | —             |
+| `cache`      | `redis`       | `redis:7-alpine`              | `HAI_CACHE`   |
+| `storage`    | `s3`          | `minio` + 初始化 bucket       | `HAI_STORAGE` |
+| `vecdb`      | `qdrant`      | `qdrant/qdrant`               | `HAI_VECDB`   |
+| `vecdb`      | `pgvector`    | `pgvector/pgvector`           | `HAI_VECDB`   |
+| `vecdb`      | `chroma`      | `chromadb/chroma`             | `HAI_VECDB`   |
+| `vecdb`      | `lancedb`     | 无（挂载 `/app/data` 数据卷） | —             |
+
+- `cache` 为 `memory`、`reach`（邮件/短信）为外部 API，均不生成 sidecar。
+- 若同一服务已配置云 Provisioner（如 Neon 提供 `HAI_DB`），优先用云资源，不再自建 sidecar。
+- sidecar 的密码等敏感值仅写入远程 `.env.runtime`（`600`），不会进入 `compose.yml`。
+
+> 安全：`identityFile` 为私钥**路径**（非私钥内容）；`strictHostKeyChecking: true`（默认）
+> 采用 accept-new（首次信任、拒绝变更）。首次连接未知主机可先手动 `ssh` 一次。
+
 ## 错误处理
 
 ```typescript
@@ -106,6 +215,17 @@ if (!result.success) {
 | `HaiDeployError.NOT_INITIALIZED`  | `hai:deploy:010` | 未初始化     |
 | `HaiDeployError.ENV_VAR_FAILED`   | `hai:deploy:011` | 环境变量失败 |
 
+docker-ssh 专属错误码：
+
+| 错误码                                       | code             | 说明             |
+| -------------------------------------------- | ---------------- | ---------------- |
+| `HaiDeployError.CONTAINER_RUNTIME_NOT_FOUND` | `hai:deploy:015` | 未找到容器运行时 |
+| `HaiDeployError.CONTAINER_BUILD_FAILED`      | `hai:deploy:016` | 镜像构建失败     |
+| `HaiDeployError.REMOTE_CONNECT_FAILED`       | `hai:deploy:017` | 远程连接失败     |
+| `HaiDeployError.REMOTE_COMMAND_FAILED`       | `hai:deploy:018` | 远程命令失败     |
+| `HaiDeployError.IMAGE_TRANSFER_FAILED`       | `hai:deploy:019` | 镜像传输失败     |
+| `HaiDeployError.HEALTH_CHECK_FAILED`         | `hai:deploy:020` | 健康检查未通过   |
+
 ## 测试
 
 ```bash