This is an automated email from the ASF dual-hosted git repository.
tew pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-seata-go.git
The following commit(s) were added to refs/heads/master by this push:
new 39063bb5 docs: add bilingual quick start guides (#1105)
39063bb5 is described below
commit 39063bb528b98741636a410f21cebd1661a4ac15
Author: Cheyne Chen <[email protected]>
AuthorDate: Thu Apr 16 18:47:00 2026 +0800
docs: add bilingual quick start guides (#1105)
docs: add quick start guide
---
README.md | 3 +-
README_ZH.md | 2 +
docs/quickstart.md | 285 ++++++++++++++++++++++++++++++++++++++++++++++++++
docs/quickstart_zh.md | 285 ++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 574 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 31a20500..e1b70b7c 100644
--- a/README.md
+++ b/README.md
@@ -115,8 +115,9 @@ The latest tag / release is the latest stable version.
## Documentation
+[Quick Start](./docs/quickstart.md)
-You can view the full documentation from Seata Official Website: [Seata
Website page](https://seata.apache.org/zh-cn/docs/overview/what-is-seata).
+You can view the full documentation from Seata Official Website: [Seata
Website page](https://seata.apache.org/docs/overview/what-is-seata).
## Reporting bugs
diff --git a/README_ZH.md b/README_ZH.md
index 818cb49f..30acbdae 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -115,6 +115,8 @@ go get seata.apache.org/[email protected]
最新的 tag / release 就是目前的最新稳定版本。
## 文档
+[快速开始](./docs/quickstart_zh.md)
+
你可以访问 Seata 官方网站获取完整文档：[Seata
官网](https://seata.apache.org/zh-cn/docs/overview/what-is-seata)
## 问题报告
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 00000000..8ade97fc
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,285 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Seata-go Quick Start
+
+## Prerequisites
+
+- Go >= 1.20
+- Java >= 8
+- MySQL >= 8.0
+
+### Start Seata Server (Binary)
+
+1. Download the binary distribution from the official [Seata-Server Release
History](https://seata.apache.org/release-history/seata-server/) page and
extract it.
+2. Enter the extracted Seata Server directory.
+3. Start the server with `file` storage mode:
+
+```bash
+sh ./seata-server/bin/seata-server.sh -p 8091 -h 127.0.0.1 -m file
+```
+
+> - `-p 8091`: specifies the Seata Server port.
+> - `-h 127.0.0.1`: specifies the registry or advertised server address.
+> - `-m file`: stores transaction logs in `file` mode, which is suitable for a
local quick start.
+
+4. Confirm that Seata Server is running and listening on `127.0.0.1:8091`.
+
+### Start Seata Server (Docker)
+
+1. Pull the image from the official Docker Hub repository
[`apache/seata-server`](https://hub.docker.com/r/apache/seata-server):
+
+```bash
+docker pull apache/seata-server:<seata-version>
+```
+
+2. Start a container from the image you just pulled:
+
+```bash
+docker run --name seata-server \
+ -p 8091:8091 \
+ -e STORE_MODE=file \
+ apache/seata-server:<seata-version>
+```
+
+> If local Docker has limited available memory and startup fails with `There
is insufficient memory for the Java Runtime Environment to continue` or `Cannot
allocate memory`, you can explicitly lower the JVM heap size, for example:
+>
+> ```bash
+> docker run --name seata-server \
+> -p 8091:8091 \
+> -e STORE_MODE=file \
+> -e JVM_XMS=512m \
+> -e JVM_XMX=512m \
+> apache/seata-server:<seata-version>
+> ```
+>
+> Add `-d` if you want to run it in the background.
+
+3. Check the logs and confirm that the service is ready:
+
+```bash
+docker logs -f seata-server
+```
+
+4. Confirm that the client can reach `127.0.0.1:8091` before continuing.
+
+If you later need to switch Seata Server to Nacos or another registry center,
adjust the Seata Server-side `registry.conf` and `application.yaml`.
+
+If your Seata Server uses Nacos, Seata Server 1.4.x and earlier server-side
configuration is usually written in `registry.conf`, while Seata Server 1.5.0
and later usually uses `application.yaml`. For 1.4.x and earlier, for example:
+
+```hocon
+registry {
+ type = "nacos"
+ nacos {
+ application = "seata-server"
+ serverAddr = "127.0.0.1:8848"
+ group = "SEATA_GROUP"
+ namespace = ""
+ cluster = "default"
+ username = ""
+ password = ""
+ }
+}
+
+config {
+ type = "nacos"
+ nacos {
+ serverAddr = "127.0.0.1:8848"
+ group = "SEATA_GROUP"
+ namespace = ""
+ username = ""
+ password = ""
+ }
+}
+```
+
+> `registry.conf`: official parameter reference and Nacos config-center
example: [Parameter
Configuration](https://seata.apache.org/docs/user/configurations) · [Nacos
Configuration Center](https://seata.apache.org/docs/user/configuration/nacos/)
+
+Seata Server 1.5.0 and later usually uses `application.yaml` as the
server-side configuration file in the Nacos scenario:
+
+```yaml
+seata:
+ registry:
+ type: nacos
+ nacos:
+ application: seata-server
+ server-addr: 127.0.0.1:8848
+ group: SEATA_GROUP
+ namespace: ""
+ cluster: default
+ username: ""
+ password: ""
+ config:
+ type: nacos
+ nacos:
+ server-addr: 127.0.0.1:8848
+ group: SEATA_GROUP
+ namespace: ""
+ data-id: seataServer.properties
+ username: ""
+ password: ""
+```
+
+> `application.yaml`: official parameter reference and Nacos registry example:
[Parameter Configuration](https://seata.apache.org/docs/user/configurations) ·
[Nacos Registry Center](https://seata.apache.org/docs/user/registry/nacos/)
+
+`seatago.yml` is the Seata Go client configuration file in this repository.
Use it to adjust the client-side registry center, transaction group, and server
address. For example:
+
+```yaml
+seata:
+ application-id: quickstart-demo
+ tx-service-group: default_tx_group
+ data-source-proxy-mode: AT
+
+ service:
+ vgroup-mapping:
+ default_tx_group: default
+ grouplist:
+ default: 127.0.0.1:8091
+
+ registry:
+ type: file
+
+ client:
+ tm:
+ default-global-transaction-timeout: 60s
+ rm:
+ lock:
+ retry-interval: 30s
+ retry-times: 10
+ retry-policy-branch-rollback-on-conflict: true
+ undo:
+ log-serialization: json
+ log-table: undo_log
+ only-care-update-columns: true
+
+ tcc:
+ fence:
+ enable: false
+```
+
+References for the configuration structure and a full sample:
+
+- `seatago.yml`: [Config struct](../pkg/client/config.go) · [Full
sample](../testdata/conf/seatago.yml)
+
+## Quick Integration
+
+Install the dependency:
+
+```bash
+go get seata.apache.org/seata-go/v2@latest
+```
+
+Initialize the Seata client:
+
+```go
+package main
+
+import (
+ "context"
+
+ "seata.apache.org/seata-go/v2/pkg/client"
+ "seata.apache.org/seata-go/v2/pkg/tm"
+)
+
+func main() {
+ // Initialize the Seata client
+ client.InitPath("./conf/seatago.yml")
+ // Or set SEATA_GO_CONFIG_PATH=/path/to/your/seatago.yml first, then
call:
+ // client.Init()
+
+ ctx := context.Background()
+
+ // Run business logic in a global transaction
+ err := tm.WithGlobalTx(ctx, &tm.GtxConfig{Name: "my-tx"}, func(ctx
context.Context) error {
+ // Business logic
+ return nil
+ })
+ if err != nil {
+ panic(err)
+ }
+}
+```
+
+## Example Scenarios
+
+### AT Example
+
+AT mode wraps business logic with `tm.WithGlobalTx(...)` and uses the
`seata-at-mysql` driver to intercept database access:
+
+```go
+import (
+ "context"
+ "database/sql"
+
+ "seata.apache.org/seata-go/v2/pkg/tm"
+)
+
+db, err := sql.Open(
+ "seata-at-mysql",
+
"root:password@tcp(127.0.0.1:3306)/seata_demo?charset=utf8mb4&parseTime=True&multiStatements=true",
+)
+if err != nil {
+ return err
+}
+
+ctx := context.Background()
+err = tm.WithGlobalTx(ctx, &tm.GtxConfig{Name: "create-order"}, func(ctx
context.Context) error {
+ _, err := db.ExecContext(ctx,
+ "UPDATE account SET balance = balance - ? WHERE user_id = ?",
+ 100,
+ 1,
+ )
+ return err
+})
+```
+
+Before using AT mode, make sure the business database has already created the
[undo_log](../testdata/sql/undo_log.sql) table.
+
+> Full example: [AT
Example](https://github.com/apache/incubator-seata-go-samples/tree/main/at/basic).
+
+### TCC Example
+
+TCC mode uses `tcc.NewTCCServiceProxy(...)` to register Try/Confirm/Cancel
actions, then chains them with `tm.WithGlobalTx(...)`:
+
+```go
+proxy, err := tcc.NewTCCServiceProxy(&InventoryTCC{})
+if err != nil {
+ return err
+}
+
+return tm.WithGlobalTx(ctx, &tm.GtxConfig{Name: "inventory-tcc"}, func(ctx
context.Context) error {
+ _, err := proxy.Prepare(ctx, ReserveRequest{OrderID: 1001})
+ return err
+})
+```
+
+If you need fence mode, set `seata.tcc.fence.enable: true` in `seatago.yml`
and create the `tcc_fence_log` table.
+
+> Full example: [TCC
Example](https://github.com/apache/incubator-seata-go-samples/tree/main/tcc/local).
+
+### XA Example
+
+The current repository supports MySQL XA. The transaction entrypoint is the
same as AT; you only need to switch the driver to `seata-xa-mysql`:
+
+```go
+db, err := sql.Open(
+ "seata-xa-mysql",
+
"root:password@tcp(127.0.0.1:3306)/seata_demo?charset=utf8mb4&parseTime=True&multiStatements=true",
+)
+```
+
+> Full example: [XA
Example](https://github.com/apache/incubator-seata-go-samples/tree/main/xa/basic).
diff --git a/docs/quickstart_zh.md b/docs/quickstart_zh.md
new file mode 100644
index 00000000..ea0136fb
--- /dev/null
+++ b/docs/quickstart_zh.md
@@ -0,0 +1,285 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Seata-go 快速开始
+
+## 环境准备
+
+- Go >= 1.20
+- Java >= 8
+- MySQL >= 8.0
+
+### 启动 Seata Server（二进制）
+
+1. 从 Seata 官网的 [Seata-Server
版本历史](https://seata.apache.org/zh-cn/release-history/seata-server/)
页面下载二进制发行包并解压。
+2. 进入解压后的 Seata Server 目录。
+3. 使用 `file` 存储模式启动服务：
+
+```bash
+sh ./seata-server/bin/seata-server.sh -p 8091 -h 127.0.0.1 -m file
+```
+
+> - `-p 8091`：指定 Seata Server 端口。
+> - `-h 127.0.0.1`：指定服务注册地址或对外暴露地址。
+> - `-m file`：使用 `file` 模式存储事务日志，适合本地快速开始。
+
+4. 确认 Seata Server 成功启动并监听 `127.0.0.1:8091`。
+
+### 启动 Seata Server（Docker）
+
+1. 从 Docker Hub 官方仓库
[`apache/seata-server`](https://hub.docker.com/r/apache/seata-server) 拉取镜像：
+
+```bash
+docker pull apache/seata-server:<seata-version>
+```
+
+2. 使用刚刚拉取的镜像启动容器：
+
+```bash
+docker run --name seata-server \
+ -p 8091:8091 \
+ -e STORE_MODE=file \
+ apache/seata-server:<seata-version>
+```
+
+> 如果本地 Docker 可用内存较小，启动时出现 `There is insufficient memory for the Java Runtime
Environment to continue` 或 `Cannot allocate memory`，可以显式调低 JVM 堆大小，例如：
+>
+> ```bash
+> docker run --name seata-server \
+> -p 8091:8091 \
+> -e STORE_MODE=file \
+> -e JVM_XMS=512m \
+> -e JVM_XMX=512m \
+> apache/seata-server:<seata-version>
+> ```
+>
+> 如需后台运行，可额外添加 `-d`。
+
+3. 查看启动日志，确认服务已就绪：
+
+```bash
+docker logs -f seata-server
+```
+
+4. 确认客户端可以访问 `127.0.0.1:8091`。
+
+如果后面需要将 Seata Server 切换到 Nacos 或其他注册中心，可对照 Seata Server 侧的 `registry.conf` 与
`application.yaml` 进行修改。
+
+如果你的 Seata Server 使用 Nacos 部署，Seata Server 1.4.x 的服务端配置通常写在 `registry.conf`
中，例如：
+
+```hocon
+registry {
+ type = "nacos"
+ nacos {
+ application = "seata-server"
+ serverAddr = "127.0.0.1:8848"
+ group = "SEATA_GROUP"
+ namespace = ""
+ cluster = "default"
+ username = ""
+ password = ""
+ }
+}
+
+config {
+ type = "nacos"
+ nacos {
+ serverAddr = "127.0.0.1:8848"
+ group = "SEATA_GROUP"
+ namespace = ""
+ username = ""
+ password = ""
+ }
+}
+```
+
+> `registry.conf`：官方参数总表与 Nacos
配置中心示例：[参数配置](https://seata.apache.org/zh-cn/docs/user/configurations) · [Nacos
配置中心](https://seata.apache.org/zh-cn/docs/user/configuration/nacos/)
+
+Seata Server 1.5.0 及以后在 Nacos 场景下通常使用 `application.yaml` 作为服务端配置文件：
+
+```yaml
+seata:
+ registry:
+ type: nacos
+ nacos:
+ application: seata-server
+ server-addr: 127.0.0.1:8848
+ group: SEATA_GROUP
+ namespace: ""
+ cluster: default
+ username: ""
+ password: ""
+ config:
+ type: nacos
+ nacos:
+ server-addr: 127.0.0.1:8848
+ group: SEATA_GROUP
+ namespace: ""
+ data-id: seataServer.properties
+ username: ""
+ password: ""
+```
+
+> `application.yaml`：官方参数总表与 Nacos
注册中心示例：[参数配置](https://seata.apache.org/zh-cn/docs/user/configurations) · [Nacos
注册中心](https://seata.apache.org/zh-cn/docs/user/registry/nacos/)
+
+`seatago.yml` 是当前仓库的 Seata Go 客户端配置文件，用于调整客户端的注册中心、事务分组与服务地址。例如：
+
+```yaml
+seata:
+ application-id: quickstart-demo
+ tx-service-group: default_tx_group
+ data-source-proxy-mode: AT
+
+ service:
+ vgroup-mapping:
+ default_tx_group: default
+ grouplist:
+ default: 127.0.0.1:8091
+
+ registry:
+ type: file
+
+ client:
+ tm:
+ default-global-transaction-timeout: 60s
+ rm:
+ lock:
+ retry-interval: 30s
+ retry-times: 10
+ retry-policy-branch-rollback-on-conflict: true
+ undo:
+ log-serialization: json
+ log-table: undo_log
+ only-care-update-columns: true
+
+ tcc:
+ fence:
+ enable: false
+```
+
+配置结构与完整样例参考如下：
+
+- `seatago.yml`：[配置结构定义](../pkg/client/config.go) ·
[完整样例](../testdata/conf/seatago.yml)
+
+## 快速集成
+
+安装依赖：
+
+```bash
+go get seata.apache.org/seata-go/v2@latest
+```
+
+初始化 Seata 客户端：
+
+```go
+package main
+
+import (
+ "context"
+
+ "seata.apache.org/seata-go/v2/pkg/client"
+ "seata.apache.org/seata-go/v2/pkg/tm"
+)
+
+func main() {
+ // 初始化 Seata 客户端
+ client.InitPath("./conf/seatago.yml")
+ // 或者先设置 SEATA_GO_CONFIG_PATH=/path/to/your/seatago.yml，再调用：
+ // client.Init()
+
+ ctx := context.Background()
+
+ // 使用分布式事务
+ err := tm.WithGlobalTx(ctx, &tm.GtxConfig{Name: "my-tx"}, func(ctx
context.Context) error {
+ // 业务逻辑
+ return nil
+ })
+ if err != nil {
+ panic(err)
+ }
+}
+```
+
+## 示例场景
+
+### AT 模式示例
+
+AT 模式通过 `tm.WithGlobalTx(...)` 包裹业务逻辑，并使用 `seata-at-mysql` 驱动接管数据库访问：
+
+```go
+import (
+ "context"
+ "database/sql"
+
+ "seata.apache.org/seata-go/v2/pkg/tm"
+)
+
+db, err := sql.Open(
+ "seata-at-mysql",
+
"root:password@tcp(127.0.0.1:3306)/seata_demo?charset=utf8mb4&parseTime=True&multiStatements=true",
+)
+if err != nil {
+ return err
+}
+
+ctx := context.Background()
+err = tm.WithGlobalTx(ctx, &tm.GtxConfig{Name: "create-order"}, func(ctx
context.Context) error {
+ _, err := db.ExecContext(ctx,
+ "UPDATE account SET balance = balance - ? WHERE user_id = ?",
+ 100,
+ 1,
+ )
+ return err
+})
+```
+
+使用 AT 模式前，请确认业务库已经创建 [undo_log](../testdata/sql/undo_log.sql) 表。
+
+> 完整示例可参考：[AT
模式示例](https://github.com/apache/incubator-seata-go-samples/tree/main/at/basic)。
+
+### TCC 模式示例
+
+TCC 模式通过 `tcc.NewTCCServiceProxy(...)` 注册 Try/Confirm/Cancel 动作，再由
`tm.WithGlobalTx(...)` 串联全局事务：
+
+```go
+proxy, err := tcc.NewTCCServiceProxy(&InventoryTCC{})
+if err != nil {
+ return err
+}
+
+return tm.WithGlobalTx(ctx, &tm.GtxConfig{Name: "inventory-tcc"}, func(ctx
context.Context) error {
+ _, err := proxy.Prepare(ctx, ReserveRequest{OrderID: 1001})
+ return err
+})
+```
+
+如果需要开启 fence，可在 `seatago.yml` 中设置 `seata.tcc.fence.enable: true`，并创建
`tcc_fence_log` 表。
+
+> 完整示例可参考：[TCC
模式示例](https://github.com/apache/incubator-seata-go-samples/tree/main/tcc/local)。
+
+### XA 模式示例
+
+当前仓库已支持 MySQL XA，事务入口与 AT 相同，只需要将驱动切换为 `seata-xa-mysql`：
+
+```go
+db, err := sql.Open(
+ "seata-xa-mysql",
+
"root:password@tcp(127.0.0.1:3306)/seata_demo?charset=utf8mb4&parseTime=True&multiStatements=true",
+)
+```
+
+> 完整示例可参考：[XA
模式示例](https://github.com/apache/incubator-seata-go-samples/tree/main/xa/basic)。
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
