运维文档

# v8patchctl 补丁工具

本文档覆盖 v8patchctl 的完整使用方式，包括前端静态资源、组件库、Nodejs 离线包、客开组件包，以及后端镜像与 Maven 依赖上传。适用于5.3.0之前版本。

# 功能流程图

1776317599027.png

# 1. 前置准备

# 1.1 安装

直接将程序上传到操作系统的bin目录即可。二进制程序直接启动

$ mv  v8patchctl-linux-xxx  /usr/local/bin/v8patchctl

查看帮助

$ v8patchctl -h

查看版本（格式：分支-commitid-日期）：

$ v8patchctl --version



 ________  _______   _______       ___    ___ ________  ________
|\   ____\|\  ___ \ |\  ___ \     |\  \  /  /|\   __  \|\   ___  \
\ \  \___|\ \   __/|\ \   __/|    \ \  \/  / | \  \|\  \ \  \\ \  \
 \ \_____  \ \  \_|/_\ \  \_|/__   \ \    / / \ \  \\\  \ \  \\ \  \
  \|____|\  \ \  \_|\ \ \  \_|\ \   \/  /  /   \ \  \\\  \ \  \\ \  \
    ____\_\  \ \_______\ \_______\__/  / /      \ \_______\ \__\\ \__\
   |\_________\|_______|\|_______|\___/ /        \|_______|\|__| \|__|
   \|_________|                  \|___|/


Patch deployment helper: pull public config from Nacos and upload patch assets to object storage

Usage:
  v8patchctl [flags]
  v8patchctl [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  nacos       Manage Nacos endpoints
  pull-public Pull Nacos config (dataId=public, group=DEFAULT_GROUP fallback seeyon) and print storage/k8s config
  upload      Unzip a patch package and handle frontend files / backend images

Flags:
      --env string          Environment key in nacos_endpoints.yaml (required)
  -h, --help                help for v8patchctl
      --nacos-file string   Path to nacos endpoints yaml (default: ~/.v8patchctl/nacos_endpoints.yaml) (default "/Users/v_zhenxiyao/.v8patchctl/nacos_endpoints.yaml")
      --version             Print version and exit

Use "v8patchctl [command] --help" for more information about a command.

# 1.2 基础依赖

  • 可访问nacos
  • 可访问容器镜像仓库
  • 可访问对象存储，支持OBS、OSS、minio
  • 可访问 Kubernetes API（补丁包含后端镜像时）

# 2. 基础配置

# 2.1 Nacos 端点（初始化）

$ v8patchctl nacos add  
==============================
新增 Nacos 环境
按回车可保留默认值
==============================
请输入 env (环境名，例: dev): poc   
请输入 server_addr (Nacos 地址，例: 10.0.0.1:8848): 10.103.3.10:8848
请输入 username (登录用户名，例: nacos): nacos
请输入 password (登录密码，例: nacos): xxxx
请输入 namespace (Nacos namespace，例: seeyon-dev): seeyon-poc
请输入 describe (备注，例: 开发环境): poc 环境
env "poc" added


# 也可直接修改下面文件
# ~/.v8patchctl/nacos_endpoints.yaml
envs:
  poc:   # --env 指定环境 dev
    server-addr: "10.103.3.10:8848"  # nacos地址
    username: "nacos"   # nacos 用户名
    password: "nacos"   # nacos 密码
    namespace: "seeyon-poc"   # v8 的nacos 配置命名空间
    describe: poc 环境
  test:   # --env 指定环境 test
    server-addr: "10.192.168.2:8848"  # nacos 地址
    username: "nacos"  # nacos 用户名
    password: "xxxx"  # nacos 密码
    namespace: "xxxx-xxxx-xxxx"    # v8 的nacos 配置命名空间

管理多个环境示例：

$ v8patchctl nacos list  # 列出环境信息
$ v8patchctl nacos add   # 增加环境信息
$ v8patchctl nacos update --env dev  # 更新dev环境信息
$ v8patchctl nacos remove --env dev  # 删除dev环境信息

# 2.2 Nacos public 配置（对象存储）

支持 MinIO / OBS / OSS。

# 2.3 日志记录

默认记录在/var/log/v8patchctl/路径下，每次打包都会生成一个日志文件，示例：

/var/log/v8patchctl/patchctl_20260414_144500.log

# 3. 命令概览

# 3.1 拉取 Nacos 公共配置

# 拉取dev环境的public配置，该子命令没有具体作用，只是用于验证拉取到的nacos配置是否可用
$ v8patchctl --env dev pull-public

# 3.2 上传补丁

# 真正执行补丁更新操作
# 命令格式 v8patchctl upload --env <指定环境>  --zip <指定补丁包>
$ v8patchctl --env dev upload --zip ./your_patch.zip   // 同时支持在线http/https

# 3.3 常用参数

  • --zip：补丁包路径（本地或 http/https）
  • --env：环境名，对应 nacos_endpoints.yaml 中的 env
  • --prefix：覆盖前端上传前缀（仅对常规前端补丁生效）
  • --dry-run：仅打印行为，不实际上传/变更
  • --skip-backup：跳过前端备份逻辑
  • --keep：备份保留数量（默认 3）
  • --tmpdir：指定临时目录
  • --namespace：K8s namespace（覆盖配置）
  • --registry：镜像仓库地址（覆盖配置）
  • --kubeconfig：kubeconfig 路径（覆盖配置）
  • --version：输出版本并退出

# 4. 前端补丁处理规则

# 4.1 常规前端补丁

结构：

<appname>/frontend/content/...

行为：

  • 上传到 <appname>/ 前缀
  • 支持 --prefix 覆盖
  • 触发备份到 __backup/<appname>/<timestamp>/

# 4.2 组件库补丁（fe_comp/web/libs）

结构（固定）：

fe_comp/web/libs/...

行为：

  • 上传到 libs/ 前缀
  • 不触发备份

# 4.3 Nodejs 离线包补丁（fe_comp/nodejs）

结构（固定）：

fe_comp/nodejs/...

行为：

  • 上传到 frontend-dependencies/udc-offline-pkgs/ 前缀
  • 不触发备份

# 4.4 客开custom-extensions 离线包补丁（custom-extensions）

结构（固定）：

custom-extensions/...

行为：

  • 上传到 custom-extensions 前缀
  • 触发备份到 __backup/custom-extensions/<timestamp>/

# 5. 后端补丁处理规则

后端补丁可能包含两类内容：

# 5.1 后端镜像 tar

结构示例：

<appname>/backend/*.tar

行为：

  1. 通过 skopeo 读取 tar 中的镜像引用
  2. 用“镜像 tag 包含 Deployment 名称”进行匹配
  3. 以 Deployment 当前镜像为准构造目标镜像（仅替换 tag；registry 可由 --registry 覆盖）
  4. 将镜像推送到目标仓库
  5. 更新 K8s Deployment 镜像（namespace 来自配置或 --namespace）

匹配示例：

  • 导入镜像：dockerhub.kubekey.local/seeyon/seeyon:m5-5.6.13
  • Deployment：m5（tag 中包含 m5）
  • 目标镜像：<deployment 当前镜像的 registry/repo>:m5-5.6.13

说明：

  • 如果同一个 tag 命中多个 Deployment，会报歧义错误。

# 5.2 Maven 依赖目录

结构示例（目录名为 backend-dependencies）：

<appname>/backend/backend-dependencies/...

行为：

  • 上传到对象存储 maven-dependencies/ 前缀

说明：当前代码检测目录名为 backend-dependencies，上传前缀为 maven-dependencies/。

# 6. 组合补丁

一个 zip 包可同时包含：

  • 常规前端
  • fe_comp/web/libs
  • fe_comp/nodejs
  • custom-extensions
  • 后端镜像 tar
  • backend-dependencies

命中多种类型时，会依次执行多次上传与后端更新。

# 7. 常见操作示例

# 7.1 补丁更新（默认前缀）

$ v8patchctl --env dev upload --zip ./patch.zip

# 7.2 干跑，演练不实际上传执行

$ v8patchctl --env dev upload --zip ./patch.zip --dry-run

# 7.3 跳过备份

$ v8patchctl --env dev upload --zip ./patch.zip --skip-backup

# 7.4 指定 K8s namespace 与 registry

$ v8patchctl --env dev upload --zip ./patch.zip --namespace seeyon-poc --registry registry.example.com

# 8. 故障排查

  • 镜像未匹配：确保导入镜像 tag 中包含目标 Deployment 名称

# 9. 下载链接⛓️

通过网盘分享的文件：v8patchctl 链接: https://pan.baidu.com/s/1bNimPtPma688cmxBAIAdzg 提取码: 5h3v

编撰人：zhenxy

快速跳转

← License注入器 →