Galaxy-Sec Operator Ecosystem

-e, --env <ENV>: 环境名称，例如：-e dev（默认：default）
-d, --debug <DEBUG>: 调试级别，例如：-d 1（默认：0）
-f, --conf <CONF>: 配置文件路径，默认为：
- work: ./_rg/work.gxl
- adm: ./_rg/adm.gxl
--log <LOG>: 配置日志级别，例如：--log cmd=debug,parse=info
-q, --quiet: 静默模式
-h, --help: 显示帮助信息
-V, --version: 显示版本信息

使用示例

基本执行

# 执行默认工作流
gflow

# 执行指定流程
gflow conf test package

环境切换

# 使用开发环境
gflow -e dev

# 使用生产环境
gflow -e prod

调试模式

# 启用调试模式
gflow -d 2

# 配置详细日志
gflow --log cmd=debug,parse=info

指定配置

# 使用自定义配置文件
gflow -f ./config/my-config.gxl

配置文件

默认配置文件为：

./_rg/work.gxl - 工作流配置
./_rg/adm.gxl - 管理配置

配置文件包含：

任务定义
变量配置
模块引用
执行策略

环境变量

GALAXY_FLOW_HOME: Galaxy Flow 主目录
RUST_LOG: Rust 日志级别

gmod - Galaxy Module Management Tool

概述

gmod 是 Galaxy 模块管理工具，用于创建、更新和本地化 Galaxy 模块。它提供了完整的模块生命周期管理功能，帮助开发者快速构建和维护 Galaxy 项目。

安装

# 从源代码安装
cargo install --path .

# 或者使用二进制分发
curl -fsSL https://github.com/galaxy-sec/galaxy-ops/releases/latest/download/gmod.tar.gz | tar -xz
sudo mv gmod /usr/local/bin/

基本用法

显示版本信息

gmod
# 输出示例：gmod: 1.0.0

显示帮助信息

gmod --help
gmod <command> --help

命令详解

gmod example

创建示例模块结构

语法：

gmod example

功能：

在当前目录创建完整的示例模块结构
包含所有必需的配置文件和模板
展示模块组织的最佳实践

示例：

gmod example
# 创建示例模块到当前目录

gmod new

定义新的模块规范

语法：

gmod new [OPTIONS]

选项：

-n, --name <NAME> - 模块名称（字母数字，可包含连字符和下划线）【必填】
-d, --debug <LEVEL> - 调试级别（0-4）
- 0：关闭调试输出
- 1：基础调试信息
- 2：详细调试信息
- 3：跟踪调试信息
- 4：完整调试信息
--log <LOG> - 日志配置（格式：模块=级别,模块=级别）

功能：

创建指定名称的新模块
初始化模块目录结构
生成所有必需的配置文件

示例：

# 创建名为 "my-module" 的新模块
gmod new --name my-module

# 创建模块并启用调试输出
gmod new --name my-module --debug 2

# 创建模块并配置日志
gmod new --name my-module --log cmd=debug,parse=info

输出：

创建目录：my-module/
生成配置文件：my-module/mod.yml
生成配置文件：my-module/module.yaml
生成模板文件：my-module/templates/
生成示例文件：my-module/examples/

gmod update

更新现有模块的依赖关系

语法：

gmod update [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
--log <LOG> - 日志配置
-f, --force <LEVEL> - 强制更新级别
- 0：正常更新
- 1：跳过确认
- 2：覆盖现有文件
- 3：强制 git pull

功能：

更新模块的依赖关系
下载远程引用的模块
支持强制更新模式

示例：

# 正常更新模块
gmod update

# 强制更新，跳过确认
gmod update --force 1

# 详细调试输出更新过程
gmod update --debug 3 --log all=debug

gmod localize

本地化模块配置

语法：

gmod localize [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
--log <LOG> - 日志配置
--value <PATH> - 值文件路径（YAML/JSON）
--default - 使用默认值，不使用用户提供的 value.yml

功能：

根据环境特定的值生成本地化配置
支持多环境配置管理
可选择使用自定义或默认值

示例：

# 使用默认值本地化
gmod localize --default

# 使用自定义值文件本地化
gmod localize --value prod-values.yml

# 使用自定义值文件并启用调试
gmod localize --value dev-values.yml --debug 2

环境变量

TEST_MODE - 测试模式设置
MOCK_SUCCESS - 模拟成功状态

配置文件

模块配置结构

my-module/
├── mod.yml                    # 模块主配置文件
├── module.yaml               # 模块元数据
├── templates/                # 模板目录
├── examples/                # 示例文件
└── config/                  # 配置文件
    ├── default.yml          # 默认配置
    ├── local.yml            # 本地配置
    └── env/                  # 环境特定配置
        ├── dev.yml
        ├── staging.yml
        └── prod.yml

mod.yml 示例

name: my-module
version: "1.0.0"
description: "My Galaxy Module"
author: "Your Name <your.email@example.com>"

dependencies:
  - galaxy/core: ">=1.0.0"
  - galaxy/utils: "~2.0.0"

sources:
  - type: git
    url: "https://github.com/username/my-module.git"
    ref: main

outputs:
  - name: main
    path: "build/output"
    format: tar.gz

最佳实践

模块命名

使用小写字母、数字、连字符和下划线
避免特殊字符和空格
使用有意义的名称，如：user-service-api

依赖管理

使用语义化版本控制
定期更新依赖：gmod update --force 1
在生产环境使用锁定版本

调试技巧

# 启用完整调试输出
gmod update --debug 4 --log all=debug

# 检查模块依赖关系
gmod new --name debug-test --debug 2

# 使用详细日志进行故障排除
gmod localize --debug 3 --log cmd=debug,net=trace

故障排除

常见问题

Q: 创建模块失败

错误：无法创建目录 "my-module"
原因：目录已存在或权限不足
解决：删除现有目录或检查权限

Q: 更新模块时网络错误

错误：无法下载依赖
解决：检查网络连接和 git 配置
gmod update --debug 3 --log net=debug

Q: 本地化失败

错误：无法解析值文件
解决：检查 YAML/JSON 格式是否正确
gmod localize --value config.yml --debug 2

调试模式

使用调试模式获取详细的执行信息：

# 最高级别调试
gmod update --debug 4 --log all=debug

# 关键模块调试
gmod new --name test --debug 3 --log cmd=debug

测试

项目包含完整的测试套件：

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_gxmod_cmd_app_creation

# 运行测试并显示输出
cargo test -- --nocapture

示例工作流

开发新模块

# 1. 创建新模块
gmod new --name user-service

# 2. 编辑模块配置
cd user-service
vim mod.yml

# 3. 开发功能
# ... 编码 ...

# 4. 更新依赖
cd ..
gmod update

# 5. 本地化配置
gmod localize --value dev-values.yml

# 6. 验证模块
gmod example

部署到生产环境

# 1. 创建生产模块
gmod new --name user-service-prod

# 2. 更新到最新版本
gmod update --force 3

# 3. 使用生产配置本地化
gmod localize --value prod-values.yml

# 4. 验证配置
ls -la user-service-prod/config/env/prod.yml

贡献指南

欢迎贡献代码和建议：

Fork 项目（https://github.com/galaxy-sec/galaxy-ops）
创建特性分支
提交更改
推送到分支
创建 Pull Request

gops - Galaxy Operations System 系统操作管理工具

概述

gops 是 Galaxy Operations System 的核心管理工具，用于管理系统配置、导入模块、更新引用等操作。它提供了完整的系统操作功能，帮助开发者高效地管理 Galaxy 系统的各种配置和操作。

安装

# 从源代码安装
cargo install --path .

# 或者使用二进制分发
https://github.com/galaxy-sec/galaxy-ops/releases/latest/

基本用法

显示版本信息

gops
# 输出示例：gops: 1.0.0

显示帮助信息

gops --help
gops <command> --help

命令详解

gops new

创建新的系统配置

语法：

gops new [OPTIONS]

选项：

-n, --name <NAME> - 系统配置名称（必填）
- 系统配置的唯一标识名称
- 支持字母数字、连字符和下划线
- 必须为非空字符串

功能：

创建指定名称的新系统配置
初始化系统配置目录结构
生成所有必需的配置文件
设置默认的系统配置参数

示例：

# 创建名为 "my-config" 的新系统配置
gops new --name my-config

# 创建带详细调试的系统配置
gops new --name debug-config --debug 2

输出：

创建目录：my-config/
生成配置文件：my-config/ops_config.yml
生成模板文件：my-config/templates/
生成示例文件：my-config/examples/
生成脚本文件：my-config/scripts/

gops import

导入外部模块到当前系统

语法：

gops import [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
- 0：关闭调试输出
- 1：基础调试信息
- 2：详细调试信息
- 3：跟踪调试信息
- 4：完整调试信息
--log <LOG> - 日志配置（格式：模块=级别,模块=级别）
-f, --force <LEVEL> - 强制更新级别
- 0：不强制更新
- 1：强制更新引用
- 2：强制更新依赖
- 3：强制更新所有内容
-p, --path <PATH> - 模块导入路径（必填）
- 可以是相对路径或绝对路径
- 指定要导入的模块所在位置

功能：

从指定路径导入模块配置
将模块集成到当前系统
自动处理模块依赖关系
支持强制导入模式

示例：

# 从指定路径导入模块
gops import --path /path/to/module

# 跳过确认导入
gops import --path /path/to/module --force 1

# 详细调试导入过程
gops import --path /path/to/module --debug 3 --log import=debug

# 强制更新所有内容
gops import --path /path/to/module --force 3

gops update

更新系统模块和引用

语法：

gops update [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
--log <LOG> - 日志配置
-f, --force <LEVEL> - 强制更新级别
- 0：不强制更新
- 1：强制更新引用
- 2：强制更新依赖
- 3：强制更新所有内容

功能：

更新系统模块的引用关系
更新模块的依赖配置
下载远程资源引用
支持多种强制更新模式

示例：

# 正常更新系统
gops update

# 强制更新引用
gops update --force 1

# 详细调试更新过程
gops update --debug 3 --log all=debug

gops localize

本地化模块配置

语法：

gops localize [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
--log <LOG> - 日志配置
--value <PATH> - 本地化值文件路径
- 指定用于本地化的值文件路径
- 通常是 YAML 格式的配置文件
--default - 使用默认模块配置
- 启用默认模块模式
- 不使用用户自定义的 value.yml 文件

功能：

根据环境特定的值本地化模块配置
适配不同环境的配置需求
支持多环境配置管理
可选择使用自定义或默认值

示例：

# 使用默认配置本地化
gops localize --default

# 使用自定义值文件本地化
gops localize --value prod-values.yml

# 使用自定义值文件并启用调试
gops localize --value dev-values.yml --debug 2

注意： 目前 gops localize 命令实现为 todo!()，功能尚未完成。

gops setting

系统设置管理

语法：

gops setting [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
--log <LOG> - 日志配置
- 格式：模块=级别,模块=级别
- 例如：--log setting=debug,system=info

功能：

管理系统级别的配置设置
查看和修改系统配置参数
提供系统状态信息
支持调试和日志配置

示例：

# 查看系统设置
gops setting

# 启用调试输出查看设置
gops setting --debug 2

# 配置日志级别查看设置
gops setting --log setting=debug,system=info

环境变量

TEST_MODE - 测试模式设置
MOCK_SUCCESS - 模拟成功状态
TEST_MODE 和 MOCK_SUCCESS 用于测试环境，确保测试的安全性和隔离性

配置文件

系统配置结构

my-config/
├── ops_config.yml              # 系统主配置文件
├── templates/                  # 模板目录
├── examples/                  # 示例文件
├── scripts/                   # 脚本文件
├── modules/                   # 模块目录
├── config/                    # 配置文件
│   ├── default.yml           # 默认配置
│   ├── local.yml             # 本地配置
│   └── env/                  # 环境特定配置
│       ├── dev.yml
│       ├── staging.yml
│       └── prod.yml
└── settings/                  # 系统设置
    ├── system.yml
    ├── security.yml
    └── performance.yml

ops_config.yml 示例

# 系统配置文件
system_name: my-ops-system
version: "1.0.0"
description: "My Galaxy Operations System"

# 模块配置
modules:
  - name: core
    type: system
    version: "1.0.0"
  - name: database
    type: external
    path: "/path/to/database-module"
    version: "2.1.0"

# 依赖配置
dependencies:
  - galaxy/core: ">=1.0.0"
  - galaxy/utils: "~2.0.0"
  - galaxy/security: "^1.5.0"

# 导入配置
imports:
  - name: user-service
    path: "/path/to/user-service"
    version: "1.2.0"

# 输出配置
outputs:
  - name: artifacts
    path: "build/artifacts"
    format: tar.gz

# 系统设置
settings:
  debug_level: 1
  log_level: info
  auto_update: true

最佳实践

配置命名

使用小写字母、数字、连字符和下划线
避免特殊字符和空格
使用有意义的名称，如：production-config
区分环境和用途：dev-api-config

模块管理

# 导入新模块
gops import --path /path/to/new-module --force 1

# 更新现有模块
gops update --force 2

# 验证配置
gops setting --debug 2

配置管理

# 开发环境配置
gops localize --value dev-config.yml --debug 2

# 测试环境配置
gops localize --value test-config.yml

# 生产环境配置
gops localize --value prod-config.yml --default

调试技巧

# 启用完整调试输出
gops import --path /test --debug 4 --log all=debug

# 检查系统设置
gops setting --debug 3 --log setting=debug

# 使用详细日志进行故障排除
gops update --debug 2 --log cmd=debug,net=trace

故障排除

常见问题

Q: 创建配置失败

错误：无法创建目录 "my-config"
原因：目录已存在或权限不足
解决：删除现有目录或检查权限

Q: 导入模块失败

错误：无法导入模块
原因：路径不存在或权限不足
解决：检查路径是否正确，确保有读取权限
gops import --path /test/path --debug 3 --log import=debug

Q: 更新模块时网络错误

错误：无法下载依赖
解决：检查网络连接和 git 配置
gops update --debug 3 --log net=debug

Q: 本地化功能未实现

错误：localize 功能尚未完成
原因：当前版本实现为 todo!()
解决：等待后续版本支持，或使用其他配置管理方式

调试模式

使用调试模式获取详细的执行信息：

# 最高级别调试
gops import --path /test --debug 4 --log all=debug

# 关键模块调试
gops new --name test --debug 3 --log cmd=debug

# 设置调试
gops setting --debug 2 --log setting=debug

系统诊断

# 检查配置文件
ls -la my-config/

# 验证系统配置
cat my-config/ops_config.yml

# 检查模块目录
ls -la my-config/modules/

# 查看系统设置
gops setting --debug 1

测试

项目包含完整的测试套件：

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_gxops_run_success

# 运行测试并显示输出
cargo test -- --nocapture

# 测试环境隔离
TEST_MODE=true cargo test

示例工作流

开发新系统

# 1. 创建新系统配置
gops new --name my-ops-system

# 2. 导入外部模块
gops import --path /path/to/user-service --force 1

# 3. 导入数据库模块
gops import --path /path/to/database-module --force 2

# 4. 更新系统模块
gops update

# 5. 查看系统设置
gops setting --debug 1

# 6. 本地化配置（功能待实现）
gops localize --value dev-config.yml

部署到生产环境

# 1. 创建生产系统配置
gops new --name production-system

# 2. 导入生产模块
gops import --path /path/to/production-modules --force 3

# 3. 更新到最新版本
gops update --force 3

# 4. 查看生产设置
gops setting --log production=debug

# 5. 使用生产配置本地化
gops localize --value prod-config.yml --default

版本历史

当前版本：1.0.0

初始版本
支持系统配置创建
支持模块导入功能
支持系统模块更新
支持系统设置管理
本地化功能标记为待实现（todo!()）
完整的错误处理和日志记录

功能开发状态

功能	状态	说明
new	✅ 完成	创建新的系统配置
import	✅ 完成	导入外部模块到当前系统
update	✅ 完成	更新系统模块和引用
localize	⏳ 待开发	本地化模块配置（当前为 todo!()）
setting	✅ 完成	系统设置管理

贡献指南

欢迎贡献代码和建议：

Fork 项目
创建特性分支
提交更改
推送到分支
创建 Pull Request

gprj 命令使用文档

概述

gprj 是 Galaxy Flow 的项目管理工具，用于初始化和管理 Galaxy 项目环境。

基本用法

gprj <COMMAND> [OPTIONS]

命令列表

1. init - 初始化命令

用于初始化 Galaxy 环境和项目。

init prj-with-local - 使用本地模块初始化项目

gprj init prj-with-local

创建新项目并使用本地模块作为依赖。

init prj - 使用远程模板初始化项目

gprj init prj [OPTIONS]

参数

--tpl <TPL>: 选择模板名称（默认：simple）
- 可选值：simple, open_pages, rust_prj 等
--branch <BRANCH>: 指定模板仓库分支
--tag <TAG>: 指定模板仓库标签
- 可选值：alpha, develop, beta, release/1.0
--repo <REPO>: 模板仓库地址（默认：https://gal-tpl.git）
-d, --debug <DEBUG>: 调试级别（默认：0）
--log <LOG>: 日志配置
-p, --cmd-print: 打印执行的命令

示例

# 使用默认模板初始化
gprj init prj

# 使用特定模板
gprj init prj --tpl rust_prj

# 使用特定分支
gprj init prj --branch develop

# 使用特定标签
gprj init prj --tag release/1.0

2. update - 更新命令

用于更新项目模块。

update mod - 更新模块

gprj update mod [OPTIONS]

参数

-d, --debug <DEBUG>: 调试级别（默认：0）
-f, --conf-work <CONF_WORK>: 工作配置文件（默认：./_gal/work.gxl）
--conf-adm <CONF_ADM>: 管理配置文件（默认：./_gal/adm.gxl）
--log <LOG>: 日志配置
-q, --quiet: 静默模式（默认：true）

示例

# 更新模块
gprj update mod

# 使用自定义配置更新
gprj update mod -f ./config/work.gxl

3. conf - 配置管理

用于管理配置文件。

conf init - 初始化配置

gprj conf init [OPTIONS]

示例

# 初始化本地配置
gprj conf init

# 初始化远程配置
gprj conf init --remote

4. check - 检查命令

检查当前项目配置和环境。

gprj check

5. adm - 管理命令

执行管理任务，等同于 gflow 的管理模式。

gprj adm [OPTIONS]

配置文件

默认配置文件

./_gal/work.gxl - 工作流配置
./_gal/adm.gxl - 管理配置
./_gal/head.gxl - 头部配置

使用流程

1. 初始化新项目

# 1. 初始化环境
gprj init env

# 2. 初始化项目
gprj init prj --tpl simple

# 3. 检查配置
gprj check

2. 更新项目

# 更新所有模块
gprj update mod

# 使用自定义配置更新
gprj update mod -f ./my-config.gxl

3. 配置管理

# 初始化配置
gprj conf init

# 使用远程配置
gprj conf init --remote

模板仓库

默认模板仓库

地址：https://gal-tpl.git
包含模板：simple, open_pages, rust_prj 等

自定义模板仓库

gprj init prj --repo https://my-tpl.git --tpl my-template

环境变量

GALAXY_FLOW_HOME: Galaxy Flow 主目录
RUST_LOG: Rust 日志级别

常见问题

权限问题

确保有执行权限：

chmod +x gprj

配置冲突

如果配置文件已存在，先备份再重新初始化：

mv _gal/work.gxl _gal/work.gxl.backup
gprj conf init

最佳实践

项目初始化

先初始化环境：gprj init env
选择合适的模板：gprj init prj --tpl <template>
检查配置：gprj check
更新模块：gprj update mod

团队协作

使用统一的模板仓库
定期更新模块：gprj update mod
使用版本控制管理配置文件

gsys - Galaxy System Management Tool

概述

gsys 是 Galaxy 系统管理工具，用于创建、更新和本地化 Galaxy 系统配置。它提供了完整的系统生命周期管理功能，帮助开发者快速构建和维护 Galaxy 系统。

安装

# 从源代码安装
cargo install --path .

# 或者使用二进制分发
https://github.com/galaxy-sec/galaxy-ops/releases/latest/

基本用法

显示版本信息

gsys
# 输出示例：gsys: 1.0.0

显示帮助信息

gsys --help
gsys <command> --help

命令详解

gsys new

创建新的系统操作符

语法：

gsys new [OPTIONS]

选项：

-n, --name <NAME> - 系统名称（字母数字，可包含连字符和下划线）【必填】

功能：

创建指定名称的新系统
初始化系统目录结构
生成所有必需的配置文件
交互式选择系统型号配置

示例：

# 创建名为 "my-system" 的新系统
gsys new --name my-system

# 创建系统时交互式选择系统型号
# 系统会提示：请选择系统型号配置:
# 1. ModelSTD_1
# 2. ModelSTD_2
# ...
# 选择完成后会自动生成对应的配置文件

输出：

创建目录：my-system/
生成配置文件：my-system/sys/sys_model.yml
生成模板文件：my-system/templates/
生成示例文件：my-system/examples/

gsys update

更新现有系统配置

语法：

gsys update [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
- 0：关闭调试输出
- 1：基础调试信息
- 2：详细调试信息
- 3：跟踪调试信息
- 4：完整调试信息
--log <LOG> - 日志配置（格式：模块=级别,模块=级别）
-f, --force <LEVEL> - 强制更新级别
- 0：正常更新
- 1：跳过确认
- 2：覆盖文件
- 3：强制 git pull

功能：

更新系统的配置和依赖关系
下载远程引用的系统资源
支持多种强制更新模式
自动处理系统版本冲突

示例：

# 正常更新系统
gsys update

# 跳过确认更新
gsys update --force 1

# 详细调试输出更新过程
gsys update --debug 3 --log all=debug

# 完整强制更新
gsys update --force 3 --debug 4

gsys localize

本地化系统配置

语法：

gsys localize [OPTIONS]

选项：

-d, --debug <LEVEL> - 调试级别（0-4）
--log <LOG> - 日志配置
--value <PATH> - 值文件路径（YAML/JSON）
--default - 使用内置默认值，不使用用户提供的 value.yml

功能：

根据环境特定的值生成本地化配置
支持多环境配置管理
可选择使用自定义或默认值
自动生成环境特定的配置文件

示例：

# 使用默认值本地化
gsys localize --default

# 使用自定义值文件本地化
gsys localize --value prod-values.yml

# 使用自定义值文件并启用调试
gsys localize --value dev-values.yml --debug 2

# 使用详细日志进行本地化
gsys localize --value staging-values.yml --log cmd=debug,localize=info

系统型号配置

支持的系统型号

gsys 支持多种系统型号配置，可通过以下方式查看：

# 查看所有支持的系统型号
python3 -c "from galaxy_ops.module import ModelSTD; print('\n'.join(str(m) for m in ModelSTD.support()))"

系统型号选择

在创建新系统时，gsys 会交互式提示选择系统型号：

请选择系统型号配置:
1. ModelSTD_AWS
2. ModelSTD_Docker
3. ModelSTD_Kubernetes
4. ModelSTD_BareMetal
5. 从当前系统自动检测
请输入选项编号 [1-5]:

当前系统检测

如果选择"从当前系统自动检测"，gsys 会自动检测当前运行环境并生成对应的配置：

# 自动检测当前系统
ModelSTD::from_cur_sys()  # 内部调用的方法

环境变量

TEST_MODE - 测试模式设置
MOCK_SUCCESS - 模拟成功状态
TEST_MODE 和 MOCK_SUCCESS 用于测试环境，确保测试的安全性和隔离性

配置文件

系统配置结构

my-system/
├── sys/                       # 系统配置目录
│   ├── sys_model.yml          # 系统型号配置
│   ├── dependencies.yml      # 依赖配置
│   └── config/               # 系统配置
│       ├── default.yml        # 默认配置
│       ├── local.yml          # 本地配置
│       └── env/               # 环境特定配置
│           ├── dev.yml
│           ├── staging.yml
│           └── prod.yml
├── templates/                 # 模板目录
├── examples/                 # 示例文件
├── scripts/                  # 脚本文件
└── deployment/               # 部署配置
    ├── docker/
    ├── kubernetes/
    └── terraform/

sys_model.yml 示例

# AWS 系统型号配置
system_name: my-aws-system
model: ModelSTD_AWS
version: "1.0.0"

# 基础配置
base_config:
  region: us-east-1
  availability_zones:
    - us-east-1a
    - us-east-1b
    - us-east-1c

# 计算资源
compute:
  type: auto_scaling
  min_size: 2
  max_size: 10
  desired_capacity: 3
  instance_type: t3.large

# 存储配置
storage:
  type: ebs
  volume_size: 100
  volume_type: gp3
  encrypted: true

# 网络配置
network:
  vpc_cidr: "10.0.0.0/16"
  subnet_cidrs:
    - "10.0.1.0/24"
    - "10.0.2.0/24"
    - "10.0.3.0/24"

# 安全配置
security:
  enable_vpc: true
  enable_security_groups: true
  enable_iam: true

Docker 系统型号配置

# Docker 系统型号配置
system_name: my-docker-system
model: ModelSTD_Docker
version: "1.0.0"

# 容器配置
containers:
  - name: main
    image: "my-app:latest"
    ports:
      - "8080:80"
    environment:
      - NODE_ENV=production
    volumes:
      - "/opt/app/data:/app/data"

# 网络配置
networks:
  - name: app-network
    driver: bridge
    internal: false

# 数据卷配置
volumes:
  - name: app-data
    driver: local

最佳实践

系统命名

使用小写字母、数字、连字符和下划线
避免特殊字符和空格
使用有意义的名称，如：production-web-app
区分环境和用途：dev-api-gateway

系统型号选择

# AWS 环境
gsys new --name aws-ecommerce -- 选择 ModelSTD_AWS

# Docker 环境
gsys new --name docker-microservices -- 选择 ModelSTD_Docker

# Kubernetes 环境
gsys new --name k8s-monitoring -- 选择 ModelSTD_Kubernetes

# 裸金属服务器
gsys new --name bare-metal-database -- 选择 ModelSTD_BareMetal

依赖管理

定期更新系统依赖：gsys update --force 1
在生产环境使用锁定版本
使用版本控制管理配置变更

配置管理

# 开发环境配置
gsys localize --value dev-config.yml --log cmd=debug

# 测试环境配置
gsys localize --value test-config.yml

# 生产环境配置
gsys localize --value prod-config.yml --default

故障排除

常见问题

Q: 创建系统失败

错误：无法创建目录 "my-system"
原因：目录已存在或权限不足
解决：删除现有目录或检查权限

Q: 系统型号选择失败

错误：无法解析系统型号
解决：检查系统型号配置文件是否正确
gsys new --name test-system -- 选择 1

Q: 更新系统时网络错误

错误：无法下载依赖
解决：检查网络连接和 git 配置
gsys update --debug 3 --log net=debug

Q: 本地化失败

错误：无法解析值文件
解决：检查 YAML/JSON 格式是否正确
gsys localize --value config.yml --debug 2

调试模式

使用调试模式获取详细的执行信息：

# 最高级别调试
gsys update --debug 4 --log all=debug

# 关键模块调试
gsys new --name test --debug 3 --log cmd=debug

# 网络调试
gsys update --debug 3 --log net=debug

系统诊断

# 检查系统配置
ls -la my-system/sys/

# 验证系统型号配置
cat my-system/sys/sys_model.yml

# 检查环境配置
ls -la my-system/sys/config/env/

测试

项目包含完整的测试套件：

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_gxsys_run_success

# 运行测试并显示输出
cargo test -- --nocapture

# 测试环境隔离
TEST_MODE=true cargo test

示例工作流

开发新系统

# 1. 创建新系统
gsys new --name my-system

# 2. 选择系统型号（交互式）
# 输入编号选择对应的系统型号

# 3. 编辑系统配置
cd my-system
vim sys/sys_model.yml

# 4. 更新系统资源
cd ..
gsys update

# 5. 本地化配置
gsys localize --value dev-config.yml

# 6. 验证系统配置
ls -la my-system/sys/config/env/

部署到生产环境

# 1. 创建生产系统
gsys new --name production-system

# 2. 选择生产环境系统型号
# 根据实际情况选择 AWS/Docker/K8s 等

# 3. 更新到最新版本
gsys update --force 3

# 4. 使用生产配置本地化
gsys localize --value prod-config.yml --default

# 5. 验证生产配置
cat my-system/sys/config/env/prod.yml

版本历史

当前版本：1.0.0

初始版本
支持系统创建、更新和本地化
交互式系统型号选择
多种系统型号支持（AWS、Docker、Kubernetes、BareMetal）
完整的错误处理和日志记录

贡献指南

欢迎贡献代码和建议：

Fork 项目
创建特性分支
提交更改
推送到分支
创建 Pull Request

BUILDIN

维护器

系统维护器

系统模型配置

概述

sys_model.yml 是 Sys-Operator 中最重要的配置文件之一，定义了系统的基础信息、目标运行环境和扩展元数据。所有系统都必须包含这个文件，它是系统定义的核心。

配置结构

基础系统定义

# 必需字段
name: system_name                    # 系统名称（必需）
model: arm-mac14-host               # 目标平台模型（必需）
vender: "Galaxy-Ops"                # 厂商信息（可选）

字段详解

1. `name` - 系统名称

类型: string 必需: 是 描述: 系统的唯一标识名称

规范:

使用小写字母
单词间用下划线分隔
避免特殊字符和空格
长度建议不超过 64 个字符
避免使用保留关键字

示例:

# 好的示例
name: production_web_system
name: microservice_platform
name: database_cluster

# 避免的示例
name: Production Web System  # 包含空格
name: prod_web_system$      # 包含特殊字符
name: sys_1                 # 无意义的编号

2. `model` - 目标平台模型

类型: string 必需: 是 描述: 系统运行的目标平台和环境

格式: arch-os-spc

组成部分:

架构 (arch):
- arm: ARM 架构（Apple M1/M2, Raspberry Pi 等）
- x86: x86-64 架构（Intel/AMD）
- amd64: AMD64 架构（兼容 x86-64）
- aarch64: ARM64 架构
操作系统 (os):
- mac14: macOS 14.x
- ubt22: Ubuntu 22.04 LTS
环境 (spc):
- host: 宿主机环境
- k8s: Kubernetes 环境

示例:

# Apple M1 芯片，macOS 14，Host 模式
model: arm-mac14-host

# Intel x86，Ubuntu 22.04，Kubernetes 模式
model: x86-ubt22-k8s

# Intel x86，Ubuntu 22.04，Docker 容器模式
model: x86-ubt22-docker

3. `vender` - 厂商信息

类型: string 必需: 否 描述: 系统的厂商、组织或开发者信息

用途:

标识系统来源
版本管理和发布
技术支持联系
生态系统分类

示例:

vender: "Galaxy-Ops"
vender: "Enterprise Corp"
vender: "Open Source Community"
vender: "Development Team"

最佳实践

1. 命名最佳实践

系统命名建议

使用描述性名称，清晰表达系统功能
包含环境标识（如 production_, staging_, dev_）
避免使用版本号（使用 metadata.version 管理）
保持命名一致性

示例:

# 好的命名
name: production_web_system
name: staging_api_gateway
name: dev_database_cluster
name: monitoring_platform

# 避免的命名
name: web_system_prod      # 环境标识分离
name: sys_v2               # 版本号分离
name: app1                 # 无意义的编号

版本管理建议

使用语义化版本
使用 metadata.version 而非文件名
考虑使用标签和分支管理版本

3. 模型选择建议

环境区分

使用不同的模型区分开发和生产环境
考虑容器化 vs 宿主机部署的差异
支持混合环境部署需求

故障排除

1. 常见错误

缺少必需字段

# 错误示例
# 缺少 name 字段
model: x86-ubt22-host
vender: "Example Corp"

# 缺少 model 字段
name: example_system
vender: "Example Corp"

模型格式错误

# 错误示例
model: arm-mac-14-host    # 分隔符错误
model: x86-ubuntu-22-host # 操作系统名称错误
model: arm-mac14-docker  # 不支持的环境

命名格式错误

# 错误示例
name: Production System  # 包含空格
name: system$1           # 包含特殊字符
name: SYSTEM_NAME        # 包含大写字母

总结

sys_model.yml 是系统配置的核心文件，定义了系统的基础信息和运行环境。理解各个字段的含义和规范对于正确配置系统至关重要：

name: 系统的唯一标识，必须规范命名
model: 目标平台环境，格式必须正确
vender: 厂商信息，用于标识系统来源

遵循这些配置规范和最佳实践，可以：

提高配置的可读性和维护性
确保系统在不同环境中的正确部署
支持系统的版本管理和生命周期管理
便于团队协作和知识共享

建议在使用过程中：

定期验证配置文件的正确性
保持命名和格式的一致性

微服务系统示例

概述

本文档提供了一个完整的微服务系统示例，展示如何使用 Sys-Operator 构建和管理复杂的微服务架构。该示例包含 Web 前端、API 网关、用户服务、订单服务和数据库等多个模块，体现了现代微服务系统的典型架构模式。

系统架构

整体架构图

graph TB
    subgraph "客户端层"
        A[Web浏览器]
        B[移动应用]
        C[API客户端]
    end

    subgraph "接入层"
        D[Nginx Ingress]
        E[API Gateway]
    end

    subgraph "业务服务层"
        F[用户服务]
        G[订单服务]
        H[支付服务]
        I[通知服务]
    end

    subgraph "数据层"
        J[PostgreSQL主库]
        K[PostgreSQL从库]
        L[Redis缓存]
    end

    subgraph "基础设施层"
        M[Kubernetes集群]
        N[监控系统]
        O[日志系统]
    end

    A --> D
    B --> D
    C --> E

    D --> E
    E --> F
    E --> G
    E --> H
    E --> I

    F --> J
    G --> J
    H --> J
    I --> L

    J --> K
    J --> L

    F --> M
    G --> M
    H --> M
    I --> M

    M --> N
    M --> O

服务依赖关系

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   用户服务      │───▶│   订单服务      │───▶│   支付服务      │
│ (UserService)   │    │ (OrderService)  │    │ (PaymentService) │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   PostgreSQL    │    │   PostgreSQL    │    │   PostgreSQL    │
│    主库         │    │    主库         │    │    主库         │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Redis缓存    │    │    Redis缓存    │    │    Redis缓存    │
│ (用户会话)      │    │ (订单状态)      │    │ (支付状态)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

系统配置

1. 系统模型定义 (`sys/sys_model.yml`)

# 系统基本信息
name: microservice_platform
model: x86-ubt22-k8s
vender: "TechCorp"


### 2. 模块列表配置 (`sys/mod_list.yml`)

```yaml
# 接入层模块
- name: nginx_ingress
  addr:
    repo: https://github.com/galaxy-operators/nginx
    tag: v1.25.3
  model: x86-ubt22-k8s
  enable: true


- name: api_gateway
  addr:
    repo: https://github.com/galaxy-operators/api-gateway
    tag: v3.0.0
  model: x86-ubt22-k8s
  enable: true
  priority: 90


# 用户服务模块
- name: user_service
  addr:
    repo: https://github.com/techcorp/user-service
    tag: v4.1.0
  model: x86-ubt22-k8s
  enable: true
  priority: 80


# 订单服务模块
- name: order_service
  addr:
    repo: https://github.com/techcorp/order-service
    tag: v3.5.0
  model: x86-ubt22-k8s
  enable: true


# 支付服务模块
- name: payment_service
  addr:
    repo: https://github.com/techcorp/payment-service
    tag: v2.8.0
  model: x86-ubt22-k8s
  enable: true


# 通知服务模块
- name: notification_service
  addr:
    repo: https://github.com/techcorp/notification-service
    tag: v1.6.0
  model: x86-ubt22-k8s



# 数据库模块
- name: postgres_primary
  addr:
    repo: https://github.com/galaxy-operators/postgresql-ha
    tag: v15.5.0
  model: x86-ubt22-k8s
  enable: true


- name: postgres_readonly
  addr:
    repo: https://github.com/galaxy-operators/postgresql-ha
    tag: v15.5.0
  model: x86-ubt22-k8s
  enable: true


# 缓存模块
- name: redis_cache
  addr:
    repo: https://github.com/galaxy-operators/redis-ha
    tag: v7.2.4
  model: x86-ubt22-k8s
  enable: true


# 外部服务模块
- name: external_payment_gateway
  addr:
    path: ./external-gateways/payment-gateway
  model: x86-ubt22-k8s


# 监控模块
- name: monitoring_stack
  addr:
    repo: https://github.com/galaxy-operators/enterprise-monitoring
    tag: v2.5.0
  model: x86-ubt22-k8s
  enable: true

3. 系统变量配置 (`sys/vars.yml`)

# 系统配置
vars:
# 环境配置
- name: ENVIRONMENT
  value: "production"
  description: "部署环境"

- name: CLUSTER_NAME
  value: "${CLUSTER_NAME:production-cluster}"
  description: "Kubernetes集群名称"


- name: NAMESPACE
  value: "${NAMESPACE:microservices}"
  description: "Kubernetes命名空间"


# 应用配置
- name: APP_VERSION
  value: "2.3.0"
  description: "应用版本"


- name: DOMAIN_NAME
  value: "${DOMAIN_NAME:platform.techcorp.com}"
  description: "系统域名"


- name: BASE_URL
  value: "https://${DOMAIN_NAME}"
  description: "基础URL"


# 安全配置
- name: ENABLE_MTLS
  value: "${ENABLE_MTLS:true}"
  description: "启用双向TLS"
  type: boolean
  group: security

- name: API_RATE_LIMIT
  value: "${API_RATE_LIMIT:1000}"
  description: "API速率限制"
  type: integer
  min: 1
  max: 10000
  group: security

- name: SESSION_TIMEOUT_MINUTES
  value: "${SESSION_TIMEOUT_MINUTES:30}"
  description: "会话超时时间"
  type: integer
  min: 5
  max: 1440


# 数据库配置
- name: DATABASE_BACKUP_SCHEDULE
  value: "${DATABASE_BACKUP_SCHEDULE:0 1 * * *}"
  description: "数据库备份计划"


- name: DATABASE_RETENTION_DAYS
  value: "${DATABASE_RETENTION_DAYS:30}"
  description: "数据保留天数"
  type: integer
  min: 7
  max: 365


- name: CONNECTION_POOL_SIZE
  value: "${CONNECTION_POOL_SIZE:20}"
  description: "连接池大小"
  type: integer
  min: 1
  max: 100


# 缓存配置
- name: CACHE_DEFAULT_TTL
  value: "${CACHE_DEFAULT_TTL:3600}"
  description: "默认缓存TTL（秒）"
  type: integer
  min: 60
  max: 86400


- name: CACHE_MAX_SIZE
  value: "${CACHE_MAX_SIZE:10000}"
  description: "缓存最大条目数"
  type: integer
  min: 100
  max: 100000


- name: CACHE_REFRESH_INTERVAL
  value: "${CACHE_REFRESH_INTERVAL:300}"
  description: "缓存刷新间隔（秒）"
  type: integer
  min: 60
  max: 3600
  group: cache

# 消息队列配置
- name: MESSAGE_QUEUE_MAX_RETRIES
  value: "${MESSAGE_QUEUE_MAX_RETRIES:3}"
  description: "消息队列最大重试次数"
  type: integer
  min: 1
  max: 10
  group: messaging

- name: MESSAGE_QUEUE_DELAY_SECONDS
  value: "${MESSAGE_QUEUE_DELAY_SECONDS:60}"
  description: "消息队列重试延迟"
  type: integer
  min: 10
  max: 3600


# 高可用配置
- name: HIGH_AVAILABILITY_ENABLED
  value: "${HIGH_AVAILABILITY_ENABLED:true}"
  description: "启用高可用"
  type: boolean
  group: ha

- name: HEALTH_CHECK_INTERVAL_SECONDS
  value: "${HEALTH_CHECK_INTERVAL_SECONDS:30}"
  description: "健康检查间隔"
  type: integer
  min: 10
  max: 300

- name: FAILURE_DETECTION_SECONDS
  value: "${FAILURE_DETECTION_SECONDS:60}"
  description: "故障检测时间"
  type: integer
  min: 30
  max: 300
  group: ha

- name: AUTO_FAILOVER_ENABLED
  value: "${AUTO_FAILOVER_ENABLED:true}"
  description: "启用自动故障转移"
  type: boolean


# 性能配置
- name: DEFAULT_REPLICAS
  value: "${DEFAULT_REPLICAS:2}"
  description: "默认副本数"
  type: integer
  min: 1
  max: 10


- name: MAX_REPLICAS
  value: "${MAX_REPLICAS:10}"
  description: "最大副本数"
  type: integer
  min: 1
  max: 100


- name: CPU_REQUEST
  value: "${CPU_REQUEST:100m}"
  description: "CPU请求值"


- name: MEMORY_REQUEST
  value: "${MEMORY_REQUEST:256Mi}"
  description: "内存请求值"


- name: CPU_LIMIT
  value: "${CPU_LIMIT:2000m}"
  description: "CPU限制值"


- name: MEMORY_LIMIT
  value: "${MEMORY_LIMIT:4Gi}"
  description: "内存限制值"


# 监控配置
- name: MONITORING_ENABLED
  value: "${MONITORING_ENABLED:true}"
  description: "启用监控"
  type: boolean
  group: monitoring

- name: ALERT_EMAIL_RECIPIENTS
  value: "${ALERT_EMAIL_RECIPIENTS:devops-alerts@techcorp.com}"
  description: "告警邮件接收者"


- name: SLACK_WEBHOOK_URL
  value: "${SLACK_WEBHOOK_URL}"
  description: "Slack Webhook URL"


- name: PAGERDUTY_SERVICE_KEY
  value: "${PAGERDUTY_SERVICE_KEY}"
  description: "PagerDuty服务密钥"


# 业务配置
- name: BUSINESS_HOURS_START
  value: "${BUSINESS_HOURS_START:09:00}"
  description: "业务开始时间"


- name: BUSINESS_HOURS_END
  value: "${BUSINESS_HOURS_END:18:00}"
  description: "业务结束时间"


- name: MAINTENANCE_WINDOW_START
  value: "${MAINTENANCE_WINDOW_START:02:00}"
  description: "维护窗口开始时间"


- name: MAINTENANCE_WINDOW_END
  value: "${MAINTENANCE_WINDOW_END:04:00}"
  description: "维护窗口结束时间"


- name: FEATURE_FLAGS
  value: "${FEATURE_FLAGS:new-dashboard,advanced-analytics}"
  description: "功能开关"

4. 系统工作流配置 (`sys/workflows/operators.gxl`)

#![allow(unused)]
fn main() {
TODO
}

Sys-Operator 目录结构

概述

本文档详细说明了 Sys-Operator 的目录结构，帮助你理解系统组织和文件规范。

完整的目录结构

system_name/
├── _gal/                              # 项目配置目录
│   ├── adm.gxl                       # 系统管理配置
│   ├── work.gxl                      # 工作流环境配置
│   └── project.toml                  # 项目元数据配置
├── sys/                              # 系统定义目录
│   ├── sys_model.yml                 # 系统模型定义
│   ├── mod_list.yml                  # 模块列表定义
│   ├── vars.yml                      # 系统变量定义
│   ├── mods/                         # 模块本地化副本
│   │   ├── module1_name/
│   │   │   └── arm-mac14-host/       # 特定平台配置
│   │   │       ├── spec/             # 规范文件
│   │   │       ├── local/            # 本地化配置
│   │   │       ├── values/           # 值文件
│   │   │       ├── vars.yml          # 模块变量
│   │   │       ├── setting.yml       # 本地化设置
│   │   │       └── workflows/        # 模块工作流
│   │   └── module2_name/
│   │       └── x86-ubt22-k8s/        # 不同平台配置
│   │           └── [相同结构]
│   └── workflows/                    # 系统工作流定义
│       └── operators.gxl             # 系统操作符工作流
├── sys-prj.yml                       # 系统项目配置
├── version.txt                       # 系统版本信息
├── .gitignore                        # Git 忽略文件
└── test_res/                         # 测试资源目录

目录说明

`_gal/` - 项目配置目录

存储 Galaxy 项目的配置文件，包括版本管理、工作流定义和项目元数据。

关键文件：

adm.gxl: 系统管理配置，定义版本管理和发布流程
work.gxl: 工作流环境配置，定义执行环境和参数
project.toml: 项目元数据配置，包含项目基本信息

作用：

集中管理项目级别的配置
提供版本控制和发布管理
定义多环境执行配置

`sys/` - 系统定义目录

包含系统的核心定义文件和模块的本地化副本，是 Sys-Operator 的核心目录。

关键文件：

sys_model.yml: 系统模型定义，包含系统基本信息和目标环境
mod_list.yml: 模块列表定义，包含系统包含的所有模块配置
vars.yml: 系统变量定义，定义环境变量和配置参数

作用：

定义系统的基础架构
管理模块组合和依赖
配置系统级变量和参数

`mods/` - 模块本地化副本

存储系统中包含的各个模块的本地化配置和文件，这些是从模块源地址复制或下载而来的。

子目录结构：

mods/
├── module_name/
│   └── platform_model/               # 平台特定配置
│       ├── spec/                    # 规范文件
│       ├── local/                   # 本地化配置
│       ├── values/                  # 值文件
│       ├── vars.yml                 # 模块变量
│       ├── setting.yml              # 本地化设置
│       └── workflows/               # 模块工作流

平台命名规范：

arm-mac14-host: Apple M1/M2 芯片，macOS 系统，Host 模式
x86-ubt22-host: Intel/AMD x86，Ubuntu 22.04，Host 模式
x86-ubt22-k8s: Intel/AMD x86，Ubuntu 22.04，Kubernetes 模式

作用：

存储模块的本地化配置
支持多平台部署
提供模块的定制化配置

`workflows/` - 系统工作流目录

包含系统级别的操作流程定义，使用 GXL 语言编写。

关键文件：

operators.gxl: 系统操作符工作流，定义系统的生命周期管理

工作流类型：

init: 系统初始化
update: 系统更新
localize: 系统本地化
install: 系统安装
start: 系统启动
stop: 系统停止
status: 系统状态检查

其他重要文件

`sys-prj.yml` - 系统项目配置

定义系统项目的完整配置，包括：

测试环境配置
构建配置
发布配置
质量检查
安全配置
监控配置

`version.txt` - 系统版本信息

简单的文本文件，包含系统版本号：

1.0.0

文件组织原则

1. 按功能分类

配置文件: 存储在项目根目录和 _gal/ 目录
系统定义: 存储在 sys/ 目录
模块文件: 存储在 sys/mods/ 目录
工作流文件: 存储在 sys/workflows/ 目录
测试资源: 存储在 test_res/ 目录

3. 层次结构

项目级: 系统整体配置和元数据
系统级: 系统定义和配置
模块级: 模块具体配置和文件
平台级: 特定平台的配置

最佳实践

2. 目录维护

保持目录结构的标准化
遵循命名规范
定期清理无用文件
保持 .gitignore 文件的更新

总结

Sys-Operator 的目录结构设计遵循了模块化、可维护性、可扩展性的原则。通过标准化的目录结构，可以有效地组织系统配置，管理模块依赖，并支持多平台部署。理解和遵循这个目录结构对于使用 Sys-Operator 至关重要。

更多详情请参考文件组织方式和命名规范。

文件组织方式

概述

本文档详细说明 Sys-Operator 中的文件组织方式，包括配置文件的结构、模块文件的存储、工作流文件的编排等，帮助你理解如何有效地组织和管理系统文件。

配置文件组织

1. 系统级配置文件

系统级配置文件存储在 sys/ 目录下，定义整个系统的基础架构和配置。

`sys_model.yml` - 系统模型定义

文件作用: 定义系统的基本信息和目标运行环境

配置结构:

# 基础系统定义
name: system_name                    # 系统名称（必需）
model: arm-mac14-host               # 目标平台模型（必需）
vender: "Galaxy-Ops"                # 厂商信息（可选）

命名规范:

文件名必须为 sys_model.yml
系统名称必须唯一且有意义
模型名称遵循 arch-os-spc 格式
版本号遵循语义化版本规范

`mod_list.yml` - 模块列表定义

文件作用: 定义系统包含的所有模块及其配置

配置结构:

# 基础模块列表
- name: module_name                     # 模块名称（必需）
  addr:                                  # 模块地址（必需）
    repo: "https://github.com/user/repo" # Git 仓库（可选）
    tag: "v1.0.0"                        # 标签（可选）
    branch: "main"                       # 分支（可选）
    path: "./local/path"                 # 本地路径（可选）
  model: arm-mac14-host                 # 目标平台模型（必需）
  enable: true                           # 是否启用（可选，默认为 true）

# 高级模块配置
- name: advanced_module
  addr:
    repo: "https://github.com/user/module"
    tag: "v2.0.0"
  model: x86-ubt22-k8s
  enable: true
  setting:                              # 模块特定设置（可选）
    src: "${GXL_PRJ_ROOT}/sys/setting/module"
    dst: "${GXL_PRJ_ROOT}/sys/mods/module/local/"

配置验证:

模块名称不能重复
模块地址必须有效
模型必须存在
依赖关系不能形成循环

`vars.yml` - 系统变量定义

文件作用: 定义系统级别的环境变量和配置参数

配置结构:

# 基础变量
vars:
- name: VARIABLE_NAME             # 变量名（必需）
  value: "default_value"          # 默认值（必需）
  desp: "变量描述"               # 描述（可选）

# 类型化变量
- name: INT_VAR
  type: integer                  # 数据类型（可选）
  min: 1                         # 最小值（可选）
  max: 100                       # 最大值（可选）
  value: 10

- name: BOOL_VAR
  type: boolean
  value: true

- name: ENUM_VAR
  type: enum                     # 枚举类型
  values: [opt1, opt2, opt3]     # 可选值（必需）
  value: opt1

- name: REGEX_VAR
  type: string
  pattern: "^[a-zA-Z]+$"         # 正则模式（必需）
  value: "valid_string"

# 分组变量
vars:
# 网络配置
- name: HTTP_PORT
  group: network
  value: 80

- name: HTTPS_PORT
  group: network
  value: 443

# 数据库配置
- name: DB_HOST
  group: database
  value: "localhost"

- name: DB_PORT
  group: database
  type: integer
  min: 1
  max: 65535
  value: 5432

# 环境变量替换
- name: CONFIG_PATH
  value: "${CONFIG_PATH:/etc/app/config}"

- name: DEBUG_MODE
  value: "${DEBUG_MODE:false}"

# 条件变量
- name: FEATURE_FLAG
  value: "${FEATURE_FLAG:default}"

2. 项目级配置文件

项目级配置文件存储在 _gal/ 目录下，定义项目级别的管理配置。

`_gal/adm.gxl` - 系统管理配置

文件作用: 定义系统的版本管理和发布配置

配置结构:

#![allow(unused)]
fn main() {
// 引入版本管理模块
extern mod ver,git,ver_adm {
    git = "https://github.com/galaxy-operators/cfm-gxl.git",
    channel = "${GXL_CHANNEL:main}"
}

// 环境定义
mod envs {
    env default {
        PKG_NAME = "your_system";        // 系统包名
        VERSION = "1.0.0";              // 系统版本
        MAINTAINER = "devops@example.com";
        DESCRIPTION = "System description";
    }

    env production {
        PKG_NAME = "production-system";
        VERSION = "1.0.0";
        MAINTAINER = "prod-team@example.com";
    }
}

// 主模块继承版本管理功能
mod main : ver_adm {
    // 版本信息任务
    #[task(name="version")]
    flow version {
        gx.echo("System version: ${VERSION}");
        gx.echo("Package name: ${PKG_NAME}");
        gx.echo("Maintainer: ${MAINTAINER}");
    }

    // 发布任务（可选）
    #[task(name="publish")]
    flow publish {
        gx.echo("Publishing system to registry...");
        // 发布逻辑
    }
}
}

`_gal/work.gxl` - 工作流环境配置

文件作用: 定义系统的工作流环境和执行配置

配置结构:

#![allow(unused)]
fn main() {
// 引入操作符和版本管理模块
extern mod operators { path = "./sys/workflows"; }
extern mod ver,git {
    git = "https://github.com/galaxy-operators/cfm-gxl.git",
    channel = "${GXL_CHANNEL:main}"
}

// 环境定义
mod envs {
    // 默认环境
    env default : _common {
        FORCE_FLAG = "";                // 强制标志
        LOG_LEVEL = "";                 // 日志级别
        SYS_BIN = "gsys";              // 系统管理器
        MOD_BIN = "gmod";              // 模块管理器
        SYS = "sys";                    // 系统标识
        MODULE_ENV = "default";         // 模块环境
    }

    // 强制执行环境
    env force {
        FORCE_FLAG = "-f 3";
        LOG_LEVEL = "--log debug";
    }

    // 生产环境
    env production {
        FORCE_FLAG = "-f 2";
        LOG_LEVEL = "--log info";
        MODULE_ENV = "production";
    }

    // 通用配置
    env _common {
        BUILD_PATH = "${GXL_PRJ_ROOT}/build";    // 构建路径
        DEPLOY_PATH = "${GXL_PRJ_ROOT}/deploy";   // 部署路径
    }
}

// 主模块继承操作符功能
mod main : operators {
    BUILD_PATH = "${GXL_PRJ_ROOT}/build";

    // 自动加载入口
    #[auto_load(entry)]
    flow ver.use | @_into_main {
        ENV_SYS_MODEL = ${DEFINE.MODEL};          // 设置系统模型
        ENV_PKG_NAME = ${DEFINE.NAME};             // 设置包名
    }

    // 主配置任务
    #[task(name="main conf")]
    flow conf {
        gx.echo("=== 开始系统配置 ===");

        // 更新系统配置
        gx.cmd ("${ENV_SYS_BIN} update ${ENV_LOG_LEVEL} ${ENV_FORCE_FLAG}");

        // 本地化系统配置
        gx.cmd ("${ENV_SYS_BIN} localize ${ENV_LOG_LEVEL}");

        gx.echo("=== 系统配置完成 ===");
    }
}
}

3. 模块文件组织

模块文件存储在 sys/mods/ 目录下，每个模块有自己的本地化副本。

模块目录结构

sys/mods/
├── module_name/
│   └── platform_model/
│       ├── spec/                    # 规范文件
│       │   ├── module_spec.yml      # 模块规范
│       │   └── interfaces.yml       # 接口定义
│       ├── local/                   # 本地化配置
│       │   ├── config.yml           # 本地配置
│       │   ├── templates/            # 模板文件
│       │   └── scripts/             # 脚本文件
│       ├── values/                  # 值文件
│       │   ├── production.yml       # 生产环境值
│       │   ├── staging.yml          # 测试环境值
│       │   └── development.yml      # 开发环境值
│       ├── vars.yml                 # 模块变量
│       ├── setting.yml              # 本地化设置
│       └── workflows/               # 模块工作流
│           ├── install.gxl          # 安装工作流
│           ├── configure.gxl        # 配置工作流
│           └── start.gxl             # 启动工作流

模块配置文件

vars.yml - 模块变量:

# 模块特定变量
vars:
- name: MODULE_VERSION
  value: "1.0.0"
  description: "模块版本"

- name: MODULE_TYPE
  value: "service"
  description: "模块类型"

- name: MODULE_PORT
  type: integer
  min: 1
  max: 65535
  value: 8080
  description: "服务端口"

setting.yml - 本地化设置:

TODO

模块工作流文件

workflows/install.gxl - 安装工作流:

// 模块安装工作流
mod install {
    // 安装任务
    #[task(name="module_install")]
    flow install {
        gx.echo("=== 开始模块安装 ===");
        gx.echo("模块名称: ${MODULE.NAME}");
        gx.echo("模块版本: ${MODULE.VERSION}");

        // 预检查
        gx.echo("1. 执行预检查...");
        gx.pre_check();

        // 依赖安装
        gx.echo("2. 安装依赖...");
        gx.install_dependencies();

        // 配置文件
        gx.echo("3. 配置文件...");
        gx.configure();

        // 验证安装
        gx.echo("4. 验证安装...");
        gx.validate();

        gx.echo("=== 模块安装完成 ===");
    }
}

4. 工作流文件组织

系统工作流文件存储在 sys/workflows/ 目录下。

`operators.gxl` - 系统操作符工作流

文件作用: 定义系统级别的操作流程

配置结构:

TODO

5. 项目配置文件

sys-prj.yml - 系统项目配置

文件作用: 定义系统项目的完整配置

配置结构:

# 基础项目配置
name: "Production Web System"               # 系统项目名称
version: "1.0.0"                           # 项目版本
description: "Production web application system with monitoring"

# 测试环境配置
test_envs:
  dep_root: "./test_deps"                   # 依赖根目录
  deps:
    - addr:
        repo: https://github.com/galaxy-operators/bitnami-common.git
      local: ./test_res/bit-common          # 本地路径
      rename: bit-common                    # 重命名
      enable: true                          # 是否启用

总结

Sys-Operator 的文件组织方式遵循了模块化、标准化、可维护性的原则。通过合理的文件结构和配置组织，可以有效管理系统配置，提高开发效率，降低维护成本。理解并遵循这些文件组织方式对于有效使用 Sys-Operator 至关重要。

更多详情请参考目录结构和命名规范。

命名规范

概述

本文档详细说明 Sys-Operator 中的命名规范，包括文件名、变量名、模块名、系统名等的命名约定，帮助你保持命名的一致性和可读性。

命名原则

1. 可读性原则

目标: 命名应该清晰表达其用途，便于理解和维护。

规则:

使用有意义的名称，避免缩写和模糊的词汇
名称应该自解释，减少额外的注释需求
保持名称的简洁性，不过度冗长

示例:

# 好的命名
name: "production_web_system"
name: "user_management_service"
name: "database_connection_pool"

# 不好的命名
name: "prod_sys"         # 缩写不清晰
name: "system_1"         # 无意义
name: "usermgmt_service" # 缩写不规范

2. 一致性原则

目标: 保持整个项目命名风格的一致性。

规则:

统一的命名风格（全小写、驼峰、下划线等）
相同概念使用相同的术语
遵循项目的现有命名约定

示例:

# 一致的命名风格
vars:
  - name: database_host           # 下划线分隔
  - name: database_port
  - name: database_name

# 不一致的命名风格
vars:
  - name: databaseHost           # 混合风格
  - name: DB_PORT                # 大写缩写
  - name: databaseName           # 驼峰命名

3. 可扩展性原则

目标: 命名应该支持项目的扩展和演进。

规则:

避免硬编码的数字和版本
使用通用的术语，便于复用
支持多环境和多部署

示例:

# 可扩展的命名
name: "web_application_system"    # 通用的名称
name: "microservice_platform"      # 可扩展的平台名称

# 不可扩展的命名
name: "system_v2_1_production   # 硬编码版本
name: "legacy_app_deprecated     # 硬编码状态

文件命名规范

1. 配置文件

YAML 配置文件:

sys_model.yml           # 系统模型定义（必需）
mod_list.yml            # 模块列表定义（必需）
vars.yml               # 系统变量定义（必需）
admin-config.gxl       # 系统管理配置（推荐）
work-config.gxl        # 工作流环境配置（推荐）
project-config.toml    # 项目配置（推荐）

命名规则:

使用小写字母
多个单词用下划线分隔
扩展名表示文件格式（.yml, .gxl, .toml）
文件名应该反映文件内容

错误示例:

SysModel.yaml          # 大写字母和错误扩展名
model_list.yml         # 缩写不清晰
config.yml             # 过于通用
system_configs.yml     # 复数形式不必要

2. 工作流文件

GXL 工作流文件:

operators.gxl          # 系统操作符工作流（必需）
system-workflows.gxl   # 系统工作流（可选）
module-workflows.gxl   # 模块工作流（可选）
custom-workflows.gxl   # 自定义工作流（可选）

命名规则:

工作流文件应该以 -workflows.gxl 结尾
自定义工作流应该有明确的前缀
系统级和模块级工作流应该区分

3. 模块文件

模块目录名:

sys/mods/
├── web_server/
├── database_server/
├── cache_manager/
├── message_queue/
├── load_balancer/
└── monitoring_agent/

命名规则:

使用小写字母
多个单词用下划线分隔
描述性名称，明确模块功能
避免缩写和简写

4. 平台目录名

平台模型目录:

arm-mac14-host
x86-ubt22-host
x86-ubt22-k8s
x86-centos8-host
arm-linux-k8s

命名规则:

格式：arch-os-spc
架构：arm, x86, amd64
操作系统：mac14, ubt22, centos8, linux
环境：host, k8s, docker

变量命名规范

1. 系统变量

命名规则:

使用全大写字母
单词间用下划线分隔
前缀标识变量类型
包含适当的命名空间

示例:

# 系统配置
- name: SYSTEM_NAME
  value: "production_system"

- name: SYSTEM_VERSION
  value: "1.0.0"

- name: SYSTEM_ENVIRONMENT
  value: "production"

# 网络配置
- name: NETWORK_HOST
  value: "localhost"

- name: NETWORK_PORT
  value: 8080

- name: NETWORK_PROTOCOL
  value: "https"

# 数据库配置
- name: DATABASE_HOST
  value: "postgres-primary"

- name: DATABASE_PORT
  value: 5432

- name: DATABASE_NAME
  value: "production_db"

# 安全配置
- name: SECURITY_ENCRYPTION_KEY
  value: "generated_key_here"

- name: SECURITY_SSL_CERT_PATH
  value: "/etc/ssl/certs/server.crt"

# 性能配置
- name: PERFORMANCE_MAX_THREADS
  value: 100

- name: PERFORMANCE_MEMORY_LIMIT
  value: "4GB"

2. 模块变量

命名规则:

模块名作为前缀
跟随具体的配置项
使用统一的术语

示例:

# web_server 模块变量
vars:
  - name: WEB_SERVER_PORT
    value: 80

  - name: WEB_SERVER_SSL_PORT
    value: 443

  - name: WEB_SERVER_WORKERS
    value: 4

  - name: WEB_SERVER_KEEP_ALIVE
    value: "75s"

# database_server 模块变量
vars:
  - name: DATABASE_SERVER_HOST
    value: "db-primary"

  - name: DATABASE_SERVER_PORT
    value: 5432

  - name: DATABASE_SERVER_MAX_CONNECTIONS
    value: 100

  - name: DATABASE_SERVER_TIMEOUT
    value: "30s"

3. 环境变量

命名规则:

支持环境变量替换
使用默认值语法
变量名与配置名对应

示例:

# 环境变量替换
vars:
  - name: DATABASE_HOST
    value: "${DATABASE_HOST:localhost}"

  - name: DATABASE_PORT
    value: "${DATABASE_PORT:5432}"

  - name: ENABLE_DEBUG
    value: "${ENABLE_DEBUG:false}"

  - name: LOG_LEVEL
    value: "${LOG_LEVEL:info}"

  - name: CONFIG_PATH
    value: "${CONFIG_PATH:/etc/app/config}"

  - name: API_KEY
    value: "${API_KEY}"

4. 分组变量

命名规则:

使用 group 字段进行分类
组名与功能相关
组内变量命名保持一致

示例:

# 按功能分组的变量
vars:
# 网络配置组
- name: HTTP_PORT
  group: network
  value: 80

- name: HTTPS_PORT
  group: network
  value: 443

- name: DOMAIN_NAME
  group: network
  value: "example.com"

# 数据库配置组
- name: DB_HOST
  group: database
  value: "postgres"

- name: DB_PORT
  group: database
  value: 5432

- name: DB_NAME
  group: database
  value: "app_db"

# 安全配置组
- name: ENABLE_SSL
  group: security
  value: true

- name: SSL_CERT_PATH
  group: security
  value: "/etc/ssl/certs/server.crt"

- name: SSL_KEY_PATH
  group: security
  value: "/etc/ssl/private/server.key"

# 监控配置组
- name: ENABLE_MONITORING
  group: monitoring
  value: true

- name: METRICS_PORT
  group: monitoring
  value: 9090

- name: LOG_LEVEL
  group: monitoring
  value: "info"

模块命名规范

1. 模块名

命名规则:

使用小写字母
单词间用下划线分隔
描述性名称
避免缩写

示例:

# 好的模块名
- name: web_server
- name: database_server
- name: cache_manager
- name: message_queue
- name: load_balancer
- name: monitoring_agent
- name: file_storage
- name: authentication_service

# 不好的模块名
- name: web
- name: db
- name: cache
- name: mq
- name: lb
- name: monitor
- name: storage
- name: auth

2. 模块类型

常用模块类型:

server      # 服务器服务
client      # 客户端服务
proxy       # 代理服务
gateway     # 网关服务
cache       # 缓存服务
storage     # 存储服务
queue       # 消息队列
monitor     # 监控服务
security    # 安全服务
network     # 网络服务

命名模式:

{function}_{type}: web_server, database_server
{type}_{service}: cache_redis, queue_rabbitmq
{service}_{tool}: monitor_grafana, security_consul

系统命名规范

1. 系统名

命名规则:

使用小写字母
单词间用下划线分隔
描述性名称
包含环境标识（可选）

示例:

# 生产环境
name: production_web_system
name: staging_api_gateway
name: development_database_cluster

# 开发环境
name: dev_web_system
name: test_user_service
name: local_message_queue

# 通用环境
name: microservice_platform
name: data_processing_system
name: enterprise_application

2. 系统标识

命名规则:

系统名作为基础
添加环境前缀（可选）
添加版本标识（可选）

标识格式:

{environment}_{system_name}_{version}

示例:

prod_web_system_v1.0.0
staging_api_gateway_v2.1.0
dev_database_cluster_v0.9.0

工作流命名规范

1. 任务名

命名规则:

使用动词开头
描述具体操作
动词+名词结构

常用动词:

install     # 安装
start       # 启动
stop        # 停止
restart     # 重启
update      # 更新
configure   # 配置
deploy      # 部署
backup      # 备份
restore     # 恢复
validate    # 验证
check       # 检查
monitor     # 监控

示例:

# 好的任务名
#[task(name="install_service")]
#[task(name="start_application")]
#[task(name="stop_database")]
#[task(name="update_config")]
#[task(name="deploy_system")]
#[task(name="validate_environment")]

# 不好的任务名
#[task(name="install")]        # 过于简单
#[task(name="do_start")]        # 冗余
#[task(name="run_installer")]   # 间接

2. 流程名

命名规则:

使用多个单词
描述完整流程
包含系统标识

示例:

# 系统操作流程
flow system_installation
flow system_configuration
flow system_deployment
flow system_monitoring

# 模块操作流程
flow module_initialization
flow module_configuration
flow module_deployment
flow module_validation

GXL 元素命名规范

1. 变量名

命名规则:

使用大写字母
单词间用下划线分隔
描述变量内容

示例:

// 系统配置变量
let SYSTEM_NAME = "web_system"
let SYSTEM_MODEL = "arm-mac14-host"
let MODULE_COUNT = 5

// 环境变量
let ENVIRONMENT = "production"
let LOG_LEVEL = "info"
let FORCE_FLAG = ""

// 路径变量
let PROJECT_ROOT = "${GXL_PRJ_ROOT}"
let CONFIG_PATH = "${PROJECT_ROOT}/config"
let DEPLOY_PATH = "${PROJECT_ROOT}/deploy"

2. 函数名

命名规则:

使用动词+名词结构
动词用现在时
描述函数功能

示例:

// 检查函数
function check_environment()
function check_dependencies()
function check_health()

// 安装函数
function install_system()
function install_module(module_name)
function install_dependencies()

// 配置函数
function configure_system()
function configure_module(module)
function apply_settings()

// 工具函数
function read_file(file_path)
function write_file(file_path, content)
function validate_config()

3. 标签名

命名规则:

使用小写字母
单词间用下划线分隔
标签语义明确

示例:

// 系统标签
label system_initialized
label system_running
label system_stopped
label system_error

// 模块标签
label module_installed
label module_started
label module_stopped
label module_failed

// 流程标签
label installation_complete
label deployment_successful
label validation_passed
label configuration_applied

避免的命名模式

1. 不推荐的命名

避免使用:

单字符变量名（a, b, c）
缩写不明确的名称（cfg, tmp, var）
硬编码数字和版本
保留关键字和特殊字符
过于通用的名称

示例:

# 不推荐的命名
- name: a                    # 单字符
- name: cfg                  # 缩写不明确
- name: v1                  # 硬编码版本
- name: temp_123             # 临时编号
- name: system               # 过于通用
- name: config               # 过于通用
- name: data                 # 过于通用

2. 特殊字符和保留字

避免使用的字符:

空格和特殊字符
连字符（-）
斜杠（/）
点号（.）开头或结尾
保留关键字

示例:

# 错误的命名
- name: web server          # 包含空格
- name: api-gateway        # 使用连字符
- name: config/backup       # 包含斜杠
- name: .hidden            # 以点号开头
- name: system$            # 包含特殊字符
- name: null               # 保留关键字

命名验证工具

1. 自动验证脚本

bash 脚本示例:

#!/bin/bash

# 验证 YAML 配置文件
validate_naming_conventions() {
    local file=$1
    local errors=0
    
    # 检查变量名
    if [[ $file == *"vars.yml" ]]; then
        local invalid_vars=$(yq eval '.vars[] | select(.name | ascii_downcase != .name)' "$file")
        if [[ -n "$invalid_vars" ]]; then
            echo "错误: 变量名必须全小写"
            echo "$invalid_vars"
            errors=$((errors + 1))
        fi
    fi
    
    # 检查模块名
    if [[ $file == *"mod_list.yml" ]]; then
        local invalid_modules=$(yq eval '.[] | select(.name | ascii_downcase != .name)' "$file")
        if [[ -n "$invalid_modules" ]]; then
            echo "错误: 模块名必须全小写"
            echo "$invalid_modules"
            errors=$((errors + 1))
        fi
    fi
    
    return $errors
}

# 验证所有配置文件
for file in sys/*.yml; do
    if [[ -f "$file" ]]; then
        echo "验证文件: $file"
        validate_naming_conventions "$file"
        if [[ $? -eq 0 ]]; then
            echo "✓ 通过验证"
        else
            echo "✗ 验证失败"
        fi
    fi
done

2. 集成验证

Git 钩子示例:

#!/bin/bash
# .git/hooks/pre-commit

# 检查提交的文件是否包含配置文件
changed_files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(yml|gxl)$')

if [[ -n "$changed_files" ]]; then
    echo "验证命名规范..."
    
    for file in $changed_files; do
        echo "检查文件: $file"
        
        # 执行命名规范检查
        if ! validate_naming_conventions "$file"; then
            echo "错误: $file 不符合命名规范"
            exit 1
        fi
    done
fi

echo "命名规范验证通过"

最佳实践

1. 创建命名规范文档

内容建议:

项目特定的命名规则
术语表和缩写定义
示例和反例
验证工具使用方法
维护更新策略

2. 自动化验证

工具集成:

CI/CD 流水线集成
代码审查工具集成
文档生成工具集成
开发环境配置集成

总结

良好的命名规范是项目成功的重要因素。Sys-Operator 的命名规范注重可读性、一致性和可扩展性，通过清晰的命名约定可以：

提高代码可读性和维护性
减少沟通成本和理解误差
支持项目的长期演进
便于团队协作和代码审查
提供更好的开发体验

遵循这些命名规范，并与团队保持一致的命名约定，将有助于建立高质量、可维护的系统配置。

更多详情请参考目录结构和文件组织方式。

TODO

Mod-Operator 开发指南

概述

Mod-Operator 是 Galaxy Ops 框架的核心组件，用于定义和管理可复用的运维模块。每个 Mod-Operator 代表一个独立的软件组件或服务，包含完整的生命周期管理能力，包括安装、配置、启动、停止、监控等操作。

核心特性

多平台支持: 支持不同的 CPU 架构、操作系统和运行环境组合
模块化设计: 每个模块都是独立的，可单独开发和版本管理
工作流驱动: 使用 GXL 语言定义复杂的运维操作流程
模板本地化: 支持配置模板渲染和环境适配
依赖管理: 处理模块间的依赖关系
构件管理: 统一的软件包下载、缓存和分发机制

在 Galaxy Ops 生态系统中的位置

gmod (创建模块) → gsys (组合系统) → gops (工程管理) → gflow (执行工作流)

Mod-Operator 是整个运维体系的基础构建块，由 gmod 工具创建和管理，最终通过 gflow 执行具体的运维操作。

文档索引

本指南被拆分为以下文档以便于维护：

配置说明 - 核心配置文件详细说明
开发指南 - 开发工作流和最佳实践
故障排除 - 调试和故障排除
API 参考 - API 和枚举参考

快速开始

创建新模块

# 创建基础模块
gmod new postgresql

# 创建带目标的模块
gmod new postgresql --targets arm-mac14-host,x86-ubt22-k8s

# 从模板创建
gmod new postgresql --template database

基本文件结构

module_name/
├── mod/                              # 模块定义目录
│   ├── arm-mac14-host/              # ARM + macOS14 + Host 环境
│   │   ├── _gal/                    # 项目配置目录
│   │   ├── local/                   # 本地化生成的配置
│   │   ├── spec/                    # 规范文件目录
│   │   ├── values/                  # 值文件目录
│   │   ├── vars.yml                 # 变量定义
│   │   ├── setting.yml              # 本地化设置
│   │   └── workflows/               # 工作流定义
│   └── x86-ubt22-k8s/              # x86 + Ubuntu22 + K8s 环境
│       └── [相同的子目录结构]
├── mod-prj.yml                      # 模块项目配置
├── version.txt                      # 版本文件
├── .gitignore                       # Git 忽略文件
└── test_res/                        # 测试资源目录

支持的目标平台

组合	CPU架构	操作系统	运行环境	适用场景
`arm-mac14-host`	ARM	macOS 14+	Host 宿主机	Apple Silicon Mac 本地开发
`x86-ubt22-host`	x86_64	Ubuntu 22.04	Host 宿主机	Linux 服务器本地部署
`x86-ubt22-k8s`	x86_64	Ubuntu 22.04	Kubernetes	K8s 集群容器化部署

开发工作流

1. 定义模块规范

编辑 spec/artifact.yml - 构件定义
编辑 spec/depends.yml - 依赖定义

2. 配置变量

编辑 vars.yml - 变量定义
编辑 values/_value.yml - 默认值

3. 编写工作流

编辑 workflows/operators.gxl - 使用 GXL 定义工作流

关键概念

ModelSTD 标准型号

Mod-Operator 使用 ModelSTD 标准型号来定义目标平台，格式为 arch-os-spc：

CPU 架构: X86 (x86_64), ARM
操作系统: MAC14 (macOS 14+), UBT22 (Ubuntu 22.04), WIN10 (Windows 10+), COS7 (CentOS 7)
运行空间: Host (宿主机环境), K8S (Kubernetes 环境)

构件管理

构件定义了模块所需的软件包和下载资源，包括：

名称 (name)
版本 (version)
原始地址 (origin_addr)
缓存地址 (cache_addr)
缓存启用 (cache_enable)
本地文件名 (local)

依赖管理

模块可以依赖其他模块或资源，支持：

本地路径依赖
Git 仓库依赖
条件依赖（根据变量启用/禁用）
版本约束

工作流引擎

使用 GXL (Galaxy eXecution Language) 定义运维操作：

支持任务定义和执行
变量模板渲染
条件分支和循环
外部命令执行
错误处理和重试机制

Mod-Operator 开发指南

本文档详细介绍 Mod-Operator 的开发工作流程、最佳实践和技巧，帮助开发者高效地创建高质量的运维模块。

开发工作流

1. 创建新模块

使用 gmod 工具快速创建新模块的骨架结构。

基础模块创建

# 创建基础模块
//fix: use gmod cmd and args

生成的模块结构

postgresql/
├── mod/
│   ├── arm-mac14-host/
│   │   ├── spec/
│   │   │   ├── artifact.yml
│   │   │   └── depends.yml
│   │   ├── vars.yml
│   │   ├── setting.yml
│   │   ├── values/
│   │   │   ├── _value.yml
│   │   │   └── _used.yml
│   │   ├── workflows/
│   │   │   └── operators.gxl
│   │   └── _gal/
│   │       ├── work.gxl
│   │       └── project.toml
│   └── x86-ubt22-k8s/
│       └── [相同结构]
├── mod-prj.yml
├── version.txt
├── .gitignore
└── README.md

2. 模块开发步骤

步骤 1：定义构件和依赖

编辑 spec/artifact.yml 和 spec/depends.yml：

# 编辑构件配置
vim mod/arm-mac14-host/spec/artifact.yml

# 编辑依赖配置
vim mod/arm-mac14-host/spec/depends.yml

artifact.yml 示例：

- name: postgresql
  version: 17.4
  origin_addr:
    url: https://mirrors.aliyun.com/postgresql/latest/postgresql-17.4.tar.gz
  cache_enable: false
  local: postgresql-17.4.tar.gz

- name: pcre
  version: 8.45
  origin_addr:
    url: https://sourceforge.net/projects/pcre/files/pcre/8.45/pcre-8.45.tar.gz
  local: pcre-8.45.tar.gz

depends.yml 示例：

dep_root: ./depends

deps:
- addr:
    path: ./common_libs
  local: common_libs
  enable: true

- addr:
    repo: https://github.com/openssl/openssl.git
    tag: "3.0.0"
  local: openssl
  enable: true

步骤 2：配置变量和默认值

编辑变量配置文件：

# 定义环境变量
vim mod/arm-mac14-host/vars.yml

vars.yml 示例：

vars:
- name: DATABASE_PORT
  desp: "数据库端口号"
  type: integer
  min: 1024
  max: 65535
  value: 5432

- name: MAX_CONNECTIONS
  type: integer
  min: 1
  max: 1000
  value: 100

- name: DATA_DIR
  value: "/var/lib/postgresql"

- name: ENABLE_SSL
  type: boolean
  value: false

步骤 3：编写工作流

编辑 workflows/operators.gxl 定义运维操作：

# 编写操作工作流
vim mod/arm-mac14-host/workflows/operators.gxl

步骤 4：配置本地化设置[按需]

编辑 setting.yml 配置模板渲染：

# 配置本地化设置
vim mod/arm-mac14-host/setting.yml

localize:
  templatize_path:
    excludes:
    - README.md
    - LICENSE
    - "*.log"

  templatize_cust:
    label_beg: '{{'
    label_end: '}}'

步骤 5：验证和测试


# 生成本地化配置
gmod localize

# 测试工作流
gflow install --dry-run

3. 开发工具使用

gmod - 模块管理工具

# 创建模块
gmod new module_name


# 生成本地化配置
gmod localize

gflow - 工作流执行工具

# 执行工作流
gflow install
gflow start
gflow stop
gflow restart

# 调试模式
gflow install -d 1  # 详细输出
gflow install -d 2  # 更详细输出
gflow install -d 3  # 最详细输出

# 试运行模式
gflow install --dry-run

最佳实践

1. 模块设计原则

单一职责原则

✅ 好的做法：

# 专注单一组件
name: postgresql
description: "PostgreSQL 数据库管理模块"

❌ 不好的做法：

# 职责混乱
name: database_stack
description: "数据库、缓存、消息队列管理模块"

接口一致性

✅ 好的做法：

# 统一的任务命名
#[task(name="gops@install")]
flow install { ... }

#[task(name="gops@start")]
flow start { ... }

#[task(name="gops@stop")]
flow stop { ... }

#[task(name="gops@restart")]
flow restart { ... }

❌ 不好的做法：

# 不一致的命名
#[task(name="install")]
flow install { ... }

#[task(name="startup")]
flow start { ... }

#[task(name="halt")]
flow stop { ... }

配置外部化

✅ 好的做法：

# 所有配置参数提取到变量
vars:
- name: DATABASE_PORT
  value: 5432

- name: MAX_CONNECTIONS
  value: 100

- name: DATA_DIR
  value: "/var/lib/postgresql"

❌ 不好的做法：

# 硬编码配置
flow install {
    gx.cmd("postgres -p 5432 -d /var/lib/postgresql");
}

2. 工作流设计

幂等性设计

✅ 好的做法：

flow install {
    // 检查是否已安装
    if gx.defined("/usr/local/bin/postgres") {
        gx.echo("PostgreSQL 已安装，跳过安装步骤");
        return;
    }

    // 执行安装
    gx.cmd("./install.sh");

    // 验证安装
    gx.assert(gx.path_exists("/usr/local/bin/postgres"));
}

❌ 不好的做法：

flow install {
    // 没有检查，可能重复安装
    gx.cmd("./install.sh");
}

3. 变量管理

命名规范

✅ 好的命名：

vars:
- name: DATABASE_PORT
  value: 5432

- name: MAX_CONNECTIONS
  value: 100

- name: DATA_DIRECTORY
  value: "/var/lib/postgresql"

❌ 不好的命名：

vars:
- name: port
  value: 5432

- name: max_conn
  value: 100

- name: data_dir
  value: "/var/lib/postgresql"

类型安全

✅ 好的做法：

vars:
- name: DATABASE_PORT
  type: integer
  min: 1024
  max: 65535
  value: 5432

- name: ENABLE_SSL
  type: boolean
  value: false

- name: LOG_LEVEL
  type: enum
  values: [debug, info, warn, error]
  value: info

❌ 不好的做法：

vars:
- name: DATABASE_PORT
  value: "5432"  # 字符串而不是数字

- name: ENABLE_SSL
  value: "false"  # 字符串而不是布尔值

环境变量支持

✅ 好的做法：

vars:
- name: DATABASE_PORT
  value: "${POSTGRES_PORT:5432}"  # 默认值 5432

- name: INSTALL_PREFIX
  value: "${PREFIX:/usr/local}"  # 默认 /usr/local

- name: DEBUG_MODE
  type: boolean
  value: "${DEBUG:false}"  # 默认 false

4. 依赖管理

版本约束

✅ 好的做法：

deps:
- addr:
    repo: https://github.com/openssl/openssl.git
    tag: "3.0.0"  # 语义化版本
  enable: true

- addr:
    repo: https://github.com/pcre/pcre.git
    tag: "8.45"
  enable: true

❌ 不好的做法：

deps:
- addr:
    repo: https://github.com/openssl/openssl.git
    tag: "latest"  # 不稳定的版本
  enable: true

条件依赖

✅ 好的做法：

deps:
- addr:
    path: ./optional_libs
  local: optional_libs
  enable: "${USE_FEATURES:true}"

- addr:
    repo: https://github.com/debug/tools.git
    branch: main
  local: debug_tools
  enable: "${BUILD_MODE:debug}" == "debug"

❌ 不好的做法：

deps:
- addr:
    path: ./optional_libs
  local: optional_libs
  enable: true  # 应该根据条件启用

本地依赖优先

✅ 好的做法：

deps:
# 本地依赖优先
- addr:
    path: ./local_libs
  local: common_libs
  enable: true

# 外部依赖作为后备
- addr:
    repo: https://github.com/external/lib.git
    tag: "1.0.0"
  local: common_libs
  enable: false  # 默认禁用

5. 文档和维护

版本管理

✅ 好的做法：

# mod-prj.yml
name: postgresql
version: "17.4.0"
description: "PostgreSQL 数据库管理模块"

# version.txt
17.4.0

❌ 不好的做法：

# 没有版本管理
name: postgresql
version: "latest"
description: "PostgreSQL 数据库管理模块"

总结

遵循本开发指南，可以创建出高质量、可维护、可扩展的 Mod-Operator 模块。关键要点：

标准化开发流程：遵循一致的模块创建和开发流程
最佳实践设计：采用单一职责、幂等性、错误处理等设计原则
有效的调试策略：使用详细的日志、断言和分步调试
性能优化：利用并行执行和缓存机制
高级功能：掌握条件工作流、模板系统

通过合理应用这些技巧和最佳实践，可以显著提升模块开发效率和质量，为复杂的系统运维提供坚实的基础。

Mod-Operator 配置文件详解

本文档详细介绍 Mod-Operator 的各个配置文件及其使用方法。

配置文件概览

Mod-Operator 使用多种配置文件来定义模块的行为和属性：

文件	位置	作用	格式
`spec/artifact.yml`	`mod/{platform}/spec/`	定义软件包和资源	YAML
`spec/depends.yml`	`mod/{platform}/spec/`	定义依赖关系	YAML
`vars.yml`	`mod/{platform}/`	定义环境变量	YAML
`setting.yml`	`mod/{platform}/`	配置本地化行为	YAML
`workflows/operators.gxl`	`mod/{platform}/workflows/`	工作流定义	GXL
`mod-prj.yml`	根目录	项目配置	YAML

spec/artifact.yml - 构件定义

artifact.yml 是 Mod-Operator 中最重要的配置文件之一，它定义了模块所需的软件包、资源及其下载配置。

基本格式

# 单个构件定义
- name: postgresql
  version: 0.1.0
  origin_addr:
    url: https://mirrors.aliyun.com/postgresql/latest/postgresql-17.4.tar.gz
  cache_enable: false
  local: postgresql-17.4.tar.gz

字段说明

字段	类型	必需	说明
`name`	String	是	构件名称
`version`	String	是	构件版本
`origin_addr`	Object	是	原始下载地址
`cache_addr`	Object	否	缓存地址（可选）
`cache_enable`	Boolean	否	是否启用缓存（默认 false）
`local`	String	是	本地存储文件名

地址类型支持

HTTP 地址

- name: nginx
  version: 1.25.3
  origin_addr:
    url: https://nginx.org/download/nginx-1.25.3.tar.gz
  local: nginx-1.25.3.tar.gz

Git 仓库

- name: galaxy-flow
  version: 0.1.0
  origin_addr:
    repo: https://github.com/galaxy-sec/galaxy-flow.git
    branch: main
  local: galaxy-flow

本地路径

- name: custom-library
  version: 1.0.0
  origin_addr:
    path: /path/to/local/library.tar.gz
  local: custom-library.tar.gz

多构件定义

- name: postgresql
  version: 17.4
  origin_addr:
    url: https://mirrors.aliyun.com/postgresql/latest/postgresql-17.4.tar.gz
  cache_enable: false
  local: postgresql-17.4.tar.gz

- name: pcre
  version: 8.45
  origin_addr:
    url: https://sourceforge.net/projects/pcre/files/pcre/8.45/pcre-8.45.tar.gz
  local: pcre-8.45.tar.gz

- name: openssl
  version: 3.0.0
  origin_addr:
    repo: https://github.com/openssl/openssl.git
    tag: openssl-3.0.0
  local: openssl-3.0.0

spec/depends.yml - 依赖定义

depends.yml 定义模块依赖的其他模块或资源，支持多种依赖类型和条件依赖。

基本格式

dep_root: ./depends

deps:
- addr:
    path: ./data
  local: data_resources
  enable: true

字段说明

字段	类型	必需	说明
`dep_root`	String	是	依赖根目录
`deps`	Array	是	依赖列表
`addr`	Object	是	依赖地址配置
`local`	String	是	本地化名称
`enable`	Boolean	是	是否启用

依赖地址类型

本地路径依赖

deps:
- addr:
    path: ./common_libs          # 相对路径
  local: common_libs
  enable: true

- addr:
    path: /usr/local/lib        # 绝对路径
  local: system_libs
  enable: false

Git 仓库依赖

deps:
- addr:
    repo: https://github.com/user/module.git
    tag: "1.0.0"                # 版本标签
  local: external_module
  enable: true

条件依赖

deps:
- addr:
    path: ./optional_libs
  local: optional_libs
  enable: "${ENABLE_FEATURES:false}"  # 条件启用

- addr:
    repo: https://github.com/debug/debug-tools.git
    branch: main
  local: debug_tools
  enable: "${BUILD_MODE:debug}" == "debug"

HTTP URL 依赖

deps:
- addr:
    url: https://example.com/dependencies.zip
  local: external_deps
  enable: true

vars.yml - 变量定义

vars.yml 定义模块使用的环境变量和配置参数，支持类型安全和验证规则。

基本格式

vars:
- name: DATABASE_PORT
  desp: "数据库端口号"
  value: 5432

- name: MAX_CONNECTIONS
  value: 100

字段说明

字段	类型	必需	说明
`name`	String	是	变量名
`desp`	String	否	描述（可选）
`value`	String	是	默认值
`type`	String	否	类型（string, integer, boolean, enum）
`min`	Number	否	最小值（数字类型）
`max`	Number	否	最大值（数字类型）
`values`	Array	否	枚举值（枚举类型）

变量类型

字符串变量

vars:
- name: MODULE_NAME
  desp: "模块名称"
  value: postgresql

- name: DATA_DIR
  value: "/var/lib/postgresql"

整数变量

vars:
- name: DATABASE_PORT
  type: integer
  min: 1024
  max: 65535
  value: 5432

- name: MAX_CONNECTIONS
  type: integer
  min: 1
  max: 1000
  value: 100

布尔变量

vars:
- name: ENABLE_SSL
  type: boolean
  value: false

- name: ENABLE_DEBUG
  type: boolean
  value: true

变量引用和模板

# 支持变量间引用
vars:
- name: INSTALL_PREFIX
  value: "/usr/local"

- name: MODULE_PATH
  value: "${INSTALL_PREFIX}/{{MODULE_NAME}}"

- name: CONFIG_FILE
  value: "${MODULE_PATH}/config.conf"

环境变量支持

# 支持通过环境变量覆盖默认值
vars:
- name: DATABASE_PORT
  value: "${POSTGRES_PORT:5432}"    # 默认 5432，可被 POSTGRES_PORT 环境变量覆盖

- name: INSTALL_PREFIX
  value: "${PREFIX:/usr/local}"     # 默认 /usr/local，可被 PREFIX 环境变量覆盖

- name: DEBUG_MODE
  type: boolean
  value: "${DEBUG:false}"           # 默认 false，可被 DEBUG 环境变量覆盖

setting.yml - 本地化设置

setting.yml 配置模板渲染和本地化行为，定义哪些文件需要模板化以及模板标记格式。

基本格式

localize:
  templatize_path:
    excludes:
    - README.md
    - LICENSE
    - "*.log"

  templatize_cust:
    label_beg: '[['
    label_end: ']]'

字段说明

字段	类型	必需	说明
`templatize_path`	Object	否	模板路径配置
`templatize_cust`	Object	否	自定义模板标记
`excludes`	Array	否	排除的文件列表
`includes`	Array	否	包含的文件列表（优先级高于 excludes）
`label_beg`	String	否	模板开始标记
`label_end`	String	否	模板结束标记

文件选择策略

排除特定文件

localize:
  templatize_path:
    excludes:
    - README.md
    - CHANGELOG.md
    - "*.log"
    - "*.tmp"

仅包含特定类型文件

localize:
  templatize_path:
    includes:
    - "*.conf"
    - "*.yml"
    - "*.yaml"
    - "templates/*"

混合使用

localize:
  templatize_path:
    includes:
    - "*.conf"
    - "*.template"
    excludes:
    - "examples/*"
    - "test/*"

模板标记配置

默认标记（Jinja2 风格）

localize:
  templatize_cust:
    label_beg: '{{'
    label_end: '}}'

自定义标记

localize:
  templatize_cust:
    label_beg: '[['
    label_end: ']]'

多种标记支持

localize:
  templatize_cust:
    label_beg: '${'
    label_end: '}'

本地化规则

# 为不同环境配置不同的本地化规则
localize:
  # 生产环境配置
  templatize_path:
    excludes:
    - "*.dev"
    - "*.test"

  templatize_cust:
    label_beg: '{{'
    label_end: '}}'

# 开发环境配置
localize:
  templatize_path:
    includes:
    - "*.dev"
    - "config.dev/*"

  templatize_cust:
    label_beg: '[['
    label_end: ']]'

values/_used.yml - 使用的值定义

_used.yml 记录实际使用的配置值及其来源，便于配置审计和问题排查。

基本格式

SPEED_LIMIT:
  origin: mod-default
  value: 1000
  source_file: "values/_value.yml"

MODULE_NAME:
  origin: mod-default
  value: postgresql

PORT:
  origin: user-override
  value: 5433
  source_file: "user-config.yml"

MAX_CONNECTIONS:
  origin: env-override
  value: 200
  environment_var: "MAX_CONNECTIONS"

值来源类型

来源类型	说明	示例
`mod-default`	模块默认值	来自 `values/_value.yml`
`user-override`	用户覆盖值	来自用户配置文件
`env-override`	环境变量覆盖	来自环境变量
`cmd-line`	命令行参数	来自命令行选项
`template-render`	模板渲染结果	运行时计算值

工作流配置

workflows/operators.gxl - 工作流定义

operators.gxl 使用 GXL 语言定义模块的运维操作流程，包括安装、配置、启动、停止等任务。

基本结构

// 引入外部模块
extern mod mod_ops {
    git = "https://github.com/galaxy-operators/ops-gxl.git",
    channel = "${GXL_CHANNEL_OPS:main}"
}

// 定义操作符模块
mod operators : empty_operators {
    // 自动加载入口
    #[auto_load(entry)]
    flow __into {
        // 加载配置文件
        gx.read_file(
            file : "./values/_used.json",
            name : "SETTING"
        );
    }

    // 任务定义...
}


#### 常见任务示例

##### 安装任务
```gxl
#[task(name="gops@install")]
flow install {
    };
}

启动任务

#[task(name="gops@start")]
flow start {
}

停止任务

#[task(name="gops@stop")]
flow stop {
}

mod-prj.yml - 项目配置

mod-prj.yml 定义模块的项目级别配置，包括模块信息、构建目标和发布配置。

基本格式

# 模块项目配置
name: postgresql
version: 0.1.0
description: "PostgreSQL 数据库管理模块"
maintainer: "PostgreSQL Team <team@example.com>"
license: "Apache-2.0"

# 测试环境配置
test_envs:
  dep_root: "./test-deps"
  deps: []





## 总结

通过合理配置这些配置文件，可以实现：

1. **标准化管理**：统一的配置结构和命名规范
2. **灵活适配**：多平台和环境支持
3. **版本控制**：完整的版本管理和依赖追踪
4. **自动化**：工作流驱动的运维操作
5. **可维护性**：清晰的配置分层和验证机制

遵循本配置指南，可以开发出高质量、可维护、可扩展的 Mod-Operator 模块。

Mod-Operator API 和枚举参考

本文档提供 Mod-Operator 的 API 接口、枚举定义和数据结构参考，是开发者进行二次开发和功能扩展的重要指南。

模块 API

ModuleSpec 接口

模块的核心数据结构，定义了模块的基本信息和支持的目标平台。

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Getters)]
pub struct ModuleSpec {
    /// 模块名称
    name: String,

    /// 目标平台配置映射
    targets: IndexMap<ModelSTD, ModModelSpec>,

    /// 本地化路径
    local: Option<PathBuf>,
}

impl ModuleSpec {
    /// 创建新模块
    pub fn init<S: Into<String>>(name: S, target_vec: Vec<ModModelSpec>) -> Self

    /// 清理其他平台配置
    pub fn clean_other(&mut self, node: &ModelSTD) -> MainResult<()>

    /// 保存主要配置
    pub fn save_main(&self, path: &Path, name: Option<String>) -> MainResult<()>
}
}

方法详解

方法	参数	返回值	说明
`init`	`name: String`, `target_vec: Vec<ModModelSpec>`	`ModuleSpec`	创建新的模块实例
`clean_other`	`node: &ModelSTD`	`MainResult<()>`	清理指定平台外的其他平台配置
`save_main`	`path: &Path`, `name: Option<String>`	`MainResult<()>`	保存模块主要配置文件

使用示例

#![allow(unused)]
fn main() {
// 创建模块
let targets = vec![
    ModModelSpec::init(
        ModelSTD::x86_ubt22_k8s(),
        ArtifactPackage::default(),
        ModWorkflows::mod_k8s_tpl_init(),
        GxlProject::spec_k8s_tpl(),
        VarCollection::default(),
        None,
    ),
    ModModelSpec::init(
        ModelSTD::arm_mac14_host(),
        ArtifactPackage::default(),
        ModWorkflows::mod_host_tpl_init(),
        GxlProject::spec_host_tpl(),
        VarCollection::default(),
        None,
    ),
];

let module_spec = ModuleSpec::init("postgresql", targets);

// 清理其他平台
module_spec.clean_other(&ModelSTD::x86_ubt22_k8s());
}

ModModelSpec 接口

模型规格定义，包含模块的具体实现配置。

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Getters)]
pub struct ModModelSpec {
    /// 模型标准
    model: ModelSTD,

    /// 构件包定义
    artifact_pkg: ArtifactPackage,

    /// 工作流定义
    workflows: ModWorkflows,

    /// GXL 项目配置
    prj: GxlProject,

    /// 变量集合
    vars: VarCollection,

    /// 设置配置
    setting: Option<Setting>,
}

impl ModModelSpec {
    /// 创建新的模型规格
    pub fn init(
        model: ModelSTD,
        artifact_pkg: ArtifactPackage,
        workflows: ModWorkflows,
        prj: GxlProject,
        vars: VarCollection,
        setting: Option<Setting>,
    ) -> Self

    /// 更新本地配置
    pub async fn update_local(
        &self,
        accessor: Accessor,
        path: &Path,
        options: &DownloadOptions,
    ) -> MainResult<UpdateUnit>

    /// 本地化处理
    pub async fn localize(
        &self,
        dst_path: Option<ValuePath>,
        options: LocalizeOptions,
    ) -> MainResult<()>

    /// 保存配置
    pub fn save_to(&self, path: &Path, name: Option<String>) -> SerdeResult<()>

    /// 从文件加载
    pub fn load_from(path: &Path) -> SerdeResult<Self>
}
}

主要方法

方法	参数	说明
`init`	`model`, `artifact_pkg`, `workflows`, `prj`, `vars`, `setting`	创建模型规格实例
`update_local`	`accessor`, `path`, `options`	更新本地构件配置
`localize`	`dst_path`, `options`	执行本地化处理
`save_to`	`path`, `name`	保存配置到文件
`load_from`	`path`	从文件加载配置

枚举定义

ModelSTD 标准型号

模型标准定义，包含 CPU 架构、操作系统和运行环境。

#![allow(unused)]
fn main() {
/// CPU 架构枚举
pub enum CpuArch {
    /// x86_64 架构
    X86,
    /// ARM 架构
    Arm,
}

/// 操作系统枚举
pub enum OsCPE {
    /// macOS 14+
    MAC14,
    /// Windows 10+
    WIN10,
    /// Ubuntu 22.04
    UBT22,
    /// CentOS 7
    COS7,
}

/// 运行环境枚举
pub enum RunSPC {
    /// 宿主机环境
    Host,
    /// Kubernetes 环境
    K8S,
}

/// 模型标准结构
#[derive(Debug, Clone, PartialEq, Eq, Hash, Getters)]
pub struct ModelSTD {
    /// CPU 架构
    arch: CpuArch,
    /// 操作系统
    os: OsCPE,
    /// 运行环境
    spc: RunSPC,
}
}

常用预定义实例

#![allow(unused)]
fn main() {
// 主流平台组合
impl ModelSTD {
    /// x86 + Ubuntu 22.04 + Kubernetes
    pub fn x86_ubt22_k8s() -> Self

    /// x86 + Ubuntu 22.04 + Host
    pub fn x86_ubt22_host() -> Self

    /// ARM + macOS 14 + Host
    pub fn arm_mac14_host() -> Self

    /// ARM + Ubuntu 22.04 + Host
    pub fn arm_ubt22_host() -> Self
}
}

Artifact 枚举

构件类型和状态枚举。

#![allow(unused)]
fn main() {
/// 构件类型
pub enum ArtifactType {
    /// HTTP/HTTPS 下载
    Http,
    /// Git 仓库
    Git,
    /// 本地文件
    Local,
    /// 容器镜像
    Container,
}

/// 构件状态
pub enum ArtifactStatus {
    /// 待下载
    Pending,
    /// 下载中
    Downloading,
    /// 已下载
    Downloaded,
    /// 解压中
    Extracting,
    /// 已解压
    Extracted,
    /// 已安装
    Installed,
    /// 错误
    Error,
}
}

枚举比较和转换

#![allow(unused)]
fn main() {
// 枚举比较
impl PartialEq for CpuArch {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (CpuArch::X86, CpuArch::X86) => true,
            (CpuArch::Arm, CpuArch::Arm) => true,
            _ => false,
        }
    }
}

// 枚举转字符串
impl ToString for CpuArch {
    fn to_string(&self) -> String {
        match self {
            CpuArch::X86 => "x86".to_string(),
            CpuArch::Arm => "arm".to_string(),
        }
    }
}

// 字符串转枚举
impl FromStr for CpuArch {
    type Err = ParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "x86" | "x86_64" | "amd64" => Ok(CpuArch::X86),
            "arm" | "aarch64" => Ok(CpuArch::Arm),
            _ => Err(ParseError::InvalidCpuArch(s.to_string())),
        }
    }
}
}

数据结构

ArtifactPackage 构件包

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize, Getters)]
pub struct ArtifactPackage {
    /// 构件列表
    artifacts: Vec<Artifact>,
}

impl ArtifactPackage {
    /// 创建默认构件包
    pub fn default() -> Self

    /// 从构件列表创建
    pub fn from(artifacts: Vec<Artifact>) -> Self

    /// 获取所有构件
    pub fn artifacts(&self) -> &Vec<Artifact>

    /// 添加构件
    pub fn add_artifact(&mut self, artifact: Artifact)

    /// 移除构件
    pub fn remove_artifact(&mut self, name: &str) -> Option<Artifact>

    /// 查找构件
    pub fn find_artifact(&self, name: &str) -> Option<&Artifact>

    /// 验证构件包
    pub fn validate(&self) -> Result<(), ValidationError>
}
}

VarCollection 变量集合

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize, Getters)]
pub struct VarCollection {
    /// 变量定义列表
    vars: Vec<VarDefinition>,
}

impl VarCollection {
    /// 定义变量
    pub fn define(vars: Vec<VarDefinition>) -> Self

    /// 添加变量
    pub fn add_var(&mut self, var: VarDefinition)

    /// 获取变量
    pub fn get_var(&self, name: &str) -> Option<&VarDefinition>

    /// 设置变量值
    pub fn set_value(&mut self, name: &str, value: String) -> Result<(), VarError>

    /// 解析变量值
    pub fn resolve_value(&self, name: &str, context: &Context) -> Result<String, VarError>

    /// 验证变量
    pub fn validate(&self) -> Result<(), VarError>
}
}

GxlProject GXL 项目

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize, Getters)]
pub struct GxlProject {
    /// 项目名称
    name: String,

    /// 工作流定义
    workflows: HashMap<String, GxlWorkflow>,

    /// 项目配置
    config: HashMap<String, Value>,
}

impl GxlProject {
    /// 创建项目配置模板
    pub fn spec_k8s_tpl() -> Self

    /// 创建主机配置模板
    pub fn spec_host_tpl() -> Self

    /// 添加工作流
    pub fn add_workflow(&mut self, name: String, workflow: GxlWorkflow)

    /// 获取工作流
    pub fn get_workflow(&self, name: &str) -> Option<&GxlWorkflow>

    /// 执行工作流
    pub async fn execute_workflow(
        &self,
        name: &str,
        context: &Context,
    ) -> Result<WorkflowResult, WorkflowError>
}
}

工作流 API

GxlWorkflow GXL 工作流

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GxlWorkflow {
    /// 工作流名称
    name: String,

    /// 工作流描述
    description: Option<String>,

    /// 任务列表
    tasks: Vec<GxlTask>,

    /// 变量定义
    variables: HashMap<String, GxlVariable>,

    /// 条件分支
    conditions: Vec<GxlCondition>,

    /// 错误处理
    error_handler: Option<GxlErrorHandler>,
}

impl GxlWorkflow {
    /// 创建工作流
    pub fn new(name: String) -> Self

    /// 添加任务
    pub fn add_task(&mut self, task: GxlTask)

    /// 添加条件分支
    pub fn add_condition(&mut self, condition: GxlCondition)

    /// 设置错误处理器
    pub fn set_error_handler(&mut self, handler: GxlErrorHandler)

    /// 验证工作流
    pub fn validate(&self) -> Result<(), WorkflowError>

    /// 执行工作流
    pub async fn execute(&self, context: &mut Context) -> Result<WorkflowResult, WorkflowError>
}
}

GxlTask GXL 任务

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum GxlTask {
    /// 命令任务
    Command(GxlCommandTask),

    /// 脚本任务
    Script(GxlScriptTask),

    /// 模板渲染任务
    Template(GxlTemplateTask),

    /// 下载任务
    Download(GxlDownloadTask),

    /// 并行任务
    Parallel(GxlParallelTask),

    /// 条件任务
    Conditional(GxlConditionalTask),

    /// 循环任务
    Loop(GxlLoopTask),
}
}

任务执行上下文

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct Context {
    /// 变量存储
    variables: HashMap<String, Value>,

    /// 工作目录
    working_dir: PathBuf,

    /// 执行状态
    status: ExecutionStatus,

    /// 错误收集
    errors: Vec<ExecutionError>,

    /// 日志输出
    logs: Vec<LogEntry>,
}

impl Context {
    /// 创建新上下文
    pub fn new() -> Self

    /// 设置变量
    pub fn set_var(&mut self, name: String, value: Value)

    /// 获取变量
    pub fn get_var(&self, name: &str) -> Option<&Value>

    /// 执行命令
    pub async fn execute_command(&mut self, cmd: &str) -> Result<CommandResult, CommandError>

    /// 添加日志
    pub fn add_log(&mut self, level: LogLevel, message: String)

    /// 保存状态
    pub fn save_state(&self) -> Result<StateSnapshot, StateError>

    /// 恢复状态
    pub fn restore_state(&mut self, state: &StateSnapshot) -> Result<(), StateError>
}
}

配置文件格式

YAML 配置验证

#![allow(unused)]
fn main() {
/// 配置验证器
pub struct ConfigValidator;

impl ConfigValidator {
    /// 验证 artifact.yml
    pub fn validate_artifact(yaml_content: &str) -> Result<Vec<Artifact>, ConfigError>

    /// 验证 depends.yml
    pub fn validate_depends(yaml_content: &str) -> Result<DependsConfig, ConfigError>

    /// 验证 vars.yml
    pub fn validate_vars(yaml_content: &str) -> Result<VarCollection, ConfigError>

    /// 验证 setting.yml
    pub fn validate_setting(yaml_content: &str) -> Result<Setting, ConfigError>

    /// 验证 mod-prj.yml
    pub fn validate_project(yaml_content: &str) -> Result<ProjectConfig, ConfigError>
}
}

配置生成器

#![allow(unused)]
fn main() {
/// 配置文件生成器
pub struct ConfigGenerator;

impl ConfigGenerator {
    /// 生成 artifact.yml
    pub fn generate_artifact(artifacts: &[Artifact]) -> String

    /// 生成 depends.yml
    pub fn generate_depends(deps: &[Dependency]) -> String

    /// 生成 vars.yml
    pub fn generate_vars(vars: &[VarDefinition]) -> String

    /// 生成 setting.yml
    pub fn generate_setting(setting: &Setting) -> String

    /// 生成 mod-prj.yml
    pub fn generate_project(project: &ProjectConfig) -> String
}
}

错误代码

错误类型定义

#![allow(unused)]
fn main() {
/// 系统错误
#[derive(Debug, Error)]
pub enum SystemError {
    #[error("配置解析错误: {0}")]
    ConfigParse(String),

    #[error("文件操作错误: {0}")]
    FileOperation(String),

    #[error("网络错误: {0}")]
    Network(String),

    #[error("进程错误: {0}")]
    Process(String),

    #[error("权限错误: {0}")]
    Permission(String),

    #[error("资源不足: {0}")]
    Resource(String),
}

/// 业务错误
#[derive(Debug, Error)]
pub enum BusinessError {
    #[error("模块不存在: {0}")]
    ModuleNotFound(String),

    #[error("任务执行失败: {0}")]
    TaskFailed(String),

    #[error("验证失败: {0}")]
    ValidationFailed(String),

    #[error("状态错误: {0}")]
    InvalidState(String),

    #[error("依赖冲突: {0}")]
    DependencyConflict(String),
}
}

错误处理模式

#![allow(unused)]
fn main() {
/// 错误处理结果
pub type Result<T> = std::result::Result<T, Error>;

/// 错误处理工具
pub struct ErrorHandler;

impl ErrorHandler {
    /// 记录错误
    pub fn log_error(error: &Error) {
        // 记录错误日志
    }

    /// 错误恢复
    pub fn recover(context: &mut Context, error: &Error) -> Result<()> {
        // 执行错误恢复操作
        Ok(())
    }

    /// 错误通知
    pub fn notify(error: &Error) -> Result<()> {
        // 发送错误通知
        Ok(())
    }
}
}

API 使用示例

创建自定义模块

use galaxy_ops::{
    artifact::{Artifact, ArtifactPackage},
    model::{ModelSTD, CpuArch, OsCPE, RunSPC},
    module::ModuleSpec,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 定义目标平台
    let target_platforms = vec![
        ModelSTD::x86_ubt22_k8s(),
        ModelSTD::arm_mac14_host(),
    ];

    // 创建构件包
    let artifacts = vec![
        Artifact::new(
            "nginx",
            "1.25.3",
            "https://nginx.org/download/nginx-1.25.3.tar.gz".parse()?,
            "nginx-1.25.3.tar.gz",
        ),
        Artifact::new(
            "openssl",
            "3.0.0",
            "https://github.com/openssl/openssl.git".parse()?,
            "openssl-3.0.0",
        ),
    ];

    let artifact_pkg = ArtifactPackage::from(artifacts);

    // 为每个平台创建模型规格
    let mut target_specs = Vec::new();
    for platform in target_platforms {
        let model_spec = ModModelSpec::init(
            platform.clone(),
            artifact_pkg.clone(),
            ModWorkflows::mod_k8s_tpl_init(),
            GxlProject::spec_k8s_tpl(),
            VarCollection::define(vec![
                VarDefinition::new("MODULE_NAME", "nginx"),
                VarDefinition::new("VERSION", "1.25.3"),
            ]),
            None,
        );

        target_specs.push(model_spec);
    }

    // 创建模块规格
    let module_spec = ModuleSpec::init("nginx-server", target_specs);

    // 保存模块配置
    module_spec.save_main(&std::path::Path::new("./nginx"), Some("nginx".to_string()))?;

    println!("自定义模块创建成功");
    Ok(())
}

错误处理示例

#![allow(unused)]
fn main() {
use galaxy_ops::{error::{SystemError, BusinessError}, workflow::Context};

fn handle_error(context: &mut Context, error: &dyn std::error::Error) {
    match error.downcast_ref::<SystemError>() {
        Some(sys_error) => {
            match sys_error {
                SystemError::ConfigParse(msg) => {
                    eprintln!("配置解析错误: {}", msg);
                    // 执行配置错误恢复
                    ConfigErrorHandler::recover(context, msg);
                }
                SystemError::FileOperation(msg) => {
                    eprintln!("文件操作错误: {}", msg);
                    // 执行文件错误恢复
                    FileErrorHandler::recover(context, msg);
                }
                SystemError::Network(msg) => {
                    eprintln!("网络错误: {}", msg);
                    // 执行网络错误恢复
                    NetworkErrorHandler::recover(context, msg);
                }
                _ => {
                    eprintln!("未知系统错误: {}", msg);
                }
            }
        }
        None => {
            match error.downcast_ref::<BusinessError>() {
                Some(biz_error) => {
                    match biz_error {
                        BusinessError::ModuleNotFound(msg) => {
                            eprintln!("模块不存在: {}", msg);
                            ModuleErrorHandler::recover(context, msg);
                        }
                        BusinessError::TaskFailed(msg) => {
                            eprintln!("任务执行失败: {}", msg);
                            TaskErrorHandler::recover(context, msg);
                        }
                        BusinessError::ValidationFailed(msg) => {
                            eprintln!("验证失败: {}", msg);
                            ValidationErrorHandler::recover(context, msg);
                        }
                        _ => {
                            eprintln!("未知业务错误: {}", msg);
                        }
                    }
                }
                None => {
                    eprintln!("未分类错误: {}", error);
                }
            }
        }
    }
}
}

总结

本 API 参考文档提供了 Mod-Operator 框架的完整接口和功能说明，包括：

模块管理 API - 用于创建和管理模块实例
枚举定义 - 标准化的平台和类型定义
数据结构 - 核心配置和数据类型
工作流 API - 任务执行和流程控制
配置处理 - 配置文件的验证和生成
错误处理 - 完善的错误处理机制
环境变量 - 系统和用户配置变量
实用示例 - 常见场景的实现示例

通过这些 API，开发者可以：

创建自定义模块类型
扩展工作流功能
自定义配置验证
实现高级监控功能
集成第三方系统

建议开发者在使用前仔细阅读相关章节，并根据实际需求选择合适的 API 接口。

Mod-Operator 故障排除指南

本文档提供 Mod-Operator 常见问题的诊断步骤、解决方案和调试技巧，帮助开发者快速定位和解决问题。

配置

📖 NetAccessCtrl 简约配置指南（非开发者版）

什么是 NetAccessCtrl？

NetAccessCtrl 是一个网络访问控制模块，可以在使用orino_variate 时自动将您的网络请求重定向到更快的镜像服务器，支持认证、超时设置和代理配置。它可以帮助您：

🚀 加速 GitHub、GitLab 等国外服务访问
🔐 安全管理认证信息
⏱️ 控制网络请求超时时间
🌐 配置代理服务器
📝 使用环境变量动态配置

快速开始

1. 创建配置文件

在您的项目根目录创建 net-accessor_ctrl.yaml 文件：

# 基础配置示例
enable: true
units:
  - rules:
      - pattern: "https://github.com/*"
        target: "https://mirror.ghproxy.com/"
    # 可选：添加认证信息
    auth:
      username: "your_username"
      password: "your_token"

2. 常用场景配置

GitHub 加速访问

enable: true
units:
  - rules:
      - pattern: "https://github.com/*"
        target: "https://mirror.ghproxy.com/"
      - pattern: "https://raw.githubusercontent.com/*"
        target: "https://raw.ghproxy.com/"

GitLab 镜像

enable: true
units:
  - rules:
      - pattern: "https://gitlab.com/*"
        target: "https://gitlab-mirror.com/"

NPM 包管理器加速

enable: true
units:
  - rules:
      - pattern: "https://registry.npmjs.org/*"
        target: "https://registry.npmmirror.com/"

3. 完整配置示例

enable: true
units:
  # GitHub 配置
  - rules:
      - pattern: "https://github.com/*"
        target: "https://ghproxy.com/"
      - pattern: "https://raw.githubusercontent.com/*"
        target: "https://raw.ghproxy.com/"
    auth:
      username: "${GITHUB_USER}"
      password: "${GITHUB_TOKEN}"
    timeout:
      connect-timeout: 30
      read-timeout: 60
      total-timeout: 300
    proxy:
      url: "http://proxy.company.com:8080"

  # 其他服务配置
  - rules:
      - pattern: "https://api.example.com/*"
        target: "https://internal-api.example.com/"

配置参数说明

基本参数

enable: true 或 false，是否启用网络访问控制
units: 配置单元列表，每个单元包含重定向规则和配置

单元配置 (units)

每个 unit 包含：

rules: 重定向规则列表
auth: 可选的认证信息（用户名和密码）
timeout: 可选的超时设置
proxy: 可选的代理配置

规则配置 (rules)

每个 rule 包含：

pattern: 要匹配的URL模式（支持 * 通配符）
target: 重定向的目标地址

环境变量支持

您可以使用环境变量来动态配置，避免硬编码敏感信息：

enable: true
units:
  - rules:
      - pattern: "https://${GITHUB_DOMAIN:github.com}/*"
        target: "https://${MIRROR_DOMAIN:ghproxy.com}/"
    auth:
      username: "${GITHUB_USER}"
      password: "${GITHUB_TOKEN}"
    proxy:
      url: "${PROXY_URL:http://proxy.default:8080}"

环境变量语法：

${VARIABLE_NAME}: 使用环境变量
${VARIABLE_NAME:default_value}: 使用环境变量，如果不存在则使用默认值

使用方法

1. 设置环境变量（可选）

# Linux/Mac
export GITHUB_USER="your_username"
export GITHUB_TOKEN="your_token"
export PROXY_URL="http://proxy.company.com:8080"

# Windows
set GITHUB_USER=your_username
set GITHUB_TOKEN=your_token
set PROXY_URL=http://proxy.company.com:8080

2. 将配置文件放在正确位置

系统级配置：/etc/net-access.yaml
用户级配置：~/.config/net-access.yaml
项目级配置：项目根目录/net-access.yaml

3. 验证配置

配置完成后，您可以通过以下方式验证是否生效：

# 测试 GitHub 访问
curl -I "https://github.com/user/repo/releases"

# 查看是否重定向到镜像服务器

常见问题

Q: 如何添加多个镜像服务器？

A: 在 units 中添加多个配置单元，系统会按顺序尝试：

enable: true
units:
  # 第一个镜像
  - rules:
      - pattern: "https://github.com/*"
        target: "https://mirror1.github.com/"

  # 备用镜像
  - rules:
      - pattern: "https://github.com/*"
        target: "https://mirror2.github.com/"

Q: 如何设置不同的超时时间？

A: 在 timeout 部分配置：

timeout:
  connect-timeout: 30    # 连接超时（秒）
  read-timeout: 60       # 读取超时（秒）
  total-timeout: 300     # 总超时（秒）

Q: 如何处理认证？

A: 在 auth 部分配置用户名和密码，推荐使用环境变量：

auth:
  username: "${YOUR_USERNAME}"
  password: "${YOUR_PASSWORD}"

Q: 配置不生效怎么办？

A: 检查以下几点：

确保 enable: true
检查配置文件路径是否正确
验证 YAML 语法是否正确
检查 URL 模式是否匹配

Q: 如何配置代理？

A: 在 proxy 部分配置：

proxy:
  url: "http://proxy.example.com:8080"

Q: 支持哪些通配符？

A: 目前支持 * 通配符，可以匹配任意字符序列。例如：

https://github.com/* 匹配所有 GitHub 地址
https://raw.githubusercontent.com/* 匹配所有 GitHub 原始文件地址

配置示例合集

常用镜像服务

GitHub 全家桶加速

enable: true
units:
  - rules:
      - pattern: "https://github.com/*"
        target: "https://ghproxy.com/"
      - pattern: "https://raw.githubusercontent.com/*"
        target: "https://raw.ghproxy.com/"
      - pattern: "https://gist.github.com/*"
        target: "https://gist.ghproxy.com/"

Python 包管理器 (PyPI)

enable: true
units:
  - rules:
      - pattern: "https://pypi.org/*"
        target: "https://pypi.doubanio.com/"

Docker 镜像加速

enable: true
units:
  - rules:
      - pattern: "https://registry-1.docker.io/*"
        target: "https://dockerhub.azk8s.cn/"

RubyGems 加速

enable: true
units:
  - rules:
      - pattern: "https://rubygems.org/*"
        target: "https://gems.ruby-china.com/"

企业内部配置

内部服务映射

enable: true
units:
  - rules:
      - pattern: "https://external-api.company.com/*"
        target: "https://internal-api.company.com/"
    auth:
      username: "${INTERNAL_API_USER}"
      password: "${INTERNAL_API_PASSWORD}"
    timeout:
      connect-timeout: 10
      read-timeout: 30
      total-timeout: 60

多环境配置

# 开发环境配置
enable: ${ENABLE_NET_ACCESS:true}
units:
  - rules:
      - pattern: "https://api.${ENV:dev}.company.com/*"
        target: "http://localhost:8080/"
    timeout:
      connect-timeout: 5
      read-timeout: 15
      total-timeout: 30

最佳实践

安全性建议

使用环境变量: 避免在配置文件中硬编码敏感信息
设置文件权限: 确保配置文件只有授权用户可读
```
chmod 600 net-access.yaml
```
定期更新认证信息: 定期更换密码和访问令牌
使用 HTTPS: 确保所有目标地址使用 HTTPS 协议

性能优化建议

规则排序: 将最常用的规则放在前面
合理设置超时: 根据网络环境调整超时时间
使用就近镜像: 选择地理位置较近的镜像服务器
避免过度重定向: 不要配置过多的重定向层级

维护建议

版本控制: 将配置文件纳入版本控制（排除敏感信息）
文档记录: 记录配置文件的用途和变更历史
定期测试: 定期测试配置是否仍然有效
备份配置: 保留配置文件的备份

获取帮助

如果遇到问题，可以通过以下方式获取帮助：

检查清单

在寻求帮助前，请先检查：

配置文件语法是否正确
环境变量是否正确设置
网络连接是否正常
认证信息是否有效
目标服务器是否可访问

常见资源

YAML 语法验证: https://www.yamllint.com/
环境变量设置指南: 搜索 "环境变量设置 [您的操作系统]"
网络连接测试: 使用 ping 和 curl 命令测试
镜像服务状态: 查看镜像服务的官方状态页面

联系支持

如果以上方法都无法解决问题，请联系技术支持并提供以下信息：

操作系统和版本
配置文件内容（去除敏感信息）
错误信息或日志
重现问题的步骤

附录

配置文件模板

基础模板

# NetAccessCtrl 基础配置模板
enable: true
units:
  - rules:
      - pattern: "https://example.com/*"
        target: "https://mirror.example.com/"

完整模板

# NetAccessCtrl 完整配置模板
enable: true
units:
  - rules:
      - pattern: "https://service1.com/*"
        target: "https://mirror1.service1.com/"
      - pattern: "https://service2.com/*"
        target: "https://mirror2.service2.com/"
    auth:
      username: "${SERVICE1_USER}"
      password: "${SERVICE1_PASSWORD}"
    timeout:
      connect-timeout: 30
      read-timeout: 60
      total-timeout: 300
    proxy:
      url: "${PROXY_URL:http://proxy.default:8080}"

  - rules:
      - pattern: "https://another-service.com/*"
        target: "https://internal.another-service.com/"
    # 此单元无认证、超时和代理配置

常用镜像服务器列表

服务类型	原地址	推荐镜像地址
GitHub	`https://github.com/*`	`https://ghproxy.com/`
GitHub Raw	`https://raw.githubusercontent.com/*`	`https://raw.ghproxy.com/`
PyPI	`https://pypi.org/*`	`https://pypi.doubanio.com/`
NPM	`https://registry.npmjs.org/*`	`https://registry.npmmirror.com/`
Docker Hub	`https://registry-1.docker.io/*`	`https://dockerhub.azk8s.cn/`
RubyGems	`https://rubygems.org/*`	`https://gems.ruby-china.com/`

注意：镜像服务地址可能会发生变化，请以最新信息为准。

快速开始总结：

创建 net-access.yaml 文件
复制相应场景的配置示例
设置环境变量（可选）
放置配置文件到正确位置
验证配置是否生效

祝您使用愉快！🎉

GXL 语法

flow

示例

简单使用

#![allow(unused)]
fn main() {
flow test {
  gx.echo (  "hello world" );
}
}

增加描述

#![allow(unused)]
fn main() {
#[usage(desp="test flow")]
flow test() {
  gx.echo (  "hello world" );
}
}

编排

#![allow(unused)]
fn main() {
flow head {
  gx.echo ( "head"; )
}
flow tail {
  gx.echo ( "tail"; )
}

// 执行过程为: test -> head -> tail
flow  @test | head | tail  { }
flow  test | head | tail  { }


// 执行过程为: head -> tail -> test
flow  | head | tail  |@test { }

//执行过程为: head -> test -> tail
flow  head | @test | tail {
  gx.echo ( "test"; )
}
}

定义

#![allow(unused)]
fn main() {
  flow [ <flows>|]  @<flow_name>  [|<flows>] {
  }
}

分支

#![allow(unused)]
fn main() {
mod main {
  api = "1.0"
  flow conf {
    if  ${API} == "1.0" {
        gx.echo ( value : "this is if true cond " );
    }
    else {
        gx.echo ( value : "this is if false cond" );
    }
  }
}
}

通配比较

#![allow(unused)]
fn main() {
mod main {
  api = "1.0"
  flow conf {
    if  ${API} =* "1*" {
        gx.echo ( value : "this is if true cond " );
    }
    else {
        gx.echo ( value : "this is if false cond" );
    }
  }
}
}

mod

mod 是顶级的组织结构

只有 envs,main 两个mod 中的 env 和 flow cli 直接load

#![allow(unused)]
fn main() {
mod envs {
  prop1 = "prop1"
  env dev {}
}
mod main {
  prop1 = "prop1"
  flow test {}
}
}

执行

#![allow(unused)]
fn main() {
gflow -e dev test 
}

示例

#![allow(unused)]
fn main() {
}

Activity

包装shell 成为 activity

#![allow(unused)]
fn main() {
 activity copy {
     src = "" ;
     dst = "" ;
     log = "1" ;
     out = "true"
     executer = "copy_act.sh" ;
}
}

变量定义

示例

#![allow(unused)]
fn main() {
    one= "one";
    sys_a = { mod1 : "A", mod2 : "B" , mod3: 1 , mod4 : 2};
    sys_b =  [ "C", "D" ];
    sys_c = ${SYS_B[1]} ;
    sys_d = ${SYS_A.MOD1} ;
}

使用示例

#![allow(unused)]
fn main() {
mod envs {
    env default   {
      data_list =  [ "JAVA", "RUST", "PYTHON"] ;
      data_obj =  { 
        JAVA : { NAME: "JAVA", SCORE: 80 }, 
        RUST : { NAME: "RUST", SCORE: 100 }, 
        PYTHON : { NAME: "PYTHON", SCORE: 200} 
        } ;
    }
}
mod main   {
  flow array_do{
    for ${CUR} in ${ENV_DATA_LIST} {
      gx.echo( "CUR:${CUR}" );
    }
  }
  flow obj_do{
    for ${CUR} in ${ENV_DATA_OBJ} {
      gx.echo( "CUR:${CUR.NAME} : ${CUR.SCORE}" );
    }
  }

}
}

内置常量

GXL_PRJ_ROOT: 最近定义了 _gal/project.toml 的目录
GXL_START_ROOT: GXL 启动处理的目录
GXL_CUR_DIR: GXL 当前所在目录，在调用gx.run时，与GXL_START_ROOT可能不同
GXL_CMD_ARG: gflow -- <cmd_arg>

flow

注解

task (v0.6.0)

#![allow(unused)]
fn main() {
#[task(name="setup")]
flow setup{
    ...
}
}

dryrun (v0.7.0)

#[dryrun(_pub_dryrun)]
flow _pub_dysec {
    ...
}
flow _pub_dryrun {
    ...
}

transcation undo (v0.7.0)

flow trans1 | step1 | step2 | step3 ;
  #[transaction,undo(_undo_step1)]
  flow step1 {
    gx.echo (" step1 ");
  }
  #[undo(_undo_step2)]
  flow step2 {
    gx.echo (" step2 ");
  }
  #[undo(_undo_step3)]
  flow step3 {
    gx.echo (" step3 ");
    gx.assert ( value : "true" , expect : "false" );
  }

  flow _undo_step1 {
    gx.echo (" undo step1 ");
  }
  flow _undo_step2 {
    gx.echo (" undo step2 ");
  }
  flow _undo_step3 {
    gx.echo (" undo step3 ");
  }

usage

#![allow(unused)]
fn main() {
#[usage(desp="test")]
flow test_1 {

}
}

auto_load

#![allow(unused)]
fn main() {
#[auto_load(entry,exit)] 

//entry: 进入flow 
//exit : 退出flow
示例:

mod main {

  flow start {
    gx.echo ( value : "hello" );
  }
  #[auto_load(entry)]
  flow conf {
    gx.echo ( value : "hello" );
  }
}
}

defined

#![allow(unused)]
fn main() {
    if defined(${PRJ_ROOT}) {
        gx.echo (  "${PRJ_ROOT}/test/main.py"  );
        }
        else {
        gx.echo (  "${PRJ_ROOT}/test/main.py"  );
    }
}

GXL 文件语法

GXL 语法定义

GXL（Galaxy Flow Language）是一种为 DevSecOps 自动化工作流设计的领域特定语言。根据代码库中的信息，GXL 的语法定义主要在 galaxy-sec/galaxy-flow 仓库的解析器模块中实现。

GXL 语法结构

GXL 语言遵循模块化、层次化的结构，主要由以下核心组件组成：

模块（Modules）：使用 mod 关键字定义，是 GXL 的顶层组织单元
环境（Environments）：使用 env 关键字定义，用于配置不同的执行上下文
流程（Flows）：使用 flow 关键字定义，表示工作流程序
活动（Activities）：可重用的操作单元，在流程中调用

EBNF 语法


; GXL 文件由一系列模块定义组成
GXL-File = *Module


(* GXL 文件由一系列模块定义组成 *)
GXL-File = {Module};

(* 模块定义 *)
Module = "mod", whitespace, ModuleName, whitespace, "{", whitespace, ModuleContent, whitespace, "}", whitespace, ";";
ModuleName = Identifier;
ModuleContent = {Property | Environment | Flow};

(* 属性定义 (键值对) *)
Property = PropertyName, whitespace, "=", whitespace, PropertyValue, whitespace, ";";
PropertyName = Identifier;
PropertyValue = String;

(* 环境定义 *)
Environment = "env", whitespace, EnvName, [whitespace, ":", whitespace, EnvRefList], whitespace, "{", whitespace, EnvContent, whitespace, "}";
EnvName = Identifier;
EnvContent = {Property};
EnvRefList = EnvRef, {",", whitespace, EnvRef};
EnvRef = Identifier;

(* 流程定义 - 两种形式：直接定义或引用其他流程 *)
Flow = DirectFlow | ReferenceFlow;

(* 直接定义流程 *)
DirectFlow = "flow", whitespace, FlowName, [whitespace, ":", whitespace, FlowRefList [ whitespace , ":" whitespace, FlowRefList ] ], whitespace, "{", whitespace, FlowContent, whitespace, "}", whitespace, ";";
FlowName = Identifier;
FlowContent = {Command};

(* 引用其他流程 *)
ReferenceFlow = "flow", whitespace, FlowName, whitespace, ":", whitespace, FlowRefList, whitespace, ";";
FlowRefList = FlowRef, {",", whitespace, FlowRef};
FlowRef = Identifier;


(* 命令定义 *)
Command = (BuiltinCommand | ActivityCall), whitespace, ";";

(* 内置命令 *)
BuiltinCommand = "gx.", CommandName, whitespace, "{", whitespace, CommandProps, whitespace, "}";
CommandName = "echo" | "vars" | "cmd" | "read" | "tpl" | "assert" | "ver";
CommandProps = {PropertyAssignment};
PropertyAssignment = PropertyName, whitespace, "=", whitespace, PropertyValue, whitespace,  ",";

(* 活动调用 *)
ActivityCall = ActivityName, whitespace, "{", whitespace, CommandProps, whitespace, "}";
ActivityName = Identifier, {".", Identifier};

(* 标识符 *)
Identifier = Alpha, {Alpha | Digit | "_"};
Alpha = "A" | "B" | ... | "Z" | "a" | "b" | ... | "z";
Digit = "0" | "1" | ... | "9";

(* 字符串 *)
String = '"', {StringChar}, '"';
StringChar = UnescapedChar | EscapedChar;
UnescapedChar = ? 除了 " 和 \ 的任何字符 ?;
EscapedChar = "\", ("\" | '"');

(* 变量引用 *)
VariableRef = "${", VariableName, "}";
VariableName = Identifier;

(* 空白字符 *)
whitespace = {" " | "\t" | "\r" | "\n"};

(* 外部模块引用 *)
ExternModule = "extern", whitespace, "mod", whitespace, ModuleNameList, whitespace, "{", whitespace, ModuleSource, whitespace, "}", whitespace, ";";
ModuleNameList = ModuleName, {",", whitespace, ModuleName};
ModuleSource = PathSource | GitSource;
PathSource = "path", whitespace, "=", whitespace, String;
GitSource = "git", whitespace, "=", whitespace, String, whitespace, ",", whitespace, "channel", whitespace, "=", whitespace, String;


(* 注解 *)
Annotation = "#[", AnnotationName, ("(", AnnotationParams, ")")?, "]";
AnnotationName = Identifier;
AnnotationParams = AnnotationParam, {",", whitespace, AnnotationParam};
AnnotationParam = Identifier, whitespace, "=", whitespace, String;

示例

#![allow(unused)]
fn main() {
env dev {
	root = "${HOME}/my_project";
	gx.read_cmd {
		name = "MY_PATH" ;
		cmd  = "pwd" ;
	};
}
}

#![allow(unused)]
fn main() {
mod my_module {
    -- 模块属性
    author = "John Doe";
    version = "1.0";

    -- 环境定义
    env test {
        root = "${HOME}/test_project";
        gx.read_cmd {
            name = "TEST_PATH";
            cmd = "ls";
        };
    }

    -- 流程定义
    flow my_flow {
        step1 = "execute_task";
        task1.run {
            param1 = "value1";
            param2 = "value2";
        };
    }
}
}

示例

Assert 示例

示例代码

#![allow(unused)]
fn main() {
extern mod os { path= "../../_gal/mods"; }
mod base_env {
    env _common {
      gx.vars {
        DOMAIN    = "domain" ;
      }
    }
    env cli : _common {
      ROOT   = "./";

    }
    env unit_test : _common {
      ROOT   = "./example";
    }
}
mod envs : base_env {
    #[usage(desp="default")]
    env default : cli ;
    env empty {}
    env ut : unit_test  ;
}
mod base{
  mod_val = "1";
  flow define {
    base = "BASE";
  }
  #[auto_load(entry)]
  flow base_into  {
    base_begin = "BASE_INTO";
  }
  #[auto_load(exit)]
  flow base_exit {
    base_end = "BASE_EXIT";
  }
}
mod other {
  flow def1 {
    other_val = "OTHER_DEF";
  }
  flow def2{
    other_val = "OTHER_DEF2";
  }
}
mod main   {
  conf = "${ENV_ROOT}/conf" ;

  #[auto_load(entry)]
  flow __into  | other.def1  {
    other_val = "OTHER_DE1";
  }
  #[auto_load(exit)]
  flow __exit | other.def2 ;
  #[usage(desp="main")]
  flow assert_main {
    one= "one";
    sys_a = { mod1 : "A", mod2 : "B" };
    sys_b =  [ "C", "D" ];
    sys_c = ${SYS_B[1]} ;
    sys_d = ${SYS_A.MOD1} ;
    gx.assert ( value : "${MAIN_CONF}" , expect : "${ENV_ROOT}/conf" );
    gx.assert ( value : "${OTHER_VAL}" , expect : "OTHER_DEF" );
    gx.assert ( value : "${SYS_A.MOD1}" , expect : "A" );
    gx.assert ( value : "${sys_a.mod1}" , expect : "A" );
    gx.assert ( value : "${sys_b[0]}" , expect : "C" );
    gx.assert ( value : "${sys_d}" , expect : "A" );
  }

  flow base.define | @assert_parent   {
    gx.assert ( value : "${MAIN_CONF}" , expect : "${ENV_ROOT}/conf" );
    gx.assert ( value : "${BASE_MOD_VAL}" , expect : "1" );
    gx.assert ( value : "${OTHER_VAL}" , expect : "OTHER_DEF" );
    gx.assert ( value : "${BASE}" , expect : "BASE" );
    gx.assert ( value : "${BASE_BEGIN}" , expect : "BASE_INTO" );
  }

}
}

说明

这个示例展示了如何使用 gx.assert 命令进行断言检查。在 assert_main 流程中，多个 gx.assert 命令用于验证变量的值是否符合预期。在 base.define 流程中，也使用了 gx.assert 来验证环境变量和模块变量的值。

graph TD
    A[Start] --> B[Load base_env]
    B --> C[Load envs]
    C --> D[Load base module]
    D --> E[Load other module]
    E --> F[Load main module]
    F --> G[Execute __into flow]
    G --> H[Execute assert_main flow]
    H --> I[Execute gx.assert commands]
    I --> J[Execute base.define flow]
    J --> K[Execute more gx.assert commands]
    K --> L[Execute __exit flow]
    L --> M[End]

Dryrun Example

This example demonstrates the dryrun functionality in GXL.

#![allow(unused)]
fn main() {
mod main {

env default {}

flow _step1 {
    gx.echo ("step1");
}

#[dryrun(_step3)]
flow _step2 {
    gx.echo ("step2");
    gx.assert ( value : "true" , expect : "false" );
}

flow _step3 {
    gx.echo ("dryrun setp2");
}

flow start | _step1 | _step2 ;

}
}

graph TD
    A[Start] --> B[Load main module]
    B --> C[Execute start flow]
    C --> D[Execute _step1 flow]
    D --> E[Execute _step2 flow]
    E --> F{Assertion fails?}
    F -->|Yes| G[Execute _step3 flow]
    F -->|No| H[End]
    G --> I[End]

Fun Example

This example demonstrates how to define and use functions in GXL.

#![allow(unused)]
fn main() {
extern mod os { path = "../../_gal/mods"; }

mod sys {
    fun echo(name) {
        gx.echo("echo:${name}");
    }
    fun echo_obj(obj) {
        gx.echo("echo_obj:${obj}");
    }
    fun echo_list(list) {
        gx.echo("echo_list:${list}");
    }
}

mod envs {
    env default {
        DATA = [
            "JAVA",
            "RUST",
            "PYTHON",
        ];
        OBJ = {
            name: "test",
            value: "value",
        };
    }
}

mod main {
    flow conf {
        sys.echo("test");
        sys.echo_obj("${OBJ}");
        sys.echo_list("${DATA}");
    }
}
}

graph TD
    A[Start] --> B[Load sys module]
    B --> C[Define echo functions]
    C --> D[Load envs module]
    D --> E[Load main module]
    E --> F[Execute conf flow]
    F --> G[Call sys.echo function]
    G --> H[Call sys.echo_obj function]
    H --> I[Call sys.echo_list function]
    I --> J[End]

Read 示例

示例代码

#![allow(unused)]
fn main() {
extern mod os { path= "../../_gal/mods"; }
mod envs {
    env _dev_local {
        gx.read_file ( file : "./var.ini" );
    }
    env default : _dev_local ;
}
mod main   {
  flow conf  {
    gx.echo (  "${RUST}" );
    gx.echo (  "${JAVA}" );
    gx.assert ( value : "${JAVA}" , expect : "90"  );

    gx.read_cmd (
        //fail!
        //cmd  : r#"git branch --show-current |  sed -E "s/(feature|develop|ver-dev|release|master|issue)(\/\.*)?/_branch_\1/g" "# ,
        //suc!
        cmd  : "git branch --show-current | sed -E 's/release/rls/g'" ,
        name : "GIT_BRANCH" );

    gx.echo ( "what:${GIT_BRANCH}" );

    gx.read_file ( file : "./var2.ini" , name : "DATA");

    for ${CUR} in ${DATA} {
        gx.echo ( value : "${CUR}" );
    }
  }



}
}

graph TD
    A[Start] --> B[Load envs module]
    B --> C[Execute _dev_local env]
    C --> D[Execute gx.read_file command]
    D --> E[Load main module]
    E --> F[Execute conf flow]
    F --> G[Execute gx.echo commands]
    G --> H[Execute gx.read_cmd command]
    H --> I[Execute gx.echo command]
    I --> J[Execute gx.read_file command]
    J --> K[Loop through DATA]
    K --> L[Execute gx.echo command for each item]
    L --> M[End]

说明

这个示例展示了如何使用 gx.read 命令从不同来源读取数据。在 _dev_local 环境中，使用 gx.read_file 从 var.ini 文件读取数据。在 conf 流程中，使用 gx.read_cmd 执行 Git 命令并捕获输出，以及使用 gx.read_file 从 var2.ini 文件读取数据。还展示了如何遍历读取的数据。

Shell Example

This example demonstrates how to execute shell commands in GXL.

#![allow(unused)]
fn main() {
extern mod os { path = "../../_gal/mods"; }

mod envs {
    env _dev_local {}
    env default : _dev_local;
}

mod main {
    flow conf {
        gx.read_file(file: "./var.yml", name: "VAR");
        gx.echo("what:${VAR.MEMBER.JAVA}");

        gx.shell(
            arg_file: "./var.json",
            shell: "./demo.sh",
            out_var: "SYS_OUT");

        gx.echo("what:${SYS_OUT}");

        gx.read_file(file: "./var_list.yml", name: "DATA");
        for ${CUR} in ${DATA.DEV_LANG} {
            gx.shell(
                shell: "./demo_ex.sh ${CUR}",
                out_var: "SYS_OUT");
            gx.echo("what:${SYS_OUT}");
        }

        gx.read_file(file: "./var_obj.yml", name: "DATA");
        for ${CUR} in ${DATA} {
            gx.shell(
                shell: "./demo_ex.sh ${CUR.SYS.NAME}",
                out_var: "SYS_OUT");
            gx.echo("what:${SYS_OUT}");
        }
    }
    flow do_obj {
        gx.read_file(file: "./var_obj.yml", name: "DATA");
        for ${CUR} in ${DATA} {
            //gx.echo( "CUR:${CUR.SYS.NAME}" );
            gx.shell(
                shell: "./demo_ex.sh ${CUR.SYS.NAME}",
                out_var: "SYS_OUT");
            gx.echo("what:${SYS_OUT}");
        }
    }
}
}

说明

这个示例展示了如何使用 gx.shell 命令执行 shell 脚本。在 conf 流程中，首先从 var.yml 文件读取数据，然后使用 gx.shell 执行 demo.sh 脚本，并通过 arg_file 参数传递 var.json 文件。还展示了如何在循环中执行 shell 脚本，并处理列表和对象数据。

graph TD
    A[Start] --> B[Load envs module]
    B --> C[Load main module]
    C --> D[Execute conf flow]
    D --> E[Execute gx.read_file command]
    E --> F[Execute gx.echo command]
    F --> G[Execute gx.shell command]
    G --> H[Execute gx.echo command]
    H --> I[Execute gx.read_file command]
    I --> J[Loop through DATA.DEV_LANG]
    J --> K[Execute gx.shell command for each item]
    K --> L[Execute gx.echo command]
    L --> M[Execute gx.read_file command]
    M --> N[Loop through DATA]
    N --> O[Execute gx.shell command for each item]
    O --> P[Execute gx.echo command]
    P --> Q[End]

Template Example

This example demonstrates how to use templates in GXL.

#![allow(unused)]
fn main() {
extern mod os { path = "../../_gal/mods"; }

mod base_env {
    env _common {
        gx.vars {
            DOMAIN = "domain";
            SOCK_FILE = "socket";
            GXL_PRJ_ROOT = "./";
        }
    }
    env cli : _common {
        ROOT = "./";
    }
    env unit_test : _common {
        ROOT = "./example";
    }
}

mod envs : base_env {
    #[usage(desp = "default")]
    env default : cli;
    env empty {}
    env ut : unit_test;
}

mod main {
    conf = "${ENV_ROOT}/conf";
    flow conf {
        os.path(dst: "${MAIN_CONF}/used", keep: "true");
        gx.tpl(
            tpl: "${MAIN_CONF}/tpls/",
            dst: "${MAIN_CONF}/used/",
            file: "${MAIN_CONF}/value.json");

        ```cmd
        echo "hello";
        cp ./conf/value.json ./conf/used/back.json;
        ```
    }
}
}

This example shows how to use the gx.tpl command to process template files. In the conf flow, the os.path command is first used to create the target directory, then the gx.tpl command renders template files from the tpls directory based on values in the value.json file and outputs them to the used directory. Finally, an inline shell command block is shown to copy a file.

Transaction Example

This example demonstrates how to use transactions in GXL.

#![allow(unused)]
fn main() {
extern mod base { path = "./_gal/"; }

mod envs {
    env default {};
}

mod main {
    flow trans1 | step1 | step2 | base.base_step1 | step3;
    flow trans2 | step1 | step3 | step2;

    #[transaction, undo(_undo_step1)]
    flow step1 {
        gx.echo(" step1 ");
    }
    #[undo(_undo_step2)]
    flow step2 {
        gx.echo(" step2 ");
    }
    #[undo(_undo_step3)]
    flow step3 {
        gx.echo(" step3 ");
        gx.assert(value: "true", expect: "false");
    }

    flow _undo_step1 {
        gx.echo(" undo step1 ");
    }
    flow _undo_step2 {
        gx.echo(" undo step2 ");
    }
    flow _undo_step3 {
        gx.echo(" undo step3 ");
    }
}
}

graph TD
    A[Start] --> B[Load base module]
    B --> C[Load envs module]
    C --> D[Load main module]
    D --> E[Define flows]
    E --> F[Execute trans1 flow]
    F --> G[Execute step1 flow]
    G --> H[Execute step2 flow]
    H --> I[Execute base.base_step1 flow]
    I --> J[Execute step3 flow]
    J --> K[Execute trans2 flow]
    K --> L[Execute step1 flow]
    L --> M[Execute step3 flow]
    M --> N[Execute step2 flow]
    N --> O[End]

Vars Example

This example demonstrates how to define and use variables in GXL.

#![allow(unused)]
fn main() {
mod envs {
    env default {
        data_list = [
            "JAVA",
            "RUST",
            "PYTHON",
        ];
        data_obj = {
            JAVA: { NAME: "JAVA", SCORE: 80 },
            RUST: { NAME: "RUST", SCORE: 100 },
            PYTHON: { NAME: "PYTHON", SCORE: 200 },
        };
    }
}

mod main {
    flow array_do {
        for ${CUR} in ${ENV.DATA_LIST} {
            gx.echo("CUR:${CUR}");
        }
    }
    flow obj_do {
        for ${CUR} in ${ENV.DATA_OBJ} {
            gx.echo("CUR:${CUR.NAME} : ${CUR.SCORE}");
        }
    }
}
}

Description

This example shows how to define variables in an environment and how to use these variables in flows. In the default environment, a list data_list and an object data_obj are defined. In the array_do flow, the data_list list is iterated over and each element is output. In the obj_do flow, the data_obj object is iterated over and the properties of each object are output.

graph TD
    A[Start] --> B[Load envs module]
    B --> C[Define data_list and data_obj variables]
    C --> D[Load main module]
    D --> E[Execute array_do flow]
    E --> F[Loop through ENV.DATA_LIST]
    F --> G[Execute gx.echo command for each item]
    G --> H[Execute obj_do flow]
    H --> I[Loop through ENV.DATA_OBJ]
    I --> J[Execute gx.echo command for each item]
    J --> K[End]

Galaxy Flow 内置能力文档

本文档详细描述了Galaxy Flow中所有内置能力的语法定义和使用示例。

gx.assert {
  value: <表达式>,      // 要检查的值
  expect: <期望值>,     // 期望的值
  err: <错误信息>,      // 断言失败时的错误信息（可选）
  result: <变量名>      // 存储断言结果的变量名（可选）
}

示例代码

// 检查变量值是否等于期望值
gx.assert {
  value: ${MY_VAR},
  expect: "expected_value",
  err: "MY_VAR值不正确"
}

// 检查表达式结果并存储结果
gx.assert {
  value: ${CALC_RESULT},
  expect: 42,
  result: "assert_result"
}

gx.cmd {
  cmd: <命令字符串>,     // 要执行的命令
  shell: <Shell类型>,    // 指定使用的Shell（可选）
  out: <输出变量名>,     // 捕获命令标准输出的变量名（可选）
  err: <错误变量名>,     // 捕获命令错误输出的变量名（可选）
  suc: <成功标识>,       // 命令执行成功的标识（可选）
  sudo: <布尔值>,        // 是否使用sudo权限执行（可选）
  log: <日志级别>,       // 日志记录级别（可选）
  silence: <布尔值>      // 是否静默执行（可选）
}

示例代码

// 执行简单命令
gx.cmd {
  cmd: "ls -la"
}

// 执行命令并捕获输出
gx.cmd {
  cmd: "date",
  out: "current_date"
}

// 使用sudo权限执行命令
gx.cmd {
  cmd: "systemctl restart nginx",
  sudo: true
}

gx.echo {
  value: <文本内容>,     // 要输出的文本内容
  file: <文件路径>,      // 输出到文件的路径（可选）
  export: <变量名>,      // 导出为环境变量的名称（可选）
  inc: <布尔值>          // 是否追加到文件末尾（可选）
}

示例代码

// 输出简单文本
gx.echo {
  value: "Hello, Galaxy Flow!"
}

// 输出到文件
gx.echo {
  value: "This is a log entry",
  file: "app.log"
}

// 追加到文件
gx.echo {
  value: "Additional information",
  file: "app.log",
  inc: true
}

// 导出为环境变量
gx.echo {
  value: "production",
  export: "ENV_TYPE"
}

// 从文件读取
gx.read_file {
  file: <文件路径>,      // 要读取的文件路径
  name: <变量名>         // 存储文件内容的变量名
}

// 从标准输入读取
gx.read_stdin {
  name: <变量名>,        // 存储输入内容的变量名
  prompt: <提示文本>     // 输入提示文本（可选）
}

// 从命令输出读取
gx.read_cmd {
  cmd: <命令字符串>,     // 要执行的命令
  name: <变量名>,        // 存储命令输出的变量名
  shell: <Shell类型>     // 指定使用的Shell（可选）
}

示例代码

// 从文件读取内容
gx.read_file {
  file: "config.json",
  name: "config_data"
}

// 从标准输入读取
gx.read_stdin {
  name: "user_input",
  prompt: "请输入您的姓名: "
}

// 从命令输出读取
gx.read_cmd {
  cmd: "git rev-parse HEAD",
  name: "commit_hash"
}

gx.vars {
  <变量名1>: <值1>,      // 变量名和对应的值
  <变量名2>: <值2>,      // 可以定义多个变量
  // ...
}

示例代码

// 定义多个变量
gx.vars {
  app_name: "MyApp",
  version: "1.0.0",
  debug: true
}

// 使用变量引用
gx.vars {
  project_root: "${HOME}/projects",
  config_file: "${project_root}/config.yaml"
}

gx.tpl {
  tpl: <模板内容>,       // 模板内容
  dst: <目标文件路径>,   // 生成文件的路径
  data: <数据变量名>,    // 模板数据变量名（可选）
  engine: <引擎类型>,    // 模板引擎类型（可选）
  file: <模板文件路径>   // 模板文件路径（可选，与tpl互斥）
}

示例代码

// 使用内联模板
gx.tpl {
  tpl: "Hello, {{name}}! Welcome to {{app_name}}.",
  dst: "output.txt",
  data: "user_data"
}

// 使用模板文件
gx.tpl {
  file: "template.txt",
  dst: "output.txt",
  data: "template_data"
}

gx.ver {
  value: <版本值>,       // 版本值
  default: <默认值>,     // 默认版本值（可选）
  file: <文件路径>,      // 版本文件路径（可选）
  export: <变量名>,      // 导出版本信息的变量名（可选）
  inc: <递增类型>        // 版本递增类型（可选，可选值：build/bugfix/feature/main）
}

示例代码

// 设置版本值
gx.ver {
  value: "1.2.3"
}

// 从文件读取版本并递增
gx.ver {
  file: "VERSION",
  inc: "feature"
}

// 导出版本信息
gx.ver {
  value: "2.0.0",
  export: "APP_VERSION"
}

gx.shell {
  shell: <脚本文件路径>,  // 要执行的Shell脚本文件路径
  arg_file: <参数文件>,   // 参数文件路径（可选）
  out_var: <输出变量名>,  // 捕获脚本输出的变量名（可选）
  default: <默认脚本>     // 默认脚本文件路径（可选，与shell互斥）
}

示例代码

// 执行Shell脚本
gx.shell {
  shell: "deploy.sh"
}

// 执行脚本并捕获输出
gx.shell {
  shell: "build.sh",
  out_var: "build_output"
}

// 使用参数文件
gx.shell {
  shell: "install.sh",
  arg_file: "install.args"
}

// 下载文件
gx.download {
  url: <下载URL>,        // 文件下载URL
  local_file: <本地路径>, // 保存到本地的文件路径
  username: <用户名>,     // 认证用户名（可选）
  password: <密码>        // 认证密码（可选）
}

// 上传文件
gx.upload {
  url: <上传URL>,        // 文件上传URL
  local_file: <本地路径>, // 要上传的本地文件路径
  method: <HTTP方法>,     // HTTP方法（如POST、PUT等，默认POST）
  username: <用户名>,     // 认证用户名（可选）
  password: <密码>        // 认证密码（可选）
}

示例代码

// 下载文件
gx.download {
  url: "https://example.com/file.zip",
  local_file: "downloaded_file.zip"
}

// 上传文件
gx.upload {
  url: "https://example.com/upload",
  local_file: "local_file.txt",
  method: "POST"
}

// 创建tar归档
gx.tar {
  src: <源文件/目录>,     // 要归档的源文件或目录
  file: <归档文件名>      // 生成的归档文件名
}

// 解压tar归档
gx.untar {
  file: <归档文件名>,     // 要解压的归档文件
  dst: <目标目录>         // 解压到的目标目录
}

示例代码

// 创建tar归档
gx.tar {
  src: "src/",
  file: "source.tar"
}

// 解压tar归档
gx.untar {
  file: "source.tar",
  dst: "extracted/"
}

gx.artifact {
  file: <文件路径>,       // 构建产物文件路径
  dst_path: <目标路径>    // 目标存储路径
}

示例代码

// 处理构建产物
gx.artifact {
  file: "target/release/myapp",
  dst_path: "artifacts/v1.0.0/"
}

gx.run {
  local: <工作流路径>,    // 要运行的工作流文件路径
  env: <环境配置>,        // 环境配置（可选）
  flow: <流程列表>,       // 要执行的流程列表（可选）
  conf: <配置文件>,       // 配置文件路径（可选）
  isolate: <布尔值>       // 是否隔离环境（可选）
}

示例代码

// 运行其他工作流
gx.run {
  local: "./subflow.gxl"
}

// 在特定环境中运行工作流
gx.run {
  local: "./deploy.gxl",
  env: "production",
  flow: "build,deploy"
}

// 隔离环境运行
gx.run {
  local: "./test.gxl",
  isolate: true
}

gx.defined(${变量名})

示例代码

// 检查变量是否已定义
if (gx.defined(${MY_VAR})) {
  gx.echo { value: "MY_VAR已定义，值为: ${MY_VAR}" }
} else {
  gx.echo { value: "MY_VAR未定义" }
}

gx.artifact

功能描述

处理构建产物文件。

语法定义

gx.artifact {
  file: <文件路径>,       // 构建产物文件路径
  dst_path: <目标路径>    // 目标存储路径
}

示例代码

// 处理构建产物
gx.artifact {
  file: "target/release/myapp",
  dst_path: "artifacts/v1.0.0/"
}

gx.assert

功能描述

执行断言检查，验证表达式的值是否符合预期。

语法定义

gx.assert {
  value: <表达式>,      // 要检查的值
  expect: <期望值>,     // 期望的值
  err: <错误信息>,      // 断言失败时的错误信息（可选）
  result: <变量名>      // 存储断言结果的变量名（可选）
}

示例代码

// 检查变量值是否等于期望值
gx.assert {
  value: ${MY_VAR},
  expect: "expected_value",
  err: "MY_VAR值不正确"
}

// 检查表达式结果并存储结果
gx.assert {
  value: ${CALC_RESULT},
  expect: 42,
  result: "assert_result"
}

gx.cmd

功能描述

执行系统命令或脚本。

语法定义

gx.cmd {
  cmd: <命令字符串>,     // 要执行的命令
  shell: <Shell类型>,    // 指定使用的Shell（可选）
  out: <输出变量名>,     // 捕获命令标准输出的变量名（可选）
  err: <错误变量名>,     // 捕获命令错误输出的变量名（可选）
  suc: <成功标识>,       // 命令执行成功的标识（可选）
  sudo: <布尔值>,        // 是否使用sudo权限执行（可选）
  log: <日志级别>,       // 日志记录级别（可选）
  silence: <布尔值>      // 是否静默执行（可选）
}

示例代码

// 执行简单命令
gx.cmd {
  cmd: "ls -la"
}

// 执行命令并捕获输出
gx.cmd {
  cmd: "date",
  out: "current_date"
}

// 使用sudo权限执行命令
gx.cmd {
  cmd: "systemctl restart nginx",
  sudo: true
}

gx.defined

功能描述

检查变量是否已定义。

语法定义

gx.defined(${变量名})

示例代码

// 检查变量是否已定义
if (gx.defined(${MY_VAR})) {
  gx.echo { value: "MY_VAR已定义，值为: ${MY_VAR}" }
} else {
  gx.echo { value: "MY_VAR未定义" }
}

gx.download 和 gx.upload

功能描述

下载和上传文件。

语法定义

// 下载文件
gx.download {
  url: <下载URL>,        // 文件下载URL
  local_file: <本地路径>, // 保存到本地的文件路径
  username: <用户名>,     // 认证用户名（可选）
  password: <密码>        // 认证密码（可选）
}

// 上传文件
gx.upload {
  url: <上传URL>,        // 文件上传URL
  local_file: <本地路径>, // 要上传的本地文件路径
  method: <HTTP方法>,     // HTTP方法（如POST、PUT等，默认POST）
  username: <用户名>,     // 认证用户名（可选）
  password: <密码>        // 认证密码（可选）
}

示例代码

// 下载文件
gx.download {
  url: "https://example.com/file.zip",
  local_file: "downloaded_file.zip"
}

// 上传文件
gx.upload {
  url: "https://example.com/upload",
  local_file: "local_file.txt",
  method: "POST"
}

gx.echo

功能描述

输出文本信息到控制台。

语法定义

gx.echo {
  value: <文本内容>,     // 要输出的文本内容
  file: <文件路径>,      // 输出到文件的路径（可选）
  export: <变量名>,      // 导出为环境变量的名称（可选）
  inc: <布尔值>          // 是否追加到文件末尾（可选）
}

示例代码

// 输出简单文本
gx.echo {
  value: "Hello, Galaxy Flow!"
}

// 输出到文件
gx.echo {
  value: "This is a log entry",
  file: "app.log"
}

// 追加到文件
gx.echo {
  value: "Additional information",
  file: "app.log",
  inc: true
}

// 导出为环境变量
gx.echo {
  value: "production",
  export: "ENV_TYPE"
}

gx.read

功能描述

从不同来源读取数据并存储到变量中。

语法定义

// 从文件读取
gx.read_file {
  file: <文件路径>,      // 要读取的文件路径
  name: <变量名>         // 存储文件内容的变量名
}

// 从标准输入读取
gx.read_stdin {
  name: <变量名>,        // 存储输入内容的变量名
  prompt: <提示文本>     // 输入提示文本（可选）
}

// 从命令输出读取
gx.read_cmd {
  cmd: <命令字符串>,     // 要执行的命令
  name: <变量名>,        // 存储命令输出的变量名
  shell: <Shell类型>     // 指定使用的Shell（可选）
}

示例代码

// 从文件读取内容
gx.read_file {
  file: "config.json",
  name: "config_data"
}

// 从标准输入读取
gx.read_stdin {
  name: "user_input",
  prompt: "请输入您的姓名: "
}

// 从命令输出读取
gx.read_cmd {
  cmd: "git rev-parse HEAD",
  name: "commit_hash"
}

gx.run

功能描述

运行其他GXL工作流文件。

语法定义

gx.run {
  local: <工作流路径>,    // 要运行的工作流文件路径
  env: <环境配置>,        // 环境配置（可选）
  flow: <流程列表>,       // 要执行的流程列表（可选）
  conf: <配置文件>,       // 配置文件路径（可选）
  isolate: <布尔值>       // 是否隔离环境（可选）
}

示例代码

// 运行其他工作流
gx.run {
  local: "./subflow.gxl"
}

// 在特定环境中运行工作流
gx.run {
  local: "./deploy.gxl",
  env: "production",
  flow: "build,deploy"
}

// 隔离环境运行
gx.run {
  local: "./test.gxl",
  isolate: true
}

gx.shell

功能描述

执行Shell脚本文件。

语法定义

gx.shell {
  shell: <脚本文件路径>,  // 要执行的Shell脚本文件路径
  arg_file: <参数文件>,   // 参数文件路径（可选）
  out_var: <输出变量名>,  // 捕获脚本输出的变量名（可选）
  default: <默认脚本>     // 默认脚本文件路径（可选，与shell互斥）
}

示例代码

// 执行Shell脚本
gx.shell {
  shell: "deploy.sh"
}

// 执行脚本并捕获输出
gx.shell {
  shell: "build.sh",
  out_var: "build_output"
}

// 使用参数文件
gx.shell {
  shell: "install.sh",
  arg_file: "install.args"
}

gx.tar 和 gx.untar

功能描述

创建和解压tar归档文件。

语法定义

// 创建tar归档
gx.tar {
  src: <源文件/目录>,     // 要归档的源文件或目录
  file: <归档文件名>      // 生成的归档文件名
}

// 解压tar归档
gx.untar {
  file: <归档文件名>,     // 要解压的归档文件
  dst: <目标目录>         // 解压到的目标目录
}

示例代码

// 创建tar归档
gx.tar {
  src: "src/",
  file: "source.tar"
}

// 解压tar归档
gx.untar {
  file: "source.tar",
  dst: "extracted/"
}

gx.tpl

功能描述

使用模板引擎处理文件模板。

语法定义

gx.tpl {
  tpl: <模板内容>,       // 模板内容
  dst: <目标文件路径>,   // 生成文件的路径
  data: <数据变量名>,    // 模板数据变量名（可选）
  engine: <引擎类型>,    // 模板引擎类型（可选）
  file: <模板文件路径>   // 模板文件路径（可选，与tpl互斥）
}

示例代码

// 使用内联模板
gx.tpl {
  tpl: "Hello, {{name}}! Welcome to {{app_name}}.",
  dst: "output.txt",
  data: "user_data"
}

// 使用模板文件
gx.tpl {
  file: "template.txt",
  dst: "output.txt",
  data: "template_data"
}

gx.vars

功能描述

定义和设置多个变量。

语法定义

gx.vars {
  <变量名1>: <值1>,      // 变量名和对应的值
  <变量名2>: <值2>,      // 可以定义多个变量
  // ...
}

示例代码

// 定义多个变量
gx.vars {
  app_name: "MyApp",
  version: "1.0.0",
  debug: true
}

// 使用变量引用
gx.vars {
  project_root: "${HOME}/projects",
  config_file: "${project_root}/config.yaml"
}

gx.ver

功能描述

管理和操作版本信息。

语法定义

gx.ver {
  value: <版本值>,       // 版本值
  default: <默认值>,     // 默认版本值（可选）
  file: <文件路径>,      // 版本文件路径（可选）
  export: <变量名>,      // 导出版本信息的变量名（可选）
  inc: <递增类型>        // 版本递增类型（可选，可选值：build/bugfix/feature/main）
}

示例代码

// 设置版本值
gx.ver {
  value: "1.2.3"
}

// 从文件读取版本并递增
gx.ver {
  file: "VERSION",
  inc: "feature"
}

// 导出版本信息
gx.ver {
  value: "2.0.0",
  export: "APP_VERSION"
}

Keyboard shortcuts

galaxy-sec operator ecosystem