@gbits-jszx/gw-cli

面向多个网关项目的跨平台构建、运行和交付工具。项目从 gw.project.yaml 解析；npm package/publish 专用于维护 CLI 本身。

PC 开发构建发布、WSL/云 VM 初始化部署更新。公网 registry 为 https://registry.npmjs.org/，包内包含 Windows amd64 和 Linux amd64（含 WSL）二进制。

打包过程和最终 .tgz 全部位于仓库根目录 .gw-build/npm/；源码目录不会生成 bin/native 或被 npm version 改写。

npm package 会依次输出准备包、Windows/Linux 编译和 npm 压缩打包日志。编译期间每 5 秒报告已用时间，完成时显示各平台二进制大小、npm 文件清单、压缩包文件名、输出目录和总耗时；任何阶段失败都会保留原始错误并返回非零退出码。

日期版本号

npm、Image、Chart 统一使用 yyyy.M.d-id，例如 2026.9.11-2 表示 2026 年 9 月 11 日第 2 次构建。npm package、npm publish 和 publish npm 默认 --version auto，按执行机器的本地日期生成，序号从 1 开始、同日递增、跨日重置。也可用 --version 2026.9.11-2 指定版本，日期须有效，月、日和序号均不得带前导零。

该格式可直接被 npm 解析为 SemVer：yyyy.M.d 是 major/minor/patch，id 是数字型 prerelease 标识。包内 package.json 的 version、gwVersion 和 Windows/Linux 二进制编译版本使用完全相同的字符串，不再做 yyyy.Mdd.id 映射。日常安装继续使用 @latest；精确复现使用完整版本号。由于它在 SemVer 中属于 prerelease，普通版本范围默认不会匹配，依赖方不要使用 ^2026.9.11，应使用 @latest 或精确版本。

npm publish / publish npm 会自动向 npm 传入 --tag latest，明确把本次版本设为 @latest，同时满足 npm 对 prerelease 发布的显式 tag 要求。--dry-run 使用相同参数但不上传；npm pack --dry-run 只检查打包，不能替代发布检查。

旧的 yyyy.MM.dd.id 仅保留为显式输入兼容，用于重建已经发布的旧包；新自动版本不会再生成旧格式。

序号记录位于 ~/jszx-infra/.gw-cli/projects.yaml，按 project-id 和制品类型隔离；打包开始即占用，失败和 dry-run 也占用一次，避免自动重用版本。同一用户目录下的并发自动打包不会重复分配，清理 .gw-build 或切换仓库副本不会重置编号。手动指定版本可用于重打包或在本地验证后发布；换机器或 CI 多节点并行时仍需统一分配并显式传入未发布版本。GW_CLI_PROJECTS 可覆盖账本路径。

镜像 tag

image build 默认 --tag auto，生成 yyyy.M.d-id，例如 2026.9.10-1。该格式同时满足 Docker tag 与 Helm SemVer，Image 和 Chart 在 Harbor 中可使用完全一致的版本字符串。日期按执行 CLI 的机器本地时间计算，序号从 1 起，同日递增、跨日重置。参数优先级为 --tag > GW_IMAGE_TAG > auto；自动和新显式版本使用新格式，已存在的 yyyy.MM.dd.id 仍可显式重建或推送。

镜像与 npm 独立计数，编号同样写入用户级 projects.yaml。开始构建时即占号，失败也保留，但只有成功构建才更新该 repository 的最近可推送 tag。同一 project-id 的不同镜像 repository 共用镜像每日序号，各自保存最近成功构建。显式 tag 可用于本地重建；不查询 Harbor。换机器或 CI 多节点构建时，应统一分配并显式传入未发布 tag，不能覆盖已发布镜像。

# 自动编号，输出 Docker 构建日志及最终完整镜像名
npx -y --prefer-online @gbits-jszx/gw-cli@latest image build
# 自动使用该 repository 最近一次成功构建的 tag，不生成新编号
npx -y --prefer-online @gbits-jszx/gw-cli@latest image push

image push / publish image 的默认 --tag auto 会读取最近成功构建记录；没有记录时要求先 build 或显式传入 tag。优先级为 --tag > GW_IMAGE_TAG > 自动识别；为兼容已有本地镜像，显式推送仍接受旧 tag 格式。以上行为在源码修改发布后才进入 npm @latest，发布前用 go run ./tools/cli image build 验证。

Chart 版本

chart package 默认生成与镜像一致的 yyyy.M.d-id，例如 2026.9.10-1；Chart metadata、归档名和 Harbor OCI tag 不再二次映射或添加 project-id 前缀。chart push 默认复用 projects.yaml 中尚未发布且文件仍存在的精确归档；没有可复用包时自动分配下一版本、打包并推送。旧的 {project-id}-yyyy.MM.dd.id、yyyy.MM.dd.id 和合法 SemVer 仍可显式用于重建或回滚。

使用

首次发布成功后，在 GW-Framework 项目根目录执行：

npx -y --prefer-online @gbits-jszx/gw-cli@latest --version
npx -y --prefer-online @gbits-jszx/gw-cli@latest doctor
npx -y --prefer-online @gbits-jszx/gw-cli@latest build all
npx -y --prefer-online @gbits-jszx/gw-cli@latest run all
# 另开终端
npx -y --prefer-online @gbits-jszx/gw-cli@latest test all

build、run、test 统一接受 core|mock|web|all，all 只包含三个 app。build、run 需要源码和 Go，run 还需要 Docker（Windows 默认走 WSL）。npm 发布使用当前平台 npm；镜像命令优先使用当前平台 Docker，Windows 缺少 Docker 时转 WSL；Chart 推送在 Windows 默认走 WSL，可用 --wsl=false 切换。平台能力由 doctor 输出。

k3s init 支持 Windows/WSL 和 Linux amd64 VM，无需源码或 Go：

npx -y --prefer-online @gbits-jszx/gw-cli@latest k3s init --dry-run
npx -y --prefer-online @gbits-jszx/gw-cli@latest k3s init

目标机器需预先安装并运行 k3s、安装 Helm，并允许当前用户访问 kubeconfig。Windows 默认走 Ubuntu-24.04 WSL，Linux 直接执行；不自动安装 k3s 或 Helm。PostgreSQL 参数使用 --pgsql-*，数据库名为 --pgsql-dbname。已有密码分别复用，首次业务及管理员密码人工输入，危险修改需二次确认，缺少 Docker 登录配置时跳过 imagePullSecret。完整说明见 k3s 初始化。源码修改发布后才会进入 npm @latest。

发布凭据

项目身份、交付地址与部署目标声明在项目 gw.project.yaml；帮助和版本不创建配置。用户 ~/jszx-infra/.gw-cli/config.yaml 仅保存发布凭据，projects.yaml 按项目记录制品版本。CI 携带项目文件并注入凭据，不依赖全局当前项目。

npx -y --prefer-online @gbits-jszx/gw-cli@latest publish npm --version 2026.9.11-2
npx -y --prefer-online @gbits-jszx/gw-cli@latest publish image
npx -y --prefer-online @gbits-jszx/gw-cli@latest publish chart

缺少 npm Token 或 Harbor Robot 账号/密码时，CLI 会询问并自动保存到 ~/jszx-infra/.gw-cli/config.yaml；可用 GW_CLI_CONFIG 覆盖位置。已有配置不重复询问。命令参数、NODE_AUTH_TOKEN / GW_HARBOR_USERNAME / GW_HARBOR_PASSWORD 优先于用户配置。

Token 和密码在终端中不回显。配置文件保存明文凭据，Unix 下目录/文件权限为 0700/0600，Windows 使用用户目录 ACL。网关服务不读取此文件。

首次发布与本地验证

2026-09-09 查询公网 @gbits-jszx/gw-cli 返回 404；首次发布前直接运行源码 CLI：

# 自动使用当天序号，终端会打印版本和文件名
go run ./tools/cli npm package
# 或显式指定版本
go run ./tools/cli npm package --version 2026.9.11-2
npx -y --package ./.gw-build/npm/gbits-jszx-gw-cli-2026.9.11-2.tgz gw-cli --version
npx -y --package ./.gw-build/npm/gbits-jszx-gw-cli-2026.9.11-2.tgz gw-cli build all
# 只检查发布包，不上传、不询问 Token
go run ./tools/cli publish npm --dry-run
# 真正发布：输入具备 @gbits-jszx/gw-cli 发布权限的 npm Token
go run ./tools/cli publish npm --version 2026.9.11-2

发布后的版本号不可复用。这里的 gw-cli 是包内命令名，公网下载始终使用 scoped 包 @gbits-jszx/gw-cli。