Kết nối được đếm thế nào

1 kết nối = 1 phiên soạn thảo đồng thời: một view có quyền sửa đang mở trên máy chủ soạn thảo. Phiên chỉ đọc và mọi việc của DocBuilder không tính.

Cũng không tính: kiểm tra sức khoẻ, /hosting/discovery, /hosting/capabilities, và việc Nextcloud dựng ảnh xem trước qua /cool/convert-to trong mạng nội bộ. Đường /cool/convert-to không mở qua o3o-proxy (trả 404); hệ thống ngoài chuyển đổi bằng POST /v1/convert, cũng không tính kết nối.

Cách đếm#

1. Lấy mẫu

   Mỗi 10 giây, gate hỏi kênh quản trị nội bộ của máy chủ soạn thảo danh sách view đang mở và cờ chỉ đọc của từng view. Số view sửa trong mẫu mới nhất là current. Gate không lưu tên tệp hay tên người dùng.

2. Phiên vừa cho vào

   Phiên sửa vừa được cho vào nhưng chưa xuất hiện trong mẫu được tính vào pending, để nhiều người mở cùng lúc không vượt trần. Mục pending tự xoá khi có mẫu xác nhận, hoặc sau 60 giây.

3. Áp trần

   Phiên soạn thảo MỚI được cho vào khi current + pending < limit. limit là 50 với bản cộng đồng; với token doanh nghiệp hợp lệ, limit đúng bằng conns trong token, kể cả khi số đó nhỏ hơn 50. O3O_GATE_CONNECTION_CAP chỉ hạ được trần. Một người vừa rời thì chỗ trống dùng được ngay ở mẫu kế tiếp.

4. Đỉnh trượt 5 phút

   peak_5m là giá trị lớn nhất của current trong 300 giây gần nhất. Số này dùng để BÁO CÁO và đối soát, không dùng để từ chối.

5. Ân hạn nối lại

   Khi số view sửa của một tài liệu giảm, gate giữ suất ân hạn 120 giây cho tài liệu đó. Người mất mạng chớp nhoáng hoặc tải lại trang được vào lại đúng tài liệu đó kể cả khi trần đã đầy.

Khi chạm trần#

{
  "error": {
    "code": "connection_limit_reached",
    "message": "Hệ thống đã đạt giới hạn 50 phiên soạn thảo đồng thời của bản cộng đồng. Tài liệu của bạn vẫn an toàn. Bạn có thể mở ở chế độ chỉ đọc hoặc thử lại sau ít phút.",
    "detail": {
      "limit": 50,
      "current": 50,
      "edition": "community"
    },
    "request_id": "req_0123456789abcdef"
  }
}

Khi bộ đếm không hoạt động#

Gate theo nguyên tắc fail-open: nếu không có mẫu còn mới (tuổi mẫu quá 3 chu kỳ), connections.enforcing thành false và mọi phiên đều được cho vào. Nếu chính gate ngừng chạy, proxy cũng cho qua. Người dùng không bao giờ bị chặn vì lỗi của bộ đếm. Fail-open chỉ áp khi nguồn số liệu hoặc chính gate hỏng: yêu cầu WebSocket mà gate không phân tích được là yêu cầu lạ, không phải lỗi của bộ đếm, nên luôn bị từ chối.

Xem số liệu: GET /o3o/status#

{
  "service": "o3o-gate",
  "version": "1.0.0",
  "api": "v1",
  "time": "2026-09-21T10:00:00Z",
  "instance_id": "inst_3f9a1c0b7d2e4a55",
  "edition": "community",
  "dev_mode": false,
  "dev_image": true,
  "dev_image_note": "Image soạn thảo là bản thượng nguồn, CHỈ THỬ NỘI BỘ, không phải bản O3O phát hành.",
  "license": {
    "state": "none",
    "kind": null,
    "plan": null,
    "conns": null,
    "exp": null,
    "upd": null,
    "customer": null,
    "key_hint": null,
    "grace_days_left": null,
    "message": "Không có token bản quyền. Đang chạy bản cộng đồng."
  },
  "connections": {
    "limit": 50,
    "current": 3,
    "pending": 0,
    "peak_5m": 4,
    "readonly": 2,
    "views_total": 5,
    "documents": 2,
    "limit_reached": false,
    "source": "adminws",
    "sampled_at": "2026-09-21T09:59:55Z",
    "sample_age_seconds": 5,
    "enforcing": true
  },
  "upstream": {
    "coolwsd": "ok",
    "coolwsd_version": "26.04.4.1"
  },
  "embed": {
    "enabled": true,
    "jwt_required": true,
    "callback_signing": true,
    "open_documents": 1,
    "sessions": 2
  }
}

# Khối connections
curl -s http://localhost:8080/o3o/status | jq .connections

# Xem liên tục mỗi 10 giây
watch -n 10 'curl -s http://localhost:8080/o3o/status | jq -c "{current: .connections.current, peak_5m: .connections.peak_5m, limit: .connections.limit}"'

# pip install requests
import requests

s = requests.get("http://localhost:8080/o3o/status", timeout=10).json()
c = s["connections"]
print(f"{c['current'] + c['pending']}/{c['limit']} ({s['edition']}), peak_5m={c['peak_5m']}")
if not c["enforcing"]:
    print("Cảnh báo: bộ đếm đang fail-open")
if c["limit_reached"]:
    print("Đã chạm trần: phiên sửa mới sẽ bị từ chối")

Nhật ký đối soát#

Mỗi 5 phút gate ghi thêm một dòng vào /data/usage/usage-YYYY-MM.csv trong volume o3o-gate-data: ts_utc,peak_edit,peak_views_total,limit,edition, có dòng tiêu đề. Đây là số liệu để bạn tự đối soát khi cân nhắc mua thêm kết nối.

# Chạy trong thư mục online/; số liệu dưới đây là minh hoạ
docker compose --env-file .env -f docker/compose.dev.yml cp o3o-gate:/data/usage ./usage
head -3 ./usage/usage-2026-09.csv
# ts_utc,peak_edit,peak_views_total,limit,edition
# 2026-09-21T10:00:00Z,4,6,50,community
# 2026-09-21T10:05:00Z,7,9,50,community

Thử hành vi chạm trần trên máy DEV#

Image DEV của máy chủ soạn thảo có trần cứng riêng 20 kết nối và 10 tài liệu, nên trên máy DEV không thử được tới mốc 50. Đặt O3O_GATE_CONNECTION_CAP=2 rồi mở ba phiên sửa: phiên thứ ba nhận trang chạm trần, phiên chỉ đọc vẫn vào được.