@gbits-jszx/gw-cli 2026.9.13-8 → 2026.9.14-2
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/README.md +44 -21
- package/bin/gw-cli.js +2 -1
- package/bin/native/gw-cli-linux-amd64 +0 -0
- package/bin/native/gw-cli-windows-amd64.exe +0 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,12 +2,29 @@
|
|
|
2
2
|
|
|
3
3
|
面向多个网关项目的跨平台构建、运行和交付工具。项目身份唯一来自显式 `--project-id <代号>`(或 `--project-id=<代号>`);不需要 `gw.project.yaml`,不接受旧 `--project` 路径,也不从 `GW_PROJECT_FILE` 或用户凭据中的旧 ID 兜底。`npm build/package/publish` 专用于维护 CLI 本身,包名固定为 `@gbits-jszx/gw-cli`,项目代号只隔离版本账本。
|
|
4
4
|
|
|
5
|
-
> 当前公开版本为 `@gbits-jszx/gw-cli@2026.9.13-
|
|
5
|
+
> 当前公开版本为 `@gbits-jszx/gw-cli@2026.9.13-11`,`latest` 已核对。公网使用 `npx -y --prefer-online @gbits-jszx/gw-cli@latest`;没有 Node/npm 的 Linux/WSL 可直接运行包内 `bin/native/gw-cli-linux-amd64`。源码开发继续使用 `go run ./tools/cli`。
|
|
6
|
+
>
|
|
7
|
+
> 默认 `all`、部署版本自动选择和 CLI 产品中立改造已进入源码,尚未发布到 npm;发布前使用源码验证。
|
|
6
8
|
|
|
7
9
|
[PC 开发构建发布、WSL/云 VM 初始化部署更新](../../../docs/user-docs/CLI-MULTI-PROJECT.md)。公网 registry 为 `https://registry.npmjs.org/`,包内包含 Windows amd64 和 Linux amd64(含 WSL)二进制。
|
|
8
10
|
|
|
9
11
|
打包过程和最终 `.tgz` 全部位于仓库根目录 `.gw-build/npm/`;源码目录不会生成 `bin/native` 或被 `npm version` 改写。
|
|
10
12
|
|
|
13
|
+
## 端口调试与新项目
|
|
14
|
+
|
|
15
|
+
新增 `debug port kill <端口>` 尚未发布到 npm,使用源码验证:
|
|
16
|
+
|
|
17
|
+
```powershell
|
|
18
|
+
go run ./tools/cli debug port kill 18080 --dry-run
|
|
19
|
+
go run ./tools/cli debug port kill 18080
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
无需项目代号,查询指定端口的 TCP 监听和 UDP 绑定 PID,并强制结束对应进程。`--dry-run` 仅预览;不清理远端连接,不跨 Windows/WSL,不自动提权或结束进程树。Linux/WSL 需要 `ss`(iproute2);查询权限不足或清理失败会返回非零退出码。正在运行的 `run all` 若有一个 app 被结束,监督进程会退出并清理其余 app 和临时数据库;清理后的占用查询会发现自动重启,但不会自动追杀新 PID。
|
|
23
|
+
|
|
24
|
+
Windows 默认 `run all` 启动本机 app,连接 `db start` 管理的本机持久 PostgreSQL(`127.0.0.1:15433`);不是 k3s Pod。一次性数据库显式使用 `run all --database temporary`,默认映射 `127.0.0.1:55432`,退出时回收容器和数据;`--target local|wsl` 只控制该临时模式的 Docker 执行位置。
|
|
25
|
+
|
|
26
|
+
CLI 当前不提供新项目源码脚手架;先准备框架源码布局,再运行 `config new` 交互登记用户级项目配置。它不会生成目录或改写 Go module;`deploy k3s init` 只初始化集群资源。完整步骤见[新项目接入](../../../docs/user-docs/CLI-MULTI-PROJECT.md#新项目如何开始)。
|
|
27
|
+
|
|
11
28
|
`npm build` 与 `npm package` 等价,从当前源码编译 Windows/Linux CLI 并生成 `.tgz`。编译期间每 5 秒报告已用时间,完成时显示各平台二进制大小、npm 文件清单、压缩包文件名、输出目录和总耗时;任何阶段失败都会保留原始错误并返回非零退出码。`npm publish` / `publish npm` 每次重新构建,并在默认自动编号下分配新的 npm 版本,不直接上传之前 build 的归档。源码 `go run ./tools/cli --version` 显示嵌入的源码基线 `2026.9.11-2`;打包阶段才把发布版本注入二进制和 `package.json`。
|
|
12
29
|
|
|
13
30
|
## 日期版本号
|
|
@@ -20,13 +37,13 @@ npm、Image、Chart 使用相同的 `yyyy.M.d-id` 格式,但按项目和制品
|
|
|
20
37
|
|
|
21
38
|
旧的 `yyyy.MM.dd.id` 仅保留为显式输入兼容,用于重建已经发布的旧包;新自动版本不会再生成旧格式。
|
|
22
39
|
|
|
23
|
-
|
|
40
|
+
序号记录位于统一配置 `~/jszx-infra/.gw-cli/config.yaml` 的 `projects.<project-id>.artifacts`,按项目和制品类型隔离;打包开始即占用,失败和 dry-run 也占用一次,避免自动重用版本。同一用户目录下、同一项目的并发自动打包不会重复分配,清理 `.gw-build` 或切换仓库副本不会重置编号。手动指定版本可用于重打包或在本地验证后发布;换机器或 CI 多节点并行时仍需统一分配并显式传入未发布版本。`GW_CLI_PROJECTS` 仅覆盖旧账本作为升级兼容路径。npm 包名固定,不同项目代号的账本隔离不代表能向该包重复发布同一个版本;维护 CLI 应使用稳定代号,当前为 `gw-demo`。该代号名下最新发布为 `2026.9.13-11`。
|
|
24
41
|
|
|
25
42
|
## 镜像 tag
|
|
26
43
|
|
|
27
|
-
`image build` 默认 `--tag auto`,生成 `yyyy.M.d-id`,例如 `2026.9.10-1`。该格式同时满足 Docker tag 与 Helm SemVer,Image 与 Chart
|
|
44
|
+
`image build` 默认 `--tag auto`,生成 `yyyy.M.d-id`,例如 `2026.9.10-1`。该格式同时满足 Docker tag 与 Helm SemVer,Image 与 Chart 各自编号。`deploy helm install` 省略版本参数时,会按 `--project-id` 从发布账本自动选择最近成功发布的 Chart 版本和目标镜像仓库最近成功发布的 Image tag;换机器或账本缺失时再显式传入。日期按执行 CLI 的机器本地时间计算,序号从 1 起,同日递增、跨日重置。参数优先级为 `--tag` > `GW_IMAGE_TAG` > `auto`;自动和新显式版本使用新格式,已存在的 `yyyy.MM.dd.id` 仍可显式重建或推送。
|
|
28
45
|
|
|
29
|
-
镜像与 npm
|
|
46
|
+
镜像与 npm 独立计数,编号同样写入统一配置的 `projects.<project-id>.artifacts`。开始构建时即占号,失败也保留,但只有成功构建才更新该 repository 的最近可推送 tag。同一 `project-id` 的不同镜像 repository 共用镜像每日序号,各自保存最近成功构建。显式 tag 可用于本地重建;不查询 Harbor。换机器或 CI 多节点构建时,应统一分配并显式传入未发布 tag,不能覆盖已发布镜像。
|
|
30
47
|
|
|
31
48
|
```powershell
|
|
32
49
|
# 自动编号,输出 Docker 构建日志及最终完整镜像名
|
|
@@ -39,18 +56,22 @@ go run ./tools/cli --project-id gw-demo image push
|
|
|
39
56
|
|
|
40
57
|
## Chart 版本
|
|
41
58
|
|
|
42
|
-
`chart package` 独立生成 `yyyy.M.d-id`,例如 `2026.9.10-1`;Chart metadata、归档名和 Harbor OCI tag 不再二次映射或添加 project-id 前缀。`chart push`
|
|
59
|
+
`chart package` 独立生成 `yyyy.M.d-id`,例如 `2026.9.10-1`;Chart metadata、归档名和 Harbor OCI tag 不再二次映射或添加 project-id 前缀。`chart push` 默认复用统一配置中尚未发布且文件仍存在的精确归档;没有可复用包时自动分配下一版本、打包并推送。旧的 `{project-id}-yyyy.MM.dd.id`、`yyyy.MM.dd.id` 和合法 SemVer 仍可显式用于重建或回滚。Chart 默认地址为 `oci://<Harbor>/<Harbor项目>/charts/<project-id>`,自动与镜像路径分离,无需另传 `/charts`;`--registry/--repository` 可覆盖 registry 和 OCI 父路径。
|
|
43
60
|
|
|
44
61
|
## 配置查看与校验
|
|
45
62
|
|
|
46
63
|
```powershell
|
|
64
|
+
go run ./tools/cli config new
|
|
65
|
+
go run ./tools/cli config new --project-id my-gateway --non-interactive --yes
|
|
66
|
+
go run ./tools/cli config list
|
|
67
|
+
go run ./tools/cli config list --json
|
|
68
|
+
go run ./tools/cli config show
|
|
69
|
+
go run ./tools/cli config check
|
|
47
70
|
go run ./tools/cli --project-id gw-demo config show
|
|
48
|
-
go run ./tools/cli --project-id gw-demo config validate
|
|
49
|
-
go run ./tools/cli --project-id gw-demo project show
|
|
50
71
|
```
|
|
51
72
|
|
|
52
|
-
`config show` 仅显示凭据状态,不输出 Token 或密码;`config
|
|
53
|
-
配置命令已随 `2026.9.13-
|
|
73
|
+
`config new` 回显确认后写入 `projects.<project-id>` 并输出接入命令;若同一文件仍是旧版或混合版凭据结构,会先在内存升级和校验,再创建 `config.yaml.bak.<时间>` 私有备份并原子替换,失败不改原文件。`config list` 读取统一配置中已记录的项目代号;`config show` 仅显示凭据状态,不输出 Token 或密码;`config check` 只做静态校验,不执行集群写操作。运行时配置使用 `config runtime get/set/history/rollback`。
|
|
74
|
+
配置命令已随 `2026.9.13-9` 发布到 npm latest。
|
|
54
75
|
|
|
55
76
|
## 使用
|
|
56
77
|
|
|
@@ -59,28 +80,30 @@ go run ./tools/cli --project-id gw-demo project show
|
|
|
59
80
|
```powershell
|
|
60
81
|
go run ./tools/cli --version
|
|
61
82
|
go run ./tools/cli --project-id gw-demo doctor
|
|
62
|
-
go run ./tools/cli --project-id gw-demo test
|
|
63
|
-
go run ./tools/cli --project-id gw-demo build
|
|
83
|
+
go run ./tools/cli --project-id gw-demo test
|
|
84
|
+
go run ./tools/cli --project-id gw-demo build
|
|
64
85
|
go run ./tools/cli --project-id gw-demo run all
|
|
65
86
|
```
|
|
66
87
|
|
|
67
88
|
| 命令 | `--project-id` |
|
|
68
89
|
|---|---|
|
|
69
90
|
| `build/run/test`、`image/chart/npm/publish` 的实际操作 | 必填 |
|
|
70
|
-
| `
|
|
91
|
+
| `deploy k3s/helm` 的实际操作,包括状态查询及 dry-run | 必填 |
|
|
71
92
|
| 隐藏 `cleanup`,仅供 npm wrapper 回收本地资源 | 必填 |
|
|
93
|
+
| `config new --non-interactive` | 必填 |
|
|
94
|
+
| `config list/new/show/check/runtime` | 可选;`config new` 交互询问代号 |
|
|
72
95
|
| `doctor` | 可选 |
|
|
73
96
|
| 帮助和版本查询 | 不需要 |
|
|
74
97
|
|
|
75
98
|
项目代号最长 63 字符,以小写字母开头,只含小写字母、数字和不连续的连字符,末尾为字母或数字。缺失、空值、非法值或重复参数均失败;两次相同值也不接受。源码从当前目录向上找最近 `go.mod`,不通过项目代号定位另一个仓库。
|
|
76
99
|
|
|
77
|
-
`build`、`run`、`test`
|
|
100
|
+
`build`、`run`、`test` 省略目标时默认 `all`,也可显式选择 `core|mock|web|all`;目标固定映射 `./apps/core-gateway`、`./apps/mock-gateway`、`./apps/web-service`,构建和运行的 `all` 不包含 CLI。`test core/mock/web` 只执行对应宿主的 `go test -short`,`test all` 执行 `go test -short ./apps/...` 覆盖 `apps` 下全部包但不扫描 CLI;需要执行 CLI 集成测试时单独运行 `go test ./tools/cli`,CI 若要测试全部 Go 包但跳过集成测试则运行 `go test -short ./...`。单目标执行对应 package 的测试子树。旧 manifest 自定义 app/package/build/run/test/health-url 不再生效。`smoke` 和整个 `dev` 入口已删除。
|
|
78
101
|
|
|
79
102
|
基础默认值仍为 `tools/helm/default/values.yaml`;`--profile beta` / `--profile release` 选择 Chart 内 profile,`--values` 额外覆盖,未指定 profile 时只用基础默认值。`--release` 仅表示 Helm 实例名。
|
|
80
103
|
|
|
81
|
-
本地 `run`
|
|
104
|
+
本地 `run all` 除了通用宿主、`local.*` 配置和本机持久 PostgreSQL,还会根据 `local.demo` 启动仓库内置登录与 Hello Demo,本地演示账号和密码固定为 `demo/demo`;不读取用户环境变量。Helm/k3s 部署仍由对应应用 values 与 Secret 管理。显式 `--database temporary` 使用随机密码,退出时回收。
|
|
82
105
|
|
|
83
|
-
Go 项目的 `build`、`run`、`test` 需要源码和 Go
|
|
106
|
+
Go 项目的 `build`、`run`、`test` 需要源码和 Go。本仓库默认 `run` 还需要已由 `db start` 启动的本机 PostgreSQL,以及 Windows 上执行统一迁移脚本所需的 Git for Windows;只有 `--database temporary` 需要 Docker。`run` 会按目标先构建,再启动 `.gw-build/local/` 下对应二进制;Windows 启动 `.exe`,省略目标时等同 `build all`。如果旧 app 仍占用任一 app 端口,`run` 直接失败,不会自动终止旧进程。npm 发布使用当前平台 npm;镜像命令优先使用当前平台 Docker,Windows 缺少 Docker 时转 WSL;Chart 推送在 Windows 默认走 WSL,可用 `--wsl=false` 切换。平台能力由 `doctor` 输出。
|
|
84
107
|
|
|
85
108
|
根 `--help` 只展示下一层入口,并按颜色分为“本地 PC · 日常开发”“远程 VM · 日常部署”“高级命令 · 制品与维护”;各级命令沿用所属分组颜色,参数默认值使用洋红色突出。交互终端默认启用颜色;`GW_CLI_COLOR=always|never` 可强制开关,未强制开启时 `NO_COLOR` 会关闭颜色。集群操作唯一入口为 `deploy k3s` / `deploy helm`,包括 `deploy k3s restore/purge`;顶层 `k3s` / `helm` 已删除。
|
|
86
109
|
|
|
@@ -90,29 +113,29 @@ Go 项目的 `build`、`run`、`test` 需要源码和 Go,本仓库 `run` 还
|
|
|
90
113
|
go run ./tools/cli --project-id gw-demo deploy k3s init --dry-run
|
|
91
114
|
```
|
|
92
115
|
|
|
93
|
-
目标机器需预先安装并运行 k3s、安装 Helm,并允许当前用户访问 kubeconfig;不自动安装 k3s 或 Helm。PostgreSQL 参数使用 `--pgsql-*`,数据库名为 `--pgsql-dbname`。已有密码分别复用,首次业务及管理员密码人工输入,危险修改需二次确认。imagePullSecret 来自执行机器的 Docker `auths`,缺少有效凭据时跳过,不能由 Chart 的 Helm 登录替代。完整说明见 [k3s 初始化](../../../docs/user-docs/K3S-INIT.md)。源码改动需要重新发布才会进入 npm `@latest`,当前 `@latest` 已是 `2026.9.13-
|
|
116
|
+
目标机器需预先安装并运行 k3s、安装 Helm,并允许当前用户访问 kubeconfig;不自动安装 k3s 或 Helm。部署前可运行 `doctor --scope deploy`,该 scope 只检查 Helm/k3s/kubeconfig,不要求 Go、Node.js 或 npm。PostgreSQL 参数使用 `--pgsql-*`,数据库名为 `--pgsql-dbname`。已有密码分别复用,首次业务及管理员密码人工输入,危险修改需二次确认。imagePullSecret 来自执行机器的 Docker `auths`,缺少有效凭据时跳过,不能由 Chart 的 Helm 登录替代。完整说明见 [k3s 初始化](../../../docs/user-docs/K3S-INIT.md)。源码改动需要重新发布才会进入 npm `@latest`,当前 `@latest` 已是 `2026.9.13-11`。
|
|
94
117
|
|
|
95
118
|
## 发布凭据
|
|
96
119
|
|
|
97
|
-
项目身份仅来自 `--project-id`,默认交付地址和资源名称从代号推导。Harbor 端点按对应命令支持的参数 > `GW_HARBOR_REGISTRY/GW_HARBOR_PROJECT` > 用户配置端点 > `szharbor.g-bits.com/jszx-infra` 默认值解析。用户 `~/jszx-infra/.gw-cli/config.yaml`
|
|
120
|
+
项目身份仅来自 `--project-id`,默认交付地址和资源名称从代号推导。Harbor 端点按对应命令支持的参数 > `GW_HARBOR_REGISTRY/GW_HARBOR_PROJECT` > 用户配置端点 > `szharbor.g-bits.com/jszx-infra` 默认值解析。用户 `~/jszx-infra/.gw-cli/config.yaml` 保存凭据、平台区块和项目制品版本,不保存当前项目;旧 `projects.yaml` 仅通过显式 `GW_CLI_PROJECTS` 兼容。CI 显式传代号并注入凭据,无需携带项目清单。帮助和版本查询不创建配置。
|
|
98
121
|
|
|
99
122
|
Namespace/应用 Release 默认代号,PG Release 默认 `<代号>-pg`,数据库名/用户名将 `-` 转为 `_`,数据库连接 Secret 默认 `<代号>-database`。超长 Release/资源名自动缩短并保留确定性哈希;Namespace 和制品地址保留完整代号。kubeconfig/context 默认 `/etc/rancher/k3s/k3s.yaml` / `default`,可通过现有参数及环境变量覆盖。详细规则见[多项目 CLI 指南](../../../docs/user-docs/CLI-MULTI-PROJECT.md)。
|
|
100
123
|
|
|
101
124
|
```powershell
|
|
102
125
|
go run ./tools/cli --project-id gw-demo npm publish
|
|
103
126
|
go run ./tools/cli --project-id gw-demo image push
|
|
104
|
-
go run ./tools/cli --project-id gw-demo chart push
|
|
127
|
+
go run ./tools/cli --project-id gw-demo chart push
|
|
105
128
|
```
|
|
106
129
|
|
|
107
130
|
缺少 npm Token 或 Harbor Robot 账号/密码时,CLI 会询问并自动保存到 `~/jszx-infra/.gw-cli/config.yaml`;可用 `GW_CLI_CONFIG` 覆盖位置。已有配置不重复询问。命令参数、`NODE_AUTH_TOKEN` / `GW_HARBOR_USERNAME` / `GW_HARBOR_PASSWORD` 优先于用户配置。
|
|
108
131
|
|
|
109
|
-
`deploy helm install`
|
|
132
|
+
`deploy helm install` 的 release、namespace、Chart 地址、数据库资源名、kubeconfig/context 均由 `--project-id` 和固定规则推导;Chart 版本和镜像 tag 默认读取该项目的最近成功发布记录。`--version`、`--tag` 只用于跨机器、账本缺失、回滚或一次性覆盖。拉取 OCI Chart 时先复用 Helm 原生登录或公共访问;只有确认认证失败才补齐 Harbor 账密,隐藏密码输入、保存后通过 stdin 登录。支持 `--username` / `--password` 和 `GW_HARBOR_USERNAME` / `GW_HARBOR_PASSWORD`,也支持 `--helm-registry-config` / `HELM_REGISTRY_CONFIG` 指定执行机器的 Helm 凭据文件。网络、版本不存在等错误直接报告;`--dry-run` 不探测、不登录、不询问账密。
|
|
110
133
|
|
|
111
134
|
Token 和密码在终端中不回显。配置文件保存明文凭据,Unix 下目录/文件权限为 0700/0600,Windows 使用用户目录 ACL。网关服务不读取此文件。
|
|
112
135
|
|
|
113
136
|
## 源码打包与本地验证
|
|
114
137
|
|
|
115
|
-
已有公开 npm 包;`--project-id` 改造首发于 `2026.9.13-2`,config 命令随 `2026.9.13-
|
|
138
|
+
已有公开 npm 包;`--project-id` 改造首发于 `2026.9.13-2`,config 命令随 `2026.9.13-9` 发布。以下 npm 操作继续使用版本账本对应的维护代号 `gw-demo`:
|
|
116
139
|
|
|
117
140
|
```powershell
|
|
118
141
|
# 自动使用当天序号,终端会打印版本和文件名
|
|
@@ -120,7 +143,7 @@ go run ./tools/cli --project-id gw-demo npm build
|
|
|
120
143
|
# 把占位文件名替换为本次 build 实际输出的文件名;这里使用本地新包
|
|
121
144
|
$gwNpmArchive = './.gw-build/npm/<本次输出的文件名>.tgz'
|
|
122
145
|
npx -y --package $gwNpmArchive gw-cli --version
|
|
123
|
-
npx -y --package $gwNpmArchive gw-cli --project-id gw-demo
|
|
146
|
+
npx -y --package $gwNpmArchive gw-cli --project-id gw-demo config show
|
|
124
147
|
# 只检查发布包,不上传、不询问 Token
|
|
125
148
|
go run ./tools/cli --project-id gw-demo npm publish --dry-run
|
|
126
149
|
# 获得发布授权后执行:重新构建并自动编号,输入具备发布权限的 npm Token
|
package/bin/gw-cli.js
CHANGED
|
@@ -57,7 +57,8 @@ function runsLocalServices(command) {
|
|
|
57
57
|
if (arg.startsWith('--')) continue;
|
|
58
58
|
return ['core', 'mock', 'web', 'all'].includes(arg);
|
|
59
59
|
}
|
|
60
|
-
|
|
60
|
+
// The native CLI defaults an omitted app target to all.
|
|
61
|
+
return true;
|
|
61
62
|
}
|
|
62
63
|
|
|
63
64
|
// Keep the wrapper alive while the native CLI stops its services and database.
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -9,12 +9,12 @@
|
|
|
9
9
|
"files": [
|
|
10
10
|
"bin"
|
|
11
11
|
],
|
|
12
|
-
"gwVersion": "2026.9.
|
|
12
|
+
"gwVersion": "2026.9.14-2",
|
|
13
13
|
"license": "MIT",
|
|
14
14
|
"name": "@gbits-jszx/gw-cli",
|
|
15
15
|
"publishConfig": {
|
|
16
16
|
"access": "public",
|
|
17
17
|
"registry": "https://registry.npmjs.org/"
|
|
18
18
|
},
|
|
19
|
-
"version": "2026.9.
|
|
19
|
+
"version": "2026.9.14-2"
|
|
20
20
|
}
|