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

package/README.md

@@ -1,12 +1,18 @@
 # @h-ai/deploy
 
-自动化部署模块，支持一键将 SvelteKit 应用部署到 Vercel，并自动开通所需的基础设施服务。
+自动化部署模块，支持两种部署方式：一键将 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 +83,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 +211,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

package/dist/index.d.ts

@@ -9,16 +9,112 @@ import { HaiResult, HaiError } from '@h-ai/core';
  * @module deploy-config
  */
 
+/** SSH 连接配置（docker-ssh Provider 使用 OpenSSH 客户端连接远程主机） */
+declare const SshConfigSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    username: z.ZodString;
+    identityFile: z.ZodOptional<z.ZodString>;
+    knownHostsFile: z.ZodOptional<z.ZodString>;
+    strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+    connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** 端口直出暴露配置 */
+declare const PortExposeSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"port">>;
+    containerPort: z.ZodDefault<z.ZodNumber>;
+    hostPort: z.ZodNumber;
+}, z.core.$strip>;
+/** docker-ssh 部署平台配置 */
+declare const DockerSshProviderConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"docker-ssh">;
+    ssh: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodNumber>;
+        username: z.ZodString;
+        identityFile: z.ZodOptional<z.ZodString>;
+        knownHostsFile: z.ZodOptional<z.ZodString>;
+        strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+        connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    remote: z.ZodDefault<z.ZodObject<{
+        baseDir: z.ZodDefault<z.ZodString>;
+        runtime: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            docker: "docker";
+            podman: "podman";
+        }>>;
+    }, z.core.$strip>>;
+    expose: z.ZodObject<{
+        type: z.ZodDefault<z.ZodLiteral<"port">>;
+        containerPort: z.ZodDefault<z.ZodNumber>;
+        hostPort: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 /** 部署平台配置联合类型（后续可扩展更多平台） */
 declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"vercel">;
     token: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"docker-ssh">;
+    ssh: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodNumber>;
+        username: z.ZodString;
+        identityFile: z.ZodOptional<z.ZodString>;
+        knownHostsFile: z.ZodOptional<z.ZodString>;
+        strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+        connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    remote: z.ZodDefault<z.ZodObject<{
+        baseDir: z.ZodDefault<z.ZodString>;
+        runtime: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            docker: "docker";
+            podman: "podman";
+        }>>;
+    }, z.core.$strip>>;
+    expose: z.ZodObject<{
+        type: z.ZodDefault<z.ZodLiteral<"port">>;
+        containerPort: z.ZodDefault<z.ZodNumber>;
+        hostPort: z.ZodNumber;
+    }, z.core.$strip>;
 }, z.core.$strip>], "type">;
+/** SSH 连接配置（parse 后） */
+type SshConfig = z.infer<typeof SshConfigSchema>;
+/** 端口暴露配置（parse 后） */
+type PortExposeConfig = z.infer<typeof PortExposeSchema>;
+/** docker-ssh 部署平台配置（parse 后） */
+type DockerSshProviderConfig = z.infer<typeof DockerSshProviderConfigSchema>;
 /** 部署模块完整配置 Schema */
 declare const DeployConfigSchema: z.ZodObject<{
     provider: z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"vercel">;
         token: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"docker-ssh">;
+        ssh: z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodDefault<z.ZodNumber>;
+            username: z.ZodString;
+            identityFile: z.ZodOptional<z.ZodString>;
+            knownHostsFile: z.ZodOptional<z.ZodString>;
+            strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+            connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>;
+        remote: z.ZodDefault<z.ZodObject<{
+            baseDir: z.ZodDefault<z.ZodString>;
+            runtime: z.ZodDefault<z.ZodEnum<{
+                auto: "auto";
+                docker: "docker";
+                podman: "podman";
+            }>>;
+        }, z.core.$strip>>;
+        expose: z.ZodObject<{
+            type: z.ZodDefault<z.ZodLiteral<"port">>;
+            containerPort: z.ZodDefault<z.ZodNumber>;
+            hostPort: z.ZodNumber;
+        }, z.core.$strip>;
     }, z.core.$strip>], "type">;
     services: z.ZodOptional<z.ZodObject<{
         db: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -49,6 +145,13 @@ declare const DeployConfigSchema: z.ZodObject<{
             accessKeySecret: z.ZodString;
         }, z.core.$strip>], "provisioner">>;
     }, z.core.$strip>>;
+    container: z.ZodOptional<z.ZodObject<{
+        runtime: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            docker: "docker";
+            podman: "podman";
+        }>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** 部署配置类型（parse 后） */
 type DeployConfig = z.infer<typeof DeployConfigSchema>;
@@ -70,6 +173,12 @@ declare const HaiDeployError: {
     readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
     readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
     readonly CREDENTIAL_ERROR: _h_ai_core.HaiErrorDef;
+    readonly CONTAINER_RUNTIME_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly CONTAINER_BUILD_FAILED: _h_ai_core.HaiErrorDef;
+    readonly REMOTE_CONNECT_FAILED: _h_ai_core.HaiErrorDef;
+    readonly REMOTE_COMMAND_FAILED: _h_ai_core.HaiErrorDef;
+    readonly IMAGE_TRANSFER_FAILED: _h_ai_core.HaiErrorDef;
+    readonly HEALTH_CHECK_FAILED: _h_ai_core.HaiErrorDef;
 };
 /**
  * 部署错误接口
@@ -94,7 +203,7 @@ interface DeployError {
     cause?: unknown;
 }
 /** 基础设施服务类型 */
-type ServiceType = 'db' | 'cache' | 'storage' | 'email' | 'sms';
+type ServiceType = 'db' | 'cache' | 'storage' | 'email' | 'sms' | 'vecdb';
 /**
  * 应用扫描结果
  *
@@ -107,8 +216,12 @@ interface ScanResult {
     isSvelteKit: boolean;
     /** 目标平台 adapter 是否已安装（如 @sveltejs/adapter-vercel） */
     adapterInstalled: boolean;
+    /** 容器部署所需的 @sveltejs/adapter-node 是否已安装 */
+    nodeAdapterInstalled: boolean;
     /** 检测到的模块依赖需要的服务列表 */
     requiredServices: ServiceType[];
+    /** 各服务检测到的后端类型（如 db→postgresql/mysql，vecdb→qdrant），用于生成匹配的 sidecar */
+    serviceBackends: Partial<Record<ServiceType, string>>;
     /** 构建命令 */
     buildCommand: string;
 }
@@ -126,6 +239,10 @@ interface DeployResult {
     status: 'ready' | 'building' | 'error';
     /** 已设置的环境变量名列表 */
     envVarsSet: string[];
+    /** 部署 Provider 名称（如 vercel / docker-ssh），容器部署时返回 */
+    provider?: string;
+    /** 健康检查结果：passed 表示 HTTP 探测成功，container-only 表示仅确认容器运行 */
+    healthCheck?: 'passed' | 'container-only' | 'skipped';
 }
 /**
  * 基础设施开通结果
@@ -262,4 +379,4 @@ declare const deploy: DeployFunctions;
 /** 读取错误中的恢复清单；仅返回明确允许展示的字段。 */
 declare function getDeployRecovery(error: HaiError): DeployRecoveryInfo | undefined;
 
-export { type DeployAppOptions, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployRecoveryInfo, type DeployResult, HaiDeployError, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, deploy, getDeployRecovery };
+export { type DeployAppOptions, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployRecoveryInfo, type DeployResult, type DockerSshProviderConfig, HaiDeployError, type PortExposeConfig, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, type SshConfig, deploy, getDeployRecovery };