脚本说明
更新时间：2026-05-08 部署相关脚本以
scripts/git-incremental-deploy.ps1为当前默认口径。
详细说明：
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提供。
预检：
.\scripts\git-incremental-deploy.ps1 -DryRun
正式环境：
.\scripts\git-incremental-deploy.ps1
影子环境：
.\scripts\git-incremental-deploy.ps1 -Target shadow
部署指定提交：
.\scripts\git-incremental-deploy.ps1 -Commit <commit-sha>
正式部署由维护人员执行，不要求普通用户手动运行。
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.ps1build-base-image.ps1scripts/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 图、详情图。
示例：
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。
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 上正式导入生产库时，必须启用：
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。
未确认清单前禁止执行正式硬删除。