3화. Seafile 13 메이저 업그레이드 실전 기록 — 이미지 태그만 바꾸면 깨진다

구글 드라이브·드롭박스 같은 파일 동기화 서비스를 내 서버에 만들어주는 오픈소스가 Seafile이다. 동기화 속도가 빠르기로 유명한 이 소프트웨어를 12 버전에서 13 버전으로 올리는 작업은, 겉보기와 달리 "이미지 태그를 바꾸고 재시작"으로 끝나지 않는다. 이 글은 Seafile의 소개와 신규 설치 방법, 그리고 실제로 메이저 업그레이드를 수행하며 부딪힌 문제들 — DB 환경변수 요구, 경로 구조 변경, 프록시 설정 — 을 순서대로 정리한 기록이다.

이런 때 유용합니다

• 회사 문서를 구글 드라이브에 두기 부담스러울 때. 파일은 내 서버의 디스크에만 존재한다.
• 수 GB짜리 영상·설계 파일을 매번 통째로 올리는 게 답답할 때. 변경된 부분만 전송하는 델타 동기화라 대용량 파일 갱신이 빠르다.
• 외부에 파일을 보낼 때마다 압축해서 메일로 보내는 게 번거로울 때. 만료일과 비밀번호를 걸 수 있는 공유 링크로 끝난다.
• 휴대폰 사진을 자동으로 백업하고 싶을 때. 앱을 설치하면 사진첩이 서버로 자동 동기화된다.
• 여러 PC에서 같은 작업 폴더를 쓸 때. 사무실 데스크톱과 집 노트북이 항상 같은 상태를 유지한다.

필요한 것은 서버와 디스크 공간뿐이다. 구독료는 없다.

Seafile은 어떤 프로그램인가

Seafile은 파일 동기화와 공유에 특화된 오픈소스 클라우드 스토리지 서버다. 구글 드라이브나 드롭박스처럼 PC·휴대폰에 클라이언트를 깔고 파일을 동기화하며, 웹UI에서 파일 관리와 공유 링크 생성이 가능하다. 데이터는 내 서버의 디스크에 쌓인다.

Nextcloud와 자주 비교되는데 성격이 다르다. Nextcloud는 파일 서버에 캘린더·연락처·오피스 등 수백 개 앱을 얹는 "종합 플랫폼"이고, Seafile은 동기화 속도와 대용량 파일 처리에 특화된 전문가다. Seafile의 델타 동기화는 수 GB짜리 파일에서 변경된 블록만 전송하므로, 대형 파일을 자주 갱신하는 작업 환경에서 체감 속도가 확연히 다르다.

주요 기능을 정리하면:

버전은 무료인 CE(Community Edition)와 유료인 PE(Pro)가 있는데, 소규모 사용자는 CE로 충분하다. 이 글도 CE 기준이다.

전체 구성

Seafile 13은 단일 컨테이너가 아니라 여러 컴포넌트의 조합이다.

flowchart LR
    U["브라우저 · PC/모바일 클라이언트"] --> CD["리버스 프록시 - Caddy/Nginx"]
    subgraph SRV["Docker 서버"]
        CD --> S["seafile 메인 - 웹UI와 파일서버"]
        S --> DB[("MariaDB - 사용자·메타데이터")]
        S --> R["Redis - 캐시"]
        S --> SD["Seadoc - 웹 문서 편집"]
        S --> NT["notification-server - 실시간 갱신"]
        S --> TH["thumbnail-server - 이미지 미리보기"]
        S --> DT[("seafile-data - 실제 파일 블록")]
    end

웹UI(Seahub)와 실제 파일 전송(seaf-server)이 한 컨테이너로 통합됐고, 문서 편집·알림·썸네일은 별도 컴포넌트로 분리됐다. 이 구조 변화가 13으로 올라갈 때 프록시 설정을 바꿔야 하는 이유다.

신규 설치 방법 (13 기준)

처음부터 설치하는 사람을 위한 최소 구성이다.

services:
  db:
    image: mariadb:11
    environment:
      MYSQL_ROOT_PASSWORD: "DB루트비밀번호"
      MYSQL_DATABASE: seahub_db
    volumes:
      - ./db:/var/lib/mysql

  seafile:
    image: seafileltd/seafile-mc:13.0-latest
    depends_on:
      - db
    environment:
      SEAFILE_MYSQL_DB_HOST: db
      SEAFILE_MYSQL_DB_USER: seafile
      SEAFILE_MYSQL_DB_PASSWORD: "DB비밀번호"
      SEAFILE_MYSQL_DB_CCNET_DB_NAME: ccnet_db
      SEAFILE_MYSQL_DB_SEAFILE_DB_NAME: seafile_db
      SEAFILE_MYSQL_DB_SEAHUB_DB_NAME: seahub_db
      SEAFILE_SERVER_HOSTNAME: files.example.com   # 접속 도메인
      SEAFILE_SERVER_PROTOCOL: https
    volumes:
      - ./data:/shared
    ports:
      - "8080:80"

설치 절차: ①위 파일로 기동 ②웹UI 접속해 관리자 계정 생성 ③도메인을 붙일 거면 리버스 프록시로 8080을 연결 ④파일 업로드·다운로드 실제 테스트. 여기서 주목할 점은 DB 접속 정보가 환경변수로 명시된다는 것 — 이것이 12와의 결정적 차이이며, 업그레이드의 핵심 주제다.

업그레이드 전에 반드시 할 것

1. seafile-data 디렉터리 전체 백업 — 실제 파일 블록이 여기 있다.
2. 데이터베이스 덤프 — 마이그레이션이 DB 스키마를 건드린다. 덤프 후 반드시 읽히는지 검증까지.
3. 현재 버전·확장 컴포넌트 목록 기록.

메이저 업그레이드의 롤백은 "백업 시점으로 되돌리기"가 유일하다. 스키마가 한 단계 올라간 뒤에는 13 전용 데이터가 되기 때문이다. 백업이 전부다.

실전 기록 — 여기서 막히는다

1) DB 환경변수가 필수가 됐다

12까지는 컨테이너가 DB 접속 정보를 기존 conf 파일에서 읽었지만, *13은 환경변수 `SEAFILE_MYSQLDB`를 요구한다.** 위 신규 설치 예시에 나온 여섯 개 변수를 업그레이드 시에도 그대로 넣어야 마이그레이션이 동작한다.

이걸 빼먹으면 증상이 교묘하다. 컨테이너는 멀쩡히 running 상태인데, 로그에 DB 오류가 반복되고 웹UI가 열리지 않는다. "컨테이너는 살았는데 서비스가 죽었다"면 제일 먼저 환경변수를 본다.

2) 파일 전송 경로가 통합됐다

12까지는 웹 트래픽과 파일 전송 트래픽(/seafhttp)이 별도 경로로 갈랐고, 리버스 프록시에도 그 라우트가 따로 있었다. 13부터는 파일 전송이 단일 엔드포인트로 통합됐다. 그래서 옛 프록시 설정은 제거해야 한다:

# 12 스타일 — 13에서는 제거해야 한다
handle_path /seafhttp/* {
    reverse_proxy seafile:80
}

도메인 전체를 seafile의 통합 포트(80)로 넘기는 단순 구성이 13의 정답이다. 증상으로는 "웹UI는 열리는데 파일 업로드·다운로드만 실패"가 대표적이다.

3) 프록시 설정을 고쳤는데 증상이 그대로다

Caddyfile을 새로 쓰고 컨테이너를 재시작했는데도 옛 동작을 하는 경우가 있었다. 원인은 설정 파일이 이미지 빌드 시점에 복사되어 컨테이너 내부에 굳어 있었기 때문. 이런 경우 restart가 아니라 재생성(down 후 up)이 필요하다. "분명히 고쳤는데 왜 같지"의 상당수가 이것이다.

4) 확장 컴포넌트

13의 쾌적한 사용을 위해서는 컴포넌트 세 개를 추가로 띄우는 것이 좋다.

업그레이드 점검 목록

1. 데이터+DB 백업 (덤프 검증까지)
2. SEAFILE_MYSQL_DB_* 환경변수 여섯 개 추가
3. 프록시에서 /seafhttp 라우트 제거, 단일 프록시로 통합
4. 메인 컨테이너 기동 → 로그에서 마이그레이션 완료 확인
5. 웹UI 로그인 → 파일 업로드/다운로드 실제 테스트 (웹UI만 열리면 통과가 아니다)
6. Seadoc·알림·썸네일 기동 및 기능 테스트
7. 클라이언트(PC/모바일) 동기화까지 확인

트러블슈팅 정리

자주 묻는 질문

마이너 업데이트(13.0.x)도 이렇게 해야 하나?

아니오. 이 과정은 메이저(12→13)에서만 필요하다. 이후 마이너 업데이트는 이미지 태그 교체와 재생성으로 끝난다. 단 백업은 항상.

Nextcloud 대신 Seafile을 고를 이유는?

동기화 속도와 대용량 파일 처리다. 델타 동기화 덕분에 큰 파일을 다루는 환경에서 체감 차이가 크다. 반대로 캘린더·연락처·수백 개의 앱 생태계를 원하면 Nextcloud가 맞다. 용도를 파일에 두면 Seafile이 답인 경우가 많다.

업그레이드 실패 시 서비스를 살릴 수 있나?

백업해둔 데이터 디렉터리+DB 덤프로 12 상태 복구는 가능하다. 단 마이그레이션이 실행된 데이터는 13 전용이므로, 롤백은 반드시 백업 시점으로 돌아가는 방식이다. 그래서 백업 검증이 절차의 1단계다.

서버 한 대로 충분하다 연재 목차 — 시리즈 소개 · 1화. Home Assistant · 2화. Frigate + go2rtc

CE 에디션 기준, 실제 운영 서버에서 다운타임 최소화를 목표로 수행한 업그레이드 기록입니다.