docs: add self-hosted HA guidance

RainbowDashy · RainbowDashy · commit cb0faed33b34 · 2026-03-24T10:45:29.000+08:00
diff --git a/docs/administration/license.mdx b/docs/administration/license.mdx
@@ -14,6 +14,10 @@ Bytebase offers [3 pricing plans](https://www.bytebase.com/pricing): `Free`, `Pr
   **Pro plan is cloud-only.** Self-hosted deployments require an Enterprise license. Existing Pro self-host licenses are grandfathered. Self-hosted Free instances can start a [14-day Enterprise trial](https://www.bytebase.com/contact-us/).
 </Info>
 
+<Note>
+Running more than one self-hosted Bytebase replica requires HA to be enabled in the license. If multiple replicas are detected without HA enabled, Bytebase disables backend runners for safety.
+</Note>
+
 ## Configure Workspace License
 
 Go to **Settings > Subscription**, paste your license and click **Upload License**.
diff --git a/docs/docs.json b/docs/docs.json
@@ -36,6 +36,7 @@
                   "get-started/self-host/deploy-with-docker",
                   "get-started/self-host/deploy-with-kubernetes",
                   "get-started/self-host/external-postgres",
+                  "get-started/self-host/high-availability",
                   "get-started/self-host/network-architecture",
                   "get-started/self-host/external-access",
                   "get-started/self-host/external-url",
@@ -603,4 +604,4 @@
       "tagId": "GTM-MMG29QS6"
     }
   }
-}
+}
diff --git a/docs/get-started/self-host/deploy-with-kubernetes.mdx b/docs/get-started/self-host/deploy-with-kubernetes.mdx
@@ -6,8 +6,7 @@ title: Deploy with Kubernetes
 ## Deployment
 
 <Note>
-
-Make sure to set the replicas to **1**, otherwise, it may cause data race issues.
+Single-replica deployment still works as before. For multi-replica deployment, see [High Availability](/get-started/self-host/high-availability/).
 
 </Note>
 
@@ -20,7 +19,6 @@ metadata:
   name: bytebase
   namespace: default
 spec:
-  # To prevent data races, only request one replica.
   replicas: 1
   selector:
     matchLabels:
@@ -92,6 +90,10 @@ spec:
 
 Bytebase provides an official Helm chart for simplified Kubernetes deployments. For comprehensive configuration options and advanced settings, visit the [Bytebase Helm Chart on Artifact Hub](https://artifacthub.io/packages/helm/bytebase/bytebase).
 
+<Note>
+The current official Helm chart deploys a single replica and does not yet expose HA-specific settings such as replica count and the `--ha` flag. If you want to run Bytebase in HA mode today, use a custom manifest based on this guide or customize the chart template before deploying.
+</Note>
+
 ### Installation
 
 Deploy Bytebase using Helm with your external PostgreSQL database:
@@ -110,3 +112,46 @@ To remove the Bytebase deployment:
 ```bash
 helm delete --namespace <YOUR_NAMESPACE> <RELEASE_NAME>
 ```
+
+## HA Deployment
+
+To run Bytebase with multiple replicas on Kubernetes:
+
+1. Configure an external PostgreSQL database with `PG_URL`.
+2. Set `replicas` to more than `1`.
+3. Add the `--ha` flag to every Bytebase replica.
+4. Put the replicas behind one stable ingress, gateway, or service entrypoint.
+5. Make sure the workspace license has HA enabled.
+
+Example:
+
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: bytebase
+  namespace: default
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: bytebase
+  serviceName: bytebase
+  template:
+    metadata:
+      labels:
+        app: bytebase
+    spec:
+      containers:
+        - name: bytebase
+          image: bytebase/bytebase:latest
+          env:
+            - name: PG_URL
+              value: 'postgresql://<<user>>:<<secret>>@<<host>>:<<port>>/<<dbname>>'
+          args:
+            - '--port'
+            - '8080'
+            - '--ha'
+          ports:
+            - containerPort: 8080
+```
diff --git a/docs/get-started/self-host/external-postgres.mdx b/docs/get-started/self-host/external-postgres.mdx
@@ -8,6 +8,10 @@ import TerminalDockerRunPgUrl from '/snippets/install/terminal-docker-run-pg-url
 
 PostgreSQL 14 or above.
 
+<Note>
+External PostgreSQL is required for [High Availability](/get-started/self-host/high-availability/). HA mode is not supported with Bytebase's embedded PostgreSQL.
+</Note>
+
 ### Database
 
 Create a database named `bytebase` with UTF-8 encoding. UTF-8 encoding is required for proper system operation.
@@ -128,4 +132,3 @@ spec:
 <Note>
 When using file-based secrets, Kubernetes automatically updates the mounted file content when the Secret is updated (typically within a minute). Bytebase monitors the file for changes and automatically reloads the connection string, enabling seamless secret rotation without downtime.
 </Note>
-
diff --git a/docs/get-started/self-host/high-availability.mdx b/docs/get-started/self-host/high-availability.mdx
@@ -0,0 +1,76 @@
+---
+title: High Availability
+---
+
+Bytebase supports high availability (HA) for self-hosted deployments.
+
+In HA mode, you run multiple Bytebase replicas behind the same external endpoint. The replicas coordinate through the shared metadata PostgreSQL database, so scheduled work such as rollout tasks, plan checks, schema sync, and cancellation handling remains safe across replicas.
+
+## Requirements
+
+- Use an external PostgreSQL database for Bytebase metadata
+- Start every replica with the `--ha` flag
+- Put all replicas behind the same load balancer / ingress / service
+- Configure the same External URL for the deployment
+- Use a license with HA enabled
+
+<Warning>
+HA mode does not work with Bytebase's embedded PostgreSQL. If `PG_URL` is not set, Bytebase will refuse to start in HA mode.
+</Warning>
+
+## How It Works
+
+- Each replica sends heartbeats to the metadata PostgreSQL database
+- Distributed coordination uses PostgreSQL advisory locks and row-level claiming
+- Long-running tasks are owned by a replica; stale work is detected if that replica stops heartbeating
+- Cancel signals are propagated across replicas through PostgreSQL `NOTIFY/LISTEN`
+
+## Kubernetes Example
+
+The example below shows the minimum HA-specific changes compared with a single-replica deployment:
+
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: bytebase
+  namespace: default
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: bytebase
+  serviceName: bytebase
+  template:
+    metadata:
+      labels:
+        app: bytebase
+    spec:
+      containers:
+        - name: bytebase
+          image: bytebase/bytebase:latest
+          env:
+            - name: PG_URL
+              value: "postgresql://<<user>>:<<secret>>@<<host>>:<<port>>/<<dbname>>"
+          args:
+            - "--port"
+            - "8080"
+            - "--ha"
+          ports:
+            - containerPort: 8080
+```
+
+Use an ingress, gateway, or load balancer in front of the replicas so clients always access Bytebase through one stable URL.
+
+## Operational Notes
+
+- HA is mainly for Kubernetes or other orchestrated environments. A single `docker run` deployment is still a single-node setup.
+- Replicas do not require embedded PostgreSQL or shared local metadata storage.
+- If multiple replicas are running without HA enabled in the license, Bytebase disables backend runners to avoid unsafe execution.
+
+## Related Guides
+
+- [Production Setup](/get-started/self-host/production-setup/)
+- [Deploy with Kubernetes](/get-started/self-host/deploy-with-kubernetes/)
+- [Configure External PostgreSQL](/get-started/self-host/external-postgres/)
+- [Configure External URL](/get-started/self-host/external-url/)
diff --git a/docs/get-started/self-host/production-setup.mdx b/docs/get-started/self-host/production-setup.mdx
@@ -17,7 +17,7 @@ This page provides a comprehensive checklist for setting up Bytebase in a produc
 
 ### Storage
 
-Bytebase uses a PostgreSQL database to store SQL statements and other metadata. 
+Bytebase uses a PostgreSQL database to store SQL statements and other metadata.
 
 - If using cloud services (RDS, Cloud SQL) that support disk expansion, you can start with 20 GB and increase the size later as usage grows
 - Otherwise, start with 100 GB to avoid running out of space
@@ -28,6 +28,7 @@ Teams that frequently work with large SQL files may need more.
 
 - Review system requirements (see above)
 - [Configure External PostgreSQL](/get-started/self-host/external-postgres/)
+- Decide whether you need [High Availability](/get-started/self-host/high-availability/)
 - [Configure External Access](/get-started/self-host/external-access)
 - [Configure External URL](/get-started/self-host/external-url)
 - Pin Docker image to specific version instead of `latest` ([changelog](https://docs.bytebase.com/changelog))
@@ -39,6 +40,16 @@ Teams that frequently work with large SQL files may need more.
   docker pull bytebase/bytebase:3.7.0@sha256:00b436855b08739aad02fd52e41b5d74c03db9c70c49ce5de42376347cd1403c
   ```
 
+## High Availability Checklist
+
+If you plan to run Bytebase with multiple replicas:
+
+- Use external PostgreSQL. HA is not supported with embedded PostgreSQL
+- Start every replica with `--ha`
+- Put replicas behind one ingress, gateway, or load balancer
+- Set the same External URL for the whole deployment
+- Confirm your license has HA enabled before scaling above one replica
+
 ### Monitoring
 
 - Telemetry metrics available at `/metrics` endpoint
@@ -48,13 +59,16 @@ Teams that frequently work with large SQL files may need more.
 If deploying on a cloud provider, use the recommended stack:
 
 #### AWS
+
 - **Compute**: EC2 or ECS/EKS
 - **Database**: RDS for PostgreSQL
 
 #### GCP
+
 - **Compute**: GCE or GKE
 - **Database**: Cloud SQL for PostgreSQL
 
 #### Azure
+
 - **Compute**: Virtual Machines or AKS
 - **Database**: Azure Database for PostgreSQL

Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@`
`36`	`36`	`"get-started/self-host/deploy-with-docker",`
`37`	`37`	`"get-started/self-host/deploy-with-kubernetes",`
`38`	`38`	`"get-started/self-host/external-postgres",`
	`39`	`+ "get-started/self-host/high-availability",`
`39`	`40`	`"get-started/self-host/network-architecture",`
`40`	`41`	`"get-started/self-host/external-access",`
`41`	`42`	`"get-started/self-host/external-url",`
`@@ -603,4 +604,4 @@`
`603`	`604`	`"tagId": "GTM-MMG29QS6"`
`604`	`605`	`}`
`605`	`606`	`}`
`606`		`-}`
	`607`	`+}`