TLS и заглавки за сигурност

Сертификати

• Caddy автоматично получава и подновява сертификати от Let's Encrypt за всяко име, което обслужва (PLATFORM_DOMAIN, RMM_DOMAIN, RMM_FILES_DOMAIN и всяко име в PLATFORM_OLD_DOMAINS; на ACME_EMAIL се получават известия за изтичане). За всяко име е нужен DNS запис, който сочи към хоста, и достъпен порт 80 (HTTP-01 challenge). Сертификатите се съхраняват в тома caddy-data; правете му резервно копие, за да не се налага повторно издаване след изграждане наново.
• За да използвате собствен сертификат, заменете автоматичния TLS в блоковете на сайтовете в deploy/Caddyfile с tls /path/cert.pem /path/key.pem и монтирайте файловете в контейнера web.
• За лабораторни среди без публичен DNS вижте Инсталиране → Лабораторна инсталация.

Сайтове

deploy/Caddyfile винаги обслужва следните сайтове:

Сайт	Обслужва
PLATFORM_DOMAIN	Приложението на Hub на / и неговия API на /api/platform/*; портала на Axis на /axis/* и неговия API на /axis/api/* (без префикса, към бекендите); документацията на /docs/*; /manage/api/* за агентите, регистрирани там, а останалите /manage/* → 308 към /axis/*. /api/platform/internal/* и всеки друг /api/* → 404.
RMM_DOMAIN	Хостът на Axis отпреди Hub: /api/* и /manage/api/* към бекендите (регистрирани агенти, конектори, скриптове); /docs/* и /axis/* → 308 към същия път на PLATFORM_DOMAIN; всичко останало (страниците на стария портал) → 308 към https://PLATFORM_DOMAIN/axis{uri}.
PLATFORM_OLD_DOMAINS (по избор)	По-ранни имена на Hub: /axis/api/* и /manage/api/* към бекендите; всичко останало → 308 към същия път на PLATFORM_DOMAIN (страниците /manage/* към /axis/*).
RMM_FILES_DOMAIN	Обектно хранилище (MinIO) за изтегляния и качвания чрез предварително подписани URL адреси.

Препредаването на отдалечения работен плот между репликите (/api/remote/v1/internal/*) се отказва (404) на всеки публичен хост; репликите се достигат една друга директно.

Зад съществуващ nginx

На хост, където nginx вече обслужва други сайтове на портове 80 и 443 (в продукция от 2026-09-27: уебсайтът, helpdesk и Vaultwarden), Caddy се публикува на loopback, а nginx насочва всяка TLS връзка по името на сървъра (SNI) без да я дешифрира. Caddy запазва своите сертификати, WebSockets и порт 8322; другите сайтове запазват своите.

1. В deploy/.env: WEB_HTTP_PORT=127.0.0.1:8080 и WEB_HTTPS_PORT=127.0.0.1:8443 (HTTP/3 на 443/udp и 8322 остават публикувани директно).

2. apt install libnginx-mod-stream, а на най-горното ниво на /etc/nginx/nginx.conf: stream { include /etc/nginx/stream.d/*.conf; }.

3. /etc/nginx/stream.d/sni.conf:

   map $ssl_preread_server_name $sni_upstream {
       hub.entrosity.com          127.0.0.1:10444;
       manage.entrosity.com       127.0.0.1:10444;
       portal.entrosity.com       127.0.0.1:10444;
       files.manage.entrosity.com 127.0.0.1:10444;
       media.entrosity.com        127.0.0.1:10444;
       default                    127.0.0.1:10443;  # собствените HTTPS сайтове на nginx
   }
   server {
       listen 443;
       listen [::]:443;
       ssl_preread on;
       proxy_protocol on;          # адресът на клиента за следващата стъпка
       proxy_pass $sni_upstream;
       proxy_connect_timeout 5s;
       proxy_timeout 24h;          # агентите държат WebSockets отворени с часове
   }
   # Премахва PROXY заглавката преди Caddy (Caddyfile остава непроменен).
   server {
       listen 127.0.0.1:10444 proxy_protocol;
       proxy_pass 127.0.0.1:8443;
       proxy_timeout 24h;
   }

4. Всеки съществуващ HTTPS сървър на nginx слуша на listen 127.0.0.1:10443 ssl proxy_protocol; вместо на 443/[::]:443, а /etc/nginx/conf.d/00-realip.conf възстановява адреса на клиента: set_real_ip_from 127.0.0.1; real_ip_header proxy_protocol;.

5. /etc/nginx/conf.d/entrosity-platform.conf предава порт 80 на имената на Entrosity към Caddy (пренасочвания към HTTPS, HTTP-01 challenges): server с listen 80;, петте имена и location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; }.

6. nginx -t && systemctl restart nginx (рестарт, не reload: порт 443 преминава от http към stream).

Caddy вижда връзките от nginx, а не адреса на клиента; имената зад Cloudflare и преди това имаха адреса на Cloudflare.

Внимание

Всяко ново име на сървър за Caddy трябва да се добави в map, иначе стига до nginx. Инструментите, които пренаписват конфигурацията на nginx, връщат listen 443 и тогава nginx не стартира: след bench setup nginx (Frappe helpdesk) или certbot --nginx за ново име променете отново редовете им listen както в стъпка 4. certbot renew не е засегнат.

Заглавки

Hub и Axis (под /axis/) се обслужват със:

• HSTS (една година, включително поддомейните);
• строга политика за сигурност на съдържанието (Content Security Policy);
• X-Frame-Options: DENY, X-Content-Type-Options: nosniff;
• политики Referrer и Permissions.

Документацията под /docs/ получава собствена политика: тя допуска и вградени скриптове и blob workers, които са нужни на статичната компилация на Docusaurus и на справочника за API. Политиката на порталите остава непроменена.

Хостът за файлове изпраща Content-Security-Policy: default-src 'none'; sandbox, а качените файлове винаги се съхраняват като application/octet-stream, така че нищо качено не може да се изпълни в браузър.

Агенти и TLS инспекция

Агентите и конекторите проверяват сертификата на сървъра спрямо хранилището за доверени сертификати на Windows (Windows trust store). Прокси, което прихваща TLS в мрежата на клиента, трябва или да е доверено от машините, или имената на сървъра да са изключени от него (адресът, с който устройството е регистрирано, и хостът за файлове). В противен случай симптомът е x509: certificate signed by unknown authority в журнала на агента.

WebSocket връзките трябва да преминават през уеб проксито. Ако са блокирани, агентите преминават към периодично запитване по HTTPS (Отстраняване на проблеми).