# PC · NAS 공통 서버 운영

LifeOps의 독립 관리 서비스와 공통 웹 설정 방식을 참고하여 AIonique 자체 코드로 구현했습니다. LifeOps 코드·운영 파일을 가져오거나 참조 경로로 연결하지 않습니다.

## 구성과 접속

Windows PC와 Linux NAS 모두 서버 운영을 지원하며 공통 웹 관리 화면은 `/manage/`입니다. 로컬 업데이트의 실행 방법은 운영체제에 따라 구분합니다.

| 구분 | Windows PC 서버 | Linux NAS 서버 |
|---|---|---|
| 서버 관리 | 공통 웹 `/manage/`, Windows 트레이에서 열기 | 공통 웹 `/manage/` |
| 업데이트 | 웹 서버 관리 → 업데이트에서 서버 release 폴더 ZIP 선택, 또는 트레이 → 설정 → 업데이트 / Update-Server.cmd | NAS의 Docker Compose 배포 절차. 웹 업데이트 화면에서 절차 확인 |
| 진행·결과 표시 | 웹에서 시작하면 같은 웹 화면에서 서버·Agent 진행 및 복구 결과 확인. 트레이에서 시작하면 전용 Windows 진행 창 사용 | NAS의 Compose 실행 결과와 웹 Agent 상태 확인 |
| Windows 트레이·PowerShell 창 | 로컬 PC에만 사용. 실행용 콘솔은 숨기고 사용자 진행 창은 표시 | 사용하지 않음 |

PC 브라우저로 NAS를 관리해도 Windows 로컬 업데이터가 NAS를 업데이트하는 것은 아닙니다. Windows의 진행 창을 숨기는 것은 NAS 지원을 위한 동작이 아니며, NAS에 Windows 전용 안내창을 띄우지 않습니다.

서버와 등록 Agent는 같은 릴리스 버전으로 관리합니다. Windows는 진행 창에서 서버 적용 이후 Agent 적용·재연결·실행 확인까지 기다려 전체가 준비된 뒤에만 완료를 표시합니다. NAS는 Compose로 새 서버를 배포하면 같은 Agent 동기화를 시작하고 웹 상단에서 전체 진행·미완료 PC·전체 완료를 확인합니다. Compose 시작 성공과 서버 자체 건강 응답은 Agent 적용 완료를 뜻하지 않으며 `/health`의 `update_ready`를 따로 제공합니다. 오프라인·실패 대상은 미완료로 남기고 자동 대기는 재연결까지 보존합니다. 최대 15분의 초기 대기 후에도 미완료를 성공으로 바꾸지 않으며 준비된 PC부터 사용할 수 있습니다.

`compose.yaml`은 Gateway, 독립 operator, HTTPS Caddy를 실행합니다. NAS에는 Windows 트레이·PowerShell·Multipass가 필요하지 않습니다. 추론 PC의 Agent는 기존 Windows 서비스이며 NAS에서 실행할 필요가 없습니다.

기존 Windows 설치는 새 소스/배포본을 적용한 뒤 Compose에 operator가 포함되어야 합니다. 소스만 수정한 상태에서는 이미 실행 중인 서버가 자동 변경되지 않습니다. 같은 인스턴스 ID·프로젝트 이름·state 볼륨·암호화 키를 유지하고 기존 운영 업데이트 절차를 사용하세요. Gateway와 operator는 같은 이미지 태그를 사용합니다.

접속 주소는 기존 HTTPS 주소의 `/manage/`입니다. 메인관리자 계정으로 로그인하면 서버를 중지한 뒤에도 같은 주소에서 시작할 수 있습니다. NAS 브라우저와 PC 트레이가 같은 화면과 관리 API를 사용합니다. Docker 엔진 또는 HTTPS·operator 자체가 꺼진 경우에는 NAS Container Manager나 PC 실행 환경에서 먼저 시작해야 합니다.

## 새 Linux NAS 인스턴스 준비 예시

Docker Engine과 Compose v2가 준비되어 있어야 합니다. 기존 운영 폴더에 초기화 명령을 실행하지 마세요. 소스를 NAS의 별도 프로그램 폴더에 복사한 뒤, 일회성 초기화에는 Python 3과 cryptography가 설치된 환경을 사용합니다.

```sh
python3 tools/bootstrap.py --root /volume1/aionique --host 192.0.2.10 --port 8443
docker compose --env-file /volume1/aionique/deploy.env config --quiet
docker compose --env-file /volume1/aionique/deploy.env up -d --build
```

`192.0.2.10`은 실제 NAS 주소로 바꿉니다. `/volume1/aionique` 역시 실제 저장소의 새 폴더로 바꿉니다. 초기화가 만든 인증기관 인증서 `certs/ca.crt`를 접속 PC에서 신뢰하도록 설치하고, 초기 관리자 안내는 README를 따릅니다. 초기화에는 NAS의 시스템 폴더가 아닌 앱 전용 폴더를 사용하세요. 기존 계정·키를 계속 사용할 때는 기존 state 볼륨과 secrets를 그대로 연결해야 합니다.

## 추론 PC의 엔진 포트 접속 제한

Windows Agent 설치 시 Ollama·Strata 포트를 서버 PC IP로만 제한할지 확인합니다. 동의하면 해당 Agent PC의 엔진 포트에 서버 IP와 로컬 연결만 허용합니다. 서버 웹 접속 IP 설정은 제공하지 않으며 PC 등록·등록 URL 재발급은 서버 HTTPS 방화벽을 변경하지 않습니다. 기존 OS 방화벽·회사 정책·라우터 설정은 별도입니다.

## 경로 지정

Compose 초기 경로는 `AIONIQUE_ROOT` 아래의 documents, Resource, logs, backups입니다. 첫 배포부터 별도 폴더를 사용할 경우 deploy.env에 `AIONIQUE_DOCUMENTS_PATH`, `AIONIQUE_RESOURCE_PATH`, `AIONIQUE_LOGS_PATH`, `AIONIQUE_BACKUPS_PATH`를 지정할 수 있습니다. 지정하지 않으면 기존 기본값을 사용합니다.

웹에서는 Docker **데몬이 실행되는 호스트** 기준의 절대 경로를 입력합니다. NAS는 `/volume1/...` 같은 경로, Docker Desktop은 Linux 엔진에 보이는 `/run/desktop/mnt/host/c/...` 같은 경로를 사용합니다. 전용 Multipass 환경에서는 VM 내부의 `/opt/...` 경로입니다. 브라우저가 실행되는 PC의 `C:\...` 경로나 네트워크 공유 주소를 그대로 입력하지 않습니다. 공유 폴더는 Docker 호스트에 먼저 마운트합니다.

대상 폴더는 미리 만들고 필요한 데이터를 준비합니다. 새 경로 지정은 복사·이동 작업이 아닙니다. 자료 폴더는 읽기 권한, 리소스·로그·백업 폴더는 컨테이너 UID 10001의 쓰기 권한이 필요합니다. 서로 같은 경로나 포함 관계인 경로는 거절합니다. 없는 호스트 폴더를 Docker가 임의로 생성하지 않도록 설정했습니다. 새 경로를 적용한 뒤 필요하면 기존 자료 색인 화면에서 다시 색인합니다.

웹 설정은 operator 전용 볼륨에 저장합니다. Gateway 데이터 볼륨은 변경하지 않습니다. Compose 설정을 내려받아 다음 배포 명령에 마지막 `-f` 파일로 추가하면, operator의 설정 재적용을 기다리는 동안에도 새 경로를 유지합니다. 이 파일에는 호스트 경로와 이미지 태그·자동 시작 여부가 포함되며 비밀번호·키는 포함하지 않습니다.

## 복구와 범위

설정 적용은 이전 컨테이너를 중지하여 보관하고 새 컨테이너를 시작해 건강 상태를 확인합니다. 성공 시 이전 컨테이너만 제거하고 볼륨은 제거하지 않습니다. 실패 또는 적용 중 operator 중단 시 이전 컨테이너를 되돌립니다. 원본 폴더와 새 폴더는 삭제하지 않습니다. 복구 기록을 저장할 디스크 공간도 확보하세요.

수동 중지 상태는 operator가 보존하며 Windows 공유 런타임 감시와 전용 VM의 health guardian도 이를 존중합니다. 운영자가 전체 Compose를 명시적으로 시작하면 일시적으로 Gateway가 시작될 수 있으며 operator가 저장된 중지 의도를 다시 적용합니다.

이번 화면의 범위는 Gateway 시작·중지·재시작·자동 시작·저장 경로·운영 이력입니다. 서버 프로그램 ZIP 설치/업데이트, TLS 인증서 발급·갱신, 공개 포트 변경은 기존 배포 절차를 사용합니다. Windows Agent의 서비스·Windows 방화벽·자동 로그인 트레이 기능은 추론 PC의 운영체제 기능입니다. 이를 NAS의 로컬 기능으로 실행하지 않습니다. 원격 Agent의 모델·사용자·키·색인·업데이트 관리는 기존 웹 서버 관리에서 계속 사용합니다.

## HTTPS 우선 접속과 복구

Gateway PC 트레이는 기존 HTTPS 주소의 `/manage/health`를 먼저 확인하고 정상이라면 `/manage/`를 엽니다. 통신 실패 시 같은 PC의 `https://localhost:<기존 포트>/manage/`를 엽니다. 인증서 신뢰는 기존 설치의 CA를 사용하며 검증을 끄지 않습니다. 이 경로도 Caddy·operator가 필요하므로 PC 전원·Docker·Caddy 자체 장애는 주소 전환으로 해결하지 못합니다. 401·403은 연결 장애가 아니므로 기본 주소에서 인증합니다.

NAS에서는 메인관리자가 **서버 설정 → 복구 접속**에 기본 주소와 독립적으로 접근할 수 있는 HTTPS 관리 주소를 등록합니다. NAS의 별도 리버스 프록시나 복구 네트워크가 같은 operator의 `/manage/`로 연결되도록 먼저 구성하고 인증서 신뢰도 준비하세요. 등록한 주소를 직접 열어 메인관리자로 로그인한 뒤 **이 복구 주소에서 접속 확인**을 눌러야 자동 전환에 사용됩니다. 주소를 변경하면 다시 확인해야 합니다. NAS 구축 전에는 미등록 안내를 유지합니다. 외부 인터넷에서도 복구하려면 주 접속 경로와 별도로 접근 가능한 경로가 필요합니다. LAN 주소는 같은 LAN 또는 별도 VPN에서만 사용할 수 있습니다.

확인 완료 주소는 초록색과 기본 접힘, 미확인 상태는 빨간색과 기본 펼침으로 표시합니다. 서버 설정 상위 영역은 기본 접힘입니다. 이미 열린 화면은 확인된 주소를 현재 탭에 보관하고 연속 3회 통신 실패 시 복구 주소로 이동합니다. 로그인·권한 거부는 전환하지 않고 보관한 주소를 지웁니다. 비밀번호·세션·CSRF 값은 다른 주소로 전달하지 않으며 복구 주소에서 다시 로그인합니다. 원격 브라우저는 접속 기기 자신의 localhost로 이동하지 않습니다.

**관리 접속 파일 저장**으로 받은 `AIonique-Management.html`은 로그인 정보 없이 기본·복구 주소만 포함합니다. 접속할 PC에 보관하세요. 기본 페이지가 처음부터 열리지 않으면 그 페이지 안의 코드는 실행되지 않으므로, 저장한 파일이 HTTPS 상태를 확인하여 처음부터 접속 경로를 고릅니다. HTTPS를 직접 입력한 브라우저 오류 화면에서 자동 전환되는 것은 아닙니다.

## 트레이 메뉴

Gateway 메뉴는 웹 열기, 서버 제어(시작·중지·재시작), 설정(서버 설정·업데이트), 도움말(사용 설명서·변경 이력·버전 정보), 종료입니다. 서버 제어는 같은 웹 관리 화면에서 메인관리자 인증 후 실행합니다. 종료는 Windows 관리자 승인 후 기존 독립 operator 작업 큐로 Gateway만 중지하고 성공 시 트레이를 닫습니다. HTTPS·operator와 다른 앱·추론 PC는 중지하지 않습니다. 구형 operator 미설치 인스턴스는 기존 로컬 관리 절차를 사용하므로 최신 설치 전환을 먼저 완료하세요.

Windows 프로그램 ZIP 업데이트는 설정 하위의 기존 업데이트 도구를 사용합니다. NAS의 업데이트는 기존 Compose 배포 절차를 사용하며 이번 화면에 웹 ZIP 업로더를 추가한 것은 아닙니다. AIonique는 Tailscale을 내장·관리하지 않으므로 LifeOps의 Tailscale 인증 상태나 인증키를 공유하지 않습니다. Agent 메뉴의 별도 Windows 서비스·포트 설정과 트레이 닫기는 유지합니다.

서버 PC의 localhost 관리 주소에서 접속 파일을 저장하면 현재 PC용 HTTPS localhost 복구를 포함합니다. 이 파일은 해당 PC에서만 사용하고 다른 PC·NAS용으로 배포하지 마세요. 원격 브라우저에는 확인된 서버 복구 주소가 없으면 다운로드가 허용되지 않습니다.

Gateway·Agent 트레이는 웹과 동일한 공식 AIonique 로고를 사용하며, 오른쪽 아래 작은 G/A 배지와 툴팁의 Gateway/Agent 문구로 역할을 구분합니다. Windows 화면 배율에 따라 아이콘 크기를 선택합니다.