部署脚本使用说明
脚本分层
| 类型 | 文件 | 说明 |
|---|---|---|
| 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 统一入口
# 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
核心阶段：
npm run check（可用-SkipCheck跳过）- 本地 Docker 构建（自动加载/缓存基础镜像）
- 推送镜像到
${Server}:5000/youyidian/<镜像名>:<Tag> - 目标服务器拉取镜像并
docker compose up -d --no-deps app /api/health轮询，确保服务恢复
常用参数：
-Server/-Username/-KeyPath：控制 SSH 目标与凭据-EnvFile：指定构建期.env.production-SkipCheck/-SkipBuild/-SkipUpload：按需跳过阶段-CleanImages -KeepImageCount 5：构建完成后自动清理旧镜像
兜底：安全部署脚本
.\scripts\deploy\安全部署.ps1
仍以“打包源码→上传→服务器内构建”方式执行，主要用于 Registry 无法使用的客户/测试环境。建议只在确认 Registry 流程不可行时才切换到该脚本。
其他：本地打包上传
.\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）。
功能特点
- Registry 优先：镜像统一托管在
${Server}:5000/youyidian/*，方便向客户交付。 - 阶段化输出：每个阶段均打印醒目标题，失败时便于快速定位。
- 健康检查：完成后自动轮询
/api/health，确认服务可用再退出。 - 容器友好：统一使用
docker compose，兼容docker-compose。 - 数据保护（仅安全部署脚本）：上传前自动备份
uploads/，部署完成再恢复。
安全建议
- 不要将密码提交到 Git：如果修改了脚本中的默认密码，确保不要提交到 Git 仓库
- 使用环境变量：可以考虑使用环境变量存储密码
- 定期更换密码：定期更换服务器密码
- 使用 SSH 密钥：如果可能，使用 SSH 密钥而不是密码（更安全）
故障排除
1. 连接失败
- 检查服务器地址和端口是否正确
- 检查网络连接
- 检查防火墙设置
2. 密码错误
- 确认密码正确
- 检查用户名是否正确
3. 构建失败
- 检查 Docker 是否正常运行
- 检查 Docker Compose 是否安装
- 查看构建日志获取详细错误信息
4. 文件上传失败
- 检查文件路径是否正确
- 检查服务器磁盘空间
- 检查文件权限
注意事项
- BuildKit：Dockerfile 默认启用 BuildKit，如果本地未开启可通过
$env:DOCKER_BUILDKIT=1（PowerShell）或export DOCKER_BUILDKIT=1（Bash）打开。 - PuTTY：仍需
plink.exe/pscp.exe（Windows 下）。可在 https://www.putty.org/ 下载。 - Host Key：首次连接服务器建议手动将指纹加入
known_hosts，避免脚本交互中断。 - 凭证管理：优先使用 SSH 密钥或加密密码文件，避免明文写入脚本。
更新日志
- 2025-11-26：将
deploy-new-fixed.ps1设为默认入口；安全部署脚本改为应急备用；README 按 Registry 流程重写。 - 2025-11-19：清理 legacy 脚本，仅保留安全部署 + 本地打包路径；README 改为按场景列举。
- v1.0.0：初始版本，支持 Docker 构建缓存、密码/密钥认证、自动备份。