AFFiNE sur Google Cloud Run

AFFiNE est une base de connaissances open source, centrée sur la confidentialité, qui réunit documents, tableaux blancs et bases de données dans un même espace de travail — une alternative auto-hébergeable à Notion et Miro. Ce module déploie AFFiNE sur Cloud Run v2, au-dessus du socle App_CloudRun, qui provisionne et gère l'infrastructure Google Cloud partagée.

Ce guide se concentre sur les services cloud qu'utilise AFFiNE et sur la manière de les explorer et de les exploiter depuis la console Google Cloud et la ligne de commande. Pour les mécanismes communs à toutes les applications Cloud Run — identité du service, ingress et équilibrage de charge, mise à l'échelle et concurrence, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, sauvegardes et cycle de vie du déploiement — reportez-vous au guide du socle App_CloudRun plutôt que de les répéter ici.

1. Vue d'ensemble

Le serveur auto-hébergé d'AFFiNE s'exécute comme un conteneur Node.js unique sur Cloud Run v2. Le déploiement assemble un ensemble ciblé de services Google Cloud :

Fonctionnalité	Service Google Cloud	Remarques
Calcul	Cloud Run v2	Service Node.js, 2 vCPU / 4 GiB par défaut, instance unique toujours active
Base de données	Cloud SQL for PostgreSQL 15	Obligatoire — AFFiNE ne prend pas en charge MySQL (vérifié au moment du plan)
Collaboration en temps réel	Redis	Obligatoire — pub/sub de synchronisation des documents Yjs et file de jobs ; l'hôte NFS héberge aussi le Redis par défaut
Stockage des blobs	Filestore / NFS	Pièces jointes téléversées conservées dans `/root/.affine/storage` (gen2 requis)
Stockage d'objets	Cloud Storage	Un bucket `storage` dédié provisionné automatiquement
Secrets	Secret Manager	Mot de passe de la base de données géré automatiquement ; AFFiNE n'a besoin d'aucun secret applicatif
Image de conteneur	Cloud Build + Artifact Registry	Build personnalisé léger au-dessus de `ghcr.io/toeverything/affine`
Ingress	URL Cloud Run / Cloud Load Balancing	URL `run.app` par défaut, équilibreur de charge HTTPS externe + domaine personnalisé en option

Valeurs par défaut judicieuses à connaître d'emblée :

PostgreSQL 15 est obligatoire. Une validation au moment du plan limite database_type aux versions de PostgreSQL ; MySQL est rejeté.
Redis est obligatoire. Une validation au moment du plan fait échouer le déploiement si enable_redis = false. Sans redis_host explicite, l'IP du serveur NFS est utilisée comme point de terminaison Redis.
Instance unique par conception. min_instance_count = 1, max_instance_count = 1, cpu_always_allocated = true — les WebSockets de collaboration en temps réel doivent rester accessibles et alimentés en CPU, et l'état de collaboration propre à chaque processus ainsi que les blobs sur le système de fichiers rendent la mise à l'échelle horizontale dangereuse.
Pas de socket Cloud SQL. enable_cloudsql_volume = false : AFFiNE utilise un DATABASE_URL de type URL-authority qui ne peut pas contenir les deux-points du chemin du socket ; le point d'entrée se connecte donc via l'IP privée de l'instance avec sslmode=require.
Deux jobs d'initialisation à l'application. db-init crée de manière idempotente la base de données et l'utilisateur ; affine-migrate exécute le self-host-predeploy d'AFFiNE (migration du schéma + génération de la clé de signature) avant le démarrage du serveur.
Aucun secret applicatif. AFFiNE conserve sa propre clé de signature dans PostgreSQL lors de la migration ; seul le mot de passe de la base de données généré automatiquement réside dans Secret Manager.
Les sondes de santé ciblent / — AFFiNE renvoie HTTP 200 sur son chemin racine une fois prêt.
application_version = "latest" correspond à stable — AFFiNE ne publie pas de tag d'image latest.
La recherche plein texte/vectorielle est désactivée (AFFINE_INDEXER_ENABLED = "false") — l'indexeur nécessite un backend vectoriel qui n'est pas provisionné ici.

2. Services Google Cloud et comment les explorer

Toutes les commandes supposent que PROJECT et REGION sont définis. Les noms du service et des ressources figurent dans les sorties du déploiement.

A. Cloud Run — le service AFFiNE

AFFiNE s'exécute comme un service Cloud Run v2 épinglé sur une instance unique toujours active. Chaque déploiement crée une révision immuable ; le trafic bascule vers la plus récente qui est saine.

Console : Cloud Run → sélectionnez le service pour voir les révisions, le trafic, les journaux et les métriques.

CLI :

gcloud run services list --project "$PROJECT" --region "$REGION"
gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
gcloud run revisions list --service <service-name> --project "$PROJECT" --region "$REGION"

Consultez App_CloudRun pour la mise à l'échelle, la concurrence, l'environnement d'exécution et la répartition du trafic.

B. Cloud SQL for PostgreSQL 15

AFFiNE stocke les espaces de travail, les documents, les utilisateurs et sa propre clé de signature dans une instance gérée Cloud SQL for PostgreSQL 15. Comme le DATABASE_URL d'AFFiNE est un DSN de type URL-authority, le service se connecte via l'IP privée avec TLS (sslmode=require) plutôt que par le socket de l'Auth Proxy. Au premier déploiement, le job db-init crée la base de données et l'utilisateur de l'application, puis affine-migrate crée le schéma.

Console : SQL → sélectionnez l'instance pour voir les connexions, les sauvegardes, les flags et les métriques.

CLI :

gcloud sql instances list --project "$PROJECT"
gcloud sql instances describe <instance-name> --project "$PROJECT"
gcloud sql connect <instance-name> --user=<db-user> --project "$PROJECT"

Le nom de l'instance, la base de données, l'utilisateur et le secret du mot de passe figurent dans les sorties. Consultez App_CloudRun pour le modèle de connexion, les sauvegardes et la rotation des mots de passe.

C. Redis — collaboration en temps réel

Redis porte le pub/sub de synchronisation des documents Yjs d'AFFiNE et sa file de jobs en arrière-plan — le déploiement refuse de produire un plan sans lui. Lorsqu'aucun redis_host externe n'est configuré, le Redis hébergé sur le serveur NFS partagé est utilisé automatiquement.

Console : Memorystore → Redis (si vous utilisez une instance gérée) ; Compute Engine → VM instances (l'hôte NFS/Redis).

CLI :

redis-cli -h <redis-host> ping
redis-cli -h <redis-host> info clients

D. Filestore (NFS) et Cloud Storage

Les blobs téléversés (images, pièces jointes, fichiers intégrés) sont écrits sur un partage NFS monté sur /root/.affine/storage, afin de survivre aux révisions et aux redémarrages. Un bucket Cloud Storage dédié (suffixe storage) est également provisionné automatiquement. L'environnement d'exécution gen2 est requis pour les montages NFS.

Console : Filestore → Instances (ou Compute Engine → VM instances pour la VM NFS autogérée) ; Cloud Storage → Buckets.

CLI :

gcloud filestore instances list --project "$PROJECT"
gcloud storage buckets list --project "$PROJECT"
gcloud storage ls gs://<storage-bucket>/        # bucket name is in the Outputs

Consultez App_CloudRun pour le montage NFS, GCS Fuse et CMEK.

E. Secret Manager

Le mot de passe de la base de données généré automatiquement est le seul secret — AFFiNE génère et stocke sa clé de signature dans PostgreSQL pendant le job affine-migrate ; il n'existe donc aucun secret applicatif à gérer ou à faire tourner.

Console : Security → Secret Manager.

CLI :

gcloud secrets list --project "$PROJECT"
gcloud secrets versions access latest --secret=<secret-name> --project "$PROJECT"

Consultez App_CloudRun pour les détails d'injection et de rotation.

F. Réseau et entrée

Le service est accessible par défaut à son URL run.app. Un équilibreur de charge HTTPS externe avec domaine personnalisé, Cloud CDN et Cloud Armor peut être ajouté ; les paramètres d'ingress et la sortie VPC contrôlent la connectivité. Le point d'entrée cloud définit par défaut AFFINE_SERVER_EXTERNAL_URL sur l'URL du service injectée, afin que les invitations et les liens de partage se résolvent correctement.

Console : Cloud Run (URL du service) ; Network services → Load balancing.

CLI :

gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
gcloud compute addresses list --project "$PROJECT"

Consultez App_CloudRun.

G. Cloud Logging et Monitoring

Les journaux des conteneurs sont envoyés à Cloud Logging ; les métriques Cloud Run et Cloud SQL sont envoyées à Cloud Monitoring, avec des tests de disponibilité et des règles d'alerte en option.

Console : Logging → Logs Explorer ; Monitoring → Dashboards / Alerting.

CLI :

gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50

3. Comportement de l'application AFFiNE

Configuration de la base de données en deux étapes. À l'application, db-init (image postgres:15-alpine) crée de manière idempotente le rôle et la base de données AFFiNE, accorde les privilèges et tente d'accorder cloudsqlsuperuser afin que les migrations puissent exécuter CREATE EXTENSION. Ensuite, affine-migrate exécute node ./scripts/self-host-predeploy d'AFFiNE à l'aide de l'image applicative construite — migration idempotente du schéma et génération de la clé de signature. Les deux peuvent être réexécutés sans risque ; affine-migrate effectue jusqu'à 3 tentatives.
La clé de signature réside dans la base de données. Contrairement à la plupart des applications, il n'y a pas de variable d'environnement de type APP_SECRET : la clé générée par self-host-predeploy est conservée dans PostgreSQL, de sorte que le déploiement ne porte aucun secret applicatif susceptible de se désynchroniser ou à faire tourner.
Assemblage du DSN au démarrage. Le point d'entrée cloud construit DATABASE_URL à partir des variables DB_* injectées par le socle (en encodant les identifiants pour l'URL) et associe REDIS_HOST/PORT/AUTH aux REDIS_SERVER_* d'AFFiNE. Sur Cloud Run, il se connecte à l'IP privée de Cloud SQL avec sslmode=require ; une variable d'environnement DATABASE_URL prédéfinie est prioritaire.
URL externe. AFFINE_SERVER_EXTERNAL_URL vaut par défaut l'URL du service Cloud Run. Définissez-la explicitement (via environment_variables) une fois un domaine personnalisé en service, afin que les liens de partage et les e-mails d'invitation utilisent le bon hôte.
Configuration du premier lancement. Ouvrez l'URL du service et créez le premier compte — sur une nouvelle instance AFFiNE auto-hébergée, le premier utilisateur inscrit devient l'administrateur du serveur, et le panneau d'administration se trouve à <url>/admin.
Chemin de santé. Les sondes de démarrage, de vivacité et de disponibilité (readiness) ciblent /, qui renvoie HTTP 200 une fois le serveur prêt (fenêtre de démarrage : délai initial de 60 s + jusqu'à 30 × 15 s).
Contrainte de mise à l'échelle. Le service est épinglé sur exactement une instance toujours active. Les blobs sur le système de fichiers NFS et l'état Yjs propre à chaque processus rendent plusieurs instances dangereuses ; procédez plutôt à une mise à l'échelle verticale (cpu_limit / memory_limit).

Vérification :

SERVICE=$(gcloud run services list --project "$PROJECT" --region "$REGION" \
  --filter="metadata.name~affine" --format="value(metadata.name)" --limit=1)
SERVICE_URL=$(gcloud run services describe "$SERVICE" --project "$PROJECT" \
  --region "$REGION" --format="value(status.url)")
curl -s -o /dev/null -w "%{http_code}\n" "$SERVICE_URL/"    # expect 200

4. Variables de configuration

Les variables sont regroupées exactement comme elles apparaissent sur la plateforme de déploiement. Seuls les paramètres propres à AFFiNE ou notables pour lui sont listés ; toutes les autres entrées sont héritées d'App_CloudRun avec leur comportement standard.