AFE_SZ_DEV/agent-skills
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit with project setup and basic structure established.

Browse Source
This commit is contained in:
ken.li
2026-01-16 17:44:35 +08:00
parent bf3ab6a241
commit 02bf619c65
40 changed files with 3363 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/g3fo-docs/references/middleware/keepalived/deploy.md
+325
View File
@@ -0,0 +1,325 @@
# Docker 部署 Keepalived 2.3.4 实现三节点高可用 VIP
本文档详细说明如何在三台机器上通过 Docker 部署 Keepalived 2.3.4，实现 VIP（${VIP_IP}）的高可用，并通过仲裁节点防止脑裂问题。
## 1. 节点信息
| 节点名称 | IP 地址 | 角色 | 基础优先级 | 备注 |
| --- | --- | --- | --- | --- |
| Node A | ${NODE_A_IP} | 主节点 (Master) | 110 | MySQL 故障优先级扣 50 → 60 |
| Node B | ${NODE_B_IP} | 备节点 (Backup) | 100 | MySQL 故障优先级扣 50 → 50 |
| Node C | ${NODE_C_IP} | 仲裁节点 (Arbiter) | 40 | 参与选举但不持有 VIP |
+ **VIP 地址**：${VIP_IP}
+ **仲裁节点作用**：Node C 仅参与选举流程，防止 Node A 和 Node B 之间发生脑裂，正常场景下不持有 VIP。
## 2. 构建 Keepalived 镜像（解决 libip4tc 报错）
采用多阶段构建方式，确保镜像最小化且包含所有运行时依赖。
### 2.1 Dockerfile 内容
```dockerfile
# Stage 1: 构建 Keepalived 二进制文件
FROM alpine:3.23.2 AS builder
# 安装构建依赖
RUN apk add --no-cache \
gcc \
make \
libc-dev \
openssl-dev \
libnl3-dev \
ipset-dev \
iptables-dev \
libnfnetlink-dev \
libnftnl-dev \
libmnl-dev \
net-snmp-dev \
libssh2-dev \
pcre2-dev \
autoconf \
automake \
linux-headers \
curl \
tar
# 下载并编译 Keepalived 2.3.4
ENV KEEPALIVED_VERSION=2.3.4
RUN curl -sSL https://www.keepalived.org/software/keepalived-${KEEPALIVED_VERSION}.tar.gz -o keepalived.tar.gz && \
tar -zxf keepalived.tar.gz && \
cd keepalived-${KEEPALIVED_VERSION} && \
./configure --prefix=/usr --sysconfdir=/etc && \
make && \
make install DESTDIR=/install
# Stage 2: 构建最终运行镜像
FROM alpine:3.23.2
# 安装运行时依赖
RUN apk add --no-cache \
libnl3 \
ipset \
iptables \
libnftnl \
libmnl \
libnfnetlink \
net-snmp-libs \
libssh2 \
pcre2 \
openssl \
ca-certificates \
tzdata \
libip4tc \
libip6tc
# 从构建阶段复制编译好的二进制文件
COPY --from=builder /install /
# 创建默认配置目录
RUN mkdir -p /etc/keepalived
# 暴露 VRRP 协议端口 (112)
EXPOSE 112
# 前台运行 Keepalived（适配 Docker 容器运行模式）
# --dont-fork: 不后台运行
# --log-console: 日志输出到控制台（便于 Docker 日志查看）
ENTRYPOINT ["keepalived", "--dont-fork", "--log-console"]
```
### 2.2 构建镜像命令
```bash
docker build -t keepalived:2.3.4 .
```
## 3. 配置文件部署
### 3.1 前置准备
在三台机器上统一创建配置目录：
```bash
mkdir -p /data/keepalived
```
### 3.2 Docker Compose 配置（三台机器通用）
创建 `/data/keepalived/docker-compose.yml`：
```yaml
services:
keepalived:
image: keepalived:2.3.4
container_name: keepalived
restart: always
network_mode: host # 主机网络模式，确保 VRRP 协议正常通信
cap_add: # 添加网络管理权限
- NET_ADMIN
- NET_BROADCAST
- NET_RAW
volumes:
- /data/keepalived/keepalived.conf:/etc/keepalived/keepalived.conf:ro # 只读挂载配置文件
- /data/keepalived/check-mysql.sh:/etc/keepalived/check-mysql.sh:ro # 挂载 MySQL 检测脚本（仅 Node A/B 需要）
```
### 3.3 各节点 Keepalived 配置
#### 3.3.1 Node A（${NODE_A_IP}）配置
路径：`/data/keepalived/keepalived.conf`
```nginx
global_defs {
router_id ${ROUTER_ID_A}
vrrp_skip_check_adv_addr
script_user root # 指定脚本执行用户
enable_script_security # 启用脚本安全校验，防止执行未授权脚本
}
# MySQL 存活检测脚本定义
vrrp_script check_mysql {
script "/etc/keepalived/check-mysql.sh"
interval 3 # 检测间隔：3 秒
weight -50 # 检测失败时，优先级扣 50
fall 3 # 连续 3 次失败判定为故障
rise 2 # 连续 2 次成功判定为恢复
}
vrrp_instance VI_1 {
state BACKUP # 所有节点统一设为 BACKUP，靠优先级决定 Master
interface ${INTERFACE} # 替换为宿主机实际网卡名（如 ens33/br0 等）
virtual_router_id ${VIRTUAL_ROUTER_ID} # 虚拟路由 ID，集群内必须一致（1-255）
priority 110 # 基础优先级
preempt_delay 30 # 优先级恢复后，延迟 30 秒抢占 VIP（减少抖动）
advert_int 1 # VRRP 通告间隔：1 秒
# 认证配置（集群内必须一致）
authentication {
auth_type PASS
auth_pass ${AUTH_PASS}
}
# 单播配置（替代组播，适配部分网络环境）
unicast_src_ip ${NODE_A_IP} # 本机 IP
unicast_peer { # 集群其他节点 IP
${NODE_B_IP}
${NODE_C_IP}
}
# 虚拟 IP 配置
virtual_ipaddress {
${VIP_IP}/32 # VIP 地址（32 位掩码）
}
# 绑定检测脚本
track_script {
check_mysql
}
}
```
#### 3.3.2 Node B（${NODE_B_IP}）配置
路径：`/data/keepalived/keepalived.conf`
```nginx
global_defs {
router_id ${ROUTER_ID_B}
vrrp_skip_check_adv_addr
script_user root
enable_script_security
}
# MySQL 存活检测脚本定义
vrrp_script check_mysql {
script "/etc/keepalived/check-mysql.sh"
interval 3
weight -50
fall 3
rise 2
}
vrrp_instance VI_1 {
state BACKUP
interface ${INTERFACE} # 替换为宿主机实际网卡名
virtual_router_id ${VIRTUAL_ROUTER_ID}
priority 100 # 基础优先级（低于 Node A）
advert_int 1
authentication {
auth_type PASS
auth_pass ${AUTH_PASS}
}
unicast_src_ip ${NODE_B_IP}
unicast_peer {
${NODE_A_IP}
${NODE_C_IP}
}
virtual_ipaddress {
${VIP_IP}/32
}
track_script {
check_mysql
}
}
```
#### 3.3.3 Node C（${NODE_C_IP}，仲裁节点）配置
路径：`/data/keepalived/keepalived.conf`
```nginx
global_defs {
router_id ${ROUTER_ID_C}
vrrp_skip_check_adv_addr
}
vrrp_instance VI_1 {
state BACKUP
interface ${INTERFACE} # 替换为宿主机实际网卡名
virtual_router_id ${VIRTUAL_ROUTER_ID}
priority 40 # 最低优先级（仅参与选举，不持有 VIP）
advert_int 1
authentication {
auth_type PASS
auth_pass ${AUTH_PASS}
}
unicast_src_ip ${NODE_C_IP}
unicast_peer {
${NODE_A_IP}
${NODE_B_IP}
}
# 仲裁节点不配置 virtual_ipaddress，不持有 VIP
}
```
### 3.4 MySQL 检测脚本（仅 Node A/B 需要）
路径：`/data/keepalived/check-mysql.sh`
```bash
#!/bin/sh
# 检测逻辑：
# 1. timeout 2：限制命令 2 秒内完成，避免脚本阻塞
# 2. nc -z：仅检测端口连通性（无数据传输）
# 3. 屏蔽所有输出，仅返回退出码
if timeout 2 nc -z 127.0.0.1 3306 > /dev/null 2>&1; then
# 端口连通，返回 0（Keepalived 判定正常）
exit 0
else
# 端口不通/超时，返回 1（Keepalived 触发优先级扣减）
exit 1
fi
```
添加执行权限：
```bash
chmod +x /data/keepalived/check-mysql.sh
```
## 4. 启动与验证
### 4.1 启动容器
三台机器执行相同命令：
```bash
cd /data/keepalived
docker-compose up -d
```
### 4.2 日志查看
```bash
docker logs -f keepalived
```
> 正常日志会显示 VRRP 选举过程、VIP 绑定/释放、脚本检测结果等信息。
>
### 4.3 VIP 验证
在任意节点执行，查看 VIP 是否绑定：
```bash
ip addr show ${INTERFACE} # 替换为实际网卡名
```
+ 正常情况下，VIP（${VIP_IP}）会绑定在优先级最高的节点（初始为 Node A）。
+ 输出示例：`inet ${VIP_IP}/32 scope global ${INTERFACE}`
## 5. 故障场景分析
详细的故障场景模拟与 VIP 切换逻辑分析，请参阅：[Keepalived 故障场景分析](./fault-analysis.md)
## 6. 核心总结
### 6.1 优先级规则
+ VIP 归属由 Keepalived **有效优先级** 决定：基础优先级 A(110) > B(100) > C(40)；
+ MySQL 故障会让 A/B 优先级扣 50，Keepalived 离线则失去选举资格。
### 6.2 仲裁节点作用
+ Node C 仅参与选举流程，不持有 VIP；
+ 核心作用是防止 A、B 脑裂，正常/单节点故障场景下不影响 A/B 选举逻辑。
### 6.3 风险与优化
+ **风险**：A/B MySQL 均故障但 Keepalived 正常时，VIP 仍绑定到 A，此时无可用 MySQL；需在业务层增加数据库存活检测，避免连接失效的 VIP。
+ **抢占优化**：A 恢复后会在 `preempt_delay`（30 秒）后抢占 VIP，若需避免业务抖动，可在 Node A 配置中添加 `nopreempt` 关闭抢占。
### 6.4 关键配置注意事项
+ 所有节点 `virtual_router_id` 和认证信息必须一致；
+ 网卡名需替换为宿主机实际名称；
+ 仲裁节点 C 不配置 `virtual_ipaddress`，不挂载 MySQL 检测脚本。
skills/g3fo-docs/references/middleware/keepalived/fault-analysis.md
+25
View File
@@ -0,0 +1,25 @@
# Keepalived 故障场景分析
本文档详细分析了在三节点高可用架构下，不同故障场景对 VIP 归属和集群状态的影响。
## 故障场景表
| 场景编号 | 故障场景描述 | 节点 A 状态（MySQL/Keepalived） | 节点 B 状态（MySQL/Keepalived） | 节点 C 状态（Keepalived） | 各节点有效优先级 | VIP 最终归属 | 关键说明 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 初始正常状态 | 正常/正常 | 正常/正常 | 正常 | A=110、B=100、C=40 | Node A | A 优先级最高，成为 Master |
| 2 | A 的 MySQL 停机，Keepalived 正常 | 故障/正常 | 正常/正常 | 正常 | A=60、B=100、C=40 | Node B | A 扣权重后，B 优先级更高接管 VIP |
| 3 | 场景 2 后，A 的 MySQL 恢复 | 恢复/正常 | 正常/正常 | 正常 | A=110、B=100、C=40 | Node A | A 优先级恢复，30 秒后抢占 VIP |
| 4 | A 的 Keepalived 停机 | 正常/故障（离线） | 正常/正常 | 正常 | A=离线、B=100、C=40 | Node B | A 无选举资格，B 接管 |
| 5 | B 的 MySQL 停机 | 正常/正常 | 故障/正常 | 正常 | A=110、B=50、C=40 | Node A | B 扣权重后，A 仍为最高 |
| 6 | B 的 Keepalived 停机 | 正常/正常 | 正常/故障（离线） | 正常 | A=110、B=离线、C=40 | Node A | B 无选举资格，A 保持 Master |
| 7 | A、B MySQL 均停机 | 故障/正常 | 故障/正常 | 正常 | A=60、B=50、C=40 | Node A | 无可用 MySQL，但 Keepalived 仍按优先级选举 |
| 8 | A MySQL 停机 + B Keepalived 停机 | 故障/正常 | 无意义/故障（离线） | 正常 | A=60、B=离线、C=40 | Node A | B 离线，A 优先级高于 C（但 MySQL 不可用） |
| 9 | A Keepalived 停机 + B MySQL 停机 | 正常/故障（离线） | 故障/正常 | 正常 | A=离线、B=50、C=40 | Node B | A 离线，B 优先级高于 C（但 MySQL 不可用） |
| 10 | A、B Keepalived 均停机 | 正常/故障（离线） | 正常/故障（离线） | 正常 | A=离线、B=离线、C=40 | 无节点绑定 VIP | C 无 VIP 配置，仅参与选举不持有 VIP |
| 11 | A MySQL+Keepalived 均停机 | 故障/故障（离线） | 正常/正常 | 正常 | A=离线、B=100、C=40 | Node B | A 完全离线，B 正常接管 |
| 12 | B MySQL+Keepalived 均停机 | 正常/正常 | 故障/故障（离线） | 正常 | A=110、B=离线、C=40 | Node A | B 完全离线，A 保持 Master |
| 13 | 场景 7 后，A MySQL 恢复 | 恢复/正常 | 故障/正常 | 正常 | A=110、B=50、C=40 | Node A | A 优先级恢复最高，接管 VIP |
| 14 | 场景 7 后，B MySQL 恢复 | 故障/正常 | 恢复/正常 | 正常 | A=60、B=100、C=40 | Node B | B 优先级高于 A，接管 VIP |
| 15 | C Keepalived 停机 | 正常/正常 | 正常/正常 | 故障（离线） | A=110、B=100、C=离线 | Node A | C 仅为仲裁，离线不影响 A/B 选举 |
| 16 | A、B MySQL 均停机 + C 停机 | 故障/正常 | 故障/正常 | 故障（离线） | A=60、B=50、C=离线 | Node A | C 离线不影响 A/B 选举 |
| 17 | 所有节点 Keepalived 均停机 | 正常/故障（离线） | 正常/故障（离线） | 故障（离线） | 全离线 | 无节点绑定 VIP | 无 Keepalived 参与选举，VIP 失联 |
skills/g3fo-docs/references/middleware/mysql/deploy.md
+337
View File
@@ -0,0 +1,337 @@
# MySQL 8.4 双主（Source-Source）同步部署文档（跨主机统一目录/容器名版）
> **AI 响应规范 (MySQL 执行策略)**:
> 1. **强制参数**: 所有 `docker exec` 命令必须包含 `-h127.0.0.1` 参数。
> 2. **双重输出**: 涉及 SQL 操作时，必须同时输出 `Docker 执行命令` 和 `纯 SQL 脚本`。
## 文档概述
你需要部署跨两台独立主机的 MySQL 8.4 双主双向复制集群，核心要求是：两台主机的容器名、目录路径统一使用 `mysql`（仅通过 IP 区分节点），保证两节点数据一致性，支持初始化、校验、宕机重启恢复及节点重建全流程。核心设计遵循：
+ **GTID + AUTO_POSITION**：重启后自动定位同步位点，减少人工干预；
+ **ROW 模式 binlog**：避免非确定性函数导致的数据不一致；
+ **持久化数据卷**：独立 Volume 保障容器重启数据不丢失；
+ **自增键隔离**：通过步长/偏移配置避免双写主键冲突。
## 1. 环境准备
### 1.1 节点信息（核心区分点）
| 节点 | 主机IP | server_id | auto_increment_offset | 核心标识 |
| :--- | :--- | :--- | :--- | :--- |
| 主节点A | ${NODE_A_IP} | 1 | 1 | 生成主键1、3、5… |
| 主节点B | ${NODE_B_IP} | 2 | 2 | 生成主键2、4、6… |
### 1.2 系统依赖（两台主机统一执行）
```plain
# 安装 Docker & Docker Compose、MySQL 客户端
sudo apt update && sudo apt install -y docker.io docker-compose-plugin mysql-client
# 验证依赖（确保版本正常）
docker --version && docker compose version && mysql --version
```
### 1.3 目录规划（两台主机完全一致）
```plain
# 两台主机均执行以下命令，目录统一为 /data/mysql
sudo mkdir -p /data/mysql/{data,backup,logs}
sudo chown 999:999 /data/mysql -R # MySQL 容器默认UID/GID为999，避免权限问题
```
## 2. 双主节点部署
### 2.1 Docker Compose 配置（两台主机完全一致）
创建 `/data/mysql/docker-compose.yml`，内容如下（无节点差异）：
```plain
version: '3.8'
networks:
g3fo:
driver: bridge
services:
mysql:
image: mysql:8.4.7
container_name: mysql # 两台主机容器名统一为mysql
restart: always
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
ports:
- 3306:3306 # 端口统一，通过主机IP区分节点
networks:
- g3fo
volumes:
- /data/mysql/data:/var/lib/mysql
- /data/mysql/backup:/backup
- /data/mysql/my.cnf:/etc/mysql/conf.d/my.cnf
- /data/mysql/logs:/var/log/mysql
- /etc/localtime:/etc/localtime
- /etc/timezone:/etc/timezone
environment:
- TZ=Asia/Hong_Kong
- MYSQL_ROOT_PASSWORD=afe123456 # 两台主机统一密码，生产建议修改
privileged: true # 保障文件权限操作
```
### 2.2 MySQL 配置文件（my.cnf）
#### 节点A（${NODE_A_IP}）：`/data/mysql/my.cnf`
```plain
[mysqld]
# ========== 节点唯一标识（核心区分点） ==========
server_id=1 # 全局唯一，不可与节点B重复
report_host=${NODE_A_IP} # 当前主机IP，便于复制状态识别
datadir=/var/lib/mysql
socket=/var/lib/mysql/mysql.sock
# ========== 基础配置（两台主机一致） ==========
character-set-server=utf8mb4
max_connections=1000
skip_name_resolve=ON # 关闭DNS解析，提升连接效率
# ========== 复制核心配置（两台主机一致） ==========
log_bin=mysql-bin # 开启binlog
binlog_format=ROW # 强制ROW模式，保证复制一致性
binlog_row_image=FULL # 记录完整行数据
binlog_expire_logs_seconds=604800 # 7天自动清理binlog
gtid_mode=ON # 开启GTID模式
enforce_gtid_consistency=ON # 强制GTID事务一致性
log_slave_updates=ON # 从库同步的事务写入自身binlog（双向复制必需）
skip_slave_start=OFF # 重启自动启动复制线程
relay_log_recovery=ON # 重启自动恢复中继日志
max_binlog_size=1G # 单个binlog最大1G
# ========== 数据可靠性（两台主机一致） ==========
innodb_flush_log_at_trx_commit=1 # 事务提交立即刷盘（ACID）
sync_binlog=1 # 每次事务同步binlog到磁盘
# ========== 双主自增键隔离（核心区分点） ==========
auto_increment_increment=2 # 自增步长2（两台主机一致）
auto_increment_offset=1 # 节点A起始值1（生成1、3、5…）
# ========== 日志配置（两台主机一致） ==========
log_error = /var/log/mysql/mysql_error.log # 错误日志
log_error_verbosity = 2 # 记录错误+警告
slow_query_log = 1 # 开启慢查询日志
slow_query_log_file = /var/log/mysql/mysql_slow.log
long_query_time = 2 # 慢查询阈值2秒
# ========== 读写权限（两台主机一致） ==========
read_only=OFF
super_read_only=OFF
```
#### 节点B（${NODE_B_IP}）：`/data/mysql/my.cnf`
```plain
[mysqld]
# ========== 节点唯一标识（核心区分点） ==========
server_id=2 # 与节点A区分
report_host=${NODE_B_IP} # 当前主机IP
datadir=/var/lib/mysql
socket=/var/lib/mysql/mysql.sock
# ========== 基础配置（与节点A一致） ==========
character-set-server=utf8mb4
max_connections=1000
skip_name_resolve=ON
# ========== 复制核心配置（与节点A一致） ==========
log_bin=mysql-bin
binlog_format=ROW
binlog_row_image=FULL
binlog_expire_logs_seconds=604800
gtid_mode=ON
enforce_gtid_consistency=ON
log_slave_updates=ON
skip_slave_start=OFF
relay_log_recovery=ON
max_binlog_size=1G
# ========== 数据可靠性（与节点A一致） ==========
innodb_flush_log_at_trx_commit=1
sync_binlog=1
# ========== 双主自增键隔离（核心区分点） ==========
auto_increment_increment=2
auto_increment_offset=2 # 节点B起始值2（生成2、4、6…）
# ========== 日志配置（与节点A一致） ==========
log_error = /var/log/mysql/mysql_error.log
log_error_verbosity = 2
slow_query_log = 1
slow_query_log_file = /var/log/mysql/mysql_slow.log
long_query_time = 2
# ========== 读写权限（与节点A一致） ==========
read_only=OFF
super_read_only=OFF
```
### 2.3 启动容器（两台主机统一执行）
```plain
# 进入目录并启动容器
cd /data/mysql && docker compose up -d
# 验证启动状态（确保容器状态为Up）
docker ps | grep mysql
```
## 3. 双主复制初始化
### 3.1 创建复制专用用户（两台主机统一执行）
```plain
# 无需区分节点，直接执行（创建repl用户，允许跨主机访问）
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
CREATE USER 'repl'@'%' IDENTIFIED BY 'afe123456';
GRANT REPLICATION SLAVE ON *.* TO 'repl'@'%';
FLUSH PRIVILEGES;
"
```
### 3.2 配置双向复制（核心：仅IP参数不同）
#### 步骤1：节点A（${NODE_A_IP}）配置为节点B的从库
```plain
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
STOP REPLICA;
RESET REPLICA ALL;
CHANGE REPLICATION SOURCE TO
SOURCE_HOST = '${NODE_B_IP}', # 节点B的IP（核心区分点）
SOURCE_PORT = 3306,
SOURCE_USER = 'repl',
SOURCE_PASSWORD = 'afe123456',
SOURCE_AUTO_POSITION = 1, # GTID自动定位（无需手动找位点）
SOURCE_CONNECT_RETRY = 10,
SOURCE_RETRY_COUNT = 86400,
GET_SOURCE_PUBLIC_KEY = 1; # 适配MySQL 8.0+密码认证
START REPLICA;
"
```
#### 步骤2：节点B（${NODE_B_IP}）配置为节点A的从库
```plain
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
STOP REPLICA;
RESET REPLICA ALL;
CHANGE REPLICATION SOURCE TO
SOURCE_HOST = '${NODE_A_IP}', # 节点A的IP（核心区分点）
SOURCE_PORT = 3306,
SOURCE_USER = 'repl',
SOURCE_PASSWORD = 'afe123456',
SOURCE_AUTO_POSITION = 1,
SOURCE_CONNECT_RETRY = 10,
SOURCE_RETRY_COUNT = 86400,
GET_SOURCE_PUBLIC_KEY = 1;
START REPLICA;
"
```
## 4. 同步状态校验
### 4.1 核心校验命令（两台主机统一执行）
**A. Docker 执行模式 (包含 -h127.0.0.1):**
```bash
# 查看复制状态
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "SHOW REPLICA STATUS\G"
```
**B. 纯 SQL 模式:**
```sql
SHOW REPLICA STATUS\G
```
### 4.2 关键校验字段（必须全部满足）
| 字段 | 目标值 | 说明 |
| :--- | :--- | :--- |
| Replica_IO_Running | Yes | IO线程正常（接收binlog） |
| Replica_SQL_Running | Yes | SQL线程正常（执行事务） |
| Last_SQL_Error | 空 | 无同步错误 |
| Seconds_Behind_Source | 0 | 无同步延迟 |
| Retrieved_Gtid_Set | 非空 | 已获取对端节点GTID |
| Executed_Gtid_Set | 包含Retrieved_Gtid_Set | 已执行所有获取的事务 |
### 4.3 数据一致性验证
```plain
# 节点A（${NODE_A_IP}）创建测试数据
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
CREATE DATABASE IF NOT EXISTS test_sync;
USE test_sync;
CREATE TABLE IF NOT EXISTS t1 (id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(20));
INSERT INTO t1 (name) VALUES ('nodeA_test');
"
# 节点B（${NODE_B_IP}）验证同步（应能查到nodeA_test数据）
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "SELECT * FROM test_sync.t1;"
# 节点B插入数据，节点A验证同步
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "INSERT INTO test_sync.t1 (name) VALUES ('nodeB_test');"
docker exec -it mysql mysql -uroot -pafe123456 -h${NODE_A_IP} -e "SELECT * FROM test_sync.t1;"
```
## 5. 故障处理流程
### 5.1 宕机重启恢复
#### 场景：容器/主机重启后复制未自动恢复（两台主机操作逻辑一致，仅IP不同）
```plain
# 以节点A（${NODE_A_IP}）为例，恢复与节点B的复制关系
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
STOP REPLICA;
# 重新指定复制源（利用GTID自动定位，无需手动找位点）
CHANGE REPLICATION SOURCE TO
SOURCE_HOST = '${NODE_B_IP}', # 对端节点IP
SOURCE_PORT = 3306,
SOURCE_USER = 'repl',
SOURCE_PASSWORD = 'afe123456',
SOURCE_AUTO_POSITION = 1,
GET_SOURCE_PUBLIC_KEY = 1;
START REPLICA;
# 验证状态
SHOW REPLICA STATUS\G;
"
# 节点B执行时，仅需将SOURCE_HOST改为${NODE_A_IP}即可
```
### 5.2 重建节点（单节点数据损坏/丢失）
#### 步骤1：从正常节点全量备份（假设节点B损坏，从节点A备份）
```plain
# 节点A（${NODE_A_IP}）执行备份
docker exec -it mysql mysqldump -uroot -pafe123456 -h127.0.0.1 --all-databases --master-data=2 --single-transaction > /data/mysql/backup/full_backup.sql
# 将备份文件复制到损坏的节点B（${NODE_B_IP}）
scp /data/mysql/backup/full_backup.sql root@${NODE_B_IP}:/data/mysql/backup/
```
#### 步骤2：停止损坏节点并恢复数据（节点B执行）
```plain
# 停止mysql容器
cd /data/mysql && docker compose down
# 清空损坏数据（保留目录结构）
sudo rm -rf /data/mysql/data/*
# 重启mysql容器（初始化空库）
docker compose up -d
# 导入备份数据
docker exec -i mysql mysql -uroot -pafe123456 < /data/mysql/backup/full_backup.sql
```
#### 步骤3：重新配置双向复制
参考「3.2 配置双向复制」，重新执行节点B作为节点A从库、节点A作为节点B从库的配置命令（仅IP参数区分）。
### 5.3 复制冲突解决
详细的冲突定位与修复流程，请参考：[MySQL 复制冲突解决指南](./fault-analysis.md)
## 6. 日志管理
详细的日志轮转与安全登录配置，请参考：[MySQL 日志管理指南](./log-management.md)
## 7. 重要提醒
### 7.1 核心区分点（避免配置错误）
+ 两台主机仅 `server_id`、`report_host`（IP）、`auto_increment_offset` 三个参数不同，其余配置完全一致；
+ 容器名、目录路径、端口均统一为 `mysql`/`/data/mysql`/3306，通过主机IP区分节点。
### 7.2 一致性限制
+ MySQL原生异步双主复制**无法保证严格的数据一致性**，双写场景仍可能出现冲突；
+ 生产环境建议**单写多读**（指定一个节点为写节点，另一个为读节点），避免双写冲突。
#### 总结
#### 跨主机双主复制的核心差异仅为 `server_id`、主机IP、自增偏移量，其余目录/容器名/配置可完全统一；
#### 同步故障优先通过错误日志定位冲突，修复数据而非跳过事务（避免永久不一致）；
#### GTID模式下无需手动定位同步位点，重启/重建节点时仅需重新指定对端IP即可自动恢复复制。
skills/g3fo-docs/references/middleware/mysql/fault-analysis.md
+76
View File
@@ -0,0 +1,76 @@
# MySQL 8.4 复制冲突解决指南
> **AI 响应规范 (MySQL 执行策略)**:
> 1. **强制参数**: 所有 `docker exec` 命令必须包含 `-h127.0.0.1` 参数。
> 2. **双重输出**: 涉及 SQL 操作时，必须同时输出 `Docker 执行命令` 和 `纯 SQL 脚本`。
> 3. **默认连接**: 默认使用 `-uroot -pafe123456 -h127.0.0.1`。
## 1. 复制冲突解决（主键/唯一键重复）
### 1.1 快速定位冲突信息
提取冲突 GTID、表、值（直接执行，自动解析错误日志）：
```bash
grep "Duplicate entry" /data/mysql/logs/mysql_error.log | perl -nle '
if (/^(\S+).*?transaction\s+'\''([^'\'']+)'\''.*?table\s+([^\s;]+);.*?Duplicate entry\s+'\''([^'\'']+)'\''\s+for\s+key\s+'\''([^'\'']+)'\''/) {
print "\n" . "="x50;
print "时间: $1";
print "GTID: $2";
print "表名: $3";
print "冲突值: $4 (索引: $5)";
print "\n方案 A (删除冲突行):";
print "DELETE FROM $3 WHERE [主键列] = \x27$4\x27;";
print "\n方案 B (跳过此事务):";
print "STOP REPLICA; SET GTID_NEXT=\x27$2\x27; BEGIN; COMMIT; SET GTID_NEXT=\x27AUTOMATIC\x27; START REPLICA;";
}
'
```
### 1.2 安全修复冲突（推荐删除冲突数据）
停止复制，临时关闭 binlog（避免删除操作同步到对端）：
**A. Docker 执行模式 (包含 -h127.0.0.1):**
```bash
# 以实际冲突表和主键为例（示例：test_sync.t1 的 id=12）
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
STOP REPLICA;
SET sql_log_bin = OFF;
DELETE FROM `test_sync`.`t1` WHERE `id` = 12;
SET sql_log_bin = ON;
START REPLICA;
SHOW REPLICA STATUS\G;
"
```
**B. 纯 SQL 模式:**
```sql
STOP REPLICA;
SET sql_log_bin = OFF;
DELETE FROM `test_sync`.`t1` WHERE `id` = 12;
SET sql_log_bin = ON;
START REPLICA;
SHOW REPLICA STATUS\G;
```
### 1.3 应急跳过冲突事务（仅紧急场景）
精准跳过指定 GTID 事务（MySQL 8.0+ 推荐）：
**A. Docker 执行模式 (包含 -h127.0.0.1):**
```bash
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
STOP REPLICA;
SET GTID_NEXT = '760f0600-f896-11ef-b265-0242ac130002:6'; # 替换为实际冲突 GTID
BEGIN; COMMIT;
SET GTID_NEXT = 'AUTOMATIC';
START REPLICA;
"
```
**B. 纯 SQL 模式:**
```sql
STOP REPLICA;
SET GTID_NEXT = '760f0600-f896-11ef-b265-0242ac130002:6';
BEGIN; COMMIT;
SET GTID_NEXT = 'AUTOMATIC';
START REPLICA;
```
skills/g3fo-docs/references/middleware/mysql/log-management.md
+89
View File
@@ -0,0 +1,89 @@
# MySQL 8.4 日志管理指南
> **AI 响应规范 (MySQL 执行策略)**:
> 1. **强制参数**: 所有 `docker exec` 命令必须包含 `-h127.0.0.1` 参数。
> 2. **双重输出**: 涉及 SQL 操作时，必须同时输出 `Docker 执行命令` 和 `纯 SQL 脚本`。
## 1. 日志轮转配置
防止日志文件过大，两台主机配置一致。创建 `/etc/logrotate.d/mysql_error_log`：
```plain
/data/mysql/logs/mysql_error.log /data/mysql/logs/mysql_slow.log {
daily # 每天轮转
missingok # 文件不存在不报错
rotate 30 # 保留30天日志
compress # 压缩旧日志
delaycompress # 延迟压缩（避免写入异常）
notifempty # 空文件不轮转
create 644 # 新日志权限
postrotate
# 刷新MySQL日志文件
docker exec mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "FLUSH ERROR LOGS; FLUSH SLOW LOGS;" || true
endscript
}
```
### 1.1 手动测试日志轮转
```bash
logrotate -f /etc/logrotate.d/mysql_error_log
```
## 2. 加密登录配置（.mylogin.cnf）
### 2.1 配置目的
为避免执行日志刷新操作时明文暴露数据库账号密码，通过 `mysql_config_editor` 生成加密的 `.mylogin.cnf` 文件，实现安全、免密的日志操作。
### 2.2 操作步骤
#### 步骤 1：在宿主机器生成加密登录配置
直接在宿主机器执行以下命令（两台双主节点均需执行）：
```bash
mysql_config_editor set \
--login-path=mysql_log_flush \ # 自定义标识
--user=log_flush \ # 提前创建的日志操作专用低权限账号
--password \ # 交互式输入密码
--host=127.0.0.1 \ # 本地连接地址
--port=3306 # MySQL 服务端口
```
#### 步骤 2：将配置文件同步至 MySQL 容器
有两种实现方式：
**方式 1：复制配置文件到容器内**
```bash
sudo docker cp ~/.mylogin.cnf mysql:/root/.mylogin.cnf
```
**方式 2：执行命令时临时挂载配置文件**
```bash
docker exec -v ~/.mylogin.cnf:/root/.mylogin.cnf mysql \
mysql --login-path=mysql_log_flush -e "FLUSH ERROR LOGS; FLUSH SLOW LOGS;"
```
#### 步骤 3：使用加密配置执行日志操作
```bash
docker exec mysql mysql --login-path=mysql_log_flush -e "FLUSH ERROR LOGS; FLUSH SLOW LOGS;"
```
### 2.3 安全与权限注意事项
1. **专用账号权限最小化**：仅授予 `RELOAD` 权限。
**A. Docker 执行模式:**
```bash
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
CREATE USER 'log_flush'@'127.0.0.1' IDENTIFIED BY 'afe123456';
GRANT RELOAD ON *.* TO 'log_flush'@'127.0.0.1';
FLUSH PRIVILEGES;
"
```
**B. 纯 SQL 模式:**
```sql
CREATE USER 'log_flush'@'127.0.0.1' IDENTIFIED BY 'afe123456';
GRANT RELOAD ON *.* TO 'log_flush'@'127.0.0.1';
FLUSH PRIVILEGES;
```
2. **配置文件权限管控**：`.mylogin.cnf` 权限应为 600。
3. **密码更新处理**：若密码修改，需重新生成配置。
skills/g3fo-docs/references/middleware/redis/deploy.md
+336
View File
@@ -0,0 +1,336 @@
# Redis Sentinel 高可用架构部署与运维手册
## 一、概述
### 1.1 核心功能
Redis Sentinel（哨兵）是 Redis 的高可用解决方案。其核心目标是实现主从切换的自动化，确保系统在主节点故障时能够自动选举新的主节点并恢复服务。
### 1.2 适用场景
- 生产环境下的 Redis 高可用需求。
- 需要自动故障转移（Failover）的分布式系统。
- 读写分离架构。
### 1.3 前置条件
- **运行环境**：Docker & Docker Compose。
- **镜像版本**：推荐使用 Redis 8.4.0 及以上版本。
- **网络规划**：所有节点需网络互通，且需明确各宿主机的外部 IP。
---
## 二、环境准备
在所有节点（主节点、从节点、哨兵节点）上执行目录初始化及权限设置。
### 2.1 目录结构配置
```bash
# 创建配置、数据、日志目录
mkdir -p /data/redis/{conf,data,logs}
# 权限初始化（针对 Redis 容器默认用户 999）
chown -R 999:999 /data/redis
chmod -R 750 /data/redis
```
---
## 三、部署流程
### 3.1 Docker 服务编排
使用 Docker Compose 部署 Redis 服务及 Sentinel 节点。
**docker-compose.yml 示例：**
```yaml
version: '3.8'
services:
# Redis 节点容器
redis:
image: redis:8.4.0
container_name: redis
restart: always
ports:
- "6379:6379"
volumes:
- /etc/localtime:/etc/localtime:ro
- /etc/timezone:/etc/timezone:ro
- /data/redis/conf:/etc/redis
- /data/redis/data:/data
- /data/redis/logs:/var/log/redis
command: redis-server /etc/redis/redis.conf
networks:
- redis-net
# Sentinel 节点容器
redis-sentinel:
image: redis:8.4.0
container_name: redis-sentinel
restart: always
ports:
- "26379:26379"
volumes:
- /data/redis/conf:/etc/redis
- /data/redis/logs:/var/log/redis
command: redis-sentinel /etc/redis/sentinel.conf
networks:
- redis-net
networks:
redis-net:
driver: bridge
```
---
## 四、核心配置说明
### 4.1 Redis 服务端配置 (`redis.conf`)
```Properties
# 基础配置
bind 0.0.0.0
# 需被远程连接，关闭这配置
protected-mode no
port 6379
# 指定广播地址，即使 Docker 内部获取到的是 172.x，也强制告诉 Sentinel 我是 ${REDIS_MASTER_IP}
replica-announce-ip ${REDIS_MASTER_IP}
replica-announce-port 6379
# Docker中禁止后台运行（由容器管理）
daemonize no
pidfile /var/run/redis.pid
logfile /var/log/redis/redis.log
# 容器内数据目录（对应宿主机/data/redis/data）
dir /data
# 密码配置（建议修改为自己的密码）
requirepass afe123456
# 允许从节点同步时使用的密码
masterauth afe123456
# 持久化配置（按需调整，默认开启RDB）
# 当满足 “900 秒（15 分钟）内发生至少 1 次写操作” 时，触发 RDB 持久化（将内存中的数据快照写入磁盘）
save 900 1
save 300 10
save 60 10000
# 开启 RDB 文件的压缩功能
rdbcompression yes
# 指定 RDB 快照文件的名称
dbfilename dump.rdb
# 主从复制配置（AP1是主节点，无需配置replicaof）
# 开启无盘同步（减少磁盘IO）
repl-diskless-sync yes
# 无盘同步的延迟时间（单位：秒，默认值为 5）
repl-diskless-sync-delay 5
# 复制积压缓冲区（动态扩容，Redis 8.4默认支持）
repl-backlog-size 1mb
# 其他优化配置
# 内存满时淘汰策略
maxmemory-policy allkeys-lru
# 1. 开启 AOF 持久化
appendonly yes
# 2. 指定 AOF 文件名（Redis 7+ 这是一个目录名的一前缀）
appendfilename "appendonly.aof"
# 3. 开启混合持久化 (核心配置)
# 在 AOF 重写时，会先写入 RDB 格式的快照，再追加增量指令
aof-use-rdb-preamble yes
# 4. 刷盘策略 (性能与安全的平衡)
# 每秒刷盘一次，意味着死机最多丢失 1 秒的数据
appendfsync everysec
# 5. 重写触发机制 (防止文件无限膨胀)
# 当 AOF 文件比上次重写后大小增长 100% 且文件大于 64MB 时触发重写
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb
notify-keyspace-events AE
```
从节点添加配置
```Properties
# 指定广播地址，即使 Docker 内部获取到的是 172.x，也强制告诉 Sentinel 我是 ${REDIS_SLAVE_IP}
replica-announce-ip ${REDIS_SLAVE_IP}
replica-announce-port 6379
# 核心：指定主节点（AP1的IP和端口）
replicaof ${REDIS_MASTER_IP} 6379
# 从节点只读（默认开启，避免误写）
replica-read-only yes
```
以下为生产环境推荐的核心配置项：
| 配置项 | 说明 | 推荐值 |
| :--- | :--- | :--- |
| `bind` | 绑定 IP 地址 | `0.0.0.0` |
| `protected-mode` | 保护模式 | `no` |
| `port` | 监听端口 | `6379` |
| `replica-announce-ip` | 宣告外部 IP（解决 Docker NAT 问题） | 宿主机实际 IP |
| `requirepass` | 服务访问密码 | 自定义强密码 |
| `masterauth` | 主从同步授权密码 | 与 `requirepass` 一致 |
| `appendonly` | 开启 AOF 持久化 | `yes` |
| `aof-use-rdb-preamble` | 开启混合持久化 | `yes` |
> **注意：** 在从节点配置中，必须包含 `replicaof <master-ip> 6379` 以建立主从关系。
### 4.2 哨兵配置 (`sentinel.conf`)
```Properties
# 基础配置
bind 0.0.0.0
protected-mode no
port 26379
# 强制向其他哨兵和客户端宣告自己的外部IP，从节点需要修复对应自主机IP
sentinel announce-ip ${REDIS_MASTER_IP}
sentinel announce-port 26379
# Docker中禁止后台运行
daemonize no
logfile /var/log/redis/sentinel.log
dir /tmp
# 监控主节点（名称mymaster，主节点IP=AP1的IP，端口6379，quorum=2）
sentinel monitor mymaster ${REDIS_MASTER_IP} 6379 2
# 主节点密码（与Redis主节点一致）
sentinel auth-pass mymaster afe123456
# 故障检测超时时间（30秒，可调整）
sentinel down-after-milliseconds mymaster 30000
# 故障转移时，最多1个从节点同时同步新主节点（避免带宽占用过高）
sentinel parallel-syncs mymaster 1
# 故障转移超时时间（180秒）
sentinel failover-timeout mymaster 180000
# 禁止Sentinel在故障转移后自动重配置主节点（Docker环境下无需开启）
sentinel deny-scripts-reconfig yes
```
哨兵节点用于监控主节点状态并协调切换。
| 配置项 | 说明 | 示例值 |
| :--- | :--- | :--- |
| `sentinel monitor` | 监控主节点（名称、IP、端口、法定人数） | `mymaster ${REDIS_MASTER_IP} 6379 2` |
| `sentinel auth-pass` | 主节点访问密码 | `mymaster afe123456` |
| `sentinel down-after-milliseconds` | 故障判定超时时间（毫秒） | `30000` |
| `sentinel failover-timeout` | 故障转移超时时间 | `180000` |
| `sentinel announce-ip` | 宣告哨兵外部 IP | 宿主机实际 IP |
---
## 五、客户端集成（Redisson）
在 Spring Boot 应用中，使用 Redisson 实现哨兵模式的连接：
```yaml
spring:
redis:
redisson:
config: |
sentinelServersConfig:
masterName: "mymaster" # Sentinel 里监控主库的名字（sentinel monitor <name> ...）
sentinelAddresses: # Sentinel 节点地址列表（redis://host:port）
- "redis://${REDIS_MASTER_IP}:26379"
- "redis://${REDIS_SLAVE_IP}:26379"
- "redis://${REDIS_SENTINEL_3_IP}:26379"
# --- 认证（Redis 6+ ACL 也可用 username）---
password: "afe123456" # Redis 主从节点密码（requirepass / ACL 密码）
sentinelPassword: "afe123456" # Sentinel 密码（requirepass / ACL 密码）；若与 password 相同也可省略
# --- DB ---
database: ${app.redis-database:0} # 选择 DB（0~15，取决于你的 redis 配置）
# --- 启动检查 / 发现 ---
checkSentinelsList: true # 启动时校验 Sentinel 列表（默认 true）
sentinelsDiscovery: true # 是否自动发现更多 sentinel（默认 true；Docker/NAT 环境可考虑关掉避免“拓扑污染”）
dnsMonitoringInterval: 5000 # DNS 变更监控间隔 ms；-1 表示禁用（对域名方式接入有用）
# --- 读写/订阅模式 ---
readMode: "MASTER" # 读策略：SLAVE / MASTER / MASTER_SLAVE
subscriptionMode: "MASTER" # 订阅（pubsub）连接使用节点：SLAVE / MASTER
checkSlaveStatusWithSyncing: true # 检查 slave 的 master-link-status=ok（默认 true）
# --- 负载均衡（可选，默认 RoundRobin）---
# 注意：下面这种 !<class> 写法需要 YAML 标签支持（Redisson 原生 YAML 支持）
loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
# --- 连接池（重要：这些是“每个节点”的池大小）---
masterConnectionMinimumIdleSize: 24 # 每个 master 最小空闲连接数（默认 24）
masterConnectionPoolSize: 64 # 每个 master 最大连接数（默认 64）
slaveConnectionMinimumIdleSize: 24 # 每个 slave 最小空闲连接数（默认 24）
slaveConnectionPoolSize: 64 # 每个 slave 最大连接数（默认 64）
# --- 订阅连接池（pubsub）---
subscriptionConnectionMinimumIdleSize: 1 # 订阅连接最小空闲数（默认 1）
subscriptionConnectionPoolSize: 50 # 订阅连接最大连接数（默认 50）
subscriptionsPerConnection: 5 # 每条订阅连接允许的订阅数上限（默认 5）
subscriptionTimeout: 7500 # 订阅超时 ms（默认 7500）
# --- 超时与重试 ---
idleConnectionTimeout: 10000 # 连接空闲多久后可被回收 ms（默认 10000）
connectTimeout: 10000 # 建连超时 ms（默认 10000）
timeout: 6000 # 命令响应超时 ms（默认 3000，从成功发送命令后开始计时）
retryAttempts: 4 # 命令发送失败重试次数（默认 4）
# --- 连接保活 ---
pingConnectionInterval: 30000 # 定期 PING 检测死连接 ms；0 关闭（默认 30000）
keepAlive: false # TCP keepAlive（默认 false）
tcpNoDelay: true # TCP_NODELAY（默认 true）
# --- 故障 slave 处理 ---
failedSlaveReconnectionInterval: 3000 # slave 断线后重连尝试间隔 ms（默认 3000）
failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
threads: 16 # Redisson 业务线程池（默认 16；监听/远程服务等）
nettyThreads: 32 # Netty IO 线程（默认 32；0=CPU*2）
transportMode: "NIO" # NIO / EPOLL / KQUEUE（默认 NIO）
protocol: "RESP2" # RESP2 / RESP3（默认 RESP2）
# 编解码器（默认 Kryo5Codec；你用 JsonJacksonCodec 也可以）
codec:
class: "org.redisson.codec.JsonJacksonCodec"
# 分布式锁看门狗（默认 30000ms；无 leaseTimeout 的锁依赖它续期）
lockWatchdogTimeout: 30000
# 其他通用项（按需）
lazyInitialization: false # true=首次用到才连接；false=启动即连接
useThreadClassLoader: true # 解决部分容器 ClassNotFound 问题
keepPubSubOrder: true # PubSub 消息是否保持到达顺序
useScriptCache: true # Lua 脚本缓存
# 下面这些是高级项/按需再开：
valkeyCapabilities: [] # 例如 ["REDIRECT"]
lockWatchdogBatchSize: 100
checkLockSyncedSlaves: true
slavesSyncTimeout: 1000
reliableTopicWatchdogTimeout: 600000
minCleanUpDelay: 5
maxCleanUpDelay: 1800
cleanUpKeysAmount: 100
```
---
## 六、运维常用命令
### 6.1 哨兵管理命令
详细的 Redis 常用命令及 Sentinel 运维操作请参考：[Redis 常用命令使用指南](./usage.md)
通过 `redis-cli` 连接哨兵端口（默认 26379）执行：
| 命令 | 功能描述 |
| :--- | :--- |
| `SENTINEL masters` | 列出所有被监控的主节点状态 |
| `SENTINEL master <name>` | 查看指定主节点的详细信息 |
| `SENTINEL slaves <name>` | 查看指定主节点的从节点列表 |
| `SENTINEL sentinels <name>` | 列出除当前节点外的其他哨兵实例 |
| `SENTINEL get-master-addr-by-name <name>` | 获取当前有效的主节点 IP 和端口 |
| `SENTINEL failover <name>` | **手动强制触发**故障转移 |
| `SENTINEL reset <pattern>` | 重置配置，清除过期节点信息 |
| `SENTINEL ckquorum <name>` | 检查当前哨兵数量是否满足法定人数 |
---
## 七、注意事项与最佳实践
> 注意：
> 1. **脑裂保护**：建议配置 `min-replicas-to-write 1` 和 `min-replicas-max-lag 10`，确保主库至少有 1 个正常的从库时才允许写入，防止网络分区导致的数据丢失。
> 2. **Docker 网络**：在容器环境下，务必配置 `replica-announce-ip` 和 `sentinel announce-ip`，否则哨兵可能会记录容器内部 IP 导致客户端无法连接。
> 3. **持久化平衡**：推荐开启混合持久化（AOF + RDB），并设置 `appendfsync everysec` 以平衡性能与安全性。
> 4. **权限细化**：生产环境建议将 `/data/redis` 目录权限进一步收紧，仅允许特定 UID 访问。
---
**参考资料**：[Redisson 官方配置文档](https://redisson.pro/docs/configuration/#sentinel-yaml-config-format)
skills/g3fo-docs/references/middleware/redis/usage.md
+105
View File
@@ -0,0 +1,105 @@
# Redis 常用命令使用指南
本手册涵盖了 Redis 日常运维、开发及 Sentinel 高可用管理中常用的核心命令。
## 一、 基础连接与管理
### 1.1 连接命令
```bash
# 标准连接
redis-cli -h <host> -p <port> -a <password>
# 连接哨兵节点示例
redis-cli -h ${REDIS_MASTER_IP} -p 26379 -a afe123456
```
### 1.2 系统管理
| 命令 | 说明 |
| :--- | :--- |
| `PING` | 检查连接是否存活，返回 PONG 表示正常 |
| `AUTH <password>` | 身份验证 |
| `SELECT <db_index>` | 切换数据库（默认 0-15） |
| `INFO` | 查看服务器详细信息（CPU、内存、持久化、主从等） |
| `CONFIG GET <parameter>` | 获取配置参数 |
| `CONFIG SET <parameter> <value>` | 动态修改配置参数（不持久化到文件，需执行 REWRITE） |
| `CONFIG REWRITE` | 将动态修改的配置重写到配置文件中 |
| `DBSIZE` | 返回当前数据库中的 key 数量 |
| `FLUSHDB` | 清空当前数据库中所有 key（谨慎使用） |
| `FLUSHALL` | 清空所有数据库中所有 key（谨慎使用） |
---
## 二、 键值对操作 (Key)
| 命令 | 说明 |
| :--- | :--- |
| `KEYS <pattern>` | 查找符合模式的 key（生产环境严禁使用 `KEYS *`，建议用 `SCAN`） |
| `EXISTS <key>` | 判断 key 是否存在 |
| `DEL <key>` | 删除 key |
| `TYPE <key>` | 查看 key 存储的数据类型 |
| `EXPIRE <key> <seconds>` | 设置 key 的过期时间（秒） |
| `TTL <key>` | 查看 key 的剩余存活时间（-1 永久，-2 已过期） |
| `RENAME <key> <newkey>` | 修改 key 名称 |
---
## 三、 常用数据结构操作
### 3.1 字符串 (String)
- `SET <key> <value>`: 设置键值。
- `GET <key>`: 获取值。
- `INCR <key>`: 自增 1。
- `SETEX <key> <seconds> <value>`: 设置键值及过期时间。
### 3.2 列表 (List)
- `LPUSH <key> <value>`: 从左侧插入。
- `RPUSH <key> <value>`: 从右侧插入。
- `LPOP <key>`: 从左侧弹出。
- `LRANGE <key> <start> <stop>`: 获取范围内的元素。
### 3.3 哈希 (Hash)
- `HSET <key> <field> <value>`: 设置哈希字段。
- `HGET <key> <field>`: 获取哈希字段。
- `HGETALL <key>`: 获取所有字段和值。
### 3.4 集合 (Set)
- `SADD <key> <member>`: 添加元素。
- `SMEMBERS <key>`: 获取所有成员。
- `SISMEMBER <key> <member>`: 判断是否为成员。
---
## 四、 Sentinel (哨兵) 核心管理命令
通过 `redis-cli` 连接哨兵端口（默认 26379）后执行：
| 命令 | 说明 |
| :--- | :--- |
| `SENTINEL masters` | **查看哨兵监控的所有主节点状态** |
| `SENTINEL master <name>` | 查看指定主节点的详细信息 |
| `SENTINEL slaves <name>` | **查询指定主节点（如 mymaster）下的所有从节点** |
| `SENTINEL sentinels <name>` | **列出除当前连接外的其他 Sentinel 实例** |
| `SENTINEL get-master-addr-by-name <name>` | 获取当前有效的主节点 IP 和端口 |
| `SENTINEL ckquorum <name>` | 检查当前哨兵数量是否满足法定人数 |
| `SENTINEL failover <name>` | **手动强制触发故障转移** |
| `SENTINEL reset <pattern>` | **重置配置，清除过期或不在线的从节点/哨兵信息** |
---
## 五、 持久化与同步运维
| 命令 | 说明 |
| :--- | :--- |
| `SAVE` | 同步保存数据到磁盘（会阻塞 Redis） |
| `BGSAVE` | 异步保存数据到磁盘 |
| `BGREWRITEAOF` | 异步重写 AOF 文件 |
| `LASTSAVE` | 查看最后一次成功保存到磁盘的时间戳 |
| `ROLE` | 查看当前实例的角色（master/slave/sentinel） |
---
## 六、 官方文档参考
- [Redis Commands (Official)](https://redis.io/commands)
- [Redis Sentinel Documentation](https://redis.io/docs/management/sentinel/)
- [Redis Administration](https://redis.io/docs/management/admin/)