docs(deployment): 更新Airflow部署指南并完善Makefile

all: down pull init up

all: down pull mkdir fix-permission init up

pull:

	git pull

mkdir:

	mkdir -p ./dags ./volumes/logs ./volumes/plugins ./volumes/config ./volumes/pg_data

	mkdir -p ./dags ./volumes/logs ./volumes/plugins ./volumes/config ./volumes/pg_data ./volumes/es_data

fix-permission:

	sudo chown -R 1000:0 ./volumes/es_data

rmdir:

	rm -rf ./volumes

# Airflow 部署指南

# Airflow 部署指南 (v3.0.5)

本指南描述如何使用官方 Apache Airflow 3.0.5 镜像部署 Airflow 服务器，使用 CeleryExecutor、Redis 和 PostgreSQL。

本指南描述如何使用官方 Apache Airflow 3.0.5 镜像部署 CSST Airflow 集群。当前架构包含了 CeleryExecutor、Redis、PostgreSQL，并深度集成了 **Elasticsearch + Kibana** 作为集中的日志采集与展示平台。

## 前提条件

- 已安装 Docker 和 Docker Compose

- Git

- Make

- Linux 环境（因涉及权限与路径映射）

## 架构升级说明

1. **DAG Factory 模式**: `dags/common/dag_factory.py` 提取了通用的 `DockerOperator` 逻辑，支持数十个流程快速接入。

2. **统一镜像仓库变量**: 引入了 `HARBOR` 环境变量控制镜像前缀，可根据部署环境自动切换仓库。

3. **远程日志收集**: 增加了 Elasticsearch (39200)、Kibana (35601) 和 Filebeat 容器，实现了任务日志的统一索引、可视化和快速检索。

## 部署步骤

# 对于 ZJLAB 环境

make copy-env-zjlab

```

> **提示**: 环境文件中包含了关键变量如 `HARBOR` 仓库地址，可按需修改 `.env` 调整。

### 3. 初始化目录结构

### 3. 初始化目录与权限

```bash

make mkdir

make fix-permission

```

> **注意**: `fix-permission` 会使用 `sudo` 修复 Elasticsearch 数据目录的归属，以防启动时因无权写入数据而失败。

### 4. 初始化 Airflow

### 4. 初始化 Airflow 数据库

```bash

make init

```

### 5. 启动 Airflow 服务

#### 启动主服务（包括 Flower）

```bash

make up-master

```

### 5. 启动所有服务

#### 启动工作节点服务

> **⚠️ 部署强烈建议**：

> 如果您是在单台机器上进行完整的测试或生产部署，**请不要只使用 `make up`**，因为这只会启动调度器而不会启动任何计算节点（任务将永远卡在排队中）。

> 

> **正确的单机启动流程应为：**

> ```bash

> make up-master   # 启动主控组件（附带 Flower 监控）

> make up-worker   # 启动 Celery 工作节点（真正执行任务的引擎）

> ```

```bash

make up-worker

```

#### 命令区别与集群部署指南：

*   **`make up`**：启动核心调度服务（Scheduler、API Server、DAG Processor）以及数据库组件（Postgres、Redis、Elasticsearch、Kibana 等）。**注意：它不会启动实际执行任务的 Celery Worker。**

*   **`make up-master`**：不仅执行 `make up` 的所有内容，还会**额外启动 Flower 服务**（一个用于监控 Celery 队列状态的 Web UI）。

    *   *为什么 Flower 不作为默认启动？* 因为它是可选的可视化组件。Airflow 核心调度并不依赖它。官方出于节省服务器资源和安全端口暴露的考量，将其设置为按需启动（Profile隔离）。

*   **`make up-worker`**：**专门用于启动 Celery Worker 容器**。

    *   *分布式部署场景*：您可以在多台不同的机器上克隆本代码，并**仅运行** `make up-worker` 来横向扩展计算能力（注意需修改 `.env` 中的 `MASTER_IP` 指向主节点）。

#### 在后台启动所有服务

```bash

make up

```

## Makefile 命令

## Makefile 命令速查

| 命令 | 描述 |

|------|------|

| `make all` | 完整部署：停止、拉取、初始化、启动 |

| `make up-master` | 启动 Airflow 主服务和 Flower |

| `make up-worker` | 启动 Airflow 工作节点 |

| `make copy-env-csu` | 复制 CSU 环境文件 |

| `make copy-env-p368` | 复制 P368 环境文件 |

| `make copy-env-zjlab` | 复制 ZJLAB 环境文件 |

| `make init` | 初始化 Airflow |

| `make up` | 在后台启动所有服务 |

| `make all` | **一键完整部署**：停止、拉取、建目录、修权限、初始化、启动 |

| `make mkdir` | 创建所有必需的挂载目录 |

| `make fix-permission` | 修复 `es_data` 目录的属主权限 (UID 1000) |

| `make copy-env-*` | 复制对应的预设环境变量文件 |

| `make init` | 初始化 Airflow 数据库 |

| `make up` | 启动核心调度器与基础设施 (不含 Worker) |

| `make up-master` | 启动核心组件并附带开启 Flower 监控 |

| `make up-worker` | 启动 Celery Worker 以执行具体的 Task |

| `make down` | 停止所有服务 |

| `make migrate` | 运行数据库迁移 |

| `make clean` | 清理服务 |

| `make clean` | 停止服务并清理容器 |

| `make ps` | 列出运行中的服务 |

| `make restart` | 重启服务 |

## 访问 Airflow

- Airflow Web UI: `http://<MASTER_IP>:38080`

- Flower (Celery 监控): `http://<MASTER_IP>:35555`

- PostgreSQL: `localhost:35432`

- Redis: `localhost:36379`

## 配置

部署使用官方 Apache Airflow 3.0.5 镜像，具有以下配置：

## 访问服务与系统

- CeleryExecutor 用于分布式任务执行

- PostgreSQL 作为元数据数据库

- Redis 作为消息代理

- 通过环境变量进行自定义 Airflow 配置

- **Airflow Web UI**: `http://<MASTER_IP>:38080` (账号/密码默认: `airflow`/`airflow`)

- **Kibana (日志中心)**: `http://<MASTER_IP>:35601` (直接在 Discover 页面选择 `airflow-*` 视图检索日志)

- **Elasticsearch API**: `http://<MASTER_IP>:39200`

- **Flower (Celery 监控)**: `http://<MASTER_IP>:35555`

- **PostgreSQL**: `localhost:35432`

- **Redis**: `localhost:36379`

## 环境变量

.env 文件中的关键环境变量：

- `AIRFLOW_IMAGE_NAME`: 官方 Apache Airflow 3.0.5 镜像

- `AIRFLOW_UID`: Airflow 容器的用户 ID

- `MASTER_IP`: 主节点的 IP 地址

- `JWT_SECRET`: JWT 认证的密钥

- `_AIRFLOW_WWW_USER_USERNAME`: Airflow Web UI 用户名

- `_AIRFLOW_WWW_USER_PASSWORD`: Airflow Web UI 密码

## 常见操作

### 更新 Airflow

```bash

make down

# 如需更新环境文件

make up

```

### 运行数据库迁移

```bash

make migrate

```

### 检查服务状态

```bash

make ps

```

## DAG 状态查询示例

### 清理

由于 Airflow 3 升级了鉴权体系（强制 JWT），如果想在外部系统（如自建看板）查询 DAG 运行状态，推荐使用 Docker CLI 获取最稳定可靠的 JSON 状态数据。

可直接运行仓库内提供的演示脚本进行参考：

```bash

make clean

python query_status_demo.py

```

它演示了如何查询 `csst-msc-l1-mbi` 和 `csst-msc-l1-qc0` 的各步骤运行情况。

## 故障排除

- 确保 Docker 正在运行

- 检查端口 38080、35555、35432 和 36379 是否可用

- 验证环境变量是否正确设置

- 确保宿主机端口未被占用：`38080` (Airflow), `39200` (ES), `35601` (Kibana)

- 若 Elasticsearch 启动失败 (Unhealthy)，请查看权限问题，再次执行 `make fix-permission` 并 `docker compose restart elasticsearch`

- 检查容器日志以了解错误：

  ```bash

  docker compose logs

  docker compose logs -f

  ```