# cloud_sync_victoria_log

**Repository Path**: dicky2008/cloud_sync_victoria_log

## Basic Information

- **Project Name**: cloud_sync_victoria_log
- **Description**: 云端日志同步到本地victoria日志
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-08
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VictoriaLogs + CLS 本地日志归档方案

将腾讯云 CLS（Cloud Log Service）日志批量同步到本地，落盘为 gzip 压缩的 NDJSON 原始文件，再导入 VictoriaLogs 做全文搜索和字段过滤。适用于日志冷热分离、本地长期归档、离线排查等场景。

已接入真实腾讯云 CLS API，支持子窗口并发拉取、断点续传、自动重试、高峰自适应降并发。

## 核心特性

- **子窗口并发拉取**：按 15 分钟切分子窗口，ThreadPoolExecutor 并发拉取（默认非高峰 8 并发）
- **流式落盘**：边拉边写 plain text 临时文件，完成后 gzip 压缩，避免全内存暂存导致 OOM
- **断点续传**：每页保存 checkpoint，中断后从断点继续，不丢已拉数据，不重复拉取
- **自动重试**：子窗口失败后自动重试（默认 2 次），退避等待 5s→10s→15s
- **高峰自适应**：高峰时段（默认 14-17 点）自动降低并发（默认 6），规避 CLS 限流
- **进度可视化**：内置 HTML 进度查看器，实时展示按小时统计的完成度
- **大文件流式导入**：使用 curl.exe 流式上传，支持 >100MB 的 gzip 文件导入 VictoriaLogs

## 适用场景

- 每天批量同步昨天完整日志，CLS 仅保留 2-3 天热数据
- 本地或云服务器磁盘充足，但 CPU/内存相对紧张
- 需要全文搜索、按字段过滤、按服务/级别/trace_id 排查问题
- 希望保留一份原始 `jsonl.gz`，便于后续重建索引或迁移工具

## 目录结构

```text
victorialogs-cls-demo/
  ├── progress.html                      # 同步进度查看器（浏览器打开）
  ├── docker-compose.yml                 # VictoriaLogs 容器部署
  ├── .env.example                       # 环境变量模板
  ├── .env                               # 实际配置（不入库）
  ├── raw/                               # 原始日志归档
  │   ├── sync_state.json                # 同步状态记录
  │   └── 2026-07-31/                    # 按日期分目录
  │       ├── 00-00.jsonl.gz             # 子窗口文件（HH-MM.jsonl.gz）
  │       ├── 00-15.jsonl.gz
  │       ├── .00-00.checkpoint          # 断点续传 checkpoint（拉取完成后删除）
  │       └── 00-00.jsonl.tmp            # 拉取中的临时文件（完成后压缩为 .gz）
  ├── victoria-logs-bin/                 # VictoriaLogs 二进制
  │   └── victoria-logs-windows-amd64-prod.exe
  ├── victorialogs-data/                 # VictoriaLogs 数据目录
  └── scripts/
      ├── sync_cls_yesterday.py          # CLS 同步脚本（核心）
      ├── import_to_victorialogs.ps1     # Windows 导入脚本
      ├── import_to_victorialogs.sh      # Linux/Mac 导入脚本
      ├── query_examples.ps1             # Windows 查询示例
      ├── query_examples.sh              # Linux/Mac 查询示例
      ├── run_demo.ps1                   # Windows 一键 demo（模拟日志）
      ├── run_demo.sh                    # Linux/Mac 一键 demo
      └── generate_mock_logs.py          # 模拟日志生成（仅 demo 用）
```

## 平台支持

| 组件 | Linux/Mac | Windows |
|---|---|---|
| VictoriaLogs | Docker 或二进制 | Docker Desktop 或二进制 |
| `sync_cls_yesterday.py` | 原生支持（需 Python 3.10+） | 原生支持 |
| 导入脚本 | `import_to_victorialogs.sh` | `import_to_victorialogs.ps1` |
| 查询脚本 | `query_examples.sh` | `query_examples.ps1` |
| 进度查看器 | 任意浏览器 | 任意浏览器 |

## 推荐配置

| 资源 | 建议 |
|---|---|
| CPU | 2 核起步，推荐 4 核 |
| 内存 | 8G 起步，推荐 16G |
| 磁盘 | 300G SSD 或更大（10G/天日志约保留 30 天） |
| 系统 | Ubuntu 22.04 / 24.04 或 Windows |
| 部署方式 | Docker Compose 或原生二进制 |
| Python | 3.10+（使用了 `zoneinfo`） |
| 依赖 | `tencentcloud-sdk-python-cls` |

## 快速启动

### 1. 配置环境变量

复制模板并填入腾讯云 CLS 配置：

```bash
cp .env.example .env
```

`.env` 内容：

```bash
TENCENT_SECRET_ID=你的SecretId
TENCENT_SECRET_KEY=你的SecretKey
CLS_REGION=ap-guangzhou
CLS_TOPIC_ID=你的TopicId
```

### 2. 安装依赖

```bash
pip install tencentcloud-sdk-python-cls
```

### 3. 启动 VictoriaLogs

Docker 方式：

```bash
docker compose up -d
curl http://127.0.0.1:9428/health
```

Windows 原生二进制方式：

```powershell
.\victoria-logs-bin\victoria-logs-windows-amd64-prod.exe `
    -retentionPeriod=30d `
    -storageDataPath=victoria-logs-data
```

默认监听 9428 端口。

### 4. 同步 CLS 日志到本地

加载环境变量后运行同步脚本：

```powershell
# Windows PowerShell
Get-Content .env | ForEach-Object {
    if ($_ -match '^\s*([^#\s][^=]*)\s*=\s*(.+)\s*$') {
        Set-Item -Path "Env:$($Matches[1].Trim())" -Value $Matches[2].Trim()
    }
}

# 同步指定日期（默认并发 8，高峰 6）
python scripts/sync_cls_yesterday.py --date 2026-07-31
```

```bash
# Linux/Mac
set -a && source .env && set +a
python3 scripts/sync_cls_yesterday.py --date 2026-07-31
```

同步完成后，日志文件存储在 `raw/2026-07-31/HH-MM.jsonl.gz`。

### 5. 导入 VictoriaLogs

```powershell
# Windows：导入整个日期目录
.\scripts\import_to_victorialogs.ps1 raw\2026-07-31\
```

```bash
# Linux/Mac
./scripts/import_to_victorialogs.sh raw/2026-07-31/
```

### 6. 查询验证

打开 VictoriaLogs Web UI：

```text
http://127.0.0.1:9428
```

常用查询：

```text
*
error
level:error
service:payment-api
trace_id:你的trace_id
error | fields _time, service, level, trace_id, request_id, _msg
```

命令行查询：

```bash
curl http://127.0.0.1:9428/select/logsql/query -d 'query=error' -d 'limit=10'
```

## 同步脚本详解

`scripts/sync_cls_yesterday.py` 是核心同步脚本，支持以下参数：

| 参数 | 默认值 | 说明 |
|---|---|---|
| `--date` | 昨天 | 指定同步日期，如 `2026-07-31` |
| `--hour` | 全天 | 只拉指定小时（0-23） |
| `--workers` | 8 | 非高峰并发数 |
| `--peak-workers` | 6 | 高峰时段并发数 |
| `--peak-hours` | 14,15,16,17 | 高峰小时列表 |
| `--sub-window-minutes` | 15 | 子窗口大小（分钟） |
| `--max-retries` | 2 | 单子窗口失败自动重试次数 |
| `--limit` | 1000 | 单次 API 返回条数（CLS 上限 1000） |
| `--max-rows` | 0 | 单子窗口最大拉取条数，0 不限 |
| `--start` / `--end` | - | 自定义时间窗口（ISO 格式） |
| `--force` | false | 强制重拉已 success 的子窗口 |
| `--dry-run` | false | 只打印计划不执行 |

### 工作原理

1. **子窗口切分**：将一天 24 小时按 15 分钟切分为 96 个子窗口
2. **并发调度**：用 ThreadPoolExecutor 并发拉取，高峰时段自动降并发
3. **流式落盘**：每个子窗口边拉边写 `.jsonl.tmp`（plain text），每页 flush 落盘
4. **断点续传**：每页拉取后保存 checkpoint（count/offset/context/page），中断后从断点继续
5. **分页策略**：先用 Context 翻页（最多 1 万条），超过后切换 Offset 模式
6. **压缩归档**：拉取完成后 gzip 压缩为 `.jsonl.gz`，删除临时文件和 checkpoint
7. **自动重试**：子窗口失败后自动重试，退避等待 5s→10s→15s
8. **状态记录**：所有子窗口状态写入 `raw/sync_state.json`

### 断点续传

同步过程被中断（如磁盘满、手动停止）后，重新运行相同命令会自动从断点继续：

- 有 checkpoint + 有 `.tmp`：从断点页继续追加
- 有 checkpoint + 无 `.tmp`（如磁盘满导致 tmp 丢失）：用 `--force` 强制重拉该窗口
- 无 checkpoint：从头拉取

### 降低带宽占用

默认 8 并发约占 10MB/s 带宽。如需降低对本机网络的影响：

```bash
python scripts/sync_cls_yesterday.py --date 2026-07-31 --workers 4 --peak-workers 4
```

4 并发约占用 5MB/s 带宽，同步时间相应延长。

## 进度查看器

项目内置 `progress.html` 同步进度查看器，提供按小时统计的完成度可视化。

### 方式一：HTTP 实时模式（推荐）

在项目根目录启动本地 HTTP 服务：

```bash
python -m http.server 8080
```

浏览器访问：

```text
http://localhost:8080/progress.html
```

页面自动读取 `raw/sync_state.json` 和目录文件，支持「自动刷新 30s」。

### 方式二：离线拖拽模式

双击打开 `progress.html`，将 `raw/sync_state.json` 拖拽到页面即可查看。

### 页面功能

- 6 个统计卡片：已完成、拉取中、异常(stale)、未开始、总进度、累计日志数
- 总进度条（绿/蓝/橙分段）
- 24 小时网格，每行 4 个子窗口方块，鼠标悬停显示日志数和更新时间
- 四种状态：✓完成(绿) · 拉取中(蓝，有.tmp) · !异常(橙，.tmp丢失) · 未开始(灰)
- 综合判断 `sync_state.json` + 目录 `.tmp`/`.checkpoint` 文件，识别 stale 窗口

## 每日同步设计

推荐生产链路：

```text
CLS 保留 2-3 天
  ↓
每天凌晨 1-3 点拉取昨天 00:00:00 到今天 00:00:00 的日志
  ↓
按 15 分钟子窗口并发拉取，流式落盘 raw/<date>/HH-MM.jsonl.tmp
  ↓
拉取完成后压缩为 raw/<date>/HH-MM.jsonl.gz
  ↓
导入 VictoriaLogs（/insert/jsonline 接口，NDJSON 格式）
  ↓
记录 sync_state.json
  ↓
保留最近 7-30 天热数据
```

不要卡在凌晨 00:00 立即拉取，建议延迟到 01:00 或 02:00，避免昨天最后几分钟日志仍在写入。

## 定时任务

### Linux cron

每天凌晨 2 点同步昨天日志：

```cron
0 2 * * * cd /data/log-archive && set -a && . ./.env && set +a && python3 scripts/sync_cls_yesterday.py >> logs/sync.log 2>&1 && ./scripts/import_to_victorialogs.sh raw/$(date -d yesterday +\%F)/ >> logs/sync.log 2>&1
```

### Windows 任务计划程序

```powershell
$action = New-ScheduledTaskAction -Execute "powershell.exe" `
    -Argument "-File C:\log-archive\scripts\run_daily_sync.ps1"
$trigger = New-ScheduledTaskTrigger -Daily -At 2am
Register-ScheduledTask -TaskName "VictoriaLogs-CLS-Sync" `
    -Action $action -Trigger $trigger
```

建议先手动跑通，再加到定时任务。

## 安全建议

- 不要把真实 `.env` 提交到代码仓库
- VictoriaLogs Web UI 不建议直接暴露到公网
- 如果要公网访问，建议通过 Nginx 加 Basic Auth、IP 白名单或 VPN
- 原始 `raw/*.jsonl.gz` 可能包含敏感信息，需要限制服务器访问权限

## 已知限制与经验

- CLS SearchLog API 的 `Limit` 参数最大为 1000，单线程串行拉取存在速度瓶颈
- 8 并发在业务高峰时段（14:00-17:30）会触发 CLS 限流，建议高峰时段使用 6 并发或更低
- 8 并发同步约占用 10MB/s 带宽，可能影响本机网络使用
- 全内存暂存日志会导致 OOM 风险，已改为流式落盘
- PowerShell 的 HttpClient 在处理大文件（>100MB）上传时会返回 null，导入脚本已改用 `curl.exe` 流式上传
- PowerShell 脚本需使用 UTF-8 编码，中文输出在 PowerShell 5.1 + GBK 环境下可能乱码