# EasyAI Windows 一键部署方案

## 1. 背景与目标

`start.sh` 是 Linux 下的一键部署脚本，本方案为 Windows 平台提供等效的 `start.ps1` PowerShell 脚本。针对 Windows 典型场景做如下**精简**：

- **仅 IP 访问**：不含域名模式与 HTTPS
- **本地访问无需放行端口**：选择本地 (127.0.0.1) 时，不涉及防火墙配置
- **Docker 未安装时**：用户可选择手动或自动安装 **Docker Desktop for Windows**（winget/Chocolatey）
- **支持变量非交互部署**：通过 `DEPLOY_IP` 或 `DEPLOY_ACCESS=local` 可跳过访问方式选择

## 2. Linux start.sh 流程梳理

### 2.1 整体流程

| 步骤 | 功能 | 说明 |
|------|------|------|
| 1 | 项目初始化 | 校验当前目录下存在 `docker-compose.yml` |
| 2 | 部署配置问答 | IP 或域名二选一，并采集对应参数 |
| 3 | 配置文件生成 | 生成/更新 `.env`、`.env.tools`、`.env.ASG` |
| 4 | Docker 安装与检查 | 检测并安装 Docker（Ubuntu/CentOS） |
| 5 | 启动服务 | `docker compose pull && docker compose up -d` |
| 6 | HTTPS 配置（可选） | 域名模式下执行 `https.sh` |

### 2.2 配置问答逻辑

- **IP 模式**：输入服务器 IP 地址，需要放行 3001、3002、3003 端口
- **域名模式**：输入域名，可选是否启用 HTTPS，需放行 80、443 端口

### 2.3 环境变量写入 .env

- `NUXT_PUBLIC_BASE_APIURL`：API 地址
- `NUXT_PUBLIC_BASE_SOCKETURL`：WebSocket 地址
- `NUXT_PUBLIC_SG_APIURL`：Agent 服务治理 API 地址

**IP 模式**：
```
NUXT_PUBLIC_BASE_APIURL=http://<IP>:3001
NUXT_PUBLIC_BASE_SOCKETURL=ws://<IP>:3002
NUXT_PUBLIC_SG_APIURL=http://<IP>:3003
```

**域名模式**：
```
NUXT_PUBLIC_BASE_APIURL=/api
NUXT_PUBLIC_BASE_SOCKETURL=wss://<domain>/socket.io
NUXT_PUBLIC_SG_APIURL=/asg-api
```

---

## 3. Windows 与 Linux 差异

| 项目 | Linux | Windows |
|------|-------|---------|
| 脚本语言 | Bash | PowerShell |
| 文本替换 | sed | `(Get-Content) -replace` 或 `Set-Content` |
| 用户输入 | `read -p` | `Read-Host` |
| 访问方式 | IP + 域名 + HTTPS | **仅 IP**（本地 / 局域网） |
| 端口放行 | 本地无特殊说明 | **本地访问无需放行**，局域网需放行 3001/3002/3003 |
| Docker | apt/yum 安装 Linux Docker | **Docker Desktop for Windows**，未安装时可选择手动或自动安装 |

---

## 4. Windows IP 访问方式设计（核心差异）

Windows 版**仅支持 IP 访问**，不包含域名模式与 HTTPS 配置。用户访问方式分为两类：

| 选项 | 访问方式 | IP 值 | 端口说明 |
|------|----------|-------|----------|
| 1 | 本地访问 | `127.0.0.1` | 本机访问，**无需放行端口** |
| 2 | 局域网访问 | 用户输入本机局域网 IP | 同网段设备访问，需放行 3001、3002、3003 |

**交互流程：**

1. `[1] 本地访问` → 自动使用 `127.0.0.1`，无需配置防火墙
2. `[2] 局域网访问` → 提示用户输入局域网 IP（可提示 `ipconfig` 查看），并提醒放行上述端口

---

## 5. 实现方案

### 5.1 脚本文件

- 文件路径：`easyai/start.ps1`
- 一行命令示例：
  ```powershell
  git clone https://git.51easyai.com/wangbo/easyai; cd easyai; .\start.ps1
  ```

### 5.2 模块划分

| 模块 | 函数/区块 | 功能 |
|------|-----------|------|
| 项目初始化 | `Init-ProjectDir` | 检查 `docker-compose.yml`，切换到项目根目录 |
| 配置问答 | `Run-DeployQuestions` | 本地访问 / 局域网访问选择（含 IP 输入） |
| 环境变量 | `PromptOrEnv` | 支持环境变量覆盖，用于 CI/自动化 |
| 配置文件 | `Setup-EnvFiles` | 复制 sample 并修改 `.env`、`.env.tools`、`.env.ASG` |
| Docker 检查 | `Test-Docker` | 检测 `docker`，未安装则让用户选择**手动安装**或**自动安装** |
| 启动服务 | `Start-Services` | `docker compose pull` 与 `docker compose up -d` |
| 主流程 | `Main` | 串联上述步骤 |

### 5.3 环境变量支持（非交互模式）

| 变量 | 说明 |
|------|------|
| `DEPLOY_ACCESS` | `local` 时直接使用 `127.0.0.1`；`lan`/`ip` 需要同时传 `DEPLOY_IP` |
| `DEPLOY_IP` | 访问 IP（本地填 `127.0.0.1`，局域网填实际 IP） |
| `DEPLOY_DRY_RUN` | 1 时只生成配置，不安装/启动 Docker |
| `DEPLOY_FORCE_RECONFIG` | 非空时强制重新配置 |
| `DEPLOY_NON_INTERACTIVE` | 1 时缺少必要变量会直接报错，不进入问答 |
| `DEPLOY_DOCKER_INSTALL` | Docker Desktop 未安装时使用，`manual` 打开下载地址，`auto` 使用 winget/choco 自动安装 |
| `DEPLOY_NO_WAIT` | 1 时脚本结束或失败不等待按 Enter |

### 5.4 配置文件修改实现（仅 IP 模式）

使用 PowerShell 替换 `.env` 中相关行：

```powershell
$content = Get-Content .env -Raw -Encoding UTF8
$content = $content -replace 'NUXT_PUBLIC_BASE_APIURL=.*', "NUXT_PUBLIC_BASE_APIURL=http://${DEPLOY_IP}:3001"
$content = $content -replace 'NUXT_PUBLIC_BASE_SOCKETURL=.*', "NUXT_PUBLIC_BASE_SOCKETURL=ws://${DEPLOY_IP}:3002"
$content = $content -replace 'NUXT_PUBLIC_SG_APIURL=.*', "NUXT_PUBLIC_SG_APIURL=http://${DEPLOY_IP}:3003"
Set-Content .env -Value $content -Encoding UTF8 -NoNewline
```

### 5.5 Docker 处理策略

- **目标**：检测并安装 **Docker Desktop for Windows**（Windows 版 Docker）
- **检测**：执行 `docker --version` 或 `docker compose version`
- **未安装时**： prompt 让用户选择
  - `[1] 手动安装`：输出安装说明及 Docker Desktop for Windows 下载链接，退出脚本
  - `[2] 自动安装`：通过 winget 或 Chocolatey 安装 Docker Desktop for Windows，安装后需用户重启终端/机器再继续
- 若设置 `DEPLOY_DOCKER_INSTALL=manual|auto`，脚本会直接执行对应分支，不再提示选择

### 5.6 执行策略

PowerShell 默认可能禁止执行脚本，建议在文档中说明：

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

或在脚本开头提示用户使用：

```powershell
powershell -ExecutionPolicy Bypass -File .\start.ps1
```

---

## 6. 部署完成输出

成功部署后输出访问地址，例如：

- 本地访问：`http://127.0.0.1:3010`
- 局域网访问：`http://<LAN_IP>:3010`

---

## 7. 实现清单

- [x] 创建 `start.ps1` 主脚本
- [x] 实现 `Init-ProjectDir`：项目目录校验
- [x] 实现 `Run-DeployQuestions`：本地 / 局域网 IP 选择（无域名/HTTPS）
- [x] 实现 `Setup-EnvFiles`：配置文件生成与替换
- [x] 实现 `Test-Docker`：Docker 检测，未安装时 prompt「手动安装」或「自动安装」
- [x] 实现 `Install-Docker`：自动安装 **Docker Desktop for Windows**（winget / Chocolatey）
- [x] 实现 `Start-Services`：`docker compose` 启动
- [x] 实现 `Main`：主流程串联
- [x] 支持 `DEPLOY_DRY_RUN`、`DEPLOY_IP` 环境变量非交互模式
- [x] 支持 `DEPLOY_ACCESS=local`、`DEPLOY_NON_INTERACTIVE`、`DEPLOY_DOCKER_INSTALL` 非交互控制
- [x] 在 README 或文档中补充 Windows 部署说明与执行策略
- [x] 创建 `scripts/test-start-ps1-env.py` 验证 .env 替换逻辑

---

## 8. Windows 测试说明

### 本地测试（需 Windows 或 WSL + PowerShell）

```powershell
# 非交互 + 仅生成配置（不启动 Docker）
$env:DEPLOY_DRY_RUN = "1"
$env:DEPLOY_IP = "127.0.0.1"
.\start.ps1

# 或使用本机访问模式变量
$env:DEPLOY_DRY_RUN = "1"
$env:DEPLOY_ACCESS = "local"
$env:DEPLOY_NO_WAIT = "1"
.\start.ps1

# 检查 .env 是否已正确写入
Select-String -Path .env -Pattern "NUXT_PUBLIC_BASE"
```

### 完整部署测试（需 Windows + Docker Desktop）

```powershell
.\start.ps1
# 按提示选择 [1] 本地访问 或 [2] 局域网访问
# 若未安装 Docker，选择 [1] 手动 或 [2] 自动安装
```

### 执行策略（若提示无法运行脚本）

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 或
powershell -ExecutionPolicy Bypass -File .\start.ps1
```