Skip to main content
Version: v2.5

Namingserver Registry (beta)

Namingserver is Seata's native registry center.

Prerequisites

Download the Seata binary package from this link

Running Namingserver in IDE

If you need to debug or develop namingserver locally, import Seata source code, locate the namingserver module, set the port number for namingserver in resources/application.yml, then start namingserver.

Running Namingserver

After extracting, navigate to the seata-namingserver directory. Open the conf/application.yml file and configure the port for namingserver.

For Mac or Linux, run:

bin\seata-namingserver.sh

For Windows, run:

bin\seata-namingserver.bat

Running Namingserver with Docker

Pull the Image

docker pull apache/seata-naming-server:latest

Quick Start

docker run -d --name seata-naming-server \
-p 8081:8081 \
apache/seata-naming-server:latest

Important: If you don't configure the console password, the system will automatically generate a random password at startup and display it in the logs. Use the following command to view it:

docker logs seata-naming-server | grep "auto-generated password"

Start with Environment Variables

docker run -d --name seata-naming-server \
-p 8081:8081 \
-p 10055:10055 \
-e SERVER_PORT=8081 \
-e SEATA_SECURITY_SECRETKEY=TXlDdXN0b21TZWNyZXRLZXlGb3JTZWF0YUpXVDIwMjQ= \
-e SEATA_SECURITY_TOKEN_VALIDITY=1800000 \
-v ./logs:/logs/seata \
apache/seata-naming-server:latest

Start with Custom Configuration File

docker run -d --name seata-naming-server \
-p 8081:8081 \
-v /path/to/application.yml:/seata-namingserver/conf/application.yml \
-v ./logs:/logs/seata \
apache/seata-naming-server:latest

Start with Docker Compose

Create a docker-compose.yml file:

version: "3"

services:
seata-naming-server:
image: apache/seata-naming-server:latest
container_name: seata-naming-server
hostname: seata-naming-server
ports:
- "8081:8081"
- "10055:10055"
environment:
- SERVER_PORT=8081
- SEATA_SECURITY_SECRETKEY=TXlDdXN0b21TZWNyZXRLZXlGb3JTZWF0YUpXVDIwMjQ=
- SEATA_SECURITY_TOKEN_VALIDITY=1800000
volumes:
- ./logs:/logs/seata
# Optional: mount custom configuration file
# Official image (JIB) example:
# - ./conf/application.yml:/seata-naming-server/resources/application.yml
# Dockerfile-built image example (https://github.com/apache/incubator-seata/blob/2.x/distribution/docker/namingserver/Dockerfile):
# - ./conf/application.yml:/seata-namingserver/conf/application.yml
restart: unless-stopped

Start the service:

docker-compose up -d

View logs:

docker-compose logs -f seata-naming-server

Stop the service:

docker-compose down

Docker Environment Variables

Environment VariableDescriptionDefault Value
SERVER_PORTNamingserver HTTP port8081
SEATA_SECURITY_SECRETKEYJWT Token signing key (Base64 encoded)Built-in key
SEATA_SECURITY_TOKEN_VALIDITYToken validity period (milliseconds)1800000 (30 minutes)
LOG_HOMELog storage path${user.home}/logs/seata

Note: Console username and password configuration are not supported through environment variables and must be configured in the application.yml file.

Generate Security Key

The JWT key must be a Base64-encoded string. You can generate one using the following commands:

# Generate a random key
openssl rand -base64 32

# Or convert a custom string to Base64
echo -n "MyCustomSecretKeyForSeataJWT2024" | base64

Quick Start

Setting up Seata with namingserver as the registry is straightforward, involving configurations on both client and server sides.

Namingserver Configuration Description

server:
port: 8081 ## namingserver port
spring:
application:
name: seata-namingserver
logging:
config: classpath:logback-spring.xml
file:
path: ${log.home:${user.home}/logs/seata}
console: ## As of version 2.4, the console has been moved from Seata-server to Namingserver
user:
username: seata ## Account for console interface and open-api authentication, strongly recommended to change from default
password: seata ## Password for console interface and open-api authentication, strongly recommended to change from default
heartbeat:
threshold: 90000 ## Time to remove Seata-server nodes when they go down ungracefully
period: 60000 ## Check node heartbeats every 60 seconds, remove nodes if they exceed the threshold
seata:
security:
secretKey: SeataSecretKey0c382ef121d778043159209298fd40bf3850a017 ## Token signing key, strongly recommended to change from default
tokenValidityInMilliseconds: 1800000 ## Token expiration time
csrf-ignore-urls: /naming/v1/**,/api/v1/naming/** ## URLs that don't require CSRF protection, use default values as these are for client open-api
ignore:
urls: /,/**/*.css,/**/*.js,/**/*.html,/**/*.map,/**/*.svg,/**/*.png,/**/*.jpeg,/**/*.ico,/api/v1/auth/login,/version.json,/naming/v1/health,/error ## URLs that don't require authentication

Client Registry Configuration

Add the following registry configuration to application.yml:

seata:
registry:
type: seata
seata:
server-addr: 127.0.0.1:8081 ## IP and port of configured namingserver, use commas to separate multiple nodes
namespace: public ## Namespace
heartbeat-period: 5000 ## Heartbeat interval
username: seata
password: seata

Server Registry Configuration

Add the following configuration to conf/application.yaml. For other configurations, refer to configuration options:

seata:
registry:
type: seata
seata:
server-addr: 127.0.0.1:8081 ## IP and port of configured namingserver, use commas to separate multiple nodes
cluster: default ## Cluster name
namespace: public ## Namespace
heartbeat-period: 5000 ## Heartbeat interval
username: seata
password: seata

Getting a Token

If you're using IntelliJ IDEA's built-in HTTP client, you can get a token like this:

POST http://localhost:8081/api/v1/auth/login
Content-Type: application/json

{
"username": "username",
"password": "password"
}

If you're using curl, you can do:

curl -X POST http://localhost:8081/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "username", "password": "password"}'

You'll receive a response like this. Copy the data field for use in the authorization header in subsequent requests:

{
"code": "200",
"message": "success",
"data": "Bearer xxxxxxxxxx",
"success": true
}

Create the client transaction-group -> Seata cluster mapping

Start the namingserver, then start the Seata Server.

Send an HTTP request to a namingserver node to create the transaction-group mapping (the namingserver node will automatically synchronize it to other nodes):

curl -X POST -H "authorization: Bearer xxxxxxx" http://127.0.0.1:8081/naming/v1/addGroup?clusterName=cluster2&namespace=public&unitName&vGroup=my_test_tx_group

(where namespace is the namespace configured on the client, vGroup is the transaction group configured on the client, and clusterName is the Seata Server cluster to map to)

Switch the client transaction-group -> Seata cluster mapping (cutover)

Send an HTTP request to a namingserver node to modify the transaction-group mapping (the namingserver node will automatically synchronize it to other nodes):

curl -X POST -H "authorization: Bearer xxxxxxx" http://127.0.0.1:8081/naming/v1/changeGroup?clusterName=cluster2&namespace=public&unitName&vGroup=my_test_tx_group

(where namespace is the namespace configured on the client, vGroup is the transaction group configured on the client, and clusterName is the Seata Server cluster to map to)

If there is no Seata Server available under the specified namespace and clusterName when creating the transaction group, creation will fail. After configuring the client and starting your application, you can start using Seata services.

Tips:

    1. Ensure the client and server registries are in the same namespace, otherwise services won't be found.
    1. Namingserver should only be used on internal networks, never expose it to public networks.
    1. Namingserver is an experimental feature and may change in future versions. Please evaluate and test thoroughly before using in production.
    1. Adding, deleting, or modifying transaction groups must be done through namingserver's open-api. Bypassing this may cause data inconsistency, resulting in service discovery failures or exceptions.