ljwx-health/backup_docs_20260104_182653/DOCKER_README.md

LJWX 统一 Docker Compose 部署文档

📋 目录

• 概述
• 系统架构
• 快速开始
• 服务说明
• 管理命令
• 配置说明
• 故障排查

🎯 概述

这是 LJWX 项目的统一 Docker Compose 配置，整合了以下三大部分：

1. 业务应用：ljwx-boot、ljwx-admin、ljwx-bigscreen
2. 基础设施：MySQL、Redis
3. 监控系统：Prometheus、Grafana、Loki、Alertmanager

所有服务通过一个 docker-compose.yml 文件统一管理，简化部署和运维流程。

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────────┐
│                        LJWX 系统架构                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ ljwx-admin   │  │ ljwx-bigscreen│  │  监控面板     │         │
│  │  (前端管理)   │  │   (大屏展示)   │  │  (Grafana)   │         │
│  │  :5173       │  │   :5001       │  │   :3001      │         │
│  └──────┬───────┘  └──────┬────────┘  └──────┬───────┘         │
│         │                 │                   │                  │
│         └─────────────────┼───────────────────┘                  │
│                           │                                      │
│                  ┌────────▼─────────┐                           │
│                  │   ljwx-boot      │                           │
│                  │   (后端API)       │                           │
│                  │    :9998         │                           │
│                  └────────┬─────────┘                           │
│                           │                                      │
│         ┌─────────────────┼─────────────────┐                   │
│         │                 │                 │                   │
│    ┌────▼─────┐    ┌─────▼──────┐    ┌─────▼──────┐           │
│    │  MySQL   │    │   Redis    │    │ Prometheus │           │
│    │  :3306   │    │   :6379    │    │   :9091    │           │
│    └──────────┘    └────────────┘    └────────────┘           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

🚀 快速开始

前置要求

• Docker >= 20.10
• Docker Compose >= 2.0
• 至少 4GB 可用内存
• 至少 20GB 可用磁盘空间

一键启动

# 1. 复制环境变量配置文件
cp .env.example .env

# 2. 根据需要修改 .env 文件中的配置
vim .env

# 3. 启动所有服务
./docker-manager.sh start

# 或者使用原生 docker-compose 命令
docker-compose up -d

分步启动（推荐）

对于首次部署，建议分步启动以便更好地控制启动顺序：

# 1. 先启动基础设施服务
./docker-manager.sh start-infra

# 2. 等待 MySQL 和 Redis 完全启动（约 30 秒）
./docker-manager.sh status

# 3. 启动业务应用服务
./docker-manager.sh start-apps

# 4. （可选）启动监控系统
./docker-manager.sh start-monitor

📦 服务说明

业务应用服务

服务名	容器名	端口	说明
ljwx-boot	ljwx-boot	9998	Spring Boot 后端服务
ljwx-admin	ljwx-admin	5173	Vue3 前端管理界面
ljwx-bigscreen	ljwx-bigscreen	5001	Flask 大屏展示服务

基础设施服务

服务名	容器名	端口	说明
ljwx-mysql	ljwx-mysql	3306	MySQL 8.0 数据库
ljwx-redis	ljwx-redis	6379	Redis 7 缓存服务

监控系统服务

服务名	容器名	端口	说明
ljwx-prometheus	ljwx-prometheus	9091	监控指标收集
ljwx-alertmanager	ljwx-alertmanager	9094	告警管理
ljwx-loki	ljwx-loki	3100	日志聚合
ljwx-promtail	ljwx-promtail	-	日志采集
ljwx-grafana	ljwx-grafana	3001	监控可视化面板
ljwx-node-exporter	ljwx-node-exporter	9101	系统指标导出

🎮 管理命令

使用管理脚本（推荐）

# 查看帮助
./docker-manager.sh help

# 启动服务
./docker-manager.sh start              # 启动所有服务
./docker-manager.sh start-infra        # 仅启动基础设施
./docker-manager.sh start-apps         # 仅启动业务应用
./docker-manager.sh start-monitor      # 仅启动监控系统

# 停止服务
./docker-manager.sh stop               # 停止所有服务
./docker-manager.sh down               # 停止并删除容器（保留数据）

# 查看状态
./docker-manager.sh status             # 查看服务状态
./docker-manager.sh health             # 健康检查
./docker-manager.sh urls               # 显示访问地址

# 查看日志
./docker-manager.sh logs               # 查看所有日志
./docker-manager.sh logs ljwx-boot     # 查看指定服务日志

# 重启服务
./docker-manager.sh restart            # 重启所有服务
./docker-manager.sh restart ljwx-boot  # 重启指定服务

# 完全清理（谨慎操作）
./docker-manager.sh cleanup            # 删除所有容器和数据卷

使用原生 Docker Compose 命令

# 启动服务
docker-compose up -d                   # 启动所有服务
docker-compose up -d ljwx-mysql ljwx-redis  # 启动指定服务

# 停止服务
docker-compose stop                    # 停止所有服务
docker-compose stop ljwx-boot          # 停止指定服务

# 查看状态和日志
docker-compose ps                      # 查看服务状态
docker-compose logs -f ljwx-boot       # 查看指定服务日志

# 重启服务
docker-compose restart                 # 重启所有服务
docker-compose restart ljwx-boot       # 重启指定服务

# 删除服务
docker-compose down                    # 删除所有容器（保留数据）
docker-compose down -v                 # 删除所有容器和数据卷

⚙️ 配置说明

环境变量配置

编辑 .env 文件修改配置：

# MySQL 配置
MYSQL_ROOT_PASSWORD=root123456         # MySQL root 密码
MYSQL_DATABASE=ljwx                    # 数据库名
MYSQL_USER=ljwx                        # 应用数据库用户
MYSQL_PASSWORD=ljwx123456              # 应用数据库密码

# Redis 配置
REDIS_PASSWORD=redis123456             # Redis 密码

# Spring Boot 配置
SPRING_PROFILES_ACTIVE=prod            # Spring 运行环境

# Node.js 配置
NODE_ENV=development                   # Node 运行环境
VITE_USER_NODE_ENV=development         # Vite 运行环境

端口配置

如果默认端口冲突，可以在 docker-compose.yml 中修改端口映射：

ports:
  - "主机端口:容器端口"

例如，修改 ljwx-boot 端口：

ljwx-boot:
  ports:
    - "8080:9998"  # 将主机端口改为 8080

数据持久化

数据卷配置在 docker-compose.yml 的 volumes 部分：

• mysql_data: MySQL 数据目录
• redis_data: Redis 数据目录
• prometheus_data: Prometheus 时序数据
• grafana_data: Grafana 配置和仪表盘
• loki_data: Loki 日志数据
• alertmanager_data: Alertmanager 配置

数据默认存储在 Docker 的卷存储目录中，可以通过以下命令查看：

docker volume ls
docker volume inspect <volume_name>

🌐 服务访问地址

启动成功后，可以通过以下地址访问各个服务：

业务应用

• 后端 API: http://localhost:9998
• 管理界面: http://localhost:5173
• 大屏服务: http://localhost:5001

监控系统

• Grafana: http://localhost:3001 (默认账号: admin / admin123)
• Prometheus: http://localhost:9091
• Alertmanager: http://localhost:9094

基础设施

• MySQL: localhost:3306
• Redis: localhost:6379

🔧 故障排查

常见问题

1. 端口冲突

问题：启动时提示端口已被占用

解决：

# 查看端口占用情况
lsof -i :9998
lsof -i :3306

# 修改 docker-compose.yml 中的端口映射
# 或停止占用端口的服务

2. 容器启动失败

问题：某个容器无法启动

解决：

# 查看容器日志
docker-compose logs ljwx-boot

# 查看详细错误信息
docker logs ljwx-boot

# 重新构建镜像
docker-compose build --no-cache ljwx-boot
docker-compose up -d ljwx-boot

3. 数据库连接失败

问题：应用无法连接到 MySQL

解决：

# 检查 MySQL 是否正常运行
docker-compose ps ljwx-mysql

# 检查 MySQL 健康状态
docker-compose exec ljwx-mysql mysqladmin ping -p

# 查看 MySQL 日志
docker-compose logs ljwx-mysql

# 确认 .env 文件中的数据库密码配置正确

4. 内存不足

问题：服务启动后系统变慢或容器被杀死

解决：

# 查看 Docker 资源使用情况
docker stats

# 调整 Docker Desktop 内存限制（推荐至少 4GB）
# 或者分批启动服务，不要一次性启动所有服务
./docker-manager.sh start-infra
./docker-manager.sh start-apps

5. 磁盘空间不足

问题：磁盘空间不足导致服务异常

解决：

# 清理未使用的 Docker 资源
docker system prune -a

# 查看 Docker 磁盘使用情况
docker system df

# 删除旧的镜像和容器
docker image prune -a
docker container prune

健康检查

# 使用管理脚本进行健康检查
./docker-manager.sh health

# 手动检查各服务健康状态
docker-compose ps

# 检查容器健康状态
docker inspect --format='{{.State.Health.Status}}' ljwx-boot
docker inspect --format='{{.State.Health.Status}}' ljwx-mysql

日志查看

# 查看所有服务日志
./docker-manager.sh logs

# 查看特定服务日志
./docker-manager.sh logs ljwx-boot

# 查看最近的日志
docker-compose logs --tail=100 ljwx-boot

# 实时跟踪日志
docker-compose logs -f ljwx-boot

📊 监控系统使用

Grafana 仪表盘

1. 访问 http://localhost:3001
2. 使用默认账号登录：admin / admin123
3. 导航到 Dashboards 查看预配置的监控面板：
   • 系统资源监控
   • 应用性能监控
   • 告警规则监控

Prometheus 指标查询

1. 访问 http://localhost:9091
2. 在查询框中输入 PromQL 查询语句
3. 常用查询示例：

   # CPU 使用率
   rate(process_cpu_seconds_total[5m])
   
   # 内存使用
   process_resident_memory_bytes
   
   # HTTP 请求数
   http_requests_total
   

告警配置

告警规则配置文件位于：

• ljwx-bigscreen/bigscreen/monitoring/prometheus/alerts.yml
• ljwx-bigscreen/bigscreen/monitoring/alertmanager/alertmanager.yml

修改配置后重启相应服务：

docker-compose restart ljwx-prometheus ljwx-alertmanager

🔐 安全建议

生产环境部署注意事项

1. 修改默认密码

   # 修改 .env 文件中的所有密码
   MYSQL_ROOT_PASSWORD=<strong-password>
   MYSQL_PASSWORD=<strong-password>
   REDIS_PASSWORD=<strong-password>
   

2. 网络隔离

   • 将数据库和 Redis 端口仅暴露给内部网络
   • 使用防火墙限制访问

3. 数据备份

   # MySQL 备份
   docker-compose exec ljwx-mysql mysqldump -u root -p ljwx > backup.sql
   
   # Redis 备份
   docker-compose exec ljwx-redis redis-cli --rdb /data/dump.rdb
   

4. 日志管理

   • 定期清理旧日志
   • 配置日志轮转

5. 更新策略

   • 定期更新镜像到最新稳定版本
   • 测试后再应用到生产环境

📚 相关文档

• CLAUDE.md - 项目整体说明
• ljwx-bigscreen/CLAUDE.md - 大屏服务说明
• ljwx-admin/CLAUDE.md - 管理界面说明
• Monitoring README - 监控系统详细文档

🤝 支持

如有问题，请查看：

1. 本文档的故障排查部分
2. 各服务的日志输出
3. 相关服务的官方文档

---

最后更新: 2025-11-25 版本: 1.0.0