diff --git a/tidb-cloud/branch-github-integration.md b/tidb-cloud/branch-github-integration.md
index 144b3ccfe2026..ed06d698ac399 100644
--- a/tidb-cloud/branch-github-integration.md
+++ b/tidb-cloud/branch-github-integration.md
@@ -40,7 +40,11 @@ To integrate TiDB Serverless branching with your GitHub repository, take the fol
     - If you have not logged into GitHub, you will be asked to log into GitHub first.
     - If it is the first time you use the integration, you will be asked to authorize the **TiDB Cloud Branching** app.
 
+<<<<<<< HEAD
     ![github-authorize.png](/media/tidb-cloud/branch/github-authorize.png)
+=======
+   <img src="https://docs-download.pingcap.com/media/images/docs/tidb-cloud/branch/github-authorize.png" width="80%" />
+>>>>>>> 6efd9be235 (update media resource links to point to new locations (#20415))
 
 4. In the **Connect to GitHub** dialog, select a GitHub account in the **GitHub Account** drop-down list.
 
@@ -50,7 +54,11 @@ To integrate TiDB Serverless branching with your GitHub repository, take the fol
 
 6. Click **Connect** to connect between your TiDB Serverless cluster and your GitHub repository.
 
+<<<<<<< HEAD
     ![github-connect.png](/media/tidb-cloud/branch/github-connect.png)
+=======
+   <img src="https://docs-download.pingcap.com/media/images/docs/tidb-cloud/branch/github-connect.png" width="40%" />
+>>>>>>> 6efd9be235 (update media resource links to point to new locations (#20415))
 
 ## TiDB Cloud Branching app behaviors
 
diff --git a/tidb-cloud/migrate-from-mysql-using-data-migration.md b/tidb-cloud/migrate-from-mysql-using-data-migration.md
index f2c1496e61e16..dfb093e66a374 100644
--- a/tidb-cloud/migrate-from-mysql-using-data-migration.md
+++ b/tidb-cloud/migrate-from-mysql-using-data-migration.md
@@ -209,15 +209,15 @@ For detailed instructions about incremental data migration, see [Migrate Only In
 
     - If you click **All**, the migration job will migrate the existing data from the whole source database instance to TiDB Cloud and migrate ongoing changes after the full migration. Note that it happens only if you have selected the **Existing data migration** and **Incremental data migration** checkboxes in the previous step.
 
-        <img src="https://download.pingcap.com/images/docs/tidb-cloud/migration-job-select-all.png" width="60%" />
+        <img src="https://docs-download.pingcap.com/media/images/docs/tidb-cloud/migration-job-select-all.png" width="60%" />
 
     - If you click **Customize** and select some databases, the migration job will migrate the existing data and migrate ongoing changes of the selected databases to TiDB Cloud. Note that it happens only if you have selected the **Existing data migration** and **Incremental data migration** checkboxes in the previous step.
 
-        <img src="https://download.pingcap.com/images/docs/tidb-cloud/migration-job-select-db.png" width="60%" />
+        <img src="https://docs-download.pingcap.com/media/images/docs/tidb-cloud/migration-job-select-db.png" width="60%" />
 
     - If you click **Customize** and select some tables under a dataset name, the migration job only will migrate the existing data and migrate ongoing changes of the selected tables. Tables created afterwards in the same database will not be migrated.
 
-        <img src="https://download.pingcap.com/images/docs/tidb-cloud/migration-job-select-tables.png" width="60%" />
+        <img src="https://docs-download.pingcap.com/media/images/docs/tidb-cloud/migration-job-select-tables.png" width="60%" />
 
     <!--
     - If you click **Customize** and select some databases, and then select some tables in the **Selected Objects** area to move them back to the **Source Database** area, (for example the `username` table in the following screenshots), then the tables will be treated as in a blocklist. The migration job will migrate the existing data but filter out the excluded tables (such as the `username` table in the screenshots), and will migrate ongoing changes of the selected databases to TiDB Cloud except the filtered-out tables.
diff --git a/tidb-monitoring-api.md b/tidb-monitoring-api.md
index 9039794cce255..fb03e486bb382 100644
--- a/tidb-monitoring-api.md
+++ b/tidb-monitoring-api.md
@@ -78,7 +78,7 @@ curl http://127.0.0.1:10080/schema_storage/test
 
 - PD API address: `http://${host}:${port}/pd/api/v1/${api_name}`
 - Default port: `2379`
-- Details about API names: see [PD API doc](https://download.pingcap.com/pd-api-v1.html)
+- Details about API names: see [PD API doc](https://docs-download.pingcap.com/api/pd-api/pd-api-v1.html)
 
 The PD interface provides the status of all the TiKV servers and the information about load balancing. See the following example for the information about a single-node TiKV cluster:
 
diff --git a/tiproxy/tiproxy-load-balance.md b/tiproxy/tiproxy-load-balance.md
new file mode 100644
index 0000000000000..29a8d706eea10
--- /dev/null
+++ b/tiproxy/tiproxy-load-balance.md
@@ -0,0 +1,194 @@
+---
+title: TiProxy Load Balancing Policies
+summary: Introduce the load balancing policies in TiProxy and their applicable scenarios.
+---
+
+# TiProxy Load Balancing Policies
+
+TiProxy v1.0.0 only supports status-based and connection count-based load balancing policies for TiDB servers. Starting from v1.1.0, TiProxy introduces five additional load balancing policies: label-based, health-based, memory-based, CPU-based, and location-based.
+
+By default, TiProxy applies these policies with the following priorities:
+
+1. Status-based load balancing: when a TiDB server is shutting down, TiProxy migrates connections from that TiDB server to an online TiDB server.
+2. Label-based load balancing: TiProxy prioritizes routing requests to TiDB servers that share the same label as the TiProxy instance, enabling resource isolation at the computing layer.
+3. Health-based load balancing: when the health of a TiDB server is abnormal, TiProxy migrates connections from that TiDB server to a healthy TiDB server.
+4. Memory-based load balancing: when a TiDB server is at risk of running out of memory (OOM), TiProxy migrates connections from that TiDB server to a TiDB server with lower memory usage.
+5. CPU-based load balancing: when the CPU usage of a TiDB server is much higher than that of other TiDB servers, TiProxy migrates connections from that TiDB server to a TiDB server with lower CPU usage.
+6. Location-based load balancing: TiProxy prioritizes routing requests to the TiDB server geographically closest to TiProxy.
+7. Connection count-based load balancing: when the connection count of a TiDB server is much higher than that of other TiDB servers, TiProxy migrates connections from that TiDB server to a TiDB server with fewer connections.
+
+To adjust the priorities of load balancing policies, see [Configure load balancing policies](#configure-load-balancing-policies).
+
+## Status-based load balancing
+
+TiProxy periodically checks whether a TiDB server is offline or shutting down using the SQL port and status port.
+
+## Label-based load balancing
+
+Label-based load balancing prioritizes routing connections to TiDB servers that share the same label as TiProxy, enabling resource isolation at the computing layer. This policy is disabled by default and should only be enabled when your workload requires computing resource isolation.
+
+To enable label-based load balancing, you need to:
+
+- Specify the matching label name through [`balance.label-name`](/tiproxy/tiproxy-configuration.md#label-name).
+- Configure the [`labels`](/tiproxy/tiproxy-configuration.md#labels) configuration item in TiProxy.
+- Configure the [`labels`](/tidb-configuration-file.md#labels) configuration item in TiDB servers.
+
+After configuration, TiProxy uses the label name specified in `balance.label-name` to route connections to TiDB servers with matching label values.
+
+Consider an application that handles both transaction and BI workloads. To prevent these workloads from interfering with each other, configure your cluster as follows:
+
+1. Set [`balance.label-name`](/tiproxy/tiproxy-configuration.md#label-name) to `"app"` in TiProxy, indicating that TiDB servers will be matched by the label name `"app"`, and connections will be routed to TiDB servers with matching label values.
+2. Configure two TiProxy instances, adding `"app"="Order"` and `"app"="BI"` to their respective [`labels`](/tiproxy/tiproxy-configuration.md#labels) configuration items.
+3. Divide TiDB instances into two groups, adding `"app"="Order"` and `"app"="BI"` to their respective [`labels`](/tidb-configuration-file.md#labels) configuration items.
+4. Optional: For storage layer isolation, configure [Placement Rules](/configure-placement-rules.md) or [Resource Control](/tidb-resource-control-ru-groups.md).
+5. Direct transaction and BI clients to connect to their respective TiProxy instance addresses.
+
+<img src="https://docs-download.pingcap.com/media/images/docs/tiproxy/tiproxy-balance-label.png" alt="Label-based Load Balancing" width="600" />
+
+Example configuration for this topology:
+
+```yaml
+component_versions:
+  tiproxy: "v1.1.0"
+server_configs:
+  tiproxy:
+    balance.label-name: "app"
+  tidb:
+    graceful-wait-before-shutdown: 15
+tiproxy_servers:
+  - host: tiproxy-host-1
+    config:
+      labels: {app: "Order"}
+  - host: tiproxy-host-2
+    config:
+      labels: {app: "BI"}
+tidb_servers:
+  - host: tidb-host-1
+    config:
+      labels: {app: "Order"}
+  - host: tidb-host-2
+    config:
+      labels: {app: "Order"}
+  - host: tidb-host-3
+    config:
+      labels: {app: "BI"}
+  - host: tidb-host-4
+    config:
+      labels: {app: "BI"}
+tikv_servers:
+  - host: tikv-host-1
+  - host: tikv-host-2
+  - host: tikv-host-3
+pd_servers:
+  - host: pd-host-1
+  - host: pd-host-2
+  - host: pd-host-3
+```
+
+## Health-based load balancing
+
+TiProxy determines the health of a TiDB server by querying its error count. When the health of a TiDB server is abnormal while others are normal, TiProxy migrates connections from that server to a healthy TiDB server, achieving automatic failover.
+
+This policy is suitable for the following scenarios:
+
+- A TiDB server frequently fails to send requests to TiKV, causing frequent SQL execution failures.
+- A TiDB server frequently fails to send requests to PD, causing frequent SQL execution failures.
+
+## Memory-based load balancing
+
+TiProxy queries the memory usage of TiDB servers. When the memory usage of a TiDB server is rapidly increasing or reaching a high level, TiProxy migrates connections from that server to a TiDB server with lower memory usage, preventing unnecessary connection termination due to OOM. TiProxy does not guarantee identical memory usage across TiDB servers. This policy only takes effect when a TiDB server is at risk of OOM.
+
+When a TiDB server is at risk of OOM, TiProxy attempts to migrate all connections from it. Usually, if OOM is caused by runaway queries, ongoing runaway queries will not be migrated to another TiDB server for re-execution, because these connections can only be migrated after the transaction is complete.
+
+This policy has the following limitations:
+
+- If the memory usage of a TiDB server grows too quickly and reaches OOM within 30 seconds, TiProxy might not be able to detect the OOM risk in time, potentially leading to connection termination.
+- TiProxy aims to maintain client connections without termination, not to reduce the memory usage of TiDB servers to avoid OOM. Therefore, TiDB servers might still encounter OOM.
+- This policy applies only to TiDB server v8.0.0 and later versions. For earlier versions of TiDB servers, this policy does not take effect.
+
+## CPU-based load balancing
+
+TiProxy queries the CPU usage of TiDB servers and migrates connections from a TiDB server with high CPU usage to a server with lower usage, reducing overall query latency. TiProxy does not guarantee identical CPU usage across TiDB servers but ensures that the CPU usage differences are minimized.
+
+This policy is suitable for the following scenarios:
+
+- When background tasks (such as `ANALYZE`) consume a significant amount of CPU resources, the TiDB servers executing these tasks have higher CPU usage.
+- When workloads on different connections vary greatly, even if the connection count on each TiDB server is similar, the CPU usage might differ significantly.
+- When TiDB servers in the cluster have different CPU resource configurations, even with balanced connection counts, the actual CPU usage might be imbalanced.
+
+## Location-based load balancing
+
+TiProxy prioritizes routing connections to geographically closer TiDB servers based on the locations of TiProxy and TiDB servers.
+
+This policy is suitable for the following scenarios:
+
+- When a TiDB cluster is deployed across availability zones in the cloud, to reduce cross-availability zone traffic costs between TiProxy and TiDB servers, TiProxy prioritizes routing requests to TiDB servers in the same availability zone.
+- When a TiDB cluster is deployed across data centers, to reduce network latency between TiProxy and TiDB servers, TiProxy prioritizes routing requests to TiDB servers in the same data center.
+
+By default, this policy has a lower priority than health-based, memory-based, and CPU-based load balancing policies. You can increase its priority by setting [`policy`](/tiproxy/tiproxy-configuration.md#policy) to `location`. To maintain availability and performance, it is recommended to ensure that at least three TiDB servers are in the same location.
+
+TiProxy determines the locations of itself and TiDB servers based on the `zone` label. You need to set the following configuration items:
+
+- In the [`labels`](/tidb-configuration-file.md#labels) configuration item of the TiDB server, set `zone` to the current availability zone. For configuration details, see [Configure labels for TiDB](/schedule-replicas-by-topology-labels.md#optional-configure-labels-for-tidb).
+- In the [`labels`](/tiproxy/tiproxy-configuration.md#labels) configuration item of TiProxy, set `zone` to the current availability zone.
+
+For clusters deployed using TiDB Operator, see [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/stable/configure-a-tidb-cluster#high-availability-of-data).
+
+The following is an example of a cluster configuration:
+
+```yaml
+component_versions:
+  tiproxy: "v1.1.0"
+server_configs:
+  tidb:
+    graceful-wait-before-shutdown: 15
+tiproxy_servers:
+  - host: tiproxy-host-1
+    config:
+      labels:
+        zone: east
+  - host: tiproxy-host-2
+    config:
+      labels:
+        zone: west
+tidb_servers:
+  - host: tidb-host-1
+    config:
+      labels:
+        zone: east
+  - host: tidb-host-2
+    config:
+      labels:
+        zone: west
+tikv_servers:
+  - host: tikv-host-1
+  - host: tikv-host-2
+  - host: tikv-host-3
+pd_servers:
+  - host: pd-host-1
+  - host: pd-host-2
+  - host: pd-host-3
+```
+
+In the preceding configuration, the TiProxy instance on `tiproxy-host-1` prioritizes routing requests to the TiDB server on `tidb-host-1` because `tiproxy-host-1` has the same `zone` configuration as `tidb-host-1`. Similarly, the TiProxy instance on `tiproxy-host-2` prioritizes routing requests to the TiDB server on `tidb-host-2`.
+
+## Connection count-based load balancing
+
+TiProxy migrates connections from a TiDB server with more connections to a server with fewer connections. This policy is not configurable and has the lowest priority.
+
+Typically, TiProxy identifies the load on TiDB servers based on CPU usage. This policy usually takes effect in the following scenarios:
+
+- When the TiDB cluster is just starting up, the CPU usage of all TiDB servers is close to 0. In this case, this policy prevents imbalanced load during startup.
+- When the [CPU-based load balancing](#cpu-based-load-balancing) is not enabled, this policy ensures load balancing.
+
+## Configure load balancing policies
+
+TiProxy lets you configure the combination and priority of load balancing policies through the [`policy`](/tiproxy/tiproxy-configuration.md#policy) configuration item.
+
+- `resource`: the resource priority policy performs load balancing based on the following priority order: status, label, health, memory, CPU, location, and connection count.
+- `location`: the location priority policy performs load balancing based on the following priority order: status, label, location, health, memory, CPU, and connection count.
+- `connection`: the minimum connection count policy performs load balancing based on the following priority order: status, label, and connection count.
+
+## More resources
+
+For more information about the load balancing policies of TiProxy, see the [design document](https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-02-01-multi-factor-based-balance.md).
diff --git a/tiproxy/tiproxy-overview.md b/tiproxy/tiproxy-overview.md
new file mode 100644
index 0000000000000..830b08187d24c
--- /dev/null
+++ b/tiproxy/tiproxy-overview.md
@@ -0,0 +1,234 @@
+---
+title: TiProxy Overview
+summary: Learn the main features, installation, and usage of TiProxy.
+---
+
+# TiProxy Overview
+
+TiProxy is the official proxy component of PingCAP. It is placed between the client and the TiDB server to provide load balancing, connection persistence, service discovery, and other features for TiDB.
+
+TiProxy is an optional component. You can also use a third-party proxy component or connect directly to the TiDB server without using a proxy.
+
+The following figure shows the architecture of TiProxy:
+
+<img src="https://docs-download.pingcap.com/media/images/docs/tiproxy/tiproxy-architecture.png" alt="TiProxy architecture" width="500" />
+
+## Main features
+
+TiProxy provides connection migration, failover, service discovery, and quick deployment.
+
+### Connection migration
+
+TiProxy can migrate connections from one TiDB server to another without breaking the client connection.
+
+As shown in the following figure, the client originally connects to TiDB 1 through TiProxy. After the connection migration, the client actually connects to TiDB 2. When TiDB 1 is about to be offline or the ratio of connections on TiDB 1 to connections on TiDB 2 exceeds the set threshold, the connection migration is triggered. The client is unaware of the connection migration.
+
+<img src="https://docs-download.pingcap.com/media/images/docs/tiproxy/tiproxy-session-migration.png" alt="TiProxy connection migration" width="400" />
+
+Connection migration usually occurs in the following scenarios:
+
+- When a TiDB server performs scaling in, rolling upgrade, or rolling restart, TiProxy can migrate connections from the TiDB server that is about to be offline to other TiDB servers to keep the client connection alive.
+- When a TiDB server performs scaling out, TiProxy can migrate existing connections to the new TiDB server to achieve real-time load balancing without resetting the client connection pool.
+
+### Failover
+
+When a TiDB server is at risk of running out of memory (OOM) or fails to connect to PD or TiKV, TiProxy detects the issue automatically and migrates the connections to another TiDB server, thus ensuring continuous client connectivity.
+
+### Service discovery
+
+When a TiDB server performs scaling in or scaling out, if you use a common load balancer, you need to manually update the TiDB server list. However, TiProxy can automatically discover the TiDB server list without manual intervention.
+
+### Quick deployment
+
+TiProxy is integrated into [TiUP](https://github.com/pingcap/tiup), [TiDB Operator](https://github.com/pingcap/tidb-operator), [TiDB Dashboard](/dashboard/dashboard-intro.md), and [Grafana](/tiproxy/tiproxy-grafana.md), and supports built-in virtual IP management, reducing the deployment, operation, and management costs.
+
+## User scenarios
+
+TiProxy is suitable for the following scenarios:
+
+- Connection persistence: When a TiDB server performs scaling in, rolling upgrade, or rolling restart, the client connection is broken, resulting in an error. If the client does not have an idempotent error retry mechanism, you need to manually check and fix the error, which greatly increases the labor cost. TiProxy can keep the client connection, so that the client does not report an error.
+- Frequent scaling in and scaling out: The workload of an application might change periodically. To save costs, you can deploy TiDB on the cloud and automatically scale in and scale out TiDB servers according to the workload. However, scaling in might cause the client to disconnect, and scaling out might result in unbalanced load. TiProxy can keep the client connection and achieve load balancing.
+- CPU load imbalance: When background tasks consume a significant amount of CPU resources or workloads across connections vary significantly, leading to an imbalanced CPU load, TiProxy can migrate connections based on CPU usage to achieve load balancing. For more details, see [CPU-based load balancing](/tiproxy/tiproxy-load-balance.md#cpu-based-load-balancing).
+- TiDB server OOM: When a runaway query causes a TiDB server to run out of memory, TiProxy can proactively detect the OOM risk and migrate other healthy connections to a different TiDB server, thus ensuring continuous client connectivity. For more details, see [Memory-based load balancing](/tiproxy/tiproxy-load-balance.md#memory-based-load-balancing).
+
+TiProxy is not suitable for the following scenarios:
+
+- Sensitive to performance: The performance of TiProxy is lower than that of HAProxy and other load balancers, so using TiProxy will reduce the QPS. For details, refer to [TiProxy Performance Test Report](/tiproxy/tiproxy-performance-test.md).
+- Sensitive to cost: If the TiDB cluster uses hardware load balancers, virtual IP, or the load balancer provided by Kubernetes, adding TiProxy will increase the cost. In addition, if you deploy the TiDB cluster across availability zones on the cloud, adding TiProxy will also increase the traffic cost across availability zones.
+- Failover for unexpected TiDB server downtime: TiProxy can keep the client connection only when the TiDB server is offline or restarted as planned. If the TiDB server is offline unexpectedly, the connection is still broken.
+
+It is recommended that you use TiProxy for the scenarios that TiProxy is suitable for and use HAProxy or other proxies when your application is sensitive to performance.
+
+## Installation and usage
+
+This section describes how to deploy and change TiProxy using TiUP.
+
+For other deployment methods, refer to the following documents:
+
+- To deploy TiProxy using TiDB Operator, see the [TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/deploy-tiproxy) documentation.
+- To quickly deploy TiProxy locally using TiUP, see [Deploy TiProxy](/tiup/tiup-playground.md#deploy-tiproxy).
+
+### Deploy TiProxy
+
+1. Before TiUP v1.15.0, you need to manually generate a self-signed certificate.
+
+    Generate a self-signed certificate for the TiDB instance and place the certificate on all TiDB instances to ensure that all TiDB instances have the same certificate. For detailed steps, see [Generate self-signed certificates](/generate-self-signed-certificates.md).
+
+2. Configure the TiDB instances.
+
+    When using TiProxy, you also need to configure the following items for the TiDB instances:
+
+    - Before TiUP v1.15.0, configure the [`security.session-token-signing-cert`](/tidb-configuration-file.md#session-token-signing-cert-new-in-v640) and [`security.session-token-signing-key`](/tidb-configuration-file.md#session-token-signing-key-new-in-v640) of TiDB instances to the path of the certificate. Otherwise, the connection cannot be migrated.
+    - Configure the [`graceful-wait-before-shutdown`](/tidb-configuration-file.md#graceful-wait-before-shutdown-new-in-v50) of TiDB instances to a value greater than the longest transaction duration of the application. Otherwise, the client might disconnect when the TiDB server is offline. You can view the transaction duration through the [Transaction metrics on the TiDB monitoring dashboard](/grafana-tidb-dashboard.md#transaction). For details, see [TiProxy usage limitations](#limitations).
+
+    A configuration example is as follows:
+
+    ```yaml
+    server_configs:
+      tidb:
+        security.session-token-signing-cert: "/var/sess/cert.pem"
+        security.session-token-signing-key: "/var/sess/key.pem"
+        graceful-wait-before-shutdown: 15
+    ```
+
+3. Define the TiProxy instances.
+
+    When selecting the model and number of TiProxy instances, consider the following factors:
+
+    - For the workload type and maximum QPS, see [TiProxy Performance Test Report](/tiproxy/tiproxy-performance-test.md).
+    - Because the number of TiProxy instances is less than that of TiDB servers, the network bandwidth of TiProxy is more likely to become a bottleneck than that of TiDB servers. Therefore, you also need to consider the network bandwidth. For example, in AWS, the baseline network bandwidth of the same series of EC2 is not proportional to the number of CPU cores. For details, see [Network performance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/compute-optimized-instances.html#compute-network-performance). In such cases, when the network bandwidth becomes a bottleneck, splitting the TiProxy instance into more and smaller instances can improve QPS.
+
+    It is recommended to specify the version number of TiProxy in the topology configuration so that TiProxy will not be upgraded when you upgrade the TiDB cluster through [`tiup cluster upgrade`](/tiup/tiup-component-cluster-upgrade.md). Otherwise, the client connection might be disconnected during TiProxy upgrade.
+
+    For more information about the template for TiProxy, see [A simple template for the TiProxy topology](https://github.com/pingcap/docs/blob/master/config-templates/simple-tiproxy.yaml).
+
+    For detailed descriptions of the configuration items in the TiDB cluster topology file, see [Topology Configuration File for TiDB Deployment Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
+    A configuration example is as follows:
+
+    ```yaml
+    component_versions:
+      tiproxy: "v1.2.0"
+    tiproxy_servers:
+      - host: 10.0.1.11
+        port: 6000
+        status_port: 3080
+      - host: 10.0.1.12
+        port: 6000
+        status_port: 3080
+    ```
+
+4. Configure the TiProxy instances.
+
+    To ensure the high availability of TiProxy, it is recommended to deploy at least two TiProxy instances and configure a virtual IP by setting [`ha.virtual-ip`](/tiproxy/tiproxy-configuration.md#virtual-ip) and [`ha.interface`](/tiproxy/tiproxy-configuration.md#interface) to route the traffic to the available TiProxy instance.
+
+    To configure TiProxy configuration items, see [TiProxy Configuration File](/tiproxy/tiproxy-configuration.md). For more configurations of TiUP deployment topology, see [tiproxy-servers configurations](/tiup/tiup-cluster-topology-reference.md#tiproxy_servers).
+
+    A configuration example is as follows:
+
+    ```yaml
+    server_configs:
+      tiproxy:
+        ha.virtual-ip: "10.0.1.10/24"
+        ha.interface: "eth0"
+    ```
+
+5. Start the cluster.
+
+    To start the cluster using TiUP, see [TiUP documentation](/tiup/tiup-documentation-guide.md).
+
+6. Connect to TiProxy.
+
+    After the cluster is deployed, the cluster exposes the ports of TiDB server and TiProxy at the same time. The client should connect to the port of TiProxy instead of the port of TiDB server.
+
+### Modify TiProxy configuration
+
+To ensure that TiProxy keeps the client connection, do not restart TiProxy unless necessary. Therefore, most of the TiProxy configuration items can be modified online. For the list of configuration items that support online change, see [TiProxy configuration](/tiproxy/tiproxy-configuration.md).
+
+When using TiUP to change the TiProxy configuration, if the configuration item to be changed supports online change, you can use the [`--skip-restart`](/tiup/tiup-component-cluster-reload.md#--skip-restart) option to avoid restarting TiProxy.
+
+### Upgrade TiProxy
+
+When you deploy TiProxy, it is recommended to specify the version of TiProxy so that TiProxy will not be upgraded when you upgrade the TiDB cluster.
+
+If you need to upgrade TiProxy, add [`--tiproxy-version`](/tiup/tiup-component-cluster-upgrade.md#--tiproxy-version) in the upgrade command to specify the version of TiProxy:
+
+```shell
+tiup cluster upgrade <cluster-name> <version> --tiproxy-version <tiproxy-version>
+```
+
+### Restart the TiDB cluster
+
+When you restart the TiDB cluster using [`tiup cluster restart`](/tiup/tiup-component-cluster-restart.md), TiDB servers are not rolling restarted, which causes the client connection to be disconnected. Therefore, avoid using this command.
+
+Instead, when you upgrade the cluster using [`tiup cluster upgrade`](/tiup/tiup-component-cluster-upgrade.md) or reload the configuration using [`tiup cluster reload`](/tiup/tiup-component-cluster-reload.md), TiDB servers are rolling restarted, so the client connection is not affected.
+
+## Compatibility with other components
+
+- TiProxy only supports TiDB v6.5.0 and later versions.
+- TiProxy's TLS connection has incompatible features with TiDB. For details, see [Security](#security).
+- TiDB Dashboard and Grafana support TiProxy from v7.6.0.
+- TiUP supports TiProxy from v1.14.1, and TiDB Operator supports TiProxy from v1.5.1.
+- Because the interface provided by the status port of TiProxy is different from that of TiDB server, when you use [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) to import data, the target database should be the address of TiDB server, not the address of TiProxy.
+
+## Security
+
+TiProxy provides TLS connections. The TLS connection between the client and TiProxy is enabled according to the following rules:
+
+- If the [`security.server-tls`](/tiproxy/tiproxy-configuration.md#server-tls) configuration of TiProxy is set to not use TLS connection, the TLS connection between the client and TiProxy is not enabled regardless of whether the client enables TLS connection.
+- If the [`security.server-tls`](/tiproxy/tiproxy-configuration.md#server-tls) configuration of TiProxy is set to use TLS connection, the TLS connection between the client and TiProxy is enabled only when the client enables TLS connection.
+
+The TLS connection between TiProxy and TiDB server is enabled according to the following rules:
+
+- If TiProxy's [`security.require-backend-tls`](/tiproxy/tiproxy-configuration.md#require-backend-tls) is set to `true`, TiProxy and TiDB server always enable TLS connection regardless of whether the client enables TLS connection. If TiProxy's [`security.sql-tls`](/tiproxy/tiproxy-configuration.md#sql-tls) is set to not use TLS or TiDB server does not configure TLS certificate, the client reports an error.
+- If TiProxy's [`security.require-backend-tls`](/tiproxy/tiproxy-configuration.md#require-backend-tls) is set to `false`, TiProxy's [`security.sql-tls`](/tiproxy/tiproxy-configuration.md#sql-tls) is configured with TLS and TiDB server is configured with a TLS certificate, TiProxy and TiDB server only enable TLS connection when the client enables TLS connection.
+- If TiProxy's [`security.require-backend-tls`](/tiproxy/tiproxy-configuration.md#require-backend-tls) is set to `false`, TiProxy's [`security.sql-tls`](/tiproxy/tiproxy-configuration.md#sql-tls) is set to not use TLS or TiDB server does not configure a TLS certificate, TiProxy and TiDB server do not enable TLS connection.
+
+TiProxy has the following behaviors incompatible with TiDB:
+
+- The `STATUS` and `SHOW STATUS` statements might return different TLS information. The `STATUS` statement returns the TLS information between the client and TiProxy, while the `SHOW STATUS` statement returns the TLS information between TiProxy and TiDB server.
+- TiProxy does not support [certificate-based authentication](/certificate-authentication.md). Otherwise, the client might fail to log in because the TLS certificate between the client and TiProxy is different from that between TiProxy and TiDB server, and TiDB server verifies the TLS certificate based on the TLS certificate on TiProxy.
+
+## Limitations
+
+TiProxy cannot keep the client connection in the following scenarios:
+
+- TiDB is offline unexpectedly. TiProxy only keeps the client connection when the TiDB server is offline or restarted as planned, and does not support failover of the TiDB server.
+- TiProxy performs scaling in, upgrade, or restart. Once TiProxy is offline, the client connection is broken.
+- TiDB actively disconnects the connection. For example, when a session does not send a request for a period of time longer than `wait_timeout`, TiDB actively disconnects the connection, and TiProxy also disconnects the client connection.
+
+TiProxy cannot migrate connections in the following scenarios, and thus cannot keep the client connection or achieve load balancing:
+
+- The duration of a single statement or a single transaction exceeds the [`graceful-wait-before-shutdown`](/tidb-configuration-file.md#graceful-wait-before-shutdown-new-in-v50) configured on the TiDB server.
+- The session uses the cursor to read data, and the cursor is not closed or the data is not read within the [`graceful-wait-before-shutdown`](/tidb-configuration-file.md#graceful-wait-before-shutdown-new-in-v50) configured on the TiDB server.
+- The session creates a [local temporary table](/temporary-tables.md#local-temporary-tables).
+- The session holds a [user-level lock](/functions-and-operators/locking-functions.md).
+- The session holds a [table lock](/sql-statements/sql-statement-lock-tables-and-unlock-tables.md).
+- The session creates a [prepared statement](/develop/dev-guide-prepared-statement.md), and the prepared statement is invalid. For example, the table related to the prepared statement is dropped after the prepared statement is created.
+- The session creates a session-level [execution plan binding](/sql-plan-management.md#sql-binding), and the binding is invalid. For example, the table related to the binding is dropped after the binding is created.
+- After the session is created, the user used by the session is deleted or the username is changed.
+
+## Supported connectors
+
+TiProxy requires that the connector used by the client supports [authentication plugins](https://dev.mysql.com/doc/refman/8.0/en/pluggable-authentication.html). Otherwise, the connection might fail.
+
+The following table lists some supported connectors:
+
+| Language   | Connector              | The minimum supported version |
+|------------|------------------------|------------------------------|
+| Java       | MySQL Connector/J      | 5.1.19                       |
+| C          | libmysqlclient         | 5.5.7                        |
+| Go         | Go SQL Driver          | 1.4.0                        |
+| JavaScript | MySQL Connector/Node.js | 1.0.2                        |
+| JavaScript | mysqljs/mysql          | 2.15.0                       |
+| JavaScript | node-mysql2            | 1.0.0-rc-6                   |
+| PHP        | mysqlnd                | 5.4                          |
+| Python     | MySQL Connector/Python | 1.0.7                        |
+| Python     | PyMySQL                | 0.7                          |
+
+Note that some connectors call the common library to connect to the database, and these connectors are not listed in the table. You can refer to the above table for the required version of the corresponding library. For example, MySQL/Ruby uses libmysqlclient to connect to the database, so it requires that the libmysqlclient used by MySQL/Ruby is version 5.5.7 or later.
+
+## TiProxy resources
+
+- [TiProxy Release Notes](https://github.com/pingcap/tiproxy/releases)
+- [TiProxy Issues](https://github.com/pingcap/tiproxy/issues): Lists TiProxy GitHub issues
diff --git a/tiproxy/tiproxy-traffic-replay.md b/tiproxy/tiproxy-traffic-replay.md
new file mode 100644
index 0000000000000..1a0e93d494b56
--- /dev/null
+++ b/tiproxy/tiproxy-traffic-replay.md
@@ -0,0 +1,193 @@
+---
+title: TiProxy Traffic Replay
+summary: Introduce the use cases and steps for the TiProxy traffic replay feature.
+---
+
+# TiProxy Traffic Replay
+
+> **Warning:**
+>
+> Currently, the TiProxy traffic replay feature is experimental. It is not recommended that you use it in production environments. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tiproxy/issues) on GitHub.
+
+Starting from TiProxy v1.3.0, you can use TiProxy to capture access traffic in a TiDB production cluster and replay it in a test cluster at a specified rate. This feature enables you to reproduce actual workloads from the production cluster in a test environment, verifying SQL statement execution results and performance.
+
+<img src="https://docs-download.pingcap.com/media/images/docs/tiproxy/tiproxy-traffic-replay.png" alt="TiProxy traffic replay" width="800" />
+
+## Use cases
+
+Traffic replay is suitable for the following scenarios:
+
+- **Verify TiDB version upgrades**: Replay production traffic on a test cluster with a new TiDB version to verify that the new TiDB version can successfully execute all SQL statements.
+- **Assess change impact**: Simulate production traffic on a test cluster to verify the impact of changes on the cluster. For example, verify the effects before modifying configuration items or system variables, altering table schemas, or enabling new TiDB features.
+- **Validate performance before TiDB scaling**: Replay traffic at corresponding rates on a test cluster with a new scale to validate whether the performance meets requirements. For example, to plan a 50% cluster downscale for cost savings, replay traffic at half speed to validate if SQL latency meets requirements after scaling.
+- **Test performance limits**: Replay traffic multiple times on a test cluster of the same scale, increasing the replay rate each time to test the throughput limit of that scale and assess whether performance meets future business growth needs.
+
+Traffic replay is not suitable for the following scenarios:
+
+- Verify SQL compatibility between TiDB and MySQL: TiProxy only supports reading traffic files it generates and cannot capture traffic from MySQL for replay on TiDB.
+- Compare SQL execution results between TiDB versions: TiProxy only verifies if SQL statements execute successfully but does not compare results.
+
+## Usage
+
+1. Prepare the test environment:
+
+    1. Create a test cluster. For more information, see [Deploy a TiDB Cluster Using TiUP](/production-deployment-using-tiup.md).
+    2. Install `tiproxyctl` and ensure the host with `tiproxyctl` can connect to TiProxy instances in both production and test clusters. For more information, see [Install TiProxy Control](/tiproxy/tiproxy-command-line-flags.md#install-tiproxy-control).
+    3. Replicate data from the production cluster to the test cluster. For more information, see [Data Migration Overview](/migration-overview.md).
+    4. Run the [`ANALYZE`](/sql-statements/sql-statement-analyze-table.md) statement in the test cluster to update statistics.
+
+2. Use the [`tiproxyctl traffic capture`](/tiproxy/tiproxy-command-line-flags.md#traffic-capture) command to connect to the production cluster's TiProxy instance and start capturing traffic.
+
+    > **Note:**
+    >
+    > - TiProxy captures traffic on all connections, including existing and newly created ones.
+    > - In TiProxy primary-secondary mode, connect to the primary TiProxy instance.
+    > - If TiProxy is configured with a virtual IP, it is recommended to connect to the virtual IP address.
+    > - The higher the CPU usage of TiProxy, the greater the impact of traffic capture on QPS. To reduce the impact on the production cluster, it is recommended to reserve at least 30% of CPU capacity, which results in an approximately 3% decrease in average QPS. For detailed performance data, see [Traffic capture test](/tiproxy/tiproxy-performance-test.md#traffic-capture-test).
+    > - TiProxy does not automatically delete previous capture files when capturing traffic again. You need to manually delete them.
+
+    For example, the following command connects to the TiProxy instance at `10.0.1.10:3080`, captures traffic for one hour, and saves it to the `/tmp/traffic` directory on the TiProxy instance:
+
+    ```shell
+    tiproxyctl traffic capture --host 10.0.1.10 --port 3080 --output="/tmp/traffic" --duration=1h
+    ```
+
+    Traffic files are automatically rotated and compressed. Example files in the `/tmp/traffic` directory:
+
+    ```shell
+    ls /tmp/traffic
+    # meta    traffic-2024-08-29T17-37-12.477.log.gz  traffic-2024-08-29T17-43-11.166.log.gz traffic.log
+    ```
+
+    For more information, see [`tiproxyctl traffic capture`](/tiproxy/tiproxy-command-line-flags.md#traffic-capture).
+
+3. Copy the traffic file directory to the test cluster's TiProxy instance.
+4. Use [`tiproxyctl traffic replay`](/tiproxy/tiproxy-command-line-flags.md#traffic-replay) to connect to the test cluster's TiProxy instance and start replaying traffic.
+
+    By default, SQL statements are executed at the same rate as in the production cluster, and each database connection corresponds to a connection in the production cluster to simulate the production load and ensure consistent transaction execution order.
+
+    For example, the following command connects to the TiProxy instance at `10.0.1.10:3080` using username `u1` and password `123456`, reads traffic files from the `/tmp/traffic` directory on the TiProxy instance, and replays the traffic:
+
+    ```shell
+    tiproxyctl traffic replay --host 10.0.1.10 --port 3080 --username="u1" --password="123456" --input="/tmp/traffic"
+    ```
+
+    Because all traffic runs under user `u1`, ensure `u1` can access all databases and tables. If no such user exists, create one.
+
+    For more information, see [`tiproxyctl traffic replay`](/tiproxy/tiproxy-command-line-flags.md#traffic-replay).
+
+5. View the replay report.
+
+    After replay completion, the report is stored in the `tiproxy_traffic_replay` database on the test cluster. This database contains two tables: `fail` and `other_errors`.
+
+    The `fail` table stores failed SQL statements, with the following fields:
+
+    - `cmd_type`: the type of a failed command, such as `Query` (execute an ordinary statement), `Prepare` (prepare a statement), and `Execute` (execute a prepared statement).
+    - `digest`: the digest of the failed SQL statement.
+    - `sample_stmt`: the SQL text when the statement first failed.
+    - `sample_err_msg`: the error message when the SQL statement failed.
+    - `sample_conn_id`: the connection ID recorded in the traffic file for the SQL statement. You can use this to view the execution context in the traffic file.
+    - `sample_capture_time`: the execution time recorded in the traffic file for the SQL statement. You can use this to view the execution context in the traffic file.
+    - `sample_replay_time`: the time when the SQL statement failed during replay. You can use this to view error information in the TiDB log file.
+    - `count`: the number of times the SQL statement failed.
+
+    The following is an example output of the `fail` table:
+
+    ```sql
+    SELECT * FROM tiproxy_traffic_replay.fail LIMIT 1\G
+    ```
+
+    ```
+    *************************** 1. row ***************************
+               cmd_type: StmtExecute
+                 digest: 89c5c505772b8b7e8d5d1eb49f4d47ed914daa2663ed24a85f762daa3cdff43c
+            sample_stmt: INSERT INTO new_order (no_o_id, no_d_id, no_w_id) VALUES (?, ?, ?) params=[3077 6 1]
+         sample_err_msg: ERROR 1062 (23000): Duplicate entry '1-6-3077' for key 'new_order.PRIMARY'
+         sample_conn_id: 1356
+    sample_capture_time: 2024-10-17 12:59:15
+     sample_replay_time: 2024-10-17 13:05:05
+                  count: 4
+    ```
+
+    The `other_errors` table stores unexpected errors, such as network errors or database connection errors, with the following fields:
+
+    - `err_type`: the type of error, presented as a brief error message. For example, `i/o timeout`.
+    - `sample_err_msg`: the complete error message when the error first occurred.
+    - `sample_replay_time`: the time when the error occurred during replay. You can use this to view error information in the TiDB log file.
+    - `count`: the number of occurrences for this error.
+
+    The following is an example output of the `other_errors` table:
+
+    ```sql
+    SELECT * FROM tiproxy_traffic_replay.other_errors LIMIT 1\G
+    ```
+
+    ```
+    *************************** 1. row ***************************
+              err_type: failed to read the connection: EOF
+        sample_err_msg: this is an error from the backend connection: failed to read the connection: EOF
+    sample_replay_time: 2024-10-17 12:57:39
+                 count: 1
+    ```
+
+    > **Note:**
+    >
+    > - The table schema of `tiproxy_traffic_replay` might change in future versions. It is not recommended to directly read data from `tiproxy_traffic_replay` in your application or tool development.
+    > - Replay does not guarantee that the transaction execution order between connections exactly matches the capture sequence. This might lead to incorrect error reports.
+    > - TiProxy does not automatically delete the previous replay report when replaying traffic. You need to manually delete it.
+
+## Test throughput
+
+To test cluster throughput, use the `--speed` option to adjust the replay rate.
+
+For example, `--speed=2` executes SQL statements at twice the rate, reducing the total replay time by half:
+
+```shell
+tiproxyctl traffic replay --host 10.0.1.10 --port 3080 --username="u1" --password="123456" --input="/tmp/traffic" --speed=2
+```
+
+Increasing the replay rate only reduces idle time between SQL statements and does not increase the number of connections. When session idle time is already short, increasing the speed might not effectively improve throughput. In such cases, you can deploy multiple TiProxy instances to replay the same traffic files simultaneously, increasing concurrency to improve throughput.
+
+## View and manage tasks
+
+During capture and replay, tasks automatically stop if unknown errors occur. To view the current task progress or error information from the last task, use the [`tiproxyctl traffic show`](/tiproxy/tiproxy-command-line-flags.md#traffic-show) command:
+
+```shell
+tiproxyctl traffic show --host 10.0.1.10 --port 3080
+```
+
+For example, the following output indicates a running capture task:
+
+```json
+[
+   {
+      "type": "capture",
+      "start_time": "2024-09-03T09:10:58.220644+08:00",
+      "duration": "2h",
+      "output": "/tmp/traffic",
+      "progress": "45%",
+      "status": "running"
+   }
+]
+```
+
+For more information, see [`tiproxyctl traffic show`](/tiproxy/tiproxy-command-line-flags.md#traffic-show).
+
+To cancel the current capture or replay task, use the [`tiproxyctl traffic cancel`](/tiproxy/tiproxy-command-line-flags.md#traffic-cancel) command:
+
+```shell
+tiproxyctl traffic cancel --host 10.0.1.10 --port 3080
+```
+
+For more information, see [`tiproxyctl traffic cancel`](/tiproxy/tiproxy-command-line-flags.md#traffic-cancel).
+
+## Limitations
+
+- TiProxy only supports replaying traffic files captured by TiProxy and does not support other file formats. Therefore, make sure to capture traffic from the production cluster using TiProxy first.
+- TiProxy traffic replay does not support filtering SQL types and DML and DDL statements are replayed. Therefore, you need to restore the cluster data to its pre-replay state before replaying again.
+- TiProxy traffic replay does not support testing [Resource Control](/tidb-resource-control-ru-groups.md) and [privilege management](/privilege-management.md) because TiProxy uses the same username to replay traffic.
+- TiProxy does not support replaying [`LOAD DATA`](/sql-statements/sql-statement-load-data.md) statements.
+
+## More resources
+
+For more information about the traffic replay of TiProxy, see the [design document](https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md).
\ No newline at end of file