Déploiement et modernisation

Pour votre première configuration locale, suivez Première demande. Utilisez cette page pour choisir une méthode de déploiement, configurer une instance distante ou mettre à jour.

SubLane fonctionne comme un processus avec une façade intégrée et SQLite. Production ne nécessite pas Node.js, Redis ou un service de proxy séparé. Exécutez une instance sur chaque répertoire de données.

Publié Docker images

Tags des publications publier ghcr.io/murongg/sublane pour linux/amd64 et linux/arm64. Docker sélectionne l'architecture hôte. Les images sont publiques et peuvent être tirées sans se connecter au GHCR. Docker avec Compose; pas de commande source, Go, Node.js ou de construction d'image locale est nécessaire.

Le manuel Compose exemples ci-dessous épingler la publication 0.1.0-rc.1 Prélibération. SUBLANE_IMAGE explicitement pour les déploiements manuels: Compose par défaut est latest, qui est seulement publié avec une version stable.

Utilisez une version fixe ou un digest pour les déploiements répétables. Une nouvelle image apparaissant dans GHCR ne met pas automatiquement à jour un conteneur en cours d'exécution.

Installer le script

Exécutez l'installateur depuis un terminal pour choisir Docker ou un binaire Linux publié, une instance normale ou une démo en lecture seule, puis pas de proxy, Caddy ou Nginx:

Utilisez Up/Down ou une touche de nombre pour mettre en évidence une option, puis Entrée pour confirmer. La première option est sélectionnée par défaut. Les terminaux de base utilisent des invites de texte numérotées. Le domaine reste une entrée de texte, et l'installateur affiche la configuration générée pour confirmation avant le déploiement. --non-interactive Désactive toutes les invites.

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash

Sans --version, le script sélectionne GitHubCe n'est que lorsqu'il n'existe pas de version stable qu'elle sélectionne la version la plus récente, à l'exclusion des brouillons. La version concrète sélectionnée est enregistrée dans la configuration générée, de sorte que les redémarrages ne changent pas silencieusement les versions. GitHub API les erreurs arrêtent l'installation au lieu de déclencher un repli de canal.

Le script vérifie l'artefact de publication sélectionné contre SHA256SUMS avant de l'installer dans un nouveau ./sublane répertoire. Bash, curl et soit sha256sum ou shasum sont nécessaires; la sélection automatique de la version nécessite également jq. Docker mode nécessite Docker Compose et attend que le conteneur devienne en bonne santé. Le mode binaire prend en charge Linux amd64/arm64, nécessite un gestionnaire utilisateur système de travail, permet un service utilisateur et attend pour /readyz. Il ne s'installe pas Docker, Caddy ou Nginx, et ne construit pas à partir de la source.

Pour choisir une version publiée, un nouveau répertoire et un port hôte sans instructions :

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- \
  --version 0.1.0-rc.1 --dir ./team-gateway --port 8088 --runtime docker --proxy none --non-interactive

Les balises de version peuvent inclure le leader v. Le port du moteur reste lié à 127.0.0.1. Lorsque aucun terminal n'est disponible, une instance normale utilisant Docker sans proxy reste la valeur par défaut; passe --runtime, --proxyou --demo pour sélectionner d'autres modes. Pour un serveur distant, utilisez un tunnel SSH pour la configuration initiale ou configurez le HTTPS proxy inversé.

L'installateur utilise ss (d'iproute2) ou lsof pour vérifier le port de backend sélectionné avant de télécharger et encore avant de créer le déploiement. Si un auditeur loopback ou wildcard utilise déjà ce port, il s'arrête et vous demande de choisir un port non utilisé avec --port, par exemple --port 8088. Installez l'un ou l'autre utilitaire si aucun n'est disponible. Un proxy existant sur les ports 80 ou 443 ne bloque pas une installation en utilisant le port moteur 8080. Les contrôles ne peuvent pas réserver le port ; les contrôles de santé de démarrage capturent toujours les conflits qui apparaissent après.

Par exemple, choisissez le binaire publié et générer un fichier Caddyfile pour un domaine public:

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- \
  --runtime binary --proxy caddy --domain sublane.example.com

--domain est optionnel avec Caddy ou Nginx. Sans cela, le proxy généré écoute sur 127.0.0.1:80 sur HTTP et SUBLANE_PUBLIC_URL avec un domaine, les ensembles d'installateurs SUBLANE_PUBLIC_URL=https://<domain> et génère une HTTPS configuration proxy. Il affiche la configuration avant l'installation, mais ne le copie ni ne recharge le service proxy. Examiner les produits Caddyfile ou nginx.conf et appliquez-le vous-même ; le modèle Nginx assume les fichiers de certificat sous /etc/letsencrypt/live/<domain>/.

Pour Docker, l'installateur écrit l'image sélectionnée, le port et un unique Compose nom du projet à .env. Gardez-le avec docker.compose.yaml; il identifie le volume de données du déploiement. Pour le mode binaire, il génère sublane.env, start.sh et une unité d'utilisateur système liée; les données restent dans un privé data/ répertoire. Un service utilisateur système peut s'arrêter lorsque l'utilisateur se déconnecte à moins que la persistance soit activée; vérifier loginctl show-user "$USER" -p Linger Les nouvelles installations refusent les répertoires et les liens symboliques existants. Une installation existante gérée par script peut être mise à jour avec le même script, comme décrit ci-dessous. Si le démarrage échoue, la configuration et les données créées sont conservées pour inspection.

Mettre à jour une installation gérée par script

Première exporter et vérifier une sauvegarde de base de données, et lire les notes de sortie de cible. Exécutez le script depuis le parent du répertoire d'installation. Dans un terminal, une cible existante offre Mettre à jour l'instance existante et demande une confirmation avant le déploiement. Pour sélectionner explicitement la mise à jour :

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- \
  --update --dir ./sublane

Sans --version, les mises à jour utilisent la même sélection stable/prérelease que l'installation. --version <published-version> pour épingler un relâchement, --wait-timeout 120 pour changer l'attente de préparation, ou --non-interactive pour sauter la confirmation. Le script détecte les drapeaux d'exécution existants; installation-seulement tels que --runtime, --port, --proxy et --demo sont rejetés lors des mises à jour.

Docker les mises à jour conservent la Compose nom du fichier et du projet, modifier seulement SUBLANE_IMAGE en .env, tirer l'image sélectionnée, et recréer le service avec une attente de santé. Mises à jour binaires vérifier l'archive, remplacer la documentation exécutable et emballée / licence des fichiers, redémarrer l'unité utilisateur système existante, et attendre pour /readyz. Les fichiers d'environnement, le lanceur, l'unité utilisateur, la configuration proxy et les chemins de données sont préservés. Le port existant du service devrait être occupé, de sorte que les mises à jour n'exécutent pas de nouvelles vérifications de port d'installation.

Le téléchargement, la somme de contrôle, la configuration et les échecs de la pompe d'image laissent les fichiers déployés inchangés. Avant le remplacement, le script enregistre les fichiers de programme/configuration précédents dans un privé .update-backup.* répertoire à l'intérieur de l'installation et imprime son chemin. Ces fichiers ne sont pas une sauvegarde de base de données. Le démarrage a échoué les conserve et les données de déploiement actuelles pour inspection, signale une défaillance, et n'exécute pas automatiquement une version ancienne contre une base de données potentiellement migrée. récupération et renversement Une mise à jour simultanée est refusée; si le processus a été tué de force, supprimer .update-lock seulement après avoir confirmé qu'aucune mise à jour ne reste active.

Ce chemin de mise à jour prend en charge les installations créées par le script. Déploiements et déploiements manuels qui nécessitent des ajouts Compose les fichiers de remplacement doivent utiliser le procédure de mise à niveau manuelle, y compris toutes les dérogations sur les départs ultérieurs.

Pour revoir le script avant de le lancer, téléchargez-le avec curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh -o install.sh, alors cours bash install.sh --help ou bash install.sh après l'avoir examiné.

Manuel Compose déploiement

Créer un répertoire de déploiement et télécharger docker.compose.yaml de la sélection GitHub Libération:

mkdir sublane && cd sublane
curl -fsSL https://github.com/murongg/SubLane/releases/download/v0.1.0-rc.1/docker.compose.yaml -o docker.compose.yaml

Dans ce répertoire, créez un Compose .env fichier pour garder la version d'image sélectionnée à travers les redémarrages et les mises à niveau:

SUBLANE_IMAGE=ghcr.io/murongg/sublane:0.1.0-rc.1
SUBLANE_BIND_ADDRESS=127.0.0.1
SUBLANE_PORT=8080
SUBLANE_LOG_LEVEL=info
# Add this when using an HTTPS reverse proxy:
# SUBLANE_PUBLIC_URL=https://sublane.example.com
# In Docker, first identify the proxy source IP as seen inside the container:
# SUBLANE_TRUSTED_PROXIES=<proxy-source-ip>/32

Compose lit .env pour l'interpolation; l'application autonome Go ne charge pas .env Un digest immuable peut être utilisé comme l'ensemble SUBLANE_IMAGE valeur au lieu d'une balise.

docker compose -f docker.compose.yaml pull
docker compose -f docker.compose.yaml up -d
docker compose -f docker.compose.yaml ps
docker compose -f docker.compose.yaml logs --tail=100 sublane

Ouvrir http://127.0.0.1:8080 pour un hôte distant, utilisez un tunnel SSH pour la configuration initiale. Compose la cartographie reste sur loopback; la publication 0.0.0.0 est un choix d'opérateur explicite.

L'image fonctionne comme l'Alpine existante sublane compte de service, comprend les certificats CA et les avis de licence, et les vérifications /readyz. Compose utilise un système de fichiers racine en lecture seule, un 64 Mio en écriture /tmp pour SDK les fichiers scratch, les capacités Linux abandonnées, les journaux de conteneurs limités et une période de grâce de 30 secondes d'arrêt. SUBLANE_PORT. Si vous dépassez le port d'écoute interne vous-même, changez également le contrôle de santé et la cartographie du port.

Données persistantes

Le nom sublane-data volume des cales /data/sublane.db, ses fichiers WAL et /data/credentials.key. Gardez la clé de chiffrement avec la base de données. Compose les clés de service/volume sont conservées, de sorte que les mises à jour à partir de la source plus ancienne ne cessent d'utiliser le même volume lorsqu'il est exécuté à partir du même Compose Projet en cours.

Gardez la Compose nom/répertoire du projet cohérent. La modification crée un volume nommé différent et peut faire apparaître une instance existante non initialisée. Ne pas exécuter docker compose -f docker.compose.yaml down -v lors de la mise à jour ou de la récupération : qui supprime le volume de données. Les montages de bind sont supportés, mais leurs permissions d'hôte doivent laisser le compte non root de l'image écrire le répertoire monté. Préférez le volume par défaut nommé à moins que la propriété du chemin hôte ne soit intentionnelle.

Construire à partir de la source

Pour construire localement, clonez le dépôt et utilisez la redéfinition source-build :

git clone https://github.com/murongg/SubLane.git
cd SubLane
docker compose -f docker.compose.yaml -f docker.compose.build.yaml up --build -d

Utilisez les deux fichiers pour les commandes subséquentes contre ce déploiement. Pour définir les métadonnées de construction :

VERSION=0.1.0-dev REVISION=$(git rev-parse HEAD) \
  docker compose -f docker.compose.yaml -f docker.compose.build.yaml build

Le fichier Docker compile Go for TARGETOS/TARGETARCH de construction native, de sorte que la construction ARM64 sur x86-64 n'émule pas le compilateur ou la construction frontale. Une image multi-plateforme peut être construite avec un constructeur Buildx configuré:

docker buildx build --platform linux/amd64,linux/arm64 \
  --build-arg VERSION=0.1.0-dev --output type=oci,dest=dist/sublane.oci.tar .

Créer dist d'abord. Une construction/charge locale régulière cible normalement une plate-forme. Docker's guide de compilation croisée.

Binary Linux autonome

Télécharger l'archive correspondant à votre machine et SHA256SUMS de la même version:

• sublane_VERSION_linux_amd64.tar.gz: x86-64.
• sublane_VERSION_linux_arm64.tar.gz- AArchim64.

Sous Linux, vérifiez les fichiers téléchargés, extrait l'archive dans un nouveau répertoire en version, et exécutez :

sha256sum --check --ignore-missing SHA256SUMS
./sublane --version
SUBLANE_ADDR=127.0.0.1:8080 SUBLANE_DATA_DIR=/srv/sublane/data ./sublane

L'archive contient les textes exécutables, AGPL et des licences tierces, Compose fichier, exemple d'environnement et documentation de déploiement/backup. Gardez le répertoire de données en dehors du répertoire exécutable en version, le rendre privé et en écriture par l'utilisateur de service, et utilisez un superviseur de processus pour une opération persistante. L'installateur guidé peut effectuer cette configuration avec un service utilisateur système. Ne pas exécuter la passerelle comme racine.

Mode démo

L'installateur offre instance normale ou démo en lecture seule Le mode normal reste la valeur par défaut. Pour sélectionner le mode démo directement :

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- --demo

--demo fonctionne avec les deux --runtime docker et --runtime binaryAjouter --non-interactive pour utiliser des valeurs par défaut pour les choix restants. L'installateur écrit SUBLANE_DEMO=true à .env pour Compose ou sublane.env pour le service binaire, et affiche la connexion de démonstration publique après l'installation. SUBLANE_DEMO ne remplace pas le mode sélectionné par l'installateur.

Le support de démonstration doit être présent dans la configuration vérifiée de la version sélectionnée. L'installateur rejette les versions plus anciennes avant de tirer/démarrer les conteneurs ou de permettre un service; utiliser --version pour sélectionner une version qui inclut le support de démonstration. Il ne revient pas à une instance normale.

Dans un build contenant du support de démonstration, commencez une démonstration en lecture seule avec:

SUBLANE_DEMO=true ./sublane

Ouvrez l'adresse habituelle du serveur et choisissez Explorez la démo, ou connectez-vous avec le nom d'utilisateur demo et mot de passe sublane-demo. L'application montre des exemples de comptes d'abonnement, de pools, de membres, API les métadonnées clés, l'historique des demandes et 30 jours d'utilisation. La navigation, les filtres, la langue et les préférences de thème fonctionnent normalement. OAuth, sauvegardes et tous les appels de passerelle (y compris WebSocket) sont bloqués ; la connexion et la déconnexion restent disponibles.

Chaque démarrage crée une nouvelle base de données temporaire privée et une clé de chiffrement. SUBLANE_DATA_DIR, prix caches , ou des références réelles , et ne contacte pas les fournisseurs ou les services de publication / prix . sublane-demo-* répertoire dans le répertoire temporaire du système d'exploitation. Redémarrage recrée les exemples avec des dates récentes. SUBLANE_DEMO pour reprendre une installation normale.

Utilisation pour le développement SUBLANE_DEMO=true make dev. Avec cette version Compose fichier, ensemble SUBLANE_DEMO=true en .env Les versions existantes publiées sans support de démonstration doivent d'abord être mises à niveau ou reconstruites. Les paramètres d'écoute ordinaire, d'origine externe et de proxy de confiance s'appliquent toujours.

Configuration du temps d'exécution

Le service autonome lit ces variables d'environnement de processus; .env.example liste des exemples. Il ne charge pas un .env fichier automatiquement. Compose lit .env pour sa propre interpolation et passe l'environnement configuré dans le conteneur.

Les Docker image remplace l'adresse d'écoute à 0.0.0.0:8080 et répertoire de données vers /data. SUBLANE_IMAGE, SUBLANE_BIND_ADDRESS et SUBLANE_PORT configurer Compose Seulement. SQLite initialise le schéma consolidé sur une nouvelle base de données et utilise une seule connexion de base de données.

Le démarrage initialise les nouvelles bases et applique, dans l’ordre, les migrations manquantes aux bases existantes compatibles. L’ancienne structure préliminaire avec 001_settings.sql est refusée ; conservez son répertoire avant d’en utiliser un nouveau. Exportez et vérifiez une sauvegarde avant la mise à niveau. Changer uniquement l’image ne restaure pas les données migrées.

SUBLANE_MAX_REQUEST_BODY_MB s'applique à la passerelle HTTP demandes, WebSocket messages et contexte de conversation reconstruit. Responses Redémarrez le service autonome ou recréez le conteneur après avoir modifié la limite de demande, et aligner les limites de corps mandataire inverses avec la nouvelle valeur.

Si vous passez outre SUBLANE_PRICING_URL, également SUBLANE_PRICING_HASH_URL Une URL de prix personnalisée sans URL de hachage est récupérée et analysée, mais n'est pas vérifiée par le hash.

Les changements d'exécution de la passerelle nécessitent un redémarrage ou une récréation de conteneur. Compose fichier passe ces variables à travers. mises à jour gérées par Script préserver existant Compose fichiers; ajouter les nouvelles entrées d'environnement à un ancien enregistré Compose fichier avant de compter sur .env Les paramètres de concordance des comptes et des membres demeurent séparés.

HTTPS proxy inversé

Jeu SUBLANE_PUBLIC_URL à l'origine extérieure exacte, par exemple https://sublane.example.com, et de recréer le service afin que les changements d'environnement prennent effet. Ceci est nécessaire derrière un proxy inverse parce que le repli dérive l'origine de l'en-tête de la requête Host. L'origine configurée est utilisée pour les vérifications de demande du navigateur et les cookies de session sécurisés. WebSocket des mises à niveau.

Jeu SUBLANE_TRUSTED_PROXIES à l'adresse CIDR de votre propre houblon mandataire. Pour un standalone SubLane binaire atteint sur IPv4 loopback, utilisation 127.0.0.1/32 (ajouter ::1/128 pour le loopback IPv6). Docker conteneur peut voir le proxy hôte comme son adresse de pont plutôt que loopback; l'installateur laisse cette valeur vide dans Docker mode à moins que vous passiez --trusted-proxies avec l'adresse SubLane Pour un conteneur proxy, utilisez son adresse fixe ou un sous-net privé dédié et étroitement encadré. SubLane ignore X-Forwarded-For à moins que le pair direct corresponde à cette liste, puis utilise l'IP le plus méfiant dans la chaîne pour les limites de connexion. SubLane Sans cela, tous les utilisateurs derrière un proxy partagent la limite de connexion du proxy.

Pour un proxy Caddy fonctionnant sur le même host :

sublane.example.com {
    reverse_proxy 127.0.0.1:8080
}

Poignées de Caddy TLS et WebSocket mises à niveau et rinçages SSE les réponses automatiquement. Gardez le comportement par défaut flush afin que les déconnectés client puissent annuler le travail en amont; négatif flush_interval modifie ce comportement d'annulation. Référence de la procuration inversée de Caddy. Si le proxy est un autre conteneur, utilisez le Compose Nom du service sublane:8080 sur un réseau partagé; 127.0.0.1 à l'intérieur du conteneur mandataire se réfère à ce conteneur lui-même.

Pour une installation Nginx existante, mettez la carte dans le http contexte et utiliser ces emplacements à l'intérieur HTTPS bloc serveur & #160;:

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

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $sublane_connection;
    proxy_buffering off;
    proxy_read_timeout 650s;
    proxy_send_timeout 650s;
    client_max_body_size 128m;
}

# Web backup uploads/downloads can be larger and last up to 15 minutes.
location /api/settings/backup/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_request_buffering off;
    proxy_buffering off;
    proxy_read_timeout 950s;
    proxy_send_timeout 950s;
    client_max_body_size 256m;
}

Configurer la HTTPS certificat dans le serveur parent Nginx. Nginx WebSocket guide Les limites doivent également permettre les tailles de requête/de sauvegarde à n'importe quelle autre couche de proxy. Les propres autorisations et limites de corps de la passerelle restent en vigueur.

Mise à jour

1. Consultez les notes de publication et enregistrez la version/digest de l'image actuelle.

2. Exportez une sauvegarde cohérente et copiez-la hors du volume de données :

   docker compose -f docker.compose.yaml exec sublane sh -c 'mkdir -p /data/backups'
   docker compose -f docker.compose.yaml exec sublane sublane backup --output /data/backups/pre-upgrade.sublane-backup.tar.gz
   docker compose -f docker.compose.yaml exec sublane sublane backup verify --input /data/backups/pre-upgrade.sublane-backup.tar.gz
   docker compose -f docker.compose.yaml cp sublane:/data/backups/pre-upgrade.sublane-backup.tar.gz ./pre-upgrade.sublane-backup.tar.gz
   chmod 600 ./pre-upgrade.sublane-backup.tar.gz

   Utilisez un nouveau nom de fichier pour chaque mise à jour; les sauvegardes existantes ne sont jamais écrasées. L'archive inclut la clé de chiffrement et appartient au stockage privé.

3. Changement SUBLANE_IMAGE en .env vers la version sélectionnée, puis tirez et recréez :

   docker compose -f docker.compose.yaml pull
   docker compose -f docker.compose.yaml up -d
   docker compose -f docker.compose.yaml ps
   docker compose -f docker.compose.yaml logs --tail=100 sublane

4. Confirmer la santé, l'inscription, les comptes/pools/clés attendus et un appel de client explicitement autorisé. Une nouvelle base de données reçoit la consolidation SQLite La santé de l'image vérifie l'état de préparation du processus/base de données, pas l'autorisation réelle du fournisseur.

Récupération et renversement

Si une version a migré le schéma, restaure l'archive pré-upgrade dans un nouveau répertoire avec l'ancienne binaire/image prévue, puis arrête le service actuel et change vers ce répertoire restauré. Conserver le volume original jusqu'à ce que la vérification soit terminée. Ne jamais laisser deux processus partager le même SQLite répertoire.

Les guide de sauvegarde couvre CLI et la préparation de restauration web et la Compose remplacement pour /data/restore-ready. Continuer à utiliser la retrouve de restauration sur les démarrages ultérieurs pendant que ce répertoire est actif. Une sauvegarde à partir d'un schéma plus récent ne peut pas être ouverte par une version plus ancienne qui ne la reconnaît pas.

Vérification du conteneur

Avec une Docker moteur en marche:

docker compose -f docker.compose.yaml config --quiet
docker compose -f docker.compose.yaml -f docker.compose.build.yaml config --quiet
docker buildx build --load --build-arg VERSION=0.0.0-test -t sublane:smoke .
bash scripts/container-smoke.sh sublane:smoke 0.0.0-test

Il vérifie la santé, la version, l'exécution non-root, les chemins d'exécution en lecture seule, la configuration de premier tirage avec des identifiants synthétiques, les permissions de clés, la sauvegarde/vérifier/restaurer et la persistance après le redémarrage. Il supprime uniquement ces ressources temporaires. Il ne contacte pas les fournisseurs en amont ou n'utilise pas les données d'instance existantes. CI effectue les mêmes vérifications sur les coureurs amd64 et arm64 natifs.