cs-note/hzh/Gen2D/14-部署架构.md

---
tags: [deployment, docker-compose, monitoring, prometheus, grafana, devops]
create time: 2026-06-03 11:05
---

# 14. 部署架构

## 概述

Docker Compose 编排 + Prometheus 监控 + Grafana 可视化 + 自动化部署脚本。

## 正文

### 容器拓扑

```mermaid
flowchart TB
    subgraph "Docker Compose"
        subgraph "应用层"
            FE["frontend-v2\nReact SPA\nNginx :80"]
            BE["backend-v2\nGo HTTP Server\n:8080"]
        end

        subgraph "数据层"
            DB["MySQL\n持久化存储"]
            RD["Redis\n缓存 + 限流"]
            RMQ["RabbitMQ\n消息队列"]
        end

        subgraph "监控层"
            PR["Prometheus\n指标采集 :9090"]
            GF["Grafana\n可视化 :3000"]
        end

        subgraph "外部服务"
            AI["LLM API\n(OpenAI 兼容)"]
            IG["Image Gen API\n文生图"]
            QN["七牛云 CDN\n对象存储"]
        end
    end

    FE -->|"HTTP API"| BE
    BE -->|"SQL"| DB
    BE -->|"Redis 协议"| RD
    BE -->|"AMQP"| RMQ
    BE -->|"HTTP"| AI
    BE -->|"HTTP"| IG
    BE -->|"Upload"| QN
    PR -->|"/metrics\n每 10s"| BE
    GF -->|"PromQL"| PR
    FE -->|"CDN URL"| QN

    style FE fill:#61dafb,stroke:#333,color:#000
    style BE fill:#00add8,stroke:#333,color:#fff
    style PR fill:#e6522c,stroke:#333,color:#fff
    style GF fill:#f46800,stroke:#333,color:#fff
```

### 服务组成

| 服务 | 镜像 | 端口 | 职责 |
|------|------|------|------|
| `backend-v2` | 自建 Go 镜像 | `9001:8080` | HTTP API + 管线执行 |
| `frontend-v2` | 自建 Nginx 镜像 | `9000:80` | React SPA 静态资源 |
| `redis` | `redis:7-alpine` | `6379` | 令牌桶限流 + 缓存 |
| `rabbitmq` | `rabbitmq:3-management` | `5672/15672` | 可选消息队列 |
| `prometheus` | `prom/prometheus` | `9090` | 指标采集与告警 |
| `grafana` | `grafana/grafana` | `3000` | 仪表盘可视化 |

---

### 监控栈

#### Prometheus 配置

```yaml
# deploy/prometheus/prometheus.yml
scrape_configs:
  - job_name: "gen2d-backend"
    static_configs:
      - targets: ["backend-v2:8080"]
    metrics_path: "/metrics"
    scrape_interval: 10s
```

Prometheus 每 **10 秒**抓取一次后端的 `/metrics` 端点，采集全部 35+ 指标。

#### Grafana 自动化

```mermaid
flowchart LR
    subgraph "Provisioning"
        DS["datasources/\n自动配置数据源"]
        DB["dashboards/\n自动导入仪表盘"]
    end

    subgraph "Grafana"
        GF["Grafana Server\n:3000"]
    end

    DS -->|"启动时加载"| GF
    DB -->|"启动时加载"| GF
```

Grafana 通过 provisioning 机制自动加载：
- **数据源配置** — 指向 Prometheus 实例
- **仪表盘 JSON** — 预定义的 3 个仪表盘

#### 告警规则

10 条告警规则覆盖全栈关键指标：

| 告警名称 | 条件 | 严重程度 |
|----------|------|----------|
| 后端实例宕机 | `up == 0` 持续 1 分钟 | Critical |
| HTTP 5xx 错误率 | `> 5%` 持续 2 分钟 | Warning |
| 请求延迟过高 | `P99 > 5s` 持续 3 分钟 | Warning |
| 管线任务失败率 | `> 10%` 持续 5 分钟 | Warning |
| 协程池队列满 | `pool_queued_tasks > 90` | Warning |
| 协程池拒绝率 | `> 20%` 持续 2 分钟 | Critical |
| 用户限流触发 | `rate_limit_rejected > 50/min` | Info |
| Redis 连接失败 | `redis_up == 0` | Warning |
| RabbitMQ 连接失败 | `rabbitmq_up == 0` | Warning |
| 磁盘空间不足 | `< 10%` 可用 | Critical |

---

### 部署脚本

```mermaid
flowchart TD
    A["deploy.sh"] --> B["拉取最新代码"]
    B --> C["构建后端镜像\ndocker build"]
    C --> D["构建前端镜像\ndocker build"]
    D --> E["docker compose up -d"]
    E --> F["健康检查\n等待服务就绪"]
    F --> G["部署完成"]

    style A fill:#4caf50,stroke:#333,color:#fff
```

部署脚本 `deploy.sh` 负责：
1. 拉取最新代码
2. 构建 Docker 镜像
3. 使用 Docker Compose 启动所有服务
4. 执行健康检查验证部署

---

### 配置管理

```mermaid
flowchart LR
    subgraph "配置源"
        Y["config.yaml\n文件配置"]
        E[".env\n环境变量"]
        D["默认值\n代码内置"]
    end

    subgraph "加载优先级"
        P["ENV > YAML > Default"]
    end

    subgraph "运行时"
        C["Config Struct\n全局配置对象"]
    end

    D --> P
    Y --> P
    E --> P
    P --> C
```

| 环境 | 配置方式 | 说明 |
|------|----------|------|
| 开发 | `config.yaml` 文件 | 本地开发，配置直观 |
| 测试 | 环境变量覆盖 | CI/CD 管线注入 |
| 生产 | K8s ConfigMap / Secret | 容器编排平台管理 |

---

### 网络与存储

#### Docker 网络

所有服务加入 `gen2d-v2-net` 桥接网络，容器间通过服务名互相访问。

#### 数据卷

| 卷名 | 挂载点 | 用途 |
|------|--------|------|
| `backend-v2-data` | `/data` | 后端持久化数据 |
| MySQL data | 默认 | 数据库持久化 |
| Redis data | 默认 | 缓存持久化 |

## 关联文档

- [[07-可观测性]] — Prometheus 指标与 Grafana 仪表盘详情
- [[15-配置级联机制]] — YAML / ENV / Default 三层配置机制
- [[01-系统总览]] — 部署架构在整体系统中的位置
- [[00-索引]] — 返回文档总览