# 저장소, 백업, 한도

Oleafly Server의 모든 설정, 디스크나 S3 버킷에 파일 저장하기, 컴파일된 PDF, 프록시 뒤에서 실행하기, 한 네트워크의 수업과 각 계정을 위한 한도, 로그, 백업, 복원, 업데이트.

이 페이지는 Oleafly Server를 일상적으로 운영하는 방법을 다룹니다. 설치하려면 [공동 작업 서버 운영하기](/docs/collaboration/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` | 이 제공자의 모든 이메일 주소를 인증된 것으로 취급합니다. 먼저 [인증된 이메일 주소](/docs/collaboration/server-access/#verified-email-addresses)를 읽어 보세요. | `false` |
| `OLEAFLY_SMTP_URL`, `OLEAFLY_MAIL_FROM` | 이메일. [이메일](/docs/collaboration/server-access/#email)을 읽어 보세요. | 꺼짐 |
| `OLEAFLY_OPEN_SIGNUP` | 내가 설정한 제공자 중 하나로 로그인하는 사람 누구에게나 멤버 계정을 줍니다. [공개 가입](/docs/collaboration/server-access/#open-sign-up)을 읽어 보세요. | `false` |
| `OLEAFLY_WEB` | 브라우저 접근을 켭니다. [브라우저 접근](/docs/collaboration/server-access/#browser-access)을 읽어 보세요. | `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). [계정별 한도](#limits-per-account)를 읽어 보세요. | 한도 없음, 공개 가입이면 `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에 시크릿 두지 않기](/docs/collaboration/server/#keep-secrets-out-of-env)를 읽어 보세요.

## 저장소

기본적으로 서버는 모든 것을 `OLEAFLY_DATA_DIR`에 보관합니다. 데이터베이스, 사람들이 공유하는 파일, 프로젝트 스냅숏입니다. 스냅숏은 각 프로젝트의 저장된 사본으로, 사람들이 빠르게 참여하고 따라잡게 해 줍니다.

### 버킷에 파일 두기

서버는 파일과 스냅숏을 대신 Amazon S3에 보관할 수 있고, MinIO나 Cloudflare R2처럼 S3 호환 API를 가진 다른 저장소에도 보관할 수 있습니다. 어느 쪽이든 데이터베이스는 `OLEAFLY_DATA_DIR`에 남으므로 서버에는 여전히 데이터 폴더가 필요합니다.

1. 버킷을 만들고 공개 접근을 차단합니다.
2. 그 버킷의 객체를 읽고, 쓰고, 삭제할 수 있고 그 밖에는 아무것도 할 수 없는 키를 만듭니다. Amazon S3에서는 `arn:aws:s3:::lab-bucket/*`에 대한 `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`이며, 폴더를 쓴다면 `arn:aws:s3:::lab-bucket/oleafly/*`에 대한 것입니다.
3. 예를 들어 `.env`에 변수를 설정합니다.

   ```sh
   OLEAFLY_BLOB_STORE=s3://lab-bucket/oleafly
   OLEAFLY_S3_REGION=eu-west-1
   OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-id
   OLEAFLY_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를 서버로 보내며, SyncTeX 파일이 있으면 함께 보냅니다. 프로젝트마다 1분에 최대 한 번 보냅니다. 서버는 프로젝트마다 PDF 하나와 SyncTeX 파일 하나를 주 파일 이름, 컴파일한 사람, 컴파일한 시각과 함께 보관합니다. [브라우저 접근](/docs/collaboration/server-access/#browser-access)은 프로젝트의 사람들에게 이 PDF를 보여 줍니다.

새로 올라온 파일은 이전 파일을 대체하며, 이전 파일은 쓰는 곳이 없어지면 삭제됩니다. 컴파일된 파일은 다른 파일과 함께 디스크나 버킷에 저장되고, 프로젝트와 함께 삭제됩니다. 컴파일된 파일은 최대 `OLEAFLY_MAX_FILE_MB`까지 클 수 있습니다. 소유자의 [계정 저장 용량](#limits-per-account)에는 포함되지만, 시간당 업로드 수에는 포함되지 않습니다.

프로젝트의 모든 참여자가 컴파일된 파일을 읽을 수 있습니다. 파일을 바꿀 수 있는 사람은 소유자와 편집자뿐입니다.

## 리버스 프록시 뒤에서

서버는 평문 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 연결을 차단합니다. 필터링 프록시가 있는 대학이나 회사 네트워크가 흔히 그렇습니다. 그런 곳에서도 실시간 편집은 더 느리게나마 동작합니다. 서버가 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가 바꾸는 것

서버는 두 곳에 클라이언트 주소를 기록합니다. 보안 로그와, 한 주소가 로그인을 시작하거나 실시간 연결을 열 수 있는 빈도에 대한 [한도](#limits-for-a-class-on-one-network)입니다.

이 설정이 없으면 서버는 자기에게 연결한 대상의 주소를 씁니다. 프록시 뒤에서는 그 대상이 항상 프록시이므로, 모든 사람이 하나의 한도를 공유하고 보안 로그에는 프록시의 주소만 나타납니다.

`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는 추가 설정 없이 WebSocket 연결과 `X-Forwarded-For`를 통과시키고 인증서도 직접 받습니다. `Caddyfile` 전체는 [앞단에 HTTPS 두기](/docs/collaboration/server/#put-https-in-front)에 있습니다.

### nginx

먼저 certbot 등으로 도메인의 인증서를 받으세요. 그런 다음 이것을 `/etc/nginx/conf.d/oleafly.conf`로 저장하고 `sudo nginx -t && sudo systemctl reload nginx`를 실행하세요.

```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 2.4.47 이상이 필요하며, Debian 12와 Ubuntu 22.04 이후 버전에 있습니다. 모듈을 켭니다.

```sh
sudo a2enmod proxy proxy_http ssl
```

이것을 `/etc/apache2/sites-available/oleafly.conf`로 저장한 다음 `sudo a2ensite oleafly && sudo systemctl reload apache2`를 실행하세요.

```apache
<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 주소는 한 주소로 칩니다. 이 한도는 서버가 각 사람의 실제 주소를 볼 수 있어야 사람별로 동작하므로, [프록시를 올바르게 설정](#what-oleafly_behind_proxy-changes)하세요.

서버는 30초마다 각 실시간 연결에 핑을 보냅니다. 핑에 90초 동안 응답하지 않는 연결과 서버가 보내는 내용을 읽지 않는 연결은 닫습니다.

프로젝트 한도는 모든 사람에게 적용됩니다. 프로젝트 전체는 `OLEAFLY_MAX_PROJECT_MB`(기본 200 MB), 파일 하나는 `OLEAFLY_MAX_FILE_MB`(50 MB), 한 프로젝트의 인원은 `OLEAFLY_MAX_MEMBERS_PER_PROJECT`(20)입니다. 관리 콘솔의 **개요**에서 현재 한도를 볼 수 있습니다.

## 계정별 한도

계정마다 한도 세 가지가 적용됩니다. 직접 설정하기 전에는 꺼져 있지만, [공개 가입](/docs/collaboration/server-access/#open-sign-up)이 켜져 있으면 다음 기본값으로 켜집니다.

| 한도 | 설정 | 공개 가입일 때 |
| --- | --- | --- |
| 계정이 소유한 프로젝트의 저장 용량 | `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`입니다.

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo 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-server
```

systemd에서는 다음과 같습니다.

```sh
sudo systemctl stop oleafly-server
sudo 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` 대신 내 아카이브의 날짜를 쓰세요.

```sh
cd /opt/oleafly-server
sudo docker volume create oleafly-restore-drill
sudo 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.gz
sudo 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-server
curl -fsS https://collab.example.org/.well-known/oleafly-server
```

두 응답의 `server_id`가 일치해야 합니다. 연습용 사본에는 누구도 로그인시킬 수 없는 임시 GitHub 로그인이 있고 열린 포트도 없어서 아무도 사용할 수 없습니다. 끝나면 제거하세요.

```sh
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill
```

### 복원

Docker Compose에서 실제로 복원하려면 서버를 멈추고, 볼륨의 내용을 아카이브로 바꾸고, 다시 시작하세요.

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo 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-server
```

systemd에서는 다음과 같습니다.

```sh
sudo systemctl stop oleafly-server
sudo find /var/lib/private/oleafly-server -mindepth 1 -delete
sudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gz
sudo systemctl start oleafly-server
```

복원된 서버에는 백업 이후에 사람들이 한 변경이 없습니다. 각 앱은 앱이 계속 열려 있었든 나중에 열었든 다시 연결될 때 이를 알아차리고 자기가 가진 누락된 변경을 다시 보냅니다. 이를 위해 아무도 할 일이 없습니다. 다른 사람의 누락된 변경 위에 쌓인 변경은 그 사람이 프로젝트를 열 때까지 기다립니다. 그 사람의 변경은 그 사람의 앱만 보낼 수 있기 때문입니다. 장애 시점 전후에 편집하던 모든 사람에게 프로젝트를 한 번 열어 달라고 요청하세요.

### Litestream으로 연속 복사하기

아카이브에는 만든 시점에 있던 것만 들어 있습니다. [Litestream](https://litestream.io)은 서버 데이터베이스의 모든 변경을 일어난 지 1초쯤 뒤에 S3 호환 버킷으로 복사합니다. Compose 파일에는 선택 사항인 서비스로 들어 있습니다.

Litestream은 데이터베이스만 복사합니다. 파일이 버킷에 있다면 버킷에 이미 파일과 스냅숏이 있으므로, Litestream 사본과 버킷이 합쳐져 잃어버린 디스크를 되살릴 수 있습니다. 파일이 디스크에 있다면 Litestream이 `blobs` 폴더를 복사하지 않으므로 볼륨 아카이브도 계속 만드세요.

1. 이 서버의 Litestream만 쓰는 버킷이나 버킷 안의 폴더를 만듭니다. `OLEAFLY_BLOB_STORE`와 공유하지 마세요. Litestream에 버킷을 나열하고 그 안의 객체를 읽고, 쓰고, 삭제할 수 있는 키를 줍니다.
2. `.env`에 정보를 추가합니다.

   ```sh
   LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-server
   LITESTREAM_REGION=eu-west-1
   LITESTREAM_ACCESS_KEY_ID=your-access-key-id
   LITESTREAM_SECRET_ACCESS_KEY=your-secret-access-key
   COMPOSE_PROFILES=litestream
   ```

   Amazon S3가 아닌 저장소라면 `LITESTREAM_ENDPOINT`도 그 주소로, `LITESTREAM_REGION`은 그 저장소가 기대하는 리전(R2는 `auto`)으로 설정하세요. `COMPOSE_PROFILES`는 모든 `docker compose` 명령에 Litestream이 포함되게 합니다.
3. 시작합니다.

   ```sh
   sudo docker compose up -d
   ```

4. 데이터베이스를 복사했는지 확인합니다. `snapshot complete`가 있는 줄이 출력됩니다.

   ```sh
   sudo docker compose logs litestream | grep 'snapshot complete'
   ```

Litestream은 하루에 한 번 전체 사본을 만들고, 일주일 치 사본과 그 사이의 변경을 보관합니다. 일정은 `litestream.yml`에 있습니다.

#### Litestream 복원 연습

이 연습은 버킷에서 데이터베이스를 임시 볼륨으로 복원하고, 그 위에서 서버의 두 번째 사본을 시작하고, 둘이 같은 서버인지 확인합니다. 실행 중인 서버는 건드리지 않습니다.

```sh
cd /opt/oleafly-server
sudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --version
sudo 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.sqlite3
sudo 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-server
curl -fsS https://collab.example.org/.well-known/oleafly-server
```

첫 명령은 서버에 필요한 소유자로 임시 볼륨을 만듭니다. 마지막 두 응답의 `server_id`가 일치해야 합니다. 끝나면 사본을 제거하세요.

```sh
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill
```

#### Litestream에서 데이터베이스 복원하기

데이터베이스 파일이 손상되었거나 사라졌지만 데이터 폴더의 나머지는 멀쩡할 때는, 서버와 Litestream을 멈추고, 남은 데이터베이스를 제거하고, 복원한 다음 다시 시작하세요.

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server litestream
sudo 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-litestream
sudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3
sudo docker compose up -d
```

파일이 버킷에 있는 상태에서 디스크를 잃었다면 새로 만든 빈 볼륨에서 위 명령을 실행하고 `.env`에는 같은 버킷 설정을 유지하세요. 모든 프로젝트가 파일과 스냅숏과 함께 돌아옵니다.

파일이 디스크에 있는 상태에서 디스크를 잃었다면 가장 최근 아카이브를 [복원](#restore)하고 거기서 끝내세요. 더 오래된 아카이브 위에 Litestream의 더 새로운 데이터베이스를 얹지 마세요. 데이터베이스가 아카이브에 없는 파일과 스냅숏을 가리키게 되어 그 프로젝트들이 열리지 않습니다.

## 업데이트

먼저 백업하세요. 서버는 새 릴리스를 처음 시작할 때 데이터베이스를 업데이트하므로, 이전 릴리스로 돌아가려면 업데이트 전에 만든 백업을 복원해야 합니다.

- **명령 한 줄 설치**: `curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update`를 실행합니다. `.env`는 유지하고, 새 릴리스의 파일과 이미지를 받고, 서버를 다시 시작합니다.
- **직접 하는 Docker Compose**: [직접 하는 Docker Compose](/docs/collaboration/server/#docker-compose-by-hand)에서처럼 새 릴리스의 파일을 서버 폴더에 내려받은 다음 `sudo docker compose up -d`를 실행합니다.
- **Coolify**: **Redeploy**를 선택합니다. 게시된 이미지를 쓰면 이미지의 태그 아래 최신 릴리스를 받아 옵니다.
- **Render**: 서비스를 열고 수동 배포를 시작합니다. 이미지를 다시 가져옵니다.
- **Railway**: 메뉴에서 서비스를 다시 배포합니다. Railway는 GitHub 레지스트리의 이미지를 스스로 업데이트할 수도 있습니다.
- **systemd**: [서버 내려받기](/docs/collaboration/server/#download-the-server)에서처럼 새 릴리스를 설치한 다음 `sudo systemctl restart oleafly-server`를 실행합니다.

Oleafly는 연결할 때마다 서버의 버전을 확인합니다. 앱과 서버가 함께 동작하지 못하면 Oleafly가 어느 쪽을 업데이트해야 하는지 알려 줍니다.
