ModernAdminStudio/USAGE.md

Enterprise Admin Studio - 사용자 가이드 및 운영 매뉴얼 (USAGE.md)

1. 사전 요구사항 (Prerequisites)

• 운영체제: Windows 10, Windows 11, Windows Server 2016 / 2019 / 2022 / 2025
• PowerShell 환경:
  • 권장: PowerShell 7.x (pwsh.exe)
  • 지원: Windows PowerShell 5.1 (powershell.exe)
• .NET 환경: .NET Framework 4.7.2+ 또는 .NET 8 Desktop Runtime (WPF 지원)
• 네트워크 방화벽 오픈 (실제 Live 모드 사용 시):
  • Active Directory: TCP 389 (LDAP) 또는 TCP 636 (LDAPS)
  • NetApp ONTAP: TCP 443 (HTTPS REST API)
  • MS SQL Server: TCP 1433 (Default Instance)

---

2. 애플리케이션 시작 (How to Run)

방법 A: 탐색기에서 원클릭 실행 (권장)

• C:\dev\ws\ModernAdminStudio\Run.bat 파일을 더블 클릭합니다.
• 배치 파일이 시스템에 설치된 pwsh.exe(PowerShell 7)를 우선 감지하여 백그라운드 콘솔창 없이 깔끔하게 Modern UI 창만 띄웁니다.

방법 B: 터미널에서 직접 실행

cd C:\dev\ws\ModernAdminStudio
pwsh -ExecutionPolicy Bypass -File .\Start-App.ps1

(PowerShell 5.1 콘솔에서도 동일하게 동작합니다.)

---

3. 동작 모드 (Operation Modes)

앱 상단 우측에는 현재 동작 모드가 배지로 표시됩니다:

1. 데모 / 모의 모드 (Mock Mode - 보라색 배지):
   • 실제 장비나 도메인에 연결되지 않아도 모든 UI 인터랙션, 그리드 정렬, 백업 시뮬레이션, 잠금 해제 시뮬레이션을 완벽하게 테스트할 수 있는 개발/시연 모드입니다.
2. 실제 연결 모드 (Live Mode - 초록색 배지):
   • 실제 Active Directory 도메인 컨트롤러, NetApp ONTAP 스토리지 REST API, MS SQL Server 인스턴스와 직접 통신하여 실제 자원을 조회 및 제어합니다.

Tip

모드 전환 방법: 좌측 메뉴의 **[환경설정 및 연결]**로 이동하여 상단의 실제 연결 모드 활성화 (Live Production Mode) 또는 각 컴포넌트별 실제 연결 사용 체크박스를 체크한 후 **[설정 저장 및 적용]**을 누르면 즉시 전환됩니다.

---

4. 메뉴별 상세 사용법

4.1 통합 대시보드 (Dashboard)

• KPI 통계 카드: AD 총 사용자 및 잠김 계정 수, NetApp Qtree/볼륨 수 및 사용률, 활성 공유 수, 온라인 SQL DB 수를 실시간 요약 표시합니다.
• 최근 시스템 감사 로그: 인프라 전반의 최신 감사 이벤트 내역을 타임라인 그리드로 제공합니다.
• 빠른 작업 바로가기: 자주 사용하는 주요 작업(AD 계정 생성/해제, Quota 증설, 공유 생성, SQL 백업)으로 1클릭 이동합니다.

4.2 Active Directory 관리

• 계정 검색: 검색창에 사용자 ID(SamAccountName), 이름(DisplayName), 부서명을 입력하고 검색을 클릭합니다.
• 상세 정보 인스펙터: 그리드에서 사용자를 클릭하면 우측 카드에 실시간으로 UPN, DN(OU 경로), 계정 상태, 암호 변경일, 소속 보안 그룹이 표시됩니다.
• 계정 잠금 해제 (Unlock):
  • 잠긴 계정을 선택하고 상단 툴바의 잠금 해제 버튼을 클릭합니다.
  • Live 모드에서는 실제 LDAP 디렉터리의 lockoutTime = 0이 커밋되어 즉시 잠금이 해제됩니다.
• 암호 초기화 (Reset Password):
  • 계정을 선택하고 암호 초기화 버튼을 클릭하면 임시 보안 암호가 생성되어 부여되며, 다음 로그온 시 암호 변경 플래그가 자동 지정됩니다.
• 활성화 / 비활성화:
  • 활성화/비활성화 토글 버튼을 통해 계정 사용 여부를 원클릭으로 변경할 수 있습니다.

4.3 NetApp 스토리지 관리

• 상단 클러스터 / SVM 선택기: 관리할 NetApp 스토리지 클러스터 및 SVM(Vserver)을 드롭다운으로 선택합니다.
• 서브 탭 1: Qtree 관리:
  • 볼륨별 Qtree 목록, 보안 스타일(NTFS / UNIX / Mixed), Oplocks 활성화 상태를 확인합니다.
  • + 새 Qtree 생성 버튼을 클릭하여 볼륨 내 신규 Qtree를 즉시 프로비저닝할 수 있습니다.
• 서브 탭 2: Quota (용량 한도):
  • 트리(Tree), 사용자(User), 그룹(Group) 단위로 설정된 Quota 정책을 조회합니다.
  • 현재 사용량, Soft Limit, Hard Limit 및 임계치 초과 여부(주의/경고 배지)를 한눈에 파악합니다.
• 서브 탭 3: 파일 공유 (CIFS / NFS):
  • 활성화된 Windows SMB (CIFS) 및 Linux NFS 공유 목록, 마운트 경로, 권한 요약을 확인합니다.
  • + 신규 공유 생성 버튼을 통해 공유 이름과 경로를 지정하여 신규 파일 공유를 생성합니다.

4.4 공유 권한 및 AD 보안그룹 연동 관리 (신규 워크플로우 틀)

핵심 시나리오: DB에서 Share 목록 및 권한 대상자를 조회하고, 체크박스로 원하는 사용자를 선택하여 Share와 동일한 이름의 AD 보안그룹에 사용자를 추가하거나 해제(제거)합니다.

1. 상단 Share 선택:
   • 관리 대상 Share (공유) 콤보박스에서 작업할 공유(예: Finance_Share, HR_Share)를 선택합니다.
   • 선택 즉시 우측의 연계 보안그룹 배지가 해당 Share 이름으로 자동 변경됩니다.
2. 좌측: DB 사용자 목록 확인 및 선택:
   • DB에서 조회된 사용자 목록을 확인하고, 처리할 사용자를 체크박스로 1명 이상 선택합니다. (상단의 전체선택 / 선택해제 버튼 활용 가능)
3. 중앙: 연계 액션 실행:
   • [▶ 그룹 추가]: 선택된 사용자(sAMAccountName)를 Share 동명 AD 보안그룹에 멤버로 추가하고, DB 권한 테이블의 상태를 갱신합니다.
   • [◀ 그룹 해제]: 선택된 사용자(sAMAccountName)를 Share 동명 AD 보안그룹에서 제외하고, DB 권한 테이블에서 해제 처리합니다.
4. 우측 & 하단: 검증 및 로그:
   • 우측 그리드에서 실제 AD 보안그룹 멤버십이 실시간 갱신되는 것을 확인합니다.
   • 하단 콘솔 창에서 각 사용자별 처리 단계([AD] 추가 완료, [DB] 갱신 완료)의 세부 로그를 확인할 수 있습니다.

Tip

직접 세부 로직을 채워 넣는 위치: Modules/ShareSyncService.ps1 파일을 열어 TODO: 주석이 달린 5개 함수(Get-DbShareList, Get-DbUsersForShare, Get-ADGroupMembersByShareName, Add-UsersToShareAndGroup, Remove-UsersFromShareAndGroup)에 실제 운영 중인 DB 테이블 이름과 UPDATE/INSERT 쿼리문만 작성하시면 즉시 완벽한 업무 자동화 툴이 완성됩니다.

4.5 MS SQL 데이터베이스 관리

• 인스턴스 연결 바: 상단에서 대상 SQL 인스턴스와 인증 방식(Windows 통합 인증 / SQL 계정)을 선택하고 연결 테스트를 수행할 수 있습니다.
• 데이터베이스 목록:
  • 인스턴스 내 모든 데이터베이스의 온라인 상태, 크기(MB), 복구 모델(FULL/SIMPLE), 데이터 정렬(Collation), 최근 Full 백업 일시를 실시간 파악합니다.
• 원클릭 Full 백업:
  • 목록에서 DB를 선택하고 즉시 백업 (Full) 버튼을 누르면 실제 백업 T-SQL 명령어가 실행되어 지정된 백업 디렉터리에 .bak 파일이 생성됩니다.
• T-SQL 간이 쿼리 콘솔:
  • 우측 하단 에디터에 쿼리를 입력하고 ▶ 쿼리 실행을 누르면 결과가 하단 콘솔 창에 즉시 출력됩니다.

4.5 환경설정 및 연결 구성 (Settings)

• 접속 파라미터 구성:
  • AD 도메인 컨트롤러 주소, 기본 검색 루트 OU, LDAPS 사용 여부
  • NetApp 클러스터 REST API 엔드포인트 URL, 대상 SVM, 관리자 계정/비밀번호
  • SQL Server 인스턴스 주소, 인증 모드, 백업 디렉터리 경로
• 개별 연결 테스트: 각 섹션의 연결 테스트 버튼을 통해 개별 시스템의 연결 상태를 사전 검증합니다.
• 전체 인프라 일괄 진단: 하단의 전체 인프라 연결 상태 일괄 진단 버튼을 누르면 AD, NetApp, SQL Server를 순차 점검하여 종합 리포트를 팝업으로 안내합니다.
• 설정 저장: 설정 저장 및 적용을 누르면 모든 내용이 config.json에 안전하게 암호화/저장되고 앱 전반에 즉시 반영됩니다.

---

5. 트러블슈팅 (Troubleshooting)

현상	원인 및 해결 방법
AD 연결 실패 (Server is not operational)	1. 도메인 컨트롤러 FQDN/IP가 올바른지 확인하십시오. 2. TCP 389/636 포트가 방화벽에서 허용되었는지 확인하십시오. 3. 도메인 가입 PC가 아닌 경우 설정 화면에서 관리자 자격증명을 입력하십시오.
NetApp REST API 401 Unauthorized	1. ONTAP 클러스터 관리자 계정(admin 또는 vsadmin)의 비밀번호를 확인하십시오. 2. ONTAP 9.6 이상 버전인지 확인하십시오.
NetApp SSL 인증서 에러	NetApp 기본 사설 인증서를 사용하는 경우 설정 화면에서 자체 서명(Self-signed) SSL 인증서 신뢰 옵션을 체크하십시오.
SQL Server 접속 실패 (Server not found)	1. SQL Server 인스턴스 이름 및 TCP/IP 프로토콜 활성화 여부를 확인하십시오. 2. SQL Server Browser 서비스 실행 여부 및 포트 1433 방화벽을 확인하십시오.