高校文献检索系统

📘 高校文献检索系统 - 第一阶段部署运维日记

gitee地址：https://gitee.com/ma-xinhui/university-literature-system

📅 项目概况

• 项目名称: 高校文献检索系统 (Spring Boot + Vue + MySQL)
• 部署环境: Ubuntu 22.04 VM, Docker容器化部署
• 运维人员: 系统运维转行学习者
• 时间范围: 2026年2月2日
• 总耗时: 约3小时

前端界面

后端界面

📝 操作日记

阶段一：环境准备与基础部署 (耗时: 45分钟)

2026-02-02 11:00 - 11:15 | 环境初始化

# 1. 系统更新与Docker安装
sudo apt update && sudo apt upgrade -y
sudo apt install docker.io docker-compose -y
sudo systemctl start docker && sudo systemctl enable docker

# 2. 创建项目目录结构
mkdir -p ~/projects/university-literature/{backend,frontend}
cd ~/projects/university-literature

操作结果: ✅ 基础环境准备完成

2026-02-02 11:15 - 11:30 | Docker网络问题解决

# 遇到问题: docker-compose命令找不到
# 解决方案: 重新安装docker-compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version  # 验证: v2.24.6

关键学习: Docker Compose独立安装与系统包管理器版本的区别

2026-02-02 11:30 - 11:45 | 镜像源配置

# 遇到问题: Docker Hub连接超时/403错误
# 解决方案: 配置国内镜像加速器
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://registry.cn-hangzhou.aliyuncs.com"
  ]
}
EOF
sudo systemctl restart docker

问题根源 : 国内网络环境对Docker Hub的访问限制
解决方案: 使用中科大和阿里云镜像源

阶段二：服务部署与配置 (耗时: 60分钟)

2026-02-02 11:45 - 12:15 | Spring Boot后端部署

# 1. 创建Dockerfile (多阶段构建)
cat > backend/Dockerfile << 'EOF'
FROM maven:3.8.6-openjdk-11 AS builder
WORKDIR /build
COPY pom.xml .
RUN mvn dependency:go-offline -B
COPY src ./src
RUN mvn clean package -DskipTests

FROM openjdk:11-jre-alpine
WORKDIR /app
COPY --from=builder /build/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
EOF

# 2. 遇到问题: openjdk:11-jre-alpine镜像拉取失败
# 解决方案: 使用华为云镜像
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/openjdk:11
docker tag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/openjdk:11 openjdk:11

技术决策: 采用多阶段构建减小镜像体积，使用国内镜像源解决网络问题

2026-02-02 12:15 - 12:30 | MySQL与Nginx配置

# docker-compose.yml核心配置
version: '3'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: literature_db
      MYSQL_USER: appuser
      MYSQL_PASSWORD: userpassword
    ports: ["3306:3306"]
    volumes: [mysql_data:/var/lib/mysql]
  
  backend:
    build: ./backend
    ports: ["8080:8080"]
    depends_on: [mysql]
  
  frontend:
    build: ./frontend
    ports: ["80:80"]
    depends_on: [backend]

2026-02-02 12:30 - 12:45 | 首次启动尝试

docker-compose up -d --build
# 结果: 后端构建失败，MySQL连接错误

阶段三：问题排查与解决 (耗时: 75分钟)

Bug #1: Maven依赖下载缓慢

现象:

Downloading from central: https://repo.maven.apache.org/maven2/...
速度极慢，构建超时

解决方案:

# 1. 创建Maven阿里云镜像配置
cat > ~/.m2/settings.xml << 'EOF'
<settings>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>*</mirrorOf>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>
EOF

# 2. 修改Dockerfile集成镜像配置
RUN mkdir -p /root/.m2 && \
    cat > /root/.m2/settings.xml << 'SETTINGS_EOF'
    [阿里云配置]
SETTINGS_EOF

效果: 下载速度从10kB/s提升到500kB/s+

Bug #2: MySQL 8.0连接失败

错误信息:

Caused by: com.mysql.cj.exceptions.UnableToConnectException: 
Public Key Retrieval is not allowed

根因分析: MySQL 8.0默认使用caching_sha2_password认证，需要显式允许公钥检索

解决方案:

# 在连接URL中添加参数
spring.datasource.url=jdbc:mysql://mysql:3306/literature_db?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC

验证命令:

# 测试数据库连接
docker-compose exec mysql mysql -uappuser -puserpassword literature_db -e "SELECT 1;"

Bug #3: 端口映射与网络问题

现象: 容器内部服务正常，但外部无法访问

排查过程:

1. 检查容器状态: docker-compose ps ✅ 全部Up
2. 检查端口映射: docker port literature-backend ✅ 8080:8080
3. 容器内部测试: docker-compose exec backend curl localhost:8080/health ✅ OK
4. 宿主机测试: curl localhost:8080/health ❌ 连接拒绝

解决方案:

# 发现防火墙规则问题
sudo iptables -L -n | grep DOCKER
# 重启Docker服务重建网络规则
sudo systemctl restart docker
docker-compose up -d

Bug #4: Nginx代理配置错误

现象: 前端能访问，但API调用返回404

错误配置:

# 原配置 - 错误的代理路径
location /health {
    proxy_pass http://backend:8080/health;  # 实际路径是/api/health
}

正确配置:

location /health {
    proxy_pass http://backend:8080/api/health;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

阶段四：最终验证与优化 (耗时: 30分钟)

2026-02-02 13:15 - 13:30 | 完整系统测试

# 测试脚本
test_endpoints() {
    echo "=== 系统健康检查 ==="
    echo "1. 后端直接访问: $(curl -s http://localhost:8080/api/health)"
    echo "2. 前端页面访问: HTTP $(curl -s -o /dev/null -w '%{http_code}' http://localhost/)"
    echo "3. Nginx代理访问: $(curl -s http://localhost/health)"
    echo "4. 数据库连接: $(docker-compose exec mysql mysql -uappuser -puserpassword -e 'SELECT 1' literature_db 2>/dev/null && echo '✓' || echo '✗')"
}

测试结果:

=== 系统健康检查 ===
1. 后端直接访问: OK
2. 前端页面访问: HTTP 200
3. Nginx代理访问: OK
4. 数据库连接: ✓

2026-02-02 13:30 - 13:45 | 性能优化与监控

# 1. 优化Docker构建缓存
docker builder prune -f

# 2. 创建监控脚本
cat > monitor.sh << 'EOF'
#!/bin/bash
while true; do
    clear
    echo "📊 实时监控 $(date '+%H:%M:%S')"
    echo "容器状态:"
    docker-compose ps
    echo -e "\n资源使用:"
    docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}" | head -4
    sleep 5
done
EOF

🐛 Bug处理总结表

Bug编号	问题描述	根本原因	解决方案	学习要点
001	Docker Compose命令找不到	未正确安装/路径问题	重新下载并配置PATH	Linux环境变量管理
002	Docker镜像拉取失败	国内网络限制	配置镜像加速器	国内开发生态适应
003	MySQL 8.0连接拒绝	Public Key Retrieval限制	连接参数添加allowPublicKeyRetrieval=true	MySQL 8.0安全特性
004	端口无法访问	防火墙/Docker网络规则	重启Docker服务	容器网络原理
005	Nginx代理404	后端上下文路径变化	更新代理路径为/api/health	反向代理配置细节
006	Maven下载缓慢	中央仓库网络慢	配置阿里云镜像	构建优化技巧

📊 技术指标统计

容器资源使用

容器名称            CPU%    内存使用
literature-mysql    0.15%   350MB
literature-backend  1.2%    450MB  
literature-frontend 0.05%   25MB

服务响应时间

• 后端API: 12ms (健康检查)
• 前端页面: 45ms (首次加载)
• 数据库查询: 8ms (简单查询)

部署规模

• 容器数量: 3个
• 镜像大小: 总计约850MB
• 配置文件: 6个 (Dockerfile, docker-compose.yml等)
• 代码行数: 约200行配置 + 150行应用代码

🎯 第一阶段成果

已实现功能

1. ✅ 容器化部署: 三服务完整架构运行
2. ✅ 服务编排: Docker Compose多容器管理
3. ✅ 网络配置: 容器间通信 + 外部访问
4. ✅ 数据库集成: MySQL 8.0 + Spring Data JPA
5. ✅ 反向代理: Nginx静态服务 + API代理
6. ✅ 健康监控: 端点健康检查机制

运维技能实践

1. 故障排查: 网络、配置、依赖问题排查全流程
2. 性能优化: 镜像构建、网络连接、资源监控
3. 自动化脚本: 测试、监控、部署脚本编写
4. 配置管理: 环境变量、配置文件版本控制

架构图

用户浏览器
    ↓
[前端:80] Nginx (静态文件 + 反向代理)
    ↓          ↙
[后端:8080] Spring Boot (REST API)
    ↓
[数据库:3306] MySQL 8.0 (数据存储)

📈 经验教训

成功经验

1. 分层排查: 从容器状态 → 网络 → 应用 → 数据库逐层排查
2. 配置文档化: 所有修改记录在脚本中，便于重现
3. 测试驱动: 每个修复后立即验证，确保问题真正解决
4. 备份意识: 关键配置修改前备份原文件

改进方向

1. 环境准备: 提前准备国内镜像源配置
2. 版本管理: 明确记录各组件版本兼容性
3. 监控先行: 部署初期就建立基础监控
4. 文档同步: 操作记录实时更新

🔄 下一步计划

第二阶段目标

1. CI/CD流水线: GitHub Actions自动化构建部署
2. 监控告警: Prometheus + Grafana监控体系
3. 日志收集: ELK Stack集中日志管理
4. 安全加固: 防火墙、SSL证书、访问控制

立即行动项

1. 备份当前成功配置到Git仓库
2. 编写部署文档供团队使用
3. 设置定时健康检查任务
4. 规划生产环境迁移方案

---

日记结束时间 : 2026年2月2日 14:00 CST
总操作次数 : 87条命令
问题解决率 : 100% (6/6 bugs fixed)
系统状态: ✅ 全部服务正常运行

"运维的本质不是避免问题，而是快速定位和解决问题。每一个bug都是学习的机会。"