部署与运维
部署与运维
整套系统由一份 docker-compose.yml 拉起:15 个基础设施 service(13 个常驻 + 2 个一次性初始化)和 3 个业务容器。业务服务的镜像由同一个 Dockerfile 按模块参数构建,全部在本机构建,没有推送镜像仓库。
1. 18 个 service 与端口
| 服务 | 容器名 | 宿主机端口 → 容器端口 | 常驻 |
|---|---|---|---|
| MySQL 主 | cloud-disk-mysql | 33306 → 3306 | 是 |
| MySQL 从 | cloud-disk-mysql-slave | 33307 → 3306 | 是 |
| 主从初始化 | cloud-disk-mysql-repl-init | 无 | 否,跑完退出 |
| Redis ×6 | cloud-disk-redis-7000 … -7005 | 37000–37005 → 6379 | 是 |
| Redis Cluster 初始化 | cloud-disk-redis-cluster-init | 无 | 否,跑完退出 |
| RabbitMQ | cloud-disk-rabbitmq | 35672 → 5672,45672 → 15672 | 是 |
| MinIO | cloud-disk-minio | 39000 → 9000,39001 → 9001 | 是 |
| Nacos | cloud-disk-nacos | 38848 → 8848,39848 → 9848 | 是 |
| Sentinel Dashboard | cloud-disk-sentinel | 38858 → 8858 | 是 |
| XXL-Job Admin | cloud-disk-xxl-job | 39080 → 39080 | 是 |
| Gateway | cloud-disk-gateway | 38080 → 38080 | 是 |
| object-storage | cloud-disk-object-storage | 38081 → 38081 | 是 |
| object-metadata | cloud-disk-object-metadata | 38082 → 38082 | 是 |
16 个常驻、2 个一次性。多数对外端口在默认值基础上偏移 30000,避免和本机已有服务冲突;Redis 从 37000 起编号,XXL-Job 用 39080。
2. 启动依赖链

depends_on 用的是 condition 形式,不是简单的“先启动”:
mysql (healthy) ──→ mysql-replication-init (exit 0) ──→ gateway / object-storage / object-metadata
└─→ xxl-job
nacos (healthy) ───────────────────────────────────→ gateway / object-storage / object-metadata
redis-7000..7005 (healthy) → redis-cluster-init (exit 0) → gateway / object-storage / object-metadata三个业务服务都同时等 Nacos healthy + Redis 初始化成功 + MySQL 主从初始化成功。Gateway 其实不连 MySQL,但它也挂着 mysql-replication-init 的条件;复制初始化失败时,Gateway 同样不会启动。这是同一份依赖模板带来的耦合,排查“网关起不来”时要先看复制容器。
xxl-job 只等 MySQL healthy。它启动后连 cloud_disk 库,表结构由 sql/init.sql 一起建好。
3. 编译与镜像
echo "JAVA_HOME=/path/to/jdk-21" > .env
make config # 探测本机 IP,写 MINIO_PUBLIC_ENDPOINT
make package-fast # mvn clean package -DskipTests
docker compose up -dMakefile 每个目标都会 source .env,所以 JAVA_HOME 不被当前 shell 认识也能编译。make config 只在 .env 里还没有 MINIO_PUBLIC_ENDPOINT 时写入,已有值不会覆盖。
Dockerfile 只有一个,靠构建参数区分模块:
ARG MODULE
ARG JVM_OPTS="-Xms128m -Xmx256m"
COPY ${MODULE}/target/*.jar app.jar
USER clouddisk
ENTRYPOINT exec java ${JVM_OPTS} --enable-preview -jar app.jar基础镜像是 eclipse-temurin:21-jre-alpine,运行用户是非 root 的 clouddisk。EXPOSE 8080 与实际端口无关,业务端口来自各自的 application.yml。
改了 common/ 之后三个业务模块都要重新打包;只改了某个模块时可以用 mvn package -pl common,gateway 这类组合缩短时间。Docker Hub 不可达时,CLAUDE.md 的替代方案是 docker cp 把 JAR 拷进已有容器,再 --force-recreate。
4. 内存预算
| 服务 | mem_limit | JVM / 运行时 |
|---|---|---|
| MySQL 主 | 512M | — |
| MySQL 从 | 512M | — |
| Redis ×6 | 192M 各 | — |
| RabbitMQ | 320M | — |
| MinIO | 320M | — |
| Nacos | 448M | -Xms128m -Xmx192m -Xmn64m |
| Sentinel | 256M | -Xms64m -Xmx128m |
| XXL-Job | 320M | -Xms128m -Xmx192m |
| Gateway | 768M | -Xms256m -Xmx384m,Netty worker 16、select 8 |
| object-storage | 512M | -Xms128m -Xmx256m |
| object-metadata | 512M | -Xms128m -Xmx256m |
| 合计 | 约 5.6 GB | 宿主机推荐 16 GB |
容器限制加起来约 5.6 GB,加上 Docker、页缓存与日志,8 GB 机器会在压测时吃紧;CLAUDE.md 与部署文档都推荐 16 GB。启动到全部就绪大约 2–3 分钟。
5. 配置从哪来
配置分三层,改之前先确认改的是哪一层:
| 层 | 位置 | 内容 |
|---|---|---|
| compose 环境变量 | docker-compose.yml 的 environment | 主机名、端口、密码、JWT 密钥、XXL-Job 地址、JVM 参数 |
| Nacos 配置中心 | dataId gateway.yaml、sentinel-rules.json | 网关路由覆盖、Sentinel 网关规则 |
| 代码内默认值 | 各模块 application.yml、ShardingSphereConfig、MinioConfig | 本地开发默认值、数据源、双 MinIO 客户端 |
网关是唯一声明了 spring.config.import: nacos:gateway.yaml 的服务,且开了 import-check.enabled: false;Nacos 上没有这份配置时不会阻止启动。两个业务服务只从 Nacos 做服务发现,不拉配置。
几个不要按 YAML 找的地方:
- 数据源不在 YAML 里。
ShardingSphereConfig用 Java 建HikariDataSource,再交给ShardingSphereDataSourceFactory;application.yml里只有mybatis-plus与分页配置。 - Redisson 不是 starter 自动配置。 三个服务都排除了
RedissonAutoConfigurationV2,由common里的RedissonClusterConfig建 Cluster 客户端。 - MinIO 凭据写死在
object-storage/application.yml(minioadmin/minioadmin),改 MinIO 密码要同步改这里并重新打包。 - JWT 密钥默认值是 49 字符的字符串,生产要换成环境变量
JWT_SECRET;长度不足 32 字节启动失败。
SPRING_AUTOCONFIGURE_EXCLUDE 在 compose 里给两个业务服务排除了 DataSourceAutoConfiguration 与 Redisson 自动配置,原因是它们各自提供了 @Primary DataSource 与 RedissonClient。
6. 主从复制与 Redis Cluster 初始化
MySQL 主从由 scripts/init-replication.sh 完成,脚本是幂等的:
- 等两台 MySQL 可 ping;
SHOW SLAVE STATUS里 IO/SQL 都是 Yes 就退出 0;- 主库建
repl用户(mysql_native_password),授权复制; - 读主库
SHOW MASTER STATUS的 file/position; - 从库
CHANGE MASTER TO ... MASTER_HOST='mysql'并START SLAVE; - 最多 5 次、每次隔 3 秒检查状态,仍失败则打印常见原因并退出 1。
主库 my-master.cnf 开了 ROW 格式 binlog,只记录 cloud_disk、cloud_disk_0、cloud_disk_1 三个库。从库 read_only = 1,server-id 分别是 1 和 2。
Redis Cluster 由 scripts/init-redis-cluster.sh 创建:等 6 个节点 ping 通,redis-cli --cluster create ... --cluster-replicas 1,三主三从。redis-cluster.conf 只开了 cluster-enabled、appendonly、protected-mode no,没有配 cluster-announce-ip,所以节点地址就是容器在 bridge 网络里的 IP,写进持久化的 nodes.conf。
这直接决定了 docker compose down 之后的处理:新网络可能换子网,旧 IP 失效,集群起不来。必须删掉 6 个 Redis 数据卷再 up。docker compose stop/start 保留网络,不会有这个问题,是日常停启的推荐方式。
docker volume rm cloud-disk_redis_7000_data ... cloud-disk_redis_7005_data7. 健康检查与验收
基础设施有 healthcheck,业务服务没有。docker compose ps 里业务服务只显示 Up,不会显示 (healthy)。
| 检查对象 | 命令/地址 | 期望 |
|---|---|---|
| 全部容器 | docker compose ps | 基础设施 healthy,初始化容器 Exit 0 |
| 网关与登录 | POST http://localhost:38080/login | 200,返回 token |
| 服务注册 | http://localhost:38848/nacos | 三个服务 UP |
| MinIO | http://localhost:39001 | minioadmin / minioadmin |
| RabbitMQ | http://localhost:45672 | admin / admin123 |
| Sentinel | http://localhost:38858 | sentinel / sentinel |
| XXL-Job | http://localhost:39080/xxl-job-admin | admin / 123456 |
| Admin UI | http://localhost:5173 | admin / 123456 |
object-storage 与 object-metadata 没有引入 Actuator,/actuator/health 不存在。旧文档写的健康端点与网关的 /actuator 放行目前都是空转;要加健康检查,先加依赖,再给 compose 配 healthcheck。
登录验证:
curl -s -w "\nHTTP:%{http_code}" -X POST http://localhost:38080/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"123456"}'8. 常见故障
| 现象 | 先查什么 | 常见原因 |
|---|---|---|
| 业务服务不启动 | docker compose ps 里两个 init 容器 | Redis cluster init 或 MySQL 复制 init 退出非 0 |
| 创建/登录成功但列表为空、HEAD 404 | 从库 SHOW SLAVE STATUS | 复制未配置或已断开,读走从库拿到旧数据 |
| Gateway 503 | Nacos 服务列表 | 后端没注册,或 Gateway 拿到的是容器内部地址 |
| 预签名下载 403/404 | MINIO_PUBLIC_ENDPOINT | 宿主机 IP 变了,或客户端访问不到该地址 |
docker compose down 后 Redis 起不来 | 6 个 Redis 卷 | 子网变化,nodes.conf 里旧 IP 失效 |
| 上传大文件超时 | 网关 response-timeout、后端堆 | 分片太大或直接传大对象 |
| OSS Bucket 请求 500 | storage.oss.access-key-* | 凭据为空,客户端未初始化 |
| 端口占用 | ss -lntp | 残留的 JMeter/Java 进程或旧容器 |
日志用 docker compose logs -f <service> 看,级别在各自 application.yml 的 logging.level.com.clouddisk,默认 DEBUG。
9. 双机部署
dual/ 把业务服务拆到第二台机器,基础设施与 Gateway 留在 Machine A:
Machine A: MySQL 主从、Redis Cluster、RabbitMQ、MinIO、Nacos、Sentinel、XXL-Job、Gateway
Machine B: object-storage:38081、object-metadata:38082(host 网络)Machine B 的服务以 network_mode: host 启动,向 Machine A 的 Nacos 注册自己的局域网 IP;Gateway 通过 lb:// 路由回来。dual/.env.dual 里的 MACHINE_A_IP 要改成实际地址,Machine A 要放行 38848/39848、33306/33307、37000–37005、35672、39000。
回退到单机:先 docker compose -f dual/docker-compose.b.yml down,再回项目根目录 docker compose up -d。