# Lưu trữ, sao lưu và giới hạn

Mọi cài đặt của Oleafly Server, lưu tệp trên đĩa hoặc trong một bucket S3, PDF đã biên dịch, chạy sau proxy, giới hạn cho các lớp học trên cùng một mạng và cho mỗi tài khoản, nhật ký, sao lưu, khôi phục và cập nhật.

Trang này nói về việc vận hành Oleafly Server hằng ngày. Để cài đặt nó, hãy bắt đầu với [Chạy máy chủ cộng tác](/docs/collaboration/server/).

## Cài đặt

Máy chủ đọc các cài đặt của nó từ biến môi trường. Một biến được đặt nhưng để trống được coi là không đặt. Nếu thiếu một cài đặt hoặc cài đặt sai định dạng, máy chủ sẽ không khởi động, và nhật ký của nó cho biết đó là cài đặt nào.

| Biến | Tác dụng | Mặc định |
| --- | --- | --- |
| `OLEAFLY_PUBLIC_URL` | Địa chỉ HTTPS mà mọi người nhập trong Oleafly. Nó có thể gồm một đường dẫn, chẳng hạn `https://www.cs.example.edu/oleafly`. Bắt buộc. Các tệp Compose và Coolify đặt nó giúp bạn. | Không có |
| `OLEAFLY_BIND` | Địa chỉ và cổng mà máy chủ lắng nghe. | `0.0.0.0:8080` |
| `OLEAFLY_DATA_DIR` | Thư mục cho cơ sở dữ liệu và các tệp đã lưu. | `/data` |
| `OLEAFLY_SERVER_NAME` | Tên mà mọi người thấy trong Oleafly, chẳng hạn `Smith Lab`. | `Oleafly Server` |
| `OLEAFLY_SERVER_ICON_URL` | Địa chỉ HTTPS của một hình ảnh vuông hiển thị cạnh tên. | Không có |
| `OLEAFLY_SETUP_CODE` | Mã thiết lập dùng một lần do bạn tự chọn: ít nhất 12 chữ cái hoặc chữ số, muốn thêm gạch ngang hay khoảng trắng cũng được. Nếu không có nó, máy chủ sẽ tự tạo một mã. | Tự tạo |
| `OLEAFLY_GITHUB_CLIENT_ID`, `OLEAFLY_GITHUB_CLIENT_SECRET` | Bật đăng nhập bằng GitHub. | Tắt |
| `OLEAFLY_GITHUB_URL` | Địa chỉ của một GitHub Enterprise Server. | `https://github.com` |
| `OLEAFLY_GITHUB_API_URL` | Địa chỉ GitHub API, nếu địa chỉ của bạn khác thường. | `https://api.github.com`, hoặc `/api/v3` dưới `OLEAFLY_GITHUB_URL` |
| `OLEAFLY_GITHUB_LABEL` | Chữ trên nút đăng nhập GitHub. | `GitHub` |
| `OLEAFLY_OIDC_<NAME>_ISSUER`, `OLEAFLY_OIDC_<NAME>_CLIENT_ID`, `OLEAFLY_OIDC_<NAME>_CLIENT_SECRET` | Bật một nhà cung cấp OpenID Connect tên là `<NAME>`. | Tắt |
| `OLEAFLY_OIDC_<NAME>_LABEL` | Chữ trên nút đăng nhập của nhà cung cấp đó, chẳng hạn `University login`. | `<NAME>` |
| `OLEAFLY_OIDC_<NAME>_TRUST_EMAIL` | Coi mọi địa chỉ email từ nhà cung cấp này là đã xác minh. Hãy đọc [Địa chỉ email đã xác minh](/docs/collaboration/server-access/#verified-email-addresses) trước. | `false` |
| `OLEAFLY_SMTP_URL`, `OLEAFLY_MAIL_FROM` | Email. Hãy đọc [Email](/docs/collaboration/server-access/#email). | Tắt |
| `OLEAFLY_OPEN_SIGNUP` | Cấp cho bất kỳ ai đăng nhập bằng một trong các nhà cung cấp của bạn một tài khoản thành viên. Hãy đọc [Đăng ký mở](/docs/collaboration/server-access/#open-sign-up). | `false` |
| `OLEAFLY_WEB` | Bật quyền truy cập qua trình duyệt. Hãy đọc [Truy cập qua trình duyệt](/docs/collaboration/server-access/#browser-access). | `false` |
| `OLEAFLY_BLOB_STORE` | Nơi lưu các tệp như hình vẽ và PDF. `fs` giữ chúng trong `OLEAFLY_DATA_DIR`. Một địa chỉ như `s3://lab-bucket` hoặc `s3://lab-bucket/oleafly` giữ chúng trong một bucket. | `fs` |
| `OLEAFLY_S3_ENDPOINT` | Địa chỉ của một kho lưu trữ tương thích S3 ngoài Amazon S3, chẳng hạn MinIO hoặc Cloudflare R2. Hãy để trống nếu dùng Amazon S3. | Amazon S3 |
| `OLEAFLY_S3_REGION` | Vùng của bucket. | `us-east-1` |
| `OLEAFLY_S3_ACCESS_KEY_ID`, `OLEAFLY_S3_SECRET_ACCESS_KEY` | Khóa mà máy chủ dùng cho bucket. Bắt buộc khi dùng địa chỉ `s3://`. | Không có |
| `OLEAFLY_MAX_PROJECT_MB` | Dự án lớn nhất mà máy chủ chấp nhận, tính bằng megabyte. | `200` |
| `OLEAFLY_MAX_FILE_MB` | Tệp đơn lẻ lớn nhất, tính bằng megabyte. | `50` |
| `OLEAFLY_MAX_MEMBERS_PER_PROJECT` | Số người nhiều nhất trên một dự án. | `20` |
| `OLEAFLY_ACCOUNT_STORAGE_MB` | Dung lượng nhiều nhất mà các dự án do một tài khoản sở hữu được lưu, tính bằng megabyte. Hãy đọc [Giới hạn cho mỗi tài khoản](#limits-per-account). | Không giới hạn, hoặc `100` khi bật đăng ký mở |
| `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | Số dự án dùng chung nhiều nhất mà một tài khoản được sở hữu. | Không giới hạn, hoặc `50` khi bật đăng ký mở |
| `OLEAFLY_UPLOADS_PER_HOUR` | Số lần tải lên tệp và ảnh chụp mà một tài khoản được thực hiện trong một giờ. | Không giới hạn, hoặc `300` khi bật đăng ký mở |
| `OLEAFLY_SIGN_IN_BURST` | Số yêu cầu đăng nhập mà một địa chỉ mạng được gửi trong một đợt. Một lượt đăng nhập tốn khoảng sáu yêu cầu, nên giá trị mặc định đủ cho 50 người ở cùng một địa chỉ đăng nhập cùng lúc. | `300` |
| `OLEAFLY_SIGN_IN_PER_MINUTE` | Số yêu cầu đăng nhập mà một địa chỉ mạng được phép mỗi phút sau đợt ban đầu. | `120` |
| `OLEAFLY_EMAIL_LINKS_PER_IP` | Số email đăng nhập mà máy chủ gửi cho những người ở cùng một địa chỉ mạng trong 15 phút. | `100` |
| `OLEAFLY_EMAIL_LINKS_PER_ADDRESS` | Số email đăng nhập mà một địa chỉ email nhận được trong 15 phút. Không thể nhiều hơn `OLEAFLY_EMAIL_LINKS_PER_IP`. | `3` |
| `OLEAFLY_DEVICE_CODES_PER_IP` | Số mã đăng nhập mà những người ở cùng một địa chỉ mạng có thể yêu cầu trong 10 phút. | `100` |
| `OLEAFLY_SNAPSHOT_MEMORY_MB` | Bộ nhớ, tính bằng megabyte, mà máy chủ được dùng để dựng các ảnh chụp dự án. | Một nửa giới hạn bộ nhớ của container, hoặc `1024` nếu không có giới hạn |
| `OLEAFLY_BEHIND_PROXY` | Lấy địa chỉ của mỗi người từ header `X-Forwarded-For` mà proxy của bạn thêm vào. Các tệp Compose, Coolify và Render bật nó. | `false` |
| `OLEAFLY_PROXY_HOPS` | Số proxy mà mỗi yêu cầu đi qua trước khi tới máy chủ. Nó cần `OLEAFLY_BEHIND_PROXY=true`. | `1` |
| `OLEAFLY_LOG_LEVEL` | Máy chủ ghi nhật ký nhiều tới đâu: `error`, `warn`, `info`, `debug` hoặc `trace`. Các thư viện mà máy chủ dùng chỉ ghi cảnh báo, trừ khi bạn chọn `debug` hoặc `trace`. | `info` |
| `OLEAFLY_SECURITY_LOG_DAYS` | Số ngày giữ các mục nhật ký bảo mật, mục nhật ký truy cập dự án và thư mời khách đã trả lời hoặc đã hết hạn. | `365` |
| `OLEAFLY_ARCHIVE_DAYS` | Số ngày giữ một dự án sau khi chủ sở hữu ngừng chia sẻ nó. | `30` |
| `OLEAFLY_POLL_HOLD_SECONDS` | Thời gian máy chủ giữ mở một yêu cầu long-polling khi không có chỉnh sửa nào đang chờ, từ 1 đến 40 giây. Hãy để nó thấp hơn vài giây so với thời gian chờ nhàn rỗi của bất kỳ proxy nào đứng trước máy chủ. | `25` |

Trong tệp `.env` của Compose, hãy đặt giá trị trong dấu nháy đơn nếu nó chứa `$` hoặc `#`. Các cài đặt chứa bí mật cũng có thể được đọc từ tệp. Hãy đọc [Giữ bí mật ra khỏi .env](/docs/collaboration/server/#keep-secrets-out-of-env).

## Lưu trữ

Theo mặc định, máy chủ giữ mọi thứ trong `OLEAFLY_DATA_DIR`: cơ sở dữ liệu, các tệp mà mọi người chia sẻ, và các ảnh chụp dự án. Ảnh chụp là các bản sao đã lưu của từng dự án, giúp mọi người tham gia và cập nhật nhanh chóng.

### Tệp trong một bucket

Máy chủ có thể giữ tệp và ảnh chụp trong Amazon S3 thay vào đó, hoặc trong một kho lưu trữ khác có API tương thích S3, chẳng hạn MinIO hoặc Cloudflare R2. Dù cách nào, cơ sở dữ liệu vẫn nằm trong `OLEAFLY_DATA_DIR`, nên máy chủ vẫn cần thư mục dữ liệu của nó.

1. Tạo một bucket và chặn truy cập công cộng vào nó.
2. Tạo một khóa chỉ có thể đọc, ghi và xóa các đối tượng trong bucket đó, không làm gì khác. Trên Amazon S3, điều đó nghĩa là `s3:GetObject`, `s3:PutObject` và `s3:DeleteObject` trên `arn:aws:s3:::lab-bucket/*`, hoặc trên `arn:aws:s3:::lab-bucket/oleafly/*` nếu bạn dùng một thư mục.
3. Đặt các biến, ví dụ trong `.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
   ```

Với một kho lưu trữ không phải Amazon S3, hãy đặt `OLEAFLY_S3_ENDPOINT` thành địa chỉ của nó, chẳng hạn `https://minio.example.org:9000` hoặc `https://<account-id>.r2.cloudflarestorage.com`, và đặt `OLEAFLY_S3_REGION` thành vùng mà nó yêu cầu (`auto` với R2). `http://` thuần cũng dùng được, nhưng chỉ dùng nó khi kho lưu trữ nằm trên cùng một mạng riêng với máy chủ.

Phần sau tên bucket là một thư mục tùy chọn. Mỗi tệp được đặt tên theo mã băm SHA-256 của nó và nằm dưới hai ký tự đầu của mã băm đó, nên một tệp có mã băm bắt đầu bằng `3f9a` được lưu thành `oleafly/3f/3f9a...`. Các ảnh chụp có thư mục `snapshots` riêng của chúng, với một thư mục cho mỗi dự án. Khi máy chủ đọc lại một tệp hoặc ảnh chụp, nó đối chiếu các byte với mã băm và từ chối bản không khớp. Nếu không có bucket, bố cục giống hệt nằm trong thư mục `blobs` bên trong `OLEAFLY_DATA_DIR`.

Nếu bucket từ chối một yêu cầu, lần tải lên hoặc tải xuống đó thất bại, và nhật ký máy chủ hiển thị điều bucket đó nói, chẳng hạn `403 Forbidden (AccessDenied)`. Lỗi máy chủ, hết thời gian chờ hay kết nối bị ngắt thì khác: máy chủ thử tối đa ba lần, với một khoảng nghỉ ngắn ngẫu nhiên giữa các lần. Nếu máy chủ không xóa được một đối tượng, nó ghi chú lại và thử thêm trong mỗi lượt bảo trì, cứ sau 6 giờ, để một sự cố không để lại đối tượng sót.

### Ảnh chụp và bộ nhớ

Khi một dự án được chia sẻ, ứng dụng của chủ sở hữu tải lên ảnh chụp đầu tiên của nó và ký ảnh bằng khóa của thiết bị đó. Từ đó trở đi, máy chủ tự dựng mọi ảnh chụp, từ ảnh chụp trước đó và các thay đổi mọi người đã gửi từ lúc đó. Một ảnh chụp mới được dựng khi một dự án có thêm 1.000 thay đổi kể từ ảnh chụp cuối. Máy chủ luôn giữ lại ít nhất 2.000 thay đổi gần nhất, nên một thiết bị vắng mặt trong thời gian ngắn sẽ cập nhật từ đó và không phải tải lại toàn bộ dự án.

Việc dựng một ảnh chụp cần khoảng mười lần kích thước ảnh chụp trước cộng với các thay đổi từ lúc đó. Máy chủ chỉ bắt đầu một lượt dựng vừa với `OLEAFLY_SNAPSHOT_MEMORY_MB`, và các lượt dựng chạy cùng lúc chia sẻ số bộ nhớ đó. Nếu một lượt dựng không vừa, máy chủ bỏ qua nó, ghi vào nhật ký mức bộ nhớ nó cần và giữ lại toàn bộ thay đổi của dự án. Các thiết bị khi đó cập nhật từ những thay đổi đó, mỗi lần vài megabyte. Nâng cài đặt lên và ảnh chụp kế tiếp sẽ được dựng. Máy chủ không lưu một ảnh chụp lớn hơn `OLEAFLY_MAX_PROJECT_MB`.

### PDF đã biên dịch

Khi một chủ sở hữu hoặc người chỉnh sửa biên dịch thành công một dự án dùng chung, ứng dụng của họ gửi PDF lên máy chủ, kèm tệp SyncTeX nếu có. Mỗi dự án được gửi tối đa một lần mỗi phút. Máy chủ giữ một PDF và một tệp SyncTeX cho mỗi dự án, kèm tên tệp chính, người biên dịch và thời điểm biên dịch. [Truy cập qua trình duyệt](/docs/collaboration/server-access/#browser-access) hiển thị PDF này cho những người trong dự án.

Mỗi lần tải lên thay thế bản trước đó, và tệp cũ bị xóa khi không còn gì dùng đến nó. Các tệp đã biên dịch được lưu cùng các tệp khác, trên đĩa hoặc trong bucket, và bị xóa cùng dự án của chúng. Một tệp đã biên dịch có thể lớn tới `OLEAFLY_MAX_FILE_MB`. Nó được tính vào [dung lượng tài khoản](#limits-per-account) của chủ sở hữu, nhưng không tính vào số lần tải lên mỗi giờ.

Mọi thành viên của một dự án đều đọc được các tệp đã biên dịch của nó. Chỉ chủ sở hữu và người chỉnh sửa mới thay thế được chúng.

## Sau một reverse proxy

Máy chủ dùng HTTP thuần, nên cần một thứ đứng trước nó xử lý HTTPS: Caddy trong bộ cài Compose, proxy của Coolify, hoặc một máy chủ web bạn đã chạy, chẳng hạn máy chủ của trường bạn. Bất cứ thứ gì đứng trước đều phải:

- chấp nhận các yêu cầu lớn tới `OLEAFLY_MAX_PROJECT_MB`
- thêm địa chỉ của máy khách vào `X-Forwarded-For`

Nó cũng nên chuyển tiếp các yêu cầu nâng cấp WebSocket tới `/ws` và giữ những kết nối đó mở ít nhất một giờ. Chỉnh sửa trực tiếp dùng chúng khi có thể. Khi bật quyền truy cập qua trình duyệt, nó cũng phải chuyển tiếp chúng tới `/web/ws`, vì ứng dụng trình duyệt không có tuyến dự phòng chậm hơn.

Hãy chạy máy chủ ở nơi chỉ proxy mới tới được. Trên cùng một máy, đặt `OLEAFLY_BIND=127.0.0.1:8080`. Sau đó đặt `OLEAFLY_BEHIND_PROXY=true`.

### Khi kết nối WebSocket bị chặn

Một số mạng chặn kết nối WebSocket, thường là mạng trường đại học hoặc công ty có proxy lọc. Chỉnh sửa trực tiếp vẫn hoạt động ở đó, chỉ chậm hơn. Khi hai lần thử WebSocket liên tiếp thất bại trong khi máy chủ vẫn trả lời qua HTTPS, Oleafly chuyển sang long-polling qua HTTP. Nó gửi các chỉnh sửa tới `/api/v1/projects/<project>/frames` và chờ các chỉnh sửa của người khác trên `/api/v1/projects/<project>/poll`, giữ mỗi yêu cầu mở tối đa `OLEAFLY_POLL_HOLD_SECONDS`. Mọi chỉnh sửa vẫn tới nơi. Oleafly thử lại WebSocket mỗi phút và quay lại nó ngay khi một kết nối thành công.

**Test connection** trong Oleafly và **Connection checks** trong bảng điều khiển quản trị cho biết khi điều này xảy ra: "Live edits take a slower route because this network blocks the usual one. They still arrive."

Nếu chính bạn chạy proxy trước máy chủ, hãy vẫn chuyển tiếp các yêu cầu nâng cấp WebSocket. Long-polling hoạt động, nhưng mỗi nhóm chỉnh sửa tốn thêm một yêu cầu và một chút trễ nữa.

Một số proxy đóng những yêu cầu im lặng chưa đầy 30 giây, nginx với `proxy_read_timeout` ngắn là một ví dụ. Chúng trả lời các yêu cầu long-polling bằng lỗi 502 hoặc 504, và các chỉnh sửa tới muộn. Hãy đặt `OLEAFLY_POLL_HOLD_SECONDS` thấp hơn vài giây so với thời gian chờ đó, chẳng hạn `8` cho thời gian chờ 10 giây.

### OLEAFLY_BEHIND_PROXY thay đổi những gì

Máy chủ ghi địa chỉ máy khách ở hai nơi: nhật ký bảo mật, và các [giới hạn](#limits-for-a-class-on-one-network) về tần suất một địa chỉ có thể bắt đầu một lượt đăng nhập hoặc mở một kết nối trực tiếp.

Không có cài đặt này, máy chủ dùng địa chỉ của bất kỳ thứ gì kết nối tới nó. Sau một proxy, đó luôn là proxy, nên mọi người dùng chung một giới hạn và nhật ký bảo mật chỉ hiện địa chỉ của proxy.

Với `OLEAFLY_BEHIND_PROXY=true`, máy chủ đọc header `X-Forwarded-For` và dùng địa chỉ cuối trong đó, chính là địa chỉ proxy của bạn thêm vào. Nếu header bị thiếu hoặc không chứa địa chỉ hợp lệ, máy chủ quay lại dùng địa chỉ của bên kết nối. Không gì khác thay đổi. Máy chủ bỏ qua `X-Forwarded-Proto`, `X-Forwarded-Host` và `Forwarded`, và dựng mọi địa chỉ nó đưa ra từ `OLEAFLY_PUBLIC_URL`.

Chỉ bật nó khi mọi yêu cầu đều đi qua proxy của bạn. Nếu mọi người cũng có thể tới máy chủ trực tiếp, bất kỳ ai cũng có thể gửi một `X-Forwarded-For` bịa đặt, ghi địa chỉ tùy ý vào nhật ký bảo mật và né giới hạn đăng nhập.

Với hai proxy nối tiếp nhau, chẳng hạn Cloudflare đứng trước proxy của Coolify, hãy đặt `OLEAFLY_PROXY_HOPS=2`. Máy chủ khi đó lấy địa chỉ thứ hai kể từ cuối. Chỉ đếm những proxy mà mọi yêu cầu đều đi qua. Một Cloudflare Tunnel dẫn thẳng tới máy chủ được tính là một.

Để kiểm tra con số đó, hãy đăng nhập từ máy tính của bạn và mở **Security log** trong bảng điều khiển quản trị. Mục mới nhất phải hiện địa chỉ công cộng của bạn, là địa chỉ mà một trang như `ifconfig.me` báo. Nếu nó hiện một địa chỉ riêng tư hoặc địa chỉ Cloudflare thay vào đó, hãy tăng `OLEAFLY_PROXY_HOPS` lên một.

### Caddy

Caddy chuyển tiếp các kết nối WebSocket và `X-Forwarded-For` mà không cần cài đặt thêm, và tự lấy chứng chỉ. [Đặt HTTPS ở phía trước](/docs/collaboration/server/#put-https-in-front) có nguyên văn `Caddyfile`.

### nginx

Hãy lấy chứng chỉ cho tên miền trước, ví dụ bằng certbot. Sau đó lưu nội dung này thành `/etc/nginx/conf.d/oleafly.conf` và chạy `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` khớp với `OLEAFLY_MAX_PROJECT_MB` mặc định là 200. Nếu bạn tăng cái này, hãy tăng cả cái kia.

### Apache

Bạn cần Apache 2.4.47 trở lên, có sẵn trong Debian 12 và Ubuntu 22.04 trở lên. Hãy bật các module:

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

Lưu nội dung này thành `/etc/apache2/sites-available/oleafly.conf`, rồi chạy `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` chuyển tiếp các kết nối WebSocket và `timeout=3600` giữ chúng mở trong một giờ. Apache tự thêm địa chỉ của máy khách vào `X-Forwarded-For`.

### Dưới một đường dẫn

Nếu máy chủ nằm dưới một đường dẫn, hãy đưa đường dẫn vào `OLEAFLY_PUBLIC_URL`, ví dụ `https://www.cs.example.edu/oleafly`, và vào các địa chỉ callback bạn đăng ký với các nhà cung cấp đăng nhập. Máy chủ trả lời cả khi có và không có đường dẫn đó, nên proxy của bạn có thể chuyển tiếp hoặc lược bỏ nó. Với nginx, dùng `location /oleafly/ {` với các dòng giống nhau bên trong, và giữ `proxy_pass http://127.0.0.1:8080;` không kèm đường dẫn để nginx chuyển tiếp đường dẫn.

## Giới hạn cho một lớp học trên cùng một mạng

Cả một lớp thường đăng nhập từ cùng một địa chỉ mạng, chẳng hạn NAT của trường đại học. Các giá trị mặc định được đặt cho tình huống đó:

- **Đăng nhập**: một địa chỉ nhận một đợt 300 yêu cầu đăng nhập, rồi hai yêu cầu mỗi giây. Một lượt đăng nhập tốn khoảng sáu yêu cầu, nên 50 người có thể đăng nhập cùng lúc. Hãy thay đổi các giá trị này bằng `OLEAFLY_SIGN_IN_BURST` và `OLEAFLY_SIGN_IN_PER_MINUTE`.
- **Liên kết email**: 100 cho một địa chỉ trong 15 phút, và 3 cho một địa chỉ email. Hãy thay đổi các giá trị này bằng `OLEAFLY_EMAIL_LINKS_PER_IP` và `OLEAFLY_EMAIL_LINKS_PER_ADDRESS`.
- **Mã đăng nhập**: 100 mã, và 10 mã sai, từ một địa chỉ trong 10 phút. Hãy thay đổi giá trị này bằng `OLEAFLY_DEVICE_CODES_PER_IP`.
- **Kết nối trực tiếp** có giới hạn riêng, lớn hơn, để cả một lớp sau cùng một địa chỉ có thể kết nối lại cùng lúc sau một lần khởi động lại. Chỉ những kết nối không chứng minh được phiên của mình mới tiêu giới hạn đó: một đợt 300, rồi mười mỗi giây. Một kết nối chứng minh được phiên của mình thì được tính vào thiết bị của chính nó, thiết bị đó có thể kết nối lại 60 lần trong một đợt, rồi một lần mỗi giây.

Mọi địa chỉ IPv6 trong cùng một mạng `/64` được tính là một địa chỉ. Các giới hạn này chỉ đúng theo từng người khi máy chủ thấy địa chỉ thật của mỗi người, nên hãy [thiết lập proxy](#what-oleafly_behind_proxy-changes) của bạn đúng cách.

Máy chủ ping mỗi kết nối trực tiếp cứ sau 30 giây. Máy chủ đóng một kết nối nếu để những ping đó không được trả lời trong 90 giây, và đóng một kết nối ngừng đọc những gì máy chủ gửi.

Giới hạn dự án áp dụng cho mọi người: `OLEAFLY_MAX_PROJECT_MB` cho cả một dự án (mặc định 200 MB), `OLEAFLY_MAX_FILE_MB` cho một tệp (50 MB) và `OLEAFLY_MAX_MEMBERS_PER_PROJECT` cho số người trên một dự án (20). **Overview** trong bảng điều khiển quản trị hiển thị các giới hạn hiện tại.

## Giới hạn cho mỗi tài khoản

Ba giới hạn áp dụng cho mỗi tài khoản. Chúng tắt cho đến khi bạn đặt chúng, trừ khi [đăng ký mở](/docs/collaboration/server-access/#open-sign-up) đang bật. Khi đó chúng được bật với các giá trị mặc định sau:

| Giới hạn | Cài đặt | Khi bật đăng ký mở |
| --- | --- | --- |
| Dung lượng cho các dự án do một tài khoản sở hữu | `OLEAFLY_ACCOUNT_STORAGE_MB` | 100 MB |
| Số dự án dùng chung do một tài khoản sở hữu | `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | 50 |
| Số lần tải lên của một tài khoản trong một giờ | `OLEAFLY_UPLOADS_PER_HOUR` | 300 |

Giá trị bạn đặt luôn được ưu tiên hơn giá trị mặc định. Mỗi giá trị phải là một số nguyên từ 1 trở lên.

- **Dung lượng** cộng dồn các tệp và lịch sử thay đổi của mọi dự án mà tài khoản sở hữu, kể cả các dự án đã lưu trữ, cùng các PDF đã biên dịch của chúng. Ảnh chụp không được tính. Một tệp mà bất kỳ ai thêm vào một dự án được tính cho chủ sở hữu dự án. Khi tài khoản của chủ sở hữu đã đầy, máy chủ từ chối các tệp mới và PDF đã biên dịch cho các dự án của họ, và họ không thể chia sẻ thêm dự án nào. Tệp vẫn nằm trên máy tính của người đã thêm nó. Văn bản mọi người gõ vẫn được đồng bộ.
- **Dự án dùng chung** đếm các dự án mà tài khoản chia sẻ, kể cả những dự án vẫn đang tải lên. Dự án đã lưu trữ không được tính, nên ngừng chia sẻ một dự án sẽ giải phóng chỗ.
- **Lượt tải lên** đếm mọi lần tải lên tệp và ảnh chụp trong khoảng một giờ. PDF đã biên dịch không được tính. Oleafly tự gửi lại một tệp bị từ chối sau đó.

**Overview** trong bảng điều khiển quản trị không hiển thị các giới hạn này. Khi bật đăng ký mở, nhật ký máy chủ nêu tên chúng mỗi lần máy chủ khởi động.

## Nhật ký

- **Nhật ký máy chủ** là những gì `docker compose logs oleafly-server`, **Logs** của Coolify hoặc `journalctl -u oleafly-server` hiển thị. `OLEAFLY_LOG_LEVEL` đặt mức chi tiết của nó.
- **Nhật ký bảo mật** ghi lại các lượt đăng nhập và lượt đăng nhập bị từ chối, thiết bị, người dùng, vai trò, cài đặt, dự án và khách, mỗi mục kèm thời gian và địa chỉ IP. Quản trị viên và người bảo trì đọc nó dưới **Security log** trong bảng điều khiển quản trị. Các mục cũ hơn `OLEAFLY_SECURITY_LOG_DAYS` ngày sẽ bị xóa.
- **Nhật ký truy cập dự án** ghi lại ai đã mở một dự án, tham gia dự án hoặc tải một bản sao, kèm tên thiết bị và thời gian. Chủ của dự án bật nó, khi **Allow project access logs** đang bật, và chỉ chính chủ đó mới đọc được nó. Thời gian giữ cũng như vậy.

## Sao lưu

Một bản sao lưu đầy đủ cần gì tùy vào nơi lưu trữ tệp:

- **Tệp trên đĩa** (`OLEAFLY_BLOB_STORE=fs`, mặc định): cơ sở dữ liệu, tệp và ảnh chụp đều nằm trong thư mục dữ liệu. Hãy sao lưu cả thư mục.
- **Tệp trong một bucket**: thư mục dữ liệu chứa cơ sở dữ liệu và bucket chứa tệp cùng ảnh chụp. Một bản sao của cơ sở dữ liệu cộng với bucket là một bản sao lưu đầy đủ. Hãy bật quản lý phiên bản cho bucket để một đối tượng bị xóa nhầm có thể được đưa lại.

Hãy sao lưu thường xuyên và giữ các bản sao ở nơi riêng tư, vì chúng chứa mọi dự án. Các cài đặt của bạn, chẳng hạn `.env`, không nằm trong thư mục dữ liệu, nên hãy giữ thêm một bản sao của chúng.

Với Docker, máy chủ dừng vài giây trong lúc bạn sao chép volume. Oleafly tự kết nối lại. Hãy chạy các lệnh này trong thư mục của máy chủ, `/opt/oleafly-server` nếu bạn dùng bộ cài đặt.

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

Với 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
```

Hãy sao chép tệp nén sang một máy khác.

Trên Coolify, tên volume bắt đầu bằng ID của tài nguyên. Hãy tìm nó bằng `docker volume ls --filter name=oleafly-data`, dùng nó thay cho `oleafly-server_oleafly-data`, và dừng cũng như khởi động máy chủ từ bảng điều khiển của Coolify thay vì bằng `docker compose`.

### Diễn tập khôi phục

Một bản sao lưu chưa từng được khôi phục chỉ là một mong đợi. Buổi diễn tập này khởi động một bản sao thứ hai của máy chủ từ bản sao lưu, không động vào bản đang chạy, và kiểm tra rằng cả hai là cùng một máy chủ. Hãy dùng ngày của tệp nén riêng của bạn thay cho `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` trong hai câu trả lời phải khớp nhau. Bản diễn tập có một chỗ đăng nhập GitHub giả không thể đăng nhập cho ai, và không có cổng mở, nên không ai dùng được nó. Hãy xóa nó khi bạn làm xong:

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

### Khôi phục

Để khôi phục thật bằng Docker Compose, hãy dừng máy chủ, thay nội dung volume bằng tệp nén, rồi khởi động lại:

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

Với 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
```

Một máy chủ đã khôi phục thiếu các thay đổi mọi người thực hiện sau bản sao lưu. Mỗi ứng dụng nhận ra điều này khi kết nối lại, dù nó vẫn đang mở hay được mở sau đó, và tự gửi lại các thay đổi còn thiếu của mình. Không ai phải làm gì cho việc đó. Một thay đổi dựa trên thay đổi còn thiếu của người khác phải đợi tới khi người đó mở dự án, vì chỉ ứng dụng của họ mới gửi được các thay đổi của họ. Hãy nhờ mọi người đã chỉnh sửa quanh thời điểm xảy ra sự cố mở dự án một lần.

### Các bản sao liên tục với Litestream

Một tệp nén chỉ chứa những gì có ở thời điểm bạn tạo nó. [Litestream](https://litestream.io) sao chép mỗi thay đổi vào cơ sở dữ liệu của máy chủ tới một bucket tương thích S3 khoảng một giây sau khi thay đổi xảy ra. Tệp Compose gồm nó như một dịch vụ tùy chọn.

Litestream chỉ sao chép cơ sở dữ liệu. Nếu tệp nằm trong một bucket, bucket đã chứa sẵn tệp và ảnh chụp, nên bản sao Litestream cùng bucket có thể khôi phục lại một đĩa đã mất. Nếu tệp nằm trên đĩa, hãy tiếp tục tạo tệp nén của volume nữa, vì Litestream không sao chép thư mục `blobs`.

1. Tạo một bucket, hoặc một thư mục trong một bucket, mà chỉ Litestream của máy chủ này dùng. Đừng dùng chung nó với `OLEAFLY_BLOB_STORE`. Hãy cho Litestream một khóa có thể liệt kê bucket và đọc, ghi cùng xóa các đối tượng trong đó.
2. Thêm các chi tiết vào `.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
   ```

   Với một kho lưu trữ không phải Amazon S3, hãy đặt `LITESTREAM_ENDPOINT` thành địa chỉ của nó và `LITESTREAM_REGION` thành vùng mà nó yêu cầu (`auto` với R2). `COMPOSE_PROFILES` khiến mọi lệnh `docker compose` gồm cả Litestream.
3. Khởi động nó:

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

4. Kiểm tra rằng nó đã sao chép cơ sở dữ liệu. Lệnh này in ra một dòng có `snapshot complete`:

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

Litestream lấy một bản sao đầy đủ mỗi ngày một lần và giữ các bản sao trong một tuần cùng các thay đổi giữa chúng. Lịch trình nằm trong `litestream.yml`.

#### Diễn tập khôi phục Litestream

Buổi diễn tập này khôi phục cơ sở dữ liệu từ bucket vào một volume tạm, khởi động một bản sao thứ hai của máy chủ trên đó, và kiểm tra rằng cả hai là cùng một máy chủ. Máy chủ đang chạy không bị ảnh hưởng.

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

Lệnh đầu tiên tạo volume tạm với chủ sở hữu mà máy chủ cần. `server_id` trong hai câu trả lời cuối phải khớp nhau. Hãy xóa bản sao khi bạn làm xong:

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

#### Khôi phục cơ sở dữ liệu từ Litestream

Khi tệp cơ sở dữ liệu bị hỏng hoặc mất nhưng phần còn lại của thư mục dữ liệu vẫn nguyên, hãy dừng máy chủ và Litestream, xóa phần cơ sở dữ liệu còn sót, khôi phục nó rồi khởi động lại:

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

Sau khi mất đĩa với tệp nằm trong bucket, hãy chạy các lệnh trên trên volume mới, trống và giữ nguyên các cài đặt bucket trong `.env`. Mọi dự án quay lại cùng tệp và ảnh chụp của chúng.

Sau khi mất đĩa với tệp nằm trên đĩa, hãy [khôi phục](#restore) tệp nén mới nhất của bạn và dừng ở đó. Đừng đặt một cơ sở dữ liệu mới hơn từ Litestream lên trên một tệp nén cũ hơn. Cơ sở dữ liệu sẽ trỏ tới các tệp và ảnh chụp mà tệp nén không có, và những dự án đó sẽ không mở được.

## Cập nhật

Hãy sao lưu trước. Máy chủ cập nhật cơ sở dữ liệu của nó ở lần đầu tiên một bản phát hành mới khởi động, nên quay lại một bản phát hành cũ hơn nghĩa là khôi phục bản sao lưu bạn đã lấy trước khi cập nhật.

- **Cài đặt bằng một lệnh**: chạy `curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update`. Nó giữ lại `.env`, lấy các tệp và image của bản phát hành mới, rồi khởi động lại máy chủ.
- **Docker Compose thủ công**: tải các tệp của bản phát hành mới vào thư mục của máy chủ như trong [Docker Compose thủ công](/docs/collaboration/server/#docker-compose-by-hand), rồi chạy `sudo docker compose up -d`.
- **Coolify**: chọn **Redeploy**. Với image đã xuất bản, thao tác đó kéo bản phát hành mới nhất dưới tag của image.
- **Render**: mở dịch vụ và bắt đầu một lần triển khai thủ công, lần đó sẽ kéo lại image.
- **Railway**: triển khai lại dịch vụ từ menu của nó. Railway cũng có thể tự cập nhật một image từ registry của GitHub.
- **systemd**: cài bản phát hành mới như trong [Tải xuống máy chủ](/docs/collaboration/server/#download-the-server), rồi chạy `sudo systemctl restart oleafly-server`.

Oleafly kiểm tra phiên bản máy chủ mỗi lần nó kết nối. Nếu ứng dụng và máy chủ không thể hoạt động cùng nhau, Oleafly cho biết bên nào cần cập nhật.
