# ストレージ、バックアップ、上限

Oleafly Server のすべての設定、ディスクまたは S3 バケットへのファイル保存、コンパイル済みの PDF、プロキシの内側での運用、1 つのネットワーク上のクラスのための制限とアカウントごとの上限、ログ、バックアップ、復元、更新を説明します。

このページでは、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` | 自分で決める 1 回限りのセットアップコード。英数字で 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` | Amazon S3 以外の S3 互換ストア（MinIO や Cloudflare R2 など）のアドレス。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` | サーバーが受け付ける最大のプロジェクトのサイズ（メガバイト単位）。 | `200` |
| `OLEAFLY_MAX_FILE_MB` | 1 つのファイルの最大サイズ（メガバイト単位）。 | `50` |
| `OLEAFLY_MAX_MEMBERS_PER_PROJECT` | 1 つのプロジェクトの最大人数。 | `20` |
| `OLEAFLY_ACCOUNT_STORAGE_MB` | 1 つのアカウントが所有するプロジェクトが保存できる最大量（メガバイト単位）。[アカウントごとの上限](#limits-per-account)をお読みください。 | 上限なし。オープンサインアップでは `100` |
| `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | 1 つのアカウントが所有できる共有プロジェクトの最大数。 | 上限なし。オープンサインアップでは `50` |
| `OLEAFLY_UPLOADS_PER_HOUR` | 1 つのアカウントが 1 時間に行えるファイルとスナップショットのアップロードの回数。 | 上限なし。オープンサインアップでは `300` |
| `OLEAFLY_SIGN_IN_BURST` | 1 つのネットワークアドレスが、短時間にまとめて送れるサインインリクエストの数。1 回のサインインに約 6 件使うため、既定値は、同じアドレスの 50 人が同時にサインインできる数です。 | `300` |
| `OLEAFLY_SIGN_IN_PER_MINUTE` | バーストの後に、1 つのネットワークアドレスに 1 分ごとに戻されるサインインリクエストの数。 | `120` |
| `OLEAFLY_EMAIL_LINKS_PER_IP` | 1 つのネットワークアドレスのユーザーに対して、サーバーが 15 分間に送るサインインメールの数。 | `100` |
| `OLEAFLY_EMAIL_LINKS_PER_ADDRESS` | 1 つのメールアドレスが 15 分間に受け取れるサインインメールの数。`OLEAFLY_EMAIL_LINKS_PER_IP` を超えることはできません。 | `3` |
| `OLEAFLY_DEVICE_CODES_PER_IP` | 1 つのネットワークアドレスのユーザーが 10 分間にリクエストできるサインインコードの数。 | `100` |
| `OLEAFLY_SNAPSHOT_MEMORY_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/*`（フォルダを使う場合は `arn:aws:s3:::lab-bucket/oleafly/*`）に対する `s3:GetObject`、`s3:PutObject`、`s3:DeleteObject` を意味します。
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 ハッシュを名前とし、そのハッシュの最初の 2 文字のフォルダの下に置かれます。たとえばハッシュが `3f9a` で始まるファイルは `oleafly/3f/3f9a...` として保存されます。スナップショットには専用の `snapshots` フォルダがあり、プロジェクトごとにフォルダがあります。サーバーはファイルやスナップショットを読み戻すとき、バイト列をハッシュと照合し、一致しないものは拒否します。バケットを使わない場合は、同じ構成が `OLEAFLY_DATA_DIR` 内の `blobs` フォルダにあります。

バケットがリクエストを拒否した場合、そのアップロードまたはダウンロードは失敗し、サーバーのログには `403 Forbidden (AccessDenied)` など、バケットの応答が表示されます。サーバーエラー、タイムアウト、接続の切断は別で、サーバーは短いランダムな間隔を置いて最大 3 回試行します。オブジェクトを削除できなかった場合は、それを記録し、6 時間ごとのメンテナンスのたびに再試行するので、障害でオブジェクトが残り続けることはありません。

### スナップショットとメモリ

プロジェクトが共有されると、所有者のアプリが最初のスナップショットをアップロードし、そのデバイスのキーで署名します。それ以降は、サーバーが前のスナップショットと、その後にユーザーが送った変更から、すべてのスナップショットを自分で作成します。新しいスナップショットは、プロジェクトに前回から 1,000 件の変更が溜まると作成されます。サーバーは、少なくとも直近 2,000 件の変更を常に保持するので、短時間離れていたデバイスは、それらから追いつき、プロジェクト全体をダウンロードし直す必要はありません。

スナップショットの作成には、前のスナップショットとその後の変更を合わせたサイズの約 10 倍が必要です。サーバーは `OLEAFLY_SNAPSHOT_MEMORY_MB` に収まる作成だけを開始し、同時に実行される作成は、その量を共有します。作成が収まらない場合、サーバーはそれをスキップし、必要なメモリ量をログに記録して、プロジェクトのすべての変更を保持します。その場合、デバイスはそれらの変更から、数メガバイトずつ追いつきます。設定を引き上げると、次のスナップショットが作成されます。サーバーは、`OLEAFLY_MAX_PROJECT_MB` より大きなスナップショットを保存しません。

### コンパイル済みの PDF

所有者または編集者が共有プロジェクトのコンパイルに成功すると、そのアプリは PDF を、SyncTeX ファイルがあればそれも一緒に、サーバーに送ります。送信は、プロジェクトごとに 1 分に 1 回までです。サーバーは、プロジェクトごとに PDF と SyncTeX ファイルを 1 つずつ、メインファイルの名前、コンパイルした人、日時とともに保持します。[ブラウザからのアクセス](/docs/collaboration/server-access/#browser-access)では、この PDF がプロジェクトのユーザーに表示されます。

アップロードのたびに前のものが置き換えられ、古いファイルは、どこからも使われなくなった時点で削除されます。コンパイル済みのファイルは、ほかのファイルと同じくディスクまたはバケットに保存され、プロジェクトとともに削除されます。コンパイル済みのファイルの大きさは、最大で `OLEAFLY_MAX_FILE_MB` です。所有者の[アカウントのストレージ](#limits-per-account)には数えられますが、1 時間あたりのアップロード数には数えられません。

プロジェクトのメンバーは誰でも、コンパイル済みのファイルを読めます。置き換えられるのは、所有者と編集者だけです。

## リバースプロキシの内側で動かす

サーバーは通常の HTTP で通信するため、手前にある何かが HTTPS を処理します。Compose のセットアップでは Caddy、あるいは Coolify のプロキシや、大学の Web サーバーなど、すでに運用している Web サーバーです。手前にあるものは、次のことを満たす必要があります。

- `OLEAFLY_MAX_PROJECT_MB` と同じ大きさまでのリクエストを受け付ける
- クライアントのアドレスを `X-Forwarded-For` に追加する

また、`/ws` への WebSocket アップグレードを通し、その接続を少なくとも 1 時間は開いたままにする必要があります。ライブ編集は、可能なときにそれらを使います。ブラウザからのアクセスがオンの場合は、`/web/ws` へのアップグレードも通す必要があります。ブラウザ用アプリには、より遅い代わりの経路がないためです。

サーバーは、プロキシだけが到達できる場所で動かします。同じマシン上なら、`OLEAFLY_BIND=127.0.0.1:8080` を設定します。そのうえで、`OLEAFLY_BEHIND_PROXY=true` を設定します。

### WebSocket 接続がブロックされるとき

WebSocket 接続をブロックするネットワークがあります。フィルタリングプロキシのある大学や会社のネットワークに多く見られます。そうしたネットワークでも、ライブ編集は動作しますが、速度は遅くなります。サーバーが HTTPS では応答しているのに WebSocket の試行が 2 回続けて失敗すると、Oleafly は HTTP のロングポーリングに切り替えます。編集は `/api/v1/projects/<project>/frames` に送り、ほかのユーザーの編集は `/api/v1/projects/<project>/poll` で待ちます。各リクエストは、最大 `OLEAFLY_POLL_HOLD_SECONDS` の間開いたままになります。すべての編集は、これまでどおり届きます。Oleafly は 1 分ごとに WebSocket を再試行し、接続できた時点でそちらに戻ります。

Oleafly の**接続をテスト**と管理コンソールの**接続チェック**は、これが起きていることを「このネットワークが通常の経路をブロックしているため、ライブ編集はより遅い経路を使っています。編集はそれでも届きます」と表示して知らせます。

サーバーの手前でプロキシを運用している場合は、それでも WebSocket アップグレードを通してください。ロングポーリングも動作しますが、編集のまとまりごとに追加のリクエストが必要になり、遅延も少し増えます。

30 秒未満で、通信のないリクエストを閉じるプロキシがあります。たとえば、短い `proxy_read_timeout` を設定した nginx です。そうしたプロキシは、ロングポーリングのリクエストに 502 または 504 のエラーを返し、編集が遅れて届きます。`OLEAFLY_POLL_HOLD_SECONDS` は、そのタイムアウトより数秒短くしてください。タイムアウトが 10 秒なら `8` です。

### OLEAFLY_BEHIND_PROXY が変えるもの

サーバーがクライアントのアドレスを記録するのは、2 か所です。セキュリティログと、1 つのアドレスがサインインを開始したりライブ接続を開いたりできる頻度の[制限](#limits-for-a-class-on-one-network)です。

この設定がない場合、サーバーは、接続してきたものそのもののアドレスを使います。プロキシの内側では、それは常にプロキシなので、全員が 1 つの制限を共有し、セキュリティログにはプロキシのアドレスしか表示されません。

`OLEAFLY_BEHIND_PROXY=true` にすると、サーバーは `X-Forwarded-For` ヘッダーを読み取り、その最後のアドレス（プロキシが追加したもの）を使います。ヘッダーがない場合や、有効なアドレスが含まれていない場合は、接続元のアドレスにフォールバックします。ほかに変わることはありません。サーバーは `X-Forwarded-Proto`、`X-Forwarded-Host`、`Forwarded` を無視し、自分が発行するアドレスはすべて `OLEAFLY_PUBLIC_URL` から組み立てます。

すべてのリクエストがプロキシ経由で届く場合にだけ、オンにしてください。ユーザーがサーバーに直接アクセスすることもできる場合、誰でも偽の `X-Forwarded-For` を送って、セキュリティログに好きなアドレスを記録させ、サインインの制限を回避できてしまいます。

プロキシが 2 つ連続している場合（たとえば Coolify のプロキシの手前に Cloudflare がある場合）は、`OLEAFLY_PROXY_HOPS=2` を設定します。サーバーは、末尾から 2 番目のアドレスを使います。数えるのは、すべてのリクエストが通過するプロキシだけです。サーバーに直接つながる Cloudflare Tunnel は 1 つと数えます。

この数を確認するには、自分のコンピュータからサインインし、管理コンソールの**セキュリティログ**を開きます。最新の項目に、あなたのパブリックアドレスが表示されるはずです。`ifconfig.me` のようなサイトが示すアドレスです。代わりにプライベートアドレスや Cloudflare のアドレスが表示される場合は、`OLEAFLY_PROXY_HOPS` を 1 つ増やします。

### 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` がその接続を 1 時間開いたままにします。Apache は、クライアントのアドレスを `X-Forwarded-For` に自分で追加します。

### パスの下で動かす

サーバーをパスの下で動かす場合は、`OLEAFLY_PUBLIC_URL`（たとえば `https://www.cs.example.edu/oleafly`）と、サインインプロバイダに登録するコールバックのアドレスに、そのパスを含めます。サーバーはそのパスがあってもなくても応答するため、プロキシはパスをそのまま渡しても、取り除いてもかまいません。nginx では、`location /oleafly/ {` を使い、中の行は同じにします。そして `proxy_pass http://127.0.0.1:8080;` はパスなしのままにして、nginx がパスをそのまま渡すようにします。

## 1 つのネットワーク上のクラスのための制限

クラス全体が、大学の NAT など、1 つのネットワークアドレスからサインインすることはよくあります。既定値は、それを想定して設定されています。

- **サインイン**：1 つのアドレスにつき、300 件のサインインリクエストをまとめて送れ、その後は 1 秒に 2 件です。1 回のサインインに約 6 件使うので、50 人が同時にサインインできます。`OLEAFLY_SIGN_IN_BURST` と `OLEAFLY_SIGN_IN_PER_MINUTE` で変更できます。
- **メールのリンク**：1 つのアドレスに 15 分間で 100 通、1 つのメールアドレスに 3 通です。`OLEAFLY_EMAIL_LINKS_PER_IP` と `OLEAFLY_EMAIL_LINKS_PER_ADDRESS` で変更できます。
- **サインインコード**：1 つのアドレスから 10 分間に、100 個のコードのリクエストと、10 回の誤ったコードの入力です。`OLEAFLY_DEVICE_CODES_PER_IP` で変更できます。
- **ライブ接続**には専用のより大きな制限があるため、1 つのアドレスの背後にいるクラス全体が、再起動後にまとめて再接続できます。この制限を消費するのは、セッションの証明に失敗する接続だけで、300 件のバーストの後は 1 秒に 10 件です。セッションを証明した接続は、そのデバイス自身の制限に数えられ、バーストで 60 回、その後は 1 秒に 1 回再接続できます。

1 つの `/64` ネットワーク内のすべての IPv6 アドレスは、1 つのアドレスとして数えられます。これらの制限がユーザー単位で機能するのは、サーバーが各ユーザーの実際のアドレスを見られる場合だけなので、[プロキシを正しく設定](#what-oleafly_behind_proxy-changes)してください。

サーバーは、各ライブ接続に 30 秒ごとに ping を送ります。その ping に 90 秒間応答しない接続と、サーバーが送るものを読まなくなった接続は、閉じられます。

プロジェクトの制限は全員に適用されます。プロジェクト全体には `OLEAFLY_MAX_PROJECT_MB`（既定では 200 MB）、1 つのファイルには `OLEAFLY_MAX_FILE_MB`（50 MB）、1 つのプロジェクトの人数には `OLEAFLY_MAX_MEMBERS_PER_PROJECT`（20 人）です。管理コンソールの**概要**に、現在の制限が表示されます。

## アカウントごとの上限

各アカウントには、3 つの上限が適用されます。設定するまではオフですが、[オープンサインアップ](/docs/collaboration/server-access/#open-sign-up)がオンの場合は、次の既定値でオンになります。

| 上限 | 設定 | オープンサインアップの場合 |
| --- | --- | --- |
| アカウントが所有するプロジェクトのストレージ | `OLEAFLY_ACCOUNT_STORAGE_MB` | 100 MB |
| アカウントが所有する共有プロジェクト | `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | 50 |
| アカウントが 1 時間に行うアップロード | `OLEAFLY_UPLOADS_PER_HOUR` | 300 |

設定した値は、常に既定値より優先されます。どの値も、1 以上の整数にする必要があります。

- **ストレージ**は、アカウントが所有するすべてのプロジェクト（アーカイブ済みのものを含む）のファイルと変更履歴、そしてそのコンパイル済みの PDF を合計します。スナップショットは数えません。プロジェクトに追加されたファイルは、誰が追加したものでも、プロジェクトの所有者の分として数えられます。所有者のアカウントがいっぱいになると、サーバーはその人のプロジェクトへの新しいファイルとコンパイル済みの PDF を拒否し、所有者はほかのプロジェクトを共有できなくなります。ファイルは、追加した人のコンピュータに残ります。入力したテキストは引き続き同期されます。
- **共有プロジェクト**は、アカウントが共有しているプロジェクトを、まだアップロード中のものも含めて数えます。アーカイブ済みのプロジェクトは数えないので、どれか 1 つの共有を停止すると空きができます。
- **アップロード**は、1 時間の枠の中で行われたすべてのファイルとスナップショットのアップロードを数えます。コンパイル済みの 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 のダッシュボードから行います。

### 復元の演習

一度も復元したことのないバックアップは、希望にすぎません。この演習では、バックアップからサーバーの 2 つ目のコピーを起動し、動作中のサーバーには手を加えず、両者が同じサーバーであることを確認します。`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
```

2 つの応答の `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 は 1 日に 1 回、完全なコピーを取り、1 週間分のコピーと、その間の変更を保持します。スケジュールは `litestream.yml` にあります。

#### Litestream の復元の演習

この演習では、バケットからデータベースを一時的なボリュームに復元し、その上でサーバーの 2 つ目のコピーを起動して、両者が同じサーバーであることを確認します。動作中のサーバーには手を加えません。

```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
```

最初のコマンドは、サーバーに必要な所有者を設定して、一時的なボリュームを作成します。最後の 2 つの応答の `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 の新しいデータベースを重ねないでください。データベースが、アーカイブにないファイルやスナップショットを指すことになり、それらのプロジェクトが開かなくなります。

## 更新

先にバックアップします。サーバーは、新しいリリースが初めて起動したときにデータベースを更新するため、古いリリースに戻すには、更新前に取ったバックアップを復元することになります。

- **1 つのコマンドでのインストール**：`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 がどちらの更新が必要かを知らせます。
