Referenz zu selbstgehosteten Umgebungen
Beginnen Sie mit den Veröffentlichungen env.example, die Sie heruntergeladen haben als .env in Erste Schritte. Es handelt sich um die kleinste unterstützte Compose-Konfiguration. Benutzen env.full.example wenn Sie eine optionale Einstellung benötigen; Auf dieser Seite wird erklärt, welche Einstellungen zusammengehören und wann sie geändert werden müssen.
Nach der Bearbeitung .env, validieren Sie die Interpolation, ohne die aufgelöste Konfiguration zu drucken:
docker compose config --quiet
Legen Sie keine Verpflichtungen fest .env, fügen Sie es in Supportanfragen ein oder stellen Sie die Ausgabe von bereit docker compose config: Die aufgelöste Ausgabe enthält Geheimnisse.
Erforderliche Produktionswerte
Generieren Sie jedes Geheimnis unabhängig mit openssl rand -hex 32. Behalten Sie die alten Werte bei jedem Upgrade bei und speichern Sie eine Wiederherstellungskopie außerhalb des Servers.
| Variabel | Produktionswert | Warum es wichtig ist |
|---|---|---|
POSTGRES_PASSWORD | Einzigartiges zufälliges Passwort | Schützt die gebündelte PostgreSQL-Datenbank. |
WEB_ORIGIN | Öffentlicher HTTPS-App-Ursprung, z. B https://kanera.example.com | Wird für Browser-Links, CORS und Authentifizierungsflüsse verwendet. Fügen Sie keinen abschließenden Schrägstrich ein. |
COOKIE_DOMAIN | App-Hostname, z. B kanera.example.com | Bereich für das Aktualisierungscookie. |
COOKIE_SECURE | true | Erforderlich, wenn die App über HTTPS bereitgestellt wird. |
JWT_SECRET | Stabiles Zufallsgeheimnis, mindestens 16 Zeichen | Signiert Benutzersitzungen. Die Rotation meldet alle ab. |
MCP_INTERNAL_SECRET | Stabiles Zufallsgeheimnis, mindestens 32 Zeichen und unterschiedlich JWT_SECRET | Ermöglicht dem MCP und den öffentlichen API-Diensten den Austausch zielgruppengebundener OAuth-Anmeldeinformationen, ohne dass ein MCP-Token weitergeleitet werden muss /api/v1. Beide Dienste müssen immer den gleichen Wert verwenden. |
MFA_ENCRYPTION_KEY | Stabiles Zufallsgeheimnis, mindestens 32 Zeichen | Schützt die Registrierung und Herausforderungen des Authentifikators. Durch die Rotation werden registrierte Authentifikatoren ungültig. |
MEDIA_SIGNING_SECRET | Stabiles Zufallsgeheimnis, mindestens 32 Zeichen | Signiert private Medien-URLs. Durch die Rotation werden vorhandene signierte URLs ungültig. |
SECRETS_ENCRYPTION_KEY | Stabiles Zufallsgeheimnis, mindestens 32 Zeichen und unterschiedlich JWT_SECRET | Verschlüsselt in der Datenbank gespeicherte SMTP-, Speicher-, Webhook- und Integrationsanmeldeinformationen. |
KANERA_DEPLOYMENT_MODE Standardmäßig ist self_hosted. Der gehostete Modus und seine Stripe-, PostHog-, Plan-Limit- und Lizenzierungsvariablen gelten für von Kanera betriebene Bereitstellungen und sollten bei einer selbst gehosteten Installation deaktiviert bleiben.
Stellen Sie Vorräte zusammen NODE_ENV=production und ANALYTICS_ENABLED=false. Geh ANALYTICS_PROVIDER, POSTHOG_PROJECT_KEY, POSTHOG_API_HOST, alle STRIPE_*, HOSTED_*, und das Token für den gehosteten Modus ist nicht gesetzt. Diese Einstellungen verwandeln eine selbstgehostete Installation nicht in Kanera Cloud.
Öffentliche URLs und Dienste
| Variabel | Standard | Stellen Sie es ein, wann |
|---|---|---|
KANERA_ENVIRONMENT | production in Produktion Compose | Sie benötigen ein anderes API-Schlüsselpräfix für Entwicklung, Test oder Staging. |
API_PUBLIC_URL | WEB_ORIGIN | Die browserseitige App-API verwendet einen anderen öffentlichen Ursprung. |
KANERA_PUBLIC_API_URL | http://public-api:3001 im Komponieren | MCP oder ein anderer interner Prozess erreicht die öffentliche API an einem anderen Ort als seiner Compose-Dienstadresse. Dies ist eine interne URL, nicht der browserseitige API-Ursprung. |
PUBLIC_API_OAUTH_ISSUER | http://localhost:3001 | Sie stellen OAuth oder die öffentliche API remote zur Verfügung; Verwenden Sie seinen über den Browser erreichbaren HTTPS-Ursprung. |
MCP_SERVER_PUBLIC_URL | http://localhost:3002/mcp | Sie machen Remote-MCP verfügbar; die komplette Öffentlichkeit nutzen /mcp URL. |
MCP_PUBLIC_URL | Abgeleitet von MCP_SERVER_PUBLIC_URL von Compose | Sie führen den MCP-Dienst außerhalb der gebündelten Compose-Verkabelung aus. |
OAUTH_ISSUER_URL | Abgeleitet von PUBLIC_API_OAUTH_ISSUER von Compose | Sie führen MCP außerhalb der gebündelten Compose-Verkabelung aus. |
API_PORT, PUBLIC_API_PORT, WORKER_PORT, MCP_PORT | 3000, 3001, 3003, 3002 | Sie führen Dienste außerhalb von Compose aus oder benötigen andere interne Listener-Ports. |
API_TRUST_PROXY, PUBLIC_API_TRUST_PROXY, MCP_TRUST_PROXY | false, false, true | Ein vertrauenswürdiger Reverse-Proxy stellt die echte Client-IP bereit. Vertrauen Sie niemals weitergeleiteten Headern von beliebigen Clients. |
Der Browser stellt eine Verbindung her web; Veröffentlichen Sie nicht die Hauptseite api Dienst. Siehe Dienste und Routing bevor Sie die öffentliche API oder MCP verfügbar machen.
Konten und Authentifizierung
| Variabel | Standard | Zweck |
|---|---|---|
SIGNUPS_ENABLED | true | Set false um die öffentliche Anmeldung und die Gründung neuer Organisationen zu stoppen. Bestehende Organisationseinladungslinks funktionieren weiterhin. |
EMAIL_VERIFICATION_ENABLED | false | Für die Anmeldung, Einladungsanmeldung und E-Mail-Änderungen ist eine Überprüfung der sechsstelligen E-Mail-Adresse erforderlich. Nur aktivieren, wenn SMTP funktioniert. |
AUTH_RATE_LIMIT_ENABLED | true | Aktivieren Sie die Brute-Force-Drosselung pro IP auf nicht authentifizierten Authentifizierungsrouten. |
AUTH_RATE_LIMIT_MAX / AUTH_RATE_LIMIT_WINDOW_MS | 10 / 60000 | Zulässige Authentifizierungsversuche pro Fenster. |
JWT_ACCESS_TTL / JWT_REFRESH_TTL_DAYS | 5m / 10 | Lebensdauer von Zugriffstoken und Aktualisierungssitzungen. |
CLOUDFLARE_TURNSTILE_SITE_KEY / CLOUDFLARE_TURNSTILE_SECRET_KEY | Unscharf | Gehosteter Anmeldeschutz. Lassen Sie die Option für normales Selbsthosting deaktiviert. |
Benutzer konfigurieren unten ihren eigenen Authentifikator Einstellungen -> Ihr Konto -> Sicherheit. Organisationsadministratoren können dies unten anfordern Einstellungen -> Organisation -> Sicherheit. Siehe Profil und Sicherheit.
Öffentliche API- und MCP-Grenzwerte
| Variabel | Standard | Zweck |
|---|---|---|
PUBLIC_API_RATE_LIMIT_ENABLED | true | Aktiviert öffentliche API- und MCP-Anforderungslimits. |
PUBLIC_API_IP_RATE_LIMIT_PER_MINUTE | 60 | Beschränkung für nicht authentifizierte Erkennung und ungültige Trägerformate. |
PUBLIC_API_FAILED_KEY_RATE_LIMIT_PER_MINUTE | 10 | Pro-IP-Limit für fehlgeschlagen kanera_* Schlüsselversuche. |
PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE | 400 | Anforderungslimit pro Schlüssel nach erfolgreicher Authentifizierung. |
PUBLIC_API_UPLOAD_RATE_LIMIT_PER_MINUTE | 30 | Limit für das Hochladen von Anhängen pro Schlüssel. |
PUBLIC_API_RATE_LIMIT_WINDOW_MS | 60000 | Ratenbegrenzungsfenster, das von der öffentlichen API und dem MCP gemeinsam genutzt wird. |
MCP_BODY_MAX_BYTES | 1048576 | Maximaler MCP-Anfragetext. |
MCP_REQUEST_TIMEOUT_MS | 30000 | Maximale Zeit für eine MCP-Anfrage. |
MCP_HEADERS_TIMEOUT_MS / MCP_KEEP_ALIVE_TIMEOUT_MS | 10000 / 5000 | Zeitüberschreitungen bei MCP-HTTP-Verbindungen. |
KANERA_API_KEY | Unscharf | Wird nur von der lokalen Standard-MCP-Bridge benötigt, nicht vom HTTP-MCP-Dienst. |
Datenbank, Cache und Kapazität
Stellen Sie Vorräte zusammen DATABASE_URL und REDIS_URL für die gebündelten PostgreSQL- und Valkey-Dienste. Legen Sie sie nur dann selbst fest, wenn Sie einen Prozess außerhalb dieses Netzwerks ausführen oder verwaltete Dienste verwenden.
| Variabel | Standard verfassen | Zweck |
|---|---|---|
DATABASE_SSL | false | Nur aktivieren, wenn eine externe Datenbank SSL erfordert. |
POSTGRES_BIND_PORT | 5433 | Nur-Loopback-Host-Port für gebündeltes PostgreSQL. |
API_REPLICAS / PUBLIC_API_REPLICAS / MCP_REPLICAS | 2 / 1 / 1 | Der Serviceprozess zählt. Halten Sie den Arbeiter bei genau eins. |
PG_POOL_MAX / WORKER_PG_POOL_MAX | 20 / 5 | Maximale Datenbankverbindungen pro App-Prozess und für den Worker. |
PG_IDLE_TIMEOUT_MS / PG_CONNECTION_TIMEOUT_MS | 30000 / 5000 | Pool-Leerlauf- und Erfassungszeitüberschreitungen. |
PG_STATEMENT_TIMEOUT_MS / SLOW_QUERY_LOG_MS | 30000 / 250 | Zeitüberschreitung bei Datenbankabfragen und Protokollierungsschwellenwert für langsame Abfragen. |
NODE_OPTIONS | Unscharf | Optionale Knotenflags, z. B. ein Heap-Limit. |
UV_THREADPOOL_SIZE | 16 | Native Arbeitsthreads, die von Hashing, Krypto und Bildverarbeitung verwendet werden. |
REALTIME_WEBSOCKET_COMPRESSION_ENABLED | true | Komprimieren Sie größere Socket.IO-WebSocket-Nachrichten. |
REALTIME_WEBSOCKET_COMPRESSION_THRESHOLD_BYTES | 1024 | Minimale Echtzeit-Framegröße zum Komprimieren. |
REALTIME_OUTBOX_POLL_MS | 500 im Komponieren | Worker-Fallback-Abfrageintervall für Echtzeit- und Webhook-Postausgangszeilen. |
USER_DISPLAY_CACHE_TTL_MS | 60000 | Lebensdauer des prozessinternen Caches für die Suche nach Anzeigenamen. |
Erhöhen Sie Replikate und Pools erst dann gemeinsam, wenn die Kapazität gemessen wurde. Siehe Updates und Skalierung.
Datei- und Objektspeicher
| Variabel | Standard | Zweck |
|---|---|---|
UPLOADS_DIR | /data/uploads im Komponieren | Lokales Upload-Verzeichnis. Bundled Compose behebt diesen Pfad und behält ihn bei kanera_uploads; Ändern Sie stattdessen die Lautstärkezuordnung .env. |
ATTACHMENT_MAX_BYTES | 104857600 | Maximale Größe des hochgeladenen Anhangs in Bytes. |
S3_REGION / S3_BUCKET | Unscharf | Starten Sie den bereitstellungsweiten S3-kompatiblen Speicher, wenn Sie über Anmeldeinformationen verfügen. |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | Unscharf | Anmeldeinformationen für den Upload-Bucket. Beide sind für umgebungsbasiertes S3 erforderlich. |
S3_ENDPOINT | Unscharf | Benutzerdefinierter Endpunkt für MinIO, R2 oder einen anderen S3-kompatiblen Anbieter. Wenn Sie es festlegen, werden Anforderungen im Pfadstil aktiviert. |
S3_PUBLIC_URL_PREFIX | Unscharf | Optionales öffentliches oder CDN-Präfix für gespeicherte Objekte. |
Der Umgebungsspeicher hat Vorrang vor dem in der App konfigurierten Organisationsspeicher. Siehe Speicherung und Backups bevor Sie eine Installation wechseln, die bereits über Uploads verfügt.
E-Mail, Benachrichtigungen und Integrationen
| Variabel | Standard | Zweck |
|---|---|---|
SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM_EMAIL | Unscharf | Standardmäßige ausgehende SMTP-Verbindung und Absender. |
SMTP_PORT / SMTP_SECURITY | 587 / starttls | SMTP-Port und Transport: starttls, tls, oder none. |
SMTP_FROM_NAME | Kanera | Anzeigename des Absenders. |
SMTP_IDENTITY_DOMAIN | E-Mail-Domäne des Absenders | EHLO- und Message-ID-Domäne. |
INTERNAL_NOTIFICATION_EMAILS | Unscharf | Durch Kommas getrennte Empfänger für Klartext-Anmelde- und Einladungsbenachrichtigungen. Erfordert Umgebungs-SMTP. |
KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS | false | Erlauben Sie persönliche NTFY-, Gotify- und Webhook-Empfänger in HTTP oder privaten Netzwerken. Reservierte Adressen und Metadatenadressen bleiben gesperrt. |
ALERT_WEBHOOK_URL | Unscharf | Slack-kompatibles Ziel für Bereitschafts-, Laufzeit- und Grafana-Benachrichtigungen. |
OPS_ALERTS_ENABLED / OPS_ALERT_THROTTLE_MS | true / 300000 | Aktivieren und deduplizieren Sie Betriebswarnungen. Ohne Ziel wird nichts verschickt. |
SLOW_REQUEST_LOG_MS | 2500 | Schwellenwert für eine Warnung zu einer langsamen Anforderung in Protokollen. |
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY | Unscharf | Optionale, durch die Bereitstellung definierte GitHub-App für private Linkvorschauen. Selbstgehostete Administratoren können stattdessen den In-App-Manifestfluss verwenden. |
TRELLO_API_KEY | Unscharf | Ermöglicht Trello-Importen die Authentifizierung und das Kopieren von Anhängen. |
Siehe E-Mail und Benachrichtigungen und Integrationen und APIs.
Backups und Aufbewahrung
| Variabel | Standard | Zweck |
|---|---|---|
DB_BACKUPS_ENABLED | false | Aktivieren Sie geplante verschlüsselte PostgreSQL-Backups auf S3-kompatiblem Speicher. |
DB_BACKUP_ENCRYPTION_PASSPHRASE | Unscharf | Erforderlich, wenn Sicherungen aktiviert sind, und erneut erforderlich, um sie wiederherzustellen. |
DB_BACKUP_TIMES_UTC | 00:15,12:15,16:45 | Durch Kommas getrennte tägliche UTC-Sicherungszeiten. |
DB_BACKUP_RETENTION_DAYS | 14 | Erfolgreiches Backup-Aufbewahrungsfenster. |
DB_BACKUP_S3_PREFIX | backups/postgres | Objektpräfix für Datenbank-Dumps. |
DB_BACKUP_S3_BUCKET, DB_BACKUP_S3_REGION, DB_BACKUP_S3_ENDPOINT | Upload-Speicherwerte | Optionales separates Backup-Ziel. |
DB_BACKUP_S3_ACCESS_KEY_ID, DB_BACKUP_S3_SECRET_ACCESS_KEY | Upload-Speicherwerte | Optionale separate Backup-Anmeldeinformationen. |
ACTIVITY_EVENT_RETENTION_DAYS | 730 | Aufbewahrung des Aktivitätsverlaufs. |
ADMIN_AUDIT_LOG_RETENTION_DAYS | 1095 | Aufbewahrung des Management-Audit-Protokolls. |
NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS | 90 / 365 | Lesebenachrichtigung und absolute Benachrichtigungsspeicherung. |
AUTH_TOKEN_RETENTION_DAYS | 30 | Kulanzzeitraum, bevor abgelaufene oder verbrauchte Authentifizierungsartefakte gelöscht werden. |
REALTIME_OUTBOX_RETENTION_DAYS / OUTBOX_STUCK_RETENTION_DAYS | 30 / 30 | Verarbeitete und dauerhaft hängengebliebene Postausgangsaufbewahrung. |
Siehe Speicherung und Backups für Backup-Anforderungen und Wiederherstellungsplanung.
Überwachung
| Variabel | Standard | Zweck |
|---|---|---|
METRICS_ENABLED | true | Registriert Prometheus-Metrikendpunkte. Sie kehren zurück 404 ohne gültigen Token. |
METRICS_TOKEN | Unscharf | Inhabertoken, mindestens 16 Zeichen, zum Scrapen erforderlich. |
COMPOSE_PROFILES | Unscharf | Einbeziehen monitoring Grafana, Prometheus, Loki, Alloy und Exporteure zu gründen; einschließen admin für das Verwaltungsportal. |
COMPOSE_PROJECT_NAME | kanera | Stellen Sie eine Identität zusammen, die Alloy verwendet, um die Protokolle dieser Bereitstellung auszuwählen. Überprüfen docker compose ls auf verwalteten Plattformen. |
GRAFANA_ADMIN_PASSWORD | Unscharf | Erforderlich, wenn das Überwachungsprofil aktiviert ist. |
MONITORING_BIND_IP | 127.0.0.1 | Host-Schnittstelle für Grafana und Prometheus. Verwenden Sie niemals eine private VPN-Adresse 0.0.0.0 in der Produktion. |
GRAFANA_BIND_PORT / PROMETHEUS_BIND_PORT | 3000 / 9090 | Host-Ports für die beiden Überwachungs-UIs. |
PROMETHEUS_RETENTION / PROMETHEUS_RETENTION_SIZE | 30d / 5GB | Zeit- und Festplattenobergrenzen für Prometheus-Daten. |
GRAFANA_ROOT_URL | Unscharf | Externe Grafana-URL bei der Bereitstellung über einen Proxy. |
POSTGRES_EXPORTER_DSN | Gebündelte Datenbank | Überschreibung für einen externen PostgreSQL-Server. |
REALTIME_EMIT_METRICS_ENABLED | false | Aktivieren Sie abgetastete Nutzlastmetriken in Echtzeit. |
REALTIME_EMIT_METRICS_SAMPLE_RATE / REALTIME_EMIT_METRICS_MIN_BYTES | 0.01 / 0 | Echtzeit-Metrik-Sampling und minimale Nutzlastgröße. |
Optionales Verwaltungsportal
Das Verwaltungsportal ist von den Mandanteneinstellungen getrennt und verfügt über eine eigene Authentifizierungsgrenze. Aktivieren Sie es nur, wenn Betreiber eine organisationsübergreifende Verwaltung oder geprüfte Supportsitzungen benötigen.
| Variabel | Standard | Zweck |
|---|---|---|
ADMIN_WEB_ORIGIN | http://localhost:4300 | Öffentlicher Ursprung und CORS-Grenze für die Admin-Konsole. |
ADMIN_API_PORT | 3002 | Interner Admin-API-Listener-Port, wenn er außerhalb der gebündelten Verkabelung ausgeführt wird. |
ADMIN_COOKIE_DOMAIN | Unscharf | Cookie-Domänenüberschreibung, wenn der Administrator-Hostname außerhalb liegt COOKIE_DOMAIN. |
ADMIN_JWT_SECRET | Unscharf | Erforderlich für die Admin-API und muss von abweichen JWT_SECRET. |
ADMIN_EMAIL / ADMIN_PASSWORD | Unscharf | Setzen Sie den ersten Superadmin nur, wenn die Admin-Benutzer-Tabelle leer ist. Sie setzen ein bestehendes Konto nicht zurück. |
ADMIN_JWT_ACCESS_TTL / ADMIN_JWT_REFRESH_TTL_DAYS | 15m / 7 | Administratorzugriff und Aktualisierungsdauer. |
ADMIN_LOGIN_RATE_LIMIT_MAX / ADMIN_LOGIN_RATE_LIMIT_WINDOW_MS | 5 / 300000 | Drosselung der Administratoranmeldung pro IP. |
ADMIN_TRUST_PROXY | true | Vertrauen Sie dem Admin-Reverse-Proxy für echte Client-IPs. |
SUPPORT_SESSION_TTL_MINUTES | 60 | Kurze Lebensdauer der Support-Sitzung; maximal acht Stunden und kein Aktualisierungstoken. |
Halten Sie das Verwaltungsportal privat, verwenden Sie einen separaten Hostnamen und ein separates Geheimnis und überprüfen Sie das Prüfprotokoll. Die vollständige Einsatzverkabelung ist in dokumentiert DEPLOY.md im Kanera-Repository.
Änderungen anwenden und überprüfen
Die meisten Änderungen erfordern die Neuerstellung der betroffenen Dienste:
docker compose config --quiet
docker compose up -d
docker compose ps
Überprüfen Sie die relevanten Dienstprotokolle, nachdem Sie Authentifizierungs-, Zustellungs-, Speicher-, API-, MCP- oder Administratoreinstellungen geändert haben. Eine syntaktisch gültige .env beweist nicht, dass externe Anmeldeinformationen oder URLs funktionieren.