Agent 및 파이프라인 플랫폼 활용 가이드

Agent 및 파이프라인 플랫폼 활용 가이드

I. Agent: 서버 정보 등록 및 관리

1. Agent를 위한 서버 정보 획득

Agent 실행 시 필요한 서버 ID는 다음과 같은 방법으로 확인할 수 있습니다.

방법 1: 관리 플랫폼 UI 활용 (가장 간편)

  1. 모니터링 플랫폼의 "서버 모니터링" 메뉴로 이동합니다.
  2. 표의 첫 번째 열에 표시된 "서버 ID"를 복사하여 사용합니다.

방법 2: API 호출을 통한 조회

등록된 서버 목록 및 각 서버의 고유 ID를 조회할 수 있습니다.


curl http://localhost:3001/api/agent/servers

API 응답에는 `id`, `name`, `host` 필드가 포함된 서버 목록이 반환됩니다. 해당 서버의 `id`를 확인합니다.

방법 3: 데이터베이스 직접 조회

SQLite 데이터베이스에서 직접 서버 정보를 조회합니다.


# SQLite 예시
sqlite3 server/data.db "SELECT id, name, host FROM servers;"

2. Agent의 자동 서버 검색 기능

--server 파라미터를 지정하지 않으면, Agent는 시작 시 자동으로 서버를 검색합니다.

  1. Agent는 실행 중인 시스템의 호스트명(hostname) 및 IP 주소를 수집합니다.
  2. 수집된 정보와 데이터베이스에 등록된 모든 서버의 `host` 필드를 비교합니다.
  3. Agent의 호스트명 또는 IP 주소가 서버 등록 정보와 정확히 일치하는 경우 (대소문자 구분 없음), 해당 서버로 자동 연결됩니다.

핵심: 서버 등록 시 `host` 필드에 올바른 IP 주소 또는 호스트명을 입력하면, Agent는 별도의 설정 없이 자동으로 해당 서버를 인식합니다.

자동 검색 매칭 로직

Agent 시스템의 호스트명 또는 IP 주소가 등록된 서버의 `host` 필드와 일치하는 경우 자동 매칭이 성공합니다.


[Agent 시스템]
- 호스트명 (예: MYSERVER-PC)
- IP 주소 (예: 192.168.0.50)
      ↓
      매칭 시도
      ↓
[등록된 서버 정보]
- servers.host 필드 (예: 192.168.0.50 또는 MYSERVER-PC)
      ↓
      일치 시 자동 연결

예시: 서버 등록 시 `host` 필드에 `192.168.0.50`을 입력하고, Agent가 해당 IP 주소에서 실행되면 `--server` 파라미터 없이도 자동 연결됩니다.

--server 파라미터는 수동 지정이 필요할 때 사용합니다. 예를 들어, 한 머신에서 여러 서버 정보를 관리해야 하거나 자동 검색이 실패했을 경우 수동으로 ID를 지정할 수 있습니다.

3. Agent 자동 식별 메커니즘 (3단계)

Agent 실행 시 (server/agent/engine.js), 다음 3단계 과정을 통해 본인에게 해당하는 서버 ID를 자동으로 식별합니다.

우선순위 방식 설명
1 명령줄 파라미터 --server=<ID> 수동 지정, 가장 높은 우선순위
2 로컬 SQLite 데이터베이스 조회 servers 테이블에서 host 필드로 매칭
3 API 자동 검색 GET /api/agent/servers API를 호출하여 전체 서버 목록과 비교

4. 시스템 식별 정보 수집

Agent는 다음 정보를 수집하여 servers.host 필드와 매칭합니다:

  • 호스트명: os.hostname() 결과 및 소문자 변환 값
  • 네트워크 IP: 내부 네트워크를 제외한 모든 IPv4/IPv6 주소
  • Loopback 주소: 127.0.0.1, localhost, ::1

매칭은 대소문자를 구분하지 않는 정확한 일치(exact match) 방식으로 이루어집니다.

5. 서버 정보 등록 방법

Agent가 자동으로 매칭할 서버 정보를 찾지 못하는 경우, 다음 방법으로 서버를 등록해야 합니다:

  • 상호작용 스크립트 실행: python scripts/register_servers.py
  • CSV 파일 일괄 등록: python scripts/register_servers.py --file servers.csv
  • 명령줄 등록: python scripts/register_servers.py --name "WebServer-01" --host 192.168.0.100 --port 22 --os "Ubuntu 20.04" --tags "web,production"
  • CSV 템플릿 활용: scripts/servers_template.csv 파일을 참조하여 작성
  • 관리 플랫폼 UI: "서버 관리" 메뉴에서 직접 추가

주의: 서버 등록 시 `host` 필드에는 Agent가 실행될 시스템의 IP 주소 또는 호스트명을 정확히 기입해야 합니다.

II. Agent 종류 및 사용법

프로젝트에는 다양한 목적을 가진 여러 버전의 Agent가 포함되어 있습니다.

1. Node.js Agent (파이프라인 실행 엔진) - 핵심 컴포넌트

위치: server/agent/engine.js

주요 기능: 지정된 디렉토리 감시 → 파일 변경 감지 → 파이프라인 단계 실행 → 결과 보고

실행 예시


# 로컬 모드 (Agent와 API 서버가 동일 머신에 있을 경우)
node server/agent/engine.js --api=http://localhost:3001/api --token=your-agent-token

# 원격 모드 (Agent가 원격 서버에 배포된 경우)
node server/agent/engine.js --api=http://remote-server-ip:3001/api --token=your-agent-token --server=<서버ID>

주요 파라미터

파라미터 기본값 설명
--api http://localhost:3001/api API 서버 주소
--token your-agent-token Agent 인증 토큰
--poll 5000 (ms) 파이프라인 설정 주기적 조회 간격
--business (없음) 특정 비즈니스에 속하는 파이프라인만 모니터링
--server (없음) 연결할 서버 ID 수동 지정
--deploy-interval 10000 (ms) 배포 파일 다운로드 주기

실행 모드 자동 감지: Agent는 uploads/ 디렉토리가 존재하는지 여부에 따라 실행 모드를 결정합니다. 존재하면 로컬 모드(파일 직접 접근), 존재하지 않으면 원격 모드(HTTP 통신으로 파일 다운로드)로 동작합니다.

2. Python Agent (시스템 지표 수집)

위치: scripts/agent.py

설치: pip install psutil requests


# 지정된 서버 ID와 간격으로 지표 수집
python scripts/agent.py --server-id <SERVER_ID> --interval 60

# 자동 등록 기능 활성화하여 서버 등록 및 지표 수집
python scripts/agent.py --auto-register --name "MyNewServer" --host 192.168.0.75

수집 지표: CPU 사용률, 메모리 사용량, 디스크 I/O, 네트워크 트래픽, 시스템 가동 시간, 상위 5개 프로세스 정보

3. PowerShell Agent (Windows 시스템 지표 수집)

위치: scripts/agent.ps1


powershell -File agent.ps1 -ServerId <SERVER_ID> -ApiBase http://localhost:3001/api -Interval 60

4. Shell Agent (Linux 시스템 지표 수집)

위치: scripts/agent.sh


bash agent.sh <SERVER_ID> [API_BASE] [INTERVAL]

III. 파이프라인 정의 및 관리

1. 파이프라인 생성

방법 1: 생성 스크립트 활용


# 사용 가능한 템플릿 목록 확인
node scripts/create_pipeline.js list-templates

# 특정 템플릿으로 JSON 파일 생성
node scripts/create_pipeline.js template <템플릿명>

# 생성된 JSON 파일을 사용하여 파이프라인 생성 (실제 생성)
node scripts/create_pipeline.js create my-pipeline.json

# 실제 생성 없이 JSON 내용 미리보기
node scripts/create_pipeline.js dry-run my-pipeline.json

방법 2: 관리 플랫폼 UI 사용

"파이프라인 오케스트레이션" 메뉴에서 직접 파이프라인을 생성하고 설정할 수 있습니다.

2. 파이프라인 JSON 구조

파이프라인의 구성은 JSON 형식으로 정의됩니다.


{
  "code": "unique_pipeline_code",
  "name": "파이프라인 이름",
  "description": "파이프라인 설명",
  "trigger_type": "file_watch",
  "trigger_config": {
    "watch_dir": "/path/to/watch",
    "file_pattern": "*.dat",
    "output_dir": "/path/to/output",
    "done_dir": "/path/to/archive"
  },
  "result_config": {
    "enabled": true,
    "collect_dirs": ["{output_dir}"],
    "include_patterns": ["*.log"],
    "exclude_patterns": [".tmp", "*.temp"],
    "max_file_size_mb": 50,
    "recursive": false
  },
  "steps": [
    {
      "name": "Step 1: Data Processing",
      "step_type": "tool_call",
      "step_order": 0,
      "stop_on_fail": true,
      "config": { "tool": "python3", "args": ["process_data.py", "--input", "{input_file}"] }
    },
    {
      "name": "Step 2: Archive Result",
      "step_type": "file_move",
      "step_order": 1,
      "config": { "source": "{output_dir}/*.result", "dest": "/path/to/final_results/" }
    }
  ]
}

3. 지원되는 변수

파이프라인 설정 내에서 사용할 수 있는 동적 변수입니다.

변수 설명
{input_file} Agent가 감지한 입력 파일의 전체 경로
{filename} 입력 파일의 이름 (확장자 포함)
{filename_noext} 입력 파일의 이름 (확장자 제외)
{work_dir} 파이프라인 실행을 위한 임시 작업 디렉토리 (자동 생성)
{watch_dir} 파일 감시 대상 디렉토리
{output_dir} 파이프라인 처리 결과물 출력 디렉토리
{now} 현재 시간 (형식: yyyyMMdd_HHmmss)

4. 지원되는 스텝 타입 (7가지)

타입 설명 주요 설정 항목
file_check 지정된 파일이 나타날 때까지 대기 wait_dir, file_pattern, timeout_seconds
tool_call 명령줄 도구 실행 (백그라운드 실행 지원) tool, args, cwd, timeout_seconds, background
log_check 로그 파일 내용 검사 file_path, match_pattern, match_type
file_move 파일 또는 디렉토리 이동 source, dest
wait 지정된 시간만큼 대기 seconds
condition 조건부 로직 실행 (예: previous.step_status == 'success', file_exists('/tmp/flag'), env('MY_VAR')) expression
result_upload 처리 결과 파일 수집 및 업로드 collect_dirs, include_patterns, exclude_patterns

5. 참고용 파이프라인 예시

파일 경로 설명
scripts/pipelines/simulation-monitor.json 실제 운영 환경에서 사용되는 시뮬레이션 모니터링 파이프라인
scripts/pipelines/_example-all-types.json 모든 스텝 타입을 포함하는 Linux 환경용 예제 템플릿
scripts/pipelines/_example-all-types-si_simulation.json 모든 스텝 타입을 포함하는 Windows 환경용 예제 템플릿

IV. Agent API 엔드포인트

Agent와 서버 간의 통신에 사용되는 주요 API입니다. (server/routes/agent.js 참조)

HTTP 메서드 경로 기능
GET /api/agent/pipelines 활성화된 파이프라인 설정 조회
GET /api/agent/servers 서버 목록 조회 (자동 검색용)
GET /api/agent/health Agent 상태 점검
POST /api/agent/executions 새로운 파이프라인 실행 기록 생성
PUT /api/agent/executions/:id 파이프라인 실행 상태 업데이트
POST /api/agent/executions/:id/steps 파이프라인 단계별 상태 보고
POST /api/agent/executions/:id/result-files 실행 결과 파일 업로드
GET /api/agent/deployments/:serverId 배포 대기 중인 파일 조회

V. 일반적인 배포 절차

  1. 서버 등록: 관리 플랫폼에서 서버 정보를 등록합니다. 이때 host 필드는 Agent가 실행될 시스템의 IP 또는 호스트명과 일치해야 합니다.
  2. Agent 배포: Node.js Agent 실행 파일 (server/agent/engine.js)을 대상 서버에 복사합니다.
  3. Agent 실행: Agent를 시작합니다. --api와 --server (필요시) 파라미터를 설정합니다.
  4. 파이프라인 생성: 관리 플랫폼에서 파이프라인을 정의하고, 해당 Agent가 실행될 서버와 연결합니다.
  5. 파이프라인 트리거: 모니터링 디렉토리에 관련 파일을 생성하면, Agent가 이를 감지하여 정의된 파이프라인을 자동으로 실행합니다.

태그: agent Pipeline Monitoring Node.js python

11월 5일 14:54에 게시됨