Configurazione del reverse proxy

Questa sezione descrive come integrare Sync-in con un reverse proxy esistente.

informazioni

Con l'installazione Docker consigliata, il server è già configurato con il reverse proxy Nginx.
Questa documentazione non si applica quindi a tale caso d'uso.

Configurazione del server Sync-in

Nel file di configurazione environment.yaml è possibile definire facoltativamente publicUrl con l'URL esatto esposto dal reverse proxy, includendo lo schema e l'eventuale porta non standard. Quando è configurato, Sync-in lo utilizza per generare i link delle notifiche e gli URL degli editor.

server:
  # Facoltativo per ora; obbligatorio nella prossima versione principale
  publicUrl: 'https://sync-in.domain.com'
  trustProxy: true # valore predefinito se non specificato

Quando publicUrl è configurato, l'URL deve essere raggiungibile dai browser degli utenti e, per gli editor per ufficio che comunicano con Sync-in, dai relativi servizi o container. In questo caso non utilizzare localhost o 127.0.0.1.

publicUrl resta facoltativo fino alla prossima versione principale. Quando viene omesso, le e-mail di notifica non contengono link di azione e gli URL degli editor utilizzano l'origine della richiesta inoltrata dal proxy come soluzione di compatibilità. Per motivi di sicurezza, publicUrl diventerà obbligatorio nella prossima versione principale: gli endpoint degli editor verranno così creati da un'origine attendibile controllata dall'amministratore anziché dalle intestazioni della richiesta.

L'opzione trustProxy indica al server in quale misura considerare attendibili i proxy, ad esempio Nginx o Traefik, per determinare l'indirizzo IP reale del client. Il valore predefinito true viene mantenuto per garantire la compatibilità con le installazioni esistenti.

Valori possibili

Valore	Comportamento
`false`	Ignora le intestazioni del proxy e utilizza solo l'IP della connessione diretta
`true`	Considera attendibili le intestazioni inoltrate da qualsiasi indirizzo connesso
`IP, CIDR`	Considera attendibili soltanto i proxy specificati
Numero (deprecato)	`>= 1` diventa `true`; `< 1` diventa `false`

avvertenza

Dalla versione 2.6.0, i valori numerici non selezionano più l'n-esimo hop e verranno rimossi nella prossima versione principale. Un valore esistente trustProxy: 1 viene interpretato come true. Il valore predefinito true è temporaneo e dovrebbe diventare false in una futura versione principale. Fino ad allora, gli IP dei client possono essere falsificati se il backend è raggiungibile direttamente o se un proxy conserva le intestazioni di inoltro fornite dal client, come avviene con $proxy_add_x_forwarded_for. Limitare l'accesso diretto a Sync-in e, quando possibile, preferire l'IP o l'intervallo CIDR di un proxy attendibile.

Configurazione di Nginx

È possibile utilizzare diversi reverse proxy. Questa documentazione descrive la configurazione con Nginx, la soluzione più comune e meglio supportata.

Questo file di configurazione costituisce il riferimento consigliato per garantire il funzionamento ottimale delle funzionalità del server Sync-in.

⚠️ Le direttive server_name, ssl_certificate e ssl_certificate_key, così come l'indirizzo del server sync_in:8080, devono essere adattati al proprio ambiente.

L'uso della variabile $http_host è intenzionale: a differenza di $host, mantiene una porta non standard presente nella richiesta del client quando inoltra le intestazioni host.

# HOST VIRTUALE NGINX DI SYNC-IN

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream sync_in_server {
    server sync_in:8080;
    keepalive 32;
}

server {
    listen 80;
    # listen 443 ssl;
    # http2 on;
    # server_name  domain.com www.domain.com;
    # ssl_certificate      /etc/ssl/certs/fullchain.pem;
    # ssl_certificate_key  /etc/ssl/certs/privkey.pem;
    # ssl_protocols TLSv1.2 TLSv1.3;
    # ssl_session_cache shared:SSL:10m;
    # ssl_session_timeout 1h;
    # ssl_prefer_server_ciphers on;
    # ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
    # ssl_ecdh_curve X25519:prime256v1;

    # Impostazioni generali
    charset UTF-8;
    server_tokens off;
    access_log off;
    include mime.types;

    # Invio ottimizzato dei file
    sendfile on;
    tcp_nodelay on;
    tcp_nopush on;

    # Buffering delle richieste inoltrate a Node
    proxy_http_version 1.1;
    chunked_transfer_encoding on;
    proxy_set_header Host $http_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-Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_cache_bypass $http_upgrade;
    proxy_redirect off;

    # Impostazioni del buffering del proxy
    proxy_buffering off; # nginx -> node
    proxy_buffers 8 512k;
    proxy_buffer_size 512k; # node highWaterMark

    # Timeout estesi per trasferimenti lunghi o WebSocket
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    keepalive_timeout  180  90s;

    # Impostazioni dei client
    proxy_request_buffering off; # client -> nginx
    large_client_header_buffers 4 16k;
    client_max_body_size 0;
    client_body_buffer_size 25M;

    location / {
        proxy_pass http://sync_in_server;
    }

    location ~* .(ico|jpg|png|gif|jpeg|swf|woff|svg)$ {
        # Nginx utilizza sempre la regola più precisa nelle proprie politiche di routing interne
        proxy_pass http://sync_in_server;
        gzip_static on;
        gzip_comp_level 5;
        expires 1d;
        add_header Cache-Control public;
    }

    # NOTA: necessario solo quando il container Docker di Collabora Online viene eseguito localmente
    #       e non si utilizza un URL esterno.
    # Rimuovere il commento dalla riga seguente per attivarlo:
    # include collabora.conf;

    # NOTA: necessario solo quando il container Docker di OnlyOffice viene eseguito localmente
    #       e non si utilizza un URL esterno.
    # Rimuovere il commento dalla riga seguente per attivarlo:
    # include onlyoffice.conf;

    # NOTA: necessario solo quando il container Docker di Euro-Office viene eseguito localmente
    #       e non si utilizza un URL esterno.
    # Rimuovere il commento dalla riga seguente per attivarlo:
    # include eurooffice.conf;

    # NOTA: necessario solo quando il container Docker di draw.io viene eseguito localmente
    #       e non si utilizza un URL esterno.
    # Rimuovere il commento dalla riga seguente per attivarlo:
    # include drawio.conf;
}

Configurazione di Collabora Online

In entrambe le modalità, la funzionalità Collabora Online deve essere attivata nel file di configurazione environment.yaml:

applications:
  files:
    editors:
      collabora:
        enabled: true

⚠️ Se Collabora Online è stato distribuito tramite Docker e Nginx viene eseguito con HTTPS, assicurarsi di attivare la terminazione SSL.

Modalità con proxy

Nella configurazione di Nginx, rimuovere il commento dalla direttiva include collabora.conf; per caricare la configurazione di Collabora Online.
In questa modalità non è necessario esporre direttamente a Internet il server Collabora Online, che deve tuttavia restare accessibile dal server Sync-in.

Creare quindi il file /etc/nginx/collabora.conf e inserirvi il contenuto seguente.

⚠️ Il valore di proxy_pass deve essere adattato all'indirizzo del server Collabora Online.

# File statici
location ^~ /browser/ {
  proxy_pass http://collabora:9980;
  proxy_set_header Host $http_host;
}

# URL di rilevamento WOPI e funzionalità
location ^~ /hosting/ {
  proxy_pass http://collabora:9980;
  proxy_set_header Host $http_host;
}

# WebSocket principale e gestione dei documenti
location ^~ /cool/ {
  proxy_pass http://collabora:9980;
  proxy_set_header Host $http_host;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $connection_upgrade;
}

Modalità esterna

Il server Collabora Online deve essere accessibile sia dal server Sync-in sia dal browser, tramite un nome di dominio o un indirizzo IP.
Configurare la direttiva externalServer in environment.yaml:

applications:
  files:
    editors:
      collabora:
        enabled: true
        externalServer: 'https://collabora.my-domain.com'

Configurazione di OnlyOffice

In entrambe le modalità, la funzionalità OnlyOffice deve essere attivata nel file di configurazione environment.yaml:

applications:
  files:
    editors:
      onlyoffice:
        enabled: true
        secret: 'REPLACE_WITH_LONG_RANDOM_ONLYOFFICE_SECRET'

informazioni

I parametri avanzati di OnlyOffice sono descritti nella sezione Parametri del server.

Generare un valore sicuro e utilizzare lo stesso segreto nel server OnlyOffice.

Modalità con proxy

Nella configurazione di Nginx, rimuovere il commento dalla direttiva include onlyoffice.conf; per caricare la configurazione di OnlyOffice.
In questa modalità non è necessario esporre direttamente a Internet il server OnlyOffice, che deve tuttavia restare accessibile dal server Sync-in.

Creare quindi il file /etc/nginx/onlyoffice.conf e inserirvi il contenuto seguente.

⚠️ Il valore di proxy_pass deve essere adattato all'indirizzo del server OnlyOffice.

location ^~ /onlyoffice/ {
    proxy_pass http://onlyoffice:80/;
    proxy_set_header X-Real-IP  $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $http_host/onlyoffice;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_no_cache 1;
    proxy_cache_bypass 1;
}

Modalità esterna

Il server OnlyOffice deve essere accessibile sia dal server Sync-in sia dal browser, tramite un nome di dominio o un indirizzo IP.
Configurare la direttiva externalServer in environment.yaml:

applications:
  files:
    editors:
      onlyoffice:
        enabled: true
        secret: 'REPLACE_WITH_LONG_RANDOM_ONLYOFFICE_SECRET'
        externalServer: 'https://onlyoffice.my-domain.com'

Configurazione di Euro-Office

Sync-in gestisce Euro-Office come editor compatibile con OnlyOffice.

In entrambe le modalità, la funzionalità Euro-Office deve essere attivata nel file di configurazione environment.yaml:

applications:
  files:
    editors:
      eurooffice:
        enabled: true
        secret: 'REPLACE_WITH_LONG_RANDOM_EUROOFFICE_SECRET'

Generare un valore sicuro e utilizzare lo stesso segreto nel server Euro-Office.

avvertenza

Non attivare contemporaneamente onlyoffice ed eurooffice, a meno che non si tratti di una scelta intenzionale.

Se entrambi sono attivi, Sync-in assegna la priorità a onlyoffice.

Modalità con proxy

Nella configurazione di Nginx, rimuovere il commento dalla direttiva include eurooffice.conf; per caricare la configurazione di Euro-Office.
In questa modalità non è necessario esporre direttamente a Internet il server Euro-Office, che deve tuttavia restare accessibile dal server Sync-in.

Creare quindi il file /etc/nginx/eurooffice.conf e inserirvi il contenuto seguente.

⚠️ Il valore di proxy_pass deve essere adattato all'indirizzo del server Euro-Office.

location ^~ /onlyoffice/ {
    proxy_pass http://eurooffice:80/;
    proxy_set_header X-Real-IP  $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $http_host/onlyoffice;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_no_cache 1;
    proxy_cache_bypass 1;
}

location ^~ /sdkjs/ {
    proxy_pass http://eurooffice:80/sdkjs/;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $http_host/onlyoffice;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
}

Modalità esterna

Il server Euro-Office deve essere accessibile sia dal server Sync-in sia dal browser, tramite un nome di dominio o un indirizzo IP.
Configurare la direttiva externalServer in environment.yaml:

applications:
  files:
    editors:
      eurooffice:
        enabled: true
        secret: 'REPLACE_WITH_LONG_RANDOM_EUROOFFICE_SECRET'
        externalServer: 'https://eurooffice.my-domain.com'

Configurazione di draw.io

In entrambe le modalità, la funzionalità draw.io deve essere attivata nel file di configurazione environment.yaml:

applications:
  files:
    editors:
      drawio:
        enabled: true

A differenza degli editor per ufficio, draw.io non richiede un segreto condiviso né un callback sul lato server.

Modalità con proxy

Nella configurazione di Nginx, rimuovere il commento dalla direttiva include drawio.conf; per caricare la configurazione di draw.io. In questa modalità, il container draw.io resta privato nella rete Docker o interna e viene esposto nel percorso /drawio/ dell'origine Sync-in.

Creare quindi il file /etc/nginx/drawio.conf e inserirvi il contenuto seguente.

⚠️ Adattare proxy_pass all'indirizzo del server draw.io. L'intestazione CORS è necessaria perché Sync-in carica l'editor locale in un iframe isolato con un'origine opaca.

location ^~ /drawio/ {
    add_header Access-Control-Allow-Origin "*" always;
    proxy_pass http://drawio:8080/;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
}

Modalità esterna

Il server draw.io deve essere accessibile dai browser degli utenti. Configurare il relativo URL con la direttiva externalServer e utilizzare un'origine dedicata per isolare l'editor da Sync-in:

applications:
  files:
    editors:
      drawio:
        enabled: true
        externalServer: 'https://drawio.my-domain.com'

Configurazione del server Sync-in​

Valori possibili​

Configurazione di Nginx​

Configurazione di Collabora Online​

Modalità con proxy​

Modalità esterna​

Configurazione di OnlyOffice​

Modalità con proxy​

Modalità esterna​

Configurazione di Euro-Office​

Modalità con proxy​

Modalità esterna​

Configurazione di draw.io​

Modalità con proxy​

Modalità esterna​

Configurazione del server Sync-in

Valori possibili

Configurazione di Nginx

Configurazione di Collabora Online

Modalità con proxy

Modalità esterna

Configurazione di OnlyOffice

Modalità con proxy

Modalità esterna

Configurazione di Euro-Office

Modalità con proxy

Modalità esterna

Configurazione di draw.io

Modalità con proxy

Modalità esterna