@wjwjq/release-helper 0.2.97 → 0.2.99

package/REFACTOR_PLAN.md

@@ -0,0 +1,861 @@
+# Release-Helper 重构方案
+
+## Context
+
+当前 release-helper 是一个前端部署打包工具，核心流程：`init` → `pack` → `release`（GitLab发布）→ 服务端 `install.sh` 安装。
+
+**主要问题**：
+1. **二进制膨胀**：Nginx 二进制直接提交到 Git 仓库（`src/deploy/pkg/nginx_binary/binary/`），仓库体积大，管理混乱
+2. **硬编码依赖**：`publish.ts` 硬编码 GitLab，无法支持其他平台
+3. **占位符替换脆弱**：`String.replace()` 简单替换，命名不统一（`__user__` vs `_user_` vs `__APP_NAME__`）
+4. **无自动化测试**
+5. **配置校验手写**：易遗漏字段
+6. **Changelog 解析简陋**：仅支持 `feat:/fix:`
+7. **Bash 脚本问题**：install.sh = upgrade.sh（`callBy` 参数未使用）、`log_warn()` 拼写 bug、`__root__` 占位符未实际替换、大量硬编码路径
+8. **安全合规**：在严格安全环境下，部署包需要能被审计（deps.txt 依赖声明）
+
+**重构目标**：保持核心能力不变的前提下，解耦架构、规范化流程、增强可维护性和安全合规性。
+
+---
+
+## 第一阶段：架构解耦（Plugin 化）
+
+### 1.1 定义平台抽象层
+
+新建 `src/platform/types.ts`：
+
+```typescript
+interface Platform {
+  name: string;
+  createTag(version: string, branch: string): Promise<void>;
+  createRelease(version: string, description: string): Promise<Release>;
+  uploadAsset(releaseId: string, file: Buffer, filename: string): Promise<AssetRef>;
+  getTags(): Promise<string[]>;
+  getChangelog(range: string): Promise<string>;
+}
+```
+
+### 1.2 GitLab 实现
+
+将 `src/publish.ts` → `src/platforms/gitlab.ts`：
+- 现有 `@gitbeaker/rest` 调用封装为 `GitlabPlatform implements Platform`
+- 接口不变，只是从自由函数改为类方法
+
+### 1.3 平台选择
+
+`release.conf.yaml` 新增字段：
+```yaml
+platform: gitlab  # 可选: gitlab | github | gitee
+```
+
+CLI 根据 `platform` 字段动态加载对应实现。
+
+---
+
+## 第二阶段：配置系统升级
+
+### 2.1 Zod Schema 校验
+
+依赖新增：`zod`
+
+`src/config/schema.ts`：
+```typescript
+const ReleaseConfSchema = z.object({
+  platform: z.enum(['gitlab', 'github', 'gitee']).default('gitlab'),
+  host: z.string().url(),
+  token: z.string().optional(),  // 可从环境变量读取
+  buildCmd: z.string().default('npm run build'),
+  assetsDir: z.string().default('dist'),
+  user: z.string().default('root'),
+  userGroup: z.string().default('root'),
+  installMode: z.enum(['standalone', 'cluster', 'static', 'all', 'selectable']).default('all'),
+  installDir: z.string().default('/opt').refine(isValidLinuxPath),
+  nginxInstallMode: z.enum(['source', 'binary']).default('binary'),
+  dockerInstallDir: z.string().optional(),
+  dockerBackupDir: z.string().optional(),
+  binaryRegistry: z.object({
+    // 新字段：二进制制品库地址
+    url: z.string().url().optional(),
+    type: z.enum(['http', 'nexus', 'minio']).default('http'),
+  }).optional(),
+});
+```
+
+### 2.2 敏感信息环境变量支持
+
+`release.conf.yaml` 支持 `${ENV_VAR}` 语法：
+```yaml
+host: https://gitlab.example.com
+token: ${GITLAB_TOKEN}   # 从环境变量读取，不写死在文件里
+```
+
+解析时替换：`parseConf()` 增加 `resolveEnvVars()` 步骤。
+
+---
+
+## 第三阶段：打包逻辑重构
+
+### 3.1 模板引擎替换 String.replace
+
+依赖新增：`handlebars`
+
+统一占位符语法：`{{APP_NAME}}`、`{{INSTALL_PATH}}`、`{{USER}}` 等。
+
+| 旧语法 | 新语法 |
+|--------|--------|
+| `__APP_NAME__` | `{{APP_NAME}}` |
+| `_user_` | `{{USER}}` |
+| `__user__` | `{{USER}}` |
+| `__usergroup__` | `{{USER_GROUP}}` |
+| `__root__` | `{{ASSETS_ROOT}}` |
+| `#ERROR_LOG_PLACEHOLDER` | `{{ERROR_LOG_PATH}}` |
+
+改造 `src/pack.ts`：
+```typescript
+function renderTemplate(template: string, data: TemplateData): string {
+  return Handlebars.compile(template, { noEscape: true })(data);
+}
+```
+
+### 3.2 二进制从制品库下载
+
+`src/pack.ts` 修改 pack 流程：
+
+```
+旧流程：
+  fs.cpSync(src/deploy, projectDir)  ← 直接复制 Git 仓库中的二进制
+
+新流程：
+  1. 读取 binaryRegistry.url
+  2. 下载 manifest.json 获取当前版本的所有平台二进制列表
+  3. 并发下载所有平台二进制到临时目录
+  4. 复制到 projectDir/pkg/nginx_binary/
+  5. 写入 deps.txt（每个二进制的 ldd 输出）供审计
+```
+
+制品库 manifest.json 格式：
+```json
+{
+  "version": "1.31.0",
+  "binaries": [
+    {
+      "id": "x86_64-el7",
+      "arch": "x86_64",
+      "os": "centos7",
+      "openssl": "1.0.2k",
+      "url": "https://registry.internal/nginx/1.31.0/x86_64-el7/nginx.tar.gz",
+      "sha256": "abc123...",
+      "deps": "libssl.so.10 => /lib64/libssl.so.10\n..."
+    },
+    { "id": "x86_64-el9", "arch": "x86_64", "os": "centos9", "openssl": "3.0.7", ... },
+    { "id": "aarch64-el8", "arch": "aarch64", "os": "centos8", "openssl": "1.1.1k", ... }
+  ]
+}
+```
+
+### 3.3 打包产物结构
+
+```
+.release/{projectName}/
+├── pkg/
+│   ├── nginx_binary/
+│   │   ├── x86_64-el7/
+│   │   │   ├── nginx.tar.gz
+│   │   │   └── deps.txt        ← 安全审计用
+│   │   ├── x86_64-el9/
+│   │   └── aarch64-el8/
+│   ├── nginx/
+│   │   ├── nginx.service.tpl   ← 统一占位符为 {{...}}
+│   │   └── nginx.logrotate.tpl
+│   └── assets/                 ← 前端构建产物
+├── script/
+│   ├── install.sh
+│   ├── upgrade.sh
+│   ├── common.sh
+│   ├── nginx.sh
+│   ├── prompt.sh
+│   └── after.sh                ← 用户自定义（可选）
+└── version
+```
+
+---
+
+## 第四阶段：Bash 部署脚本修复
+
+### 4.1 Bug 修复
+
+| 文件 | 问题 | 修复 |
+|------|------|------|
+| `common.sh:33` | `log_warn()` 输出 `[success]` | 改为 `[warn]` |
+| `common.sh:164` | `start()` 不区分 install/upgrade | 增加差异化逻辑（upgrade 时跳过用户创建等） |
+| `nginx.sh:70-73` | `__root__` 占位符替换代码被注释 | 启用并正确使用 Handlebars 风格的 `{{ASSETS_ROOT}}` |
+
+### 4.2 二进制选择逻辑重构
+
+`nginx.sh` 中的二进制选择改为基于 manifest：
+
+```bash
+# 旧：按文件名模式匹配
+tar_file="nginx-${arch}-ssl${version}.tar.gz"
+
+# 新：读取 deps.txt 和 manifest
+select_binary() {
+    local os_id=$(. /etc/os-release && echo "${ID}-${VERSION_ID%%.*}")
+    local arch=$(uname -m)
+
+    local match_dir="${PROJECT_PATH}/pkg/nginx_binary/${arch}-${os_id}"
+    if [ -d "$match_dir" ] && [ -f "$match_dir/deps.txt" ]; then
+        echo "$match_dir/nginx.tar.gz"
+        return 0
+    fi
+
+    # 回退：尝试模糊匹配
+    # ...
+}
+```
+
+### 4.3 install.sh 与 upgrade.sh 差异化
+
+```bash
+# install.sh 新增行为：
+# - 创建系统用户
+# - 首次安装 nginx
+# - 注册 systemd 服务
+
+# upgrade.sh 新增行为：
+# - 跳过用户创建
+# - 备份旧版本
+# - 平滑重启（nginx -s reload 而非 systemctl restart）
+# - 保留原有 nginx.conf 中的自定义配置（diff 合并）
+```
+
+### 4.4 统一占位符
+
+所有模板文件统一使用 `{{VAR}}` 语法：
+- `nginx.service.tpl`：`{{USER}}`、`{{USER_GROUP}}`、`{{EXEC_CMD}}`、`{{LOG_PATH}}`、`{{PID_FILE}}`、`{{APP_NAME}}`
+- `nginx.logrotate.tpl`：`{{APP_NAME}}`、`{{USER}}`、`{{USER_GROUP}}`、`{{PID_FILE}}`
+- 安装脚本中在解压后用 `sed` 或内嵌的 shell 函数做替换（避免在部署端引入 handlebars 依赖）
+
+### 4.5 移除硬编码路径
+
+```bash
+# 旧
+NGINX_BINARY_INSTALL_PATH="/etc/nginx/"
+NGINX_CONF_INSTALL_PATH="$prefix/opt/${APP_NAME}/nginx/"
+
+# 新 — 在 release.conf.yaml 中可配置，打包时替换
+NGINX_BINARY_INSTALL_PATH="{{NGINX_BINARY_DIR}}"
+NGINX_CONF_INSTALL_PATH="{{NGINX_CONF_DIR}}"
+```
+
+---
+
+## 第五阶段：Changelog 与发布
+
+### 5.1 Conventional Commits 支持
+
+`src/platforms/gitlab.ts` 中的 `getChangeLog()` 改为标准 Conventional Commits 解析：
+
+```
+支持的 type:
+  feat      → Features
+  fix       → Bug Fixes
+  perf      → Performance Improvements
+  refactor  → Code Refactoring (折叠显示)
+  docs      → Documentation (折叠显示)
+  chore/ci  → 不显示
+  BREAKING CHANGE → 置顶高亮显示
+
+scope 支持: feat(auth): xxx → * **auth**: xxx
+```
+
+使用正则 `^(feat|fix|perf|refactor|docs|chore|ci)(\(.+\))?: (.+)$` 解析。
+
+### 5.2 dry-run 模式
+
+CLI 新增 `--dry-run` 标志：
+```bash
+release-helper release --dry-run
+# 输出：将要执行的操作列表，不实际执行
+# - 将切换到 master 分支
+# - 将创建 tag v1.2.3
+# - 将打包: posidon-frontend_v1.2.3.tar.gz
+# - 将发布到 GitLab: ...
+```
+
+---
+
+## 制品库设计与实现方案
+
+> 制品库解决的核心问题：Nginx 二进制不在 Git 仓库中，但 pack 时必须能获取到所有平台的二进制。
+
+### 一、存储方案选择
+
+提供 3 种后端，按复杂度递增：
+
+| 方案 | 适用场景 | 复杂度 | 依赖 |
+|------|---------|--------|------|
+| **A. 静态文件 + HTTP** | 小型团队，无额外基础设施 | 最低 | nginx/caddy/httpd |
+| **B. MinIO (S3 兼容)** | 已有或愿意部署对象存储 | 中 | docker run minio |
+| **C. Nexus Repository** | 企业已有 Nexus 统一管控 | 中 | docker run nexus |
+
+推荐 **方案 A** 起步，后续无缝切换到 B 或 C（通过 `binaryRegistry.type` 配置切换）。
+
+---
+
+### 二、制品库目录结构
+
+```
+/storage/nginx-binaries/           # 存储根目录
+├── manifest.json                  # 全局入口，描述所有可用版本
+├── versions.json                  # 版本列表（用于版本查询/回滚）
+├── 1.31.0/                        # 按 nginx 版本分组
+│   ├── manifest.json              # 该版本的所有平台二进制描述
+│   ├── x86_64-el7/
+│   │   ├── nginx.tar.gz
+│   │   ├── nginx.tar.gz.sha256    # 校验文件
+│   │   └── deps.txt               # ldd 输出（安全审计用）
+│   ├── x86_64-el9/
+│   │   ├── nginx.tar.gz
+│   │   ├── nginx.tar.gz.sha256
+│   │   └── deps.txt
+│   ├── aarch64-el8/
+│   │   ├── nginx.tar.gz
+│   │   ├── nginx.tar.gz.sha256
+│   │   └── deps.txt
+│   └── aarch64-el9/
+│       └── ...
+├── 1.22.1/                        # 历史版本保留
+│   └── ...
+└── source/
+    └── nginx-1.31.0.tar.gz        # 源码归档（可选，用于 source 模式安装）
+```
+
+### 三、manifest.json 完整格式
+
+**全局 manifest.json** (`/storage/nginx-binaries/manifest.json`)：
+```json
+{
+  "latest": "1.31.0",
+  "versions": ["1.31.0", "1.22.1"],
+  "updated_at": "2025-01-15T10:30:00Z"
+}
+```
+
+**版本级 manifest.json** (`/storage/nginx-binaries/1.31.0/manifest.json`)：
+```json
+{
+  "nginx_version": "1.31.0",
+  "built_at": "2025-01-15T10:30:00Z",
+  "binaries": [
+    {
+      "id": "x86_64-el7",
+      "arch": "x86_64",
+      "os": "centos",
+      "os_version": "7",
+      "openssl": "1.0.2k",
+      "glibc": "2.17",
+      "file_url": "1.31.0/x86_64-el7/nginx.tar.gz",
+      "sha256": "a1b2c3d4e5f6...",
+      "file_size": 5242880,
+      "deps": "libssl.so.10 => /lib64/libssl.so.10\nlibcrypto.so.10 => /lib64/libcrypto.so.10\nlibpcre.so.1 => /lib64/libpcre.so.1\nlibz.so.1 => /lib64/libz.so.1\nlibc.so.6 => /lib64/libc.so.6\n/lib64/ld-linux-x86-64.so.2",
+      "compile_info": {
+        "docker_image": "centos:7",
+        "configure_args": "--prefix=/etc/nginx --with-http_ssl_module --with-http_v2_module --with-http_gzip_static_module --with-http_stub_status_module --with-stream",
+        "compiler": "gcc 4.8.5"
+      }
+    },
+    {
+      "id": "x86_64-el9",
+      "arch": "x86_64",
+      "os": "rocky",
+      "os_version": "9",
+      "openssl": "3.0.7",
+      "glibc": "2.34",
+      "file_url": "1.31.0/x86_64-el9/nginx.tar.gz",
+      "sha256": "...",
+      "deps": "libssl.so.3 => /lib64/libssl.so.3\nlibcrypto.so.3 => /lib64/libcrypto.so.3\n...",
+      "compile_info": { "docker_image": "rockylinux:9", "compiler": "gcc 11.4.1" }
+    },
+    {
+      "id": "aarch64-el8",
+      "arch": "aarch64",
+      "os": "rocky",
+      "os_version": "8",
+      "openssl": "1.1.1k",
+      "glibc": "2.28",
+      "file_url": "1.31.0/aarch64-el8/nginx.tar.gz",
+      "sha256": "...",
+      "deps": "...",
+      "compile_info": { "docker_image": "rockylinux:8", "qemu": true, "compiler": "gcc 8.5.0" }
+    }
+  ]
+}
+```
+
+### 四、HTTP API 设计
+
+方案 A（静态文件）直接通过 URL 访问，无额外 API：
+
+```
+GET /nginx-binaries/manifest.json          → 全局版本列表
+GET /nginx-binaries/1.31.0/manifest.json   → 某版本的所有平台二进制
+GET /nginx-binaries/1.31.0/x86_64-el7/nginx.tar.gz    → 下载
+GET /nginx-binaries/1.31.0/x86_64-el7/nginx.tar.gz.sha256 → 校验
+GET /nginx-binaries/1.31.0/x86_64-el7/deps.txt         → 审计信息
+```
+
+方案 B (MinIO) / C (Nexus) 通过 S3 API / Nexus API 访问，`binary-registry.ts` 封装差异。
+
+---
+
+### 五、Nginx 服务端实现（方案 A 示例）
+
+```nginx
+# 在内部服务器上提供制品库 HTTP 访问
+server {
+    listen 8080;
+    server_name registry.internal;
+
+    root /storage/nginx-binaries;
+
+    # 禁止目录浏览
+    autoindex off;
+
+    # 允许访问的文件类型
+    location ~ \.(json|gz|sha256|txt)$ {
+        autoindex on;              # manifest.json 需要目录索引（或显式列出文件）
+        add_header Cache-Control "public, max-age=3600";
+    }
+
+    # 认证（可选，内网可关闭）
+    # auth_basic "Binary Registry";
+    # auth_basic_user_file /etc/nginx/.htpasswd;
+}
+```
+
+### 六、二进制构建与上传流程（CI 侧）
+
+这部分**不在 release-helper 项目中**，而是单独的 CI 仓库或 GitLab CI 配置。
+
+#### 6.1 编译矩阵配置
+
+```yaml
+# nginx-binary-ci/build-config.yml
+nginx_version: "1.31.0"
+targets:
+  - id: x86_64-el7
+    arch: x86_64
+    os: centos
+    os_version: "7"
+    docker_image: centos:7
+    openssl_version: "1.0.2k"
+  - id: x86_64-el8
+    arch: x86_64
+    os: rocky
+    os_version: "8"
+    docker_image: rockylinux:8
+    openssl_version: "1.1.1k"
+  - id: x86_64-el9
+    arch: x86_64
+    os: rocky
+    os_version: "9"
+    docker_image: rockylinux:9
+    openssl_version: "3.0.7"
+  - id: aarch64-el8
+    arch: aarch64
+    os: rocky
+    os_version: "8"
+    docker_image: rockylinux:8
+    openssl_version: "1.1.1k"
+    qemu: true
+  - id: aarch64-el9
+    arch: aarch64
+    os: rocky
+    os_version: "9"
+    docker_image: rockylinux:9
+    openssl_version: "3.0.7"
+    qemu: true
+```
+
+#### 6.2 构建脚本（每个目标执行一次）
+
+```bash
+#!/bin/bash
+# nginx-binary-ci/build.sh
+set -euo pipefail
+
+NGINX_VER="$1"    # 1.31.0
+TARGET_ID="$2"    # x86_64-el7
+DOCKER_IMG="$3"   # centos:7
+ARCH="$4"         # x86_64
+
+OUTPUT_DIR="output/${NGINX_VER}/${TARGET_ID}"
+mkdir -p "$OUTPUT_DIR"
+
+# 下载 nginx 源码（若未缓存）
+[ -f "cache/nginx-${NGINX_VER}.tar.gz" ] || \
+  curl -fSL "https://nginx.org/download/nginx-${NGINX_VER}.tar.gz" -o "cache/nginx-${NGINX_VER}.tar.gz"
+
+# 在 Docker 中编译
+docker run --rm \
+  ${ARCH:+--platform "linux/${ARCH}"} \
+  -v "$(pwd)/cache:/src:ro" \
+  -v "$(pwd)/${OUTPUT_DIR}:/output" \
+  "$DOCKER_IMG" \
+  bash -c '
+    set -euo pipefail
+    yum install -y gcc gcc-c++ make pcre-devel zlib-devel openssl-devel
+    cd /tmp
+    tar xzf /src/nginx-'"${NGINX_VER}"'.tar.gz
+    cd nginx-'"${NGINX_VER}"'
+    ./configure \
+      --prefix=/etc/nginx \
+      --with-http_ssl_module \
+      --with-http_v2_module \
+      --with-http_gzip_static_module \
+      --with-http_stub_status_module \
+      --with-stream
+    make -j$(nproc)
+    make install
+
+    # 打包
+    cd /etc/nginx
+    tar czf /output/nginx.tar.gz .
+
+    # 生成依赖声明
+    ldd sbin/nginx > /output/deps.txt 2>&1 || true
+
+    # 生成 sha256
+    sha256sum /output/nginx.tar.gz | awk "{print \$1}" > /output/nginx.tar.gz.sha256
+  '
+
+echo "Build complete: ${OUTPUT_DIR}/"
+```
+
+#### 6.3 上传脚本
+
+```bash
+#!/bin/bash
+# nginx-binary-ci/upload.sh
+# 上传到制品库（方案 A：scp/rsync 到内部服务器）
+
+REGISTRY_HOST="registry.internal"
+REGISTRY_PATH="/storage/nginx-binaries"
+
+NGINX_VER="$1"
+
+# 上传所有文件
+rsync -avz "output/${NGINX_VER}/" \
+  "${REGISTRY_HOST}:${REGISTRY_PATH}/${NGINX_VER}/"
+
+# 重新生成版本级 manifest.json
+node scripts/generate-manifest.js "$NGINX_VER"
+
+# 上传 manifest
+scp "output/${NGINX_VER}/manifest.json" \
+  "${REGISTRY_HOST}:${REGISTRY_PATH}/${NGINX_VER}/manifest.json"
+
+# 更新全局 manifest
+scp "output/manifest.json" \
+  "${REGISTRY_HOST}:${REGISTRY_PATH}/manifest.json"
+```
+
+#### 6.4 manifest 自动生成
+
+```javascript
+// nginx-binary-ci/scripts/generate-manifest.js
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+
+const nginxBinaryVersion = process.argv[2]; // "1.31.0"
+const outputDir = `output/${nginxBinaryVersion}`;
+
+const targets = readdirSync(outputDir).filter(d =>
+  statSync(`${outputDir}/${d}`).isDirectory()
+);
+
+const binaries = targets.map(dir => {
+  const deps = readFileSync(`${outputDir}/${dir}/deps.txt`, 'utf-8');
+  const sha256 = readFileSync(`${outputDir}/${dir}/nginx.tar.gz.sha256`, 'utf-8').trim();
+  const size = statSync(`${outputDir}/${dir}/nginx.tar.gz`).size;
+
+  return {
+    id: dir,
+    arch: dir.split('-')[0],
+    os: extractOS(dir),
+    file_url: `${nginxBinaryVersion}/${dir}/nginx.tar.gz`,
+    sha256,
+    file_size: size,
+    deps
+  };
+});
+
+writeFileSync(`${outputDir}/manifest.json`, JSON.stringify({
+  nginx_version: nginxBinaryVersion,
+  built_at: new Date().toISOString(),
+  binaries
+}, null, 2));
+```
+
+---
+
+### 七、release-helper 侧：下载与集成
+
+#### 7.1 `src/binary-registry.ts` 实现
+
+```typescript
+interface BinaryRegistryConfig {
+  url: string;              // e.g. "http://registry.internal:8080"
+  type: 'http' | 'minio' | 'nexus';
+  auth?: { username: string; password: string };
+}
+
+interface BinaryInfo {
+  id: string;
+  arch: string;
+  os: string;
+  osVersion: string;
+  openssl: string;
+  fileUrl: string;
+  sha256: string;
+  deps: string;
+}
+
+class BinaryRegistry {
+  constructor(private config: BinaryRegistryConfig) {}
+
+  // 获取指定 nginx 版本的所有平台二进制信息
+  async listBinaries(nginxVersion: string): Promise<BinaryInfo[]> {
+    const manifestUrl = `${this.config.url}/${nginxVersion}/manifest.json`;
+    const resp = await fetch(manifestUrl);
+    const manifest = await resp.json();
+    return manifest.binaries;
+  }
+
+  // 下载单个二进制并校验
+  async downloadBinary(info: BinaryInfo, destDir: string): Promise<string> {
+    const url = `${this.config.url}/${info.fileUrl}`;
+    const destPath = `${destDir}/${info.id}/nginx.tar.gz`;
+
+    // 下载
+    await downloadFile(url, destPath);
+
+    // 校验 sha256
+    const actualSha256 = await sha256File(destPath);
+    if (actualSha256 !== info.sha256) {
+      throw new Error(`SHA256 mismatch for ${info.id}: expected ${info.sha256}, got ${actualSha256}`);
+    }
+
+    // 写入 deps.txt 供审计
+    await writeFile(`${destDir}/${info.id}/deps.txt`, info.deps);
+
+    return destPath;
+  }
+
+  // pack 流程调用：下载所有平台二进制
+  async downloadAll(nginxVersion: string, destDir: string): Promise<void> {
+    const binaries = await this.listBinaries(nginxVersion);
+    logger.info(`Found ${binaries.length} platform binaries for nginx ${nginxVersion}`);
+
+    // 并发下载
+    await Promise.all(
+      binaries.map(b => this.downloadBinary(b, destDir))
+    );
+  }
+}
+```
+
+#### 7.2 pack 流程改造
+
+```typescript
+// src/pack.ts 核心逻辑
+export async function pack(version?: string) {
+  // ... 前面的逻辑（版本输入、校验配置等）不变 ...
+
+  // 复制安装脚本和 nginx 模板（不再复制二进制）
+  fs.cpSync(resolve(__dirname, 'deploy/script'), resolve(projectDir, 'script'), { recursive: true });
+  fs.cpSync(resolve(__dirname, 'deploy/pkg/nginx'), resolve(projectDir, 'pkg/nginx'), { recursive: true });
+
+  // 从制品库下载所有平台 nginx 二进制
+  if (releaseConf.binaryRegistry?.url) {
+    const registry = new BinaryRegistry(releaseConf.binaryRegistry);
+    const nginxVersion = '1.31.0'; // 可从配置指定
+    await registry.downloadAll(nginxVersion, resolve(projectDir, 'pkg/nginx_binary'));
+  } else {
+    // 回退：如果没有配置制品库，从本地 src/deploy/pkg/nginx_binary 复制
+    // （兼容开发环境或离线场景）
+    fs.cpSync(resolve(__dirname, 'deploy/pkg/nginx_binary'), resolve(projectDir, 'pkg/nginx_binary'), { recursive: true });
+  }
+
+  // ... 后续打包逻辑不变 ...
+}
+```
+
+#### 7.3 离线场景支持
+
+```yaml
+# release.conf.yaml
+binaryRegistry:
+  url: ""                    # 为空时使用本地二进制回退
+  type: "http"
+
+# 离线场景：制品库不可达时使用本地备份
+# 本地备份放在 src/deploy/pkg/nginx_binary/（不提交到 git，但可手动放置）
+```
+
+### 八、版本管理策略
+
+```
+1. 每次编译新的 nginx 二进制时，创建新的版本目录（如 1.31.0/）
+2. 旧版本目录保留不删除（支持回滚）
+3. manifest.json 中的 versions 数组维护可用版本列表
+4. release.conf.yaml 中可指定使用哪个 nginx 版本：
+
+   nginxBinaryVersion: "1.31.0"  # 默认使用 latest
+```
+
+### 九、安全与权限
+
+| 层面 | 措施 |
+|------|------|
+| 传输 | HTTPS（内网可用自签名证书，`rejectUnauthorized: false`） |
+| 完整性 | SHA256 校验，下载后验证 |
+| 访问控制 | 方案 A：nginx basic auth 或 IP 白名单；方案 B/C：各自认证机制 |
+| 审计 | 每个二进制附带 deps.txt，记录完整动态链接依赖 |
+| 上传 | CI 专用 token/SSH key，非人工上传 |
+
+---
+
+## 第六阶段：构建与测试
+
+### 6.1 二进制矩阵构建（CI 侧，非项目代码）
+
+在制品库/CI 中维护编译矩阵：
+
+```yaml
+# nginx-binary-build.yml (放在单独的 CI 仓库)
+targets:
+  - id: x86_64-el7
+    docker_image: centos:7
+    arch: x86_64
+  - id: x86_64-el8
+    docker_image: rockylinux:8
+    arch: x86_64
+  - id: x86_64-el9
+    docker_image: rockylinux:9
+    arch: x86_64
+  - id: aarch64-el8
+    docker_image: rockylinux:8
+    arch: aarch64
+    qemu: true
+  - id: aarch64-el9
+    docker_image: rockylinux:9
+    arch: aarch64
+    qemu: true
+```
+
+每个 Docker 容器中：动态链接编译 nginx，输出 `nginx.tar.gz` + `deps.txt`。
+
+### 6.2 测试（本项目新增）
+
+依赖新增：`vitest`、`memfs`
+
+```
+src/
+├── pack.test.ts        # 测试 pack 流程（memfs mock 文件系统）
+├── config/schema.test.ts  # 测试 Zod schema 校验
+├── platforms/gitlab.test.ts  # 测试 GitLab API 调用（nock mock）
+└── templates.test.ts   # 测试 Handlebars 模板渲染
+```
+
+---
+
+## 文件变更清单
+
+### 新建文件
+```
+# 核心功能
+src/config/schema.ts              # Zod 配置 schema
+src/config/env.ts                 # 环境变量解析
+src/platform/types.ts             # Platform 接口定义
+src/platforms/gitlab.ts           # GitLab 实现（从 publish.ts 迁移）
+src/templates.ts                  # Handlebars 模板渲染
+src/binary-registry.ts            # 制品库下载逻辑
+
+# 制品库 CI 侧（单独仓库）
+nginx-binary-ci/build-config.yml  # 编译矩阵配置
+nginx-binary-ci/build.sh          # Docker 中编译 nginx
+nginx-binary-ci/upload.sh         # 上传到制品库
+nginx-binary-ci/scripts/generate-manifest.js  # manifest 自动生成
+
+# 制品库服务端（方案 A）
+nginx-binary-registry/nginx.conf  # nginx 配置，提供 HTTP 访问
+
+# 测试
+src/pack.test.ts
+src/config/schema.test.ts
+src/templates.test.ts
+src/binary-registry.test.ts
+```
+
+### 修改文件
+```
+src/cli.ts                        # 新增 --dry-run, --platform 选项
+src/prepare.ts                    # 改用 Zod 校验, 支持 ${ENV} 语法
+src/pack.ts                       # 重构：模板引擎 + 制品库下载
+src/publish.ts                    # 简化，委托给 Platform 实现
+src/release.ts                    # 适配新接口
+src/deploy/script/common.sh       # 修复 bug, install/upgrade 差异化
+src/deploy/script/nginx.sh        # 重构二进制选择, 启用 __root__ 替换
+src/deploy/script/install.sh      # 差异化逻辑
+src/deploy/script/upgrade.sh      # 差异化逻辑
+src/deploy/script/prompt.sh       # 统一占位符
+src/deploy/pkg/nginx/*.tpl        # 统一 {{VAR}} 占位符
+src/.release/release.conf.yaml    # 新增 platform, binaryRegistry 字段
+src/.release/nginx/nginx.conf     # 统一 {{VAR}} 占位符
+package.json                      # 新增 zod, handlebars, vitest 依赖
+rollup.config.js                  # 可能需要调整 handlebars 打包
+```
+
+### 删除/清理
+```
+src/deploy/pkg/nginx_binary/      # 从 Git 仓库移除（移到制品库）
+src/deploy/pkg/nginx_binary/binary/bak_1.22.1/  # 清理旧版本
+```
+
+---
+
+## 实施顺序与阶段
+
+| 阶段 | 内容 | 风险 | 可回滚 |
+|------|------|------|--------|
+| 0. 制品库搭建 | 存储部署 + CI 构建流水线 + manifest | 中 | 是（保留旧二进制在 Git 中） |
+| 1. Plugin 化 | Platform 接口 + GitLab 迁移 | 低 | 是 |
+| 2. 配置系统 | Zod + 环境变量 | 低 | 是 |
+| 3. Bash 脚本修复 | Bug fix + 差异化 | 中 | 是（需测试） |
+| 4. 模板统一 | Handlebars + 占位符统一 | 中 | 是（兼容旧语法过渡） |
+| 5. 制品库集成 | binary-registry.ts + pack 改造 | 高 | 是（无制品库配置时回退本地） |
+| 6. Changelog + dry-run | Conventional Commits | 低 | 是 |
+| 7. 测试 | vitest + memfs | 低 | 是 |
+
+**阶段 0（制品库）必须先于阶段 5 完成**，否则 pack 无法获取二进制。过渡期保留 `src/deploy/pkg/nginx_binary/` 作为本地回退。
+
+---
+
+## 验证方案
+
+### 制品库侧（阶段 0）
+1. **构建验证**：CI 流水线跑完，每个目标目录包含 `nginx.tar.gz` + `nginx.tar.gz.sha256` + `deps.txt`
+2. **HTTP 验证**：`curl http://registry.internal:8080/1.31.0/manifest.json` 返回正确 JSON
+3. **下载校验**：手动下载 `nginx.tar.gz`，比对 sha256 与 `.sha256` 文件一致
+4. **部署验证**：下载的 nginx 二进制在对应 Docker 容器中 `ldd` 检查依赖匹配 `deps.txt`
+
+### release-helper 侧
+5. **本地测试**：在示例项目中执行 `release-helper init → pack`，验证 tar.gz 结构正确
+6. **脚本测试**：在 CentOS 7/8/9 Docker 容器中运行 `install.sh`，验证 nginx 安装和功能正常
+7. **模板测试**：运行 `vitest src/templates.test.ts`，验证所有占位符正确替换
+8. **配置测试**：运行 `vitest src/config/schema.test.ts`，验证必填字段和类型校验
+9. **制品库下载测试**：运行 `vitest src/binary-registry.test.ts`，mock HTTP 下载并校验
+10. **dry-run 测试**：`release-helper release --dry-run` 输出操作列表但不执行
+11. **离线回退测试**：制品库不可达时，pack 自动回退到本地 `src/deploy/pkg/nginx_binary/`
+12. **平台测试**：切换 `platform: gitlab` 后，完整 release 流程正常