Visão geral da arquitetura

Gitrust é uma plataforma de hospedagem Git auto-hospedada construída na estrutura rustwarden-core. A aplicação expõe dois pontos de entrada de rede (HTTP + SSH) e persiste seus dados no PostgreSQL.

Visão geral

graph TB
    subgraph Clients
        Browser["Navigateur Web"]
        GitCLI["Git CLI (ssh/https)"]
    end

    subgraph "Gitrust Binary (src/main.rs)"
        Main["main()"]
    end

    subgraph "Crates Gitrust"
        Web["gitrust-web
Routes HTTP, templates,
handlers Axum"]
        SSH["gitrust-ssh
Serveur SSH (russh),
auth par clé, sessions"]
        SshGuard["gitrust-ssh-guard
SecureListener, détecteurs,
BanManager, AuthTracker"]
        Hooks["gitrust-hooks
impl RustwardenHooks
(on_user_registered, ...)"]
        Core["gitrust-core
Models, services, migrations,
rôles, types, DTOs"]
        Git["gitrust-git
Bare repos, tree browser,
pack protocol (git2)"]
    end

    subgraph "Framework"
        RW["rustwarden-core
Auth, users, JWT, sessions,
ResourceService, i18n"]
    end

    subgraph "Stockage"
        PG[(PostgreSQL)]
        FS[("Système de fichiers
bare repos .git")]
    end

    subgraph "CI/CD (optionnel)"
        CiWorker["CiWorker
tokio::spawn, mpsc,
sous-processus Dagger"]
        Dagger["Dagger Engine
Containers isolés,
cache, exécution"]
        CiEngine["ci-engine
Module Dagger Python
(Easy Mode)"]
        Syft["Syft (optionnel)
Génération SBOM
CycloneDX"]
        DTrack["Dependency-Track
(optionnel)
Analyse vulnérabilités"]
    end

    Browser -->|HTTP :4000| Web
    GitCLI -->|SSH :2222| SshGuard
    SshGuard -->|"AcceptOutcome::Accepted"| SSH
    GitCLI -->|HTTPS :4000| Web

    Main --> Web
    Main --> SSH
    Main --> SshGuard
    Main --> Hooks
    Main -.->|"si CI_ENABLED"| CiWorker

    Web --> Core
    Web --> Git
    Web -.->|"admin ACL/ban"| SshGuard
    SSH --> Core
    SSH --> Git
    SSH --> SshGuard
    SshGuard --> Core
    Hooks --> Core

    Core --> RW
    Core --> PG
    Git --> FS

    CiWorker --> Core
    CiWorker -->|"dagger call"| Dagger
    Dagger -->|"Easy Mode"| CiEngine
    Dagger -->|"Power Mode"| FS
    CiWorker -.->|"si CI_SBOM_ENABLED"| Syft
    Syft -.->|"si CI_DTRACK_ENABLED"| DTrack

Iniciando o aplicativo

O diagrama a seguir detalha a sequência de inicialização de main() até iniciar os servidores HTTP e SSH.

sequenceDiagram
    participant Main as main()
    participant Builder as RustwardenBuilder
    participant App as RustwardenApp
    participant Mig as AppMigrator
    participant DB as PostgreSQL
    participant SMTP as Serveur SMTP

    Main->>Main: GitrustConfig::from_env()
    Main->>Main: Arc (hooks FS)

    Main->>Builder: builder().from_env()
    Note over Builder: Charge .env, init tracing
    Main->>Builder: .headless().auto_migrate(false)
    Main->>Builder: .merge_routes(app_routes(hooks))
    Note over Builder: Routes = framework API
+ pages SSR gitrust
+ Extension(hooks)
    Main->>Builder: .build().await
    Builder->>DB: Connexion pool
    Builder->>DB: Migrations rustwarden-core
    Builder->>SMTP: EmailQueueProcessor.start()
    Note over SMTP: Worker de fond : dépile
email_queue toutes les 30s
    Builder-->>Main: RustwardenApp

    Main->>Mig: run_migrations(app.database())
    Mig->>DB: core_migrations() + gitrust_migrations()
    Note over DB: Tables: users, resources,
repositories, ssh_keys,
teams, team_members,
team_repository_access
    Mig-->>Main: Ok

    Main->>Main: tokio::spawn(SSH server :2222)

    alt CI_ENABLED=true
        Main->>Main: CiWorker::start(config.ci)
        Note over Main: Vérifie dagger dans PATH
Si CI_SBOM_ENABLED: vérifie syft
Si CI_DTRACK_ENABLED: vérifie API DT
        Main->>Main: tokio::spawn(CiWorker loop)
        Note over Main: Écoute mpsc channel
pour les jobs CI
    end

    Main->>App: app.run().await
    Note over App: HTTP :4000 démarre

Princípios de design

Estrutura/separação de negócios gitrust

Gitrust é construído com base no Rustwarden-core, uma estrutura de autenticação e gerenciamento de usuários Rust. Esta separação é intencional:

  • rustwarden-core gerencia: autenticação JWT, sessões, usuários, funções genéricas, i18n, SMTP, OAuth, log de auditoria genérico.
  • gitrust-core gerencia: tudo específico para o Git forge — repositórios, chaves SSH, equipes, permissões RBAC de 4 níveis, CI, importação de repositório.

A regra fundamental: nunca modifique crates/rustwarden-core/. Qualquer extensão passa por wrappers, hooks (RustwardenHooks) ou recursos implementados no lado do gitrust.

Modo sem cabeça

gitrust-web opera no modo headless(): as páginas UI padrão do Rustwarden (login, registro, configurações) são desativadas e reimplementadas inteiramente em gitrust-web/templates/. Isso permite um design coerente (barra lateral Git, DaisyUI) sem comprometer a UI genérica do framework.

SSR + HTML, zero CDN

A interface é renderizada no lado do servidor via Askama (modelos Rust compilados). HTMX gerencia interações dinâmicas (atualizações parciais de páginas, SSE para notificações e logs de CI). Nenhum ativo externo: todo CSS/JS é servido a partir de static/ — imposto pela Política de Segurança de Conteúdo da estrutura.

Resto nu no sistema de arquivos

gitrust-git está desacoplado do banco de dados. As operações Git (navegação em árvore, leitura de blob, protocolo de pacote) funcionam diretamente em repositórios simples ({GIT_REPOS_BASE_PATH}/{owner}/{slug}.git/) via libgit2. O banco de dados armazena apenas metadados (nome, descrição, visibilidade, propriedade). Essa dissociação permite que o gitrust-git seja substituído ou testado de forma independente.

CI híbrido: Dagger como abstração de execução

Em vez de implementar um executor de CI do zero, o gitrust delega a execução ao Dagger, o que garante isolamento (contêineres), reprodutibilidade (cache) e portabilidade (executor local ou remoto via SSH+rsync). O CiWorker é uma tarefa do Tokio no processo principal — não um daemon separado — que simplifica a implantação (um único binário).

Para ir mais longe