Bỏ qua, tới nội dung
Tài liệu APIv1

Tích hợp lưu trữ

Đấu Nextcloud từng bước

Cài richdocuments, chạy activate-config với wopi_url và wopi_callback_url, đặt aliasgroup, chứng chỉ, kiểm chứng bảy bước và bảng lỗi thường gặp.

Trong trang này

Nextcloud nói chuyện với máy chủ soạn thảo O3O qua ứng dụng richdocuments (tên hiển thị “Nextcloud Office”). Trang này đi từ con số không tới lúc mở được tệp .docx trong Nextcloud, dùng hồ sơ nextcloud có sẵn trong online/docker/compose.dev.yml. Các lệnh đã chạy thật trên Nextcloud 30.0.17 với richdocuments 8.5.17.

Bức tranh chung#

Thành phầnTên trong mạng o3o-netMở ra máy của bạn
o3o-proxyo3o-proxy:8080http://localhost:8080
Máy chủ soạn thảoo3o-online:9980không mở, đi qua proxy
o3o-gateo3o-gate:8070chỉ /o3o/ qua proxy
Nextcloud 30o3o-nextcloud:80http://localhost:8081
MariaDB 11, Redis 7o3o-nextcloud-db, o3o-nextcloud-rediskhông mở

Điểm dễ vấp nhất: bạn mở Nextcloud bằng http://localhost:8081, nhưng localhost bên trong container o3o-online lại là chính container đó. Vì thế ta khai cho richdocuments một địa chỉ gọi ngược nội bộ (wopi_callback_url = http://o3o-nextcloud) để WOPISrc dùng tên mà máy chủ soạn thảo gọi tới được.

Các bước#

  1. Chuẩn bị

    Dựng xong bản Docker DEV theo hướng dẫn compose, đã chạy script sinh bí mật (tệp online/.env không còn chuỗi CHANGE_ME; MariaDB từ chối mật khẩu rỗng). Cổng 8080 và 8081 còn trống.

  2. Bật hồ sơ nextcloud

    Lệnh ở khối mã đầu tiên bên dưới. Lần đầu Nextcloud tự cài đặt, mất vài phút.

  3. Cài richdocuments

    Cần máy có Internet để tải ứng dụng từ kho ứng dụng Nextcloud.

  4. Chạy activate-config với cả -w và -c

    Lệnh này ghi wopi_url, wopi_callback_url, gọi thử discovery và capabilities, rồi tự suy public_wopi_url.

  5. Đối chiếu biến môi trường phía O3O

    aliasgroup2 phải chứa http://o3o-nextcloud, tên miền tin cậy của Nextcloud phải có o3o-nextcloud.

  6. Mở thử

    Đăng nhập http://localhost:8081 bằng O3O_NC_ADMIN_USER / O3O_NC_ADMIN_PASSWORD, tải lên một tệp .docx và bấm vào nó.
BashBước 2 — bật hồ sơ nextcloud
cd online
# Bật cả hồ sơ nextcloud (Nextcloud 30 + MariaDB 11 + Redis 7)
docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud up -d

# Đợi Nextcloud cài đặt xong: "installed":true
curl -s http://localhost:8081/status.php
BashGõ tắt occ
cd online
# Gõ tắt cho lệnh occ chạy trong container o3o-nextcloud
alias occ='docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud exec --user www-data o3o-nextcloud php occ'
occ status
BashBước 3 — cài richdocuments
occ app:install richdocuments
# Nextcloud 30 cài được richdocuments 8.5.x. Nếu ứng dụng đã có sẵn thì chỉ cần bật:
occ app:enable richdocuments
BashBước 4 — activate-config
# -w: địa chỉ Nextcloud dùng để gọi máy chủ soạn thảo (tên nội bộ trong mạng o3o-net)
# -c: địa chỉ máy chủ soạn thảo dùng để gọi ngược về Nextcloud (thành gốc của WOPISrc)
occ richdocuments:activate-config -w http://o3o-online:9980 -c http://o3o-nextcloud
BashKết quả mong đợi (rút gọn)
✓ Set WOPI url to http://o3o-online:9980
✓ Set callback url to http://o3o-nextcloud
Checking configuration
🛈 Configured WOPI URL: http://o3o-online:9980
🛈 Configured public WOPI URL: http://localhost:8080
🛈 Configured callback URL: http://o3o-nextcloud

✓ Fetched /hosting/discovery endpoint
✓ Valid mimetype response
✓ Valid capabilities entry
✓ Fetched /hosting/capabilities endpoint
✓ Detected WOPI server: <tên và phiên bản máy chủ soạn thảo>
BashBước 4 — đọc lại cấu hình
occ config:app:get richdocuments wopi_url            # http://o3o-online:9980
occ config:app:get richdocuments public_wopi_url     # http://localhost:8080  (tự suy, không đặt tay)
occ config:app:get richdocuments wopi_callback_url   # http://o3o-nextcloud
occ config:app:get richdocuments wopi_allowlist      # rỗng trên máy DEV
BashBước 5 — biến phía O3O cho bản DEV
# online/.env
O3O_ONLINE_SERVER_NAME=localhost:8080
O3O_ONLINE_ALIASGROUP2=http://o3o-nextcloud,http://localhost:8081
O3O_NC_TRUSTED_DOMAINS="localhost localhost:8081 o3o-nextcloud"
# Cho gate hỏi CheckFileInfo khi đã chạm trần, để phiên chỉ đọc không bị từ chối
O3O_WOPI_ALLOWED_HOSTS=http://o3o-nextcloud
BashÁp biến mới
cd online
docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud up -d o3o-online o3o-gate
curl -s http://localhost:8080/o3o/status

Bốn khoá cấu hình của richdocuments#

Khoá của ứng dụng richdocuments

  • wopi_urlURLbắt buộc
    Địa chỉ Nextcloud (phía máy chủ PHP) dùng để gọi /hosting/discovery và /hosting/capabilities. Được dùng tên nội bộ. DEV: http://o3o-online:9980.
  • public_wopi_urlURLtuỳ chọnMặc định: tự suy
    Địa chỉ trình duyệt dùng, richdocuments tự lấy phần gốc của urlsrc mỗi lần chạy activate-config và dùng để dựng Content-Security-Policy. KHÔNG đặt tay. Sai thì sửa O3O_ONLINE_SERVER_NAME rồi chạy lại activate-config. DEV: http://localhost:8080.
  • wopi_callback_urlURLtuỳ chọnMặc định: rỗng = theo địa chỉ trình duyệt
    Gốc của WOPISrc, tức địa chỉ máy chủ soạn thảo gọi ngược về Nextcloud. Đặt bằng activate-config -c. DEV: http://o3o-nextcloud.
  • wopi_allowlistdanh sách IP/CIDRtuỳ chọnMặc định: rỗng = mọi nơi
    Chỉ nhận lời gọi WOPI từ các địa chỉ này. Phân tách bằng dấu cách, dấu phẩy, dấu chấm phẩy hoặc |. DEV: để trống. Chạy thật: IP của máy chủ soạn thảo.
  • disable_certificate_verification<code>yes</code> / rỗngtuỳ chọnMặc định: rỗng
    yes tắt kiểm chứng chỉ khi Nextcloud gọi wopi_url qua HTTPS. Chỉ dùng với chứng chỉ tự ký nội bộ.

Biến phía O3O liên quan#

Biến trong online/.env

  • O3O_ONLINE_SERVER_NAMEhost[:port]bắt buộcMặc định: <code>localhost:8080</code>
    Tên công khai của máy chủ soạn thảo. Quyết định urlsrc trong discovery và vì thế quyết định public_wopi_url.
  • O3O_ONLINE_SSL_TERMINATIONtrue / falsetuỳ chọnMặc định: <code>false</code>
    true khi người dùng vào bằng https qua proxy có TLS; urlsrc sẽ bắt đầu bằng https://.
  • O3O_ONLINE_ALIASGROUP2danh sáchbắt buộcMặc định: <code>http://o3o-nextcloud,http://localhost:8081</code>
    WOPI host được phép. Phần tử đầu là host chính, các phần tử sau là bí danh và là biểu thức chính quy (dấu chấm viết \.). aliasgroup1 luôn dành cho gate, không đổi.
  • O3O_NC_TRUSTED_DOMAINSchuỗi cách nhau bằng dấu cáchbắt buộcMặc định: <code>localhost localhost:8081 o3o-nextcloud</code>
    Tên miền tin cậy của Nextcloud. Phải có o3o-nextcloud vì máy chủ soạn thảo gọi WOPI bằng tên này.
  • O3O_WOPI_ALLOWED_HOSTSdanh sách gốc URLtuỳ chọnMặc định: rỗng
    Khi đã chạm trần kết nối, gate gọi CheckFileInfo tới các gốc này để nhận ra phiên chỉ đọc và cho qua. Rỗng thì gate không gọi ra ngoài. DEV: http://o3o-nextcloud.

Chứng chỉ và chạy thật#

Trên máy chủ thật, TLS được cắt ở proxy đứng trước o3o-proxy (xem proxy ngược). Máy chủ soạn thảo vẫn chạy HTTP bên trong nhưng phải biết người dùng vào bằng https, nên đặt O3O_ONLINE_SSL_TERMINATION=true. Nextcloud và O3O phải cùng dùng https, nếu không trình duyệt chặn nội dung hỗn hợp.

BashBiến phía O3O khi chạy thật
# online/.env trên máy chủ thật (TLS cắt ở proxy phía trước)
O3O_PUBLIC_URL=https://office.example.com
O3O_ONLINE_SERVER_NAME=office.example.com
O3O_ONLINE_SSL_TERMINATION=true
O3O_ONLINE_ALIASGROUP2=https://cloud.example.com
O3O_WOPI_ALLOWED_HOSTS=https://cloud.example.com
BashLệnh phía Nextcloud khi chạy thật
# Chạy trên máy Nextcloud thật
occ richdocuments:activate-config -w https://office.example.com -c https://cloud.example.com
occ config:app:get richdocuments public_wopi_url        # https://office.example.com

# Chỉ nhận lời gọi WOPI từ máy chủ soạn thảo (IP hoặc CIDR, ngăn cách bằng dấu cách, phẩy, chấm phẩy hoặc |)
occ config:app:set richdocuments wopi_allowlist --value="203.0.113.10/32"

# CHỈ khi Nextcloud gọi máy chủ soạn thảo qua https với chứng chỉ tự ký nội bộ
occ config:app:set richdocuments disable_certificate_verification --value=yes

Kiểm chứng bảy bước#

Dừng ở bước đầu tiên hỏng và sửa ngay bước đó.

BashKiểm chứng
cd online
# 1. urlsrc phải mang đúng địa chỉ công khai (http://localhost:8080/browser/<hash>/cool.html?)
curl -s http://localhost:8080/hosting/discovery | grep -m1 -o 'urlsrc="[^"]*"'
# 2. capabilities trả JSON
curl -s http://localhost:8080/hosting/capabilities
# 3. gate thấy máy chủ soạn thảo: "coolwsd": "ok"
curl -s http://localhost:8080/o3o/status
# 4. Nextcloud gọi được máy chủ soạn thảo: đủ các dòng ✓, mã thoát 0
occ richdocuments:activate-config -w http://o3o-online:9980 -c http://o3o-nextcloud; echo "exit=$?"
# 5. địa chỉ công khai Nextcloud đã tự suy
occ config:app:get richdocuments public_wopi_url
# 6. mở một tệp .docx trên http://localhost:8081, gõ vài chữ rồi xem số phiên sửa
curl -s http://localhost:8080/o3o/status | grep -o '"current": *[0-9]*'
# 7. nhật ký hai phía
docker compose --env-file .env -f docker/compose.dev.yml logs --tail 100 o3o-online
occ log:tail 50

Lỗi thường gặp#

Dấu hiệuNguyên nhânCách sửa
Nhật ký o3o-online có Unauthorized WOPI hostGốc của WOPISrc không nằm trong aliasgroup2Thêm đúng gốc (cả tên nội bộ lẫn tên công khai nếu dùng cả hai) vào O3O_ONLINE_ALIASGROUP2, khởi động lại o3o-online.
Khung soạn thảo trắng, trình duyệt báo từ chối nhúng khungpublic_wopi_url sai nên Content-Security-Policy của Nextcloud không cho phép địa chỉ trình soạn thảoSửa O3O_ONLINE_SERVER_NAME, khởi động lại o3o-online, chạy lại activate-config với -w và -c.
Tài liệu báo lỗi nạp; nhật ký o3o-online có lỗi nối tới localhost:8081wopi_callback_url rỗng (quên -c hoặc chạy lại activate-config không có -c)Chạy occ richdocuments:activate-config -w http://o3o-online:9980 -c http://o3o-nextcloud.
Nhật ký Nextcloud có WOPI request denied from <ip>wopi_allowlist thiếu IP của máy chủ soạn thảo, hoặc Nextcloud đang thấy IP của proxyThêm IP/CIDR đúng; khai trusted_proxies nếu có proxy.
Nextcloud trả trang “untrusted domain” cho lời gọi WOPIo3o-nextcloud chưa có trong tên miền tin cậyThêm vào O3O_NC_TRUSTED_DOMAINS (hoặc occ config:system:set trusted_domains 10 --value=o3o-nextcloud).
activate-config in Failed to fetch discovery endpointwopi_url sai, o3o-online chưa chạy, hoặc chứng chỉ tự kýKiểm curl http://localhost:8080/hosting/discovery; với chứng chỉ tự ký đặt disable_certificate_verification=yes.
Trình duyệt chặn nội dung hỗn hợpNextcloud chạy https còn trình soạn thảo chạy http, hoặc ngược lạiDùng cùng một lược đồ cho cả hai; khi có TLS đặt O3O_ONLINE_SSL_TERMINATION=true.
Hiện trang “Đã đạt giới hạn kết nối”Số phiên soạn thảo đồng thời đã chạm trần của góiMở ở chế độ chỉ đọc hoặc thử lại sau; xem cách đếm kết nối và các gói.
Nhật ký o3o-online có Could not open proof RSA keyv1 chưa cấp khoá proof cho máy chủ soạn thảoKhông ảnh hưởng Nextcloud 30: richdocuments 8.5.17 không kiểm chữ ký proof. Xem bảo mật WOPI.

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