Mod-Operator 配置文件详解

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

配置文件概览

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

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

字段说明

地址类型支持

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

字段说明

依赖地址类型

本地路径依赖

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

字段说明

变量类型

字符串变量

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: ']]'

字段说明

文件选择策略

排除特定文件

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/_value.yml - 默认值定义

_value.yml 存储模块的默认配置值，为模块提供合理的默认行为。

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"

值来源类型

工作流配置

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 模块。