@h-ai/deploy 0.1.0-alpha.65 → 0.1.0-alpha.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md CHANGED
@@ -1,202 +1,139 @@
1
1
  # @h-ai/deploy
2
2
 
3
- [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
3
+ [简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md)
4
4
 
5
- [フレームワーク](../../README.ja.md) · [CLI](../cli/README.ja.md) · [環境とミドルウェア](../cli/templates/skills/hai-deploy/middleware.md)
5
+ ## 概要
6
6
 
7
- `@h-ai/cli` の `hai deploy` が利用するデプロイ SDK です。Node.js スクリプトから単独でも利用できます。
7
+ 既存イメージまたは Vercel prebuilt 成果物を配布します。完全オフライン、サービス選択、SSH 自動化、OS 別の手動配布スクリプトに対応します。SDK は成果物を消費し、CLI --build は構築から配布を明示的に実行します。
8
8
 
9
- ## 機能と対象範囲
9
+ ## 主な機能
10
10
 
11
- | デプロイ先 | アプリ | 処理 |
12
- | ------------ | -------------------------------------------- | -------------------------------------------------------------------------------------- |
13
- | `docker-ssh` | Node サービス、adapter-node を使う SvelteKit | ローカルでイメージをビルドし、SSH で転送、Linux の Compose で起動、HTTP ヘルスチェック |
14
- | `vercel` | adapter-vercel を使う SvelteKit | ビルド、転送、環境変数設定、結果の待機。インターネット接続が必要 |
11
+ - CLI でビルド、梱包、SSH 転送、起動、アクセス確認を実行。
12
+ - アプリと自前ミドルウェアのイメージを同梱し、選択したサービスだけの更新にも対応。
13
+ - オフライン用 tar と Windows/Linux/macOS 操作スクリプトを生成し、手順の結果と失敗時の復元を扱う。
15
14
 
16
- - 対象の `pnpm-lock.yaml` importer から実行依存と workspace link をたどり、開発依存・peer を除外します。アプリ設定でバックエンドを判定し、任意の AI peer だけで AI/CUDA を有効化しません。
17
- - 最初に環境を選び `.env.<mode>` を確認します。各ミドルウェアは既定設定・カスタム接続・変更しないを選択でき、設定済みなら全処理を省略できます。
18
- - Compose は PostgreSQL、MySQL、Redis、RustFS/MinIO、Qdrant、pgvector、Chroma、OpenLDAP、Mailpit に対応します。SQLite、memory、local、LanceDB はそれぞれのローカル保存方式を使います。Mailpit はテストメール捕捉専用です。
19
- - クラウド作成は Neon、Upstash、Cloudflare R2、Resend、Alibaba Cloud SMS に対応します。R2 は既存の S3 鍵、Resend は検証済み送信ドメイン、SMS は承認済み署名・テンプレートが必要です。他はカスタム接続を使います。
15
+ ## 使い始める
20
16
 
21
- **fullstack の API と Web は別々にデプロイします。** `hai deploy packages/my-app-serv` は API のみが対象です。ルート Dockerfile の `runtime` / `web` target で API / 静的 Web イメージをビルドできます。Web は別途転送・起動し、`PUBLIC_API_BASE` と API の CORS を設定します。同時公開コマンド、ドメイン・TLS・リバースプロキシの自動設定はありません。
17
+ ### 4. ソースをコンパイルし、配布物を作る
22
18
 
23
- ## コマンドラインでの利用
19
+ デプロイツールは作成時に既定で含まれます。不要な場合は `hai create my-app --no-deploy` を指定します。SDK は開発依存に配置し、実行イメージには含めません。
24
20
 
25
- ### 1. インストールと準備
21
+ ```sh
22
+ pnpm build
23
+ pnpm build --target docker
24
+ pnpm build --target docker --images web
25
+ pnpm build --target desktop --platform windows --arch x64
26
+ ```
27
+
28
+ #### build のオプション
26
29
 
27
- Node は `^22.22.2 || ^24.15.0 || >=26.0.0` が必要です。生成プロジェクトは `pnpm@12.11.2` を固定します。Node 20 / pnpm 9.5.0 は非対応です。Windows PowerShell では `pnpm.cmd` を使います。
30
+ `--target` は compile(既定)、docker、desktop を選択します。`--images app|web|app,web` は対象イメージを、`--runtime auto|podman|docker` はローカルエンジンを選択します。auto は接続可能な Podman を優先します。`--network` は構築ネットワーク、`--no-http-proxy` は Podman のプロキシ継承無効、`--sqlite-prebuild-mirror` は信頼できる HTTP(S) バイナリ配布元です。ネイティブ配布物には対象 OS の SDK と Rust ツールチェーンが必要です。構築時にデプロイ環境や秘密情報を読み込みません。
28
31
 
29
- 生成 workspace のルートでアプリのフレームワークに合う CLI/SDK をインストールし、lockfile を保持します。パッケージ配布元または完全なオフライン依存が必要です。
32
+ #### hai.build.json でパッケージの構成を指定する
30
33
 
31
- ```powershell
32
- pnpm.cmd add -Dw @h-ai/cli @h-ai/deploy
33
- pnpm.cmd exec hai --help
34
+ ```json
35
+ { "images": [{ "name": "app", "context": ".", "dockerfile": "images/app.Dockerfile", "containerPort": 3000 }, { "name": "web", "context": ".", "dockerfile": "images/web.Dockerfile", "containerPort": 8080 }] }
34
36
  ```
35
37
 
36
- 作成時の `--features deploy` はローカル SDK を追加しますが、グローバル `hai` のインストールは行いません。CLI をグローバル導入済みなら `hai deploy` を直接使えます。テンプレートの `pnpm run deploy` はパッケージ作成用で、このコマンドとは異なります。
38
+ 各イメージに独立した Dockerfile を用意します。Web 用設定は images/web/ に置きます。Dockerfile 内の構築・実行段階は維持しますが、設定から段階を選びません。不要なイメージ項目は削除し、desktop ディレクトリは対象プロジェクトのみ設定します。
37
39
 
38
- docker-ssh の前提条件:
40
+ 構築器はパッケージ情報、ローカルアーカイブとパッチを images/dependencies/ に準備し、pnpm store と依存レイヤーをキャッシュします。通常のソース変更で全依存を再ダウンロードしない構成です。キャッシュが空でもオンライン構築できます。Windows の node_modules は Linux のネイティブ依存を代替できません。完全オフライン構築には基底イメージ、ツールと一致する ABI・アーキテクチャ・libc のバイナリも準備します。
39
41
 
40
- - サーバーのアーキテクチャー向け Linux イメージをビルドできるローカル Docker/Podman エンジン。Windows は仮想化/WSL2/VM の準備・起動が必要で、クライアントだけでは不足します。`auto` は Podman 優先、Docker の明示指定も可能です。
41
- - ローカル `ssh` / `scp`、非対話の鍵/agent 認証、サーバーのホスト指紋。
42
- - Linux の Docker/Podman と対応する `compose` コマンド。SSH ユーザーのコンテナ実行・ディレクトリー書き込み権限。Windows から SSH とアプリ公開ポートへ接続できること。
43
- - 対象パッケージの `config/_deploy.yml` と、環境ディレクトリーの `.env.prod` / `.env.test`。環境ファイルがなければ停止します。
42
+ アプリの版はルート package.json.version で管理します。`.hai/build/docker/<buildId>/` に形式 3 の manifest.json、選択イメージの tar と SHA-256 を出力します。partial は部分構築、hasWeb は構成を記録します。appContainerPort と webContainerPort は明示した app/web の待受ポートを保持し、部分構築で選ばなかったイメージのポートも失いません。未指定のポートにはデプロイ時の既定値を使います。同じアプリ版でも再構築可能で、構築 ID とイメージ参照で内容を区別します。全出力に成功してからローカルの構築参照を更新します。基底・ミドルウェア・ツールは版を固定し、latest を使いません。
44
43
 
45
- ### 2. 接続先と環境の設定
44
+ ### 5. 成果物を対象環境へデプロイする
46
45
 
47
- Docker 用の最小 `config/_deploy.yml` です。実際の接続先は `.env.local` の `HAI_DEPLOY_PROVIDER` オブジェクトで上書きします。
46
+ #### 環境と接続先を用意する
47
+
48
+ `.env.<環境>` とサービスの config/_deploy.yml を用意します。fullstack の deploy は packages/<プロジェクト>-serv、API workspace は apps/<プロジェクト>-service を指定します。これは設定と実行依存の走査入口で、成果物は構築設定のルートから読み込みます。
48
49
 
49
50
  ```yaml
50
51
  provider:
51
52
  type: docker-ssh
53
+ expose:
54
+ hostPort: 18080
52
55
  container:
53
- runtime: docker
54
56
  s3Engine: rustfs
55
- services: {}
56
- ```
57
-
58
- ホスト、ユーザー、ポート、鍵のパスを実際の値に置き換えます。`.env.local` は Git に登録しません。
59
-
60
- ```dotenv
61
- HAI_DEPLOY_PROVIDER='{"type":"docker-ssh","ssh":{"host":"10.0.0.20","port":22,"username":"deploy","identityFile":"C:/Users/me/.ssh/hai_deploy"},"remote":{"baseDir":"/opt/hai/apps","runtime":"docker"},"expose":{"type":"port","containerPort":3000,"hostPort":18080}}'
62
- ```
63
-
64
- 未設定の接続先はウィザードでも入力できます。`.env.local` に保存して次回再利用し、秘密鍵はパスだけを保存します。接続先の変更は `HAI_DEPLOY_PROVIDER` を編集します。
65
-
66
- 上書き順は `.env` → `.env.<mode>` → `.env.local` → プロセス環境変数です。`HAI_DB` など親 JSON が子の変数より優先されます。`.env.example` に全項目・説明・列挙値を記載し、`.env` と `.env.dev/test/prod` は Git 登録、実際の認証情報は `.env.local` に保存します。fullstack 初回起動には IAM ポリシーを満たす非公開の `HAI_ADMIN_DEFAULT_PASSWORD` も必要です。
67
-
68
- fullstack 本番は `.env.prod` に `HAI_SERV_CORS_ORIGIN=https://app.hai.internal` など明示的な Web Origin が必要です。既定の `*` では本番起動に失敗します。本番 refresh Cookie は Secure のため、Web/API に信頼済み HTTPS 入口を準備します。HTTP ポートの公開だけでログイン・セッション更新まで検証済みとは判定できません。
69
-
70
- ### 3. デプロイ
71
-
72
- fullstack ルートからサービス名を置き換えて実行します。
73
-
74
- ```powershell
75
- pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir .
76
- ```
77
-
78
- ウィザードは現在のバックエンドと用途を示します。既定設定は Compose サービス/ボリュームを作成し、カスタム接続では当該コンテナを作成しません。「変更しない」は対象環境ファイルに完全な設定が明示されている場合のみ表示します。公開値は対象環境、認証情報は `.env.local` に保存し、表示をマスクします。
79
-
80
- DB・キャッシュ・ストレージ接続がすべて設定済みの場合:
81
-
82
- ```powershell
83
- pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir . --yes --skip-middleware
84
57
  ```
85
58
 
86
- `--skip-middleware`(別名 `--skip-provision`)はミドルウェアの入力・設定変更・リソース作成を省略します。アプリのビルド・デプロイは行い、停止中の外部サービスを起動しません。`--yes` 単独では完全な設定を維持し、それ以外は現在のバックエンド既定値を採用します。
87
-
88
- `--project-name <name>` で名前を指定し、環境指定時は環境サフィックスが付きます。**`--skip-build` は現在 Vercel のアプリビルドのみを省略します。docker-ssh は必ずイメージをビルドし、既存イメージを直接指定するオプションはありません。** 失敗時は非ゼロ終了コードを返します。
89
-
90
- ## docker-ssh の処理とファイル
91
-
92
- 1. 対象パッケージの Dockerfile を使います。なければ workspace ルートを context にする代替 Dockerfile を生成します。fullstack サービスの既定は代替で、ルートの Web target は使いません。
93
- 2. ローカルでビルドし、`docker/podman save` で tar を作成します。
94
- 3. SSH で遠隔エンジンと Compose を確認し、SCP で tar を転送、遠隔で `load` します。
95
- 4. `compose.yml`、`.env.runtime`、`start-<mode>.sh` をローカル生成して個別に `<baseDir>/<projectName>-<mode>/` へ転送します。イメージとは別送で、Compose 全体の圧縮パッケージや Linux 上でのソースビルドではありません。
96
- 5. 遠隔スクリプトが `HAI_DEPLOY_ENVIRONMENT` / `HAI_CORE_ENV` を設定し、`compose --env-file .env.runtime ... up -d` を実行します。SDK はローカルから Node の `/health` または SvelteKit の `/` を確認して成功を返します。
97
-
98
- ローカル成果物は対象パッケージの Git 対象外 `.hai/deploy/<mode>/` に保存します。遠隔 `.env.runtime` は権限 `600` です。再デプロイ用にローカル成果物を保持してください。「変更しない」は前回のローカル Compose のサービス/ボリュームを維持するもので、任意の遠隔 Compose を読み込みません。非公開環境ファイル・デプロイアーカイブはイメージに含めません。
99
-
100
- ## 完全オフラインのデプロイ
101
-
102
- インターネットに接続しなくても、Windows と Linux 間の内部 SSH/HTTP 通信は必要です。Vercel・クラウド作成は利用できません。
103
-
104
- ### 事前に持ち込む材料
105
-
106
- | 場所 | 必要な材料・状態 |
107
- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
108
- | Windows | 対応 Node(条件を満たす Node 24 など)、pnpm 12.11.2、導入済み CLI/SDK と推移的依存、OpenSSH、初期化・起動済み Linux コンテナエンジン |
109
- | プロジェクト | 完全なソース・固定 lockfile・環境設定・認証情報。オフラインで `pnpm.cmd exec hai --help` が成功すること。現場での `npx` / `pnpm dlx` ダウンロードを避ける |
110
- | Linux | Docker CLI/Engine と Compose プラグイン(`docker compose version` 成功)、SSH 公開鍵登録、権限、公開ポート、書き込み先、ディスク容量。イメージ実行だけならホスト Node/pnpm は不要 |
111
- | イメージ | Linux の CPU 構成と一致する API・Web・ミドルウェア。Compose と完全一致する名前/tag。`docker load -i <archive.tar>` で読み込む |
112
- | アプリ設定 | PostgreSQL DB/アカウント、Redis 接続/パスワード、RustFS 鍵/バケット、初回管理者パスワード。既存サービスは起動・到達可能にする。`localhost` はアプリコンテナ自身 |
59
+ ウィザードはサーバー、SSH ユーザー、任意の鍵・指紋ファイル、公開ポートを説明付きで質問します。有効な設定は再利用し、接続情報は .env.local、秘密鍵はパスのみ保存します。パッケージ生成だけなら SSH は不要です。
113
60
 
114
- 既定は `postgres:16-alpine`、`redis:7-alpine`、`ghcr.io/rustfs/rustfs:1.0.1` です。別 tag では自動一致しません。正しいイメージの持ち込み、互換性確認済みイメージの適切な tag 設定、またはカスタム接続が必要です。SDK はミドルウェアイメージを転送しません。他の固定イメージは [Compose 実装](src/container/deploy-container-compose.ts) を参照してください。
61
+ #### 本当に必要なミドルウェアだけを設定する
115
62
 
116
- **既定のソースビルドは準備なしでオフライン動作しません。** Dockerfile は pnpm・パッケージ・SQLite バイナリーを取得し、fullstack ルートは `pnpm fetch` と外部 Dockerfile frontend も使用します。Windows の `node_modules` / pnpm store は Linux ビルド依存の代用になりません。現場でソースビルドする場合は Node ベースイメージ、frontend、Corepack/pnpm、Linux 依存・ネイティブキャッシュをローカルエンジン/ビルド環境に持ち込み、Dockerfile を調整し、外部接続を切って全ビルドを確認します。`pnpm install --offline --frozen-lockfile` はパッケージストア読み込みのみを対象とし、インストールスクリプトの追加取得は対象外です。
63
+ 実行依存と設定に基づき、既定、自分の接続、設定維持を選びます。--skip-middleware は設定と開通を省略します。SQLite、メモリーキャッシュ、ローカル保存には外部イメージがありません。完全配布物には自前ミドルウェアのイメージも自動で含めます。外部サービスは接続先への到達性が必要で、クラウド開通はオフライン処理ではありません。
117
64
 
118
- SQLite バイナリーは better-sqlite3 版、Node ABI、CPU、libc と一致する必要があります。PostgreSQL 運用でも依存導入時に必要な場合があります。Linux ビルド環境の prebuild-install キャッシュを用意するか、`container.sqlitePrebuildMirror` を内部サーバーへ向けます。どちらもなければバイナリーまたは完成イメージを事前準備します。既定の fullstack に CUDA は不要です。
65
+ #### deploy のオプション
119
66
 
120
- ### 完成イメージを SDK 経由で利用する
67
+ --env/--env-dir は環境、--build は先行する選択イメージ構築、--services は更新対象、--artifact-dir は既存成果物を指定します。--bundle-only は SSH 接続なしで tar と OS 別スクリプトを生成します。--runtime はローカル構築・イメージ出力エンジン、--output は版付きファイル名です。--yes は有効な設定を非対話で使い、不足値はエラーで示します。一体化構築でも --network、--no-http-proxy、--sqlite-prebuild-mirror を指定できます。
121
68
 
122
- 依存が使える準備環境で、完成イメージを事前作成すると現場の手順を減らせます。例は `my-app`、Web あり、サーバーと同じビルドアーキテクチャーです。
69
+ #### マシン同士が接続できる場合:自動デプロイ
123
70
 
124
- ```powershell
125
- docker build --target runtime -t my-app-api:offline .
126
- docker build --target web -t my-app-web:offline .
127
- docker save -o my-app-images.tar my-app-api:offline my-app-web:offline
71
+ ```sh
72
+ pnpm run deploy --env prod --build
73
+ pnpm run deploy --env prod --artifact-dir .hai/build/docker/<buildId>
74
+ pnpm run deploy --env prod --build --services web
128
75
  ```
129
76
 
130
- オフライン Windows の Linux エンジンに `docker load -i my-app-images.tar` で導入します。`packages/my-app-serv/Dockerfile` は次の一行にします。
77
+ 部分更新には成功済みの完全インストールと一致するポート・構成が必要です。Compose 標準の設定合成で未選択サービス、設定、ボリュームを保持します。スクリプトはプロジェクト名とサービス名で選択した旧コンテナーだけを削除し、ボリュームを保持します。その後 `compose up -d --no-deps --no-build --pull never --no-recreate web` で新しいコンテナーを作成します。他のコンテナーは稼働したままで、全体の down は実行しません。storage-init は S3 バケットの一時初期化処理で、ストレージ初期化を伴う場合に限り実行します。
131
78
 
132
- ```dockerfile
133
- FROM my-app-api:offline
134
- ```
79
+ `-d` はバックグラウンド起動、`--no-deps` は依存サービスを更新しない指定、`--no-build` はサーバーでの構築禁止、`--pull never` は取得禁止、`--no-recreate` は残っているコンテナーを保持します。選択した旧コンテナーは事前に削除されているため、新しいコンテナーが作成されます。末尾の `web` は Compose サービス名で、複数指定は空白で区切ります。
135
80
 
136
- サービスパッケージに内容 `*` の `.dockerignore` を追加します。SDK の必須ビルドは完成 API を再利用し、パッケージを取得しません。ソース変更後は完成イメージを再作成します。接続先を設定して上記デプロイを実行してください。ミドルウェアコンテナを作成するなら `.env.prod` で `HAI_DB_TYPE=postgresql`、`HAI_CACHE_TYPE=redis`、`HAI_STORAGE_TYPE=s3` を選び、ウィザードで既定設定を使います。既存サービスはカスタム接続を設定し、完了後は `--skip-middleware` も使えます。API イメージは SDK が転送します。外部接続を切ったリハーサルで、ビルダーが通信不要であることを確認します。
81
+ `storage-init` はアプリの S3 SDK でストレージの準備を待ち、不足するバケットを作成します。既存データは削除しません。storage 起動後に `compose up --no-deps --no-build --pull never --force-recreate --exit-code-from storage-init storage-init` を実行し、終了コード 0 を確認してアプリを起動します。 部分更新では旧 storage-init コンテナーを先に削除し、このコマンドの `--force-recreate` を `--no-recreate` に替えて、稼働中のアプリを保持します。`storage` だけを更新する場合も、初期化のために `app` イメージを含む成果物が必要です。直近のビルドが Web のみなら、`--artifact-dir` で元の完全な成果物を選ぶか、先に `pnpm build --target docker --images app` を実行します。このイメージは初期化に使い、稼働中の `app` サービスは更新しません。
137
82
 
138
- Web イメージは別途転送します。以下は内網 TLS 入口 `https://app.hai.internal` / `https://api.hai.internal` が準備済みで、それぞれ Web 18081 / API 18080 を代理する前提です。プロキシ設定/イメージ・証明書を持ち込み、内部 DNS/hosts とクライアントの信頼を設定してから SSH で実行します。
83
+ #### マシン同士が接続できない場合:パッケージをコピー
139
84
 
140
85
  ```sh
141
- docker load -i /path/to/my-app-images.tar
142
- docker run -d --name my-app-web-prod --restart unless-stopped -p 18081:8080 -e PUBLIC_API_BASE=https://api.hai.internal my-app-web:offline
86
+ pnpm run deploy --env prod --build --bundle-only --output release-prod.tar
143
87
  ```
144
88
 
145
- API URL はブラウザーから到達可能にし、API に `HAI_SERV_CORS_ORIGIN=https://app.hai.internal` を設定します。API `/health`、Web ログイン/業務、hash ページ再読み込み、セッション更新、再起動・永続化を確認します。これは材料と適応方法の説明で、オンライン試験は実際のオフライン検証の代わりにはなりません。
89
+ 版 1.2.3 なら release-prod-1.2.3.tar と隣接する -deploy/ を生成します。tar は選択アプリ・ミドルウェアのイメージ、設定、秘密の環境ファイル、チェックサム、README、apply.sh を含みます。Windows は deploy.ps1、Linux/macOS は deploy.sh でアップロードし、同じサーバー処理を実行します。別の PC・OS に移す場合、秘密鍵とサーバー指紋ファイルのパスを移動先に合わせます。Windows は deploy-target.json、Linux/macOS は HAI_DEPLOY_IDENTITY_FILE と HAI_DEPLOY_KNOWN_HOSTS_FILE で指定します。
146
90
 
147
- 公式資料:[Docker save](https://docs.docker.com/reference/cli/docker/image/save/) / [load](https://docs.docker.com/reference/cli/docker/image/load/)、[pnpm install](https://pnpm.io/cli/install)、[Compose プラグイン](https://docs.docker.com/compose/install/linux/)。
91
+ 隔離された Linux では独立ディレクトリに展開し、`sh apply.sh` を実行します。引数で配置先を上書きできます。各段階の失敗は非ゼロ終了し、イメージ導入・起動・HTTP 検査を別々に報告します。result-<配置ID>.json に結果を記録し、成功時だけ current を更新します。同じ配置 ID の再適用は停止しますが、同じアプリ版から生成した新しい配布物は適用できます。更新失敗時は対象コンテナーと設定を以前の状態に戻すことを試み、データボリュームと診断情報を保持します。すでに書き込まれた業務データは元に戻しません。
148
92
 
149
- ## SDK とエラー処理
93
+ #### 完全オフラインの前に確認する
150
94
 
151
- スクリプト利用に CLI は不要です。解析済み設定を渡し、同じ環境解決には公開 `loadDeploymentEnvironment` / `loadDeploymentConfig` を使います。
95
+ 完全 tar は自前ミドルウェアのアーカイブと一致するアーキテクチャを含み、起動時にレジストリーへ接続しません。Linux に Docker/Podman、Docker Compose v2 または podman-compose 1.6.0 以降、sh、tar、sha256sum、awk、curl、ディレクトリ・コンテナー権限が必要です。秘密設定を安全に転送し、版間でボリューム識別を保持します。外部ネットワークを切って起動、ログイン、再読込、再起動と永続化を検証します。HTTPS、証明書、DNS、外部サービスは別途用意します。
152
96
 
153
- ```typescript
154
- import type { DeployConfigInput } from '@h-ai/deploy'
97
+ ### SDK
98
+
99
+ ```ts
155
100
  import { deploy } from '@h-ai/deploy'
156
101
 
157
- /**
158
- * 使用现有中间件发布生产 API,并释放部署模块。
159
- * @param config - 从部署环境解析得到的配置
160
- * @returns 初始化或部署的 HaiResult,由调用者检查 success
161
- * @example `const result = await publish(config)`
162
- */
163
- export async function publish(config: DeployConfigInput) {
164
- const initialized = await deploy.init(config)
165
- if (!initialized.success)
166
- return initialized
167
- try {
168
- return await deploy.deployApp('./packages/my-app-serv', {
169
- environment: 'prod',
170
- envDir: '.',
171
- skipProvision: true,
172
- })
173
- }
174
- finally {
175
- await deploy.close()
176
- }
102
+ const initialized = await deploy.init({ provider: { type: 'docker-ssh', expose: { hostPort: 18080 } } })
103
+ if (!initialized.success)
104
+ throw new Error(initialized.error.message)
105
+ try {
106
+ const result = await deploy.deployApp('./packages/demo-serv', {
107
+ environment: 'prod',
108
+ envDir: '.',
109
+ bundleOnly: true,
110
+ artifactDir: './.hai/build/docker/<buildId>',
111
+ runtime: 'auto',
112
+ })
113
+ if (!result.success)
114
+ throw new Error(result.error.message)
115
+ // result.data.bundlePath / instructions; packaged does not mean server ready.
116
+ }
117
+ finally {
118
+ await deploy.close()
177
119
  }
178
120
  ```
179
121
 
180
- `result.success` を確認してから `error.code/message` または `data.url/healthCheck` を読みます。`deploy.scan()` / `deploy.credentials.*()` は初期化不要です。`deployApp()` がリソース作成を含むため、事前の `provisionAll()` は不要です。手動作成も結果を確認します。SDK `skipProvision` は CLI のミドルウェア省略と同じ意味です。
122
+ `selectedServices: ['web']` は部分更新を選択し、`onProgress` はパッケージ作成とサーバー実行の段階を通知します。`deploy.scan` と `deploy.credentials.*` は初期化前も使用できます。HaiResult.success を確認してからデータを読み取ります。Vercel は既存 .vercel/output を prebuilt API でアップロードするためネット接続が必要で、オフラインや Compose の部分公開には対応しません。
181
123
 
182
- クラウドは `HAI_DB`、`HAI_CACHE`、`HAI_STORAGE`、`HAI_REACH_PROVIDERS` 全体を返し、アプリは対応 YAML の読み込みとモジュール初期化が必要です。`getDeployRecovery(result.error)` は段階・リソース ID を返します。`unknown` は管理画面で確認してから再試行します。同名再試行は既存リソースを再利用し、自動削除しません。型・設定・エラーコードは [公開エントリー](src/index.ts) を参照してください。
124
+ ## 開発とテスト
183
125
 
184
- ## テストと開発
185
-
186
- 依存導入後、フレームワークルートで実行します(Windows は `pnpm.cmd`)。
187
-
188
- ```powershell
189
- pnpm.cmd --filter @h-ai/deploy typecheck
190
- pnpm.cmd --filter @h-ai/deploy lint
191
- pnpm.cmd --filter @h-ai/deploy build
192
- pnpm.cmd --filter @h-ai/deploy test
193
- pnpm.cmd check:skills
126
+ ```sh
127
+ pnpm --filter @h-ai/deploy typecheck
128
+ pnpm --filter @h-ai/deploy lint
129
+ pnpm --filter @h-ai/deploy build
130
+ pnpm --filter @h-ai/deploy test
131
+ pnpm --filter @h-ai/cli test:scaffold-gates
132
+ pnpm --filter @h-ai/cli test:deploy-gates
194
133
  ```
195
134
 
196
- `src/deploy-scanner.ts` が lockfile 走査、`deploy-middleware.ts` が接続項目、`container/` がエンジン・SSH・Compose、`providers/` がデプロイ先、`provisioners/` がクラウド作成を担当します。CLI ウィザードは `../cli/src/commands/cli-deploy*.ts` です。バックエンド/設定変更時は利用側、環境例、テスト、[デプロイ skill](../cli/templates/skills/hai-deploy/SKILL.md) を同期します。
197
-
198
- 処理変更後は CLI の typecheck/lint/build/test と `pnpm.cmd --filter @h-ai/cli test:deploy-gates` を実行します。現在のパッケージから fullstack を生成し、Podman/SSH でヘルス・環境・ログイン・再デプロイを確認します。ローカルエンジンと OpenSSH が必要で、初回はイメージ・OS/Node 依存を取得するためオフライン検証ではありません。テンプレート変更時は `pnpm.cmd --filter @h-ai/cli test:scaffold-gates` も実行します。単体テストでクラウド作成済みとは判定せず、有料操作は別途検証します。ログ・画像・報告は Git 対象外の `tmp/` / `test-results/` に保存します。
135
+ 実際の生成プロジェクト、SSH と手動公開を検証します。レジストリー接続禁止、部分更新、破損アーカイブ、同一版での再公開、ヘルスチェック失敗を含めます。finally/teardown ではテスト自身が作成したプロジェクト、イメージ、コンテナー、ログ、プロセスのみを削除します。
199
136
 
200
- ## License
137
+ ## ライセンス
201
138
 
202
139
  Apache-2.0