docs(release): 主与 release 分支合并功能清单 + 导入 release 文档目录

便于 Gitea 上 main ↔ release/20260708-axs 合并评审与冲突对照。
2026-07-09 01:14:18 +08:00
parent 5520434d53
commit 9b583ccc91
32 changed files with 9699 additions and 0 deletions
@@ -0,0 +1,81 @@
+# Nexus Python 发布辅助脚本（2026-07-08）
+
+## 目的
+
+为避免 Windows PowerShell 管道、编码和引号问题，新增 Python 发布辅助脚本：
+
+```text
+C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042\scripts\publish_release_bundle.py
+```
+
+它使用 `subprocess` 参数列表调用 `scp` / `ssh`，不依赖本地 shell 管道；默认只上传发布包并执行服务器侧 preflight，不会直接发布。
+
+## 最新发布包
+
+```text
+C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz
+```
+
+SHA256：
+
+```text
+46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b
+```
+
+## 推荐使用方式
+
+### 1. 只上传并执行 preflight（默认安全模式）
+
+```cmd
+cd /d C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042
+.venv-py312-codex\Scripts\python.exe scripts\publish_release_bundle.py ^
+  --remote nexus ^
+  --tarball C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz ^
+  --sha256 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b
+```
+
+### 2. 如果不使用 SSH config
+
+```cmd
+cd /d C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042
+.venv-py312-codex\Scripts\python.exe scripts\publish_release_bundle.py ^
+  --remote root@你的线上服务器IP ^
+  --tarball C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz ^
+  --sha256 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b ^
+  --deploy-path /opt/nexus
+```
+
+### 3. preflight 确认无误后执行 apply
+
+```cmd
+cd /d C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042
+.venv-py312-codex\Scripts\python.exe scripts\publish_release_bundle.py ^
+  --remote nexus ^
+  --tarball C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz ^
+  --sha256 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b ^
+  --apply
+```
+
+## 行为说明
+
+脚本会：
+
+1. 本地校验 tarball SHA256；
+2. 使用 `scp` 上传到 `/tmp/nexus-release-20260708.tar.gz`；
+3. 在远端从发布包解出：
+   - `deploy/preflight-release-host.sh`
+   - `deploy/apply-release-bundle.sh`
+4. 执行 preflight；
+5. 只有传入 `--apply` 时才执行正式 apply。
+
+## 已验证
+
+- `--help` 正常；
+- `--dry-run --no-upload` 正常；
+- Windows 下远端路径保持 POSIX `/tmp/...`，不会被转换成 `\tmp\...`；
+- 已纳入 `scripts/run_local_release_gate.py` 的 `py_compile`。
+
+## 本轮新增测试
+
+- `tests/test_publish_release_bundle.py`：5 个离线测试，覆盖默认 preflight、显式 apply、SHA mismatch、no-upload dry-run、远端 POSIX 路径。
+- 已纳入 `scripts/run_local_release_gate.py --with-pytest`。