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

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

Nâng cấp và quay lui Beta

Nâng cấp theo versions.json, ghim image, sao lưu trước khi nâng, thứ tự áp dụng và cách quay lui bằng một lệnh.

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

Nguyên tắc#

  • Tệp kê khai versions.json ở gốc repo là nguồn sự thật về phiên bản của từng thành phần và các ràng buộc tương thích. Dịch vụ không đọc tệp này lúc chạy; nó dành cho người vận hành, cho bộ dựng trang và cho trang Ma trận tương thích.
  • Luôn ghim image. Máy chủ soạn thảo ghim theo digest qua O3O_ONLINE_IMAGE; không dùng thẻ di động như latest ở máy chạy thật vì docker compose pull có thể đổi lõi xử lý tài liệu mà không báo.
  • Gate và DocBuilder v1 được dựng tại chỗ từ mã nguồn trong repo. Tệp compose lấy thẻ image của hai dịch vụ này từ O3O_GATE_IMAGE (mặc định o3o/gate:dev) và O3O_DOCBUILDER_IMAGE (mặc định o3o/docbuilder:dev). Mỗi lần nâng cấp, giữ lại image cũ dưới một thẻ khác để quay lui được bằng một lệnh.
  • Sau khi lấy mã của bản mới, chạy python tools/release.py env --write online/.env (ở gốc repo) để ghi khối phiên bản của .env theo versions.json: O3O_ONLINE_IMAGE, O3O_ONLINE_IMAGE_KIND, O3O_GATE_IMAGE, O3O_DOCBUILDER_IMAGE. Lệnh chỉ thay khối đó, giữ nguyên bí mật và các biến khác, và lưu bản trước ở .env.bak. Chi tiết ở Tệp compose và biến môi trường.
  • Đọc Nhật ký thay đổi trước: thay đổi phá vỡ của API chỉ xuất hiện ở phiên bản API mới, không lẻn vào v1.

Trước khi nâng cấp#

  1. Sao lưu volume o3o-gate-data: nó chứa instance-id (token có thể gắn vào mã này), secret.key (ký URL tải tệp), bản làm việc của tài liệu nhúng và nhật ký đối soát. o3o-docbuilder-data chỉ chứa kết quả tạm.
  2. Lưu bản sao .env và ghi lại image đang chạy.
  3. Hàng đợi DocBuilder nằm trong bộ nhớ: khởi động lại thì job đang chờ và đang chạy bị mất (job đã xong vẫn tải được tới hết hạn). Chờ queue.queued và queue.running của GET /v1/status về 0.
  4. Chọn giờ thấp điểm cho máy chủ soạn thảo: xem connections.current trong GET /o3o/status.
BashSao lưu volume dữ liệu của gate
# Tên volume có tiền tố là tên dự án compose
docker volume ls | grep -E 'o3o-(gate|docbuilder)-data'

# Nén ra thư mục hiện tại
docker run --rm -v <tên dự án>_o3o-gate-data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/o3o-gate-data-$(date +%Y%m%d).tgz -C /data .

Các bước nâng cấp#

BashNâng cấp một lượt
cd online
DC="docker compose --env-file .env -f docker/compose.dev.yml"

# 1. Ghi lại hiện trạng và giữ image cũ
$DC images
cp .env ".env.bak-$(date +%Y%m%d)"
GATE_IMAGE=$(grep -E '^O3O_GATE_IMAGE=' .env | cut -d= -f2-)
DOCBUILDER_IMAGE=$(grep -E '^O3O_DOCBUILDER_IMAGE=' .env | cut -d= -f2-)
docker image tag "${GATE_IMAGE:-o3o/gate:dev}" o3o/gate:rollback
docker image tag "${DOCBUILDER_IMAGE:-o3o/docbuilder:dev}" o3o/docbuilder:rollback

# 2. Hàng đợi DocBuilder phải trống; nên có ít phiên đang soạn
curl -s http://localhost:8080/v1/status | jq .queue
curl -s http://localhost:8080/o3o/status | jq '{current: .connections.current, open: .embed.open_documents}'

# 3. Lấy mã của bản mới; so danh sách biến để thêm biến mới vào .env; ghi khối phiên bản (O3O_ONLINE_IMAGE, O3O_GATE_IMAGE, O3O_DOCBUILDER_IMAGE) theo versions.json
git fetch --tags
git checkout <thẻ phát hành>
diff <(grep -oE '^[A-Z0-9_]+=' .env.example | sort) <(grep -oE '^[A-Z0-9_]+=' .env | sort)
python ../tools/release.py env --write .env

# 4. Dựng lại image với đúng thẻ trong .env (ngữ cảnh là thư mục online/)
GATE_IMAGE=$(grep -E '^O3O_GATE_IMAGE=' .env | cut -d= -f2-)
DOCBUILDER_IMAGE=$(grep -E '^O3O_DOCBUILDER_IMAGE=' .env | cut -d= -f2-)
docker build -f gate/Dockerfile -t "${GATE_IMAGE:-o3o/gate:dev}" .
docker build -f docbuilder/Dockerfile -t "${DOCBUILDER_IMAGE:-o3o/docbuilder:dev}" .

# 5. Áp dụng theo thứ tự: DocBuilder, gate, rồi phần còn lại
$DC up -d --force-recreate o3o-docbuilder
$DC up -d --force-recreate o3o-gate
$DC up -d

# 6. Kiểm phiên bản sau nâng cấp
curl -s http://localhost:8080/o3o/status | jq '{version, api, edition}'
curl -s http://localhost:8080/v1/status | jq '{version, api, core}'

Quay lui#

BashTrở về bản trước
cd online
DC="docker compose --env-file .env -f docker/compose.dev.yml"

git checkout <thẻ phát hành cũ>
cp .env.bak-YYYYMMDD .env                        # bản sao .env đã lưu ở bước 1
GATE_IMAGE=$(grep -E '^O3O_GATE_IMAGE=' .env | cut -d= -f2-)
DOCBUILDER_IMAGE=$(grep -E '^O3O_DOCBUILDER_IMAGE=' .env | cut -d= -f2-)
docker image tag o3o/gate:rollback "${GATE_IMAGE:-o3o/gate:dev}"
docker image tag o3o/docbuilder:rollback "${DOCBUILDER_IMAGE:-o3o/docbuilder:dev}"
$DC up -d --force-recreate o3o-docbuilder o3o-gate
$DC up -d                                        # tạo lại o3o-online nếu digest đã đổi

Không chạy docker image prune trong thời gian còn có thể cần quay lui. Nếu nhật ký thay đổi báo định dạng dữ liệu của gate đổi, phục hồi cả bản sao lưu volume.

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