데이터 손실 없이 홈 서버에서 Hermes 에이전트 실행하는 방법

간단한 답변

데이터 손실 없이 홈 서버에서 Hermes Agent를 실행하려면, 설정, 스킬, 로그, 생성된 파일, 게이트웨이 설정이 컨테이너 내부 파일 시스템에만 의존하지 마세요. 먼저 영구 호스트 폴더나 Docker 볼륨을 계획하고, 앱이 실제 사용하는 컨테이너 경로에 마운트하며, 파일 소유권을 확인하고, 재시작 또는 재구성 후에도 데이터가 존재하는지 검증하세요. 이 글은 볼륨 마운트, 권한, 경로 매핑 문제로 인해 컨테이너가 폴더를 찾지 못하는 일반적인 실패 패턴에 초점을 맞춥니다.

가장 안전한 초보자 작업 흐름은 다음과 같습니다:

1. 어떤 Hermes Agent 데이터가 유지되어야 하는지 파악하세요.
2. 전용 호스트 폴더나 Docker 관리 볼륨을 선택하세요.
3. 그 저장소를 올바른 컨테이너 경로에 매핑하세요.
4. 앱 사용자가 해당 위치에 쓸 수 있는지 확인하세요.
5. 업데이트나 재구성 전에 중요한 설정을 백업하세요.
6. 재시작 후에도 설정, 로그, 생성된 파일, 게이트웨이 설정이 여전히 존재하는지 확인하세요.

실행 중인 컨테이너가 있다고 해서 데이터가 안전한 것은 아닙니다. 데이터는 올바른 사용자가 쓸 수 있는 영구 위치에 저장되고, 필요 시 백업되며, 재시작 후 검증될 때만 안전합니다.

컨테이너 환경에서 Hermes Agent 데이터가 사라질 수 있는 이유

컨테이너화된 앱은 시작과 교체가 쉽습니다. 이는 업데이트, 테스트, 복구에 유용하지만, 일회용 컨테이너 레이어에만 저장된 데이터는 컨테이너가 제거, 재생성, 재구성될 때 손실될 수 있습니다.

셀프 호스팅 AI 에이전트의 경우, 기본 설정 이상의 영향을 받을 수 있습니다. 에이전트 사용 방식에 따라 모델 구성, 스킬, 생성된 파일, 로그, 메시징 게이트웨이 설정 및 기타 앱 상태가 중요할 수 있습니다.

컨테이너 재시작과 영구 앱 데이터

일반적인 컨테이너 재시작은 항상 데이터를 제거하지 않습니다. 데이터가 영구 볼륨이나 올바르게 매핑된 호스트 폴더에 저장되어 있다면 재시작 후에도 데이터가 유지되어야 합니다.

중요한 파일이 컨테이너의 쓰기 가능한 레이어에만 존재할 때 위험이 발생합니다. 이 레이어는 계획된 영구 데이터 위치와 다릅니다. 올바른 경로를 보존하거나 다시 마운트하지 않고 컨테이너를 재생성하면 앱이 새로 시작되거나 이전 파일을 찾지 못할 수 있습니다.

컨테이너 삭제 또는 재생성이 저장되지 않은 상태를 제거할 수 있는 이유

컨테이너 삭제 또는 재생성은 재시작과 다릅니다. 재생성된 컨테이너는 새로운 내부 파일 시스템, 새로운 환경 변수, 또는 다른 마운트 매핑을 사용할 수 있습니다.

Hermes Agent 설정, 스킬, 로그 또는 생성된 출력물이 영구 호스트 폴더나 볼륨에 저장되지 않았다면, 새 컨테이너로 이어지지 않을 수 있습니다. 이 때문에 “어제는 앱이 잘 작동했는데”와 “업데이트 후 앱이 초기화되었다”가 모두 사실일 수 있습니다.

앱 데이터가 어디에 저장되는지 확인하지 않았다면, 컨테이너 교체를 데이터 위험 이벤트로 간주하는 것이 안전한 습관입니다.

호스트 경로와 컨테이너 경로를 먼저 계획해야 하는 이유

호스트 경로는 홈 서버에서 데이터가 위치한 곳입니다. 컨테이너 경로는 컨테이너 내부에서 앱이 그 데이터를 보는 위치입니다. 볼륨 마운트 또는 바인드 마운트가 이 두 세계를 연결합니다.

호스트 경로가 올바르지만 잘못된 컨테이너 경로에 마운트되면, 앱은 폴더가 존재하지 않는 것처럼 동작할 수 있습니다. 컨테이너 경로가 올바르지만 호스트 경로가 일회용이라면, 앱은 의도하지 않은 곳에 데이터를 쓸 수 있습니다.

앱을 실행하기 전에 매핑을 계획하세요, 데이터 손실 후가 아닙니다.

Hermes 에이전트를 실행하기 전에 어떤 데이터를 보호해야 할까요?

컨테이너를 변경하거나 이미지를 업데이트하거나 게이트웨이를 재구성하기 전에 재생성이 어려운 데이터를 목록화하세요. 모든 파일이 같은 보호가 필요한 것은 아니지만, 어떤 파일이 중요한지 알아야 합니다.

유용한 규칙은 신원, 접근, 구성, 학습된 워크플로우 또는 쉽게 재생성할 수 없는 출력을 저장하는 모든 것을 보호하는 것입니다.

에이전트 구성 및 모델 공급자 설정

모델 설정에는 보통 공급자 선택, 엔드포인트 값, 모델 이름, 컨텍스트 관련 옵션, API 접근이 포함됩니다. 이 설정이 손실되면 에이전트가 시작은 되지만 올바르게 응답하지 못할 수 있습니다.

모델 구성을 일회성 셸 세션이 아닌 지속적인 앱 데이터 경로에 저장하세요. 환경 변수로 구성이 제공된다면, compose 파일, env 파일 또는 배포 노트의 안전한 복사본을 보관하세요.

에이전트가 터미널 도구나 메시징 게이트웨이를 사용하는 방식을 결정하는 설정 선택도 보호하세요.

앱 메모리, 세션, 기술 및 런타임 상태

Hermes 에이전트 데이터는 하나 이상의 구성 파일을 포함할 수 있습니다. Hermes 기술 데이터 구조는 기술이 ~/.hermes/skills/에 위치하며, 이는 번들, 허브 설치, 에이전트 생성 기술의 주요 진실 소스임을 설명합니다. 또한 번들 매니페스트, 기술 번들, 허브 탭 구성, 대기 중인 기술 쓰기, 구성 설정과 같은 관련 상태도 설명합니다.

이것이 중요한 이유는 에이전트가 생성한 기술이 재사용 가능한 절차적 기억이 될 수 있기 때문입니다. 잘못된 경로가 마운트되면 설정뿐 아니라 에이전트가 학습한 워크플로우나 설치한 기술도 잃을 수 있습니다.

기술, 번들, 대기 중인 쓰기, 프로필 관련 상태를 지속적인 에이전트 데이터로 취급하세요.

다운로드, 생성된 파일, 로그 및 도구 출력

생성된 파일은 쉽게 간과될 수 있습니다. 에이전트는 정상 사용 중에 계획, 스크립트, 보고서, 스크린샷, 로그 또는 다운로드된 파일을 생성할 수 있습니다.

이 파일들은 활성 작업 공간, 백엔드 작업 디렉터리, 앱 홈 디렉터리 또는 마운트된 출력 경로에 저장될 수 있습니다. 만약 그 위치가 컨테이너 내부에만 있다면, 컨테이너가 제거될 때 파일이 사라질 수 있습니다.

실용적인 사용을 위해 생성된 파일이 호스트 서버의 어디에 나타나야 하는지 결정하고 컨테이너가 그 위치에 쓰는지 확인하세요.

API 키, 봇 토큰, 환경 변수

비밀은 일반 앱 데이터가 아닙니다. API 키, 봇 토큰, 대시보드 비밀번호, 환경 변수는 지속성과 보호가 모두 필요합니다.

비밀을 무작위 생성 출력 폴더나 넓게 공유된 디렉터리에 저장하지 마세요. 제한된 접근 권한이 있는 제어된 설정 경로에 보관하세요.

좋은 비밀 관리 설정은 다음 질문에 답해야 합니다:

• 비밀이 어디에 저장되는지
• 어떤 사용자가 읽을 수 있는지
• 백업에 포함되는지 여부
• 백업이 암호화되었는지 또는 접근 제어가 있는지
• 비밀이 노출되었을 때 어떻게 교체할 수 있는지

호스트 경로 vs 컨테이너 경로 vs 볼륨 마운트

이것이 대부분의 “컨테이너가 폴더를 찾을 수 없음” 및 “재시작 후 데이터 사라짐” 문제의 핵심 개념입니다. 컨테이너는 자체 파일 시스템 내에 있거나 마운트된 것만 볼 수 있습니다.

문제 해결 전에 에이전트 데이터 생존 지도를 사용해 설정을 정리하세요.

프레임워크 모듈	핵심 질문	결정에 도움을 주는 것	설정 / 문제 해결 집중
데이터 목록	컨테이너 재시작 또는 재생성 후에도 유지되어야 하는 데이터는 무엇인가?	보호가 필요한 설정, 기술, 로그, 다운로드, 토큰, 생성 파일	중요한 에이전트 데이터를 일시적 상태로 취급하지 않도록 방지
지속 경로	지속 데이터가 호스트 어디에 저장되어야 하는가?	전용 호스트 폴더, Docker 볼륨, 바인드 마운트 중 어느 것을 사용할지	컨테이너 재생성 후 데이터 초기화 방지
마운트 매핑	호스트 경로가 컨테이너 경로에 올바르게 매핑되었는가?	앱이 의도한 폴더를 실제로 볼 수 있는지 여부	누락된 폴더 및 잘못된 대상 경로 오류 진단 도움
권한 경계	마운트된 데이터의 소유자와 데이터를 쓰는 사용자는 누구인가?	호스트 사용자, 컨테이너 사용자, 앱 사용자, 루트 중 누가 파일을 소유하는지	모든 파일을 루트 소유로 만들지 않고 권한 거부 문제 해결 도움
백업 경계	업데이트나 재구성 전에 무엇을 백업해야 하는가?	어떤 데이터가 중요하고 어떤 데이터가 임시인지	설정, 기술, 세션, 토큰, 게이트웨이 설정 손실 방지
재시작 검증	재시작 또는 업데이트 후에도 데이터가 존재하는가?	설정이 실제로 내구성이 있는지 여부	“실행 중” 상태를 반복 가능한 안전 점검으로 전환

호스트 서버가 저장하는 것

호스트 서버는 실제 폴더, 디스크, Docker가 관리하는 저장 위치를 저장합니다. 바인드 마운트를 사용하면 특정 호스트 폴더를 선택합니다. 명명된 Docker 볼륨을 사용하면 Docker가 저장 위치를 선택하고 관리합니다.

이 구분은 호스트 가시성이 백업과 마이그레이션에 영향을 미치기 때문에 중요합니다. 바인드 마운트된 폴더는 초보자가 찾고 복사하기 더 쉬울 수 있습니다. 명명된 볼륨은 Docker가 관리하는 앱 데이터에 더 깔끔할 수 있지만, 검사하거나 백업하는 방법을 알아야 합니다.

사람이 읽을 수 있는 호스트 폴더, Docker가 관리하는 앱 지속성, 또는 제어된 백업 경로 중 필요한 저장 방식을 선택하세요.

컨테이너가 볼 수 있는 것

컨테이너는 자체 내부 파일 시스템과 마운트된 경로만 볼 수 있습니다. 홈 서버의 모든 폴더를 자동으로 볼 수는 없습니다.

Docker의 바인드 마운트 안내서는 호스트 디렉터리가 컨테이너 내 대상 경로에 어떻게 나타나는지, 마운트가 올바를 때 호스트와 컨테이너 간 파일 변경이 어떻게 반영되는지 보여줍니다.

핵심은 이겁니다: 앱은 파일이 호스트 어디에 있든 상관하지 않습니다. 단, 그 파일이 앱이 사용하는 경로에 마운트되어 있어야 합니다.

볼륨 마운트가 앱 데이터를 영구적으로 유지하는 방법

영구 마운트는 앱에 단일 컨테이너 수명 이상으로 데이터를 쓸 안정적인 장소를 제공합니다. 앱 데이터의 경우, 이는 “재시작 안전”과 “컨테이너 수명 한정”의 차이입니다.

마운트는 앱이 기대하는 데이터 경로와 일치해야 합니다. 앱이 내부 폴더 하나에 쓰는데 다른 폴더를 마운트하면 데이터가 일회성 저장소에 저장될 수 있습니다.

좋은 영구 설정은 다음을 정의해야 합니다:

• 호스트 폴더인지 명명된 볼륨인지,
• 컨테이너 대상 경로;
• 마운트가 읽기-쓰기인지 읽기 전용인지,
• 어떤 앱 데이터가 그곳에 속하는지,
• 경로가 어떻게 백업될지,

잘못된 경로 매핑이 폴더 없음 오류를 일으키는 이유

잘못된 매핑은 종종 폴더가 없다는 문제처럼 보입니다. 폴더가 호스트에 존재하지만 컨테이너가 볼 수 없거나, 컨테이너에 예상 경로에 폴더가 있지만 의도한 호스트 폴더와 연결되지 않은 경우입니다.

일반적인 증상은 다음과 같습니다:

• 앱에서 폴더가 존재하지 않는다고 표시하는 경우;
• 생성된 파일이 컨테이너 내부에는 있지만 호스트에는 없는 경우;
• 컨테이너 재구성 후 로그가 사라지는 경우;
• 업데이트 후 설정이 초기화되는 경우;
• 호스트 폴더를 수정했는데 앱이 여전히 이전 설정을 사용하는 경우;
• 백업 스크립트가 실행되지만 실제 앱 데이터는 포함하지 않는 경우;

이런 문제가 발생하면 호스트 경로와 컨테이너 경로를 함께 확인하세요. 한쪽만 검사하지 마세요.

데이터 손실 없이 Hermes Agent 실행하는 방법

목표는 단순히 Hermes Agent를 시작하는 것이 아닙니다. 중요한 데이터가 재시작, 업데이트, 재구성 후에도 유지되도록 하는 것입니다.

1단계: 전용 호스트 데이터 폴더 선택하기

컨테이너를 실행하거나 재구성하기 전에 호스트 데이터 폴더를 선택하세요. 식별하기 쉽고 백업하기 쉬우며 관련 없는 개인 파일과 섞이지 않아야 합니다.

전용 폴더는 앱에 속한 파일을 쉽게 확인할 수 있어 위험을 줄여줍니다. 또한 전체 홈 디렉터리나 다른 민감한 폴더를 컨테이너에 마운트하는 것을 피할 수 있습니다.

실용적인 호스트 데이터 폴더는 다음과 같아야 합니다:

• 앱에 특화된 폴더여야 합니다;
• 일회성 다운로드 경로 외부에 두세요;
• 백업 계획에 포함하세요;
• 관련 없는 서비스와 널리 공유하지 마세요;
• 접근이 필요한 사용자나 서비스만 쓸 수 있도록 설정하세요.

2단계: 데이터 폴더를 컨테이너에 마운트하기

호스트 데이터 폴더를 앱이 기대하는 컨테이너 경로에 마운트하세요. 이 순간에 많은 데이터 손실 문제가 발생하거나 예방됩니다.

바인드 마운트의 경우, 호스트 경로는 사용자가 선택하며 대상 경로는 컨테이너 내부에 나타나는 위치입니다. 명명된 볼륨의 경우, Docker가 호스트 측 위치를 관리합니다.

앱이 자동으로 마운트된 폴더를 사용할 것이라고 가정하지 마세요. 마운트된 대상이 실제 앱 데이터 경로와 일치하는지 확인하세요.

3단계: 컨테이너가 예상한 앱 데이터 경로를 사용하는지 확인하기

마운트 후 컨테이너 내부에서 경로를 확인하세요. 폴더가 호스트에 존재해도 올바르게 마운트되지 않으면 앱에서 보이지 않을 수 있습니다.

가장 간단한 검증은 한 쪽에서 무해한 테스트 파일을 생성하거나 찾고, 다른 쪽에서 나타나는지 확인하는 것입니다. 그런 다음 앱이 실제 설정, 로그, 생성 파일을 같은 지속 경로에 쓰는지 확인하세요.

이 단계는 업데이트나 마이그레이션 전에 특히 중요합니다.

4단계: 파일 소유권과 쓰기 권한 확인하기

올바른 마운트라도 앱이 쓸 수 없으면 실패할 수 있습니다. 권한 오류는 보통 파일이 root에 의해 생성되고 앱이 나중에 다른 사용자로 실행될 때 발생합니다.

권한을 광범위하게 변경하기 전에 소유권을 확인하세요. 올바른 해결책은 보통 특정 앱 데이터 폴더를 해당 앱 사용자가 읽고 쓸 수 있게 하는 것이지, 모든 프로세스에 호스트 디렉터리에 대한 전체 권한을 주는 것이 아닙니다.

권한 거부가 발생하면 다음을 확인하세요:

1. 마운트된 호스트 경로;
2. 컨테이너 대상 경로;
3. 앱을 실행하는 사용자;
4. 파일 소유자;
5. 마운트가 읽기 전용인지 확인하세요;
6. 백업 또는 내보내기 경로가 쓰기 가능한지도 확인하세요.

5단계: 비밀 정보와 설정 파일을 일회용 경로 밖에 보관하기

비밀 정보와 설정 파일은 임시 폴더, 생성된 출력 디렉터리, 임의의 셸 기록에만 존재해서는 안 됩니다. 환경 변수를 사용한다면 배포 파일이나 env 파일을 통제된 지속 위치에 보관하세요.

비밀 정보와 로그 또는 생성된 산출물을 섞지 마세요. 로그는 문제 해결을 위해 공유될 수 있지만, 비밀 정보는 절대 무심코 공유해서는 안 됩니다.

비밀 정보를 백업한다면 백업을 보호하세요. API 키나 봇 토큰이 노출되는 백업은 다른 종류의 위험을 만듭니다.

6단계: 컨테이너를 재시작하고 데이터가 여전히 존재하는지 확인하기

설정 후 컨테이너를 재시작하고 중요한 데이터가 남아 있는지 확인하세요. 이것이 지속성에 대한 가장 실용적인 테스트입니다.

“컨테이너가 시작된다”는 것에 멈추지 마세요. 다음을 확인하세요:

• 모델 설정이 여전히 존재합니다;
• 스킬이나 앱 상태가 계속 보입니다;
• 로그가 예상된 위치에 계속 기록됩니다;
• 생성된 파일이 호스트에 나타납니다;
• 게이트웨이나 봇 설정이 여전히 작동합니다;
• 백업 파일을 찾을 수 있습니다.

재시작 검증을 통과한 설정이 처음 설치만 통과한 설정보다 훨씬 안전합니다.

권한, 백업, 그리고 안전 경계

데이터 안전성은 누가 쓸 수 있는지, 무엇이 백업되는지, 에이전트가 무엇에 접근할 수 있는지 세 가지 경계에 달려 있습니다. 이러한 경계는 파일 생성, 워크플로우 수정, 도구와의 상호작용이 가능한 셀프 호스팅 에이전트에 특히 중요합니다.

컨테이너 사용자 권한이 중요한 이유

컨테이너 사용자 권한은 앱이 데이터를 읽고 쓸 수 있는지를 결정합니다. 앱이 한 사용자로 실행되지만 마운트된 폴더가 다른 사용자 소유인 경우 쓰기 작업이 실패할 수 있습니다.

이것이 루트로 설정 명령을 실행하면 나중에 문제가 생길 수 있는 이유입니다. 루트는 파일을 성공적으로 생성할 수 있지만 일반 앱 사용자는 이를 수정하지 못할 수 있습니다.

앱 데이터 폴더 수준에서 권한을 수정하세요. 관련 없는 호스트 파일에 대한 광범위한 권한 변경은 피하세요.

모든 작업을 루트로 실행하지 말아야 하는 이유

루트는 많은 제한을 우회할 수 있지만, 그렇다고 안전한 기본값은 아닙니다. 모든 작업을 루트로 실행하면 루트 소유 파일이 생성되고 권한 문제가 숨겨지며 앱에 불필요한 접근 권한이 부여될 수 있습니다.

대부분의 자체 호스팅 앱 워크플로우에서는 루트 권한을 특정 관리 작업에만 사용해야 합니다. 가능한 경우 일상적인 앱 구성은 의도된 앱 또는 컨테이너 사용자로 실행하세요.

더 안전한 패턴은 최소 권한 부여입니다: 앱이 필요한 폴더에만 쓰기 권한을 부여하세요.

읽기 전용 마운트 또는 제한된 폴더를 사용해야 할 때

에이전트가 파일을 검사해야 하지만 수정해서는 안 될 때는 읽기 전용 마운트를 사용하세요. 에이전트가 출력을 생성해야 하지만 광범위한 개인 또는 시스템 디렉터리를 건드리지 않아야 할 때는 제한된 쓰기 가능한 폴더를 사용하세요.

이는 특히 에이전트가 모든 서버 파일에 쓰기 권한을 주지 않고 보고서, 계획 또는 스크립트를 생성하도록 할 때 유용합니다.

제한된 폴더 설계는 실수의 영향을 줄여줍니다. 또한 어떤 폴더가 앱 상태를 포함하고 어떤 폴더가 생성된 출력을 포함하는지 알기 때문에 백업이 더 쉬워집니다.

업데이트 또는 재구성 전에 에이전트 데이터를 백업하는 방법

컨테이너 이미지, 마운트 경로, 게이트웨이 설정 또는 프로필을 변경하기 전에 중요한 앱 데이터를 백업하세요. 백업은 포함된 내용과 복원 방법을 알고 있을 때만 유용합니다.

Docker 커뮤니티 볼륨 백업 권한 토론에서는 일반적인 사용자 실패 패턴을 보여줍니다: 경로가 존재해도 권한, 소유권, 라벨링, 마운트 관련 제한 때문에 백업이나 쓰기 작업이 실패할 수 있습니다.

백업을 생성하는 것뿐만 아니라 백업을 테스트하는 것도 잊지 말라는 알림으로 사용하세요. 백업 계획에는 백업 생성과 복원 검증이 모두 포함되어야 합니다.

일반적인 문제와 해결 방법

Hermes Agent 데이터가 없을 때는 앱을 바로 재설치하지 마세요. 먼저 실패한 레이어를 확인하세요: 데이터 인벤토리, 지속 경로, 마운트 매핑, 권한 경계, 백업 경계, 또는 재시작 검증.

컨테이너가 마운트된 폴더를 찾을 수 없음

이는 보통 한 레이어에는 경로가 존재하지만 다른 레이어에는 없다는 의미입니다. 호스트 폴더가 마운트되지 않았거나, 컨테이너 대상 경로가 잘못되었거나, 앱이 다른 위치를 참조하고 있을 수 있습니다.

다음 순서로 확인하세요:

1. 호스트에 폴더가 존재하는지 확인하세요.
2. 컨테이너에 마운트가 있는지 확인하세요.
3. 컨테이너 내부의 대상 경로를 확인하세요.
4. 앱이 해당 대상 경로를 사용하도록 구성되었는지 확인하세요.
5. 앱 사용자가 폴더를 읽을 수 있는지 확인하세요.
6. 컴포즈 또는 실행 설정 변경 후 마운트가 재생성되었는지 확인하세요.

컨테이너 내부에 임의 폴더를 생성하여 문제를 해결하지 마세요. 이는 오류를 일시적으로 숨길 수 있지만 데이터를 일회용 저장소에 남기게 됩니다.

앱 데이터가 재시작 후 초기화됨

재시작 후 데이터가 초기화된다면, 앱이 영구 경로 대신 컨테이너 내부 파일 시스템에 기록하고 있을 수 있습니다. 또한 예상과 다른 프로필, 환경 변수, 데이터 디렉터리를 사용하고 있을 수도 있습니다.

재시작 전후 데이터 경로가 동일한지 확인하세요. 그리고 해당 폴더가 마운트에 의해 지원되는지 아니면 컨테이너 레이어에만 있는지 점검하세요.

앱이 재생성되었다면 동일한 볼륨 또는 바인드 마운트가 새 컨테이너에 연결되었는지 확인하세요.

데이터 디렉터리에서 권한 거부 오류

권한 거부는 앱이 경로를 볼 수는 있지만 필요한 작업을 수행할 수 없음을 의미합니다. 문제는 소유권, 읽기 전용 마운트 설정, 파일 시스템 라벨, 또는 호스트 사용자와 컨테이너 사용자 간 불일치일 수 있습니다.

가장 작은 검사부터 시작하세요: 앱 사용자가 데이터 디렉터리에 무해한 테스트 파일을 생성할 수 있나요? 그렇지 않다면 해당 경로의 소유자와 권한을 점검하세요.

전체 호스트 디렉터리에 광범위한 쓰기 권한을 부여하여 문제를 해결하지 마세요. 앱 데이터 경로와 의도된 앱 사용자를 수정하세요.

생성된 파일이 컨테이너 내부에만 저장됨

재빌드 후 생성된 파일이 사라진다면, 파일이 컨테이너 내부에 저장되었을 가능성이 큽니다. 이는 앱의 작업 디렉터리나 출력 디렉터리가 매핑되지 않았을 때 자주 발생합니다.

생성된 파일이 저장될 위치를 결정하세요. 그런 다음 해당 출력 폴더를 마운트하거나 앱이 기존 영구 위치에 기록하도록 구성하세요.

경로를 변경한 후 무해한 테스트 파일을 생성하고 호스트에 나타나는지 확인하세요.

봇 또는 게이트웨이 설정이 재구성 후 사라짐

구성이 비영구 경로에 저장되었거나 앱이 재시작 후 다른 프로필로 실행되면 게이트웨이 설정이 사라질 수 있습니다. 환경 변수가 한 곳에서 변경되었지만 실행 중인 컨테이너가 다른 값을 사용하는 경우에도 동일한 문제가 발생할 수 있습니다.

게이트웨이 구성, 봇 토큰 참조, 허용 목록, 대시보드 설정이 예상한 영구 위치에 저장되어 있는지 확인하세요. 그런 다음 게이트웨이를 재시작하고 설정이 유지되는지 확인하세요.

봇이 재시작 전에는 작동하지만 재시작 후 작동하지 않는다면, 토큰을 변경하기 전에 지속성과 환경 구성을 우선 점검하세요.

Hermes 에이전트 데이터가 안전한지 확인하는 방법

안전한 설정은 재시작, 쓰기, 백업 및 접근 검사를 통과해야 합니다. 이 검사들은 복잡할 필요는 없지만 주요 변경 후에는 반복해야 합니다.

재시작 후에도 구성 유지됨

무해한 설정을 변경하고 컨테이너를 재시작한 후 설정이 유지되는지 확인하세요. 이는 앱이 영구 저장소에 기록하고 있음을 확인하는 방법입니다.

설정이 사라지면 더 이상 구성을 추가하지 마십시오. 먼저 데이터 경로를 수정하세요.

로그와 생성된 파일이 예상한 호스트 폴더에 나타남

로그와 생성된 파일은 호스트에서 예상한 위치에 나타나야 합니다. 컨테이너 내부에만 나타난다면 재구성 시 손실될 수 있습니다.

마운트 양쪽을 모두 확인하세요. 호스트와 컨테이너가 중요한 파일에 대해 일치해야 합니다.

에이전트가 권한 오류 없이 앱 데이터에 쓸 수 있음

에이전트는 의도된 사용자로서 앱 데이터 폴더에 쓸 수 있어야 합니다. 단순히 폴더가 존재하는 것보다 쓰기 테스트가 성공하는 것이 더 유용합니다.

재시작 후 로그에서 권한 오류를 주의 깊게 살펴보세요. 일부 권한 문제는 에이전트가 구성 업데이트, 스킬 작성, 생성 파일 저장, 게이트웨이 상태 업데이트를 시도할 때만 나타납니다.

백업 파일을 찾고 복원할 수 있음

백업은 위치를 찾고 테스트 장소에 복원할 수 있을 때까지 완전하지 않습니다. 최소한 백업에 보호하려는 데이터가 포함되어 있는지 확인하세요.

중요한 설정의 경우, 백업에 의존하기 전에 별도의 폴더나 테스트 인스턴스에 복원해 보세요. 이렇게 하면 데이터 손실 후에 복원 문제를 발견하는 일을 피할 수 있습니다.

재부팅 후에도 대시보드나 메시징 접근이 여전히 작동함

재부팅 후에도 대시보드나 메시징 접근이 여전히 작동하는지 확인하세요. 이는 지속 데이터, 자격 증명, 게이트웨이 설정, 네트워크 접근이 여전히 일치함을 확인하는 것입니다.

대시보드는 작동하지만 메시징이 실패하면 게이트웨이 설정과 토큰 접근을 확인하세요. 메시징은 작동하지만 생성된 파일이 사라지면 출력 경로와 마운트를 점검하세요.

실제 홈 서버 환경에서의 작동 방식

실제 홈 서버 설정에서는 시스템이 친숙한 대시보드를 제공하더라도 동일한 데이터 안전 논리가 적용됩니다. 어떤 데이터가 유지되어야 하는지, 어디에 저장되는지, 컨테이너가 어떻게 인식하는지, 어떤 사용자가 쓸 수 있는지, 재시작 후 어떻게 확인하는지 알아야 합니다.

예를 들어, ZimaOS Hermes 에이전트 설정 워크플로우는 모델 제공자 구성, 텔레그램 게이트웨이 설정, Hermes 컨테이너 진입, 앱 환경 활성화, 웹 대시보드 확인, 권한 또는 봇 응답 문제 해결을 포함하는 장치별 경로를 보여줍니다.

Docker 앱, 에이전트 워크플로우, 로컬 서비스를 항상 켜져 있는 소형 기기에서 실행하는 사용자에게 ZimaBoard 2 홈 서버는 지속적인 폴더, 컨테이너 경로, 권한, 저장 공간 확장을 함께 계획해야 하는 경량 홈 서버 환경의 좋은 예입니다. 이것이 유일한 설정은 아니지만, 이 가이드에서 다루는 자체 호스팅 앱 워크플로우 유형과 잘 맞습니다.

일반적인 교훈은 이식 가능하다는 것입니다: 유용한 작업을 위해 컨테이너화된 에이전트를 신뢰하기 전에, 중요한 데이터가 오늘 실행 중인 컨테이너를 넘어 살아남는지 반드시 확인하세요.

자주 묻는 질문(FAQ)

컨테이너를 재시작한 후 Hermes Agent 데이터가 사라진 이유는 무엇인가요?

간단한 재시작은 영구 데이터를 삭제하지 않아야 하지만, 앱이 비영구 컨테이너 경로에 쓰고 있었다면 초기화된 것처럼 보일 수 있습니다. 동일한 볼륨이나 바인드 마운트 없이 컨테이너가 재생성되면 데이터가 사라질 수도 있습니다. 더 많은 설정을 변경하기 전에 호스트 경로, 컨테이너 경로, 실제 앱 데이터 경로를 확인하세요.

Docker 볼륨과 바인드 마운트의 차이점은 무엇인가요?

Docker 볼륨은 Docker가 관리하며, 바인드 마운트는 호스트 폴더를 컨테이너에 매핑합니다. 볼륨은 앱 관리 데이터에 깔끔한 경우가 많고, 바인드 마운트는 호스트에서 직접 위치를 찾기 쉽습니다. 최선의 선택은 Docker 관리 저장소를 원하는지, 백업 및 검사를 위해 보이는 호스트 폴더를 원하는지에 따라 다릅니다.

홈 서버에서 Hermes Agent 앱 데이터를 어디에 저장해야 하나요?

임시 컨테이너 경로 대신 전용 영구 폴더나 Docker 볼륨을 사용하세요. 위치는 백업하기 쉽고, 앱의 필요에 한정되며, 민감하지 않은 다른 파일과 섞이지 않아야 합니다. 가장 중요한 점은 앱이 기대하는 컨테이너 경로가 실제로 그 영구 저장소에 매핑되어야 한다는 것입니다.

왜 컨테이너가 폴더가 없다고 하나요?

호스트에는 폴더가 있지만 컨테이너 내부에는 없을 수 있습니다. 이는 보통 마운트가 생성되지 않았거나, 소스 경로가 잘못되었거나, 대상 경로가 잘못되었거나, 앱이 다른 컨테이너 경로를 참조하고 있기 때문입니다. 무작정 새 폴더를 만들지 말고 호스트 측과 컨테이너 측을 모두 확인하세요.

권한 오류를 피하려면 Hermes Agent를 루트로 실행해야 하나요?

루트(root)로 실행하면 즉각적인 오류가 숨겨질 수 있지만, 루트 소유 파일이 생성되고 위험이 증가할 수 있습니다. 더 안전한 방법은 의도한 앱 사용자가 필요한 앱 데이터 경로만 읽고 쓸 수 있도록 하는 것입니다. 변경 사항을 이해할 때만 특정 관리 또는 수리 작업에 루트를 사용하세요.

Hermes Agent 데이터를 얼마나 자주 백업해야 하나요?

업데이트, 컨테이너 재구성, 경로 변경, 게이트웨이 재설정 또는 다른 서버로의 마이그레이션 전에 백업하세요. 활성 사용 시에는 기술, 설정, 생성된 파일 또는 세션이 변경되는 빈도에 따라 정기적으로 백업 일정을 잡으세요. 파일을 찾고 복원할 수 있음을 확인하기 전까지 백업은 신뢰할 수 없습니다.