一、概述

@oinone/pamirs-cli（命令：oinone-backend）是 Oinone 后端工程脚手架，用于快速生成基于 Maven 多模块结构的 Oinone 后端工程。当前 CLI 版本：7.2.1，支持的最新 Oinone 框架版本：7.2.9 / 6.4.12。

功能特性：

• 交互式创建工程，内置默认值与合理校验
• 支持参数静默创建（适用于 CI/CD）
• 企业版可选生成仓库凭证文件
• 提供 doctor 环境检查

二、环境要求

阶段	要求
运行 CLI	Node.js
构建生成的后端工程	Java + Maven（可用 doctor 校验）

不同 Oinone 版本对 Java 和 Maven 的要求：

Oinone 版本	JDK	Maven	Spring Boot
6.4.*	Java 8（1.8.0_221+）	—	2.3.8
7.2+	Java 17	Maven 3.6.3+	3.3.13

三、安装

npm install -g @oinone/pamirs-cli

验证安装：

oinone-backend --version

也可以使用 npx 直接运行，无需全局安装：

npx @oinone/pamirs-cli create my-project

四、创建项目

（一）交互式创建

运行 create 命令并跟随提示输入即可：

oinone-backend create my-project

注意

交互模式下，groupId 默认值为 pro.shushi.pamirs.demo。

（二）静默式创建（推荐用于 CI/CD）

通过参数一次性传入所有配置，无需交互：

社区版：

oinone-backend create my-project \
  --group-id pro.shushi.demo \
  --oinone-version 7.2.9 \
  --edition community

企业版：

oinone-backend create my-project-enterprise \
  --group-id pro.shushi.demo \
  --oinone-version 7.2.9 \
  --edition enterprise \
  --username <username> \
  --password <password> \
  --write-project-credential

（三）演练模式（不落盘）

添加 --dry-run 参数可在不写入磁盘的情况下预检参数，适用于验证配置是否正确：

oinone-backend create my-project \
  --group-id pro.shushi.demo \
  --oinone-version 7.2.9 \
  --edition community \
  --dry-run

（四）显式指定特性 / 中间件 / 模块

oinone-backend create my-project \
  --group-id pro.shushi.demo \
  --oinone-version 7.2.9 \
  --edition standard \
  --features TURBO,PERMISSION \
  --middlewares rocketmq \
  --modules sql_record,timezone

注意

--features、--middlewares、--modules 均支持逗号分隔多个值，传入 none 表示不启用任何选项。

（五）创建 Oinone 6.4.* 工程

社区版：

oinone-backend create my-project-64 \
  --group-id pro.shushi.demo \
  --oinone-version 6.4.12 \
  --edition community

企业版：

oinone-backend create my-project-64-enterprise \
  --group-id pro.shushi.demo \
  --oinone-version 6.4.12 \
  --edition enterprise \
  --username <username> \
  --password <password> \
  --write-project-credential

五、生成的工程结构

生成的后端工程为 Maven 多模块结构：

my-project/
├── pom.xml                  # 父 POM（引入 oinone-bom）
├── my-project-api/          # API 模块（接口定义）
├── my-project-core/         # 核心业务模块
├── my-project-boot/         # 启动模块（Spring Boot 应用入口）
│   ├── src/main/java/.../MyProjectApplication.java
│   └── src/main/resources/
│       ├── application.yml
│       └── config/
│           └── application-dev.yml
└── docker/                  # Docker 部署配置

构建工程：

cd my-project
mvn clean install

注意

启动模块 {artifactId}-boot 是 Spring Boot 应用入口，构建和启动时请确保 JDK 和 Maven 版本满足对应 Oinone 版本的要求（详见 环境要求）。

六、命令参考

（一）全局参数

参数	说明
-l, --lang <lang>	语言（zh-CN / en-US）
-v, --version	输出版本号
-h, --help	输出帮助

（二）oinone-backend create [artifactId]

参数	说明
-g, --group-id <groupId>	项目 groupId（默认 pro.shushi.pamirs.demo）
-o, --oinone-version <version>	Oinone 版本（例如 7.2.9）
-p, --package <package>	基础包名（默认与 groupId 一致）
-e, --edition <edition>	系统版本：community / seed / standard / professional / enterprise
--features <features>	特性列表，逗号分隔（或传 none）
--middlewares <middlewares>	中间件列表，逗号分隔（或传 none）
--modules <modules>	模块/应用列表，逗号分隔（或传 none）
-u, --username <username>	企业版 Maven 仓库用户名（可选）
-P, --password <password>	企业版 Maven 仓库密码（可选）
--write-project-credential	在项目目录写入 settings.xml 并自动加入 .gitignore
-f, --force	目标目录存在时覆盖/合并
-d, --dry-run	演练模式：不落盘

（三）oinone-backend doctor

参数	说明
-o, --oinone-version <version>	用于校验的 Oinone 版本（仅支持 6.4.* 与 7.2+）

oinone-backend doctor --oinone-version 7.2.9

（四）--features（可选特性）

各 Edition 对应的默认特性：

Edition	默认特性
community	无
seed	TURBO,SYS_SETTING_CORPORATE
standard	TURBO,SYS_SETTING_CORPORATE,PERMISSION,NO_CODE_APP_CREATION,METADATA_MANAGER
professional	TURBO,SYS_SETTING_CORPORATE,PERMISSION,NO_CODE_APP_CREATION,METADATA_MANAGER,DATA_AUDIT,VIRTUAL_FIELDS
enterprise	TURBO,SYS_SETTING_CORPORATE,PERMISSION,NO_CODE_APP_CREATION,METADATA_MANAGER,DATA_AUDIT,VIRTUAL_FIELDS,LOW_CODE_GENERATION,SSO

（五）--middlewares（中间件）

默认值	可选值
rocketmq	rocketmq,kafka,rabbitmq

传入 none 可关闭所有中间件。

（六）--modules（模块/应用）

可选值
print,sql_record,channel,international,my_center,timezone

七、企业版仓库凭证

企业版创建时启用 --write-project-credential，CLI 会在项目目录生成 settings.xml，并自动追加到 .gitignore。

构建时指定该文件：

cd my-project
mvn clean install -s settings.xml

提示

• settings.xml 包含 Maven 仓库凭证，请勿提交到版本控制（CLI 已自动将其加入 .gitignore）。

八、版本与模板映射

Oinone 版本	模板目录	说明
6.4.*	template-6.4.0	Java 8 + Spring Boot 2.3.8
7.2+	template-7.2.0	Java 17 + Maven 3.6.3+ + Spring Boot 3.3.13

版本发布日志：

• Oinone 7.2.x 版本发布日志
• Oinone 6.4.x 版本发布日志

警告

不支持的 Oinone 版本会直接报错，不会生成工程。

九、源码依赖（本地联调）

当需要对 Oinone 后端框架源码进行调试或二次开发时，可以通过以下方式将生成的业务工程与框架源码关联，实现本地联调。

（一）原理

Maven 多模块工程与 IntelliJ IDEA 的"父目录"工作单元机制：IDEA 会递归识别父目录下所有 Maven 项目（含本地框架源码工程），依赖以本地模块（project reference）而非 Maven 仓库 jar 解析，对框架源码的修改即时生效。

（二）操作步骤

1、创建父目录

mkdir oinone-dev && cd oinone-dev

2、生成业务工程并克隆框架源码

在父目录下，使用 CLI 生成业务工程：

oinone-backend create my-project \
  --group-id pro.shushi.demo \
  --oinone-version 7.2.9 \
  --edition community

在同一父目录下，克隆 Oinone 后端框架源码：

git clone https://gitee.com/oinone/oinone-pamirs.git

最终目录结构：

oinone-dev/
├── my-project/        # CLI 生成的业务工程
└── oinone-pamirs/     # Oinone 后端框架源码

3、用 IDEA 打开父目录

打开 IntelliJ IDEA，选择 File → Open，选中 oinone-dev 父目录（而非 my-project 子工程），点击 OK。

IDEA 将自动识别父目录下的两个 Maven 工程，框架依赖会解析为本地模块源码，而非远程 Maven 仓库中的 jar 包。

4、启动调试

在 IDEA 中展开 my-project > my-project-boot，找到启动类（如 MyProjectApplication.java），右键运行或 Debug 即可对框架源码断点调试。

注意

• 首次导入时需等待 IDEA 完成 Maven 索引与依赖解析。
• 确保 JDK 和 Maven 版本满足对应 Oinone 版本的要求（详见 环境要求）。
• 对 oinone-pamirs 源码的修改即时生效，无需重新发布到 Maven 仓库。