# 部署脚本使用说明

## 脚本分层

| 类型 | 文件 | 说明 |
| --- | --- | --- |
| **Registry 统一入口（推荐）** | `deploy-new-fixed.ps1` | 当前主推流程。脚本在本地构建镜像 → 推送到私有 Registry → 远端拉取 & `docker compose up`，默认走 SSH 密钥，自动做健康检查。 |
| **源码直传（备用）** | `安全部署.ps1` / `安全部署.sh` | 仍保留作为兜底方案：将源码打包上传到服务器后再构建。仅在客户环境暂未配置 Registry、或 Registry 不可用时启用。 |
| **本地打包 + 上传** | `local-build-and-upload.ps1` | 在无法推镜像的场景下，先本地构建/打包，再通过 `scp` 上传到远端解压并 `docker compose up`。 |
| **增量/应急脚本** | `deploy-optimized.ps1`、`execute-remote-deploy.ps1` | 早期“直接上传源码 + 服务器构建”方案仍保留以备回退，但已退出默认流程。调用前请确认服务器网络具备拉取基础镜像的能力。 |
| **辅助排障** | `check-*.ps1`、`fix-*.ps1`、`setup-*.ps1`、`manual-import-image.ps1`、`export-and-upload-image.ps1` 等 | 用于检查 Docker/网络状态、修复私有 Registry、导出/导入镜像、创建客户离线包等。 |
| **安全工具** | `encrypt-password.ps1` / `decrypt-password.ps1` | 需要以明文密码方式部署时，可通过该工具生成/验证加密密钥文件，避免将密码直接写进脚本。 |

> ℹ️ 其余历史脚本（例如 `deploy-simple.ps1`、`deploy-with-ssh-key.ps1` 等）已在 2025-11-19 归档/删除，避免误用老旧流程。

## 快速开始

### 推荐：Registry 统一入口
```powershell
# Windows
.\scripts\deploy\deploy-new-fixed.ps1 -KeyPath "C:\Users\xxx\.ssh\youyidian_prod_ed25519"

# macOS / Linux
powershell -File scripts\deploy\deploy-new-fixed.ps1
```

核心阶段：
1. `npm run check`（可用 `-SkipCheck` 跳过）
2. 本地 Docker 构建（自动加载/缓存基础镜像）
3. 推送镜像到 `${Server}:5000/youyidian/<镜像名>:<Tag>`
4. 目标服务器拉取镜像并 `docker compose up -d --no-deps app`
5. `/api/health` 轮询，确保服务恢复

常用参数：
- `-Server` / `-Username` / `-KeyPath`：控制 SSH 目标与凭据
- `-EnvFile`：指定构建期 `.env.production`
- `-SkipCheck` / `-SkipBuild` / `-SkipUpload`：按需跳过阶段
- `-CleanImages -KeepImageCount 5`：构建完成后自动清理旧镜像

### 兜底：安全部署脚本
```powershell
.\scripts\deploy\安全部署.ps1
```
仍以“打包源码→上传→服务器内构建”方式执行，主要用于 Registry 无法使用的客户/测试环境。建议只在确认 Registry 流程不可行时才切换到该脚本。

### 其他：本地打包上传
```powershell
.\scripts\deploy\local-build-and-upload.ps1 `
  -Server "192.168.1.100" `
  -User "root" `
  -Password "****" `
  -ProjectPath "/root/youyidian-3d"
```

> ⚠️ 此脚本仍会在服务器端执行 `docker compose build`，需要确保远程机器能访问基础镜像或提前导入（可搭配 `export-and-upload-image.ps1` / `manual-import-image.ps1`）。

## 功能特点

1. **Registry 优先**：镜像统一托管在 `${Server}:5000/youyidian/*`，方便向客户交付。
2. **阶段化输出**：每个阶段均打印醒目标题，失败时便于快速定位。
3. **健康检查**：完成后自动轮询 `/api/health`，确认服务可用再退出。
4. **容器友好**：统一使用 `docker compose`，兼容 `docker-compose`。
5. **数据保护**（仅安全部署脚本）：上传前自动备份 `uploads/`，部署完成再恢复。

## 安全建议

1. **不要将密码提交到 Git**：如果修改了脚本中的默认密码，确保不要提交到 Git 仓库
2. **使用环境变量**：可以考虑使用环境变量存储密码
3. **定期更换密码**：定期更换服务器密码
4. **使用 SSH 密钥**：如果可能，使用 SSH 密钥而不是密码（更安全）

## 故障排除

### 1. 连接失败
- 检查服务器地址和端口是否正确
- 检查网络连接
- 检查防火墙设置

### 2. 密码错误
- 确认密码正确
- 检查用户名是否正确

### 3. 构建失败
- 检查 Docker 是否正常运行
- 检查 Docker Compose 是否安装
- 查看构建日志获取详细错误信息

### 4. 文件上传失败
- 检查文件路径是否正确
- 检查服务器磁盘空间
- 检查文件权限

## 注意事项

1. **BuildKit**：Dockerfile 默认启用 BuildKit，如果本地未开启可通过 `$env:DOCKER_BUILDKIT=1`（PowerShell）或 `export DOCKER_BUILDKIT=1`（Bash）打开。
2. **PuTTY**：仍需 `plink.exe`/`pscp.exe`（Windows 下）。可在 https://www.putty.org/ 下载。
3. **Host Key**：首次连接服务器建议手动将指纹加入 `known_hosts`，避免脚本交互中断。
4. **凭证管理**：优先使用 SSH 密钥或加密密码文件，避免明文写入脚本。

## 更新日志

- **2025-11-26**：将 `deploy-new-fixed.ps1` 设为默认入口；安全部署脚本改为应急备用；README 按 Registry 流程重写。
- **2025-11-19**：清理 legacy 脚本，仅保留安全部署 + 本地打包路径；README 改为按场景列举。
- **v1.0.0**：初始版本，支持 Docker 构建缓存、密码/密钥认证、自动备份。