vcs-patch-deploy 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,53 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.3.0
4
+
5
+ ### 新增
6
+
7
+ - **自定义 apply 脚本**:`--apply-script=<文件>` / `PATCH_APPLY_SCRIPT`,项目无需再写包装脚本即可使用自己的 `apply-update.php`
8
+ - **多环境基准**:`--profile=<名称>` / `PATCH_PROFILE`,使用 `deploy/.last-deploy-marker.<名称>`,生产与预发(如 php85)互不影响;指定 profile 时不回退默认 marker
9
+ - **受保护文件**:`deploy/protect.txt`、`--protect=`、`--protect-file=`、`PATCH_PROTECT`;包内生成 `PROTECT.txt`,`apply-update.php` 对线上已存在的受保护文件跳过覆盖(首次部署仍写入),`--check` 与回滚同样生效;`patch-extract` 支持追加保护文件并与源包清单合并
10
+ - **SVN 工作副本打包**:`--worktree-diff` / `PATCH_DIFF_WORKTREE=true`,合并 `svn diff -r <from>` 与 `svn status`,支持未提交改动、未纳入版本控制的文件与新增目录;产物 `patch-wc-<时间戳>`,不自动更新基准,存在冲突时拒绝打包
11
+ - **exec 禁用保护**:`apply-update.php` 检测 `disable_functions`,`exec` 不可用时跳过 `php think clear` 并提示
12
+ - **可执行位跨平台保留**:从 Git 索引(`100755`)/ SVN `svn:executable`(XML 属性输出)识别可执行文件,zip 内写 `0755`,并生成包内 `MODES.txt`;服务器端部署后据此 `chmod`;非 Windows 上同时参考实际文件权限
13
+ - **备份会话保留策略**:`--keep-backups=N` / `PATCH_KEEP_BACKUPS`(默认 10),部署成功后自动清理更早的备份;中断会话单独限额(最多 5 个、24 小时)
14
+ - **备份目录防 Web 访问**:默认备份目录位于站点根内时给出告警,并写入 `.htaccess`(deny)与 `index.html`
15
+ - **子集包独立版本标识**:`version=<源版本>-partial-<hash>` + `partial=1`(`--only` 打包与 `patch-extract` 均生效),服务器端回滚时提示“仅恢复其中的文件”
16
+ - **同版本重建告警**:目标版本不同却复用同一 `--version` 时提示产物将被覆盖
17
+ - **deploy/out 自动清理**:`--prune-out` / `PATCH_PRUNE_OUT`,构建后按 `--keep-out`(默认同 `--keep-versions`)清理旧的 `patch-*` 目录与 zip;当前构建始终保留,不触碰其他文件,中断残留的 staging 目录超过 1 小时后清理
18
+ - **归档硬链接**:`--link-archive` / `PATCH_ARCHIVE_LINK`,`deploy/archive/` 优先硬链接 out 产物以节省磁盘;跨盘或不支持硬链接时自动退回复制
19
+
20
+ ### 修复
21
+
22
+ - **子集包版本语义**:`patch-build --only` 之前仍写完整版本号且无 `partial=1`,服务器会按完整包装处理,可能导致回滚静默只恢复子集文件;现与 `patch-extract` 统一
23
+ - **工作副本版本标签**:带 `--version` 时 VERSION.txt 不再丢失版本前缀(与目录名、versions.json 一致)
24
+ - **部署端路径校验**:`apply-update.php` 拒绝目标为符号链接,并要求父目录 `realpath` 位于 Backend 根内(防止目录软链逃逸)
25
+ - **备份/回滚保留权限**:备份元数据记录原 `mode`,回滚恢复文件后按记录 `chmod`
26
+ - **备份保留完整性**:无元数据的中断/旧包会话不再永久堆积;`--list-backups` 不再列出空会话
27
+ - **同版本回滚**:重复部署产生的 `_<时间戳>` 会话会被正确选中(取最近一次)
28
+ - **SVN 工作副本扫描剪枝**:未纳入版本控制的目录按排除规则跳过(`node_modules/`、`runtime/`、`deploy/out/` 等),并限制文件数上限
29
+ - **工作副本包不写版本归档**:`--worktree-diff` 产物只保留在 `deploy/out`,不占用 `archive/` 的 `keepVersions` 名额;带 `--version` 时使用独立版本标识
30
+ - **参数冲突**:`--worktree-diff` 与 `--to` 同时使用时直接报错
31
+ - **未知 CLI 参数**:不再只告警继续,改为直接失败并提示 `--name=value` 形式,避免拼写错误生成非预期包
32
+ - **patch-extract 删除清单**:按提取范围过滤,子集包不再继承完整包的无关删除提示;`--from-patch` 未传版本号时沿用源包 VERSION
33
+ - **zip 原子写入**:先写临时文件再替换,失败时不会留下截断的 zip 或提前销毁旧产物
34
+ - **SVN 可执行位**:读取失败不再静默降级为 0644,会给出告警;属性输出改用 XML,避免路径含 ` - ` 时误解析
35
+ - **打包内容一致性**:打包前校验工作区与目标版本是否一致(Git 比对目标 commit,SVN 比对目标 revision),不一致时中止,避免 zip 内容与 MANIFEST 声明不符;可用 `--from-worktree` / `PATCH_FROM_WORKTREE=true` 显式跳过
36
+ - **子集包不再覆盖完整包**:`--only` / `--file-list` 产物使用 `patch-v1.2.3-partial-<hash>`(无版本号时 `patch-r467-partial-<hash>`)独立命名,`versions.json` 与 `archive/` 同步区分
37
+ - **Git 子目录源码**:`--source` 指向仓库子目录时,diff 路径会正确映射(支持中文路径,`core.quotepath=false`)
38
+ - **SVN**:识别 `R`(替换)状态;跳过目录条目,避免把目录递归复制进补丁包
39
+ - **patch-extract**:`--list-versions` / `--from-patch` 不再要求当前目录是 VCS 工作区
40
+ - **deploy 元数据排除**:`deploy/.last-deploy-*`、`deploy/versions.json`、`deploy/protect.txt`、`deploy/archive/`、`.deploy-backups/` 不再进入补丁包
41
+ - **归档与登记表**:`versions.json` / `archive/index.json` 保存相对 deploy 的路径(项目迁移后仍可用);完整包与子集包分别保留;工作副本登记只保留最近 5 条
42
+
43
+ ### 改进
44
+
45
+ - **服务器脚本**:兼容 PHP 7.4(内置 `str_starts_with` / `str_ends_with` polyfill,要求 PHP >= 7.4);CI 增加 PHP 7.4/8.3 语法检查与冒烟测试(`test/php-smoke.sh`)
46
+ - **本地检查**:`npm run check`(`node --check` 覆盖 `bin/`、`lib/`、`test/`、`scripts/`),`npm test` 自动前置执行
47
+ - **路径安全**:`apply-update.php` 与 MANIFEST 解析拒绝绝对路径、`../` 逃逸与符号链接;任意目录下的 `.env` / `.env.*` 均不覆盖
48
+ - **回滚更完整**:记录本次新增文件及其 sha256,回滚时删除未被修改过的新增文件(修改过的保留并提示)
49
+ - **仅删除项的包**:服务器端仍会提示 `MANIFEST-deleted.txt`,不再因无文件可部署而漏掉提示
50
+
3
51
  ## 1.2.0
4
52
 
5
53
  ### 新增
package/README.md CHANGED
@@ -16,6 +16,8 @@ npm install --save-dev vcs-patch-deploy
16
16
  npx patch-build --help
17
17
  ```
18
18
 
19
+ 环境要求:打包端 Node.js >= 18;服务器端 PHP >= 7.4(兼容 ThinkPHP 5/6)。
20
+
19
21
  ## 快速开始(ThinkPHP + SVN)
20
22
 
21
23
  在 **PHP 项目根目录**(含 `app/`、`application/`、`config/` 或 `think`)执行:
@@ -39,6 +41,13 @@ patch-build --vcs=svn
39
41
 
40
42
  SVN 常见目录结构为 `repo-root/trunk`,进入 `trunk` 后执行上述命令即可。
41
43
 
44
+ 打包内容从**工作区**复制。为避免包内容与 `from..to` 声明不一致,打包前会校验工作区是否与目标版本一致:
45
+
46
+ - SVN:`svn diff -r <to> --summarize` 有差异(未 update / 混合版本 / 本地改动)时中止
47
+ - Git:`git diff <to> -- <文件>` 有差异(工作区未切到目标 commit / 未提交改动)时中止
48
+
49
+ 确有需要时用 `--from-worktree` 明确允许按当前工作区内容打包(MANIFEST 会记录 `content_source=working-copy`)。
50
+
42
51
  ## Git 仓库
43
52
 
44
53
  ```bash
@@ -71,6 +80,23 @@ patch-extract --list-versions
71
80
  # deploy/versions.json
72
81
  ```
73
82
 
83
+ 同一版本号的子集包会使用独立后缀(`--only` / `--file-list` 组合的短哈希),不会覆盖完整包:
84
+
85
+ ```text
86
+ deploy/out/patch-v1.2.3/ 完整包
87
+ deploy/out/patch-v1.2.3-partial-a1b2c3d4/ 子集包
88
+ deploy/out/patch-r467-partial-a1b2c3d4/ 无版本号时的子集包
89
+ ```
90
+
91
+ 子集包(`patch-build --only` 与 `patch-extract` 提取包)的 `VERSION.txt` 会写入
92
+ `version=<源版本>-partial-<hash>` 与 `partial=1`,服务器据此按**部分部署**处理;
93
+ `deploy/archive/` 中完整包与子集包分别保留 `--keep-versions` 个,避免热修复包挤掉正式版本归档。
94
+
95
+ 重复打包会在 `deploy/out/` 累积产物,可用 `--prune-out` 自动清理旧的 `patch-*` 目录与 `<zip-prefix>-*.zip`:
96
+ 保留数量由 `--keep-out` 控制(默认同 `--keep-versions`),当前构建始终保留,且不会触碰其他文件。
97
+ 归档与 out 在同一磁盘时,可加 `--link-archive` 用硬链接代替整份复制,节省约一半空间(跨盘自动退回复制);
98
+ 注意硬链接共享文件内容,之后修改 `deploy/out` 中的产物会同时改变归档。
99
+
74
100
  服务器上也可在完整 patch 包内**只部署部分文件**:
75
101
 
76
102
  ```bash
@@ -80,6 +106,98 @@ export PATCH_DEPLOY_FILES=app/service/Foo.php,app/controller/Bar.php
80
106
  php apply-update.php /path/to/production-api
81
107
  ```
82
108
 
109
+ ## 自定义 apply-update.php
110
+
111
+ 项目内如需修改服务器脚本(自定义环境变量、跳过特定文件、权限修复等),不必改 npm 包,也不必再写包装脚本:
112
+
113
+ ```bash
114
+ patch-build --vcs=git --apply-script=deploy/apply-update.php
115
+ ```
116
+
117
+ - 也可用 `PATCH_APPLY_SCRIPT=deploy/apply-update.php`
118
+ - 包内文件始终命名为 `apply-update.php`(与源文件名无关)
119
+ - `patch-extract` 同样支持 `--apply-script=`
120
+ - 未指定时使用插件自带模板 `assets/php/apply-update.php`
121
+
122
+ ## 可执行文件权限(MODES.txt)
123
+
124
+ 在 Windows 上打包时,文件系统不体现 Unix 执行位,普通 zip 会让 `.sh`、`think` 等文件丢掉 `0755`。插件会从 VCS 元数据识别可执行文件:
125
+
126
+ - Git:读取索引模式 `100755`(`git ls-files -s`)
127
+ - SVN:读取 `svn:executable` 属性(`svn propget -R`)
128
+
129
+ 命中的文件会:
130
+
131
+ 1. 以 `0755` 写入 zip(其余文件固定 `0644`,目录 `0755`)
132
+ 2. 写入包内 `MODES.txt`,服务器端部署后据此 `chmod`
133
+ 3. 子集提取时随包复制,保持同样权限
134
+
135
+ ```text
136
+ # MODES.txt
137
+ # mode 相对路径(0755 = 可执行)
138
+ 0755 app/console/run.sh
139
+ ```
140
+
141
+ ## 受保护文件(不覆盖线上运行时配置)
142
+
143
+ 有些配置文件被版本控制跟踪,但线上会被程序改写(如 `config/date_config.json`)。
144
+ 把它们加入保护清单后,**线上已存在时不覆盖**;线上不存在时仍会写入(便于首次部署)。
145
+
146
+ ```bash
147
+ # 方式一:项目内持久配置 deploy/protect.txt(每行一个相对路径)
148
+ cat > deploy/protect.txt <<'EOF'
149
+ config/date_config.json
150
+ # 注释行会被忽略
151
+ EOF
152
+
153
+ # 方式二:打包时指定
154
+ patch-build --vcs=git --protect=config/date_config.json
155
+ patch-build --vcs=git --protect-file=protect-files.txt
156
+ export PATCH_PROTECT=config/date_config.json,config/site.json
157
+ ```
158
+
159
+ 打包后在包内生成 `PROTECT.txt`,`apply-update.php` 会打印 `PROTECT: N 个文件`,并对已存在的受保护文件输出:
160
+
161
+ ```text
162
+ SKIP config/date_config.json — 受保护文件(线上已存在,未覆盖)
163
+ ```
164
+
165
+ `--check` 同样跳过(不计为失败);回滚也不会删除受保护文件。`deploy/protect.txt` 本身不会进入补丁包。
166
+
167
+ ## 多环境基准(profile)
168
+
169
+ 同一仓库需要分别向生产、预发(如不同 PHP 版本)部署时,用 profile 隔离基准:
170
+
171
+ ```bash
172
+ # 预发环境使用 deploy/.last-deploy-marker.php85
173
+ patch-build --vcs=git --profile=php85
174
+ patch-build --vcs=svn --profile=php85 --mark-deployed
175
+ # 或 export PATCH_PROFILE=php85
176
+ ```
177
+
178
+ - 默认(不带 profile)仍使用 `deploy/.last-deploy-marker`
179
+ - 指定 profile 时**不会**回退读取默认 marker / `.last-deploy-rev`,避免跨环境误用基准
180
+ - profile 仅允许字母、数字、`.` `_` `-`
181
+
182
+ ## SVN 工作副本打包(含未提交改动)
183
+
184
+ 默认 SVN 模式只按 revision 对比,要求工作副本干净。需要把本地未提交的改动直接打包时:
185
+
186
+ ```bash
187
+ patch-build --vcs=svn --worktree-diff
188
+ # 或 PATCH_DIFF_WORKTREE=true
189
+ ```
190
+
191
+ 行为:
192
+
193
+ - 以 `deploy/.last-deploy-marker`(或 `--from=`)为基准,合并 `svn diff -r <from>`(已提交 + 本地修改)与 `svn status`(新增、未纳入版本控制的文件、删除)
194
+ - 未纳入版本控制的目录会展开为具体文件;存在未解决冲突时拒绝打包
195
+ - 产物标识为 `patch-wc-<时间戳>` / `backend-update-wc-<时间戳>.zip`,MANIFEST 记录 `to_revision=working-copy`、`content_source=working-copy`
196
+ - 工作副本包**不写入** `deploy/archive/`(避免挤掉版本归档),产物保留在 `deploy/out`;带 `--version` 时版本标识为 `<版本>-wc-<时间戳>`(VERSION.txt 与 versions.json 一致)
197
+ - **不会**自动更新基准(工作副本内容不对应任何 revision);上线成功后应提交代码,再用 `--mark-deployed` 指向提交后的 revision
198
+ - `--worktree-diff` 与 `--to` 不能同时使用(目标固定为 working-copy)
199
+ - Git 请先提交后按 commit 打包(或用 `--from-worktree` 放宽一致性校验)
200
+
83
201
  ## 服务器应用
84
202
 
85
203
  ```bash
@@ -97,10 +215,15 @@ php apply-update.php
97
215
  `apply-update.php` 行为:
98
216
 
99
217
  - 按包内路径覆盖线上文件
100
- - **覆盖前备份** 线上已有文件到 `Backend/.deploy-backups/<时间戳>/`(保持相对路径)
101
- - **不覆盖** `.env`
102
- - **不自动删除** `MANIFEST-deleted.txt` 中的文件
103
- - 成功后清理 `runtime/cache`,并尝试 `php think clear`
218
+ - **覆盖前校验目标**:拒绝目标为符号链接;父目录 `realpath` 必须在 Backend 根内(防止父目录软链逃逸)
219
+ - **覆盖前备份** 线上已有文件到 `Backend/.deploy-backups/<版本>/`(保持相对路径),并记录原权限
220
+ - **不覆盖** `.env` 与任意目录下的 `.env.*`
221
+ - **不覆盖** 包内 `PROTECT.txt` 列出且线上已存在的文件(首次部署仍写入)
222
+ - **拒绝** 包内绝对路径、`../` 逃逸路径与符号链接
223
+ - **不自动删除** `MANIFEST-deleted.txt` 中的文件(`--check` 也会提示)
224
+ - 按包内 `MODES.txt` 恢复可执行位(Windows 打包时 zip 无法携带 exec 位)
225
+ - 成功后清理 `runtime/cache`,并尝试 `php think clear`(`exec` 被禁用时自动跳过)
226
+ - 回滚时恢复旧文件及权限,并删除本次新增且部署后未被修改的文件(按 sha256 校验)
104
227
 
105
228
  备份相关:
106
229
 
@@ -108,13 +231,35 @@ php apply-update.php
108
231
  # 默认开启备份;跳过备份
109
232
  php apply-update.php --no-backup /path/to/production-api
110
233
 
111
- # 自定义备份根目录(仍会在其下创建 <时间戳>/ 子目录)
234
+ # 自定义备份根目录(仍会在其下创建 <版本>/ 子目录)
112
235
  export PATCH_BACKUP_DIR=/data/backups/my-api
113
236
  php apply-update.php /path/to/production-api
237
+
238
+ # 备份会话保留数量(默认 10,部署成功后自动清理更早的会话)
239
+ php apply-update.php --keep-backups=5 /path/to/production-api
240
+ export PATCH_KEEP_BACKUPS=5
241
+ ```
242
+
243
+ 同一版本重复部署时,备份目录会追加 `_<时间戳>` 后缀(如 `v1.2.2_2026-11-18_093000`);
244
+ `--rollback=1.2.2` 会选用该版本最近一次备份。中断/没有元数据的会话不占用保留名额,
245
+ 最多保留 5 个且 24 小时后自动清理。
246
+
247
+ 备份目录若位于 Backend 根内,脚本会提示风险,并写入 `.htaccess`(Apache `Require all denied`)与 `index.html`;nginx 需自行在配置中禁止访问该路径。生产环境建议直接用 `PATCH_BACKUP_DIR` 指向站点根外。
248
+
249
+ 回滚(恢复旧文件及权限,并删除本次新增且未被修改过的文件):
250
+
251
+ ```bash
252
+ php apply-update.php --list-backups /path/to/production-api
253
+ php apply-update.php --rollback /path/to/production-api
254
+ php apply-update.php --rollback=1.2.2 /path/to/production-api
114
255
  ```
115
256
 
257
+ 子集包(`partial=1`)部署会记录在备份元数据中,回滚时会提示“仅恢复其中的文件”。
258
+
116
259
  ## CLI 参数
117
260
 
261
+ 参数统一使用 `--name=value` 形式;未知参数会直接报错退出(避免拼写错误被静默忽略)。
262
+
118
263
  | 参数 | 说明 |
119
264
  | ------ | ------ |
120
265
  | `--backend=php` | 后端类型(默认 php) |
@@ -126,24 +271,42 @@ php apply-update.php /path/to/production-api
126
271
  | `--no-zip` | 只生成 patch 目录 |
127
272
  | `--mark-deployed` | 更新基准 marker |
128
273
  | `--init` | 初始化 deploy 目录 |
274
+ | `--skip-validation` | 跳过 PHP 项目结构校验 |
275
+ | `--zip-prefix=<前缀>` | zip 文件名前缀 |
129
276
  | `--version=<版本>` | 安装版本号(写入 VERSION.txt、versions.json) |
130
277
  | `--only=<文件>` | 仅打包指定文件(逗号分隔) |
131
278
  | `--file-list=<文件>` | 文件列表(每行一个相对路径) |
279
+ | `--from-worktree` | 允许用工作区内容打包(跳过与目标版本的一致性校验) |
280
+ | `--worktree-diff` | SVN:直接打包工作副本改动(对比基准 revision,含未提交文件) |
281
+ | `--apply-script=<文件>` | 自定义 `apply-update.php` 模板 |
282
+ | `--profile=<名称>` | 多环境基准(`deploy/.last-deploy-marker.<名称>`) |
283
+ | `--protect=<路径>` | 受保护文件(逗号分隔,可重复;线上已存在则跳过覆盖) |
284
+ | `--protect-file=<文件>` | 受保护文件列表 |
285
+ | `--no-archive` | 跳过本地版本归档 |
286
+ | `--keep-versions=<N>` | 本地 archive 保留版本数(默认 10,完整包/子集包分别计算) |
287
+ | `--prune-out` | 构建后清理 `deploy/out` 旧产物 |
288
+ | `--keep-out=<N>` | `deploy/out` 保留数量(默认同 `--keep-versions`) |
289
+ | `--link-archive` | 归档优先使用硬链接(同一磁盘节省空间) |
132
290
 
133
291
  ### patch-extract
134
292
 
135
293
  | 参数 | 说明 |
136
294
  | ------ | ------ |
137
295
  | `--version=<版本>` | 从已注册版本提取 |
138
- | `--from-patch=<目录>` | 直接指定源 patch 目录 |
296
+ | `--from-patch=<目录>` | 直接指定源 patch 目录(未传 `--version` 时沿用源包 VERSION) |
139
297
  | `--only=<文件>` | 要提取的文件 |
140
298
  | `--file-list=<文件>` | 文件列表 |
299
+ | `--apply-script=<文件>` | 自定义 apply 模板 |
300
+ | `--protect=<路径>` | 追加受保护文件(与源包 PROTECT.txt、deploy/protect.txt 合并) |
301
+ | `--protect-file=<文件>` | 追加受保护文件列表 |
141
302
  | `--list-versions` | 列出 deploy/versions.json 中的版本 |
142
303
  | `--register` | 将子集包注册到 versions.json |
143
304
 
305
+ 提取时 `MANIFEST-deleted.txt` 会按本次提取范围过滤,子集包不会提示删除无关文件。
306
+
144
307
  ## 不会打进包的内容
145
308
 
146
- `.env`、`vendor/`、`runtime/`、`public/uploads/`、`deploy/out/` 等(见 `lib/backends/php.js`)。
309
+ `.env`、`vendor/`、`runtime/`、`public/uploads/`、`deploy/out/`、`deploy/versions.json`、`deploy/archive/`、`deploy/protect.txt` 等(见 `lib/backends/php.js`)。
147
310
 
148
311
  若变更含 `composer.json` / `composer.lock`,上线后需在服务器执行 `composer install --no-dev`。
149
312
 
@@ -152,8 +315,10 @@ php apply-update.php /path/to/production-api
152
315
  | 文件 | 格式 |
153
316
  | ------ | ------ |
154
317
  | `deploy/.last-deploy-marker` | `svn:467` 或 `git:fullsha` |
155
- | `deploy/.last-deploy-rev` | 兼容旧版 SVN 工具(仅数字) |
318
+ | `deploy/.last-deploy-marker.<profile>` | 多环境基准(如 `deploy/.last-deploy-marker.php85`) |
319
+ | `deploy/.last-deploy-rev` | 兼容旧版 SVN 工具(仅数字,默认 profile) |
156
320
  | `deploy/versions.json` | 版本号与 patch 目录映射 |
321
+ | `deploy/protect.txt` | 受保护文件清单(线上已存在则跳过覆盖) |
157
322
 
158
323
  **上线成功后再更新基准**,否则下次增量会漏文件。
159
324
 
@@ -185,6 +350,14 @@ export PATCH_VCS=svn
185
350
  patch-build
186
351
  ```
187
352
 
353
+ ## 开发与测试
354
+
355
+ ```bash
356
+ npm run check # node --check 语法门禁(bin/lib/test/scripts)
357
+ npm test # 单元测试 + CLI 帮助输出(自动先执行 check)
358
+ npm run test:php # 需要本机 php:apply-update.php 冒烟测试
359
+ ```
360
+
188
361
  ## License
189
362
 
190
363
  MIT