服务端命令参考

server_api 使用 Cobra 提供统一命令行入口。在源码目录中使用 go run .，编译后将其替换为可执行文件路径即可：

bash

# 源码运行
go run . <command>

# 编译后运行
./server_api <command>

本文参数与当前 server_api/cmd 中实际注册的命令保持一致。路径默认值均相对于执行命令时的当前工作目录解析，推荐在 server_api 根目录执行。

命令总览

完整命令	用途
`service admin`	启动管理端 API 服务
`service api`	启动用户端 API 服务
`version`	读取配置并显示核心框架版本
`plugin create <plugin_id>`	创建独立插件仓库和本地联调环境
`plugin validate <package.zip>`	只读校验插件发行包
`plugin generate`	重新生成后端插件静态注册文件
`plugin install <package.zip>`	首次安装插件
`plugin upgrade <package.zip>`	升级已安装插件
`plugin remove <plugin_id>`	可恢复地移除插件
`plugin purge <plugin_id>`	不可恢复地彻底清理插件
`completion <shell>`	生成 Shell 自动补全脚本
`help [command]`	查看命令帮助

通用帮助参数

所有层级都支持 Cobra 提供的帮助参数：

参数	类型	默认值	说明
`-h, --help`	Boolean	`false`	显示当前命令、子命令及参数说明，不执行业务操作

bash

go run . --help
go run . plugin --help
go run . plugin create --help

命令分组

service 与 plugin 是命令分组，本身不启动服务或修改数据：

命令	自身业务参数	说明
`service`	无	展示并承载 `admin`、`api` 两个服务子命令
`plugin`	无	展示并承载插件创建、校验、注册、安装、升级及移除子命令

二者只支持通用的 -h, --help，必须继续指定子命令才能执行业务操作。

启动管理端服务

bash

go run . service admin --config config.yaml

启动管理端 API，监听地址读取配置文件中的 server.admin_addr，默认配置通常为 :8001。启动过程中会初始化数据库、Redis 等依赖，检查基础表，加载已启用插件并注册管理端路由。

参数	简写	类型	是否必填	默认值	说明
`--config`	`-c`	String	否	`config.yaml`	配置文件路径

该命令没有端口覆盖参数。如需修改监听端口，应修改对应环境的配置文件。

启动用户端服务

bash

go run . service api -c config.yaml

启动用户端 API，监听地址读取配置文件中的 server.api_addr，默认配置通常为 :8002。启动流程与管理端一致，但只注册用户端及插件用户端路由。

参数	简写	类型	是否必填	默认值	说明
`--config`	`-c`	String	否	`config.yaml`	配置文件路径

两个服务都监听 SIGINT 和 SIGTERM，收到信号后按照 server.shutdown_timeout 完成 HTTP 服务及插件生命周期的优雅停止。

查看系统版本

bash

go run . version -c config.yaml

版本号读取自配置文件顶层的 version 字段。发布时应确保配置版本、Git Tag、版本文档及插件兼容版本保持一致。

参数	简写	类型	是否必填	默认值	说明
`--config`	`-c`	String	否	`config.yaml`	配置文件路径

输出示例：

text

server_api 0.0.1

创建插件脚手架

bash

go run . plugin create example \
  --name "示例插件" \
  --author "插件作者" \
  --homepage "https://example.com/plugin" \
  --description "示例业务插件"

默认在 server_api 同级创建 go_basic_frame_plugin_<plugin_id> 独立插件仓库，生成后端、管理端、用户端子包、插件清单、数据库迁移目录及版本文档，并在 .dev 中复制一份精简核心环境用于联调。

位置参数

参数	类型	是否必填	规则	说明
`plugin_id`	String	是	以小写字母开头，只允许小写字母、数字、下划线	插件全局唯一业务标识，同时用于目录名、路由前缀和表名前缀

可选参数

参数	类型	是否必填	默认值	说明
`--name`	String	否	`plugin_id`	插件展示名称
`--author`	String	否	空	插件作者或维护者
`--homepage`	String	否	空	插件主页，必须是有效的 HTTP 或 HTTPS 地址
`--description`	String	否	自动生成	插件功能描述
`--output`	String	否	`server_api` 同级的 `go_basic_frame_plugin_<plugin_id>`	插件仓库输出目录；目录必须不存在或为空，命令不会覆盖已有代码
`--server-root`	String	否	`.`	用于复制开发环境的 `server_api` 根目录
`--admin-root`	String	否	`../admin_client`	用于复制开发环境的管理端根目录
`--user-root`	String	否	`../user_client`	用于复制开发环境的用户端根目录
`--skip-dev`	Boolean	否	`false`	只生成发行源码仓库，不复制 `.dev` 核心联调环境

生成后的常用脚本：

脚本	说明
`./scripts/dev.sh`	启动一次后持续监听三端插件源码，保存文件即自动同步至 `.dev`
`./scripts/sync-dev.sh`	手动执行一次完整同步，用于恢复或排查开发环境
`./scripts/package.sh`	按白名单生成插件 ZIP，不包含 `.dev`、核心代码及依赖目录

输出目录限制

插件仓库不能创建在任一核心项目内部，否则复制 .dev 时可能产生递归目录。插件仓库根目录是唯一正式源码，禁止直接在 .dev 中长期编写业务代码。

校验插件发行包

bash

go run . plugin validate ../go_basic_frame_plugin_news/news-v1.0.0.zip

位置参数

参数	类型	是否必填	说明
`package.zip`	File	是	待校验的插件 ZIP 发行包路径

除通用 --help 外没有额外可选参数。该命令执行只读校验，不写入源码、数据库或插件记录，主要检查：

ZIP 文件数量、大小、路径穿越和符号链接风险；
plugin.json 字段、插件标识、版本和核心版本；
三端入口文件、当前版本接口文档、数据库文档及更新说明；
菜单业务键、父子关系、页面路径和接口权限声明；
迁移文件 SHA256 以及 SQL 是否越权操作非插件表。

校验成功会输出插件标识、版本和整个发行包的 SHA256。

生成插件静态注册文件

bash

go run . plugin generate --server-root .

扫描 <server-root>/internal/plugins/ 下含有 plugin.go 的合法插件目录，重新生成 internal/plugins/register_gen.go。

参数	类型	是否必填	默认值	说明
`--server-root`	String	否	`.`	`server_api` 根目录

register_gen.go 带有 Code generated 标记，禁止手工编辑。安装、升级和移除流程会自动生成；只有手工恢复插件源码、调整插件目录或修复注册文件时才需要单独执行。

安装插件

bash

go run . plugin install ./news-v1.0.0.zip \
  --server-root . \
  --admin-root ../admin_client \
  --user-root ../user_client \
  --config config.yaml \
  --apply-database

位置参数

参数	类型	是否必填	说明
`package.zip`	File	是	首次安装的插件 ZIP 发行包

可选参数

参数	简写	类型	是否必填	默认值	说明
`--server-root`		String	否	`.`	后端核心根目录，插件后端源码安装到此项目
`--admin-root`		String	否	`../admin_client`	管理端根目录，插件管理端源码安装到此项目
`--user-root`		String	否	`../user_client`	用户端根目录，插件用户端源码安装到此项目
`--config`	`-c`	String	否	`config.yaml`	数据库配置文件
`--apply-database`		Boolean	否	`false`	执行迁移、菜单写入和插件安装记录；不传时只安装源码

不传 --apply-database 时输出中的 数据库=false 是正常状态，表示数据库尚未变更。传入该参数后，安装器使用数据库锁和事务保证迁移、菜单及插件记录的一致性。首次安装完成后插件保持停用，需要在管理端启用并重启管理端 API 与用户端 API。

升级插件

bash

go run . plugin upgrade ./news-v1.1.0.zip \
  --server-root . \
  --admin-root ../admin_client \
  --user-root ../user_client \
  -c config.yaml \
  --apply-database

升级要求插件已经安装、当前状态为停用，并且日常版本严格遵循 SemVer 递增规则。已成功执行的迁移摘要不可修改。

位置参数

参数	类型	是否必填	说明
`package.zip`	File	是	新版本插件 ZIP 发行包

可选参数

参数	简写	类型	是否必填	默认值	说明
`--server-root`		String	否	`.`	后端核心根目录
`--admin-root`		String	否	`../admin_client`	管理端根目录
`--user-root`		String	否	`../user_client`	用户端根目录
`--config`	`-c`	String	否	`config.yaml`	数据库配置文件
`--apply-database`		Boolean	否	`false`	升级时必须传入；校验版本并执行后续增量、菜单同步和版本记录

升级完成后需要重新构建前端，并重启管理端 API 与用户端 API，使新编译代码和路由生效。

可恢复移除插件

bash

go run . plugin remove news \
  --server-root . \
  --admin-root ../admin_client \
  --user-root ../user_client \
  -c config.yaml

位置参数

参数	类型	是否必填	说明
`plugin_id`	String	是	需要移除的插件唯一标识

可选参数

参数	简写	类型	是否必填	默认值	说明
`--server-root`		String	否	`.`	后端核心根目录
`--admin-root`		String	否	`../admin_client`	管理端根目录
`--user-root`		String	否	`../user_client`	用户端根目录
`--config`	`-c`	String	否	`config.yaml`	数据库配置文件

执行前要求插件已停用且不存在其他已启用插件依赖它。命令会清理角色授权、插件菜单、菜单映射和插件记录，删除三端插件源码并重新生成静态注册文件；业务表、迁移历史、安装日志和上传文件会保留，因此后续仍可重新安装恢复。命令中断后可以重复执行。

彻底清理插件

bash

go run . plugin purge news \
  --server-root . \
  --admin-root ../admin_client \
  --user-root ../user_client \
  -c config.yaml \
  --confirm news

位置参数

参数	类型	是否必填	说明
`plugin_id`	String	是	需要彻底清理的插件唯一标识

可选参数

参数	简写	类型	是否必填	默认值	说明
`--server-root`		String	否	`.`	后端核心根目录
`--admin-root`		String	否	`../admin_client`	管理端根目录
`--user-root`		String	否	`../user_client`	用户端根目录
`--config`	`-c`	String	否	`config.yaml`	数据库配置文件
`--confirm`		String	是	空	必须与位置参数中的 `plugin_id` 完全一致，防止误操作

操作不可恢复

该命令先执行可恢复移除，再删除插件业务表；全部业务表删除成功后才清理迁移历史和安装日志。检测到外部外键引用、缺少数据库引用文档或确认值不一致时会拒绝执行。上传文件不会自动删除。执行前必须完成数据库和文件备份。

生成 Shell 自动补全

bash

# Bash
go run . completion bash > server_api-completion.bash

# Zsh
go run . completion zsh > "${fpath[1]}/_server_api"

# Fish
go run . completion fish > ~/.config/fish/completions/server_api.fish

# PowerShell
go run . completion powershell > server_api.ps1

位置参数

参数	类型	是否必填	可选值	说明
`shell`	Enum	是	`bash`、`zsh`、`fish`、`powershell`	目标 Shell 类型

可选参数

参数	类型	是否必填	默认值	说明
`--no-descriptions`	Boolean	否	`false`	不在补全候选中输出命令说明；由对应 Shell 子命令提供

自动补全由 Cobra 提供，不会读取配置或操作数据库。具体加载方式取决于当前 Shell，执行 go run . completion <shell> --help 可查看对应说明。

查看指定命令帮助

以下两种写法等价：

bash

go run . help plugin upgrade
go run . plugin upgrade --help

help 后可以继续传入完整命令路径，不接受业务参数，也不会执行目标命令。

插件操作推荐顺序

text

create → 本地开发与测试 → package.sh → validate → install
                                                ↓
                                     停用 → upgrade
                                                ↓
                                      remove 或 purge

进一步阅读

插件清单、迁移原子性、升级约束、失败恢复和卸载边界，参见插件安装与更新；目录结构及编码约束参见插件开发规范。

核心数据库发布

bash

go run . database validate --sql-root sql
go run . database install --sql-root sql --config config.yaml
go run . database upgrade --sql-root sql --config config.yaml

validate 校验每个版本的全量、增量、前置版本及摘要。install 只允许空库并导入配置版本全量；upgrade 必须严格高于当前版本，按序执行后续增量。

增加版本时自动生成 SQL：

bash

go run . database release --version 0.0.2 --incremental ../changes/core.sql
go run . plugin release ../go_basic_frame_plugin_news --version 0.0.2 --incremental ../changes/news.sql
# 无数据库变化时，用 --no-database-change 替代 --incremental

两种发布命令都在隔离 MySQL 数据库中重放、导出并验证新全量，不操作业务库；增量由开发者编写并原样归档。账号需要临时库 CREATE/DROP 权限，已有版本不能覆盖。完整规则见数据库版本管理。

插件 install、upgrade、remove、purge 均支持 --wiki-root 指定文档站目录，默认为后端同级的 go_basic_frame_wiki。

服务端命令参考 ​

命令总览 ​

通用帮助参数 ​

命令分组 ​

启动管理端服务 ​

启动用户端服务 ​

查看系统版本 ​

创建插件脚手架 ​

位置参数 ​

可选参数 ​

校验插件发行包 ​

位置参数 ​

生成插件静态注册文件 ​

安装插件 ​

位置参数 ​

可选参数 ​

升级插件 ​

位置参数 ​

可选参数 ​

可恢复移除插件 ​

位置参数 ​

可选参数 ​

彻底清理插件 ​

位置参数 ​

可选参数 ​

生成 Shell 自动补全 ​

位置参数 ​

可选参数 ​

查看指定命令帮助 ​

插件操作推荐顺序 ​

核心数据库发布 ​

服务端命令参考

命令总览

通用帮助参数

命令分组

启动管理端服务

启动用户端服务

查看系统版本

创建插件脚手架

位置参数

可选参数

校验插件发行包

位置参数

生成插件静态注册文件

安装插件

位置参数

可选参数

升级插件

位置参数

可选参数

可恢复移除插件

位置参数

可选参数

彻底清理插件

位置参数

可选参数

生成 Shell 自动补全

位置参数

可选参数

查看指定命令帮助

插件操作推荐顺序

核心数据库发布