Bắt đầu

Kiến trúc và thành phần Beta

Bốn dịch vụ sau một cửa vào duy nhất: proxy nginx, máy chủ soạn thảo, o3o-gate và DocBuilder. Định tuyến, ba luồng dữ liệu chính, cách đếm kết nối, mạng, volume và các biến phải đổi khi chạy thậ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

Các dịch vụ
Định tuyến của proxy
Luồng mở tài liệu qua Nextcloud
Luồng nhúng trực tiếp
Luồng DocBuilder
Đếm kết nối
Mạng, volume và cổng
Biến phải đổi khi chạy thật
Image DEV và bản phát hành
Hiệu năng và phần cứng
Giấy phép

Bản v1 ưu tiên ít thành phần và chạy chắc: o3o-gate và DocBuilder viết bằng Python, hàng đợi của DocBuilder nằm trong bộ nhớ, mỗi dịch vụ là một container. Không có mã nào của O3O được vá vào máy chủ soạn thảo; các dịch vụ nói chuyện với nhau qua HTTP và WebSocket.

Sơ đồ thành phần của bản Docker v1. Nét liền là đường gọi chính, nét đứt là đường phụ (đọc số phiên, callback).

Các dịch vụ#

Dịch vụ	Cổng	Nền	Trách nhiệm	Kiểm tra sức khoẻ
`o3o-proxy`	8080	`nginx:1.27-alpine`	Cửa vào duy nhất: định tuyến, `auth_request` hỏi o3o-gate, chặn đường quản trị của máy chủ soạn thảo, cho qua khi o3o-gate không trả lời.	`GET /o3o/healthz` qua proxy
`o3o-online`	9980	coolwsd (mã MPL 2.0)	Soạn thảo cộng tác trong trình duyệt.	`GET /readyz`
`o3o-gate`	8070	Python 3.12, FastAPI	Đếm phiên, áp trần kết nối, token bản quyền, `api.js`, phiên nhúng, WOPI host nội bộ, callback.	`GET /o3o/healthz`
`o3o-docbuilder`	8060	Debian bookworm, LibreOffice, FastAPI	API REST `/v1/*`: chuyển đổi, dựng từ o3oscript, điền mẫu, trích xuất.	`GET /v1/status`
`o3o-nextcloud` và CSDL	80 ra 8081	`nextcloud:30-apache`, `mariadb:11`, `redis:7-alpine`	Hồ sơ tuỳ chọn `nextcloud` để thử đấu nối.	`GET /status.php`

Định tuyến của proxy#

Đường dẫn	Tới	Ghi chú
`/browser/<mã>/cool.html`	o3o-online	Qua `auth_request` giai đoạn `page`. Bị từ chối thì o3o-gate trả trang báo đã đạt giới hạn kết nối.
`/cool/<tài liệu>/ws`, `/cool/ws?WOPISrc=…` và mọi dạng WebSocket khác	o3o-online	WebSocket, qua `auth_request` giai đoạn `ws`. Yêu cầu WebSocket mà o3o-gate không phân tích được bị từ chối.
`/browser`, `/cool/`, `/hosting`, `/lool/`	o3o-online	Không qua o3o-gate; không chuyển tiếp nâng cấp WebSocket.
`/browser/dist/admin`, `/cool/adminws`, `/cool/getMetrics`	404	Bảng quản trị và số liệu của máy chủ soạn thảo không mở ra ngoài, kể cả dạng có dấu `/` cuối.
`/o3o/`	o3o-gate	Riêng `/o3o/auth` và `/o3o/wopi/` trả 404 khi gọi từ bên ngoài.
`/v1/`	o3o-docbuilder	Không đệm thân yêu cầu; giới hạn cỡ tệp do DocBuilder tự áp theo gói.
`/`	302 tới `/o3o/`

Luồng mở tài liệu qua Nextcloud#

Quản trị cài ứng dụng kết nối richdocuments rồi chạy richdocuments:activate-config với -w http://o3o-online:9980 (địa chỉ Nextcloud gọi máy chủ soạn thảo) và -c http://o3o-nextcloud (địa chỉ máy chủ soạn thảo gọi ngược về Nextcloud, thành gốc của WOPISrc). Nextcloud đọc /hosting/discovery để biết đường dẫn trang soạn thảo.
Người dùng bấm vào một tệp. Nextcloud dựng iframe và gửi form tới cool.html kèm WOPISrc và access_token.
Proxy hỏi o3o-gate: còn chỗ thì trang soạn thảo nạp; hết chỗ thì người dùng thấy trang báo đạt giới hạn, có nút mở chỉ đọc hoặc thử lại.
Trang soạn thảo mở WebSocket; proxy hỏi o3o-gate lần nữa ở giai đoạn ws.
Máy chủ soạn thảo gọi ngược về Nextcloud theo WOPI: CheckFileInfo, GetFile, và PutFile khi lưu. o3o-gate không nằm trên đường lưu nên không thể chặn lưu.

Luồng nhúng trực tiếp#

Trang của bạn nạp /o3o/api.js và gọi new O3O.Editor(id, config).
api.js gửi POST /o3o/embed/session. o3o-gate kiểm origin và JWT, tải document.url theo quy tắc chống SSRF, xét trần kết nối, rồi trả địa chỉ trang soạn thảo và access_token.
api.js dựng iframe và gửi form; WOPISrc trỏ vào WOPI host nội bộ của o3o-gate.
Máy chủ soạn thảo gọi o3o-gate qua mạng nội bộ để đọc và ghi tệp. Mỗi lần lưu, o3o-gate ghi phiên bản mới, trả lời ngay rồi gửi callback ký HMAC tới callbackUrl.
Trình duyệt nhận sự kiện qua postMessage. Mọi người rời tài liệu 30 giây thì o3o-gate gửi callback closed và giữ tệp 24 giờ.

Luồng DocBuilder#

Máy chủ của bạn gọi /v1/convert, /v1/build, /v1/template/render hoặc /v1/extract/* kèm Authorization: Bearer.
DocBuilder xác thực, xét gói theo token bản quyền, xét hạn mức tần suất, kiểm tham số (kịch bản o3oscript được kiểm bằng JSON Schema), tải URL nguồn nếu có, rồi đưa job vào hàng đợi trong bộ nhớ.
Một worker rảnh (một tiến trình LibreOffice không giao diện riêng) xử lý job. Macro không bao giờ chạy: tệp nạp qua LibreOffice luôn ở chế độ tắt macro, còn mẫu có macro bị /v1/template/render từ chối với 422 macro_not_allowed. Quá giờ thì worker bị dừng, dựng lại, job báo lỗi timeout.
Chế độ đồng bộ trả thẳng tệp. Chế độ bất đồng bộ trả 202 kèm job; bạn hỏi GET /v1/jobs/{id} và tải GET /v1/files/{id}.

Đếm kết nối#

Một kết nối là một phiên soạn thảo đồng thời. Một người mở 3 tài liệu ở chế độ sửa = 3 kết nối. Ba người cùng sửa 1 tài liệu = 3 kết nối. o3o-gate lấy mẫu số phiên sửa mỗi 10 giây từ kênh quản trị nội bộ của máy chủ soạn thảo, báo đỉnh trượt 5 phút để đối soát, và cho phép nối lại trong 120 giây kể cả khi đã chạm trần.

Không bao giờ ngắt phiên đang mở, kể cả khi trần bị hạ (token hết hạn, đổi token).
Không bao giờ chặn lưu: o3o-gate không nằm trên đường lưu của Nextcloud; với phiên nhúng, thao tác lưu không xét trần.
Chạm trần: phiên mới qua Nextcloud thấy trang báo đạt giới hạn; phiên nhúng mới được mở ở chế độ chỉ đọc kèm băng thông báo.
Lỗi đếm hoặc máy chủ soạn thảo không trả lời: o3o-gate cho qua (fail-open) và ghi nhật ký. o3o-gate chết hẳn thì nginx cũng cho qua.
Mỗi 5 phút o3o-gate ghi một dòng vào /data/usage/usage-YYYY-MM.csv để bạn tự đối soát.

Mạng, volume và cổng#

Một mạng bridge o3o-net; các dịch vụ gọi nhau bằng tên dịch vụ.
Volume: o3o-gate-data, o3o-docbuilder-data, o3o-nextcloud-html, o3o-nextcloud-db.
Chỉ hai cổng mở ra máy chủ: O3O_PROXY_PORT (mặc định 8080) và O3O_NEXTCLOUD_PORT (mặc định 8081, chỉ khi bật hồ sơ nextcloud).
Máy chủ soạn thảo cần cap_add: [MKNOD]; image của nó không có shell nên gỡ lỗi bằng docker logs.

Biến phải đổi khi chạy thật#

Biến môi trường

O3O_PUBLIC_URLURLbắt buộcMặc định: http://localhost:8080
URL công khai của proxy, không có dấu / cuối. Dùng để dựng URL tải tệp trong callback và job.
O3O_ONLINE_SERVER_NAMEhost[:port]bắt buộcMặc định: localhost:8080
Tên máy công khai; quyết định urlsrc trong /hosting/discovery.
O3O_ONLINE_SSL_TERMINATIONtrue | falsebắt buộcMặc định: false
Đặt true khi người dùng vào bằng https (TLS do proxy phía trước đảm nhận).
O3O_ONLINE_FRAME_ANCESTORSorigintuỳ chọn
Origin của trang nhúng khi khác origin với máy chủ, một giá trị không có dấu cách.
O3O_COOLWSD_ADMIN_PASSWORDstringbắt buộc
Mật khẩu quản trị nội bộ của máy chủ soạn thảo; o3o-gate dùng để đếm phiên. Không có giá trị dự phòng: compose từ chối khởi động khi biến rỗng, gate với O3O_DEV_MODE=0 từ chối khởi động khi mật khẩu rỗng hoặc còn CHANGE_ME.
O3O_EMBED_JWT_SECRETstring ≥ 32bắt buộc
Khoá HS256 xác minh cấu hình nhúng đã ký.
O3O_EMBED_CALLBACK_SECRETstringbắt buộc
Khoá HMAC SHA-256 ký callback lưu tài liệu.
O3O_EMBED_ALLOWED_ORIGINSlistbắt buộcMặc định: *
Origin được phép nhúng; không để * khi chạy thật.
O3O_DOCBUILDER_API_KEYSlistbắt buộc
Khoá API của DocBuilder, dạng ten:khoa hoặc khoa, 24 tới 128 ký tự.
O3O_DEV_MODE0 | 1bắt buộcMặc định: 0
Phải là 0 khi chạy thật (tắt trang thử và chi tiết lỗi nội bộ).
O3O_EMBED_ALLOW_UNSIGNED0 | 1bắt buộcMặc định: 0
Phải là 0 khi chạy thật (bắt buộc ký JWT).

Danh sách đầy đủ các biến và mặc định nằm ở nhóm Tự dựng và vận hành.

Image DEV và bản phát hành#

	Chế độ DEV (v1)	Bản O3O phát hành
Image soạn thảo	Image thượng nguồn ghim theo digest (26.04.4.1.1)	Dựng từ nguồn; tệp dựng đã viết nhưng thử nghiệm, chưa dựng
Trạng thái	Chạy được, đã kiểm chứng	Sắp có
Thương hiệu	Tên và logo của thượng nguồn, không đổi được bằng cấu hình	Tên O3O Office Online; nhãn trắng cho bản doanh nghiệp (sắp có)
Trần sẵn trong image	20 kết nối, 10 tài liệu	Trần thật do o3o-gate áp theo gói
`GET /o3o/status`	`dev_image: true`	`dev_image: false`

Sắp có

Nhiều máy chủ soạn thảo sau một o3o-gate, đồng bộ khoá WOPI proof, hỗ trợ oCIS, hàng đợi DocBuilder bền vững qua khởi động lại, DocBuilder dùng lõi O3O 26.8 thay LibreOffice của Debian, chỉ số Prometheus.

Hiệu năng và phần cứng#

Chưa đo. Tài liệu chưa đưa con số về thời gian xử lý, số yêu cầu mỗi giây, bộ nhớ hay cấu hình tối thiểu theo số kết nối; các con số này sẽ được công bố khi có phép đo thật trên phần cứng xác định.

Giấy phép#

Máy chủ soạn thảo là mã nguồn mở theo giấy phép MPL 2.0; khi phát hành image O3O dựng từ nguồn, tệp nào của thượng nguồn được O3O sửa thì bản sửa sẽ được công bố cho người nhận image (sắp có). o3o-gate, api.js và cấu hình proxy là mã độc lập của O3O, chỉ giao tiếp với máy chủ soạn thảo qua HTTP và WebSocket.

Mã riêng của DocBuilder do O3O sở hữu và không sửa mã LibreOffice, nhưng không độc lập như vậy: nó nạp LibreOffice qua cầu nối UNO (python3-uno), và image của nó được phân phối KÈM LibreOffice 7.4 cài từ kho Debian bookworm, phần lớn theo MPL 2.0, một số tệp theo LGPL và Apache 2.0. Vì thế ai phân phối image DocBuilder phải giữ thông báo giấy phép của các gói đó (image giữ sẵn tệp /usr/share/doc/<gói>/copyright) và cho người nhận biết nơi lấy mã nguồn LibreOffice đúng phiên bản. Nghĩa vụ chi tiết ở mục giấy phép của trang Dựng từ nguồn.

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