> For the complete documentation index, see [llms.txt](https://docs.smply.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smply.one/it-device/host-management.md).

# 호스트 목록에서 기기 생성/연결하기

## 호스트 목록에서 기기 생성/연결하기

**호스트(Host)** 는 SMPLY Agent가 설치된 기기(엔드포인트)의 인벤토리 레코드입니다. 에이전트가 수집한 하드웨어·OS·로그인 정보를 기반으로 호스트와 SMPLY 기기를 연결해 관리합니다.

{% hint style="info" %}
**호스트 vs 기기**

* **호스트**: 에이전트가 설치된 실제 기기 정보 (hostname, OS, 시리얼)
* **SMPLY 기기**: 자산 관리 관점에서 등록된 기기 레코드 (관리번호, 소유자, 구매 정보 등)

하나의 SMPLY 기기에 하나의 호스트가 연결되는 구조로 운영됩니다.
{% endhint %}

***

### 1. 호스트 목록 페이지

**경로**: 사이드바 **호스트** 메뉴 → `/host/list`

**페이지 제목**: *호스트* **설명**: *"SMPLY 에이전트가 설치된 호스트 목록을 확인합니다."*

#### 헤더 액션 — `에이전트 다운로드` SplitButton

우측 상단 메인 버튼은 **`에이전트 다운로드`** (설치 패키지 받기). 드롭다운에는 **`설치 안내`** 가 있어 아직 설치 안 된 구성원에게 일괄로 안내 메일을 보낼 수 있습니다.

#### 상태 탭

| 탭         | 의미                                                         |
| --------- | ---------------------------------------------------------- |
| **전체**    | 모든 호스트                                                     |
| **활성**    | 정상 동작 중                                                    |
| **아카이브**  | 더 이상 사용하지 않는 호스트 (보관 처리)                                   |
| **연결 대기** | SMPLY가 사용자·기기 연결 제안을 만든 호스트. 건수가 0이면 숨겨집니다. 주황색 텍스트로 강조 표시 |

"연결 대기" 탭은 일반 그리드 대신 **승인 전용 패널**로 전환됩니다. 호스트별로 제안이 묶여 표시되고, 후보가 여럿인 경우 라디오로 하나를 고른 뒤 선택한 것만 한 번에 승인할 수 있습니다. 자세한 동작은 *5. "연결 대기" 패널에서 제안 승인*을 참고하세요.

***

### 2. 그리드 컬럼

기본 표시 컬럼 순서:

* 호스트명
* **상태** — 호스트 상태(활성 / 아카이브) 배지
* 플랫폼 (macOS / Windows 등)
* **사용자** — 연결된 구성원. 미연결이면 **`연결하기`** 링크, 추천이 있으면 옆에 주황색 `!` 배지가 함께 표시됩니다. 연결된 셀에 마우스를 올리면 X(연결 해제) 버튼이 나타납니다
* **기기** — 연결된 SMPLY 기기(관리번호). 미연결이면 **`연결하기`** 링크(추천 시 주황색 `!` 배지), 연결된 셀은 hover 시 X(연결 해제) 버튼
* OS 버전
* 하드웨어 모델
* 시리얼 번호
* 에이전트 버전
* **에이전트 확인** — 셀에는 마지막 확인 시각(상대 시간)과 에이전트 상태 배지가 표시됩니다. 기본 정렬은 이 컬럼 내림차순입니다

에이전트 상태 배지는 다음 네 가지입니다.

| 상태         | 의미                 |
| ---------- | ------------------ |
| **정상**     | 에이전트가 최근 정상적으로 확인됨 |
| **오프라인**   | 한동안 확인되지 않음        |
| **장기 미확인** | 오랫동안 확인되지 않음(주의)   |
| **비활성화**   | 에이전트가 비활성 처리됨      |

***

### 3. 호스트에 사용자/기기 연결하기

각 호스트 행의 **사용자** 셀과 **기기** 셀에서 직접 연결·해제할 수 있습니다. 두 셀 모두 동작이 같습니다 — 미연결이면 **`연결하기`** 링크, 연결된 셀에 마우스를 올리면 X(연결 해제) 버튼이 나타납니다. 추천이 있으면 링크 옆에 주황색 `!` 배지가 표시됩니다.

{% hint style="info" %}
**연결/해제는 관리자(Admin)만 가능합니다** 사용자·기기 연결, 연결 해제, 아카이브 등 호스트 관리 동작은 **관리자(Admin)** 역할에게만 노출됩니다. 일반 구성원에게는 선택 체크박스·일괄 작업·행 메뉴 자체가 보이지 않습니다.
{% endhint %}

#### 3-1. 사용자(구성원) 연결하기

**단계 1: 연결 다이얼로그 열기**

1. **사용자** 셀의 **`연결하기`** 링크를 클릭합니다.
2. *"사용자 연결하기"* 다이얼로그가 열립니다.

**단계 2: 추천 선택 또는 직접 선택**

* **추천**: SMPLY가 호스트 정보로 찾은 구성원이 상단에 **추천 카드**로 표시됩니다. 카드에는 추천 사유(예: *호스트명 일치*, *이메일 일치*, *이전에 연결됨*)와 매칭값이 함께 표시되며, 카드 우측 **`연결하기`** 버튼으로 바로 연결됩니다.
* **직접 선택**: 검색창에서 이름·이메일로 구성원을 찾아 라디오로 선택한 뒤 하단 **`연결하기`** 버튼을 누릅니다.

#### 3-2. SMPLY 기기 연결하기

**단계 1: 연결 다이얼로그 열기**

1. **기기** 셀의 **`연결하기`** 링크를 클릭합니다.
2. *"기기 연결하기"* 다이얼로그가 열립니다.

**단계 2: 기존 기기 선택 또는 신규 등록**

* **추천**: 시리얼 번호 등이 일치하는 기기가 있으면 **추천** 배지로 자동 추천되어, 관리번호·시리얼·모델명을 확인하고 **`연결하기`** 로 바로 연결할 수 있습니다.
* **직접 선택**: 검색창에서 관리번호·시리얼·모델명으로 기기를 찾아 선택합니다.
* **신규 등록**: 다이얼로그 하단의 **`새로 등록하기`** 버튼을 누르면 연결 다이얼로그가 닫히고 **기기 생성 다이얼로그**가 열립니다.

#### 3-3. 이미 다른 호스트에 연결된 기기를 연결할 때

연결하려는 기기가 이미 **다른 호스트에 연결돼 있으면**, *"기기 연결을 교체하시겠습니까?"* 확인 창이 뜹니다.

* *"이 기기는 이미 호스트 "{호스트명}"에 연결되어 있습니다. 교체하면 기존 연결이 해제되고 이 호스트에 연결됩니다."* 라는 안내가 표시됩니다.
* **`교체하기`** 를 누르면 기존 연결이 끊기고 현재 호스트로 옮겨집니다.

{% hint style="warning" %}
**연결 교체는 되돌리기 전 한 번 더 확인하세요** 한 기기는 한 번에 한 호스트에만 연결됩니다. 교체하면 기존 호스트의 기기 연결이 즉시 해제되므로, 의도한 호스트가 맞는지 확인한 뒤 진행하세요.
{% endhint %}

***

### 4. 호스트에서 신규 기기 생성 — 자동 채움

*"기기 생성하기"* 다이얼로그에서 다음 필드를 입력하면, 호스트가 수집한 정보가 자동으로 함께 저장됩니다.

**사용자 입력 필드**

| 필드       | 필수 | 설명                                                           |
| -------- | -- | ------------------------------------------------------------ |
| **카테고리** | ✅  | 노트북·모니터 등. 보통 노트북이 기본 제안                                     |
| **관리번호** | ✅  | 우리 조직의 관리 번호. **`추천 번호`** 버튼을 누르면 기존 번호 패턴을 분석해 다음 번호를 자동 제안 |

**자동 입력 항목** (*"호스트 정보에서 자동 입력되는 항목"* 회색 박스로 표시)

| 항목     | 소스                    |
| ------ | --------------------- |
| 모델명    | 호스트 하드웨어 모델           |
| 시리얼 번호 | 호스트 시리얼               |
| 사용자    | 호스트의 로그인 구성원          |
| OS     | 호스트 OS 버전 (OS 커스텀 필드) |
| 상태     | **사용 중** (고정)         |
| 소유구분   | **법인** (고정)           |

**단계 4: 저장 → 자동 연결**

1. **`기기 생성하고 연결하기`** 버튼을 클릭합니다.
2. 새 기기가 등록되고, 해당 호스트와 **자동으로 연결**됩니다.
3. 호스트 목록의 해당 행 **기기** 컬럼에 관리번호가 표시됩니다.

***

### 5. "연결 대기" 패널에서 제안 승인

"연결 대기" 탭은 SMPLY가 만든 사용자·기기 연결 제안을 **호스트별로 묶어** 보여주는 전용 패널입니다.

* 각 호스트 카드 아래에 추천된 **사용자** / **기기** 와 추천 사유(예: *시리얼 번호 일치*, *호스트명 일치*, *이메일 일치*, *이전에 연결됨*)가 표시됩니다.
* 후보가 **하나뿐(1:1)** 인 호스트는 자동으로 체크되어 있습니다.
* 후보가 **여럿** 인 호스트는 라디오로 하나를 먼저 골라야 체크할 수 있습니다.
* 좌측 체크박스로 호스트를 선택/해제하고, 상단 체크박스로 전체 선택할 수 있습니다.

상단 우측 **`선택 항목 승인 (N)`** 버튼을 누르면 선택된 제안이 한 번에 처리되고, 처리 결과(**N건 승인 완료** · 실패 시 **N건 실패**)가 표시됩니다.

***

### 6. 기기 목록에서 에이전트 정보 일괄 업데이트

호스트-기기 연결이 완료된 기기의 하드웨어·식별 정보를 최신 에이전트 수집값으로 한 번에 반영할 수 있습니다. 자산 실사 후 OS 버전·CPU·RAM 등을 수십\~수백 대 단위로 맞춰야 할 때 유용합니다.

**단계 1: 대상 기기 선택**

1. **기기** 목록(`/device`)으로 이동합니다.
2. 체크박스로 에이전트 정보를 갱신할 기기 여러 대를 선택합니다.
3. 하단 벌크 액션 바에서 **`에이전트 정보로 업데이트`** 를 클릭합니다.

**단계 2: 동기화할 필드 선택**

다이얼로그 상단에는 매칭 요약이 표시됩니다 — *"N대 동기화 가능 · M대 제외(시리얼 없음 X · 에이전트 없음 Y)"*.

| 그룹           | 필드                                   |
| ------------ | ------------------------------------ |
| **하드웨어 정보**  | OS · CPU · RAM · GPU · MAC 주소 · 메인보드 |
| **기기 식별 정보** | 모델명 · 브랜드 · **사용자**                  |

* **기본 선택**: 현재 값과 에이전트 수집값이 다른 필드만 자동 체크됩니다.
* 체크를 해제한 필드는 덮어쓰지 않습니다. 수동 배정된 소유자 값을 보존하려면 "사용자" 체크박스를 해제하세요.
* 선택한 필드가 일부 카테고리에 없으면 **"{카테고리} {N}대 · {필드} — 이 필드는 동기화되지 않습니다."** 알럿으로 안내됩니다.

**단계 3: 실행 및 결과 확인**

1. **`동기화`** 버튼을 클릭합니다. 선택된 기기 각각에 대해 카테고리별 커스텀 필드에 맞춰 변환된 값이 저장됩니다.
2. 완료되면 *"N대 기기의 에이전트 정보가 동기화되었습니다"* 토스트가 표시되고 그리드가 새로고침됩니다.
3. 시리얼이 없거나 연결된 에이전트가 없는 기기는 변경되지 않은 채 요약의 **제외** 카운트에만 집계됩니다.

{% hint style="info" %}
**같은 기기에 구/신 에이전트가 공존할 때** 에이전트 1.0.0 전환 구간에 같은 시리얼로 두 레코드가 남아 있을 수 있습니다. 벌크 동기화는 매칭된 에이전트 중 **가장 최근에 생성된(`createdAt`) 레코드**를 기준으로 값을 반영하므로 stale 값이 덮어쓰이지 않습니다.
{% endhint %}

{% hint style="warning" %}
**기기 편집 권한이 필요합니다** 벌크 액션 바의 **`에이전트 정보로 업데이트`** 항목은 **`device-edit`** 권한이 있는 구성원에게만 노출됩니다.
{% endhint %}

***

### 7. 호스트 상태 관리 (아카이브)

#### 단건 — 행 메뉴

행의 `⋯` 메뉴에서 호스트 상태를 변경할 수 있습니다.

* **활성 호스트**: **`아카이브`** 선택 → 더 이상 사용하지 않는 호스트로 표시. 기본 목록에서 숨겨지고 관리 대수에서 제외됩니다.
* **아카이브 호스트**: **`아카이브 해제`** 선택 → 다시 활성 상태로 복귀

#### 일괄 — 선택 후 하단 액션바

여러 호스트를 한 번에 아카이브하거나 해제할 수 있습니다.

1. 좌측 체크박스로 대상 호스트를 여러 개 선택합니다.
2. 하단에 나타나는 **`일괄 작업`** 액션바에서 **`아카이브`** 또는 **`아카이브 해제`** 를 선택합니다.
3. *"선택한 {N}개 호스트를 아카이브합니다…"* 확인 창에서 진행합니다.

{% hint style="info" %}
**선택·일괄·행 메뉴는 관리자(Admin) 전용** 선택 체크박스, 하단 일괄 작업 액션바, 행 `⋯` 메뉴는 **관리자(Admin)** 에게만 표시됩니다. 일반 구성원에게는 목록 조회만 제공됩니다.
{% endhint %}

***

### 8. 좌석(Seat) 제한 안내

플랜에 호스트 좌석 수 제한이 있는 경우, 목록 상단에 안내 배너가 표시됩니다.

* **여유가 있을 때**(녹색): *"{관리 중}/{좌석}대 관리 중"* 또는 *"최대 {좌석}대 관리 가능"*.
* **초과했을 때**(주황색 경고): *"최대 {좌석}대 관리 가능 · {초과}대 초과 · 추가 관리는 담당 매니저에게 문의하세요"* 와 함께 **`담당 매니저에게 문의`** CTA가 노출됩니다.

초과분 호스트는 🔒 아이콘으로 잠김 표시됩니다. 계속 관리하려면 플랜 업그레이드 또는 오래된 호스트 아카이브가 필요합니다.

***

### 9. 권한 안내

| 작업                      | 필요 권한            |
| ----------------------- | ---------------- |
| 호스트 목록 조회               | 기본 구성원 이상        |
| 사용자/기기 연결·연결 해제         | **관리자(Admin)**   |
| 호스트에서 기기 생성·연결          | **관리자(Admin)**   |
| 아카이브 / 해제 (단건·일괄)       | **관리자(Admin)**   |
| 에이전트 설치 안내 메일 발송        | **관리자(Admin)**   |
| 기기 목록에서 에이전트 정보 일괄 업데이트 | `device-edit` 권한 |

{% hint style="info" %}
**관리 동작은 관리자(Admin) 전용** 호스트의 연결·연결 해제·아카이브 같은 관리 동작은 관리자에게만 노출됩니다. 일반 구성원에게는 선택 체크박스·일괄 작업·행 메뉴가 보이지 않고 목록 조회만 제공됩니다.
{% endhint %}

플랜이 만료되면 편집 액션이 비활성화됩니다.

***

### 10. 자주 묻는 질문

#### Q: 호스트 연결 제안이 자동으로 만들어지는 기준은 무엇인가요

시리얼 번호 외에도 여러 단서로 제안이 만들어집니다.

* **기기 제안**: 시리얼 번호 등이 일치하는 기기를 추천합니다.
* **사용자 제안**: **시리얼 번호 일치 / 호스트명 일치 / 이메일 일치 / 이전에 연결됨** 같은 여러 기준으로 구성원을 추천합니다. 관찰 출처(예: Chrome 프로필)가 사유에 함께 표시되기도 합니다.

한 호스트에 후보가 **여럿** 나올 수 있으며, 이 경우 **연결 대기** 패널에서 라디오로 하나를 골라 승인합니다.

#### Q: 호스트에서 자동 채움된 정보가 잘못되어요

* 호스트 수집 정보(특히 모델명·OS)가 잘못된 경우가 간헐적으로 있습니다.
* 기기 생성 후 기기 상세 페이지에서 해당 필드를 직접 수정할 수 있습니다.
* 반복적으로 틀린다면 채널톡으로 호스트 정보를 보내주세요.

#### Q: "추천 번호" 버튼이 이상한 번호를 제안해요

관리번호 추천은 기존 번호들의 **공통 패턴**을 분석해서 다음 값을 예측합니다. 번호 체계를 바꿨거나 부서별 규칙이 있다면 수동 입력을 권장합니다.

#### Q: 호스트를 삭제할 수 있나요

직접 삭제 대신 **아카이브** 를 사용합니다. 에이전트가 제거되어 오래 확인되지 않은 호스트는 에이전트 상태가 자동으로 **`장기 미확인`** 으로 전환됩니다.

#### Q: 이 외의 문제

채널톡으로 문의해 주세요.