다목적 웹 기반 파일 매니저 AList 구축하기

개요

FileBrowser, FileGator 등은 대표적인 웹 기반 파일 매니저입니다. 이러한 웹 기반 파일 매니저는 기기나 운영체제에 구애받지 않고 누구나 큰 제약 없이 접근하기 좋은 서비스입니다. 그 외에도 유료로 돌아서버린 FileRun이나, UI가 어수선하지만 성능은 좋은 Copyparty도 있죠.

이러한 웹 기반 파일 매니저들은 노리는 수요층에 따라 서로 다른 기능을 추구하기 때문에, 조금 쓰다 보면 이 앱은 어떤 기능이 아쉽고 저 앱은 어떤 기능이 아쉬운 경우가 많습니다.

제 경우, 주변에 간단하게 파일을 공유해줄 앱이 필요했는데, 전제 조건이 Authentik을 이용해서 SSO통합을 할 수 있어야 했습니다(LDAP 제외). FileBrowser는 가볍고 좋았지만, 해당 부분이 아쉬웠죠. FileGator도 마찬가지였습니다. 이 기능을 위해 Nextcloud를 따로 구축하고 사용중이었으나, 최근 멋대로 버전30으로 업데이트 해버리며 제 환경이 많이 꼬여서 대체품을 찾다가 발견한 것이 AList입니다.

상당히 많은 스토리지를 지원해 구축만 해두면 요긴하게 쓸 수 있을 것으로 생각합니다.

 

AList 설치

Docker를 지원하므로, 편리하게 docker compose를 사용하겠습니다.

services:
  alist:
    image: xhofe/alist:latest
    container_name: alist
    volumes:
      - /docker/alist:/opt/alist/data
    ports:
      - 5244:5244
    environment:
      - PUID=0
      - PGID=0
      - UMASK=022
    restart: unless-stopped

설치가 완료되면 컨테이너에 접근해 admin계정의 비밀번호를 생성해야 합니다.

쉘에 접근할 경우 아래 명령어를 입력합니다.

docker exec -it alist ./alist admin random

그러면 아래와 같은 출력문 최하단에서 비밀번호를 확인할 수 있습니다.

INFO[2024-09-24 05:14:09] reading config file: data/config.json
INFO[2024-09-24 05:14:09] load config from env with prefix: ALIST_
INFO[2024-09-24 05:14:09] init logrus...
INFO[2024-09-24 05:14:09] admin user has been updated:
INFO[2024-09-24 05:14:09] username: admin
INFO[2024-09-24 05:14:09] password: 6Ukchjej

Portainer를 이용할 경우 Portainer에서 제공하는 콘솔 기능을 이용할 수도 있습니다.

만일, admin 계정의 비밀번호를 직접 정하고 싶다면, 아래 명령어를 사용해 설정할 수 있습니다.

./alist admin set {PASSWORD}

비밀번호를 확보했다면, IP:5244로 접속해 로그인을 진행할 수 있습니다.

설치는 간단하게 끝났습니다. 이제 구성할 차례입니다.

 

AList 설정

관리자 계정 설정

하단 중앙에 '관리'버튼을 클릭합니다.

관리자 로그인 비밀번호 및 계정명을 변경할 수 있습니다.

 

기본 설정

좌측의 설정 - 사이트를 클릭합니다.

기본적으로 마크다운을 이용해 입력할 수 있습니다.

예를 들어 사이트 공지란의 ### repo는 실제로 제목3으로 표시됩니다.

이는 로그인 시에 확인할 수 있습니다.

검색엔진에 노출시킬 필요는 없으므로 Robots.txt를 수정합니다.

User-agent: *
DisAllow: /

 

미리보기 탭에서 웹으로 재생할 미디어 형식을 지정할 수 있습니다.

여기에서 지정한 확장자는 AList자체 기능을 이용해 무려 웹에서 직접 재생을 할 수 있습니다. 별도의 설정이 없어도 같은 폴더 내에 자막이 있다면, 자막까지 함께 읽어옵니다. 아래처럼요.

 

저장소 설정

좌측의 저장소 탭을 클릭하면 AList에서 사용할 저장소를 살펴볼 수 있습니다.

현재는 구성한 저장소가 없으므로 추가 버튼을 클릭합니다.

구글 드라이브, 포토, 원드라이브, Seafile 등을 비롯해 바이두 등 어지간한 클라우드는 모두 지원하며 그 외에도 S3, SMB, FTP, SFTP, WebDAV 등도 자체적으로 지원합니다.

예시를 위해 TrueNAS의 SMB공유와 연결해 보겠습니다.

마운트 경로는 AList WEB UI상에서 보일 경로입니다. 구성을 완료하고 나면 test폴더 하위경로에 smb폴더가 보이고 그 폴더 내부에 삼바공유폴더의 내용이 보일 겁니다.

서명 사용은 AList에 연동한 스토리지를 WebDAV로 접근 시 ID/PW 인증을 사용할 것인지를 묻는 것으로, 체크해 주시면 됩니다.

Address와 Username, Password는 입력이 어렵지 않으나, Root Folder path와 Share name이 조금 헷갈릴 수 있는데,

Share name은 삼바공유명, Root folder path는 루트(/)로 사용할 하위 경로를 이야기합니다.

삼바공유명은 쉽게 말해 윈도우에서 네트워크로 접근 시 보이는 폴더들입니다. TrueNAS로 치면 왼쪽의 name이 윈도우에서 보이는 이름입니다.

리눅스의 smb.conf에서는 [ ] 괄호 안의 이름이 되겠죠.

따라서 media2 공유폴더를 그대로 Root folder로 사용하려 할 경우

• Root Folder path : .
• Share Name : media2

와 같이 입력해 주시면 됩니다.

이렇게 설정을 완료 후 홈으로 가보면, 아래와 같이 test폴더와 그 하위에 smb폴더를 확인할 수 있고, 그 안에서 삼바공유폴더의 내용물을 확인할 수 있습니다.

도로 위 빌런 신고내역 ㄷㄷ

만일 공유폴더의 특정 하위경로를 루트로 사용하려 한다면 Root Folder path의 경로를 변경하면 됩니다. 위 스샷의 villain/202409를 사용한다면

• Root folder path : villain/202409

가 됩니다.

그 외에 Local도 직접 사용할 수 있으므로, docker compose에서 마운트한 볼륨을 Local형식으로 등록해서 사용할 수도 있습니다.

 

인덱싱

좌측의 인덱스 탭에서 인덱싱을 설정할 수 있습니다. 맨 처음 생성시에는 인덱스 빌드 버튼을 통해 인덱스를 생성합니다.

인덱스 생성이 완료되면 아래처럼 인덱스 빌드 버튼이 재구축 버튼으로 바뀌고 현재 인덱스 현황이 나타납니다.

이와 동시에 홈 화면에 검색창이 나타나고, 검색 기능을 수행할 수 있게 됩니다.

 

SSO 구성

AList는 OIDC를 통한 SSO구성을 지원합니다. 공식 문서에 Authentik에 대한 설명은 없지만, GitHub Issue에서 힌트를 찾아 구성했습니다.

예시에서는 AList의 도메인을 https://alist.fentanest.com 으로 사용하겠습니다.

 

Authentik 설정

OAuth2/OpenID Provider를 생성합니다. 이름은 개별 환경에 따라 식별 가능한 수준에서 자유롭게 붙여주시면 됩니다.

리디렉션 URI/Origin은 https://alist.fentanest.com/api/auth/sso_callback?method=sso_get_token 주소를 사용해야 하는데, 이대로 사용할 경우 주소 중간의 '?' 기호가 이스케이프 처리 되지 않아 Invalid Redirect URI에러를 만나게 됩니다. 따라서, 아래처럼 입력해야 합니다.

https://alist.fentanest.com/api/auth/sso_callback\?method=sso_get_token

Subject모드는 WebDAV사용 등의 편의를 위해 사용자이름으로 합니다.

해당 공급자를 사용할 어플리케이션까지 생성해 둡니다.

 

AList SSO 설정

입력값 예시

• SSO 로그인 활성화 : 체크
• SSO 로그인 플랫폼 : OIDC
• SSO 클라이언트 ID : Authentik에서 생성한 공급자의 클라이언트ID
• SSO 클라이언트 비밀 : Authentik에서 생성한 공급자의 클라이언트 비밀
• SSO OIDC 사용자 이름 키 : sub
• SSO 조직 이름 : groups (혹은 생략)
• SSO 어플리케이션 이름 : 자유
• SSO 엔드포인트 이름 : Authentik 공급자의 OpenID 구성 발급자 주소
  https://{authentik}/application/o/{slug}
• SSO JWT 공개 키 : Authentik 공급자의 JWKS URL 주소
  https://{authentik}/application/o/{slug}/jwks
• SSO 자동 등록 : 체크(AList내에 계정이 없을 경우 자동 생성)
• SSO 기본 경로 : SSO를 통해 가입한 사용자의 기본 루트 폴더
• SSO 기본 권한 : 해당하는 권한의 숫자를 모두 더함(하단 스크린샷 참조)
• SSO 호환 모드 : 해제

 

여기까지 입력 후 저장을 클릭하고 로그아웃 해보면 우측 하단에 새로운 버튼이 나타납니다.

해당 버튼을 통해 Authentik으로 로그인할 수 있게 됩니다.

관리자는 SSO를 통해 생성된 계정의 권한을 확인할 수 있습니다.

SSO로 생성된 계정(아래 두 개)

 

Authentik과 OAuth/OIDC를 이용한 SSO 구축 글은 아래 링크들을 참조해 주세요.

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (1) – 설치

Authentik으로 홈서버 SSO 구현하기 (1) – 설치

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (3) – OAuth/OpenID

Authentik으로 홈서버 SSO 구현하기 (3) – OAuth/OpenID

 

WebDAV 이용하기

AList의 WebDAV이용방법은 굉장히 심플합니다.

• 주소 : https://도메인/dav
• ID/PW

두 가지를 이용해 연결할 수 있습니다. 예시를 위해 Raidrive로 연결해본다면, 아래와 같이 기입하면 됩니다.

 

마무리

웹 기반 파일 매니저이면서 UI도 깔끔하고 WebDAV기능도 제공하면서, 다양한 스토리지를 연결할 수도 있고, SSO통합도 가능한 앱을 찾는 것이 쉽지 않았는데, AList를 구성하고 사용하면서 정말 많이 만족하고 있습니다.

심지어 aria2나 qbittorrent를 이용해 파일을 다운로드 하고 완료된 파일을 특정 저장소로 이동하는 기능도 내재하고 있어 홈서버에서 다른 앱과 함께 사용 시 자동화 구축에도 많은 도움을 줄 수 있습니다.

유일한 단점은 공식 문서가 중국어라는 점과(영어도 있음), 앱 내의 한국어 번역이 어색해 이해하는데 시간을 필요로 한다는 점 정도....????

 

---

 

관련 글

2025.01.23 - [Apps] - Authentik으로 홈서버 SSO 구현하기 (3) – OAuth/OpenID

Authentik으로 홈서버 SSO 구현하기 (3) – OAuth/OpenID

 

---

 

출처

1. https://alist.nn.ci/guide/install/docker.html

Use Docker

2, https://github.com/alist-org/alist/discussions/7181

Authentik - SSO Settings · AlistGo alist · Discussion #7181

3. https://github.com/alist-org/alist/discussions/2215#discussioncomment-4104018

请问smb具体如何使用？ · AlistGo alist · Discussion #2215