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

Tự dựng máy chủ Beta

Yêu cầu máy, cổng, tên miền, chứng chỉ TLS và các lệnh chạy thử O3O Office Online bằng Docker trong vài phú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

Yêu cầu máy
Cổng
Chạy thử trong vài phút
Thêm Nextcloud để thử đấu nối
Tên miền và DNS
Chứng chỉ TLS

Trang này đưa O3O Office Online lên một máy có Docker: yêu cầu máy, cổng, tên miền, chứng chỉ, và các lệnh để chạy thử trong vài phút. Chi tiết từng dịch vụ và từng biến môi trường nằm ở Tệp compose và biến môi trường.

Yêu cầu máy#

Hạng mục	Yêu cầu	Ghi chú
Docker	Docker Engine trên Linux, hoặc Docker Desktop dùng engine Linux; Docker Compose v2 (lệnh `docker compose`)	Đã kiểm chứng trên Docker Desktop 29, engine Linux.
Kiến trúc CPU	x86_64 (amd64)	Kiến trúc khác: chưa kiểm.
CPU và RAM cho máy thử	Gợi ý tối thiểu 4 nhân, 8 GB RAM dành cho Docker	Cỡ máy theo số kết nối: chưa đo.
Đĩa	Gợi ý 25 GB trống cho image và dữ liệu	Dữ liệu nằm trong volume Docker.
Windows	Docker Desktop với WSL2	WSL2 mặc định chỉ dùng một phần RAM của máy; tăng giới hạn trong `.wslconfig` nếu container bị dừng vì thiếu bộ nhớ.

Cổng#

Cổng	Dịch vụ	Mở ra ngoài	Ghi chú
8080 (`O3O_PROXY_PORT`)	o3o-proxy	có	Cửa vào duy nhất, HTTP.
8081 (`O3O_NEXTCLOUD_PORT`)	o3o-nextcloud	có, chỉ hồ sơ `nextcloud`	Để thử đấu nối Nextcloud.
9980	o3o-online	không	Máy chủ soạn thảo; chỉ proxy và gate gọi tới.
8070	o3o-gate	không	Đi qua proxy ở `/o3o/`.
8060	o3o-docbuilder	không	Đi qua proxy ở `/v1/`.
3306, 6379	o3o-nextcloud-db, o3o-nextcloud-redis	không	Chỉ hồ sơ `nextcloud`.

Trên máy đã có dịch vụ khác giữ cổng 8080 hoặc 8081, đổi O3O_PROXY_PORT hoặc O3O_NEXTCLOUD_PORT, rồi đổi theo O3O_PUBLIC_URL và O3O_ONLINE_SERVER_NAME.

Chạy thử trong vài phút#

BashDựng và chạy (Linux, macOS hoặc Git Bash trên Windows)

# 1. Lấy mã nguồn O3O Office (thư mục online/ chứa bản Docker)
git clone <URL kho mã O3O Office> o3o-office
cd o3o-office

# 2. Dựng image gate và DocBuilder; ngữ cảnh dựng luôn là online/
docker build -f online/gate/Dockerfile -t o3o/gate:dev online
docker build -f online/docbuilder/Dockerfile -t o3o/docbuilder:dev online

# 3. Tạo .env cho máy DEV: script chép .env.example, thay mọi CHANGE_ME bằng chuỗi ngẫu nhiên (PowerShell: scripts\gen-secrets.ps1 -Dev)
cd online
bash scripts/gen-secrets.sh --dev

# 4. Khởi động
docker compose --env-file .env -f docker/compose.dev.yml up -d
docker compose --env-file .env -f docker/compose.dev.yml ps

# 5. Kiểm
curl -s http://localhost:8080/o3o/healthz
curl -s http://localhost:8080/o3o/status | jq '{edition, dev_image, upstream, connections: .connections.enforcing}'
curl -s http://localhost:8080/v1/status | jq '{version, core, workers}'

Máy chủ soạn thảo cần khoảng 10 đến 20 giây để sẵn sàng; trước đó /o3o/status có thể báo upstream.coolwsd = "down".
Script sinh bí mật là bước bắt buộc: hồ sơ nextcloud không khởi động được khi .env còn CHANGE_ME.
--dev đặt O3O_DEV_MODE=1 và O3O_EMBED_ALLOW_UNSIGNED=1: mở http://localhost:8080/o3o/demo để thử trình soạn thảo nhúng với tệp mẫu. Không có --dev thì .env giữ các giá trị an toàn của tệp mẫu (cả hai bằng 0); máy chạy thật dùng cách này.
Script chạy bằng bash, không chạy bằng sh, vì dùng cú pháp của bash.

Thêm Nextcloud để thử đấu nối#

BashHồ sơ nextcloud

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

# Khởi động kèm Nextcloud, MariaDB, Redis
$DC up -d

# Chờ tới khi trả "installed": true
curl -s http://localhost:8081/status.php

# Cách nhanh: script làm đủ các bước dưới, rồi tạo người dùng thử và tệp mẫu
bash scripts/setup-nextcloud.sh

# Hoặc làm tay (chỉ máy DEV). Luôn kèm --callback-url: thiếu nó, activate-config đặt lại wopi_callback_url về rỗng
$DC exec -u www-data o3o-nextcloud php occ app:install richdocuments
$DC exec -u www-data o3o-nextcloud php occ config:app:set richdocuments wopi_allowlist --value=""
$DC exec -u www-data o3o-nextcloud php occ config:app:set richdocuments disable_certificate_verification --value=yes
$DC exec -u www-data o3o-nextcloud php occ richdocuments:activate-config \
    --wopi-url=http://o3o-online:9980 --callback-url=http://o3o-nextcloud

# Phải là http://localhost:8080 (richdocuments tự suy từ discovery, không đặt tay)
$DC exec -u www-data o3o-nextcloud php occ config:app:get richdocuments public_wopi_url

Tên miền và DNS#

O3O_ONLINE_SERVER_NAME là host[:port] công khai mà người dùng gõ; nó quyết định đường dẫn trình soạn thảo trong /hosting/discovery. O3O_PUBLIC_URL là scheme://host[:port] tương ứng, không có dấu / cuối.
Kho tệp (ví dụ Nextcloud) phải tạo WOPISrc mà CONTAINER o3o-online gọi tới được. localhost bên trong container là chính container đó: dùng tên dịch vụ nội bộ (http://o3o-nextcloud) hoặc host.docker.internal.
O3O_ONLINE_ALIASGROUP2 phải chứa đúng gốc của WOPISrc. Phần tử sau dấu phẩy là biểu thức chính quy: dấu chấm viết \..
Trang nhúng trình soạn thảo nằm ở origin khác: đặt O3O_ONLINE_FRAME_ANCESTORS (một giá trị, không dấu cách).

Chứng chỉ TLS#

o3o-proxy chỉ nghe HTTP. Chứng chỉ đặt ở lớp proxy ngoài (nginx, Traefik hoặc bộ cân bằng tải) đứng trước cổng 8080; máy chủ soạn thảo luôn chạy ssl.enable=false. Khi người dùng vào bằng https, đặt đủ ba biến:

BashBiến cho https

O3O_PUBLIC_URL=https://office.example.com
O3O_ONLINE_SERVER_NAME=office.example.com
O3O_ONLINE_SSL_TERMINATION=true

Mẫu cấu hình proxy ngoài có WebSocket: Reverse proxy. Lời gọi giữa các container (WOPI, callback nội bộ) đi bằng http trong mạng Docker nên không cần chứng chỉ riêng.

Tệp compose và biến môi trườngTừng dịch vụ, từng biến.Reverse proxynginx và Traefik trước O3O, có WebSocket.Bảo mật khi chạy thậtDanh sách kiểm trước khi mở cho người dùng.Giám sátKiểm tra sức khoẻ, nhật ký, số liệu.

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