# Debian 12 多节点部署手册

本文档描述仓库当前的三节点 Compose 部署。实际参数以 `backend/docker-compose-node-01.yml`、`docker-compose-node-02.yml`、`docker-compose-node-03.yml` 和 `backend/config` 为准。

## 节点职责

默认拓扑为三台 Debian 12 主机：

| 节点 | 主要职责 |
| --- | --- |
| Node-01 | MySQL 主库、Redis 主节点、Nacos、RocketMQ NameServer/Broker、MinIO 业务写入点、网关和业务服务 |
| Node-02 | MySQL/Redis 从节点、Nacos、RocketMQ、MinIO 同步副本及业务服务副本 |
| Node-03 | MySQL/Redis 从节点、Nacos、RocketMQ Broker-B、MinIO 备用实例与监控 exporter |

节点 IP、网卡名和资源规格不是代码常量，部署前通过各节点环境文件设置。不要直接照抄旧文档中的密码或 IP。

## 前置条件

- 三节点安装 Docker Engine 和 Compose v2，时钟同步，节点间放行 Docker 网络所需端口。
- 三节点使用相同代码版本、Nacos 认证参数、数据库密码、Redis 密码和 JWT secret。
- Node-01 先准备 MySQL 主库和 Nacos schema；从节点不重复执行初始化 SQL。

## 配置

从 `backend/.env.example` 复制一份部署环境文件，至少设置：

```text
MYSQL_ROOT_PASSWORD
MYSQL_APP_USER
MYSQL_APP_PASSWORD
REDIS_PASSWORD
MINIO_ACCESS_KEY
MINIO_SECRET_KEY
MINIO_BUCKET
USER_JWT_SECRET
ADMIN_JWT_SECRET
SERVICE_AUTH_TOKEN
NACOS_USERNAME
NACOS_PASSWORD
NACOS_AUTH_TOKEN
```

同时为每个节点设置 `HOST_IP`、`NACOS_SERVERS`、`REDIS_SENTINEL_NODES`；Node-02/03 的业务服务将数据库和 MinIO 写入目标指向 Node-01。仓库提供的 `backend/scripts/minio-sync-node01-to-node02.sh` 只负责 Node-01 到 Node-02 的对象镜像，Node-03 实例不应被描述为已自动同步。所有 secret 必须是部署方自行生成的值。

## 启动顺序

在 Node-01：

```bash
cd backend
docker compose --env-file .env -f docker-compose-node-01.yml up -d
```

在 Node-02 和 Node-03 使用各自环境文件和 compose 文件启动。先观察 MySQL、Redis、Nacos、NameServer、Broker、MinIO 健康，再启动或重建业务服务：

```bash
docker compose --env-file .env -f docker-compose-node-02.yml up -d
docker compose --env-file .env -f docker-compose-node-03.yml up -d
docker compose -f docker-compose-node-01.yml ps
```

业务服务统一使用 `SPRING_PROFILES_ACTIVE=ha`，端口为网关 `9000`、认证 `9001`、用户 `9002`、内容 `9003`、评论 `9004`、推荐 `9005`、管理 `9006`。

## 验证

```bash
docker compose -f docker-compose-node-01.yml ps
curl http://<gateway-host>:9000/actuator/health
curl http://<nacos-host>:8848/nacos/v1/console/health/liveness
```

在 Nacos 控制台确认每个业务服务注册了正确的宿主机 IP，而不是 Docker 内网地址；在 Redis Sentinel 中确认主节点；在 MySQL 中确认从库复制状态。停止 Node-01 后，先验证 Sentinel 提升与业务读写，再恢复节点。

## 存储与高可用边界

- MySQL 使用主从复制，业务写入仍以主库为准。
- Redis 使用主从 + Sentinel，业务服务通过 `common-redis-ha.yaml` 连接 Sentinel。
- Nacos 使用三节点集群和共享 `nacos_config` 数据库。
- MinIO 当前采用 Node-01 单写入点、Node-02 定时镜像副本的方案；Node-03 是备用实例，不是原生 MinIO 分布式纠删码集群。
- RocketMQ 部署 NameServer 与 Broker-A/B；消息主题和 broker 配置以 `backend/config/rocketmq` 为准。

## 安全与备份

生产环境不要公开 MySQL、Redis、Nacos、RocketMQ 和 MinIO Console；仅暴露网关及前端站点。定期备份 MySQL 逻辑数据、Nacos 配置和 MinIO 对象，并在恢复演练后再进行版本升级。