Files

T

Toys-A 30c17f01e9 docs: Refresh deployment and API documentation

- Align deployment guidance with the current three-node Compose topology
- Document the current frontend architecture and development workflow
- Replace the stale API list with a controller-based route index

2026-08-18 23:37:49 +08:00

3.7 KiB

Raw Blame History

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 复制一份部署环境文件，至少设置：

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：

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 健康，再启动或重建业务服务：

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。

验证

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 对象，并在恢复演练后再进行版本升级。

3.7 KiB Raw Blame History Unescape Escape