Host Storage 어댑터 연결하기
Host Storage 어댑터는 Office가 실행되는 서버의 디렉터리를 문서 저장소로 사용합니다. Docker로 실행한 Office에는 컨테이너 안에서 접근할 수 있는 디렉터리를 지정합니다.
미리 연결된 어댑터 확인하기
Trial과 Free Commercial 컨테이너 이미지에는 문서 열기와 저장을 바로 테스트할 수 있도록 host-storage라는 Host Storage 어댑터를 미리 연결해 두었습니다.
문서 루트 디렉터리는 컨테이너 안의 /home/thinkfree/docs이며, 이미지에 포함된 샘플 문서가 이 폴더에 있습니다. 이 어댑터는 다시 등록할 필요가 없습니다.
Office 관리자 페이지에 로그인한 뒤 외부연동에서 host-storage를 확인합니다.
해당 행의 업데이트 아이콘을 누르면 문서 루트 디렉터리와 스토리지 표시 이름을 확인할 수 있습니다.
미리 연결된 어댑터의 문서 URL 만들기
문서를 여는 URL은 Office 주소, 등록한 어댑터 이름, 문서 루트 아래의 상대 경로를 조합합니다. Word 문서를 편집기로 여는 URL 형식은 다음과 같습니다.
{OFFICE_URL}/cloud-office/api/{ADAPTER_NAME}/{DOCUMENT_PATH}/open?app=WORD_EDITOR&user_id={USER_ID}&docId={DOCUMENT_ID}
ADAPTER_NAME에는 관리자 화면의 이름을 사용합니다.
스토리지 표시 이름은 URL에 사용하지 않습니다.
DOCUMENT_PATH에는 문서 루트 디렉터리를 제외한 상대 경로를 넣습니다.
위 캡처의 어댑터 이름 host-storage와 문서 루트 /home/thinkfree/docs를 사용한 예제입니다. 이 폴더에 sample.docx가 있다면 다음과 같이 연결합니다.
| 항목 | 값 |
|---|---|
| Office 주소 | http://localhost:8080 |
| 어댑터 이름 | host-storage |
| 문서 루트 디렉터리 | /home/thinkfree/docs |
| 컨테이너 안의 파일 | /home/thinkfree/docs/sample.docx |
| URL에 넣을 문서 경로 | sample.docx |
http://localhost:8080/cloud-office/api/host-storage/sample.docx/open?app=WORD_EDITOR&user_id=local-user&docId=hostsample001
예제의 user_id는 사용할 사용자 식별자로, docId는 편집 세션을 구분하는 고유한 값으로 바꿉니다.
Office 접속 주소나 포트가 다르면 URL 앞부분도 변경합니다.
다른 문서 형식의 app 값과 JavaScript로 URL을 생성하는 방법은 문서 URL 생성에서 설명합니다.
문서 폴더 연결하기
앞에서 사용한 /home/thinkfree/docs는 컨테이너 안에 있는 샘플 문서 폴더입니다. Docker를 실행하는 호스트 컴퓨터의 문서 폴더와는 별개의 위치입니다.
호스트 컴퓨터에 저장된 문서를 Office에서 열려면, 문서가 있는 폴더를 컨테이너의 /home/thinkfree/docs에 마운트해야 합니다.
아래는 Linux 사용자의 /home/username/personal-documents 폴더를 연결하는 예제입니다. 이 경로를 실제 문서 폴더의 절대 경로로 바꾸고, 폴더가 존재하며 Office가 읽고 쓸 수 있는지 확인합니다.
컨테이너를 생성할 때 Office 실행 명령에 다음 옵션을 추가합니다.
-v "/home/username/personal-documents:/home/thinkfree/docs"
콜론(:) 왼쪽의 /home/username/personal-documents는 호스트 컴퓨터의 폴더이고, 오른쪽의 /home/thinkfree/docs는 Office가 그 폴더에 접근할 컨테이너 안의 경로입니다.
관리자 화면의 문서 루트 디렉토리는 /home/thinkfree/docs로 유지합니다.
마운트한 동안에는 이 경로에서 호스트 폴더의 문서가 보입니다. 이미지에 포함된 샘플 문서는 호스트 폴더로 자동 복사되지 않으므로, 빈 폴더를 연결하면 샘플 문서도 표시되지 않습니다. Office에서 문서를 편집하고 저장하면 연결한 호스트 폴더의 파일에 반영됩니다.
마운트한 폴더의 문서 URL
위와 같이 마운트하면 호스트 컴퓨터의 /home/username/personal-documents/contracts/Proposal 2026.docx가
컨테이너에서는 /home/thinkfree/docs/contracts/Proposal 2026.docx로 보입니다.
미리 연결된 host-storage를 그대로 사용하므로, URL에는 문서 루트 아래의 contracts/Proposal 2026.docx를 넣습니다.
http://localhost:8080/cloud-office/api/host-storage/contracts/Proposal%202026.docx/open?app=WORD_EDITOR&user_id=local-user&docId=hostproposal001
폴더를 구분하는 /는 유지하고, 공백은 위 예제의 %20처럼 경로 구간별로 URL 인코딩합니다.
호스트 경로인 /home/username/personal-documents나 컨테이너의 문서 루트인 /home/thinkfree/docs는 URL에 넣지 않습니다.
Host Storage 어댑터 더 추가하기
미리 연결된 host-storage를 사용하려면 앞의 예처럼 호스트 폴더의 마운트만 바꾸면 됩니다.
다른 문서 폴더를 별도 어댑터로 연결하려면 폴더를 추가로 마운트하고 아래 절차에 따라 어댑터를 등록합니다.
다른 디렉터리를 별도 어댑터로 추가하려면 Office 실행 명령에 다음 옵션을 넣어 신규 등록을 활성화합니다.
Host Storage는 Office가 실행되는 서버의 파일과 디렉터리에 접근할 수 있습니다. 보안을 위해 새 Host Storage 어댑터 등록은 기본적으로 비활성화되어 있으며, 서비스 실행 시 아래 옵션으로 직접 활성화해야 합니다.
-e TFO_ADAPTER_HOST_STORAGE_ENABLED=true
아래 캡처는 신규 등록을 활성화한 관리자 화면입니다.
- 외부연동에서 어댑터 추가를 누릅니다.
- 어댑터 유형에서 호스트 스토리지 어댑터를 선택합니다.
- 다음 항목을 입력합니다.
| 항목 | 입력할 값 |
|---|---|
| 이름 | 문서 URL에 사용할 고유한 어댑터 이름. 예: company-documents |
| 설명 | 어댑터의 용도 |
| 스토리지 표시 이름 | 사용자에게 표시할 저장소 이름. 예: Company documents |
| 문서 루트 디렉토리 | Office가 읽고 쓸 수 있는 절대 경로. 예: /home/thinkfree/docs |
- 연결 테스트로 디렉터리에 접근하고 파일 목록을 조회할 수 있는지 확인합니다.
- 성공하면 등록을 누르고 목록에서 어댑터가 실행 중인지 확인합니다.
연결 테스트가 실패하면 Office에서 해당 경로에 접근할 수 있는지 확인합니다. 컨테이너를 사용하는 경우 호스트 경로와 컨테이너 안의 경로를 혼동하지 않도록 주의합니다.
위의 내용처럼 이름을 company-documents, 문서 루트를 /home/thinkfree/docs로 등록했다면 같은 폴더의 sample.docx는 다음 URL로 엽니다.
http://localhost:8080/cloud-office/api/company-documents/sample.docx/open?app=WORD_EDITOR&user_id=local-user&docId=companysample001
루트 아래 상대 경로는 sample.docx로 같고, URL의 어댑터 이름이 등록한 이름으로 바뀝니다. 전체 URL 옵션은 문서 URL 생성에서 확인합니다.
다른 디렉터리를 연결한 어댑터의 문서 URL
예를 들어 호스트 컴퓨터의 /home/username/work-files를 별도 문서 디렉터리로 연결하려면 Office 실행 명령에 다음 마운트 옵션을 추가합니다. 왼쪽 경로는 실제 호스트 폴더로 바꿉니다.
-v "/home/username/work-files:/home/thinkfree/team-documents"
위의 등록 절차에서 다음 값을 입력합니다. 이 예제에서는 문서 루트 디렉토리를 새로 마운트한 경로로 바꿉니다.
| 항목 | 값 |
|---|---|
| 이름 | company-documents |
| 스토리지 표시 이름 | Company documents |
| 문서 루트 디렉토리 | /home/thinkfree/team-documents |
| 호스트 컴퓨터에 있는 파일 | /home/username/work-files/reports/Quarterly Report.docx |
| URL에 넣을 문서 경로 | reports/Quarterly Report.docx |
아래는 위의 값을 입력하고 연결 테스트에 성공한 화면입니다. 등록을 눌러 어댑터를 추가합니다.
등록을 마친 뒤 다음 URL로 문서를 엽니다.
http://localhost:8080/cloud-office/api/company-documents/reports/Quarterly%20Report.docx/open?app=WORD_EDITOR&user_id=local-user&docId=companyreport001
새 어댑터 이름인 company-documents와 새 문서 루트 아래의 상대 경로를 사용합니다.
미리 연결된 어댑터의 문서 루트만 변경했다면 어댑터 이름은 host-storage로 유지하고, 변경한 루트 아래의 상대 경로를 넣습니다.
문서 열기와 저장 확인하기
위의 예제에 따라 실제 파일의 문서 URL을 만들어 브라우저에서 엽니다. 문서를 편집하고 저장한 뒤 다시 열어 변경 내용이 유지되는지 확인합니다.
관리자 화면에서 문서 찾아보기
외부연동의 어댑터 목록에서 company-documents가 실행 중인지 확인합니다.
어댑터 이름 옆의 폴더 모양 파일 찾아보기 버튼을 누릅니다.
파일 브라우저에서 폴더를 선택하면 안으로 이동합니다.
예제의 reports 폴더를 선택하면 Quarterly Report.docx를 확인할 수 있습니다.
Office 문서를 클릭하면 새 탭에서 Office 편집기가 열립니다.