문서 센터 - Jianxiu Tech

Project A

EasyOps 문서

Knowledge Base

전체 스택 운영 및 유지 관리 지식 기반

요점:은 네트워크가 없는 컴퓨터실 시나리오에 맞게 오프라인 검색 및 카테고리 검색을 지원합니다.

네트워크 엔지니어링

Huawei/H3C/Cisco 명령 빠른 확인, OSPF/STP 문제 해결.

약한 전류 보안

IPC 디버깅, 액세스 제어 배선 다이어그램, 검은색 화면 모니터링 및 PTZ 오류 위치.

데스크탑 작동 및 유지 관리

Windows 문제 해결, 프린터 공유 문제, DNS/IP 복구.

리눅스/서버

쉘 공통 명령, RAID 유지 관리, 방화벽 구성 및 강화.

클라우드 네이티브

Docker/K8s 공통 명령, 포드 예외 진단 및 배포 빠른 확인.

데이터베이스

MySQL / Redis 운영 및 유지 관리 매뉴얼, 느린 쿼리 및 백업 및 복구 가이드.

Toolbox

엔지니어링 도구 상자

요점:현장 고주파 기능은 "계산 + 진단 + 쿼리 + 작동 및 유지 관리"에 따라 계층적으로 구성되어 도구의 신속한 배치를 용이하게 합니다.

보안 스토리지

NVR 하드 드라이브 용량 추정

서브넷 마스크

IP 범위 및 브로드캐스트 컴퓨팅

PoE 전력 소비

터미널 전원 공급 장치 예산

섬유 감쇠

링크 dB 손실 추정

네트워크 진단

TCP 핑/포트 스캔/LAN 스캔

네트워크 운영 및 유지 관리 센터

HTTP 감지/WOL/도구 집계

네트워크 쿼리 센터

DNS / Whois(RDAP) / OUI

SSH 도구

연결 관리/상태 폴링/빠른 명령

첫 번째 초기화 지침

요점:는 약 15MB의 핵심 데이터를 다운로드하려면 처음으로 인터넷에 연결해야 합니다. 초기화 완료 후 오프라인 사용이 가능합니다.

로컬 우선순위:지식 베이스, 컬렉션, 기록 및 스캔 결과는 기본적으로 장치에 로컬로 저장되며 핵심 데이터는 업로드되지 않습니다.

보안 스토리지:민감한 구성 항목은 일반 텍스트 노출을 방지하기 위해 시스템 보안 기능(예: 키체인)을 사용하여 저장됩니다.

Project Divider

Project B

Asset Sonar 문서

배포 및 구성

프로덕션 구성으로 전환하기 전에 테스트 환경에서 전체 프로세스 드릴(스캔 → 확인 → 동기화 → 내보내기)을 완료하는 것이 좋습니다.

중요 알림

생산에 들어가기 전에 테스트 환경을 완전히 실행하는 것이 좋습니다. 첫 번째 생산 배치의 경우 10~20개의 그레이스케일 단위를 동기화한 다음 안정화 후 볼륨을 해제하는 것이 좋습니다.

01환경 요구 사항

Windows 10/11(22H2+ 권장, x64)
.NET Desktop Runtime 8.0 (x64)
관리자 권한으로 실행하는 것이 좋습니다(전체 하드웨어 및 시스템 정보를 쉽게 읽을 수 있도록).
Snipe-IT API 키(적어도 자산 읽기 및 쓰기, 구성 요소/액세서리 연결 권한 포함)
Snipe-IT 네트워크에서 클라이언트에 연결할 수 있습니다(HTTP/HTTPS 및 역방향 프록시 정책에 의해 허용됨).

02프로필.json 예(다중 환경)

{
  "Profiles": [
    {
      "Name": "Production",
      "ApiUrl": "http://snipeit.company.local/api/v1",
      "ApiKey": "YOUR_PROD_API_KEY",
      "TagPrefix": "AS-",
      "EnableComponents": true,
      "EnableAccessories": true,
      "Location": "HQ",
      "Company": "JianXiu Tech"
    },
    {
      "Name": "Lab",
      "ApiUrl": "http://snipeit-lab.local/api/v1",
      "ApiKey": "YOUR_LAB_API_KEY",
      "TagPrefix": "LAB-",
      "EnableComponents": false,
      "EnableAccessories": false,
      "Location": "LAB",
      "Company": "JianXiu Tech"
    }
  ]
}

API 키는 시스템 보안 메커니즘에 의해 보관되고 오랫동안 공유 시스템에 일반 텍스트로 저장되지 않는 것이 좋습니다.

02.1액세서리/구성 요소/모델 구성 참조

은 동기화 중 연결 실패 또는 중복 생성을 방지하기 위해 Snipe-IT에서 "구성 요소, 액세서리 및 모델"의 매핑 이름을 통합하는 데 사용됩니다.

{
  "ActiveProfile": "默认",
  "Profiles": {
    "默认": {
      "InternalUrl": null,
      "ExternalUrl": null,
      "ApiKey": null,
      "Department": null,
      "AssignName": null,
      "AssignUser": null,
      "AssignPassword": null,
      "EmailSuffix": "example.com",
      "ASSET_TAG_PREFIX": "DOZ",
      "CATEGORY_ID_MAP": {
        "笔记本电脑": 4,
        "台式机": 3,
        "显示器": 5
      },
      "COMPONENT_CATEGORY_ID_MAP": {
        "处理器": 7,
        "内存": 9,
        "硬盘": 10
      },
      "ACCESSORY_CATEGORY_ID_MAP": {
        "键盘": 15,
        "鼠标": 16
      },
      "CATEGORY_CODE_MAP": {
        "笔记本电脑": "BJB",
        "台式机": "TSJ"
      }
    }
  }
}

먼저 Snipe-IT에서 대상을 사전 빌드하는 것이 좋습니다. Model、Component、Accessory, 일괄 동기화를 다시 수행하세요.
이름 지정은 중복 개체(예: 16G / 16GB）。
가 처음으로 온라인 상태가 되면 배치를 확장하기 전에 매핑을 확인하기 위해 10개 단위를 샘플링하는 것이 좋습니다.

03권장 작업 절차(생산 환경)

준비단계(온라인 접속 전)
- 현재 선택되어 있는지 확인 Production 테스트 환경을 실수로 작성하는 것을 방지하기 위한 프로파일입니다.
- 검증 ApiUrl、ApiKey, 구성 요소/액세서리 스위치는 이 목록의 범위와 일치합니다.
- 먼저 프로토타입을 사용하여 연결을 확인합니다(키 필드를 스캔하고 동기화하고 다시 쓸 수 있음).
스캐닝 단계(로컬 먼저, 그 다음 동기화)
- 은 일련 번호, 모델 번호 및 자산 태그가 완전한지 확인하는 데 중점을 두고 로컬 스캔을 수행합니다.
- 더티 데이터가 자산 라이브러리에 직접 동기화되는 것을 방지하려면 먼저 null 값 필드를 채우거나 표시하세요.
- 부서/층별로 일괄적으로 작업을 구축하는 것이 좋습니다(예: 배치당 30~50개 단위).
검증단계(샘플링 검증)
- 배치당 3~5개 단위를 샘플링하여 자산 태그, 일련번호, 모델 및 위치 필드의 매핑을 확인합니다.
- 는 "자산 업데이트가 있음/새 자산이 존재하지 않음" 동작이 예상한 대로임을 확인합니다.
- 필드 정렬 불량이 발견되면 후속 배치를 계속하기 전에 매핑 구성을 수정하십시오.
동기화 단계(그레이스케일 발전)
- 먼저 소규모 배치로 동기화하고(첫 번째 배치에는 10~20개 장치 권장) 오류 코드와 실패율을 관찰합니다.
- 일회성 전체 가져오기로 인한 롤백 압력을 피하기 위해 안정적인지 확인한 후 배치를 확장합니다.
- 각 배치가 완료된 후 즉시 스냅샷(CSV/PDF)을 내보내고 배치 번호를 기록합니다.
예외 처리 단계(손절매 우선)
- 대규모 오류가 발생하면 후속 배치가 일시 중지되고 전체 재실행이 수행되지 않습니다.
- 는 오류 코드 그룹(401/403 권한, 404 경로, 409 충돌, 422 필드)에 따라 처리됩니다.
- 을 복구한 후에는 실패한 개체만 다시 시도하고 성공한 개체는 반복적으로 기록되지 않습니다.
마무리 단계(보관 및 검토)
- 은 "스캔 스냅샷 + 동기화 결과 + 예외 목록 + 작업 로그"를 보관합니다.
- 은 이러한 구성 변경 및 문제 처리 결론을 기록하고 팀 SOP를 업데이트합니다.

04필터링 및 잡음 제거 제안

"IGNORE_KEYWORDS": [
  "VMware", "Virtual", "Hyper-V", "Loopback", "Bluetooth",
  "WAN Miniport", "Teredo", "Docker", "vEthernet"
]

은 유효하지 않은 자산 노이즈를 줄이기 위해 가상 네트워크 카드, 터널 어댑터 및 임시 인터페이스를 필터링하는 데 사용됩니다.

05내보내기 및 보관 제안

시스템 조정 및 수동 서명 보존을 용이하게 하기 위해 인벤토리 단계에서 CSV + PDF를 동시에 내보내는 것이 좋습니다.
명명 제안:site-dept-date-batch,예를 들어 hq-it-2026-04-08-b01。
감사 검토를 용이하게 하기 위해 "스캔 스냅샷 + 동기화 결과 + 예외 목록"을 동일한 아카이브 디렉토리에 넣습니다.

자주 묻는 질문(FAQ) 및 문제 해결

"현상 → 원인 → 처리순서"를 먼저 읽어보시고 문제를 빨리 찾아내시기를 권장합니다.

1) 일련번호를 스캔할 수 없거나 모델번호가 비어 있습니까?

일반적인 이유: 권한 부족, 비정상적인 WMI 서비스 및 장치 BIOS 정보 누락.

관리자로 Asset Sonar를 실행합니다.
WMI 서비스(Winmgmt)가 정상인지 확인하세요.
BIOS/UEFI에서 일련 번호 필드가 지워지지 않았는지 확인하십시오.

2) Snipe-IT(401/403/404)에 연결할 수 없습니까?

먼저 API 주소에 다음이 포함되어 있는지 확인하세요. /api/v1, 키와 권한을 다시 확인하세요.

401: API 키가 올바르지 않거나 만료되었습니다.
403: 키 권한이 부족합니다(쓰기/연결 권한 없음).
404: 경로 오류, 역방향 프록시가 API 경로를 전달하지 않습니다.

3) 동기화 후 중복된 자산이 나타납니까?

중복은 일반적으로 "일련번호 불일치" 또는 "과거 더티 데이터"에서 발생합니다.

은 기본 키 전략으로 "일련번호 + 자산 태그"를 우선시합니다.
과거의 빈 일련번호 자산을 수동으로 입력하거나 보관용으로 표시하세요.
먼저 테스트 환경에서 배치를 실행하여 복제 전략을 확인한 후 프로덕션에 출시합니다.

4) 구성요소/액세서리 연결에 실패했습니까?

은 대상 개체가 존재하지 않거나 ID 매핑이 실패할 때 더 일반적입니다.

대상 구성 요소 및 액세서리가 Snipe-IT에 존재하고 할당할 수 있는지 확인하십시오.
프로필에서 활성화되어 있는지 확인하세요. EnableComponents / EnableAccessories。
실패 로그에서 개체 이름과 ID를 확인하고 매핑을 수정한 후 다시 시도하십시오.

5) 스캔 속도가 느리거나 UI가 멈췄나요?

에서는 동시성을 줄이고, 검색 범위를 좁히고, 가상 장치를 필터링할 것을 권장합니다.

먼저 하드웨어 기본 필드 수집을 수행한 다음 확장된 필드 보충 스캔을 수행합니다.
가상 네트워크 카드와 유효하지 않은 인터페이스를 제외하여 소음을 줄이세요.
대량 배치 재고를 일괄(부서별/층별)로 실행합니다.

6) 내보낸 파일이 깨졌거나 필드가 잘못 정렬되어 있습니까?

는 일반적으로 인코딩이나 지역 설정의 차이로 인해 발생합니다.

CSV UTF-8(BOM 포함) 가져오기 테이블 도구를 사용하는 것이 좋습니다.
현지화 차이를 방지하기 위해 날짜 형식과 소수점 규칙을 통합합니다.
팀 간 전송 시 변형을 방지하기 위해 PDF 아카이브 버전이 선호됩니다.

7) "부분 성공, 부분 실패"는 왜 발생하나요?

이는 일괄 처리 시나리오의 일반적인 보호 전략입니다. 성공한 항목은 먼저 라이브러리에 삭제되고 실패한 항목은 재시도 대기열에 배치됩니다.

먼저 실패 목록을 내보내고 오류 코드에 따라 그룹으로 처리합니다.
권한/매핑/네트워크를 수정한 후 실패한 배치를 다시 시도하세요.
는 전체 재실행을 방지하고 반복적인 쓰기 및 더티 데이터의 위험을 줄입니다.

8) 프로덕션 환경에서 안전하게 온라인으로 전환하는 방법은 무엇입니까?

은 "회색조 온라인" 방법을 권장합니다.

Lab Profile에서 첫 번째 테스트를 실행하고 필드 매핑을 확인합니다.
프로덕션 환경은 먼저 첫 번째 동기화 배치를 위해 작은 범위의 자산을 선택합니다.
이상이 없는지 확인한 후 범위를 확장하고, 배치별 내보내기 스냅샷을 보관합니다.

오류 코드 빠른 확인(HTTP/일반 오류)

은 "구성 문제, 권한 문제, 네트워크 문제"를 어디서부터 시작해야 할지 빠르게 결정하는 데 사용됩니다.

오류 코드/현상	일반적인 이유	우선순위 처리 단계
`401 Unauthorized`	API 키가 잘못되었거나, 만료되었거나 취소되었습니다.	키를 재생성하고 요청 헤더 형식과 프로필이 유효한지 확인합니다.
`403 Forbidden`	키에 권한이 부족합니다(쓰기/연결 없음).	키에 자산, 구성요소, 액세서리 관련 권한 추가
`404 Not Found`	URL 경로 오류, 누락 `/api/v1`	ApiUrl 수정, 역방향 프록시 전달 규칙 확인
`409 Conflict`	자산 태그 또는 일련번호 충돌	기본 키를 눌러 중복 항목을 먼저 제거한 후 증분 동기화를 수행하세요.
`422 Unprocessable Entity`	필드 형식이 API 요구 사항을 충족하지 않습니다.	필수 필드, 길이, 열거 값 및 날짜 형식을 확인하세요.
`429 Too Many Requests`	요청 주파수가 너무 높아 전류 제한이 트리거됩니다.	동시성을 줄이고 백오프 재시도 및 배치 간격을 늘립니다.
`500 / 503`	서버 예외 또는 유지 관리 기간	실패한 배치를 보관하고 간격을 두고 재시도한 후 서버 관리자에게 문의하세요.
연결 시간 초과/TLS 실패	네트워크에 연결할 수 없으며 인증서 체인이 비정상입니다.	먼저 연결을 테스트한 다음 인증서와 시간 동기화를 확인하세요.

문제 해결 Runbook(현장 실행 버전)

동기화가 비정상일 경우, 오판단 및 반복작업을 줄이기 위해 다음과 같은 순서로 실행하는 것을 권장합니다.

A단계: 기본 연결

ApiUrl에 액세스할 수 있는지 확인하십시오(포함). /api/v1）。
DNS 확인, 포트 정책 및 프록시 규칙을 확인합니다.
TLS 확인 실패를 방지하려면 장치 시스템 시간이 정확한지 확인하세요.

단계 B: 권한 및 구성

API 키 유효성 및 역할 권한을 확인합니다.
프로필에서 올바른 환경(Lab/Prod)이 선택되었는지 확인하세요.
구성 요소/액세서리 스위치가 매핑과 일치하는지 확인하십시오.

C단계: 데이터 품질 및 중복 제거

샘플을 기준으로 일련번호, 자산 태그, 모델 필드를 확인하세요.
과거의 비어 있는 일련 번호와 중복 자산을 정리합니다.
실패한 배치에 대한 "오류 코드 → 처리기" 추적 테이블을 생성합니다.

단계 D: 복구 및 재생

전체 재실행을 방지하려면 실패한 배치만 재시도하십시오.
"성공/실패 목록"을 내보내고 보관합니다.
근본 원인과 수리 계획을 기록하고 팀 SOP를 업데이트합니다.

5분 빠른 문제 해결 카드(긴급 근무)

는 "현장에서 서둘러 복구한 후 더 깊이 파고드는" 시나리오에 적합합니다. 먼저 문제를 분류한 다음 전체 Runbook을 입력합니다.

1분

오류 코드 참조

먼저 4xx / 5xx / 시간 초과를 구분하고 권한 회선을 사용할지 네트워크 회선을 사용할지 결정합니다.

2분

URL 및 키 확인

확인 /api/v1, 프로필, API 키 및 권한이 정확합니까?

3-4분

소규모 배치 재시도

는 실패한 개체만 재시도하고 영향이 증폭되는 것을 방지하기 위해 전체 재실행을 수행하지 않습니다.

5분

증거 남기기

작업 주문 템플릿에 따라 실패 목록 + 로그 조각 내보내기, 보고 및 전달.

문서 센터.