빠른 답변
데이터를 잃지 않고 홈 서버에서 Hermes Agent를 실행하려면 설정, 스킬, 로그, 생성된 파일 또는 게이트웨이 설정의 유일한 저장 위치로 컨테이너의 내부 파일 시스템에 의존하지 마세요. 먼저 영구 호스트 폴더나 Docker 볼륨을 준비하고, 앱이 실제로 사용하는 컨테이너 경로에 마운트한 다음, 파일 소유권을 확인하고, 재시작하거나 재설정한 뒤에도 데이터가 남아 있는지 검증하세요. 이 글에서는 볼륨 마운트, 권한 또는 경로 매핑 문제로 인해 컨테이너가 폴더를 찾지 못하는 흔한 오류 패턴을 다룹니다.
초보자에게 가장 안전한 작업 방식은 다음과 같습니다.
- 유지해야 하는 Hermes Agent 데이터를 파악하세요.
- 전용 호스트 폴더나 Docker 관리 볼륨을 선택하세요.
- 해당 저장소를 올바른 컨테이너 경로에 매핑하세요.
- 앱 사용자가 해당 위치에 파일을 쓸 수 있는지 확인하세요.
- 업데이트하거나 다시 빌드하기 전에 중요한 설정을 백업하세요.
- 재시작한 뒤 설정, 로그, 생성된 파일, 게이트웨이 설정이 여전히 있는지 확인하세요.
컨테이너가 실행 중이라고 해서 데이터가 자동으로 안전한 것은 아닙니다. 데이터가 영구 저장 위치에 있고, 올바른 사용자가 쓸 수 있으며, 필요에 따라 백업되고, 재시작 후 검증되어야 안전합니다.
컨테이너 환경에서 Hermes Agent 데이터가 사라질 수 있는 이유
컨테이너화된 앱은 시작하기도, 교체하기도 쉬운 경우가 많습니다. 이는 업데이트, 테스트 및 복구에 유용하지만, 일회용 컨테이너 레이어에만 저장된 데이터는 컨테이너를 제거하거나 다시 만들거나 빌드할 때 사라질 수 있다는 의미이기도 합니다.
셀프 호스팅 AI 에이전트에서는 기본 설정 외에도 영향을 받을 수 있습니다. 에이전트를 사용하는 방식에 따라 모델 설정, 스킬, 생성된 파일, 로그, 메시징 게이트웨이 설정 및 기타 앱 상태가 중요할 수 있습니다.
컨테이너 재시작과 영구 앱 데이터
일반적인 컨테이너 재시작으로 데이터가 항상 삭제되는 것은 아닙니다. 데이터가 영구 볼륨이나 올바르게 매핑된 호스트 폴더에 저장되어 있다면 재시작 후에도 사용할 수 있어야 합니다.
중요한 파일이 컨테이너의 쓰기 가능 레이어에만 저장되어 있으면 위험이 발생합니다. 이 레이어는 계획된 영구 데이터 저장 위치와 다릅니다. 올바른 경로를 보존하거나 다시 마운트하지 않은 채 컨테이너를 새로 만들면 앱이 초기 상태로 시작하거나 이전 파일을 찾지 못할 수 있습니다.
컨테이너를 삭제하거나 다시 만들면 저장되지 않은 상태가 사라질 수 있는 이유
컨테이너를 삭제하거나 다시 만드는 것은 컨테이너를 재시작하는 것과 다릅니다. 새로 만든 컨테이너는 새로운 내부 파일 시스템, 새 환경 변수 또는 다른 마운트 매핑을 사용할 수 있습니다.
Hermes Agent 설정, 스킬, 로그 또는 생성된 출력이 영구 호스트 폴더나 볼륨에 저장된 적이 없다면 새 컨테이너에 그대로 이전되지 않을 수 있습니다. 그래서 “어제는 앱이 작동했는데”와 “업데이트 후 앱이 초기화됐다”가 동시에 사실일 수 있습니다.
안전한 습관은 앱 데이터가 저장된 위치를 확인하기 전까지 컨테이너 교체를 데이터 손실 위험이 있는 작업으로 간주하는 것입니다.
호스트 경로와 컨테이너 경로를 먼저 계획해야 하는 이유
호스트 경로는 홈 서버에서 데이터가 저장되는 위치입니다. 컨테이너 경로는 컨테이너 내부에서 앱이 해당 데이터를 보는 위치입니다. 볼륨 마운트 또는 바인드 마운트는 이 두 환경을 연결합니다.
호스트 경로가 올바르더라도 잘못된 컨테이너 경로에 마운트하면 앱은 해당 폴더가 없는 것처럼 동작할 수 있습니다. 컨테이너 경로가 올바르더라도 호스트 경로가 임시 경로라면 앱이 의도하지 않은 위치에 데이터를 기록할 수 있습니다.
데이터를 잃은 뒤가 아니라 앱을 실행하기 전에 경로 매핑을 계획하세요.
Hermes Agent를 실행하기 전에 어떤 데이터를 보호해야 하나요?
컨테이너를 변경하거나 이미지를 업데이트하거나 게이트웨이를 재구성하기 전에 다시 만들기 어려운 데이터를 나열하세요. 모든 파일을 똑같이 보호할 필요는 없지만 어떤 파일이 중요한지는 알아야 합니다.
신원, 액세스 권한, 구성, 학습된 워크플로 또는 쉽게 다시 만들 수 없는 출력을 저장하는 항목은 모두 보호하는 것이 유용한 원칙입니다.
에이전트 구성 및 모델 제공업체 설정
모델 설정에는 일반적으로 제공업체 선택, 엔드포인트 값, 모델 이름, 컨텍스트 관련 옵션 및 API 액세스 정보가 포함됩니다. 이러한 설정이 손실되면 에이전트가 시작되더라도 제대로 답변하지 못할 수 있습니다.
모델 설정은 임시 셸 세션이 아니라 영구 앱 데이터 경로에 저장하세요. 환경 변수를 통해 설정을 제공하는 경우 compose 파일, env 파일 또는 배포 참고 자료를 안전하게 복사해 두세요.
에이전트가 터미널 도구나 메시징 게이트웨이를 사용하는 방식을 결정하는 설정도 보호하세요.
앱 메모리, 세션, 스킬 및 런타임 상태
Hermes Agent 데이터에는 구성 파일이 여러 개 포함될 수 있습니다. Hermes 스킬 데이터 구조에 따르면 스킬은 번들 스킬, 허브에서 설치한 스킬, 에이전트가 만든 스킬의 기본 기준 저장소인 ~/.hermes/skills/에 저장됩니다. 또한 번들 매니페스트, 스킬 번들, 허브 탭 구성, 보류 중인 스킬 쓰기 작업, 구성 설정과 같은 관련 상태도 설명합니다.
에이전트가 만든 스킬은 재사용 가능한 절차적 메모리가 될 수 있으므로 중요합니다. 잘못된 경로를 마운트하면 설정뿐 아니라 에이전트가 익힌 워크플로나 설치한 스킬까지 잃을 수 있습니다.
스킬, 번들, 보류 중인 쓰기 작업 및 프로필 관련 상태를 에이전트의 영구 데이터로 취급하세요.
다운로드, 생성된 파일, 로그 및 도구 출력
생성된 파일은 쉽게 놓칠 수 있습니다. 에이전트는 일반적인 사용 중에 계획, 스크립트, 보고서, 스크린샷, 로그 또는 다운로드한 파일을 만들 수 있습니다.
이 파일은 활성 작업 공간, 백엔드 작업 디렉터리, 앱 홈 디렉터리 또는 마운트된 출력 경로에 저장될 수 있습니다. 해당 위치가 컨테이너 안에만 있다면 컨테이너를 제거할 때 파일이 사라질 수 있습니다.
실제로 사용할 때는 생성된 파일을 호스트 서버의 어디에 표시할지 정하고, 컨테이너가 그 위치에 파일을 쓰는지 확인하세요.
API 키, 봇 토큰, 환경 변수
시크릿은 일반 앱 데이터가 아닙니다. API 키, 봇 토큰, 대시보드 비밀번호, 환경 변수는 지속성과 보호가 모두 필요합니다.
시크릿을 임의의 생성 결과 폴더나 광범위한 공유 디렉터리에 저장하지 마세요. 접근이 제한된 제어된 설정 경로에 보관하세요.
적절한 시크릿 관리 설정은 다음 질문에 답할 수 있어야 합니다.
- 시크릿이 저장된 위치;
- 어떤 사용자가 이를 읽을 수 있는지;
- 백업에 포함되는지 여부;
- 백업이 암호화되었거나 접근이 통제되는지 여부;
- 노출된 경우 시크릿을 어떻게 교체할 수 있는지.
호스트 경로, 컨테이너 경로, 볼륨 마운트
이는 대부분의 “컨테이너에서 폴더를 찾을 수 없음” 및 “재시작 후 데이터가 사라짐” 문제의 핵심 개념입니다. 컨테이너는 자체 파일 시스템에 있거나 컨테이너에 마운트된 항목만 볼 수 있습니다.
문제를 해결하기 전에 설정을 정리하려면 에이전트 데이터 보존 맵을 사용하세요.
| 프레임워크 모듈 | 핵심 질문 | 결정에 도움이 되는 사항 | 설정 / 문제 해결 중점 |
|---|---|---|---|
| 데이터 목록 | 컨테이너를 재시작하거나 다시 만들어도 어떤 데이터가 유지되어야 하나요? | 보호해야 하는 설정, 스킬, 로그, 다운로드 파일, 토큰, 생성 파일 | 중요한 에이전트 데이터를 버려도 되는 상태 데이터로 취급하지 않도록 합니다 |
| 영구 데이터 저장 경로 | 호스트에서 영구 데이터를 어디에 저장해야 하나요? | 전용 호스트 폴더, Docker 볼륨 또는 바인드 마운트 중 무엇을 사용할지 | 컨테이너를 다시 만들었을 때 데이터가 초기화되는 것을 방지합니다 |
| 마운트 매핑 | 호스트 경로가 컨테이너 경로에 올바르게 매핑되었나요? | 앱이 의도한 폴더를 실제로 볼 수 있는지 여부 | 폴더를 찾을 수 없거나 대상 경로가 잘못되었다는 오류의 원인을 파악하는 데 도움이 됩니다 |
| 권한 경계 | 마운트된 데이터의 소유자는 누구이며, 어떤 사용자가 여기에 기록하나요? | 호스트 사용자, 컨테이너 사용자, 앱 사용자 또는 root 중 누가 파일을 소유하는지 | 모든 파일의 소유자를 root로 바꾸지 않고 권한 거부 문제를 해결하는 데 도움이 됩니다 |
| 백업 범위 | 업데이트나 재구성 전에 무엇을 백업해야 하나요? | 어떤 데이터가 중요하고 어떤 데이터가 임시인지 | 설정, 스킬, 세션, 토큰, 게이트웨이 설정의 손실을 방지합니다 |
| 재시작 검증 | 재시작이나 업데이트 후에도 데이터가 남아 있나요? | 설정이 실제로 지속되는지 여부 | “실행된다”를 반복 가능한 안전 점검으로 바꿉니다 |
호스트 서버에 저장되는 항목
호스트 서버에는 실제 폴더와 디스크, Docker가 관리하는 저장소 위치가 있습니다. 바인드 마운트를 사용하면 호스트 폴더를 직접 선택합니다. 이름 있는 Docker 볼륨을 사용하면 Docker가 저장소 위치를 선택하고 관리합니다.
이 구분은 호스트에서 데이터를 확인할 수 있는지가 백업과 마이그레이션에 영향을 주기 때문에 중요합니다. 바인드 마운트 폴더는 초보자도 쉽게 찾아 복사할 수 있습니다. 이름 있는 볼륨은 Docker가 관리하는 앱 데이터에 더 깔끔할 수 있지만, 이를 확인하거나 백업하는 방법은 알아야 합니다.
사람이 읽기 쉬운 호스트 폴더가 필요한지, Docker가 관리하는 앱 영구 저장소가 필요한지, 아니면 제어된 백업 경로가 필요한지에 따라 저장소 방식을 선택하세요.
컨테이너에서 볼 수 있는 항목
컨테이너에서는 자체 내부 파일 시스템과 마운트된 경로를 볼 수 있습니다. 홈 서버의 모든 폴더를 자동으로 볼 수 있는 것은 아닙니다.
Docker의 바인드 마운트 안내에서는 호스트 디렉터리를 대상 경로의 컨테이너 내부에서 표시하는 방법과, 마운트가 올바르게 설정되었을 때 호스트와 컨테이너 간 파일 변경 사항이 반영되는 방식을 설명합니다.
핵심은 앱에서 사용하는 경로에 파일을 마운트하지 않으면, 파일이 호스트 어디에 있든 앱은 그 파일을 인식하지 못한다는 것입니다.
볼륨 마운트로 앱 데이터를 영구 보존하는 방법
영구 마운트를 사용하면 단일 컨테이너의 수명이 끝난 뒤에도 앱이 안정적인 위치에 데이터를 쓸 수 있습니다. 앱 데이터의 경우, 이 차이가 흔히 ‘재시작 후에도 유지됨’과 ‘컨테이너가 살아 있는 동안에만 유지됨’을 가릅니다.
마운트 경로는 앱이 예상하는 데이터 경로와 일치해야 합니다. 앱이 한 내부 폴더에 쓰는데 다른 폴더를 마운트하면 데이터가 여전히 삭제 가능한 저장소에 저장될 수 있습니다.
적절한 영구 저장소 설정은 다음을 정의해야 합니다.
- 호스트 폴더 또는 명명된 볼륨.
- 컨테이너 내 대상 경로
- 마운트가 읽기-쓰기인지 읽기 전용인지.
- 그곳에 저장할 앱 데이터.
- 경로를 백업하는 방법.
잘못된 경로 매핑으로 폴더 누락 오류가 발생하는 이유
잘못된 경로 매핑은 흔히 폴더가 없다는 문제처럼 보입니다. 호스트에는 폴더가 있지만 컨테이너에서 보이지 않을 수 있습니다. 또는 컨테이너에 예상한 경로의 폴더가 있지만, 의도한 호스트 폴더와 연결되어 있지 않을 수 있습니다.
일반적인 증상은 다음과 같습니다.
- 앱에서 폴더가 없다고 표시됩니다.
- 생성된 파일이 컨테이너 안에는 있지만 호스트에는 나타나지 않습니다.
- 컨테이너를 재구성한 후 로그가 사라집니다.
- 업데이트 후 설정이 초기화됩니다.
- 호스트 폴더를 수정해도 앱은 이전 설정을 계속 사용합니다.
- 백업 스크립트는 실행되지만 실제 앱 데이터는 포함하지 않습니다.
이런 일이 발생하면 호스트 경로와 컨테이너 경로를 함께 확인하세요. 한쪽만 확인하지 마세요.
데이터 손실 없이 Hermes Agent 실행하는 방법
목표는 단순히 Hermes Agent를 시작하는 것이 아닙니다. 중요한 데이터가 재시작, 업데이트, 재구성, 설정 변경 후에도 유지되도록 하는 것입니다.
1단계: 전용 호스트 데이터 폴더 선택
컨테이너를 실행하거나 재구성하기 전에 호스트 데이터 폴더를 선택하세요. 쉽게 식별하고 백업할 수 있어야 하며, 관련 없는 개인 파일과 섞이지 않아야 합니다.
전용 폴더를 사용하면 앱에 속한 항목을 쉽게 확인할 수 있어 위험을 줄일 수 있습니다. 또한 홈 디렉터리 전체나 다른 민감한 폴더를 컨테이너에 마운트하지 않아도 됩니다.
실용적인 호스트 데이터 폴더는 다음 조건을 갖춰야 합니다.
- 앱 전용이어야 합니다.
- 삭제 가능한 다운로드 경로 외부에 있어야 합니다.
- 백업 계획에 포함되어야 합니다.
- 관련 없는 서비스와 광범위하게 공유되지 않아야 합니다.
- 접근이 필요한 사용자 또는 서비스만 쓸 수 있어야 합니다.
2단계: 데이터 폴더를 컨테이너에 마운트하기
호스트 데이터 폴더를 앱이 예상하는 컨테이너 경로에 마운트하세요. 이때 데이터 손실 문제가 발생하거나 예방되는 경우가 많습니다.
바인드 마운트의 경우 호스트 경로는 직접 선택하고 대상 경로는 컨테이너 내부에서 해당 경로가 나타나는 위치입니다. 명명된 볼륨의 경우 Docker가 호스트 측 위치를 관리합니다.
앱이 마운트된 폴더를 자동으로 사용할 것이라고 가정하지 마세요. 마운트 대상이 실제 앱 데이터 경로와 일치하는지 확인하세요.
3단계: 컨테이너가 예상한 앱 데이터 경로를 사용하는지 확인하기
마운트한 후 컨테이너 내부에서 해당 경로를 확인하세요. 호스트에 폴더가 있더라도 올바르게 마운트되지 않았다면 앱에서 보이지 않을 수 있습니다.
간단한 검증 방법은 한쪽에서 문제가 없는 테스트 파일을 만들거나 찾아 다른 쪽에도 나타나는지 확인하는 것입니다. 그런 다음 앱이 실제 설정, 로그 또는 생성된 파일을 동일한 영구 경로에 저장하는지 확인하세요.
이 단계는 업데이트나 마이그레이션 전에 특히 중요합니다.
4단계: 파일 소유권 및 쓰기 권한 확인하기
마운트가 올바르더라도 앱이 해당 경로에 쓸 수 없으면 작동하지 않을 수 있습니다. 파일은 root로 생성되지만 앱이 나중에 다른 사용자로 실행될 때 권한 오류가 발생하는 경우가 많습니다.
권한을 광범위하게 변경하기 전에 소유권을 확인하세요. 일반적으로 적절한 해결 방법은 모든 프로세스에 호스트의 넓은 디렉터리를 완전히 제어할 권한을 주는 것이 아니라, 지정된 앱 사용자가 특정 앱 데이터 폴더를 읽고 쓸 수 있도록 하는 것입니다.
권한 거부 오류가 표시되면 다음을 확인하세요.
- 마운트된 호스트 경로
- 컨테이너 내 대상 경로
- 앱을 실행하는 사용자
- 파일 소유자
- 마운트가 읽기 전용인지 여부
- 백업 또는 내보내기 경로에도 쓰기 권한이 있는지 여부
5단계: 비밀 정보와 설정 파일을 삭제될 수 있는 경로 밖에 보관하기
비밀 정보와 설정 파일은 임시 폴더, 생성된 출력 디렉터리 또는 임시 셸 기록에만 저장해서는 안 됩니다. 환경 변수를 사용하는 경우 배포 파일이나 env 파일을 통제되는 영구 위치에 보관하세요.
비밀 정보와 로그 또는 생성된 결과물을 섞지 마세요. 문제 해결을 위해 로그는 공유할 수 있지만, 비밀 정보는 함부로 공유해서는 안 됩니다.
비밀 정보를 백업하는 경우 백업을 안전하게 보호하세요. API 키나 봇 토큰이 노출되는 백업은 또 다른 위험을 초래합니다.
6단계: 컨테이너를 재시작하고 데이터가 여전히 있는지 확인하기
설정 후 컨테이너를 재시작하고 중요한 데이터가 남아 있는지 확인하세요. 이것이 데이터 지속성을 확인하는 가장 실용적인 테스트입니다.
“컨테이너가 시작된다”는 것만 확인하고 끝내지 마세요. 다음을 확인하세요.
- 모델 설정이 여전히 존재합니다.
- 스킬 또는 앱 상태가 계속 표시됩니다.
- 로그가 예상한 위치에 계속 저장됩니다.
- 생성된 파일이 호스트에 나타납니다.
- 게이트웨이 또는 봇 설정이 여전히 작동합니다.
- 백업 파일을 찾을 수 있습니다.
재시작 검증을 통과한 설정은 최초 설치만 통과한 설정보다 훨씬 안전합니다.
권한, 백업 및 안전 경계
데이터 안전은 세 가지 경계에 달려 있습니다. 쓰기 권한이 있는 사용자, 백업 대상, 에이전트가 접근하도록 허용된 항목입니다. 파일을 만들고, 작업 흐름을 수정하거나, 도구를 사용할 수 있는 셀프 호스팅 에이전트에서는 이러한 경계가 특히 중요합니다.
컨테이너 사용자 권한이 중요한 이유
컨테이너 사용자 권한에 따라 앱이 데이터를 읽고 쓸 수 있는지가 결정됩니다. 앱은 한 사용자로 실행되는데 마운트된 폴더는 다른 사용자의 소유라면 쓰기 작업이 실패할 수 있습니다.
이 때문에 설정 명령을 root로 실행하면 나중에 문제가 생길 수 있습니다. root는 파일을 문제없이 만들 수 있지만 일반 앱 사용자는 해당 파일을 수정하지 못할 수 있습니다.
앱 데이터 폴더 수준에서 권한을 수정하세요. 관련 없는 호스트 파일까지 노출하는 광범위한 권한 변경은 피하세요.
모든 작업을 root로 실행하지 말아야 하는 이유
root는 여러 제한을 우회할 수 있지만, 그렇다고 기본 설정으로 안전한 것은 아닙니다. 모든 작업을 root로 실행하면 root 소유 파일이 생기고, 권한 문제가 드러나지 않으며, 앱에 필요한 것보다 더 많은 접근 권한이 부여될 수 있습니다.
대부분의 셀프 호스팅 앱 작업 흐름에서 root는 특정 관리 작업에만 사용해야 합니다. 가능하면 일반적인 앱 설정은 앱 또는 컨테이너에 지정된 사용자로 실행하세요.
더 안전한 방법은 최소 권한 원칙을 따르는 것입니다. 앱에 필요한 폴더에만 쓰기 권한을 부여하세요.
읽기 전용 마운트 또는 제한된 폴더를 사용해야 할 때
파일을 확인하기만 하고 수정해서는 안 되는 경우에는 읽기 전용 마운트를 사용하세요. 결과물을 생성해야 하지만 광범위한 개인 디렉터리나 시스템 디렉터리를 건드려서는 안 되는 경우에는 쓰기 가능한 폴더를 제한해서 사용하세요.
이는 서버 파일 전체에 대한 쓰기 권한을 주지 않고 에이전트가 보고서, 계획 또는 스크립트를 생성하도록 하려는 경우 특히 유용합니다.
폴더 범위를 제한하면 실수로 인한 영향을 줄일 수 있습니다. 또한 어느 폴더에 앱 상태가 저장되고 어느 폴더에 생성된 결과물이 저장되는지 알 수 있어 백업도 더 쉬워집니다.
업데이트 또는 재구성 전에 에이전트 데이터를 백업하는 방법
컨테이너 이미지, 마운트 경로, 게이트웨이 설정 또는 프로필을 변경하기 전에 중요한 앱 데이터를 백업하세요. 백업에 무엇이 포함되는지, 어떻게 복원하는지 알아야 백업을 유용하게 활용할 수 있습니다.
Docker 커뮤니티의 볼륨 백업 권한 관련 토론에서는 사용자가 흔히 겪는 문제를 보여 줍니다. 경로가 존재하더라도 권한, 소유권, 레이블 또는 마운트 관련 제한으로 인해 백업이나 쓰기 작업이 실패할 수 있습니다.
백업을 만드는 데 그치지 말고 테스트해야 한다는 점을 기억하세요. 백업 계획에는 백업 생성과 복원 검증이 모두 포함되어야 합니다.
일반적인 문제와 해결 방법
Hermes Agent 데이터가 없다고 해서 바로 앱을 다시 설치하지 마세요. 먼저 어떤 계층에 문제가 생겼는지 확인하세요. 데이터 인벤토리, 영속성 경로, 마운트 매핑, 권한 경계, 백업 범위 또는 재시작 검증 중 어디인지 확인해야 합니다.
컨테이너에서 마운트된 폴더를 찾을 수 없음
이는 보통 한쪽 계층에는 경로가 있지만 다른 쪽에는 없다는 뜻입니다. 호스트 폴더가 마운트되지 않았거나, 컨테이너의 대상 경로가 잘못되었거나, 앱이 다른 위치를 찾고 있을 수 있습니다.
다음 순서로 확인하세요:
- 호스트에 폴더가 있는지 확인하세요.
- 컨테이너에 마운트가 있는지 확인하세요.
- 컨테이너 내부의 대상 경로를 확인하세요.
- 앱이 해당 대상 경로를 사용하도록 설정되어 있는지 확인하세요.
- 앱 사용자가 폴더를 읽을 수 있는지 확인하세요.
- compose 또는 실행 설정을 변경한 후 마운트가 다시 생성되었는지 확인하세요.
컨테이너 내부에 임의의 폴더를 만들어 해결하지 마세요. 그렇게 하면 일시적으로 오류가 사라질 수 있지만, 데이터는 삭제될 수 있는 저장소에 남습니다.
재시작 후 앱 데이터가 초기화됨
재시작 후 데이터가 초기화된다면 앱이 영구 저장 경로가 아닌 컨테이너 내부 파일 시스템에 데이터를 쓰고 있을 수 있습니다. 예상과 다른 프로필, 환경 변수 또는 데이터 디렉터리를 사용하고 있을 수도 있습니다.
재시작 전과 후의 데이터 경로가 같은지 확인하세요. 그런 다음 폴더가 마운트에 연결되어 있는지, 아니면 컨테이너 레이어에만 있는지 확인하세요.
앱을 다시 만들었다면 새 컨테이너에 동일한 볼륨 또는 바인드 마운트가 연결되었는지 확인하세요.
데이터 디렉터리의 권한 거부 오류
권한 거부는 앱이 경로를 볼 수 있지만 필요한 작업을 수행할 수 없다는 뜻입니다. 소유권, 읽기 전용 마운트 설정, 파일 시스템 레이블 또는 호스트 사용자와 컨테이너 사용자 간의 불일치가 원인일 수 있습니다.
가장 간단한 확인부터 시작하세요. 앱 사용자가 데이터 디렉터리에 문제가 없는 테스트 파일을 만들 수 있나요? 만들 수 없다면 해당 경로의 소유자와 권한을 확인하세요.
호스트 디렉터리 전체에 광범위한 쓰기 권한을 부여해 해결하려고 하지 마세요. 앱 데이터 경로와 앱에서 사용할 사용자를 올바르게 설정하세요.
생성된 파일이 컨테이너 내부에만 저장됨
재빌드 후 생성된 파일이 사라진다면 마운트된 호스트 경로가 아니라 컨테이너 내부에 저장했을 가능성이 큽니다. 앱의 작업 디렉터리나 출력 디렉터리가 매핑되지 않은 경우에 자주 발생합니다.
생성된 파일을 저장할 위치를 정하세요. 그런 다음 해당 출력 폴더를 마운트하거나 앱이 기존 영구 저장 위치에 파일을 쓰도록 설정하세요.
경로를 변경한 후 문제가 없는 테스트 파일을 생성하고 호스트에 표시되는지 확인하세요.
재구성 후 봇 또는 게이트웨이 설정이 사라짐
설정이 영구 저장되지 않는 경로에 저장되어 있거나 재시작 후 앱이 다른 프로필로 실행되면 게이트웨이 설정이 사라질 수 있습니다. 한 곳에서 환경 변수를 변경했지만 실행 중인 컨테이너는 다른 값을 사용하는 경우에도 같은 문제가 발생할 수 있습니다.
게이트웨이 설정, 봇 토큰 참조, 허용 목록, 대시보드 설정이 예상된 영구 저장 위치에 저장되어 있는지 확인하세요. 그런 다음 게이트웨이를 재시작하고 설정이 계속 활성 상태인지 확인하세요.
봇이 재시작 전에는 작동하지만 재시작 후에는 작동하지 않는다면 토큰을 변경하기 전에 데이터 영구 저장 여부와 환경 구성을 먼저 확인하세요.
Hermes Agent 데이터가 안전한지 확인하는 방법
안전한 설정이라면 재시작, 쓰기, 백업, 접근 확인을 통과해야 합니다. 복잡하게 확인할 필요는 없지만, 주요 변경 후에는 반복해서 확인해야 합니다.
재시작 후에도 구성이 유지됨
간단한 설정을 변경하고 컨테이너를 재시작한 다음, 설정이 유지되는지 확인하세요. 이를 통해 앱이 영구 저장소에 데이터를 쓰고 있는지 확인할 수 있습니다.
설정이 사라진다면 구성을 더 추가하지 마세요. 먼저 데이터 경로를 수정하세요.
로그와 생성된 파일이 예상한 호스트 폴더에 나타남
로그와 생성된 파일이 호스트에서 예상한 위치에 나타나야 합니다. 컨테이너 내부에만 나타난다면 재빌드 시 사라질 수 있습니다.
마운트의 양쪽을 모두 확인하세요. 호스트와 컨테이너에서 중요한 파일이 동일하게 보여야 합니다.
에이전트가 권한 오류 없이 앱 데이터에 쓸 수 있음
에이전트는 지정된 사용자로 앱 데이터 폴더에 쓸 수 있어야 합니다. 폴더가 존재하는지만 확인하는 것보다 쓰기 테스트를 성공적으로 마치는 것이 더 유용합니다.
재시작 후 로그에서 권한 오류가 발생하는지 확인하세요. 에이전트가 구성을 업데이트하거나, 스킬을 작성하거나, 생성된 파일을 저장하거나, 게이트웨이 상태를 업데이트하려고 할 때만 권한 문제가 나타날 수 있습니다.
백업 파일을 찾아 복원할 수 있음
백업 파일을 찾아 테스트 위치에 복원할 수 있어야 백업이 완전하다고 할 수 있습니다. 최소한 백업에 보호하려던 데이터가 들어 있는지 확인하세요.
중요한 설정의 경우 백업에 의존하기 전에 별도의 폴더나 테스트 인스턴스에 복원해 보세요. 이렇게 하면 데이터를 잃은 뒤에야 복원 문제를 발견하는 일을 방지할 수 있습니다.
재부팅 후에도 대시보드 또는 메시지에 접근할 수 있음
재부팅 후 대시보드 또는 메시지 접근이 계속 가능한지 확인하세요. 이를 통해 영구 데이터, 인증 정보, 게이트웨이 설정, 네트워크 접근이 여전히 올바르게 설정되어 있는지 확인할 수 있습니다.
대시보드는 작동하지만 메시지가 전송되지 않는다면 게이트웨이 설정과 토큰 접근을 확인하세요. 메시지는 전송되지만 생성된 파일이 사라진다면 출력 경로와 마운트를 확인하세요.
실제 홈 서버 환경에서 작동하는 방식
실제 홈 서버 설정에서는 시스템이 사용하기 편리한 대시보드를 제공하더라도 동일한 데이터 안전 원칙이 적용됩니다. 어떤 데이터를 보존해야 하는지, 어디에 저장되는지, 컨테이너에서 어떻게 접근하는지, 어떤 사용자가 쓸 수 있는지, 재시작 후 어떻게 확인할 수 있는지 알아야 합니다.
예를 들어, ZimaOS Hermes Agent 설정 워크플로에서는 모델 제공업체 구성, Telegram 게이트웨이 설정, Hermes 컨테이너 진입, 앱 환경 활성화, 웹 대시보드 확인, 권한 또는 봇 응답 문제 해결을 포함한 장치별 절차를 보여 줍니다.
작고 상시 켜져 있는 장치에서 Docker 앱, 에이전트 워크플로, 로컬 서비스를 실행하는 사용자에게 ZimaBoard 2 홈 서버는 영구 폴더, 컨테이너 경로, 권한, 스토리지 확장을 함께 계획해야 하는 경량 홈 서버 환경의 좋은 예입니다. 가능한 구성은 여러 가지지만, 이 가이드에서 다루는 셀프 호스팅 앱 워크플로에 잘 맞는 환경입니다.
일반적으로 기억할 점은 다음과 같습니다. 컨테이너화된 에이전트에 중요한 작업을 맡기기 전에, 현재 실행 중인 컨테이너가 사라진 뒤에도 중요한 데이터가 보존되는지 확인하세요.
자주 묻는 질문
컨테이너를 다시 시작한 후 Hermes Agent 데이터가 사라진 이유는 무엇인가요?
간단히 재시작해도 영구 데이터가 삭제되지는 않지만, 앱이 영구적이지 않은 컨테이너 경로에 데이터를 기록하고 있었다면 초기화된 것처럼 보일 수 있습니다. 동일한 볼륨이나 바인드 마운트를 연결하지 않은 채 컨테이너를 다시 만들었다면 데이터가 사라졌을 수도 있습니다. 설정을 더 변경하기 전에 호스트 경로, 컨테이너 경로, 실제 앱 데이터 경로를 확인하세요.
Docker 볼륨과 바인드 마운트의 차이는 무엇인가요?
Docker 볼륨은 Docker에서 관리하는 저장소이고, 바인드 마운트는 사용자가 선택한 호스트 폴더를 컨테이너에 연결합니다. 앱이 관리하는 데이터에는 볼륨이 깔끔한 선택인 경우가 많고, 바인드 마운트는 호스트에서 직접 찾기 쉽습니다. Docker가 저장소를 관리하도록 할지, 백업과 확인을 위해 호스트에서 폴더를 직접 볼 수 있도록 할지에 따라 적합한 선택이 달라집니다.
홈 서버에서 Hermes Agent 앱 데이터는 어디에 저장해야 하나요?
임시 컨테이너 경로 대신 전용 영구 폴더나 Docker 볼륨을 사용하세요. 위치는 백업하기 쉽고, 앱에 필요한 범위로 제한되며, 관련 없는 민감한 파일과 섞이지 않아야 합니다. 가장 중요한 점은 앱이 예상하는 컨테이너 경로가 해당 영구 저장소에 실제로 연결되어 있어야 한다는 것입니다.
컨테이너에서 폴더가 없다고 표시되는 이유는 무엇인가요?
호스트에는 폴더가 있어도 컨테이너 내부에는 없을 수 있습니다. 이는 보통 마운트가 생성되지 않았거나, 소스 경로 또는 대상 경로가 잘못되었거나, 앱이 다른 컨테이너 경로를 찾고 있다는 뜻입니다. 무작정 새 폴더를 만들기보다 호스트 쪽과 컨테이너 쪽을 모두 확인하세요.
권한 오류를 피하려면 Hermes Agent를 루트로 실행해야 하나요?
루트로 실행하면 당장의 오류는 사라질 수 있지만, 루트 소유 파일이 생성되고 위험이 커질 수 있습니다. 더 안전한 방법은 지정된 앱 사용자가 필요한 앱 데이터 경로만 읽고 쓸 수 있도록 설정하는 것입니다. 변경 내용을 이해하고 있는 경우에만 특정 관리 또는 복구 작업에 루트를 사용하세요.
Hermes Agent 데이터는 얼마나 자주 백업해야 하나요?
업데이트, 컨테이너 재빌드, 경로 변경, 게이트웨이 재구성 또는 다른 서버로 마이그레이션하기 전에 백업하세요. 활발히 사용한다면 스킬, 설정, 생성된 파일 또는 세션이 변경되는 빈도에 맞춰 정기 백업을 예약하세요. 파일을 찾고 복원할 수 있는지 확인하기 전까지는 백업이 신뢰할 만하다고 볼 수 없습니다.
지원 및 팁
더 읽어보기

Transformers에서 커뮤니티 모델을 불러오기 전에 확인할 사항
Transformers Jinja 샌드박스 업데이트를 활용해 모델의 출처, 채팅 템플릿, 원격 코드, 직렬화된 가중치, 격리된 첫 실행을 검토하세요.

Mirage를 로컬에서 실행: 한 장의 이미지로 OCR 및 객체 감지
Cactus Compute의 소형 로컬 비전 모델을 사용해 보고, 실제 입력으로 OCR 및 객체 추출을 검증하며, 메모리, 언어 및 개인정보 보호의 한계를 파악해 보세요.

홈 서버에서 Open WebUI 코딩 에이전트 예약 실행하는 방법
Open WebUI에서 보고 전용 코딩 에이전트 자동화를 설정하고, 터미널과 작업 공간을 선택한 다음 권한, 로그 및 오류 복구를 확인하세요.



