Skip to content

docs: add configuration architecture section to config-center README - #8204

Open
shenshichao163-oss wants to merge 2 commits into
apache:2.xfrom
shenshichao163-oss:docs/config-center-clarification
Open

docs: add configuration architecture section to config-center README#8204
shenshichao163-oss wants to merge 2 commits into
apache:2.xfrom
shenshichao163-oss:docs/config-center-clarification

Conversation

@shenshichao163-oss

Copy link
Copy Markdown

What this PR does

Adds a Configuration Architecture section to script/config-center/README.md to clarify the relationship between the two configuration files (application.yml and config.txt) and how they relate to each other.

Changes

Added a new section before "Script Introduction" that includes:

  1. Explanation of the two configuration files:

    • application.yml — Server-side Spring Boot configuration (port, logging, config/registry/store type)
    • config.txt — Client-side transaction configuration (transport, vgroup mapping, store settings)
  2. Architecture diagram showing the config flow:

    • Server reads application.yml → connects to Config Center
    • Config Center stores config.txt content (pushed by scripts)
    • Client reads from Config Center
  3. FAQ section answering:

    • Where should seata.config.nacos.data-id be placed?
    • What does config.txt do?
    • Should I use config.txt or application.yml?

Issue Link

Fixes #5608

Motivation

Issue #5608 reports confusion about Seata configuration: which file goes where, what each config item means, and how application.yml and config.txt relate to each other. This PR adds clear documentation directly in the config-center README to address these questions.

Checklist

  • I have searched the issues of this repository and believe this is not a duplicate.
  • I have checked that this modification does not cause CI to fail.
  • I will sign the Apache CLA if required.

- Explain the relationship between application.yml and config.txt
- Add architecture diagram showing config flow between server, config center, and client
- Add FAQ section answering common questions about config placement

Fixes apache#5608

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new “Configuration Architecture” section to script/config-center/README.md to clarify how Seata server/client configuration relates to the config-center scripts (addressing confusion raised in #5608).

Changes:

  • Documents the roles of application.yml vs script/config-center/config.txt
  • Adds an ASCII diagram for the configuration flow through a config center
  • Adds a short FAQ (including seata.config.nacos.data-id placement)
Suppressed comments (3)

script/config-center/README.md:51

  • script/config-center/config.txt is described as a "client-side" config file, but it contains both client and server keys (e.g. store.* / store.mode) and is not read directly at runtime. It’s a template the scripts publish into the config center (for Nacos, each line is published as its own DataId).
2. **`script/config-center/config.txt`** — The **client-side** configuration file (key-value properties format). It contains:
   - Transport settings (protocol, heartbeat, thread pool)
   - Transaction group mappings (`service.vgroupMapping.xxx`)
   - Client-side settings (lock, undo, retry policies)
   - Storage configuration (when `store.mode=db` or `redis`)

script/config-center/README.md:94

  • The answer currently says seata.config.nacos.data-id should be in the client only and suggests the server otherwise reads a local config.txt. In practice, data-id applies to any Seata process (server or client) using Nacos config, and config.txt is just the script input template (not a runtime local config file).
**Q: Where should `seata.config.nacos.data-id` be placed?**

A: In the **client's** `application.yml`, this setting tells the Seata client which Nacos data ID to read for client configuration. On the server side, `seata.config.type=nacos` in `application.yml` tells the server to read from Nacos instead of the local `config.txt`.

script/config-center/README.md:75

  • The diagram implies the config center stores a single "config.txt" document, but the Nacos/Apollo/etc scripts actually publish key/value entries (for Nacos, each config key becomes a DataId). Renaming this box makes the flow match what the scripts do.
│  │  config.txt (client config)   │                          │
│  │  - transport.*                │                          │
│  │  - service.vgroupMapping.*    │                          │
│  │  - store.* (db settings)      │                          │
│  └────────────────────────────────┘                          │

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +41 to +45
1. **`server/src/main/resources/application.yml`** — The Seata **server** configuration file (Spring Boot style). It contains:
- Server port, logging, and Spring application settings
- `seata.config.type` — Where the server reads its configuration from (`file`, `nacos`, `consul`, `apollo`, `zk`, `etcd3`)
- `seata.registry.type` — Where the server registers itself for service discovery (`file`, `nacos`, `eureka`, `redis`, `zk`, `consul`, `etcd3`, `sofa`, `seata`)
- `seata.store.mode` — Transaction log storage mode (`file`, `db`, `redis`, `raft`)

@WangzJi WangzJi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this. The new section is helpful, but a couple of configuration roles need to be corrected:

  1. seata.config.nacos.data-id is not client-only. The server also needs it when using an all-in-one Nacos configuration such as seataServer.properties.
  2. config.txt is not a client-side configuration file. It is the source used by the publishing scripts and contains shared, client-only, and server-only settings.
  3. The server does not read a local config.txt at runtime, and using both files is not always required.

Could you update the description and diagram to reflect these distinctions?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

confused about the documentation [important]

3 participants