跳到主要内容

运维操作手册

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本手册面向运维工程师，系统性梳理日常运维操作流程与最佳实践，覆盖服务启停、配置更新、热部署、滚动升级、灰度发布、自动化流水线、日志管理、故障排查、备份恢复与运维工具使用。内容基于仓库内的 Nginx Lua 灰度配置、Jenkins Pipeline 脚本、监控与日志文档、备份脚本等实际文件整理而成，确保可落地、可复用。

项目结构​

围绕运维相关的关键位置如下：

  • 灰度发布：Nginx 配置与 Lua 脚本位于 deploy/nginx/release/grayscale
  • 自动化流水线：Jenkins 脚本位于 deploy/jenkins/{prod,test}
  • 监控与日志：docs/infra 下的监控与 API 日志文档
  • 备份策略：script/backup 下的数据库备份脚本
  • 运维命令示例：log/readme.md 提供日志查看示例
  • 数据源配置：datasource.yaml 提供数据库与 Druid 监控配置

Mermaid Diagram Code:

graph TB
subgraph "灰度发布"
NGINX["Nginx 配置<br/>nginx.conf"]
LUA["Lua 灰度脚本<br/>access_by_lua_block.lua"]
LOGMOD["日志模块<br/>logger.lua"]
end
subgraph "CI/CD 流水线"
JENKINS_PROD["Jenkins 生产脚本<br/>build.Jenkinsfile.sh / deploy.Jenkinsfile.sh / web-build-deploy.Jenkinsfile.sh"]
JENKINS_TEST["Jenkins 测试脚本<br/>build.Jenkinsfile.sh / deploy.Jenkinsfile.sh"]
end
subgraph "监控与日志"
MONITOR["监控文档<br/>docs/infra/monitor.md"]
APILog["API 日志文档<br/>docs/infra/api-log.md"]
LOGREAD["日志命令示例<br/>log/readme.md"]
end
subgraph "备份与配置"
BACKUP["备份脚本<br/>script/backup/test.sh"]
DATASOURCE["数据源配置<br/>datasource.yaml"]
end
NGINX --> LUA --> LOGMOD
JENKINS_PROD --> NGINX
JENKINS_TEST --> NGINX
MONITOR --> NGINX
APILog --> NGINX
LOGREAD --> NGINX
BACKUP --> DATASOURCE

图表来源

章节来源

核心组件​

  • 灰度发布（Nginx + Lua）：通过 MAC 地址哈希决定流量归属 v1/v2 后端，支持日志记录与回滚。
  • Jenkins 自动化流水线：分别提供构建与部署脚本，支持多模块、多服务器批量部署。
  • 监控与日志：提供 Redis、MySQL（Druid）、API 日志查询与错误日志处理入口。
  • 备份与配置：提供数据库备份清单与数据源配置示例。
  • 运维命令：提供日志查看与清空示例。

章节来源

架构总览​

下图展示灰度发布在 Nginx 层的流量分配与日志记录，以及 Jenkins 流水线如何驱动镜像构建与容器部署。

Mermaid Diagram Code:

graph TB
Client["客户端"] --> Nginx["Nginx 灰度入口<br/>listen 12345"]
Nginx --> |根据 api_version| UpV1["上游 v1<br/>backend_server_v1"]
Nginx --> |根据 api_version| UpV2["上游 v2<br/>backend_server_v2"]
subgraph "Nginx Lua 灰度"
Access["access_by_lua_block.lua<br/>MAC 哈希分流"]
Logger["logger.lua<br/>灰度日志"]
end
Nginx --> Access
Access --> Logger
subgraph "CI/CD"
Build["Jenkins 构建脚本<br/>build.Jenkinsfile.sh"]
Deploy["Jenkins 部署脚本<br/>deploy.Jenkinsfile.sh / web-build-deploy.Jenkinsfile.sh"]
end
Build --> |推送镜像| Registry["镜像仓库"]
Deploy --> |拉取镜像并运行| Container["容器实例"]

图表来源

详细组件分析​

灰度发布机制​

  • 流量分配策略
    • 通过 MAC 地址哈希取模决定 api_version=v1 或 v2。
    • 若无法提取 MAC，则默认走 v1。
  • Nginx 配置
    • 定义 backend_server_v1 与 backend_server_v2 上游。
    • 通过 proxy_pass 将请求转发至对应后端。
  • 日志记录
    • logger.lua 提供统一写日志能力，便于审计灰度命中与回退。

Mermaid Diagram Code:

flowchart TD
Start(["请求到达"]) --> GetMAC["提取 MACURL/JSON 请求体"]
GetMAC --> HasMAC{"MAC 是否有效？"}
HasMAC --> |否| SetV1["设置 api_version=v1"]
HasMAC --> |是| Hash["MD5(MAC) 取前8位转十进制"]
Hash --> Mod["num % 3"]
Mod --> Is2{"是否等于 2？"}
Is2 --> |是| SetV2["设置 api_version=v2"]
Is2 --> |否| SetV1
SetV1 --> Proxy["proxy_pass 到 backend_server_v1"]
SetV2 --> Proxy2["proxy_pass 到 backend_server_v2"]
Proxy --> Log["logger.lua 写入灰度日志"]
Proxy2 --> Log
Log --> End(["结束"])

图表来源

章节来源

自动化部署流水线（Jenkins）​

  • 构建阶段
    • 支持框架组件、模块 API、模块 Biz 的选择性构建与 Docker 镜像构建、打标签、推送与清理。
    • 生产与测试脚本差异主要体现在镜像前缀、Dockerfile 名称与日志挂载路径。
  • 部署阶段
    • 通过 SSH 登录目标服务器，停止/删除旧容器、拉取新镜像、按模块端口映射运行容器。
    • 支持多模块、多服务器批量部署；支持 Web 服务的独立构建与部署脚本。
  • 关键参数
    • MODULES/SERVERS、JAVA_OPTS、DOCKER_PARAM、SPRING_PORT、XXL_JOB_PORT 等通过 JSON 变量传入并解析为关联数组。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "开发者"
participant Jenkins as "Jenkins"
participant Build as "构建脚本"
participant Registry as "镜像仓库"
participant Deploy as "部署脚本"
participant Host as "目标主机"
Dev->>Jenkins : 触发流水线
Jenkins->>Build : 执行构建模块/框架/网关
Build->>Registry : 构建并推送镜像
Jenkins->>Deploy : 传递 MODULES/SERVERS 等参数
Deploy->>Host : SSH 登录并停止/删除旧容器
Deploy->>Host : 拉取最新镜像并运行
Host-->>Jenkins : 返回部署结果
Jenkins-->>Dev : 发布完成

图表来源

章节来源

日志管理最佳实践​

  • 日志级别与轮转
    • 容器启动参数中包含日志轮转配置（最大大小与保留文件数），确保磁盘空间可控。
  • 日志查询与分析
    • API 日志提供访问日志与错误日志入口，支持按用户、应用、时间、结果码等条件检索。
    • 监控中心提供 Redis 与 MySQL（Druid）监控入口，辅助定位性能瓶颈。
  • 运维命令示例
    • 提供 tail 与清空日志的示例命令，便于快速定位问题。

Mermaid Diagram Code:

flowchart TD
A["收集日志"] --> B["容器日志轮转配置"]
B --> C["API 日志查询访问/错误"]
C --> D["监控面板Redis/MySQL"]
D --> E["定位问题根因"]
E --> F["修复与回滚"]

图表来源

章节来源

备份恢复策略​

  • 备份范围
    • 包含仅结构或带数据的数据库清单，按日期生成 SQL 文件。
  • 备份执行
    • 本地目录准备与 mysqldump 导出，便于离线归档与恢复验证。
  • 恢复建议
    • 结合业务窗口进行恢复演练，优先验证关键表结构与数据完整性。

Mermaid Diagram Code:

flowchart TD
Start(["开始备份"]) --> Prep["准备本地备份目录"]
Prep --> DumpMeta["导出仅结构数据库"]
Prep --> DumpData["导出带数据数据库"]
DumpMeta --> Tar["打包压缩"]
DumpData --> Tar
Tar --> Store["归档存储"]
Store --> End(["结束"])

图表来源

章节来源

服务启停与配置更新​

  • 服务启停
    • 通过 Jenkins 部署脚本在目标主机执行停止/删除旧容器、拉取镜像、运行新容器。
  • 配置更新
    • 通过环境变量传参（如 SPRING_PROFILES_ACTIVE、Nacos 配置与发现参数）实现无侵入更新。
    • 数据源配置示例位于 datasource.yaml，可作为参考。

章节来源

热部署与滚动升级​

  • 热部署
    • 通过容器替换实现“热部署”：停止旧容器、拉取新镜像、启动新容器，避免服务中断。
  • 滚动升级
    • 多服务器场景下逐台执行上述流程，结合灰度发布逐步扩大流量比例，降低风险。

章节来源

回滚操作​

  • 回滚路径
    • 停止/删除当前容器，拉取上一版本镜像（latest 或历史标签）并重启。
  • 灰度回滚
    • 将 api_version 固定为 v1，或临时调整哈希策略，使流量回到稳定版本。

章节来源

依赖关系分析​

  • 组件耦合
    • Nginx Lua 脚本依赖 MAC 提取与 MD5 哈希，日志模块负责审计。
    • Jenkins 构建脚本与部署脚本解耦，分别负责镜像生命周期与容器生命周期。
  • 外部依赖
    • 镜像仓库、目标主机、Nacos 注册中心、SkyWalking Agent 等。

Mermaid Diagram Code:

graph LR
Access["access_by_lua_block.lua"] --> Logger["logger.lua"]
NConf["nginx.conf"] --> Access
Build["build.Jenkinsfile.sh"] --> Registry["镜像仓库"]
Deploy["deploy.Jenkinsfile.sh"] --> Host["目标主机"]
Monitor["monitor.md"] --> Ops["运维人员"]
APILog["api-log.md"] --> Ops

图表来源

章节来源

性能考量​

  • Nginx 层
    • 通过固定上游后端与日志审计，减少不必要的转发与解析开销。
  • 容器层
    • 合理设置日志轮转参数，避免日志文件过大影响 IO。
  • 监控层
    • 使用 Redis 与 MySQL（Druid）监控面板，关注慢查询与连接池状态。

章节来源

故障排查指南​

  • 常见问题定位
    • 灰度未命中：检查 MAC 提取逻辑与日志输出。
    • 流量未按预期分配：核对哈希取模与 api_version 设置。
    • 部署失败：检查镜像拉取、端口映射与容器健康状态。
  • 常用诊断命令
    • 日志查看与清空示例命令可直接参考 log/readme.md。
  • 应急响应预案
    • 灰度回滚：将 api_version 固定为 v1。
    • 快速降级：临时关闭灰度入口或切换到稳定后端。

章节来源

结论​

本手册基于仓库现有文件，给出了灰度发布、自动化流水线、日志管理、备份恢复与故障排查的完整运维实践路径。建议在生产环境中结合监控面板与 API 日志进行持续观测，并定期演练回滚与恢复流程，确保系统高可用与可追溯。

附录​

  • 定时任务执行规划（运维参考）
    • 仓库内包含定时任务执行规划表，可用于运维排班与资源评估。

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答