# databaseDevops

**Repository Path**: hulu_fly/database-devops

## Basic Information

- **Project Name**: databaseDevops
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Database-DevOps 使用手册

> **版本**: v1.0  
> **最后更新**: 2026-06-18  
> **适用对象**: 数据库运维工程师

---

## 目录

1. [项目概述](#1-项目概述)
2. [快速入门](#2-快速入门)
3. [数据库运维技能包 (DB-Ops)](#3-数据库运维技能包-db-ops)
4. [部署指南](#4-部署指南)
5. [常见场景操作](#5-常见场景操作)
6. [故障排查](#6-故障排查)
7. [附录](#7-附录)

---

## 1. 项目概述

本项目是 **GaussDB/MySQL 数据库运维** 的工具仓库：

### 1.1 技术栈

```
数据库层:   MySQL 8.0, GaussDB (openGauss/PostgreSQL)
工具层:     mysql CLI, gsql, gs_dump, gs_restore, gs_loader, jq
AI 引擎:    Hermes Agent (NousResearch), DeepSeek API
容器化:     Docker
```

---

## 2. 快速入门

### 2.1 环境要求

| 依赖 | 最低版本 | 用途 |
|------|----------|------|
| Docker | 20.10+ | Hermes Agent 容器化部署 |
| MySQL Client | 8.0 | MySQL 数据库连接 |
| GaussDB Client (gsql) | 503.1.0+ | GaussDB 数据库连接 |
| jq | 1.6+ | JSON 解析（脚本依赖） |

### 2.2 项目结构

```
database-devops/
├── README.md                          # 项目说明（中文）
├── README.en.md                       # 项目说明（英文）
├── .env.credentials                   # 数据库凭证（Git 忽略）
├── .gitignore
│
├── build/                             # 构建资源
│   ├── Dockerfile.hermes-db           # Hermes Agent + DB 工具镜像
│   └── gaussdb-tools/bin/gs_loader.sh # GaussDB 数据加载工具
│
├── db-ops/                            # 数据库运维技能包
│   ├── db-ops.cfg.yaml                # 配置文件模板
│   ├── db-ops.setup.sh                # 一键安装脚本
│   ├── skills/                        # 3 个技能定义
│   │   ├── db-ops-backup.skill.md     # 备份恢复技能
│   │   ├── db-ops-monitor.skill.md    # 监控诊断技能
│   │   └── db-ops-transfer.skill.md   # 导入导出技能
│   ├── templates/                     # 通知模板
│   │   ├── backup_result.tmpl.md      # 备份结果模板
│   │   └── inspect_report.tmpl.md     # 巡检报告模板
│   └── scripts/                       # 运维脚本
│       ├── gaussdb/                   # 6 个 GaussDB 脚本
│       └── mysql/                     # 6 个 MySQL 脚本
│
└── docs/                              # 参考文档
    ├── specs/hermes-agent-db-ops.md   # 规格说明
    ├── deploy/hermes-agent-docker-deploy.md  # 部署指南
    └── references/                    # 参考知识库
        ├── GaussDB数据库管理与运维实验_原理知识手册.md
        ├── GaussDB数据库管理与运维实验_详细操作指南.md
        ├── NineData实现GaussDB数据库管理与运维_实验指南.md
        └── 数据库管理与运维_业务全景与多库对比指南.md
```

---

## 3. 数据库运维技能包 (DB-Ops)

DB-Ops 是一个面向 **MySQL 8.0** 和 **GaussDB** 的智能运维技能包，运行在 **Hermes Agent** 框架之上，支持通过自然语言交互完成数据库监控、备份和数据传输。

### 3.1 三大核心技能

#### 技能一：监控诊断 (`db-ops-monitor`)

**功能**：巡检数据库健康状态，检测潜在问题。

| 检查项 | MySQL 数据源 | GaussDB 数据源 | 命令 |
|--------|-------------|---------------|------|
| 连接数 | `SHOW PROCESSLIST` | `pg_stat_activity` | `check_connections.sh` |
| 慢查询 | `performance_schema` | `pg_stat_statements` | `check_slow_queries.sh` |
| 锁等待 | `innodb_trx/innodb_locks` | `pg_locks` | `check_locks.sh` |
| 日巡检汇总 | 以上全部 | 以上全部 | `daily_inspect.sh` |

**使用示例**：
```
# 自然语言指令（通过 Hermes Agent）
"检查生产环境 MySQL 的连接数是否超过阈值"
"分析 GaussDB 慢查询 TOP 10"
"对测试环境进行日巡检"
```

**告警阈值**（可配置）：
- 连接数告警：超过最大连接数的 **80%**
- 慢查询阈值：**1000ms**
- 备份保留天数：**7 天**

#### 技能二：备份恢复 (`db-ops-backup`)

**功能**：执行全量逻辑备份，生成可恢复的 SQL 文件。

| 数据库 | 工具 | 输出格式 | 脚本 |
|--------|------|----------|------|
| MySQL | `mysqldump --single-transaction --routines --triggers` | `.sql` | `mysql/full_backup.sh` |
| GaussDB | `gs_dump -F c` | `.dump`（自定义格式） | `gaussdb/full_backup.sh` |

**安全红线**：
- ⚠️ **只做备份，不做自动恢复** — 恢复操作必须人工确认
- ⚠️ **生产环境恢复前必须先备份当前状态**
- 备份文件存储路径：`/data/backups/{db_type}/{instance}`
- 命名规则：`{db_name}_{YYYYMMDD_HHMMSS}.{ext}`

**使用示例**：
```
"全量备份生产环境 MySQL 订单库"
"备份 GaussDB 用户数据库到 /data/backups"
```

**备份结果通知模板**：参见 `db-ops/templates/backup_result.tmpl.md`

#### 技能三：导入导出 (`db-ops-transfer`)

**功能**：表级数据导出为 CSV，支持跨库迁移。

| 功能 | MySQL | GaussDB | 脚本 |
|------|-------|---------|------|
| 导出为 CSV | `SELECT INTO OUTFILE` | `COPY TO` | `export_table_csv.sh` |

**敏感表保护**：系统表（如 `information_schema`、`pg_catalog`）默认不允许导出。

**使用示例**：
```
"导出生产订单表 orders 为 CSV"
"从测试环境导出用户表数据"
```

### 3.2 安装 DB-Ops

#### 步骤一：确保 Hermes Agent 已安装

```bash
# 检查 Hermes Agent 是否运行
hermes-agent --version
```

#### 步骤二：运行一键安装脚本

```bash
cd /path/to/database-devops/db-ops
chmod +x db-ops.setup.sh
./db-ops.setup.sh
```

安装脚本自动完成：
1. 检测 `hermes-agent` 是否存在
2. 检测 MySQL 客户端 (`mysql`)
3. 检测 GaussDB 客户端 (`gsql`)
4. 检测 `jq` 工具
5. 将凭证从 `.env.credentials` 复制到 `~/.hermes/db-ops/.env`
6. 注册 3 个技能到 Hermes Agent

#### 步骤三：配置数据库连接

编辑 `db-ops/db-ops.cfg.yaml` 或 `~/.hermes/db-ops/.env`：

```yaml
# MySQL 实例
mysql:
  instances:
    prod:
      host: 47.116.196.113
      port: 3306
      user: root
      password: "123456"
    test:
      host: 47.116.196.113
      port: 3306
      user: root
      password: "123456"

# GaussDB 实例
gaussdb:
  instances:
    prod:
      host: 47.116.196.113
      port: 15432
      user: dbops
      password: "Huawei@1234"
    test:
      host: 47.116.196.113
      port: 15432
      user: dbops
      password: "Huawei@1234"

# 通用配置
common:
  slow_query_threshold_ms: 1000
  backup_dir: /data/backups
  retention_days: 7
  connection_alert_threshold: 0.8
```

⚠️ **注意**：`.env.credentials` 包含真实凭证，已被 `.gitignore` 排除，不要提交到版本库。

### 3.3 运维脚本清单

所有脚本遵循 `set -euo pipefail` 严格模式，通过环境变量动态获取连接信息。

#### GaussDB 脚本 (`db-ops/scripts/gaussdb/`)

| 脚本 | 功能 | 用法 |
|------|------|------|
| `check_connections.sh` | 连接数检查 | `GAUSSDB_HOST=... GAUSSDB_PORT=... ./check_connections.sh` |
| `check_locks.sh` | 锁等待分析 | `GAUSSDB_HOST=... GAUSSDB_PORT=... ./check_locks.sh` |
| `check_slow_queries.sh` | 慢查询 TOP N | `GAUSSDB_HOST=... GAUSSDB_PORT=... TOP_N=10 ./check_slow_queries.sh` |
| `daily_inspect.sh` | 日巡检汇总 | `GAUSSDB_HOST=... GAUSSDB_PORT=... ./daily_inspect.sh` |
| `export_table_csv.sh` | 表导出为 CSV | `TABLE=orders GAUSSDB_HOST=... ./export_table_csv.sh` |
| `full_backup.sh` | 全量逻辑备份 | `GAUSSDB_HOST=... GAUSSDB_PORT=... BACKUP_DIR=... ./full_backup.sh` |

#### MySQL 脚本 (`db-ops/scripts/mysql/`)

| 脚本 | 功能 | 用法 |
|------|------|------|
| `check_connections.sh` | 连接数检查 | `MYSQL_HOST=... MYSQL_PORT=... ./check_connections.sh` |
| `check_locks.sh` | 锁等待分析 | `MYSQL_HOST=... MYSQL_PORT=... ./check_locks.sh` |
| `check_slow_queries.sh` | 慢查询 TOP N | `MYSQL_HOST=... MYSQL_PORT=... TOP_N=10 ./check_slow_queries.sh` |
| `daily_inspect.sh` | 日巡检汇总 | `MYSQL_HOST=... MYSQL_PORT=... ./daily_inspect.sh` |
| `export_table_csv.sh` | 表导出为 CSV | `TABLE=orders MYSQL_HOST=... ./export_table_csv.sh` |
| `full_backup.sh` | 全量逻辑备份 | `MYSQL_HOST=... MYSQL_PORT=... BACKUP_DIR=... ./full_backup.sh` |

---

## 4. 部署指南

### 4.1 Docker 部署 Hermes Agent + DB-Ops

#### 构建镜像

```bash
cd build/
docker build -f Dockerfile.hermes-db -t hermes-agent-db:latest .
```

该镜像基于 `nousresearch/hermes-agent:latest`，额外安装了：
- `default-mysql-client` — MySQL CLI 工具
- `libncurses6` — GaussDB 客户端依赖
- `jq` — JSON 解析
- GaussDB 工具套件（`gsql`、`gs_dump`、`gs_restore`、`gs_loader`）

#### Docker Compose 部署

```yaml
version: '3.8'
services:
  hermes-db:
    image: hermes-agent-db:latest
    container_name: hermes-db
    stdin_open: true
    tty: true
    ports:
      - "9119:9119"
    command: >
      sh -c "hermes dashboard --host 0.0.0.0 --port 9119 --insecure --no-open &
      exec hermes"
    volumes:
      - ./data:/data
      - ~/.hermes:/root/.hermes
      - ./db-ops:/opt/db-ops
    environment:
      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
      - GAUSSDB_HOME=/opt/gaussdb-tools
    restart: unless-stopped
```

```bash
# 启动
docker compose up -d

# 查看日志
docker compose logs -f hermes-db

# 停止
docker compose down
```

#### 资源建议

| 环境 | CPU | 内存 | 磁盘 |
|------|-----|------|------|
| 开发/测试 | 2 核 | 4 GB | 20 GB |
| 生产 | 4 核 | 8 GB+ | 50 GB+ |

---

## 5. 常见场景操作

### 场景一：MySQL 生产库日巡检

```bash
# 方式一：通过 Hermes Agent 自然语言
"对生产环境 MySQL 进行日巡检"

# 方式二：直接执行脚本
cd db-ops/scripts/mysql/
MYSQL_HOST=47.116.196.113 \
MYSQL_PORT=3306 \
MYSQL_USER=root \
MYSQL_PASSWORD=123456 \
./daily_inspect.sh
```

输出示例（参考 `db-ops/templates/inspect_report.tmpl.md`）：
- 连接数使用率
- 慢查询 TOP 5
- 活跃锁等待
- 数据库列表
- 告警汇总

### 场景二：GaussDB 全量备份

```bash
# 方式一：通过 Hermes Agent 自然语言
"全量备份 GaussDB 生产库到 /data/backups"

# 方式二：直接执行脚本
cd db-ops/scripts/gaussdb/
GAUSSDB_HOST=47.116.196.113 \
GAUSSDB_PORT=15432 \
GAUSSDB_USER=dbops \
GAUSSDB_PASSWORD='Huawei@1234' \
BACKUP_DIR=/data/backups/gaussdb/prod \
./full_backup.sh
```

输出文件：`/data/backups/gaussdb/prod/{dbname}_{YYYYMMDD_HHMMSS}.dump`

恢复命令参考（需人工确认后执行）：
```bash
gs_restore -h 47.116.196.113 -p 15432 -U dbops -d target_db /path/to/backup.dump
```

### 场景三：导出 MySQL 表为 CSV

```bash
cd db-ops/scripts/mysql/
MYSQL_HOST=47.116.196.113 \
MYSQL_PORT=3306 \
MYSQL_USER=root \
MYSQL_PASSWORD=123456 \
TABLE=orders \
DATABASE=mydb \
./export_table_csv.sh
```

---

## 6. 故障排查

### 6.1 DB-Ops 常见问题

| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| `gsql: command not found` | GaussDB 客户端未安装 | 安装 GaussDB 工具包，设置 `GAUSSDB_HOME` |
| `mysql: command not found` | MySQL 客户端未安装 | `apt install default-mysql-client` |
| `jq: command not found` | jq 未安装 | `apt install jq` |
| 脚本执行报权限错误 | 脚本无执行权限 | `chmod +x db-ops/scripts/**/*.sh` |
| 数据库连接超时 | 网络不通或防火墙拦截 | 检查安全组/防火墙规则、VPN 连接 |
| 备份文件无法生成 | 磁盘空间不足或目录权限问题 | 检查 `/data/backups` 空间和写权限 |
| Hermes Agent 无法注册技能 | Agent 未运行或路径配置错误 | 确认 `hermes-agent --version` 可用 |

### 6.2 Docker 部署故障

```bash
# 检查容器状态
docker ps -a | grep hermes

# 查看启动日志
docker logs hermes-db --tail 50

# 进入容器检查工具
docker exec -it hermes-db bash
which mysql gsql jq

# 检查工具可用性
mysql --version
gsql --version
```

---

## 7. 附录

### 7.1 参考知识库

| 文档 | 位置 | 说明 |
|------|------|------|
| GaussDB 原理知识手册 | `docs/references/GaussDB数据库管理与运维实验_原理知识手册.md` | 架构概念、权限体系、备份策略 |
| GaussDB 详细操作指南 | `docs/references/GaussDB数据库管理与运维实验_详细操作指南.md` | 从购买到运维的完整步骤 |
| NineData 实验指南 | `docs/references/NineData实现GaussDB数据库管理与运维_实验指南.md` | 使用 NineData 平台管理 GaussDB |
| 多库运维对比指南 | `docs/references/数据库管理与运维_业务全景与多库对比指南.md` | MySQL/PG/GaussDB/Redis 五维度对比 |
| DB-Ops 规格说明 | `docs/specs/hermes-agent-db-ops.md` | 技能包设计规格 v1.1 |

### 7.2 环境变量速查

#### DB-Ops 环境变量

| 变量 | MySQL 默认值 | GaussDB 默认值 | 说明 |
|------|-------------|---------------|------|
| `{DB}_HOST` | — | — | 数据库主机地址 |
| `{DB}_PORT` | 3306 | 15432 | 数据库端口 |
| `{DB}_USER` | root | dbops | 数据库用户名 |
| `{DB}_PASSWORD` | — | — | 数据库密码 |
| `BACKUP_DIR` | /data/backups | /data/backups | 备份存储目录 |
| `TOP_N` | 10 | 10 | 慢查询 TOP N |
| `TABLE` | — | — | 导出表名 |
| `DATABASE` | — | — | 数据库名 |

#### Docker 环境变量

| 变量 | 说明 |
|------|------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥（必填） |
| `GAUSSDB_HOME` | GaussDB 工具目录（默认 `/opt/gaussdb-tools`） |

### 7.3 GaussDB 工具说明

| 工具 | 路径 | 功能 |
|------|------|------|
| `gsql` | `/opt/gaussdb-tools/bin/gsql` | GaussDB 命令行客户端 |
| `gs_dump` | `/opt/gaussdb-tools/bin/gs_dump` | GaussDB 逻辑备份导出 |
| `gs_restore` | `/opt/gaussdb-tools/bin/gs_restore` | GaussDB 逻辑备份恢复 |
| `gs_loader` | `/opt/gaussdb-tools/bin/gs_loader` | GaussDB 批量数据加载 |

### 7.4 备份策略建议

参考 `docs/references/GaussDB数据库管理与运维实验_原理知识手册.md`：

- **3-2-1 原则**：3 份副本，2 种介质，1 份异地
- **全量备份**：每天凌晨执行（`gs_dump` / `mysqldump`）
- **保留策略**：默认保留 7 天，生产环境建议 30 天
- **备份验证**：定期在测试环境验证备份可恢复性
- **RPO/RTO 目标**：全量逻辑备份 RPO = 上次备份时间点，RTO = 恢复时间（数据量相关）

---

> **提示**：更多细节请参阅 `docs/` 目录下的各子文档。如有问题，欢迎提交 Issue。