106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
# 部署脚本使用说明
|
||
|
||
## 脚本分层
|
||
|
||
| 类型 | 文件 | 说明 |
|
||
| --- | --- | --- |
|
||
| **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 构建缓存、密码/密钥认证、自动备份。
|
||
|