Agent 및 파이프라인 플랫폼 활용 가이드
I. Agent: 서버 정보 등록 및 관리
1. Agent를 위한 서버 정보 획득
Agent 실행 시 필요한 서버 ID는 다음과 같은 방법으로 확인할 수 있습니다.
방법 1: 관리 플랫폼 UI 활용 (가장 간편)
- 모니터링 플랫폼의 "서버 모니터링" 메뉴로 이동합니다.
- 표의 첫 번째 열에 표시된 "서버 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는 시작 시 자동으로 서버를 검색합니다.
- Agent는 실행 중인 시스템의 호스트명(hostname) 및 IP 주소를 수집합니다.
- 수집된 정보와 데이터베이스에 등록된 모든 서버의 `host` 필드를 비교합니다.
- 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. 일반적인 배포 절차
- 서버 등록: 관리 플랫폼에서 서버 정보를 등록합니다. 이때
host필드는 Agent가 실행될 시스템의 IP 또는 호스트명과 일치해야 합니다. - Agent 배포: Node.js Agent 실행 파일 (
server/agent/engine.js)을 대상 서버에 복사합니다. - Agent 실행: Agent를 시작합니다.
--api와--server(필요시) 파라미터를 설정합니다. - 파이프라인 생성: 관리 플랫폼에서 파이프라인을 정의하고, 해당 Agent가 실행될 서버와 연결합니다.
- 파이프라인 트리거: 모니터링 디렉토리에 관련 파일을 생성하면, Agent가 이를 감지하여 정의된 파이프라인을 자동으로 실행합니다.