谷雨开源 SaaS 平台（G2rain）
本文档由 g2rain-app-cli 的 README.md 自动同步生成。

G2Rain

# g2rain-app-cli

License TypeScript (opens new window) Node (opens new window)

g2rain 官方前端 CLI。支持两个项目族：

并提供 generate / build-config 开发期工具（仅业务子应用）。未指定 family 时默认生成 frontend-app。

CLI 本身是 Node 工具；生成结果须分别符合中央 frontend-app (opens new window) 与 frontend-shell (opens new window) Profile。

官网 (opens new window) · 完整文档 · 使用手册 · 命令接口 · 模板契约 · 模板快照治理 · Issues (opens new window) · Discussions (opens new window)

# 功能

  • 提供 create-g2rain-app 和 g2rain-app 两个等价 bin。
  • 子命令：app、shell、create（可省略）、generate、build-config；支持 --help / --version。
  • app / 默认 create：包内 template/；G2RAIN_TEMPLATE_PATH 可覆盖。
  • shell：包内 template-shell/；G2RAIN_SHELL_TEMPLATE_PATH 可覆盖；默认 contextPath=admin、port=3000；可选 --with-legacy（merge template-shell-legacy/，默认不含）。
  • generate / build-config：仅服务 frontend-app 工程。

CLI 不自动安装依赖、不初始化 Git、不注册平台资源。不得用 app 模板冒充 Shell。

# 环境

  • Node.js >=22
  • npm

# 安装与运行

npm 包名是 create-g2rain-app；安装后提供两个等价命令：g2rain-app 与 create-g2rain-app。

# 推荐：本机全局安装（装一次，长期使用）

npm install -g create-g2rain-app@1.0.0
g2rain-app --version

创建业务子应用：

g2rain-app app g2rain-member-app --context-path member

创建 Main Shell：

g2rain-app shell g2rain-admin-shell --context-path admin --port 3000

创建带存量双协议兼容的 Main Shell（迁移期）：

g2rain-app shell g2rain-admin-shell --context-path admin --port 3000 --with-legacy

兼容旧写法（默认 frontend-app）：

g2rain-app g2rain-member-app --context-path member

升级时显式重装目标版本：npm install -g create-g2rain-app@x.y.z。完整说明见使用手册。

# 备选：不装全局（CI / 一次性）

npx create-g2rain-app@1.0.0 app g2rain-member-app --context-path member
npx --package=create-g2rain-app@1.0.0 g2rain-app shell g2rain-admin-shell --context-path admin

生成位置是“当前工作目录下的项目名目录”，所以应先 cd 到明确的父目录。本地调试才用 G2RAIN_TEMPLATE_PATH / G2RAIN_SHELL_TEMPLATE_PATH 覆盖包内快照（见本地开发）。

# 交互式示例

> g2rain-app
? Project name › g2rain-new-app
? Context path (URL prefix, without leading slash) › new
➜ Using template: .../create-g2rain-app/template
✔ Project created at .../g2rain-new-app
  context path: /new

Context Path 默认由项目名移除 g2rain- 前缀和 -app 后缀得到。例如 g2rain-member-app 默认生成 member。

# 非交互示例

g2rain-app app g2rain-member-app --context-path member
g2rain-app g2rain-member-app --context-path member
g2rain-app g2rain-member-app --context_path member
g2rain-app g2rain-member-app member

当前未知选项会报错退出；项目名和 Context Path 的字符校验仍较弱。详见架构偏差与命令接口。

# 在已有 App 中使用生成工具

把 create-g2rain-app 装成项目 devDependency（正式项目用 npm 版本，例如 1.0.0，不要长期依赖 file:）：

# App 根目录
npm run build:generate -- --tables=member
npm run build:config
# 或直接：
npx g2rain-app generate --tables=member,member_identity
npx g2rain-app build-config

# 生成流程

flowchart TD
  CLI[执行 CLI] --> Args{参数齐全?}
  Args -->|否| Prompt[交互采集]
  Args -->|是| Target[计算目标目录]
  Prompt --> Target
  Target --> Exists{目录已存在?}
  Exists -->|是| Stop[拒绝覆盖]
  Exists -->|否| Template{包内 template 或覆盖路径?}
  Template -->|否| Fail[报错退出]
  Template -->|是| Copy[过滤并复制]
  Copy --> Replace[重写 package + 替换占位符]
  Replace --> Done[输出后续命令]

详细时序和失败行为见运行流程。

# 生成结果

当前会替换以下文件中的占位符（文件不存在时跳过）：

  • build.sh
  • lua/config.lua
  • README.md
  • .env
  • .env.production
  • vite.config.ts
  • src/runtime/env/index.ts

此外会重写 package.json 的 name、description、repository、homepage 和模板关键词，并按明确清单转换 README.md、AGENTS.md、docs/project.yaml、文档入口、架构概览与决策说明中的项目身份。docs/project.yaml 会保留 CLI 版本、模板仓库、模板 Commit 和 Context Path，便于追溯生成来源。模板新增占位文件或身份文档时必须同步 CLI 清单和契约测试。

生成后执行：

cd g2rain-member-app
npm install
npm run build

模板 lockfile 当前不会复制，因此首次生成使用 npm install 创建自己的 lockfile，而不是直接执行 npm ci。

# CLI 开发

npm ci
npm run build
npm run verify:template-snapshots

正式刷新包内模板由 GitHub Actions sync-templates 完成。本地排障：

$env:G2RAIN_ALLOW_LOCAL_SYNC = '1'
$env:G2RAIN_APP_TEMPLATE_REF = 'vX.Y.Z'
$env:G2RAIN_SHELL_TEMPLATE_REF = 'vA.B.C'
# 可选：$env:G2RAIN_TEMPLATE_SOURCE / G2RAIN_SHELL_TEMPLATE_SOURCE
npm run sync:templates
npm run verify:template-snapshots

本地验证编译产物（仅 CLI 仓开发；普通用户请用上文全局安装）：

npm run build
node dist/index.js app test-app --context-path test
# 或临时：npm link 后再执行 g2rain-app ...

npm run dev 会直接执行生成流程并在当前工作目录创建项目；不要在含同名重要目录的位置随意运行。推荐使用临时目录验证。

测试：npm test。策略见测试。

# 发布

npm 包名为 create-g2rain-app，发布 dist 与三份内嵌模板快照。正式发布：合并 sync PR → 打 CLI v* tag → publish-npm（OIDC Trusted Publishing）。本地只运行 npm pack --dry-run，不要 npm publish。详见发布与模板快照治理。

# 文档

主题 入口
项目事实与 Agent project.yaml · AGENTS.md (opens new window)
架构与边界 架构概览 · 运行流程 · 偏差
命令与模板 使用手册 · 命令接口 · 模板契约 · 快照治理
开发与交付 本地开发 · 测试 · 发布
安全 安全边界 · 漏洞报告 (opens new window)

# 贡献、许可证与联系

使用 feature/<name> 或 fix/<name> 合并到 develop，测试验证后再进入 main。CLI 变化会影响以后创建的全部 App，请同步模板契约、测试和文档。

本项目基于 Apache License 2.0 开源。

感谢所有为 g2rain 提交 Issue、代码、文档、建议和使用反馈的开发者。

← g2rain-app-template →