Nextcloud AIO — Kiến trúc và triển khai

Doc Type

Deployment

Technology

nextcloud

Status

Active

Tags

nextcloud-aioDockerReverse ProxyBackup

Kiến trúc AIO, Docker, reverse proxy, cấu hình ứng dụng và bàn giao vận hành. Đọc theo thứ tự các chương hoặc chọn mục cần tra cứu trong mục lục.

Kiến trúc và phạm vi

Sơ đồ dùng giá trị đại diện

Các tên miền, địa chỉ mạng và giá trị cấu hình trong trang này chỉ là giá trị đại diện. Thay bằng thông số trong hồ sơ hạ tầng đã được phê duyệt trước khi triển khai.

Architecture Diagram

System Flow

Open Diagram

Tổng quan hệ thống

Hệ thống cung cấp nền tảng lưu trữ file tập trung cho user nội bộ trong mạng LAN. Client truy cập tên miền nội bộ qua HTTPS; cụm Nginx HA thực hiện TLS termination, sau đó chuyển tiếp request đến backend Apache của Nextcloud AIO.

Các nguyên tắc chính:

• Không công khai trực tiếp Nextcloud AIO ra Internet.
• Chỉ reverse proxy nhận kết nối HTTPS từ client.
• Giao diện quản trị AIO chỉ dành cho mạng quản trị.
• PostgreSQL, Redis và các container thành phần nằm trong phạm vi Docker của AIO.
• Backup và restore được thực hiện bằng BorgBackup tích hợp trong AIO.

Thành phần

Thành phần	Vai trò
nextcloud-aio-mastercontainer	Điều phối AIO và quản lý các sibling container thông qua Docker socket.
nextcloud-aio-apache	Backend HTTP tại port 11000, nhận request từ reverse proxy.
nextcloud-aio-nextcloud	Ứng dụng PHP chính của Nextcloud.
nextcloud-aio-database	PostgreSQL lưu thông tin user, share, metadata và file index.
nextcloud-aio-redis	Cache, transactional file locking và hỗ trợ notify_push.
nextcloud-aio-notify-push	High Performance Backend for Nextcloud Files, giảm polling từ client.
nextcloud-aio-borgbackup	Thành phần backup/restore sử dụng BorgBackup.
nextcloud-aio-collabora	Nextcloud Office tùy chọn.
nextcloud-aio-clamav	Thành phần chống mã độc tùy chọn cho luồng upload.

Quyết định thiết kế

TLS Termination

TLS termination tại Nginx HA giúp quản lý tập trung certificate, định tuyến và chính sách truy cập. Cần cấu hình chính xác Host, X-Forwarded-*, timeout và trusted proxy.

Internal Backend

Backend Apache của AIO không nhận traffic trực tiếp từ Internet. Mọi request đều đi qua reverse proxy để áp dụng chính sách truy cập và giảm bề mặt tấn công.

Quản lý container

Giao diện web của AIO là control plane chính để khởi động, dừng và bật các thành phần tùy chọn. Ưu tiên quản lý các container thành phần qua giao diện này trong quá trình vận hành hằng ngày.

Backup Isolation

Repository Borg được đặt trên backup storage riêng để giảm rủi ro khi server ứng dụng hỏng. Khả năng restore vẫn phải được kiểm tra định kỳ, không chỉ kiểm tra việc tạo backup.

Giới hạn

• Mô hình này phụ thuộc vào độ sẵn sàng của DNS nội bộ và cụm reverse proxy.
• Mất backup storage sẽ ảnh hưởng trực tiếp đến lịch backup.
• Collabora và ClamAV có thể làm tăng đáng kể mức sử dụng CPU/RAM.
• SKIP_DOMAIN_VALIDATION không thay thế cho kiểm thử HTTPS, DNS và định tuyến.
• Khai báo trusted proxy sai có thể khiến Nextcloud ghi nhận sai IP client hoặc gây lỗi truy cập.
• Kiến trúc này không cung cấp HA cho server ứng dụng AIO khi chỉ có một backend.
• RPO/RTO thực tế phụ thuộc vào lịch Borg, dung lượng repository và thời gian restore.

Tài liệu tham khảo dùng giá trị đại diện

Tài liệu này đã loại bỏ thông tin môi trường cụ thể. Thay các giá trị đại diện bằng giá trị đã được phê duyệt trước khi triển khai; đặc biệt kiểm tra tên miền, địa chỉ backend, storage và thông tin xác thực.

Mục tiêu

Triển khai một hệ thống Nextcloud AIO có các đặc điểm:

• Chạy trên Ubuntu Server.
• Nextcloud được triển khai bằng Docker và Nextcloud AIO.
• User truy cập qua HTTPS và tên miền riêng.
• Nginx làm reverse proxy phía trước Nextcloud.
• Backend Apache của AIO không công khai trực tiếp ra Internet.
• PostgreSQL, Redis và các thành phần AIO được quản lý bằng container.
• Hỗ trợ High Performance Backend for Nextcloud Files / notify_push.
• Backup bằng BorgBackup tích hợp trong AIO.
• Có thể bật thêm Nextcloud Office / Collabora, ClamAV và Server-side Encryption (SSE).
• Có quy trình kiểm tra sau khi triển khai.

Chuẩn bị hạ tầng và runtime

Cấu hình tham khảo

30 user

Chỉ dùng Files, Redis, PostgreSQL và backup:

CPU  : 4 vCPU
RAM  : 8 GB
OS   : 80–100 GB
NIC  : 1 Gbps
Data : tùy nhu cầu

Có thêm Office và SSE:

CPU  : 4–6 vCPU
RAM  : 8–12 GB

Có Office, ClamAV và SSE:

CPU  : 6 vCPU
RAM  : 16 GB

ClamAV và Collabora có thể tiêu thụ RAM đáng kể.

Hạ tầng

Server

Khuyến nghị:

OS       : Ubuntu Server 24.04 LTS hoặc phiên bản LTS được AIO hỗ trợ
CPU      : >= 4 vCPU
RAM      : >= 8 GB
NIC      : 1 Gbps
Timezone : Asia/Ho_Chi_Minh

Kiểm tra:

hostnamectl
ip addr
lsblk
free -h
df -h
timedatectl

Đặt timezone:

timedatectl set-timezone Asia/Ho_Chi_Minh

DNS

Tên miền của Nextcloud phải phân giải về địa chỉ reverse proxy:

<nextcloud-domain>
        |
        +----> <reverse-proxy-vip>

Kiểm tra:

nslookup <nextcloud-domain>
dig <nextcloud-domain>

Firewall và mạng

Luồng tối thiểu:

Máy khách
  |
  | TCP/443
  v
Nginx Reverse Proxy
  |
  | TCP/11000
  v
Nextcloud AIO

Giao diện quản trị AIO dùng TCP/8080 và nên chỉ cho phép truy cập từ mạng quản trị.

Không công khai trực tiếp TCP/11000 ra Internet.

Ubuntu

Cập nhật hệ thống:

apt update
apt upgrade -y

Cài các gói phần mềm cơ bản:

apt install -y \
  ca-certificates \
  curl \
  gnupg \
  unzip \
  nfs-common

Khởi động lại nếu kernel hoặc gói phần mềm hệ thống yêu cầu:

reboot

Docker

Tạo keyring và import GPG key của Docker:

install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

chmod a+r /etc/apt/keyrings/docker.gpg

Thêm Docker repository:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" \
  > /etc/apt/sources.list.d/docker.list

Cài Docker và kiểm tra:

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

docker version
docker compose version
systemctl status docker --no-pager

Triển khai AIO và data directory

Thư mục AIO

Lưu file cấu hình triển khai trong thư mục riêng để thuận tiện kiểm tra và backup:

mkdir -p /root/nextcloud-aio
cd /root/nextcloud-aio

Docker Compose

Tạo file cấu hình tại /root/nextcloud-aio/compose.yaml:

services:
  nextcloud-aio-mastercontainer:
    image: ghcr.io/nextcloud-releases/all-in-one:<AIO_IMAGE_TAG>
    container_name: nextcloud-aio-mastercontainer
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - nextcloud_aio_mastercontainer:/mnt/docker-aio-config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      APACHE_PORT: 11000
      APACHE_IP_BINDING: 0.0.0.0
      SKIP_DOMAIN_VALIDATION: true

volumes:
  nextcloud_aio_mastercontainer:

APACHE_PORT là port backend nội bộ dành cho reverse proxy. Không mở port này trực tiếp ra Internet. Chỉ bật SKIP_DOMAIN_VALIDATION khi cơ chế xác minh tên miền mặc định không phù hợp với mô hình triển khai; cần kiểm tra lại HTTPS và định tuyến theo các bước bên dưới.

Dữ liệu

Nếu cần dùng thư mục dữ liệu riêng trên host, chuẩn bị đường dẫn trước khi khởi động AIO:

mkdir -p /srv/nextcloud-data
chown root:root /srv/nextcloud-data
chmod 750 /srv/nextcloud-data

Các lệnh trên chỉ tạo thư mục, chưa cấu hình AIO sử dụng thư mục đó. Ví dụ Compose ở trên vẫn dùng vị trí dữ liệu mặc định. Để dùng đường dẫn riêng, cần khai báo biến NEXTCLOUD_DATADIR cho mastercontainer trước lần cài đặt Nextcloud đầu tiên, theo hướng dẫn datadir chính thức. Không đổi biến này tùy ý sau khi đã cài đặt Nextcloud.

Không tự ý đổi quyền hoặc xóa volume khi chưa xác định rõ thư mục dữ liệu và phương án restore.

Khởi động

cd /root/nextcloud-aio
docker compose up -d
docker ps

Mở giao diện quản trị AIO từ mạng quản trị:

https://<nextcloud-backend-ip>:8080

Trong giao diện AIO:

1. Lưu mật khẩu quản trị AIO trong password manager.
2. Nhập tên miền đã được DNS trỏ về reverse proxy.
3. Chọn các thành phần cần thiết theo cấu hình thực tế.
4. Xác nhận thư mục dữ liệu trước khi hoàn tất cài đặt.
5. Chờ các container chuyển sang trạng thái healthy/running.

Không đưa mật khẩu quản trị AIO hoặc Borg passphrase vào Git, file Compose, ảnh chụp màn hình hay log CI/CD.

Reverse proxy và kết nối

Nginx Reverse Proxy

Ví dụ server block rút gọn cho luồng HTTPS đến backend Apache:

server {
    listen 443 ssl http2;
    server_name <nextcloud-domain>;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    client_max_body_size 10G;

    location / {
        proxy_pass http://<nextcloud-backend-ip>:11000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Host $host;

        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
        proxy_buffering off;
    }

    location /.well-known/carddav {
        return 301 /remote.php/dav;
    }

    location /.well-known/caldav {
        return 301 /remote.php/dav;
    }
}

Kiểm tra cấu hình trước khi reload:

nginx -t
systemctl reload nginx

Ví dụ này chưa có phần chuyển tiếp WebSocket Upgrade. Khi dùng chức năng cần WebSocket, phải bổ sung xử lý các header Upgrade và Connection theo cấu hình Nginx chính thức của Nextcloud AIO. Kiểm tra riêng kết nối WebSocket, notify_push và timeout trước khi đưa vào sử dụng.

Trusted Proxies

Trong Nextcloud, khai báo địa chỉ hoặc subnet của reverse proxy trong danh sách trusted_proxies. Lấy giá trị thực tế từ hồ sơ hạ tầng, ví dụ:

docker exec --user www-data nextcloud-aio-nextcloud php occ config:system:set trusted_proxies 0 --value=<reverse-proxy-vip>
docker exec --user www-data nextcloud-aio-nextcloud php occ config:system:set trusted_proxies 1 --value=<reverse-proxy-node-01>
docker exec --user www-data nextcloud-aio-nextcloud php occ config:system:set trusted_proxies 2 --value=<reverse-proxy-node-02>

Không khai báo toàn bộ Internet hoặc một subnet quá rộng làm trusted proxy. Điều đó có thể làm sai lệch địa chỉ IP client và tạo rủi ro bảo mật.

Kiểm tra

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

docker exec --user www-data nextcloud-aio-nextcloud php occ status
docker exec --user www-data nextcloud-aio-nextcloud php occ config:list system

Kiểm tra từ client:

curl -I https://<nextcloud-domain>/

Kết quả mong đợi: kết nối HTTPS hợp lệ, không có redirect loop và giao diện đăng nhập tải được qua tên miền đã cấu hình.

Ứng dụng và tác vụ nền

notify_push

Chỉ bật thành phần này sau khi Files và các luồng HTTPS cơ bản đã ổn định:

1. Bật container notify_push (High Performance Backend for Nextcloud Files) trong AIO.
2. Kiểm tra container tương ứng ở trạng thái running/healthy.
3. Kiểm tra cấu hình notify_push bằng lệnh occ.
4. Đăng nhập bằng user thử nghiệm và kiểm tra khả năng nhận cập nhật theo thời gian thực.

Ví dụ kiểm tra:

docker exec --user www-data nextcloud-aio-nextcloud php occ app:list | grep notify_push
docker exec --user www-data nextcloud-aio-nextcloud php occ notify_push:self-test

Nếu self-test thất bại, kiểm tra DNS, certificate, header proxy, WebSocket và firewall trước khi thay đổi ứng dụng.

Cron

Nextcloud nên chạy các tác vụ nền bằng cron thay vì chỉ dựa vào AJAX:

docker exec --user www-data nextcloud-aio-nextcloud php occ background:cron

Sau khi cấu hình cron theo cơ chế vận hành của server, kiểm tra trạng thái tác vụ nền trong giao diện quản trị hoặc bằng lệnh occ.

Upload / Download

Thực hiện bằng một user thử nghiệm:

1. Upload file nhỏ.
2. Download file đó và đối chiếu checksum.
3. Upload file lớn hơn giới hạn mặc định để kiểm tra client_max_body_size.
4. Đổi tên, di chuyển và xóa file thử nghiệm.
5. Kiểm tra log của Nginx và Nextcloud nếu có lỗi.

Không dùng dữ liệu thật trong bài kiểm tra ban đầu.

Server-side Encryption

SSE chỉ nên bật sau khi đã thống nhất mô hình quản lý khóa, backup và restore.

docker exec --user www-data nextcloud-aio-nextcloud php occ app:enable encryption
docker exec --user www-data nextcloud-aio-nextcloud php occ encryption:status

Lưu ý vận hành:

• Phải có quy trình bảo vệ khóa mã hóa.
• Phải kiểm tra restore trên môi trường an toàn.
• Backup phải có đủ khóa mã hóa cần thiết để restore dữ liệu.
• Một số luồng ZIP/UNZIP có thể làm thay đổi cách dữ liệu được xử lý; cần kiểm thử riêng trước khi dùng trong môi trường thật.

Optional Components

ClamAV

Chỉ bật ClamAV khi đã dự trù đủ RAM/CPU và có yêu cầu quét mã độc. Sau khi bật, upload file thử nghiệm và theo dõi thời gian xử lý.

Nextcloud Office / Collabora

Chỉ bật Office khi cần chỉnh sửa tài liệu trên web. Kiểm tra thêm:

• Tên miền hoặc endpoint của Office.
• TLS và WebSocket qua reverse proxy.
• Giới hạn tài nguyên của container.
• Mở và chỉnh sửa file thử nghiệm.
• Tình huống container Office dừng hoặc khởi động lại.

Backup và bàn giao vận hành

Backup Storage

Ví dụ mount NFS vào server Nextcloud:

mkdir -p /mnt/nextcloud-backup
mount -t nfs <backup-server-ip>:/export/nextcloud /mnt/nextcloud-backup
df -h /mnt/nextcloud-backup

Sau khi kiểm tra quyền truy cập, yêu cầu kết nối mạng và hành vi khi server backup tạm thời không khả dụng, khai báo mount trong /etc/fstab để tự động mount khi khởi động.

BorgBackup

Khởi tạo repository Borg ở vị trí backup đã được phê duyệt. Lưu Borg passphrase trong password manager hoặc secret store riêng, không lưu trong repository Git.

Khai báo biến môi trường cho repository đang vận hành:

export BORG_REPO=/mnt/nextcloud-backup/borg-repository
export BORG_PASSPHRASE='<borg-passphrase>'

Quy trình backup tối thiểu:

1. Xác nhận mount backup đang hoạt động.
2. Xác nhận còn đủ dung lượng.
3. Ghi lại metadata cần thiết của Nextcloud.
4. Chạy backup theo lịch đã phê duyệt.
5. Kiểm tra backup mới nhất.
6. Kiểm tra cảnh báo backup và khả năng truy cập dữ liệu trong bản backup. Thực hiện restore theo runbook riêng.

Kiểm tra repository:

borg list "$BORG_REPO"
borg info "$BORG_REPO"
borg check "$BORG_REPO"

Retention policy cần đáp ứng yêu cầu RPO/RTO trong giới hạn dung lượng hiện có. Ví dụ:

Giữ 7 bản gần nhất
Giữ 4 bản theo tuần
Giữ 6 bản theo tháng

Các con số trên chỉ là mẫu; cần điều chỉnh theo yêu cầu thực tế và kiểm tra khả năng restore định kỳ.

Lệnh kiểm tra nhanh

docker ps
docker compose -f /root/nextcloud-aio/compose.yaml ps
docker logs --tail 100 nextcloud-aio-mastercontainer
docker exec --user www-data nextcloud-aio-nextcloud php occ status
df -h
free -h

Off-host Secrets

Lưu các thông tin sau trong password manager hoặc secret store phù hợp:

• Mật khẩu quản trị AIO.
• Borg passphrase.
• Thông tin DNS và gia hạn certificate.
• Hồ sơ backend, reverse proxy và server backup.
• Thông tin mount NFS.
• Quy trình restore và người chịu trách nhiệm.

Tài liệu liên quan

• Nextcloud AIO — Vận hành và backup

  Endpoint, occ, health checks, BorgBackup, retention và quản lý secrets.

• Nextcloud AIO — Restore

  Quy trình và tài liệu liên quan trong cùng công nghệ.