서버 운영
저장소, 백업, 한도
Oleafly Server의 모든 설정, 디스크나 S3 버킷에 파일 저장하기, 컴파일된 PDF, 프록시 뒤에서 실행하기, 한 네트워크의 수업과 각 계정을 위한 한도, 로그, 백업, 복원, 업데이트.
이 페이지는 Oleafly Server를 일상적으로 운영하는 방법을 다룹니다. 설치하려면 공동 작업 서버 운영하기에서 시작하세요.
서버는 환경 변수에서 설정을 읽습니다. 설정은 되어 있지만 비어 있는 변수는 설정되지 않은 것으로 칩니다. 설정이 없거나 형식이 잘못되면 서버가 시작되지 않으며, 로그에 어느 설정인지 나옵니다.
| 변수 | 하는 일 | 기본값 |
|---|---|---|
OLEAFLY_PUBLIC_URL | 사람들이 Oleafly에 입력하는 HTTPS 주소. https://www.cs.example.edu/oleafly처럼 경로를 포함할 수 있습니다. 필수입니다. Compose와 Coolify 파일이 대신 설정해 줍니다. | 없음 |
OLEAFLY_BIND | 서버가 듣는 주소와 포트. | 0.0.0.0:8080 |
OLEAFLY_DATA_DIR | 데이터베이스와 저장된 파일을 두는 폴더. | /data |
OLEAFLY_SERVER_NAME | Oleafly에서 사람들에게 보이는 이름. 예를 들면 Smith Lab. | Oleafly Server |
OLEAFLY_SERVER_ICON_URL | 이름 옆에 표시할 정사각형 이미지의 HTTPS 주소. | 없음 |
OLEAFLY_SETUP_CODE | 직접 정하는 일회용 설정 코드. 문자나 숫자 12자 이상이며 원하면 대시나 공백을 넣을 수 있습니다. 없으면 서버가 하나 만듭니다. | 자동 생성 |
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRET | GitHub 로그인을 켭니다. | 꺼짐 |
OLEAFLY_GITHUB_URL | GitHub Enterprise Server의 주소. | https://github.com |
OLEAFLY_GITHUB_API_URL | GitHub API 주소(일반적이지 않은 경우). | https://api.github.com, 또는 OLEAFLY_GITHUB_URL 아래의 /api/v3 |
OLEAFLY_GITHUB_LABEL | GitHub 로그인 버튼의 텍스트. | GitHub |
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRET | <NAME>이라는 OpenID Connect 제공자를 켭니다. | 꺼짐 |
OLEAFLY_OIDC_<NAME>_LABEL | 그 제공자의 로그인 버튼 텍스트. 예를 들면 University login. | <NAME> |
OLEAFLY_OIDC_<NAME>_TRUST_EMAIL | 이 제공자의 모든 이메일 주소를 인증된 것으로 취급합니다. 먼저 인증된 이메일 주소를 읽어 보세요. | false |
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROM | 이메일. 이메일을 읽어 보세요. | 꺼짐 |
OLEAFLY_OPEN_SIGNUP | 내가 설정한 제공자 중 하나로 로그인하는 사람 누구에게나 멤버 계정을 줍니다. 공개 가입을 읽어 보세요. | false |
OLEAFLY_WEB | 브라우저 접근을 켭니다. 브라우저 접근을 읽어 보세요. | false |
OLEAFLY_BLOB_STORE | 그림이나 PDF 같은 파일을 저장하는 위치. fs는 OLEAFLY_DATA_DIR에 보관합니다. s3://lab-bucket이나 s3://lab-bucket/oleafly 같은 주소는 버킷에 보관합니다. | fs |
OLEAFLY_S3_ENDPOINT | MinIO나 Cloudflare R2처럼 Amazon S3가 아닌 S3 호환 저장소의 주소. Amazon S3라면 비워 둡니다. | Amazon S3 |
OLEAFLY_S3_REGION | 버킷의 리전. | us-east-1 |
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEY | 서버가 버킷에 쓰는 키. s3:// 주소를 쓰면 필수입니다. | 없음 |
OLEAFLY_MAX_PROJECT_MB | 서버가 받는 가장 큰 프로젝트 크기(MB). | 200 |
OLEAFLY_MAX_FILE_MB | 파일 하나의 최대 크기(MB). | 50 |
OLEAFLY_MAX_MEMBERS_PER_PROJECT | 한 프로젝트의 최대 인원. | 20 |
OLEAFLY_ACCOUNT_STORAGE_MB | 한 계정이 소유한 프로젝트가 저장할 수 있는 최대 용량(MB). 계정별 한도를 읽어 보세요. | 한도 없음, 공개 가입이면 100 |
OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | 한 계정이 소유할 수 있는 최대 공유 프로젝트 수. | 한도 없음, 공개 가입이면 50 |
OLEAFLY_UPLOADS_PER_HOUR | 한 계정이 한 시간에 할 수 있는 파일과 스냅숏 업로드 수. | 한도 없음, 공개 가입이면 300 |
OLEAFLY_SIGN_IN_BURST | 한 네트워크 주소가 순간적으로 보낼 수 있는 로그인 요청 수. 로그인 한 번에 요청이 약 여섯 번 들어가므로, 기본값은 한 주소의 50명이 동시에 로그인하는 경우를 감당합니다. | 300 |
OLEAFLY_SIGN_IN_PER_MINUTE | 순간 허용량을 쓴 뒤 한 네트워크 주소가 매분 회복하는 로그인 요청 수. | 120 |
OLEAFLY_EMAIL_LINKS_PER_IP | 서버가 15분 동안 한 네트워크 주소의 사람들에게 보내는 로그인 메일 수. | 100 |
OLEAFLY_EMAIL_LINKS_PER_ADDRESS | 이메일 주소 하나가 15분 동안 받을 수 있는 로그인 메일 수. OLEAFLY_EMAIL_LINKS_PER_IP보다 클 수 없습니다. | 3 |
OLEAFLY_DEVICE_CODES_PER_IP | 한 네트워크 주소의 사람들이 10분 동안 요청할 수 있는 로그인 코드 수. | 100 |
OLEAFLY_SNAPSHOT_MEMORY_MB | 서버가 프로젝트 스냅숏을 만드는 데 쓸 수 있는 메모리(MB). | 컨테이너 메모리 한도의 절반, 한도가 없으면 1024 |
OLEAFLY_BEHIND_PROXY | 프록시가 추가한 X-Forwarded-For 헤더에서 각 사람의 주소를 가져옵니다. Compose, Coolify, Render 파일은 이 값을 켭니다. | false |
OLEAFLY_PROXY_HOPS | 요청이 서버에 도달하기 전에 거치는 프록시의 수. OLEAFLY_BEHIND_PROXY=true가 필요합니다. | 1 |
OLEAFLY_LOG_LEVEL | 서버가 기록하는 로그의 양: error, warn, info, debug, trace. 서버가 쓰는 라이브러리는 debug나 trace를 고르지 않으면 경고만 기록합니다. | info |
OLEAFLY_SECURITY_LOG_DAYS | 보안 로그 항목, 프로젝트 접근 로그 항목, 응답했거나 만료된 게스트 초대를 보관하는 일수. | 365 |
OLEAFLY_ARCHIVE_DAYS | 소유자가 공유를 중지한 프로젝트를 보관하는 일수. | 30 |
OLEAFLY_POLL_HOLD_SECONDS | 대기 중인 편집이 없을 때 서버가 롱 폴링 요청을 열어 두는 시간(1초에서 40초). 서버 앞에 있는 프록시의 유휴 제한 시간보다 몇 초 짧게 두세요. | 25 |
Compose .env 파일에서는 값에 $나 #이 들어 있으면 작은따옴표로 감쌉니다. 시크릿을 담는 설정은 파일에서 읽을 수도 있습니다. .env에 시크릿 두지 않기를 읽어 보세요.
저장소
섹션 제목: “저장소”기본적으로 서버는 모든 것을 OLEAFLY_DATA_DIR에 보관합니다. 데이터베이스, 사람들이 공유하는 파일, 프로젝트 스냅숏입니다. 스냅숏은 각 프로젝트의 저장된 사본으로, 사람들이 빠르게 참여하고 따라잡게 해 줍니다.
버킷에 파일 두기
섹션 제목: “버킷에 파일 두기”서버는 파일과 스냅숏을 대신 Amazon S3에 보관할 수 있고, MinIO나 Cloudflare R2처럼 S3 호환 API를 가진 다른 저장소에도 보관할 수 있습니다. 어느 쪽이든 데이터베이스는 OLEAFLY_DATA_DIR에 남으므로 서버에는 여전히 데이터 폴더가 필요합니다.
-
버킷을 만들고 공개 접근을 차단합니다.
-
그 버킷의 객체를 읽고, 쓰고, 삭제할 수 있고 그 밖에는 아무것도 할 수 없는 키를 만듭니다. Amazon S3에서는
arn:aws:s3:::lab-bucket/*에 대한s3:GetObject,s3:PutObject,s3:DeleteObject이며, 폴더를 쓴다면arn:aws:s3:::lab-bucket/oleafly/*에 대한 것입니다. -
예를 들어
.env에 변수를 설정합니다.터미널 창 OLEAFLY_BLOB_STORE=s3://lab-bucket/oleaflyOLEAFLY_S3_REGION=eu-west-1OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-idOLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key
Amazon S3가 아닌 저장소라면 OLEAFLY_S3_ENDPOINT도 https://minio.example.org:9000이나 https://<account-id>.r2.cloudflarestorage.com 같은 그 주소로 설정하고, OLEAFLY_S3_REGION은 그 저장소가 기대하는 리전(R2는 auto)으로 설정하세요. 일반 http://도 동작하지만, 저장소가 서버와 같은 사설 네트워크에 있을 때만 쓰세요.
버킷 이름 뒤의 부분은 선택 사항인 폴더입니다. 각 파일은 SHA-256 해시를 이름으로 삼고 해시의 앞 두 글자 아래에 놓이므로, 해시가 3f9a로 시작하는 파일은 oleafly/3f/3f9a...로 저장됩니다. 스냅숏은 프로젝트마다 폴더가 있는 자체 snapshots 폴더를 씁니다. 서버는 파일이나 스냅숏을 다시 읽을 때 바이트를 해시와 대조해 확인하고, 일치하지 않으면 거부합니다. 버킷이 없으면 같은 구조가 OLEAFLY_DATA_DIR 안의 blobs 폴더에 있습니다.
버킷이 요청을 거부하면 그 업로드나 다운로드는 실패하고, 서버 로그에 403 Forbidden (AccessDenied)처럼 버킷이 답한 내용이 나타납니다. 서버 오류, 시간 초과, 끊긴 연결은 다릅니다. 서버가 사이에 짧은 무작위 간격을 두고 최대 세 번 시도합니다. 객체를 삭제하지 못하면 그 사실을 기록하고, 6시간마다 하는 유지 보수 때마다 다시 시도하므로, 장애가 나도 객체가 남지 않습니다.
스냅숏과 메모리
섹션 제목: “스냅숏과 메모리”프로젝트를 공유하면 소유자의 앱이 첫 스냅숏을 업로드하고 그 기기의 키로 서명합니다. 그때부터 서버는 이전 스냅숏과 그 뒤에 사람들이 보낸 변경을 바탕으로 모든 스냅숏을 직접 만듭니다. 마지막 스냅숏 이후 프로젝트에 변경이 1,000개 쌓이면 새 스냅숏을 만듭니다. 서버는 항상 최소한 최근 변경 2,000개를 보관하므로, 잠깐 자리를 비웠던 기기는 그 변경으로 따라잡을 수 있고 프로젝트 전체를 다시 내려받지 않습니다.
스냅숏을 만들려면 이전 스냅숏 크기의 약 열 배에 그 뒤의 변경을 더한 만큼의 메모리가 필요합니다. 서버는 OLEAFLY_SNAPSHOT_MEMORY_MB에 들어가는 빌드만 시작하며, 동시에 실행되는 빌드는 그 양을 나눠 씁니다. 빌드가 맞지 않으면 서버는 그 빌드를 건너뛰고, 필요한 메모리 양을 기록하고, 프로젝트의 변경을 모두 보관합니다. 그러면 기기들은 그 변경으로 한 번에 몇 MB씩 따라잡습니다. 설정을 올리면 다음 스냅숏이 만들어집니다. 서버는 OLEAFLY_MAX_PROJECT_MB보다 큰 스냅숏은 저장하지 않습니다.
컴파일된 PDF
섹션 제목: “컴파일된 PDF”소유자나 편집자가 공유 프로젝트를 성공적으로 컴파일하면 그 사람의 앱이 PDF를 서버로 보내며, SyncTeX 파일이 있으면 함께 보냅니다. 프로젝트마다 1분에 최대 한 번 보냅니다. 서버는 프로젝트마다 PDF 하나와 SyncTeX 파일 하나를 주 파일 이름, 컴파일한 사람, 컴파일한 시각과 함께 보관합니다. 브라우저 접근은 프로젝트의 사람들에게 이 PDF를 보여 줍니다.
새로 올라온 파일은 이전 파일을 대체하며, 이전 파일은 쓰는 곳이 없어지면 삭제됩니다. 컴파일된 파일은 다른 파일과 함께 디스크나 버킷에 저장되고, 프로젝트와 함께 삭제됩니다. 컴파일된 파일은 최대 OLEAFLY_MAX_FILE_MB까지 클 수 있습니다. 소유자의 계정 저장 용량에는 포함되지만, 시간당 업로드 수에는 포함되지 않습니다.
프로젝트의 모든 참여자가 컴파일된 파일을 읽을 수 있습니다. 파일을 바꿀 수 있는 사람은 소유자와 편집자뿐입니다.
리버스 프록시 뒤에서
섹션 제목: “리버스 프록시 뒤에서”서버는 평문 HTTP로 통신하므로 앞단의 무언가가 HTTPS를 처리합니다. Compose 설정의 Caddy, Coolify의 프록시, 또는 대학의 웹 서버처럼 이미 운영하는 웹 서버입니다. 앞단에 있는 것은 다음을 해야 합니다.
OLEAFLY_MAX_PROJECT_MB크기까지의 요청을 받는다- 클라이언트의 주소를
X-Forwarded-For에 추가한다
또한 WebSocket 업그레이드를 /ws로 통과시키고 그 연결을 최소한 한 시간 동안 열어 두어야 합니다. 실시간 편집은 가능하면 WebSocket을 씁니다. 브라우저 접근이 켜져 있으면 /web/ws로도 통과시켜야 합니다. 브라우저 앱에는 더 느린 대체 경로가 없기 때문입니다.
프록시만 접근할 수 있는 곳에서 서버를 실행하세요. 같은 장비에서는 OLEAFLY_BIND=127.0.0.1:8080으로 설정합니다. 그런 다음 OLEAFLY_BEHIND_PROXY=true를 설정합니다.
WebSocket 연결이 차단될 때
섹션 제목: “WebSocket 연결이 차단될 때”일부 네트워크는 WebSocket 연결을 차단합니다. 필터링 프록시가 있는 대학이나 회사 네트워크가 흔히 그렇습니다. 그런 곳에서도 실시간 편집은 더 느리게나마 동작합니다. 서버가 HTTPS로는 여전히 응답하는데 WebSocket 시도가 연달아 두 번 실패하면, Oleafly는 HTTP 롱 폴링으로 전환합니다. 편집은 /api/v1/projects/<project>/frames로 보내고, 다른 사람의 편집은 /api/v1/projects/<project>/poll에서 기다리며, 각 요청을 최대 OLEAFLY_POLL_HOLD_SECONDS 동안 열어 둡니다. 모든 편집은 그대로 도착합니다. Oleafly는 1분마다 WebSocket을 다시 시도하고, 연결되는 즉시 WebSocket으로 돌아갑니다.
이런 상황이 되면 Oleafly의 연결 테스트와 관리 콘솔의 연결 점검이 알려 줍니다. “이 네트워크가 일반 경로를 차단해서 실시간 편집이 더 느린 경로로 전달됩니다. 편집은 그래도 도착합니다.”
서버 앞에 프록시를 직접 운영한다면 WebSocket 업그레이드를 그래도 통과시키세요. 롱 폴링도 동작하지만, 편집 묶음마다 요청이 하나 더 들고 지연이 조금 늘어납니다.
일부 프록시는 30초 미만 동안 조용한 요청을 닫습니다. 짧은 proxy_read_timeout을 쓰는 nginx가 한 예입니다. 이런 프록시는 롱 폴링 요청에 502나 504 오류로 응답하고, 편집이 늦게 도착합니다. OLEAFLY_POLL_HOLD_SECONDS를 그 제한 시간보다 몇 초 짧게 설정하세요. 제한 시간이 10초라면 8처럼 설정합니다.
OLEAFLY_BEHIND_PROXY가 바꾸는 것
섹션 제목: “OLEAFLY_BEHIND_PROXY가 바꾸는 것”서버는 두 곳에 클라이언트 주소를 기록합니다. 보안 로그와, 한 주소가 로그인을 시작하거나 실시간 연결을 열 수 있는 빈도에 대한 한도입니다.
이 설정이 없으면 서버는 자기에게 연결한 대상의 주소를 씁니다. 프록시 뒤에서는 그 대상이 항상 프록시이므로, 모든 사람이 하나의 한도를 공유하고 보안 로그에는 프록시의 주소만 나타납니다.
OLEAFLY_BEHIND_PROXY=true이면 서버는 X-Forwarded-For 헤더를 읽고 그 안의 마지막 주소, 즉 프록시가 추가한 주소를 씁니다. 헤더가 없거나 올바른 주소가 없으면 서버는 연결한 주소로 되돌아갑니다. 그 밖에 바뀌는 것은 없습니다. 서버는 X-Forwarded-Proto, X-Forwarded-Host, Forwarded를 무시하고, 내보내는 모든 주소를 OLEAFLY_PUBLIC_URL로 만듭니다.
모든 요청이 프록시를 거칠 때만 켜세요. 사람들이 서버에 직접 접근할 수도 있다면 누구나 지어낸 X-Forwarded-For를 보내 보안 로그에 아무 주소나 남기고 로그인 한도를 피할 수 있습니다.
Cloudflare가 Coolify의 프록시 앞에 있는 경우처럼 프록시가 연달아 둘이면 OLEAFLY_PROXY_HOPS=2로 설정하세요. 그러면 서버는 끝에서 두 번째 주소를 씁니다. 모든 요청이 거치는 프록시만 세세요. 서버로 바로 이어지는 Cloudflare Tunnel은 하나로 칩니다.
숫자를 확인하려면 내 컴퓨터에서 로그인한 다음 관리 콘솔의 보안 로그를 여세요. 가장 최근 항목에 ifconfig.me 같은 사이트가 알려 주는 내 공인 주소가 나타나야 합니다. 대신 사설 주소나 Cloudflare 주소가 나타나면 OLEAFLY_PROXY_HOPS를 하나 올리세요.
Caddy
섹션 제목: “Caddy”Caddy는 추가 설정 없이 WebSocket 연결과 X-Forwarded-For를 통과시키고 인증서도 직접 받습니다. Caddyfile 전체는 앞단에 HTTPS 두기에 있습니다.
nginx
섹션 제목: “nginx”먼저 certbot 등으로 도메인의 인증서를 받으세요. 그런 다음 이것을 /etc/nginx/conf.d/oleafly.conf로 저장하고 sudo nginx -t && sudo systemctl reload nginx를 실행하세요.
map $http_upgrade $connection_upgrade { default upgrade; '' close;}
server { listen 443 ssl; server_name collab.example.org; ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;
location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header X-Forwarded-For $remote_addr; proxy_read_timeout 1h; proxy_send_timeout 1h; client_max_body_size 200m; }}client_max_body_size는 기본값인 OLEAFLY_MAX_PROJECT_MB 200과 맞춘 것입니다. 하나를 올리면 다른 하나도 올리세요.
Apache
섹션 제목: “Apache”Apache 2.4.47 이상이 필요하며, Debian 12와 Ubuntu 22.04 이후 버전에 있습니다. 모듈을 켭니다.
sudo a2enmod proxy proxy_http ssl이것을 /etc/apache2/sites-available/oleafly.conf로 저장한 다음 sudo a2ensite oleafly && sudo systemctl reload apache2를 실행하세요.
<VirtualHost *:443> ServerName collab.example.org SSLEngine on SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem
ProxyPreserveHost On ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600 ProxyPassReverse / http://127.0.0.1:8080/</VirtualHost>upgrade=websocket은 WebSocket 연결을 통과시키고 timeout=3600은 연결을 한 시간 동안 열어 둡니다. Apache는 클라이언트 주소를 X-Forwarded-For에 알아서 추가합니다.
경로 아래에서 실행하기
섹션 제목: “경로 아래에서 실행하기”서버가 경로 아래에 있다면 OLEAFLY_PUBLIC_URL에 https://www.cs.example.edu/oleafly처럼 그 경로를 포함하고, 로그인 제공자에 등록하는 콜백 주소에도 포함하세요. 서버는 그 경로가 있든 없든 모두 응답하므로, 프록시가 경로를 그대로 넘기거나 제거해도 됩니다. nginx에서는 안에 같은 줄을 두고 location /oleafly/ {를 쓰며, nginx가 경로를 그대로 넘기도록 proxy_pass http://127.0.0.1:8080;은 경로 없이 둡니다.
한 네트워크의 수업을 위한 한도
섹션 제목: “한 네트워크의 수업을 위한 한도”수업 전체가 대학의 NAT처럼 하나의 네트워크 주소에서 로그인하는 경우가 많습니다. 기본값은 이에 맞춰져 있습니다.
- 로그인: 한 주소는 로그인 요청 300개를 순간적으로 보낼 수 있고, 그 뒤에는 초당 두 개입니다. 로그인 한 번에 요청이 약 여섯 번 들어가므로 50명이 동시에 로그인할 수 있습니다.
OLEAFLY_SIGN_IN_BURST와OLEAFLY_SIGN_IN_PER_MINUTE로 바꿉니다. - 이메일 링크: 한 주소에 15분 동안 100개, 이메일 주소 하나에 3개.
OLEAFLY_EMAIL_LINKS_PER_IP와OLEAFLY_EMAIL_LINKS_PER_ADDRESS로 바꿉니다. - 로그인 코드: 한 주소에서 10분 동안 코드 100개와 틀린 코드 10개.
OLEAFLY_DEVICE_CODES_PER_IP로 바꿉니다. - 실시간 연결에는 더 큰 별도 한도가 있어서, 한 주소 뒤에 있는 수업 전체가 재시작 뒤에 한꺼번에 다시 연결할 수 있습니다. 세션을 증명하지 못하는 연결만 이 한도를 소모합니다. 순간 300개, 그 뒤에는 초당 열 개입니다. 세션을 증명하는 연결은 대신 그 기기의 한도에 포함되며, 순간적으로 60번 다시 연결할 수 있고 그 뒤에는 초당 한 번입니다.
하나의 /64 네트워크에 있는 모든 IPv6 주소는 한 주소로 칩니다. 이 한도는 서버가 각 사람의 실제 주소를 볼 수 있어야 사람별로 동작하므로, 프록시를 올바르게 설정하세요.
서버는 30초마다 각 실시간 연결에 핑을 보냅니다. 핑에 90초 동안 응답하지 않는 연결과 서버가 보내는 내용을 읽지 않는 연결은 닫습니다.
프로젝트 한도는 모든 사람에게 적용됩니다. 프로젝트 전체는 OLEAFLY_MAX_PROJECT_MB(기본 200 MB), 파일 하나는 OLEAFLY_MAX_FILE_MB(50 MB), 한 프로젝트의 인원은 OLEAFLY_MAX_MEMBERS_PER_PROJECT(20)입니다. 관리 콘솔의 개요에서 현재 한도를 볼 수 있습니다.
계정별 한도
섹션 제목: “계정별 한도”계정마다 한도 세 가지가 적용됩니다. 직접 설정하기 전에는 꺼져 있지만, 공개 가입이 켜져 있으면 다음 기본값으로 켜집니다.
| 한도 | 설정 | 공개 가입일 때 |
|---|---|---|
| 계정이 소유한 프로젝트의 저장 용량 | OLEAFLY_ACCOUNT_STORAGE_MB | 100 MB |
| 계정이 소유한 공유 프로젝트 | OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | 50 |
| 계정이 한 시간에 하는 업로드 | OLEAFLY_UPLOADS_PER_HOUR | 300 |
직접 설정한 값이 항상 기본값보다 우선합니다. 각 값은 1 이상의 정수여야 합니다.
- 저장 용량은 계정이 소유한 모든 프로젝트(보관된 프로젝트 포함)의 파일과 변경 이력, 그리고 그 프로젝트의 컴파일된 PDF를 합산합니다. 스냅숏은 포함되지 않습니다. 누가 프로젝트에 파일을 추가하든 프로젝트 소유자의 용량으로 계산됩니다. 소유자의 계정이 가득 차면 서버는 그 소유자의 프로젝트에 새 파일과 컴파일된 PDF를 받지 않으며, 소유자는 다른 프로젝트를 공유할 수 없습니다. 파일은 추가한 사람의 컴퓨터에 남습니다. 사람들이 입력하는 텍스트는 계속 동기화됩니다.
- 공유 프로젝트는 계정이 공유하는 프로젝트를 셉니다. 아직 업로드 중인 프로젝트도 포함됩니다. 보관된 프로젝트는 포함되지 않으므로, 프로젝트 하나의 공유를 중지하면 자리가 생깁니다.
- 업로드는 한 시간 동안의 모든 파일과 스냅숏 업로드를 셉니다. 컴파일된 PDF는 포함되지 않습니다. 거부된 파일은 Oleafly가 나중에 알아서 다시 보냅니다.
관리 콘솔의 개요에는 이 한도가 표시되지 않습니다. 공개 가입이 켜져 있으면 서버 로그가 시작할 때마다 한도를 알려 줍니다.
- 서버 로그는
docker compose logs oleafly-server, Coolify의 Logs,journalctl -u oleafly-server가 보여 주는 것입니다. 얼마나 많이 기록할지는OLEAFLY_LOG_LEVEL이 정합니다. - 보안 로그는 로그인과 거부된 로그인, 기기, 사람, 역할, 설정, 프로젝트, 게스트를 각각 시각과 IP 주소와 함께 기록합니다. 관리자와 유지 관리자는 관리 콘솔의 보안 로그에서 읽습니다.
OLEAFLY_SECURITY_LOG_DAYS일보다 오래된 항목은 삭제됩니다. - 프로젝트 접근 로그는 누가 프로젝트를 열고, 참여하고, 사본을 내려받았는지를 기기 이름과 시각과 함께 기록합니다. 프로젝트 접근 로그 허용이 켜져 있을 때 프로젝트 소유자가 켜며, 그 소유자만 읽을 수 있습니다. 같은 보관 기간이 적용됩니다.
전체 백업에 무엇이 필요한지는 파일이 저장된 위치에 따라 다릅니다.
- 디스크의 파일(
OLEAFLY_BLOB_STORE=fs, 기본값): 데이터베이스, 파일, 스냅숏이 모두 데이터 폴더에 있습니다. 폴더 전체를 백업하세요. - 버킷의 파일: 데이터 폴더에는 데이터베이스가 있고 버킷에는 파일과 스냅숏이 있습니다. 데이터베이스 사본과 버킷이 합쳐져 전체 백업입니다. 실수로 삭제한 객체를 되살릴 수 있도록 버킷의 버전 관리를 켜세요.
정기적으로 백업하고 사본은 비공개로 보관하세요. 사본에 모든 프로젝트가 들어 있기 때문입니다. .env 같은 설정은 데이터 폴더에 없으므로 설정의 사본도 따로 보관하세요.
Docker에서는 볼륨을 복사하는 몇 초 동안 서버가 멈춥니다. Oleafly는 저절로 다시 연결됩니다. 이 명령은 서버 폴더에서 실행하세요. 설치 프로그램을 썼다면 /opt/oleafly-server입니다.
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .sudo docker compose start oleafly-serversystemd에서는 다음과 같습니다.
sudo systemctl stop oleafly-serversudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .sudo systemctl start oleafly-server아카이브를 다른 장비에 복사하세요.
Coolify에서는 볼륨 이름이 리소스의 ID로 시작합니다. docker volume ls --filter name=oleafly-data로 찾아서 oleafly-server_oleafly-data 대신 쓰고, 서버는 docker compose 대신 Coolify 대시보드에서 멈추고 시작하세요.
복원 연습
섹션 제목: “복원 연습”한 번도 복원해 보지 않은 백업은 희망에 불과합니다. 이 연습은 백업으로 서버의 두 번째 사본을 시작하고, 실행 중인 서버는 건드리지 않고, 둘이 같은 서버인지 확인합니다. 2026-10-11 대신 내 아카이브의 날짜를 쓰세요.
cd /opt/oleafly-serversudo docker volume create oleafly-restore-drillsudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gzsudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-servercurl -fsS https://collab.example.org/.well-known/oleafly-server두 응답의 server_id가 일치해야 합니다. 연습용 사본에는 누구도 로그인시킬 수 없는 임시 GitHub 로그인이 있고 열린 포트도 없어서 아무도 사용할 수 없습니다. 끝나면 제거하세요.
sudo docker rm -f oleafly-restore-drillsudo docker volume rm oleafly-restore-drillDocker Compose에서 실제로 복원하려면 서버를 멈추고, 볼륨의 내용을 아카이브로 바꾸고, 다시 시작하세요.
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'sudo docker compose start oleafly-serversystemd에서는 다음과 같습니다.
sudo systemctl stop oleafly-serversudo find /var/lib/private/oleafly-server -mindepth 1 -deletesudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gzsudo systemctl start oleafly-server복원된 서버에는 백업 이후에 사람들이 한 변경이 없습니다. 각 앱은 앱이 계속 열려 있었든 나중에 열었든 다시 연결될 때 이를 알아차리고 자기가 가진 누락된 변경을 다시 보냅니다. 이를 위해 아무도 할 일이 없습니다. 다른 사람의 누락된 변경 위에 쌓인 변경은 그 사람이 프로젝트를 열 때까지 기다립니다. 그 사람의 변경은 그 사람의 앱만 보낼 수 있기 때문입니다. 장애 시점 전후에 편집하던 모든 사람에게 프로젝트를 한 번 열어 달라고 요청하세요.
Litestream으로 연속 복사하기
섹션 제목: “Litestream으로 연속 복사하기”아카이브에는 만든 시점에 있던 것만 들어 있습니다. Litestream (새 탭에서 열림)은 서버 데이터베이스의 모든 변경을 일어난 지 1초쯤 뒤에 S3 호환 버킷으로 복사합니다. Compose 파일에는 선택 사항인 서비스로 들어 있습니다.
Litestream은 데이터베이스만 복사합니다. 파일이 버킷에 있다면 버킷에 이미 파일과 스냅숏이 있으므로, Litestream 사본과 버킷이 합쳐져 잃어버린 디스크를 되살릴 수 있습니다. 파일이 디스크에 있다면 Litestream이 blobs 폴더를 복사하지 않으므로 볼륨 아카이브도 계속 만드세요.
-
이 서버의 Litestream만 쓰는 버킷이나 버킷 안의 폴더를 만듭니다.
OLEAFLY_BLOB_STORE와 공유하지 마세요. Litestream에 버킷을 나열하고 그 안의 객체를 읽고, 쓰고, 삭제할 수 있는 키를 줍니다. -
.env에 정보를 추가합니다.터미널 창 LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-serverLITESTREAM_REGION=eu-west-1LITESTREAM_ACCESS_KEY_ID=your-access-key-idLITESTREAM_SECRET_ACCESS_KEY=your-secret-access-keyCOMPOSE_PROFILES=litestreamAmazon S3가 아닌 저장소라면
LITESTREAM_ENDPOINT도 그 주소로,LITESTREAM_REGION은 그 저장소가 기대하는 리전(R2는auto)으로 설정하세요.COMPOSE_PROFILES는 모든docker compose명령에 Litestream이 포함되게 합니다. -
시작합니다.
터미널 창 sudo docker compose up -d -
데이터베이스를 복사했는지 확인합니다.
snapshot complete가 있는 줄이 출력됩니다.터미널 창 sudo docker compose logs litestream | grep 'snapshot complete'
Litestream은 하루에 한 번 전체 사본을 만들고, 일주일 치 사본과 그 사이의 변경을 보관합니다. 일정은 litestream.yml에 있습니다.
Litestream 복원 연습
섹션 제목: “Litestream 복원 연습”이 연습은 버킷에서 데이터베이스를 임시 볼륨으로 복원하고, 그 위에서 서버의 두 번째 사본을 시작하고, 둘이 같은 서버인지 확인합니다. 실행 중인 서버는 건드리지 않습니다.
cd /opt/oleafly-serversudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --versionsudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-servercurl -fsS https://collab.example.org/.well-known/oleafly-server첫 명령은 서버에 필요한 소유자로 임시 볼륨을 만듭니다. 마지막 두 응답의 server_id가 일치해야 합니다. 끝나면 사본을 제거하세요.
sudo docker rm -f oleafly-litestream-drillsudo docker volume rm oleafly-litestream-drillLitestream에서 데이터베이스 복원하기
섹션 제목: “Litestream에서 데이터베이스 복원하기”데이터베이스 파일이 손상되었거나 사라졌지만 데이터 폴더의 나머지는 멀쩡할 때는, 서버와 Litestream을 멈추고, 남은 데이터베이스를 제거하고, 복원한 다음 다시 시작하세요.
cd /opt/oleafly-serversudo docker compose stop oleafly-server litestreamsudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestreamsudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3sudo docker compose up -d파일이 버킷에 있는 상태에서 디스크를 잃었다면 새로 만든 빈 볼륨에서 위 명령을 실행하고 .env에는 같은 버킷 설정을 유지하세요. 모든 프로젝트가 파일과 스냅숏과 함께 돌아옵니다.
파일이 디스크에 있는 상태에서 디스크를 잃었다면 가장 최근 아카이브를 복원하고 거기서 끝내세요. 더 오래된 아카이브 위에 Litestream의 더 새로운 데이터베이스를 얹지 마세요. 데이터베이스가 아카이브에 없는 파일과 스냅숏을 가리키게 되어 그 프로젝트들이 열리지 않습니다.
업데이트
섹션 제목: “업데이트”먼저 백업하세요. 서버는 새 릴리스를 처음 시작할 때 데이터베이스를 업데이트하므로, 이전 릴리스로 돌아가려면 업데이트 전에 만든 백업을 복원해야 합니다.
- 명령 한 줄 설치:
curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update를 실행합니다..env는 유지하고, 새 릴리스의 파일과 이미지를 받고, 서버를 다시 시작합니다. - 직접 하는 Docker Compose: 직접 하는 Docker Compose에서처럼 새 릴리스의 파일을 서버 폴더에 내려받은 다음
sudo docker compose up -d를 실행합니다. - Coolify: Redeploy를 선택합니다. 게시된 이미지를 쓰면 이미지의 태그 아래 최신 릴리스를 받아 옵니다.
- Render: 서비스를 열고 수동 배포를 시작합니다. 이미지를 다시 가져옵니다.
- Railway: 메뉴에서 서비스를 다시 배포합니다. Railway는 GitHub 레지스트리의 이미지를 스스로 업데이트할 수도 있습니다.
- systemd: 서버 내려받기에서처럼 새 릴리스를 설치한 다음
sudo systemctl restart oleafly-server를 실행합니다.
Oleafly는 연결할 때마다 서버의 버전을 확인합니다. 앱과 서버가 함께 동작하지 못하면 Oleafly가 어느 쪽을 업데이트해야 하는지 알려 줍니다.