# op.dcout.site Minecraft 원격 관리 운영 설명서

이 문서는 대시보드의 `오류 코드` 패널이나 토스트에 나온 코드를 기준으로 문제를 찾기 위한 운영 문서입니다.

## 기본 점검 순서

1. 대시보드에서 서버가 `에이전트 연결됨`인지 확인합니다.
2. 초보자 가이드에서 실패한 항목을 먼저 봅니다.
3. `최근 로그`에서 같은 시간대의 오류를 검색합니다.
4. `오류 코드` 패널의 코드를 이 문서에서 찾습니다.
5. 설정 화면에서 서버 폴더, 시작 명령, 게임 포트, RCON 포트, 백업 경로를 확인합니다.

## 설정 화면 기준

- `서버 폴더`: `paper.jar`, `server.properties`, `logs/latest.log`가 있는 폴더입니다.
- `시작 명령`: 서버 폴더에서 실행되는 명령입니다. 예: `"C:\Program Files\Eclipse Adoptium\jre-25.0.3.9-hotspot\bin\java.exe" -Xms1G -Xmx4G -jar paper.jar nogui`
- `중지 명령`: 비워두면 에이전트가 RCON `stop`을 사용합니다.
- `게임 호스트/포트`: 보통 `127.0.0.1:25565`입니다.
- `RCON 호스트/포트`: 보통 `127.0.0.1:25575`입니다.
- `백업 경로`: 에이전트 PC에서 ZIP 백업을 쓸 수 있는 폴더입니다.
- `상태 갱신 주기`: 에이전트가 중앙 서버로 상태를 보내는 간격입니다. 너무 짧게 잡지 마세요.

RCON 비밀번호와 에이전트 토큰은 보안상 웹 대시보드에 표시하거나 저장하지 않습니다. 이 값은 에이전트 PC의 로컬 설정 파일에만 둡니다.

## 오류 코드

### AUTH_LOGIN_REQUIRED

- 원인: 세션 쿠키가 없거나 만료되었습니다.
- 확인: 로그인 화면으로 이동했는지 확인합니다.
- 조치: 다시 로그인한 뒤 작업을 반복합니다.

### SERVER_NOT_FOUND

- 원인: 서버 ID가 없거나 현재 계정 소유 서버가 아닙니다.
- 확인: URL의 `/servers/{server_id}` 값과 서버 목록을 비교합니다.
- 조치: 서버 목록에서 다시 선택합니다. 필요하면 새 등록 코드를 만들어 에이전트를 다시 연결합니다.

### COMMAND_UNKNOWN

- 원인: 중앙 서버 또는 에이전트가 모르는 명령입니다.
- 확인: 명령 기록에서 `command` 값을 봅니다.
- 조치: 화면의 버튼을 사용하거나 지원 명령만 호출합니다.

### COMMAND_CONFIRM_REQUIRED

- 원인: 위험 명령에 확인값이 빠졌습니다.
- 확인: 서버 끄기, 재시작, 백업, OP, 킥 같은 명령인지 확인합니다.
- 조치: 확인창에서 승인한 뒤 다시 실행합니다.

### CHAT_EMPTY

- 원인: 채팅 메시지가 비어 있습니다.
- 조치: 1자 이상 입력합니다.

### CHAT_TOO_LONG

- 원인: 채팅 메시지가 180자를 넘었습니다.
- 조치: 메시지를 나누어 보냅니다.

### RCON_COMMAND_EMPTY

- 원인: 직접 RCON 명령 입력란이 비어 있습니다.
- 조치: 예를 들어 `list`, `say 안녕하세요`, `whitelist add player`처럼 입력합니다.

### RCON_ALLOWLIST_BLOCKED

- 원인: 기본 allowlist에 없는 RCON 명령입니다.
- 확인: 명령이 위험하거나 서버 설정을 크게 바꾸는 명령인지 봅니다.
- 조치: 쉬운 명령 버튼을 우선 사용합니다. 정말 필요할 때만 서버 환경변수 `DASHBOARD_ALLOW_UNSAFE_RCON_COMMANDS=true`를 설정합니다.

### AGENT_NOT_CONNECTED

- 원인: 사용자 PC 에이전트가 중앙 서버 WebSocket에 연결되어 있지 않습니다.
- 확인:
  - 사용자 PC에서 에이전트 Python 프로세스가 실행 중인지 확인합니다.
  - 에이전트 설정의 `central_url`, `server_id`, `agent_token`을 확인합니다.
  - PC 인터넷 연결과 방화벽을 확인합니다.
- 조치: 에이전트를 재시작합니다. 토큰이 꼬였으면 새 등록 코드로 다시 페어링합니다.

### AGENT_COMMAND_FAILED

- 원인: 에이전트가 명령 처리 중 예외를 반환했습니다.
- 확인: 명령 기록의 메시지와 에이전트 로그를 봅니다.
- 조치: 아래 세부 RCON/설정 코드를 같이 확인합니다.

### AGENT_SETTINGS_UNSUPPORTED

- 원인: 해당 서버가 원격 설정 저장을 지원하지 않습니다.
- 확인: 서버가 `local-pi`인지, 에이전트 버전이 오래됐는지 확인합니다.
- 조치: Windows 에이전트를 최신 파일로 실행합니다.

### AGENT_RCON_PASSWORD_MISSING

- 원인: 에이전트 PC에 RCON 비밀번호가 설정되어 있지 않습니다.
- 확인:
  - 에이전트 설정 파일에 `rcon_password`가 있는지 확인합니다.
  - 또는 `MINECRAFT_RCON_PASSWORD` 환경변수가 있는지 확인합니다.
- 조치: `server.properties`의 `rcon.password`와 같은 값을 에이전트 로컬 설정에 넣습니다. 중앙 서버에는 저장하지 않습니다.

### AGENT_RCON_AUTH_FAILED

- 원인: RCON 비밀번호가 틀렸습니다.
- 확인: `server.properties`의 `rcon.password`와 에이전트 설정값을 비교합니다.
- 조치: 값을 맞춘 뒤 Minecraft 서버를 재시작합니다.

### AGENT_RCON_CONNECT_FAILED

- 원인: RCON 포트에 연결할 수 없습니다.
- 확인:
  - Minecraft 서버가 켜져 있는지 봅니다.
  - `server.properties`에 `enable-rcon=true`인지 확인합니다.
  - `rcon.port`와 설정 화면의 RCON 포트가 같은지 확인합니다.
  - Windows 방화벽 또는 백신이 로컬 연결을 막는지 확인합니다.
- 조치: 설정을 맞추고 서버를 재시작한 뒤 `접속자 보기` 또는 `RCON list`를 실행합니다.

### AGENT_CONFIG_INVALID

- 원인: 설정 화면에서 저장한 값의 형식이 올바르지 않습니다.
- 확인:
  - 포트는 1-65535 범위입니다.
  - 상태 갱신 주기는 10-3600초입니다.
  - 재시작 대기는 1-120초입니다.
  - 서버 폴더는 실제 존재하는 Minecraft 폴더여야 합니다.
- 조치: 값을 고친 뒤 다시 저장합니다.

## 장애별 빠른 조치

### 서버 켜기가 실패할 때

1. 설정 화면에서 `서버 폴더`가 `paper.jar`가 있는 폴더인지 확인합니다.
2. `시작 명령`을 확인합니다.
3. Paper가 요구하는 Java 버전을 확인합니다.
4. 사용자 PC에서 같은 명령을 PowerShell로 직접 실행해 봅니다.

### 채팅 보내기가 실패할 때

1. 서버가 켜져 있는지 확인합니다.
2. `RCON 연결 정상` 체크가 통과하는지 봅니다.
3. `AGENT_RCON_PASSWORD_MISSING`, `AGENT_RCON_AUTH_FAILED`, `AGENT_RCON_CONNECT_FAILED` 중 어떤 코드인지 확인합니다.

### 게임 안 채팅이 안 보일 때

1. 설정 화면의 `서버 폴더`가 맞는지 확인합니다.
2. `logs/latest.log`가 생성되는지 확인합니다.
3. 게임 안에서 실제 플레이어가 채팅을 보냈는지 확인합니다.
4. 대시보드에서 채팅 새로고침을 누릅니다.

### 백업이 실패할 때

1. 백업 경로가 존재하거나 생성 가능한지 확인합니다.
2. 디스크 여유 공간을 확인합니다.
3. 백업 대상 폴더가 너무 크면 시간이 오래 걸릴 수 있습니다.

## 운영 메모

- 등록 코드는 30분 후 만료됩니다.
- 에이전트 토큰은 중앙 서버에 해시로만 저장됩니다.
- RCON 비밀번호는 에이전트 PC 로컬에만 둡니다.
- 위험 명령은 확인창과 명령 기록을 남깁니다.
- 문제가 반복되면 명령 기록, 최근 로그, 이 문서의 오류 코드를 함께 확인합니다.