cf_Ghbf

Appearance

服务命令 ​

服务端通过 Cobra 提供统一 CLI，入口为 go run .（编译后为 ./server_api）。所有子命令一览：

命令说明
service admin启动管理端 API 服务
service api启动用户端 API 服务
version查看系统版本号
plugin validate校验插件发行包
plugin generate扫描插件目录并生成静态注册文件
plugin install安装插件发行包
plugin upgrade升级已安装插件
plugin remove可恢复移除插件
plugin purge彻底清理插件

启动服务（service admin / service api） ​

启动对应端的服务，参数：

参数说明默认
-c, --config配置文件路径config.yaml
bash
go run . service admin -c config.yaml
go run . service api   -c config.yaml

查看版本（version） ​

输出版本号，版本号来自 config.yaml 顶层 version（启动校验必填）：

参数说明默认
-c, --config配置文件路径config.yaml
bash
$ go run . version -c config.yaml
server_api v0.0.3

配置缺失或 version 未设置时返回明确错误（version 不能为空，请在配置文件中设置系统版本号）。

校验插件包（plugin validate） ​

bash
go run . plugin validate /path/news-v1.0.0.zip

校验发行包：ZIP 大小与文件数上限、路径穿越与符号链接、核心版本精确匹配、后端入口存在、菜单业务键唯一且父级存在、页面路径前缀、迁移 SHA256 一致、迁移 SQL 只操作当前插件表。校验失败不会写入任何源码或数据。

生成插件注册文件（plugin generate） ​

bash
go run . plugin generate --server-root .

扫描 internal/plugins/ 下的插件目录，自动生成注册文件 internal/plugins/register_gen.go（带 Code generated 标记，禁止手工编辑）。安装器安装/升级/移除后会自动执行；手工增删插件目录后需手动运行一次。

安装与升级插件（plugin install / plugin upgrade） ​

bash
# 安装（首次）
go run . plugin install /path/news-v1.0.0.zip \
  --server-root . \
  --admin-root ../admin_client \
  --config config.yaml \
  --apply-database

# 升级（需先停用插件并重启服务）
go run . plugin upgrade /path/news-v1.1.0.zip \
  --server-root . \
  --admin-root ../admin_client \
  --config config.yaml \
  --apply-database
参数说明默认
--server-rootserver_api 根目录.
--admin-rootadmin_client 根目录../admin_client
-c, --config数据库配置文件config.yaml
--apply-database校验后执行插件迁移、菜单和安装记录false（仅装源码）

输出说明：数据库=false 表示仅安装源码，尚未执行迁移、菜单和插件记录，需确认配置后用同一发行包重新执行并加 --apply-database；安装成功后插件默认停用状态，需在插件管理中启用并重启两端 API。

安装与升级的差异：升级要求插件已安装且停用、目标版本高于当前版本、已执行迁移的摘要不得改变。

移除插件（plugin remove） ​

bash
go run . plugin remove news \
  --server-root . \
  --admin-root ../admin_client \
  --config config.yaml

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

彻底清理插件（plugin purge） ​

bash
go run . plugin purge news \
  --server-root . \
  --admin-root ../admin_client \
  --config config.yaml \
  --confirm news
参数说明
--confirm必须填写与 plugin_id 完全一致的确认值
--server-root / --admin-root / -c同上

不可恢复：先执行可恢复移除，再删除 plg_{id}_* 业务表，全部删除成功后才清理迁移历史与安装日志。要求最新归档版本存在非空的数据库引用文档；检测到外部外键引用时拒绝执行。执行前必须备份。

完整的插件生命周期说明

安装前审查、升级规则、失败恢复与检查清单，参见插件安装与更新。