agent-skills/skills/g3fo-db-ops/references/SQL_SITE_NAMING.md

SQL Site Naming Convention

本文档说明了项目中使用的 SQL 站点命名规则及其对应关系。

站点命名对照表

目录名称	对应站点	IP地址	描述
afe_ap	Alpha Site
dls_ap	DLS
hing_wai_ap	HingWai
vn-demo	VN Demo
vn-demo-local	VN Demo Local
226	UAT

目录结构与执行机制

update_service_release 目录结构

项目中的 SQL 文件按照以下结构组织：

update_service_release/
├── 版本号/                    # 如 1.5.1.20
│   ├── sitename/             # 如 afe_ap, dls_ap 等
│   │   ├── patch/            # 补丁目录
│   │   │   └── 数字版本/      # 如 1, 2 等
│   │   │       └── *.sql     # 补丁 SQL 文件
│   │   └── *.sql             # 该站点特定的 SQL 文件
│   └── *.sql                 # 通用 SQL 文件
└── pending release x.x.x.x/  # 当前开发中的版本

SQL 执行机制

1. 版本发布目录：

   • 每个版本号目录下包含适用于不同站点的 SQL 文件
   • 站点特定的 SQL 文件放在对应的 sitename 子目录中
   • 补丁文件放在对应站点的 patch 子目录中，按数字版本号分组
   • 通用 SQL 文件直接放在版本号目录下

2. 当前开发版本：

   • update_service_release/pending release x.x.x.x 是当前正在开发的版本目录
   • 每个版本下必须包含一个修改版本号的 SQL 文件：set_version_01.sql
   • 该文件负责更新系统版本信息到 m_system_setting 表

3. Jenkins 自动化执行：

   • 通过执行 1-g3fo-db/g3fo-db-patch 任务运行 SQL
   • 大版本升级执行1-g3fo-db，只能执行一次
   • 补丁执行g3fo-db-patch，可重复执行
   • 系统会根据指定的站点和版本号执行对应目录下的 SQL 文件
   • 默认执行版本号最大的 patch（可重复执行，保证幂等性）

版本号更新文件示例

每个版本必须包含 set_version_01.sql 文件，其内容如下（控实际情况修改版本号，以下是1.5.1.20版本示例）：

UPDATE `g3fo_base`.`m_system_setting`
SET `param_value` = '1.5.1.0 M20',
    `update_on` = NOW()
WHERE
    `param_name` = 'base.systemVersion';

UPDATE `g3fo_base`.`m_system_setting`
SET `param_value` = '0',
    `update_on` = NOW()
WHERE
    `param_name` = 'base.patchNo';

命名一致性要求

为了确保自动化部署和执行流程的正常运行，sitename 目录命名必须与以下配置保持严格一致：

1. Jenkins 配置：

   • Jenkins -> 系统管理 -> Publish over SSH -> SSH Server Name 中配置的服务名
   • 例如：如果 Jenkins 中配置的 SSH Server Name 为 afe_ap，则目录名必须也为 afe_ap

2. 执行服务器配置：

   • 与执行 SQL 的服务器（Build 机或 support 机）上的 /data/g3dbExecution/db_config.json 文件中的 key 保持一致
   • 该 JSON 文件中的 key 值必须与目录名称完全匹配

这种一致性确保了：

• Jenkins 能够正确地将 SQL 文件传输到目标服务器
• SQL 脚本能够在正确的环境中执行
• 部署流程能够自动化进行而不会出现配置错误

添加新环境

当需要添加新的部署环境时，请遵循以下命名规则：

• 生产环境：使用客户名称的缩写加 _ap 后缀
• 测试环境：使用环境用途加版本号或标识符的形式

注意事项

• 所有命名应保持简洁明了
• 同一类环境应保持命名风格一致
• 添加新环境后应及时更新此文档
• 修改现有环境名称前需确认关联的所有配置均已同步更新