Implantação e actualizações

Para sua primeira configuração local, siga Primeiro pedido. Use esta página ao escolher um método de implantação, configurando uma instância remota ou atualizando.

SubLane roda como um processo com uma interface incorporada e SQLite. A produção não requer Node.js, Redis ou um serviço proxy separado. Execute uma instância contra cada diretório de dados.

Publicado Docker imagens

Lançamentos com tags publicam ghcr.io/murongg/sublane em vez linux/amd64 e linux/arm64. Docker selecciona a arquitectura da máquina. As imagens são públicas e podem ser puxadas sem iniciar sessão no GHCR. A implantação requer Docker com Compose; nenhuma verificação de código fonte, Go, Node.js ou compilação de imagens local é necessária.

O manual Compose Exemplos abaixo afixar o publicado 0.1.0-rc.1 pré- lançamento. SUBLANE_IMAGE explicitamente para implantações manuais: o Compose por omissão é latest, que só é publicado com uma liberação estável.

Use uma versão fixa ou digite para implementações repetitivas. Uma nova imagem que apareça no GHCR não atualiza automaticamente um recipiente em execução.

Instalar o programa

Executa o instalador a partir de um terminal para escolher Docker ou um binário Linux publicado, uma instância normal ou uma demonstração somente leitura, então nenhum proxy, Caddy ou Nginx:

Use o Up/Down ou uma tecla de número para destacar uma opção, então digite para confirmar. A primeira opção é selecionada por padrão. Os terminais básicos usam as instruções de texto numeradas. O domínio continua sendo uma entrada de texto, e o instalador mostra a configuração gerada para confirmação antes da implantação. As bandeiras fornecidas ignoram suas escolhas correspondentes; --non-interactive desactiva todos os alertas.

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

Sem --version, o script seleciona GitHubA versão estável mais recente. Só quando não existe uma versão estável é que ela seleciona o pré- lançamento mais recentemente publicado, excluindo rascunhos. A versão de concreto selecionada é salva na configuração gerada, de modo que as reiniciagens não mudem silenciosamente as versões. GitHub API os erros param a instalação em vez de activar um canal de recuo.

O script verifica o artefato de liberação selecionado contra SHA256SUMS antes de instalá- lo em um novo ./sublane diretório. Bash, cacho e qualquer um sha256sum ou shasum são necessários; a seleção automática de versões requer adicionalmente jq. Docker o modo requer Docker Compose O modo binário suporta o Linux amd64/arm64, requer um gerenciador de usuário do sistema de trabalho, permite um serviço de usuário e espera por /readyz. Não instala Docker, Caddy ou Nginx, e não compila a partir de fonte.

Para escolher uma versão publicada, um novo diretório e uma porta host sem prompts:

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

As tags de versão podem incluir as principais v. A porta da infra- estrutura fica ligada a 127.0.0.1. Quando nenhum terminal está disponível, uma instância normal usando Docker sem proxy permanece o padrão; passe --runtime, --proxy, ou --demo para selecionar outros modos. Para um servidor remoto, use um túnel SSH para configurar HTTPS 'proxy' inverso.

O instalador usa ss (a partir de iproute2) ou lsof para verificar a porta de infraestrutura selecionada antes de baixar e novamente antes de criar a implantação. Se um loopback ou wildcard ouvinte já usa essa porta, ele para e pede que você escolha uma porta não utilizada com --portPor exemplo, --port 8088. Instale qualquer utilitário se nenhum estiver disponível. Um proxy existente nas portas 80 ou 443 não bloqueia uma instalação usando a porta de infraestrutura 8080. As verificações não podem reservar a porta; as verificações de saúde de inicialização ainda capturam conflitos que aparecem depois.

Por exemplo, escolha o binário publicado e gere um Caddyfile para um domínio público:

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

--domain é opcional com o Caddy ou Nginx. Sem ele, o proxy gerado escuta em 127.0.0.1:80 sobre HTTP e SUBLANE_PUBLIC_URL permanece desactivada. Com um domínio, o instalador define SUBLANE_PUBLIC_URL=https://<domain> e gera uma HTTPS configuração do 'proxy'. Ele mostra a configuração antes de instalar, mas não copia para o serviço proxy ou não recarregar. Rever o gerado Caddyfile ou nginx.conf e aplique- o você mesmo; o modelo Nginx assume os arquivos de certificados sob /etc/letsencrypt/live/<domain>/.

Pela Docker, o instalador escreve a imagem selecionada, porta e uma única Compose nome do projeto para .envFica com ela. docker.compose.yaml; identifica o volume de dados da implantação. Para modo binário, gera sublane.env, start.sh e uma unidade de usuário conectada do sistema; os dados permanecem em uma privada data/ diretório. Um serviço de usuário systemd pode parar quando o usuário sair, a menos que o demoramento esteja ativado; verifique loginctl show-user "$USER" -p Linger e organizar a permanência se você precisar de uma operação sem vigilância. Novas instalações recusam diretórios e links simbólicos existentes. Uma instalação gerenciada por script existente pode ser atualizada com o mesmo script, como descrito abaixo. Se a inicialização falhar, a configuração e quaisquer dados criados são retidos para inspeção.

Atualizar uma instalação gerenciada por script

Primeiro exportar e verificar um backup de banco de dados, e leia as notas de lançamento do alvo. Execute o script a partir do pai da pasta de instalação. Actualizar a instância existente e pede confirmação antes da implantação. Para selecionar a atualização explicitamente:

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

Sem --version, atualizações usam a mesma seleção estável / pré-lançamento como instalação. Adicionar --version <published-version> para fixar uma libertação, --wait-timeout 120 para alterar a disponibilidade esperar, ou --non-interactive para saltar a confirmação. O programa detecta as opções de tempo de execução existentes; apenas na instalação, como --runtime, --port, --proxy e --demo são rejeitados durante as actualizações.

Docker as atualizações preservam o Compose ficheiro e nome do projecto, apenas alteração SUBLANE_IMAGE em .env, puxe a imagem selecionada, e recriar o serviço com uma espera de saúde. Atualizações binárias verificar o arquivo, substituir os arquivos de documentação executável e embalados, reiniciar a unidade de usuário systemd existente, e esperar por /readyz. Os arquivos de ambiente, lançador, unidade de usuário, configuração de proxy e caminhos de dados estão preservados. Espera-se que a porta existente do serviço esteja ocupada, então as atualizações não executam verificações de porta de nova instalação.

A transferência, a soma de verificação, a configuração e as falhas de preenchimento da imagem deixam os arquivos implantados inalterados. Antes da substituição, o script salva os arquivos de configuração/programa anteriores em um privado .update-backup.* diretório dentro da instalação e imprime seu caminho. Estes arquivos não são um backup de banco de dados. A inicialização falhou retém- os e os dados de implantação atuais para inspeção, relata falhas e não executa automaticamente uma versão antiga contra um banco de dados potencialmente migrado. recuperação e retrocesso quando a restauração de dados é necessária. Uma atualização simultânea é recusada; se o processo foi forçado a ser morto, remova .update-lock apenas após confirmar que nenhuma atualização permanece ativa.

Este caminho de atualização suporta as instalações criadas pelo script. Implementos manuais e implementações que requerem Compose arquivos de substituição devem usar o procedimento de actualização manual, incluindo todas as sobreposições em partidas subsequentes.

Para rever o script antes de executá-lo, baixe-o com curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh -o install.sh, então corra bash install.sh --help ou bash install.sh Depois de o rever.

Manual Compose implantação

Criar um diretório de implantação e baixar docker.compose.yaml a partir do selecionado GitHub Lançar:

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

Nesse diretório, crie um Compose .env arquivo para manter a versão da imagem selecionada entre reinícios e atualizações:

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 reads .env para interpolação; a aplicação Go standalone não carrega .env Um digest imutável pode ser usado como todo o SUBLANE_IMAGE valor em vez de uma etiqueta.

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

Abrir http://127.0.0.1:8080 e completar a configuração do administrador antes de permitir o acesso dos membros. Para uma máquina remota, use um túnel SSH para a configuração inicial. Compose mapeamento permanece em loopback; publicação 0.0.0.0 é uma escolha explícita do operador.

A imagem é executada como o Alpino existente sublane conta de serviço, inclui certificados CA e avisos de licença, e verificações /readyz. Compose usa um sistema de arquivos root somente para leitura, um MIB 64 /tmp tmpfs para SDK arquivos de scratch, recursos do Linux abandonados, logs de container limitados e um período de graça de 30 segundos. O container escuta na porta 8080; personalize a porta host através SUBLANE_PORT. Se você mesmo substituir a porta de escuta interna, também alterar o exame de saúde e mapeamento de porta.

Dados persistentes

O nome sublane-data volume contém /data/sublane.db, os seus ficheiros WAL e /data/credentials.key. Mantenha a chave de encriptação com a base de dados. Compose as chaves de serviço/volume são preservadas, assim as atualizações das compilaçãos de fontes anteriores continuam usando o mesmo volume quando são executadas a partir do mesmo Compose projecto.

Manter a Compose o nome/diretório do projecto é consistente. A alteração cria um volume diferente e pode fazer com que uma instância existente pareça não iniciada. docker compose -f docker.compose.yaml down -v ao atualizar ou recuperar: que remove o volume de dados. As montagens de ligação são suportadas, mas suas permissões de host devem permitir que a conta não root da imagem escreva o diretório montado. Preferir o volume predefinido chamado, a menos que a propriedade do caminho da máquina seja intencional.

Compilar a partir do código fonte

Para compilar localmente em vez disso, clone o repositório e use o comando de compilação de código fonte:

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

Usar ambos os ficheiros para comandos subsequentes contra essa implantação. Para definir os meta- dados de compilação:

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

O arquivo docker compila Ir para TARGETOS/TARGETARCH a partir de etapas de compilação nativas, então a construção do ARM64 no x86-64 não emula o compilador ou a construção de frontend. Uma imagem multiplataforma pode ser construída com um Buildx configurado:

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

Criar dist primeiro. Uma compilação/carga local regular normalmente tem como alvo uma plataforma. Docker's Guia de compilação cruzada.

Binário Linux autônomo

Baixe o arquivo correspondente à sua máquina e SHA256SUMS da mesma libertação:

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

No Linux, verifique os arquivos baixados, extraia o arquivo em um novo diretório versionado e execute:

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

O arquivo contém os textos executáveis, AGPL e de licença de terceiros, o Compose arquivo, um exemplo de ambiente e documentação de implantação/ backup. Mantenha o diretório de dados fora do diretório executável versionado, torne-o privado e computável pelo usuário do serviço, e use um supervisor de processo para operação persistente. O instalador guiado pode executar esta configuração com um serviço de usuário systemd. Não execute o gateway como root.

Modo de demonstração

O instalador oferece instância normal ou demo somente para leitura após a escolha do tempo de execução. O modo normal continua a ser o padrão. Para selecionar o modo de demonstração diretamente:

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

--demo funciona com ambos --runtime docker e --runtime binary. Adicionar --non-interactive para usar as opções restantes. O instalador escreve SUBLANE_DEMO=true para .env em vez Compose ou sublane.env para o serviço binário, e exibe o login de demonstração público após a instalação. SUBLANE_DEMO não substitui o modo selecionado do instalador.

O suporte a demonstração deve estar presente na configuração verificada da versão selecionada. O instalador rejeita versões antigas antes de puxar/iniciar recipientes ou habilitar um serviço; use --version para selecionar uma versão que inclua suporte demo. Ela não se encaixa em uma instância normal.

Em uma compilação contendo suporte demo, inicie uma demonstração somente de leitura com:

SUBLANE_DEMO=true ./sublane

Abre o endereço do servidor habitual e escolhe Explorar a demonstração, ou entre com o nome de usuário demo e senha sublane-demo. O aplicativo mostra contas de assinatura de amostra claramente rotuladas, pools, membros, API metadados chave, histórico de pedidos e 30 dias de uso. Navegação, filtros, idioma e preferências de tema funcionam normalmente. Formulários podem ser inspecionados, mas escreve, divulgação credencial, OAuth, backups e todas as chamadas de gateway (incluindo WebSocket) estão bloqueados; login e logout permanecem disponíveis.

Cada início cria uma nova chave de criptografia e banco de dados temporário privado. O modo de demonstração não abre SUBLANE_DATA_DIR, caches de preços, ou credenciais reais, e não contacta os fornecedores ou serviços de liberação / pricing. Desligamento gracioso remove os arquivos temporários; uma morte abrupta pode deixar um sublane-demo-* diretório no diretório temporário do sistema operacional. Reiniciar recria os exemplos com datas recentes. Parar a demonstração e desmarcar SUBLANE_DEMO para retomar uma instalação normal.

Para o desenvolvimento, utilizar SUBLANE_DEMO=true make devCom esta versão Compose arquivo, definido SUBLANE_DEMO=true em .env e recriar o recipiente. As versões publicadas existentes sem suporte demo devem ser atualizadas ou reconstruídas primeiro. As configurações comuns de escuta-endereço, origem externa e confiança-proxy ainda se aplicam.

Configuração do tempo de execução

O serviço autônomo lê essas variáveis de ambiente de processo; .env.example lista exemplos. Não carrega uma .env ficheiro automaticamente. Compose reads .env para sua própria interpolação e passa o ambiente configurado para o recipiente.

A Docker a imagem substitui o endereço de escuta para 0.0.0.0:8080 e diretório de dados para /data. SUBLANE_IMAGE, SUBLANE_BIND_ADDRESS e SUBLANE_PORT configure Compose Apenas. SQLite inicializa o esquema consolidado em um banco de dados novo e utiliza uma única conexão de banco de dados.

O arranque inicializa bases novas e aplica, por ordem, as migrações em falta a bases existentes compatíveis. A estrutura preliminar incompatível com 001_settings.sql é rejeitada; preserve o diretório original antes de usar um novo. Exporte e verifique uma cópia de segurança antes de atualizar. Mudar apenas a imagem não reverte dados migrados.

SUBLANE_MAX_REQUEST_BODY_MB aplica- se ao gateway HTTP pedidos, WebSocket mensagens e contexto de conversação reconstruído. Responses e os eventos de fluxo mantêm seus limites separados de 8 MiB. Reinicie o serviço autônomo ou recrie o recipiente após alterar o limite de solicitação, e alinhe qualquer limite de corpo proxy reverso com o novo valor.

Se você sobrepor SUBLANE_PRICING_URL, também definido SUBLANE_PRICING_HASH_URL para o arquivo SHA-256 correspondente para manter as verificações de integridade do documento habilitadas. Um URL de preço personalizado sem um URL de hash é obtido e analisado, mas não é verificado.

As alterações no tempo de execução do Gateway requerem uma reinicialização ou uma recriação do recipiente. A actual Compose o ficheiro passa por estas variáveis. As actualizações geridas pelo programa preservam a existência Compose arquivo; adicione os novos itens de ambiente a um antigo salvo Compose arquivo antes de confiar em .env substitui. As configurações de concordância de conta/membro permanecem persistidas separadamente.

HTTPS 'proxy' inverso

Definir SUBLANE_PUBLIC_URL para a origem externa exata, como https://sublane.example.com, e recriar o serviço para que as alterações de ambiente tenham efeito. Isto é necessário por trás de um proxy reverso, porque o backback deriva a origem do cabeçalho Host da requisição. A origem configurada é usada para verificação de requisição do navegador e cookies de sessão segura. Encaminhar o cabeçalho Host original e preservar a transmissão e WebSocket upgrades.

Definir SUBLANE_TRUSTED_PROXIES para os endereços CIDR do seu próprio proxy hop. Para um autônomo SubLane binário alcançado ao longo do loopback IPv4, use 127.0.0.1/32 (adicionar ::1/128 para o loopback IPv6. A Docker o recipiente pode ver o proxy da máquina como seu endereço de ponte em vez de loopback; o instalador deixa este valor em branco Docker modo, a menos que passe --trusted-proxies com o endereço SubLane Para um contentor proxy, use o seu endereço fixo ou uma sub- rede privada dedicada e com um escopo apertado. SubLane ignora X-Forwarded-For a menos que o par directo corresponda a esta lista, então usa o IP mais não confiável na cadeia de limites de login. Mantenha o acesso direto a SubLane restrito ao proxy quando este estiver configurado. Sem ele, todos os usuários por trás de um proxy compartilham o limite de login do proxy.

Para um proxy de Caddy em execução na mesma máquina:

sublane.example.com {
    reverse_proxy 127.0.0.1:8080
}

Cabos TLS e WebSocket upgrades e flushes SSE respostas automaticamente. Mantenha o comportamento padrão de flush para que as desconexão do cliente possam cancelar o trabalho a montante; negativo flush_interval altera esse comportamento de cancelamento. Veja o Referência do proxy inverso do caddy. Se o proxy for outro recipiente, use o Compose nome do serviço sublane:8080 numa rede partilhada; 127.0.0.1 dentro do recipiente proxy refere-se àquele recipiente em si.

Para uma instalação Nginx existente, coloque o mapa no http contexto e usar estes locais dentro de sua HTTPS bloco do servidor:

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;
}

Configurar o HTTPS certificado no servidor- pai Nginx. O Nginx WebSocket guia explica os cabeçalhos de atualização explícitos. Os limites também devem permitir o tamanho de requisição/reforço em qualquer outra camada de proxy. A própria autorização do gateway e os limites do corpo permanecem em vigor.

Actualização

1. Reveja as notas de lançamento e grave a versão/digest da imagem atual.

2. Exportar uma cópia de segurança consistente e copiá-la do volume de dados:

   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

   Use um novo nome de arquivo para cada atualização; os backups existentes nunca são substituídos. O arquivo inclui a chave de criptografia e pertence ao armazenamento privado.

3. Alterar SUBLANE_IMAGE em .env para a versão selecionada, então puxe e recrie:

   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. Confirmar saúde, login, contas esperadas/pools/chaves, e uma chamada explicitamente autorizada para o cliente. SQLite esquema na inicialização. A saúde da imagem verifica a prontidão processo/base de dados, não a autorização real do provedor.

Recuperação e retrocesso

A alteração de uma etiqueta de imagem sozinha não é um rollback da base de dados. Se uma versão migrou o esquema, restaure o arquivo pré-upgrade para uma nova pasta com o binário/ imagem mais antigo pretendido, então pare o serviço atual e mude para aquela pasta restaurada. Mantenha o volume original até que a verificação esteja concluída. Nunca deixe que dois processos compartilhem o mesmo SQLite directório.

A guia de backup cobre CLI e web restauração preparação e o Compose sobrescrever para /data/restore-ready. Continue usando o sobreposição de restauração em inicia mais tarde enquanto esse diretório está ativo. Um backup de um esquema mais novo não pode ser aberto por uma versão mais antiga que não o reconhece.

Verificação dos contentores

Com uma Docker motor em funcionamento:

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

O programa de fumo cria o seu próprio volume e contentor descartáveis, com a rede desactivada. Verifica a saúde, a versão, a execução não- root, os caminhos de execução apenas para leitura, a configuração de primeira execução com credenciais sintéticas, permissões de chave, backup/ verificação/ restauração e persistência após reiniciar. Remove apenas os recursos temporários. Não contacta os fornecedores de montante inicial nem usa os dados de instância existentes. O CI executa as mesmas verificações nos corredores nativo amd64 e arm64.