@h-ai/deploy 0.1.0-alpha.63 → 0.1.0-alpha.65
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.en.md +134 -175
- package/README.ja.md +134 -175
- package/README.md +133 -175
- package/dist/index.d.ts +173 -6
- package/dist/index.js +631 -255
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.ja.md
CHANGED
|
@@ -2,242 +2,201 @@
|
|
|
2
2
|
|
|
3
3
|
[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
|
|
4
4
|
|
|
5
|
-
[
|
|
5
|
+
[フレームワーク](../../README.ja.md) · [CLI](../cli/README.ja.md) · [環境とミドルウェア](../cli/templates/skills/hai-deploy/middleware.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
`@h-ai/cli` の `hai deploy` が利用するデプロイ SDK です。Node.js スクリプトから単独でも利用できます。
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## 機能と対象範囲
|
|
10
10
|
|
|
11
|
-
|
|
|
12
|
-
| ------------ |
|
|
13
|
-
| `
|
|
14
|
-
| `
|
|
11
|
+
| デプロイ先 | アプリ | 処理 |
|
|
12
|
+
| ------------ | -------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
13
|
+
| `docker-ssh` | Node サービス、adapter-node を使う SvelteKit | ローカルでイメージをビルドし、SSH で転送、Linux の Compose で起動、HTTP ヘルスチェック |
|
|
14
|
+
| `vercel` | adapter-vercel を使う SvelteKit | ビルド、転送、環境変数設定、結果の待機。インターネット接続が必要 |
|
|
15
15
|
|
|
16
|
-
|
|
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 は承認済み署名・テンプレートが必要です。他はカスタム接続を使います。
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
| ------------ | ------------- | ------------------------------ |
|
|
20
|
-
| データベース | Neon | PostgreSQL Serverless |
|
|
21
|
-
| キャッシュ | Upstash | Redis TCP + TLS |
|
|
22
|
-
| ストレージ | Cloudflare R2 | S3 互換オブジェクトストレージ |
|
|
23
|
-
| メール | Resend | SMTP（検証済みドメインが必要） |
|
|
24
|
-
| SMS | Alibaba Cloud | Alibaba Cloud SMS |
|
|
21
|
+
**fullstack の API と Web は別々にデプロイします。** `hai deploy packages/my-app-serv` は API のみが対象です。ルート Dockerfile の `runtime` / `web` target で API / 静的 Web イメージをビルドできます。Web は別途転送・起動し、`PUBLIC_API_BASE` と API の CORS を設定します。同時公開コマンド、ドメイン・TLS・リバースプロキシの自動設定はありません。
|
|
25
22
|
|
|
26
|
-
##
|
|
23
|
+
## コマンドラインでの利用
|
|
27
24
|
|
|
28
|
-
|
|
29
|
-
import { deploy } from '@h-ai/deploy'
|
|
25
|
+
### 1. インストールと準備
|
|
30
26
|
|
|
31
|
-
|
|
32
|
-
deploy.credentials.load()
|
|
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` を使います。
|
|
33
28
|
|
|
34
|
-
|
|
35
|
-
await deploy.init({
|
|
36
|
-
provider: { type: 'vercel', token: 'vel_xxx' },
|
|
37
|
-
services: {
|
|
38
|
-
db: { provisioner: 'neon', apiKey: 'neon_xxx' },
|
|
39
|
-
cache: { provisioner: 'upstash', email: 'a@b.com', apiKey: 'up_xxx' },
|
|
40
|
-
},
|
|
41
|
-
})
|
|
29
|
+
生成 workspace のルートでアプリのフレームワークに合う CLI/SDK をインストールし、lockfile を保持します。パッケージ配布元または完全なオフライン依存が必要です。
|
|
42
30
|
|
|
43
|
-
|
|
44
|
-
|
|
31
|
+
```powershell
|
|
32
|
+
pnpm.cmd add -Dw @h-ai/cli @h-ai/deploy
|
|
33
|
+
pnpm.cmd exec hai --help
|
|
34
|
+
```
|
|
45
35
|
|
|
46
|
-
|
|
47
|
-
const provisions = await deploy.provisionAll('my-app')
|
|
36
|
+
作成時の `--features deploy` はローカル SDK を追加しますが、グローバル `hai` のインストールは行いません。CLI をグローバル導入済みなら `hai deploy` を直接使えます。テンプレートの `pnpm run deploy` はパッケージ作成用で、このコマンドとは異なります。
|
|
48
37
|
|
|
49
|
-
|
|
50
|
-
const result = await deploy.deployApp('./apps/my-app')
|
|
38
|
+
docker-ssh の前提条件：
|
|
51
39
|
|
|
52
|
-
|
|
53
|
-
|
|
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`。環境ファイルがなければ停止します。
|
|
54
44
|
|
|
55
|
-
|
|
45
|
+
### 2. 接続先と環境の設定
|
|
56
46
|
|
|
57
|
-
|
|
47
|
+
Docker 用の最小 `config/_deploy.yml` です。実際の接続先は `.env.local` の `HAI_DEPLOY_PROVIDER` オブジェクトで上書きします。
|
|
58
48
|
|
|
59
49
|
```yaml
|
|
60
|
-
# config/_deploy.yml
|
|
61
50
|
provider:
|
|
62
|
-
type:
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
provisioner: neon
|
|
68
|
-
apiKey: ${HAI_DEPLOY_NEON_API_KEY}
|
|
69
|
-
cache:
|
|
70
|
-
provisioner: upstash
|
|
71
|
-
email: ${HAI_DEPLOY_UPSTASH_EMAIL}
|
|
72
|
-
apiKey: ${HAI_DEPLOY_UPSTASH_API_KEY}
|
|
51
|
+
type: docker-ssh
|
|
52
|
+
container:
|
|
53
|
+
runtime: docker
|
|
54
|
+
s3Engine: rustfs
|
|
55
|
+
services: {}
|
|
73
56
|
```
|
|
74
57
|
|
|
75
|
-
|
|
76
|
-
`HAI_DEPLOY_PROVIDER_TOKEN` なども指定した場合、規約に沿う変数が優先されます。
|
|
77
|
-
|
|
78
|
-
スクリプト・CLI で認証情報ファイルを明示的に管理するには `deploy.credentials.*` を使います：
|
|
58
|
+
ホスト、ユーザー、ポート、鍵のパスを実際の値に置き換えます。`.env.local` は Git に登録しません。
|
|
79
59
|
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
deploy.credentials.save('HAI_DEPLOY_VERCEL_TOKEN', 'vel_xxx')
|
|
83
|
-
deploy.credentials.saveAll({
|
|
84
|
-
HAI_DEPLOY_NEON_API_KEY: 'neon_xxx',
|
|
85
|
-
})
|
|
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}}'
|
|
86
62
|
```
|
|
87
63
|
|
|
88
|
-
|
|
64
|
+
未設定の接続先はウィザードでも入力できます。`.env.local` に保存して次回再利用し、秘密鍵はパスだけを保存します。接続先の変更は `HAI_DEPLOY_PROVIDER` を編集します。
|
|
89
65
|
|
|
90
|
-
|
|
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` も必要です。
|
|
91
67
|
|
|
92
|
-
|
|
68
|
+
fullstack 本番は `.env.prod` に `HAI_SERV_CORS_ORIGIN=https://app.hai.internal` など明示的な Web Origin が必要です。既定の `*` では本番起動に失敗します。本番 refresh Cookie は Secure のため、Web/API に信頼済み HTTPS 入口を準備します。HTTP ポートの公開だけでログイン・セッション更新まで検証済みとは判定できません。
|
|
93
69
|
|
|
94
|
-
###
|
|
70
|
+
### 3. デプロイ
|
|
95
71
|
|
|
96
|
-
|
|
97
|
-
- **リモート**：SSH 接続可能、docker/podman と compose が導入済み、ログインユーザーがコンテナーを実行可能。
|
|
98
|
-
- **アプリ**：SvelteKit に `@sveltejs/adapter-node` を使用（付属 `Dockerfile` は対応済み）。不足時は `ADAPTER_MISSING`。
|
|
72
|
+
fullstack ルートからサービス名を置き換えて実行します。
|
|
99
73
|
|
|
100
|
-
|
|
74
|
+
```powershell
|
|
75
|
+
pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir .
|
|
76
|
+
```
|
|
101
77
|
|
|
102
|
-
|
|
78
|
+
ウィザードは現在のバックエンドと用途を示します。既定設定は Compose サービス/ボリュームを作成し、カスタム接続では当該コンテナを作成しません。「変更しない」は対象環境ファイルに完全な設定が明示されている場合のみ表示します。公開値は対象環境、認証情報は `.env.local` に保存し、表示をマスクします。
|
|
103
79
|
|
|
104
|
-
|
|
105
|
-
|
|
80
|
+
DB・キャッシュ・ストレージ接続がすべて設定済みの場合：
|
|
81
|
+
|
|
82
|
+
```powershell
|
|
83
|
+
pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir . --yes --skip-middleware
|
|
106
84
|
```
|
|
107
85
|
|
|
108
|
-
|
|
86
|
+
`--skip-middleware`（別名 `--skip-provision`）はミドルウェアの入力・設定変更・リソース作成を省略します。アプリのビルド・デプロイは行い、停止中の外部サービスを起動しません。`--yes` 単独では完全な設定を維持し、それ以外は現在のバックエンド既定値を採用します。
|
|
109
87
|
|
|
110
|
-
|
|
111
|
-
provider:
|
|
112
|
-
type: docker-ssh
|
|
113
|
-
ssh:
|
|
114
|
-
host: 10.0.0.20 # 主机 IP 或 ~/.ssh/config 别名
|
|
115
|
-
port: 22
|
|
116
|
-
username: deploy
|
|
117
|
-
identityFile: ${HAI_DEPLOY_SSH_KEY} # 私钥文件路径，省略则用 ssh-agent
|
|
118
|
-
remote:
|
|
119
|
-
baseDir: /opt/hai/apps # 远程部署根目录
|
|
120
|
-
runtime: auto # 远程运行时；auto 优先 podman，其次 docker
|
|
121
|
-
expose:
|
|
122
|
-
type: port
|
|
123
|
-
containerPort: 3000 # 容器内端口（adapter-node 默认 3000）
|
|
124
|
-
hostPort: 18080 # 宿主机端口 → 访问地址 http://10.0.0.20:18080
|
|
88
|
+
`--project-name <name>` で名前を指定し、環境指定時は環境サフィックスが付きます。**`--skip-build` は現在 Vercel のアプリビルドのみを省略します。docker-ssh は必ずイメージをビルドし、既存イメージを直接指定するオプションはありません。** 失敗時は非ゼロ終了コードを返します。
|
|
125
89
|
|
|
126
|
-
|
|
127
|
-
runtime: auto # 本地构建运行时（可选）
|
|
90
|
+
## docker-ssh の処理とファイル
|
|
128
91
|
|
|
129
|
-
|
|
130
|
-
|
|
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 の `/` を確認して成功を返します。
|
|
131
97
|
|
|
132
|
-
|
|
98
|
+
ローカル成果物は対象パッケージの Git 対象外 `.hai/deploy/<mode>/` に保存します。遠隔 `.env.runtime` は権限 `600` です。再デプロイ用にローカル成果物を保持してください。「変更しない」は前回のローカル Compose のサービス/ボリュームを維持するもので、任意の遠隔 Compose を読み込みません。非公開環境ファイル・デプロイアーカイブはイメージに含めません。
|
|
133
99
|
|
|
134
|
-
|
|
135
|
-
hai deploy # 读取 config/_deploy.yml，输出访问地址
|
|
136
|
-
```
|
|
100
|
+
## 完全オフラインのデプロイ
|
|
137
101
|
|
|
138
|
-
|
|
139
|
-
import { deploy } from '@h-ai/deploy'
|
|
102
|
+
インターネットに接続しなくても、Windows と Linux 間の内部 SSH/HTTP 通信は必要です。Vercel・クラウド作成は利用できません。
|
|
140
103
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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` はアプリコンテナ自身 |
|
|
113
|
+
|
|
114
|
+
既定は `postgres:16-alpine`、`redis:7-alpine`、`ghcr.io/rustfs/rustfs:1.0.1` です。別 tag では自動一致しません。正しいイメージの持ち込み、互換性確認済みイメージの適切な tag 設定、またはカスタム接続が必要です。SDK はミドルウェアイメージを転送しません。他の固定イメージは [Compose 実装](src/container/deploy-container-compose.ts) を参照してください。
|
|
115
|
+
|
|
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` はパッケージストア読み込みのみを対象とし、インストールスクリプトの追加取得は対象外です。
|
|
117
|
+
|
|
118
|
+
SQLite バイナリーは better-sqlite3 版、Node ABI、CPU、libc と一致する必要があります。PostgreSQL 運用でも依存導入時に必要な場合があります。Linux ビルド環境の prebuild-install キャッシュを用意するか、`container.sqlitePrebuildMirror` を内部サーバーへ向けます。どちらもなければバイナリーまたは完成イメージを事前準備します。既定の fullstack に CUDA は不要です。
|
|
150
119
|
|
|
151
|
-
###
|
|
120
|
+
### 完成イメージを SDK 経由で利用する
|
|
152
121
|
|
|
153
|
-
|
|
122
|
+
依存が使える準備環境で、完成イメージを事前作成すると現場の手順を減らせます。例は `my-app`、Web あり、サーバーと同じビルドアーキテクチャーです。
|
|
154
123
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
8. **ヘルスチェック**：`http://<host>:<hostPort>/` を監視し、200 応答でのみ `ready` と判定。
|
|
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
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
オフライン Windows の Linux エンジンに `docker load -i my-app-images.tar` で導入します。`packages/my-app-serv/Dockerfile` は次の一行にします。
|
|
163
131
|
|
|
164
|
-
|
|
132
|
+
```dockerfile
|
|
133
|
+
FROM my-app-api:offline
|
|
134
|
+
```
|
|
165
135
|
|
|
166
|
-
|
|
136
|
+
サービスパッケージに内容 `*` の `.dockerignore` を追加します。SDK の必須ビルドは完成 API を再利用し、パッケージを取得しません。ソース変更後は完成イメージを再作成します。接続先を設定して上記デプロイを実行してください。ミドルウェアコンテナを作成するなら `.env.prod` で `HAI_DB_TYPE=postgresql`、`HAI_CACHE_TYPE=redis`、`HAI_STORAGE_TYPE=s3` を選び、ウィザードで既定設定を使います。既存サービスはカスタム接続を設定し、完了後は `--skip-middleware` も使えます。API イメージは SDK が転送します。外部接続を切ったリハーサルで、ビルダーが通信不要であることを確認します。
|
|
167
137
|
|
|
168
|
-
`
|
|
138
|
+
Web イメージは別途転送します。以下は内網 TLS 入口 `https://app.hai.internal` / `https://api.hai.internal` が準備済みで、それぞれ Web 18081 / API 18080 を代理する前提です。プロキシ設定/イメージ・証明書を持ち込み、内部 DNS/hosts とクライアントの信頼を設定してから SSH で実行します。
|
|
139
|
+
|
|
140
|
+
```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
|
|
143
|
+
```
|
|
169
144
|
|
|
170
|
-
|
|
171
|
-
| ------------ | ---------------------- | ---------------------------------------- | ------------- |
|
|
172
|
-
| `db` | `postgresql` | `postgres:16-alpine` | `HAI_DB` |
|
|
173
|
-
| `db` | `mysql` | `mysql:8.4` | `HAI_DB` |
|
|
174
|
-
| `db` | `sqlite` | なし（`/app/data` ボリュームをマウント） | — |
|
|
175
|
-
| `cache` | `redis` | `redis:7-alpine` | `HAI_CACHE` |
|
|
176
|
-
| `storage` | `s3` | `minio` + バケット初期化 | `HAI_STORAGE` |
|
|
177
|
-
| `vecdb` | `qdrant` | `qdrant/qdrant` | `HAI_VECDB` |
|
|
178
|
-
| `vecdb` | `pgvector` | `pgvector/pgvector` | `HAI_VECDB` |
|
|
179
|
-
| `vecdb` | `chroma` | `chromadb/chroma` | `HAI_VECDB` |
|
|
180
|
-
| `vecdb` | `lancedb` | なし（`/app/data` ボリュームをマウント） | — |
|
|
145
|
+
API URL はブラウザーから到達可能にし、API に `HAI_SERV_CORS_ORIGIN=https://app.hai.internal` を設定します。API `/health`、Web ログイン/業務、hash ページ再読み込み、セッション更新、再起動・永続化を確認します。これは材料と適応方法の説明で、オンライン試験は実際のオフライン検証の代わりにはなりません。
|
|
181
146
|
|
|
182
|
-
|
|
183
|
-
- 同じサービスにクラウド Provisioner がある場合（Neon の `HAI_DB` など）、クラウドを優先し sidecar を重複作成しません。
|
|
184
|
-
- sidecar のパスワードなどはリモートの `.env.runtime`（`600`）のみに保存し、`compose.yml` には含めません。
|
|
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/)。
|
|
185
148
|
|
|
186
|
-
|
|
187
|
-
> accept-new を使い、初回は信頼し、鍵変更は拒否します。未知のホストには先に手動で `ssh` 接続できます。
|
|
149
|
+
## SDK とエラー処理
|
|
188
150
|
|
|
189
|
-
|
|
151
|
+
スクリプト利用に CLI は不要です。解析済み設定を渡し、同じ環境解決には公開 `loadDeploymentEnvironment` / `loadDeploymentConfig` を使います。
|
|
190
152
|
|
|
191
153
|
```typescript
|
|
192
|
-
import {
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
154
|
+
import type { DeployConfigInput } from '@h-ai/deploy'
|
|
155
|
+
import { deploy } from '@h-ai/deploy'
|
|
156
|
+
|
|
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()
|
|
203
176
|
}
|
|
204
177
|
}
|
|
205
178
|
```
|
|
206
179
|
|
|
207
|
-
|
|
180
|
+
`result.success` を確認してから `error.code/message` または `data.url/healthCheck` を読みます。`deploy.scan()` / `deploy.credentials.*()` は初期化不要です。`deployApp()` がリソース作成を含むため、事前の `provisionAll()` は不要です。手動作成も結果を確認します。SDK `skipProvision` は CLI のミドルウェア省略と同じ意味です。
|
|
208
181
|
|
|
209
|
-
|
|
210
|
-
| --------------------------------- | ---------------- | -------------------- |
|
|
211
|
-
| `HaiDeployError.DEPLOY_FAILED` | `hai:deploy:001` | デプロイに失敗 |
|
|
212
|
-
| `HaiDeployError.BUILD_FAILED` | `hai:deploy:003` | ビルドに失敗 |
|
|
213
|
-
| `HaiDeployError.AUTH_FAILED` | `hai:deploy:006` | 認証に失敗 |
|
|
214
|
-
| `HaiDeployError.PROVISION_FAILED` | `hai:deploy:007` | リソースの作成に失敗 |
|
|
215
|
-
| `HaiDeployError.NOT_INITIALIZED` | `hai:deploy:010` | 未初期化 |
|
|
216
|
-
| `HaiDeployError.ENV_VAR_FAILED` | `hai:deploy:011` | 環境変数の処理に失敗 |
|
|
182
|
+
クラウドは `HAI_DB`、`HAI_CACHE`、`HAI_STORAGE`、`HAI_REACH_PROVIDERS` 全体を返し、アプリは対応 YAML の読み込みとモジュール初期化が必要です。`getDeployRecovery(result.error)` は段階・リソース ID を返します。`unknown` は管理画面で確認してから再試行します。同名再試行は既存リソースを再利用し、自動削除しません。型・設定・エラーコードは [公開エントリー](src/index.ts) を参照してください。
|
|
217
183
|
|
|
218
|
-
|
|
184
|
+
## テストと開発
|
|
219
185
|
|
|
220
|
-
|
|
221
|
-
| -------------------------------------------- | ---------------- | ---------------------------------- |
|
|
222
|
-
| `HaiDeployError.CONTAINER_RUNTIME_NOT_FOUND` | `hai:deploy:015` | コンテナーランタイムが見つからない |
|
|
223
|
-
| `HaiDeployError.CONTAINER_BUILD_FAILED` | `hai:deploy:016` | イメージのビルドに失敗 |
|
|
224
|
-
| `HaiDeployError.REMOTE_CONNECT_FAILED` | `hai:deploy:017` | リモート接続に失敗 |
|
|
225
|
-
| `HaiDeployError.REMOTE_COMMAND_FAILED` | `hai:deploy:018` | リモートコマンドに失敗 |
|
|
226
|
-
| `HaiDeployError.IMAGE_TRANSFER_FAILED` | `hai:deploy:019` | イメージ転送に失敗 |
|
|
227
|
-
| `HaiDeployError.HEALTH_CHECK_FAILED` | `hai:deploy:020` | ヘルスチェックに失敗 |
|
|
186
|
+
依存導入後、フレームワークルートで実行します（Windows は `pnpm.cmd`）。
|
|
228
187
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
pnpm --filter @h-ai/deploy
|
|
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
|
|
233
194
|
```
|
|
234
195
|
|
|
235
|
-
|
|
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) を同期します。
|
|
236
197
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
クラウド設定の利用：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 が必要です。
|
|
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/` に保存します。
|
|
240
199
|
|
|
241
|
-
|
|
200
|
+
## License
|
|
242
201
|
|
|
243
|
-
|
|
202
|
+
Apache-2.0
|