# 脚本说明

> 更新时间：2026-05-08
> 部署相关脚本以 `scripts/git-incremental-deploy.ps1` 为当前默认口径。

详细说明：

- [部署规范](../docs/部署规范.md)
- [Git 增量部署方案](../docs/Git增量部署方案.md)
- [部署脚本安全说明](../docs/部署脚本安全说明.md)

## 1. 核心部署脚本

### `scripts/git-incremental-deploy.ps1` ⭐⭐⭐ 当前推荐

以 Git 仓库为唯一源码入口，构建机增量拉取源码并构建镜像，生产服务器只拉取镜像并替换容器。

特点：

- 不从本机上传源码压缩包。
- 构建机执行 `git fetch/reset`。
- Docker 构建继续复用缓存。
- 镜像按提交打标签，便于回滚。
- 生产机不构建源码，只拉镜像运行。
- 默认失败时尝试回滚旧镜像。
- 默认清理 Docker 无用镜像/容器，保留构建缓存。

运行前准备：

- 本机可用 PowerShell 5.1+。
- 本机已安装 PuTTY，`plink.exe` 和 `pscp.exe` 可用。
- 构建机密码通过 `BUILD_SERVER_PASSWORD` 或 `-BuildServerPassword` 提供。
- Git 认证通过 `GIT_DEPLOY_USERNAME` / `GIT_DEPLOY_PASSWORD` 或 `GIT_AUTH_HEADER` 提供。

预检：

```powershell
.\scripts\git-incremental-deploy.ps1 -DryRun
```

正式环境：

```powershell
.\scripts\git-incremental-deploy.ps1
```

影子环境：

```powershell
.\scripts\git-incremental-deploy.ps1 -Target shadow
```

部署指定提交：

```powershell
.\scripts\git-incremental-deploy.ps1 -Commit <commit-sha>
```

正式部署由维护人员执行，不要求普通用户手动运行。

### `scripts/git-incremental-deploy-macos.sh` Mac 调度入口

Mac 不构建生产镜像。该入口负责校验精确 Git 提交、固定 SSH 主机身份并把临时调度脚本送到构建机；远端执行内容直接读取 `git-incremental-deploy.ps1` 的同一份模板，因此 Docker 构建、镜像身份、生产切换、健康检查和回滚规则不会分叉。

```bash
./scripts/git-incremental-deploy-macos.sh --dry-run
./scripts/git-incremental-deploy-macos.sh --commit '<40位小写提交SHA>'
```

默认使用 `~/.ssh/gongxiangp2_build_machine`，不接受或保存 SSH 密码。

## 2. 历史部署脚本

### `deploy-*.ps1` 本地历史脚本名

根目录 `deploy-*.ps1` 属于本地历史脚本名，受 `.gitignore` 保护，不作为仓库交付入口。

曾经出现过的旧链路包括：

- `deploy-remote-build.ps1`：本机打包源码并上传到构建机。
- `deploy-local-build.ps1`：本地构建部署。
- `deploy-public-build.ps1`：公网穿透部署。

这些名字只用于识别历史资料，不再作为当前推荐方式。

### `deploy-git-build.ps1` ⚠️ 已替代

旧 Git 工作流脚本已被 `scripts/git-incremental-deploy.ps1` 替代。后续 Git 增量部署只看新脚本。

## 3. 旧缓存脚本

下面这些脚本属于早期构建缓存方案，不是当前 Git 增量部署的默认前置步骤：

- `setup-build-cache.ps1`
- `build-base-image.ps1`
- `scripts/manage-build-cache.ps1`

只有在明确要维护旧缓存方案时才参考它们。当前常规部署优先使用构建机上的 Docker / Next 缓存，不再传播 `save-base-images.ps1`、`load-base-images.ps1`、`save-npm-packages.ps1` 这类已不存在的脚本名。

## 4. 数据库迁移脚本

### `scripts/execute-migration.ps1`

历史一次性迁移工具，只针对 `20251206000000_add_soft_delete_and_favorites` 这一个迁移，不是通用生产迁移入口。

高风险要求：

- 先确认该迁移在生产库尚未执行。
- 先确认生产库备份可用。
- 不在用户高峰期执行。
- 不把它当作普通部署流程的一部分。

### `scripts/execute-migration.sh`

Linux / macOS 版本的一次性迁移工具，适用范围同上。

## 5. 历史素材 SPU 台账与导入脚本

### `scripts/scan_spu_ledger.py` ⭐ 当前历史素材新入口

按 SPU / 组合 SPU / 版本工作区维度扫描真实素材目录，生成 SQLite 台账。

重要口径：

- 不读取旧的 SKU 锚点 CSV/SQLite 输出。
- 组合 SPU 原样保留，例如 `GBSFY-AD0297+GBSFY-CZ0102`。
- 目录名不是标准 SPU 时，即使文件名能反推，也只标记 `needs_review`。
- 店铺归属按当前业务口径：`金牌项目-1` 和 `GBJP-*` 归到 `顾家`，不再使用 `金牌` 店铺。
- `正版`、`盗版` 都允许进入候选；`错误勿用`、`废稿`、`勿用` 默认跳过。
- ready 要求同时存在主图、SKU 图、详情图。

示例：

```powershell
python scripts\scan_spu_ledger.py `
  --roots "Z:\顾家项目|Z:\金牌项目-1|Z:\朴美项目|Z:\索菲亚项目" `
  --db-path "output\tianlan-spu-ledger.db" `
  --source-batch "tianlan-z" `
  --reset
```

### `scripts/export_spu_ledger.py`

从 SPU 台账导出 review CSV、每 20 个工作区一个批次 CSV、汇总 JSON，以及可供历史导入脚本使用的 ready JSON。

```powershell
python scripts\export_spu_ledger.py `
  --db-path "output\tianlan-spu-ledger.db" `
  --output-dir "output" `
  --prefix "tianlan-spu-ledger"
```

### `scripts/import-history-materials.ts` / `scripts/run-history-import-queue.ts`

继续作为历史素材导入执行入口。新的 SPU 台账 ready JSON 可以直接作为输入，并支持 `任务-详情` 的 PS 源文件通道。

正式导入的关键边界：

- Windows 维护机可以读取 `Z:\...` 源素材，但不能只靠本机 `uploads` 写生产库。
- 连接生产库并执行 `--apply` 时，预览图必须写入新桶 `gongxiangpan`，公开地址必须是 `https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/...`。
- ZIP / PSD / 源文件必须最终同步到生产机独立 ZFS 数据集 `/mnt/PoolOne/youyidian-uploads`，并通过大小校验。
- 在 Windows 上正式导入生产库时，必须启用：

```env
HISTORY_IMPORT_REMOTE_UPLOADS_HOST=prod
HISTORY_IMPORT_REMOTE_UPLOADS_DIR=/mnt/PoolOne/youyidian-uploads
```

没有远程 uploads 同步配置时，脚本会阻止 `--apply`，避免再次出现数据库有记录但线上下载 404。

### `scripts/hard-delete-history-materials.ts`

只用于已经确认的旧批次错误素材硬删除。默认只做备份/演练；正式执行必须同时满足：

- 候选清单里有 `materialId` 和删除原因。
- 候选清单提供的 `fingerprint` 或 `sourcePath` 能在该素材的 `HISTORY_IMPORT` 日志中匹配。
- 命令包含 `--apply --confirm=HARD_DELETE_HISTORY_MATERIALS`。

未确认清单前禁止执行正式硬删除。