# deploy-loki

**Repository Path**: attacker/deploy-loki

## Basic Information

- **Project Name**: deploy-loki
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-05-08
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Loki 日志系统部署

基于 Grafana Loki 3.3.2 的日志聚合系统，支持三种部署模式。

## 系统架构

### Docker (主机) 架构

```mermaid
graph TB
    subgraph "Host Machine"
        subgraph "Application Containers"
            App1[App Container 1]
            App2[App Container 2]
            App3[App Container 3]
        end
        
        App1 -->|Write Logs| Logs[Application Logs]
        App2 -->|Write Logs| Logs
        App3 -->|Write Logs| Logs
        
        Logs --> Promtail[Promtail Container]
        Promtail -->|Push| Loki[Loki Container]
        
        Loki --> LocalFS[(Local Filesystem)]
        Loki --> S3[(S3 / MinIO)]
    end
    
    Loki --> Grafana[Grafana]
    
    style S3 fill:#ff9900
    style Grafana fill:#f46800
    style LocalFS fill:#90EE90
```

### Kubernetes Serverless 架构

```mermaid
graph TB
    subgraph "Application Pods"
        A1[App Container] --> FB1[Fluent Bit Sidecar]
        A2[App Container] --> FB2[Fluent Bit Sidecar]
    end
    
    FB1 --> LG[Loki Gateway]
    FB2 --> LG
    
    subgraph "Loki Components"
        LG --> Ingester[Ingester]
        Ingester --> WAL[WAL]
        Ingester --> Compactor[Compactor]
    end
    
    subgraph "Storage Backend"
        Compactor --> S3[(S3 Bucket)]
        S3 --> |Query| Querier[Querier]
    end
    
    Querier --> LG
    LG --> Grafana[Grafana]
    
    style S3 fill:#ff9900
    style Grafana fill:#f46800
    style Ingester fill:#00d4aa
```

### Kubernetes  架构

```mermaid
graph TB
    subgraph "EC2 Nodes"
        N1[Node 1] --> P1[Promtail DaemonSet]
        N2[Node 2] --> P2[Promtail DaemonSet]
        N3[Node 3] --> P3[Promtail DaemonSet]
    end
    
    P1 --> Loki[Loki Cluster]
    P2 --> Loki
    P3 --> Loki
    
    Loki --> Storage[(Object Storage)]
    Storage --> Loki
    Loki --> Grafana[Grafana]
    
    style Storage fill:#ff9900
    style Grafana fill:#f46800
```

## 部署方式

| 模式 | 适用场景 | 日志采集器 | 部署工具 |
|------|---------|-----------|----------|
| **Docker** | 本地测试 | Promtail | Docker Compose |
| **Kubernetes** | 有节点集群 | Promtail DaemonSet | Helm Chart |
| **Kubernetes Serverless** | Fargate | Fluent Bit Sidecar | kubectl |

## 技术栈

- **Loki**: `grafana/loki:3.3.2` - 日志聚合后端，使用 S3 持久化存储
- **Grafana**: `docker.io/grafana/grafana:8.5.27` - 日志可视化界面
- **Promtail**: `docker.io/grafana/promtail:3.0.0` - 日志采集器（EC2 模式）
- **Fluent Bit**: `docker.io/fluent/fluent-bit:3.1.1` - 日志采集器（Serverless 模式）

## 存储配置

- **S3 桶**: `loki-bucket-log-202511250829`
- **日志保留期**: 30 天（720h）
- **Schema**: boltdb-shipper + v11
- **Compaction**: 每 5 分钟
- **Region**: ap-northeast-1

### 存储后端方案

Loki 支持多种对象存储后端，选择建议：

| 存储类型 | 适用场景 | 成本 | 性能 | 可靠性 |
|---------|---------|------|------|--------|
| **AWS S3** | 生产环境（默认） | 低 | 高 | 高 |
| **MinIO** | 私有云/混合云 | 低 | 高 | 中 |
| **GCS** | Google Cloud | 低 | 高 | 高 |
| **Azure Blob** | Azure 环境 | 中 | 高 | 高 |
| **Filesystem** | 开发/测试 | 无 | 中 | 低 |

### 切换存储后端

#### 1. 切换到 MinIO

修改 `loki-deployment.yaml` 中的 `storage_config` 部分：

```yaml
storage_config:
  boltdb_shipper:
    active_index_directory: /tmp/loki/boltdb-shipper-active
    cache_location: /tmp/loki/boltdb-shipper-cache
    cache_ttl: 24h
  aws:  # MinIO 使用 S3 兼容协议
    s3: s3://minio.example.com:9000/loki-data
    bucketnames: loki-data
    endpoint: minio.example.com:9000
    access_key_id: ${MINIO_ACCESS_KEY}
    secret_access_key: ${MINIO_SECRET_KEY}
    s3forcepathstyle: true
    insecure: true  # 生产环境设为 false 并使用 HTTPS
```

#### 2. 切换到 GCS

```yaml
storage_config:
  boltdb_shipper:
    active_index_directory: /tmp/loki/boltdb-shipper-active
    cache_location: /tmp/loki/boltdb-shipper-cache
    cache_ttl: 24h
  gcs:
    bucket_name: loki-logs-bucket
    # 使用 Workload Identity 或 Service Account Key
```

同时修改 `schema_config`：

```yaml
schema_config:
  configs:
    - from: 2024-01-01
      store: boltdb-shipper
      object_store: gcs  # 改为 gcs
      schema: v11
      index:
        prefix: loki_index_
        period: 24h
```

#### 3. 切换到 Azure Blob

```yaml
storage_config:
  boltdb_shipper:
    active_index_directory: /tmp/loki/boltdb-shipper-active
    cache_location: /tmp/loki/boltdb-shipper-cache
    cache_ttl: 24h
  azure:
    container_name: loki-logs
    account_name: ${AZURE_STORAGE_ACCOUNT}
    account_key: ${AZURE_STORAGE_KEY}
    # 或使用 connection_string
```

修改 `schema_config`：

```yaml
schema_config:
  configs:
    - from: 2024-01-01
      store: boltdb-shipper
      object_store: azure  # 改为 azure
      schema: v11
```

#### 4. 切换到 Filesystem（仅测试）

```yaml
storage_config:
  boltdb_shipper:
    active_index_directory: /data/loki/boltdb-shipper-active
    cache_location: /data/loki/boltdb-shipper-cache
    cache_ttl: 24h
    shared_store: filesystem
  filesystem:
    directory: /data/loki/chunks
```

修改 `schema_config`：

```yaml
schema_config:
  configs:
    - from: 2024-01-01
      store: boltdb-shipper
      object_store: filesystem  # 改为 filesystem
      schema: v11
```

**注意**：
- Filesystem 模式需要持久化卷，不适用于 Fargate
- 切换存储后端后需要重启 Loki Pod
- 历史数据需要手动迁移

## 快速部署

### 1. Docker 部署（本地测试）

```bash
cd docker/loki && docker-compose up -d
cd ../promtail && docker-compose up -d
```

详见：[docker/README.md](docker/README.md)

### 2. Kubernetes  部署

```bash
cd kubernetes
./deploy.sh
```

详见：[kubernetes/README.md](kubernetes/README.md)

### 3. Kubernetes Serverless 部署

```bash
cd kubernetes-serverless
./deploy.sh
```

详见：[kubernetes-serverless/README.md](kubernetes-serverless/README.md)

### 4. 云主机日志采集

```bash
# 下载安装脚本
wget https://raw.githubusercontent.com/your-repo/deploy-loki/master/client/install.sh

# 执行安装
chmod +x install.sh
sudo ./install.sh --loki-server http://loki:3100
```

详见：[client/README.md](client/README.md)

### 5. 配置日志告警

```bash
# 安装告警脚本
sudo cp alerts/*.py /srv/loki/

# 配置定时任务
crontab -e
```

详见：[alerts/README.md](alerts/README.md)

## IAM 配置（S3 访问）

三种部署方式共享 IAM 配置，需要创建具有 S3 访问权限的 Secret：

```bash
kubectl create secret generic aws-s3-credentials \
  --from-literal=AWS_ACCESS_KEY_ID=<your-key> \
  --from-literal=AWS_SECRET_ACCESS_KEY=<your-secret> \
  -n <namespace>
```

或参考 `kubernetes/iam/` 目录配置 IRSA（仅限 EKS）。

## Grafana 访问

部署完成后，通过以下方式访问 Grafana：

- **Docker**: http://localhost:3000
- **Kubernetes**: 通过 LoadBalancer 或 NodePort Service
- 默认账号：`admin` / `admin`

## 目录结构

```
├── alerts/                      # 日志告警脚本
│   ├── nginx-alert.py           # Nginx/Ingress 监控
│   ├── app-alert.py             # 应用日志监控
│   └── README.md                # 告警配置文档
├── client/                      # 云主机日志采集客户端
│   ├── install.sh               # Promtail 自动安装脚本
│   ├── promtail-config.yaml     # 配置模板
│   └── README.md                # 客户端使用文档
├── docker/                      # Docker 部署
│   ├── loki/
│   └── promtail/
├── kubernetes/                  # Kubernetes  部署
│   ├── loki/                    # Loki Helm Chart
│   ├── promtail/                # Promtail DaemonSet
│   ├── grafana/                 # Grafana Helm Chart
│   └── iam/                     # IAM 策略
└── kubernetes-serverless/       # Kubernetes Serverless 部署
    ├── loki/                    # Loki Deployment
    ├── fluent-bit/              # Fluent Bit Sidecar
    ├── grafana/                 # Grafana Deployment
    └── iam/                     # IAM 策略
```

## 常见问题

### 日志未写入 S3

1. 检查 Loki Pod 日志是否有 S3 访问错误
2. 验证 AWS 凭证是否正确
3. 确认 S3 桶名称和区域配置正确

### Fluent Bit 无法采集日志（Serverless）

1. 确认应用 Pod 有 Fluent Bit Sidecar 容器
2. 检查 Fluent Bit 配置中的日志路径是否正确
3. 验证 Fluent Bit 能连接到 Loki Gateway

### Grafana 无法查询日志

1. 检查 Loki 数据源配置（URL: `http://loki-gateway/`）
2. 验证 Loki 是否有接收到日志数据
3. 确认查询语法正确（LogQL）

## 维护

- **日志清理**: 自动清理超过 30 天的日志（由 Loki Compactor 执行）
- **监控**: 可配合 Prometheus 监控 Loki 指标
- **备份**: S3 数据定期备份（建议启用 S3 版本控制）