Tự dựng và vận hành

Giám sát Beta

Kiểm tra sức khoẻ từng thành phần, đọc nhật ký, số liệu có trong v1 và các cảnh báo nên đặt.

Trang này mô tả tính năng đang ở giai đoạn beta: đã chạy được nhưng có thể còn thay đổi.

Trong trang này

Kiểm tra sức khoẻ
Nhật ký
Số liệu có trong v1
Cảnh báo nên đặt

Kiểm tra sức khoẻ#

Thành phần	Kiểm tra	Khoẻ khi	Ghi chú
o3o-proxy + o3o-gate	`GET /o3o/healthz`	`200 {"ok": true}`	Không phụ thuộc máy chủ soạn thảo.
Gate đếm được	`GET /o3o/status`	`upstream.coolwsd = "ok"` và `connections.enforcing = true`	`down`: không nối được; `auth_failed`: sai mật khẩu quản trị.
Máy chủ soạn thảo	`GET /hosting/discovery`	200, thân XML	Container còn có kiểm tra sức khoẻ sẵn trong image.
o3o-docbuilder	`GET /v1/status`	200, còn worker sống (`idle + busy > 0`)	Không cần xác thực.
o3o-nextcloud	`GET /status.php` (8081)	`"installed": true`	Chỉ hồ sơ `nextcloud`.

GET/o3o/healthz

Tiến trình gate còn sống. Dùng cho Docker và công cụ giám sát.

Xác thực: không cầnCộng đồngDoanh nghiệp

GET/v1/status

Trạng thái DocBuilder: phiên bản, lõi xử lý tài liệu, worker, hàng đợi. Không cần xác thực.

Xác thực: không cầnCộng đồngDoanh nghiệp

200Ví dụ; số liệu là minh hoạ.

{
  "service": "o3o-docbuilder",
  "version": "1.0.0",
  "api": "v1",
  "time": "2026-09-21T10:00:00Z",
  "edition": "community",
  "dev_mode": false,
  "core": {
    "name": "LibreOffice",
    "version": "7.4.7.2",
    "source": "debian-bookworm"
  },
  "workers": {
    "total": 2,
    "idle": 2,
    "busy": 0,
    "restarts": 0
  },
  "queue": {
    "queued": 0,
    "running": 0
  },
  "uptime_seconds": 3600
}

BashKiểm nhanh cả hệ thống

#!/usr/bin/env bash
# Kiểm nhanh O3O Office Online; mã thoát khác 0 khi có mục hỏng
BASE="${BASE:-http://localhost:8080}"
fail=0
ok()  { echo "OK    $1"; }
bad() { echo "LỖI  $1"; fail=1; }

curl -fsS "$BASE/o3o/healthz" >/dev/null && ok "proxy + gate" || bad "proxy + gate"
curl -fsS "$BASE/hosting/discovery" >/dev/null && ok "máy chủ soạn thảo" || bad "máy chủ soạn thảo"
curl -fsS "$BASE/o3o/status" \
  | jq -e '.upstream.coolwsd == "ok" and .connections.enforcing' >/dev/null \
  && ok "gate đếm được kết nối" || bad "gate đếm được kết nối"
curl -fsS "$BASE/v1/status" \
  | jq -e '.workers.idle + .workers.busy > 0' >/dev/null \
  && ok "DocBuilder" || bad "DocBuilder"
exit "$fail"

Nhật ký#

Gate và DocBuilder ghi ra stdout, mỗi sự kiện một dòng JSON; mức chi tiết đặt bằng O3O_LOG_LEVEL.
Nhật ký không bao giờ chứa nội dung tài liệu, token hay khoá API.
Mọi phản hồi mang X-O3O-Request-Id; dùng mã này để tìm đúng dòng nhật ký của một yêu cầu.
Image máy chủ soạn thảo không có shell: xem nhật ký bằng docker compose logs, không docker exec được.
Giới hạn dung lượng nhật ký bằng tuỳ chọn logging của Docker (ví dụ trình điều khiển local với max-size, max-file).

BashĐọc nhật ký

cd online
DC="docker compose --env-file .env -f docker/compose.dev.yml"

$DC logs -f --since 10m o3o-gate o3o-docbuilder     # theo dõi 10 phút gần nhất
$DC logs o3o-online | tail -200                     # máy chủ soạn thảo
$DC logs o3o-gate o3o-docbuilder | grep req_0123456789abcdef   # tìm theo mã yêu cầu

Số liệu có trong v1#

Nguồn	Số liệu
`GET /o3o/status`	`connections`: current, pending, peak_5m, limit, readonly, views_total, documents, limit_reached, enforcing, sample_age_seconds; `license`: state, grace_days_left; `embed`: open_documents, sessions
`GET /v1/status`	`workers`: total, idle, busy, restarts; `queue`: queued, running; uptime_seconds
`GET /v1/limits`	Mức đã dùng trong phút và trong ngày, job đang chạy và đang chờ
`usage-YYYY-MM.csv`	Đỉnh kết nối mỗi 5 phút, xem Kết nối được đếm thế nào

Cảnh báo nên đặt#

Điều kiện	Nghĩa là	Việc cần làm
`connections.enforcing = false` kéo dài	Gate không đếm được, đang cho qua toàn bộ.	Kiểm `upstream.coolwsd` và mật khẩu quản trị.
`upstream.coolwsd = "auth_failed"`	`O3O_COOLWSD_ADMIN_PASSWORD` lệch với máy chủ soạn thảo.	Sửa `.env`, tạo lại cả hai dịch vụ.
`limit_reached = true` thường xuyên, hoặc `peak_5m` sát `limit`	Thiếu kết nối vào giờ cao điểm.	Đối soát bằng tệp CSV, cân nhắc mua thêm; xem Bản quyền.
`license.state = "grace"`	Token năm đã quá hạn, còn `grace_days_left` ngày.	Gia hạn và nạp token mới.
`workers.restarts` tăng nhanh	Tệp lỗi hoặc job quá giờ liên tục.	Xem nhật ký `o3o-docbuilder`.
`queue.queued` gần `max_queued_jobs`	Sắp trả `503 queue_full`.	Giãn tải, hoặc tăng `O3O_DOCBUILDER_WORKERS` ở bản doanh nghiệp.
`embed.callback_signing = false`	Callback đang đi không có chữ ký.	Đặt `O3O_EMBED_CALLBACK_SECRET`.

PythonKiểm cảnh báo bằng Python

# pip install requests
import requests

BASE = "http://localhost:8080"


def alerts() -> list[str]:
    out = []
    s = requests.get(f"{BASE}/o3o/status", timeout=10).json()
    c, lic = s["connections"], s["license"]
    if not c["enforcing"]:
        out.append("Bộ đếm đang fail-open")
    if s["upstream"]["coolwsd"] != "ok":
        out.append("Máy chủ soạn thảo: " + s["upstream"]["coolwsd"])
    if c["limit_reached"]:
        out.append(f"Đã chạm trần kết nối {c['current']}/{c['limit']}")
    if lic["state"] == "grace":
        out.append(f"Token trong thời gian ân hạn, số ngày còn lại: {lic['grace_days_left']}")
    if not s["embed"]["callback_signing"]:
        out.append("Callback không có chữ ký")
    d = requests.get(f"{BASE}/v1/status", timeout=10).json()
    if d["workers"]["idle"] + d["workers"]["busy"] == 0:
        out.append("DocBuilder không còn worker sống")
    return out


print("\n".join(alerts()) or "OK")

Sắp có

Endpoint chỉ số theo định dạng Prometheus, P95 kết nối theo 30 ngày và trang biểu đồ sử dụng.

Báo lỗi hoặc góp ý cho trang nàyO3O Office Online · API v1 · Phiên bản trang 26.8.6