This is an automated email from the ASF dual-hosted git repository.
dybyte pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new 6fc6ac7fb4 [Docs] add FAQ sections to connector pages (EN + zh-CN)
(#10980)
6fc6ac7fb4 is described below
commit 6fc6ac7fb48996c253a95cbeb56b742cbea358d4
Author: David Zollo <[email protected]>
AuthorDate: Tue Jun 9 00:57:32 2026 +0800
[Docs] add FAQ sections to connector pages (EN + zh-CN) (#10980)
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Daniel <[email protected]>
---
docs/en/connectors/connector-faq.md | 66 ++++++++++++++++++++++++++++
docs/en/connectors/sink/Clickhouse.md | 24 +++++++++++
docs/en/connectors/sink/Doris.md | 57 ++++++++++++++++++++++++
docs/en/connectors/sink/Hive.md | 48 +++++++++++++++++++++
docs/en/connectors/sink/Jdbc.md | 64 +++++++++++++++++++++++++++
docs/en/connectors/sink/Kafka.md | 60 +++++++++++++++++++++++++-
docs/en/connectors/sink/StarRocks.md | 52 +++++++++++++++++++++-
docs/en/connectors/source/Kafka.md | 67 +++++++++++++++++++++++++++++
docs/en/connectors/source/MySQL-CDC.md | 57 +++++++++++++++++++++++-
docs/en/connectors/source/Oracle-CDC.md | 58 +++++++++++++++++++++++++
docs/en/connectors/source/PostgreSQL-CDC.md | 35 +++++++++++++++
docs/sidebars.js | 2 +
docs/zh/connectors/connector-faq.md | 65 ++++++++++++++++++++++++++++
docs/zh/connectors/sink/Clickhouse.md | 23 +++++++++-
docs/zh/connectors/sink/Doris.md | 56 ++++++++++++++++++++++++
docs/zh/connectors/sink/Hive.md | 48 +++++++++++++++++++++
docs/zh/connectors/sink/Jdbc.md | 64 +++++++++++++++++++++++++++
docs/zh/connectors/sink/Kafka.md | 57 +++++++++++++++++++++++-
docs/zh/connectors/sink/StarRocks.md | 50 +++++++++++++++++++++
docs/zh/connectors/source/Kafka.md | 67 +++++++++++++++++++++++++++++
docs/zh/connectors/source/MySQL-CDC.md | 53 +++++++++++++++++++++++
docs/zh/connectors/source/Oracle-CDC.md | 57 ++++++++++++++++++++++++
docs/zh/connectors/source/PostgreSQL-CDC.md | 35 +++++++++++++++
23 files changed, 1160 insertions(+), 5 deletions(-)
diff --git a/docs/en/connectors/connector-faq.md
b/docs/en/connectors/connector-faq.md
new file mode 100644
index 0000000000..a47544ba0b
--- /dev/null
+++ b/docs/en/connectors/connector-faq.md
@@ -0,0 +1,66 @@
+---
+sidebar_position: 10
+---
+
+# Connector FAQ
+
+This page is an index of frequently asked questions organized by connector
category. Each entry links to the FAQ section inside the corresponding
connector documentation page.
+
+These FAQ sections are intended to be quick navigation, not a second source of
truth. For exact
+option names, defaults, and full examples, always use the connector option
table and linked
+detailed sections on the connector page itself.
+
+For general SeaTunnel questions (engine setup, variable substitution,
scheduling, etc.) see the [General FAQ](../faq.md).
+
+---
+
+## CDC Connectors
+
+Change Data Capture connectors read real-time change events (INSERT / UPDATE /
DELETE) from database transaction logs.
+
+| Connector | Common FAQ Topics |
+|---|---|
+| [MySQL CDC](./source/MySQL-CDC.md#faq) | Required permissions, binlog
settings, replica support, tables without primary keys, snapshot phase, DDL
propagation, `server-id` conflicts, snapshot performance, timezone/charset |
+| [PostgreSQL CDC](./source/PostgreSQL-CDC.md#faq) | Required permissions,
logical decoding plugins, replica support, tables without primary keys,
replication slot management, replication lag |
+| [Oracle CDC](./source/Oracle-CDC.md#faq) | LogMiner permissions,
supplemental logging, CDB/PDB multi-tenant, tables without primary keys,
LogMiner performance, supported Oracle versions |
+
+---
+
+## Message Queue Connectors
+
+| Connector | Common FAQ Topics |
+|---|---|
+| [Kafka Source](./source/Kafka.md#faq) | `start_mode` options, filtering by
message key, supported formats, SASL/Kerberos authentication, consumer group
offset commit |
+| [Kafka Sink](./sink/Kafka.md#faq) | Automatic topic creation,
`partition_key_fields` behavior, exactly-once delivery, SASL/Kerberos
authentication, supported formats |
+
+---
+
+## Sink Connectors
+
+### OLAP / Analytical Stores
+
+| Connector | Common FAQ Topics |
+|---|---|
+| [Doris Sink](./sink/Doris.md#faq) | Automatic table creation, exactly-once
with 2PC, "Label already exists" error, DELETE propagation, column case
sensitivity, Stream Load format |
+| [StarRocks Sink](./sink/StarRocks.md#faq) | Automatic table creation, upsert
and DELETE support, `labelPrefix` usage, column case sensitivity, `nodeUrls` vs
`base-url` |
+| [ClickHouse Sink](./sink/Clickhouse.md#faq) | Automatic table creation,
batch write performance, supported data types, "Table doesn't exist" error |
+
+### Relational Databases
+
+| Connector | Common FAQ Topics |
+|---|---|
+| [JDBC Sink](./sink/Jdbc.md#faq) | Automatic table creation, exactly-once
with XA transactions, upsert / primary key configuration, multi-table writing,
missing JDBC driver |
+
+### Data Lakes / File Systems
+
+| Connector | Common FAQ Topics |
+|---|---|
+| [Hive Sink](./sink/Hive.md#faq) | Supported file formats, partitioned
tables, Kerberos authentication, small file problem, schema evolution |
+
+---
+
+## Tips for Finding Answers
+
+1. **Connector-specific issues** → go directly to the connector's page and
scroll to its **FAQ** section.
+2. **Cross-connector topics** (e.g., "does SeaTunnel support CDC?", "what is
`schema_save_mode`?") → see the [General FAQ](../faq.md).
+3. **Still stuck?** → search the [GitHub
Issues](https://github.com/apache/seatunnel/issues) or reach out via the
[mailing list](https://lists.apache.org/[email protected]).
diff --git a/docs/en/connectors/sink/Clickhouse.md
b/docs/en/connectors/sink/Clickhouse.md
index ae1ebe519c..afb1760f89 100644
--- a/docs/en/connectors/sink/Clickhouse.md
+++ b/docs/en/connectors/sink/Clickhouse.md
@@ -347,6 +347,30 @@ sink {
After submitting the job and successfully executing it, we can see that the
data volume of the ClickHouse data tables `multi_sink_table1` and
`multi_sink_table2` is 100 for each.
+## FAQ
+
+### Does ClickHouse Sink support automatic table creation?
+
+Yes. See the `schema_save_mode` section above for the exact modes and current
default behavior.
+If you need to customize the generated DDL, use `save_mode_create_template`
rather than
+re-introducing separate DDL option names in the FAQ.
+
+### How do I tune batch write performance?
+
+Use `bulk_size` as the primary tuning knob. The exact option name and current
default are already
+documented in the option table above, so treat that table as the source of
truth when tuning
+throughput.
+
+### What ClickHouse data types are supported?
+
+SeaTunnel maps to ClickHouse types including `Int8/16/32/64`,
`UInt8/16/32/64`, `Float32/64`, `Decimal`, `String`, `FixedString`, `Date`,
`DateTime`, `Array`, `Map`, and `Nullable` variants. Complex nested types may
require a field transform before writing.
+
+### Why do I get a "Table doesn't exist" error?
+
+Start with the `schema_save_mode` section above. If your environment should
auto-create missing
+tables, keep the documented create-on-missing flow. If your environment
requires pre-created
+tables, switch to the stricter mode explicitly and provision the table ahead
of time.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/sink/Doris.md b/docs/en/connectors/sink/Doris.md
index cd86af9c20..c199340377 100644
--- a/docs/en/connectors/sink/Doris.md
+++ b/docs/en/connectors/sink/Doris.md
@@ -527,6 +527,63 @@ sink {
}
```
+## FAQ
+
+### Does Doris Sink support automatic table creation?
+
+Yes. Use the `schema_save_mode` and `save_mode_create_template` sections above
as the canonical
+reference for the exact behavior, defaults, and DDL customization path.
+
+### How does exactly-once work with Doris Sink?
+
+Doris Sink uses Stream Load with two-phase commit (2PC) for exactly-once
semantics:
+
+```hocon
+sink {
+ Doris {
+ fenodes = "doris-fe:8030"
+ username = root
+ password = ""
+ database = "mydb"
+ table = "mytable"
+ sink.enable-2pc = "true"
+ sink.label-prefix = "unique-job-label"
+ }
+}
+```
+
+The `sink.label-prefix` must be unique per job to avoid label conflicts when
retrying or restarting.
+
+### Why do I get a "Label already exists" error?
+
+Doris uses Stream Load labels to detect and reject duplicate submissions. If a
job is restarted with 2PC enabled, the same label prefix may be reused. To
resolve:
+
+- Include a timestamp or unique token in `sink.label-prefix` to ensure
uniqueness across restarts.
+- Abort uncommitted transactions in Doris before restarting: `CANCEL LOAD
WHERE LABEL LIKE 'your-prefix%'`.
+
+### Does Doris Sink support DELETE propagation from CDC sources?
+
+Yes. Set `sink.enable-delete = "true"` to propagate DELETE operations from CDC
sources (e.g., MySQL CDC) to Doris. This requires the target table to use the
Unique Key model in Doris.
+
+### Are Doris column names case-sensitive?
+
+See the case-sensitivity example above for the exact behavior. If upstream
field names still do not
+match the Doris schema, normalize them before the sink stage or align the
target schema explicitly
+instead of relying on an undocumented `column_mapping` option.
+
+### What data format does Doris Stream Load use?
+
+Doris Sink uses JSON format for Stream Load by default. Configure it
explicitly if needed:
+
+```hocon
+doris.config {
+ format = "json"
+ read_json_by_line = "true"
+}
+```
+
+CSV format is also supported but requires careful delimiter configuration.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/sink/Hive.md b/docs/en/connectors/sink/Hive.md
index f1eaa21f5a..d87b4100ff 100644
--- a/docs/en/connectors/sink/Hive.md
+++ b/docs/en/connectors/sink/Hive.md
@@ -583,6 +583,54 @@ sink {
}
}
```
+## FAQ
+
+### What file formats does Hive Sink support?
+
+Hive Sink supports `ORC`, `PARQUET`, `TEXT`, `JSON`, and `SEQUENCE` file
formats. Specify the format with the `file_format_type` parameter. Ensure the
Hive table's `STORED AS` clause matches the configured format.
+
+### Does Hive Sink support partitioned tables?
+
+Yes. For partitioned tables, specify the partition fields using
`partition_by`. SeaTunnel writes data into the correct partition directories
automatically:
+
+```hocon
+sink {
+ Hive {
+ table_name = "mydb.sales"
+ metastore_uri = "thrift://hive-metastore:9083"
+ partition_by = ["dt", "region"]
+ }
+}
+```
+
+### How do I connect to a Kerberized Hadoop cluster?
+
+Provide the Kerberos keytab and principal in the connector configuration:
+
+```hocon
+sink {
+ Hive {
+ table_name = "mydb.events"
+ metastore_uri = "thrift://hive-metastore:9083"
+ kerberos_principal = "hive/[email protected]"
+ kerberos_keytab_path = "/etc/security/keytabs/hive.keytab"
+ krb5_path = "/etc/krb5.conf"
+ }
+}
+```
+
+### Why do I see many small files in my Hive table?
+
+Small files are created when job parallelism is high or batches are small. To
reduce small file counts:
+
+- Lower the job `parallelism` setting in the `env` block.
+- Increase `batch_size` so each task writes larger files.
+- Run a periodic compaction using Hive's `ALTER TABLE ... CONCATENATE` or a
Spark merge job.
+
+### Does Hive Sink support schema evolution?
+
+Hive Sink reads the current table schema from the Hive Metastore. If columns
are added to the upstream, they will only appear in Hive after the table DDL is
updated. SeaTunnel does not automatically `ALTER TABLE` Hive schemas.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/sink/Jdbc.md b/docs/en/connectors/sink/Jdbc.md
index 7d5396f57e..40f47c98ad 100644
--- a/docs/en/connectors/sink/Jdbc.md
+++ b/docs/en/connectors/sink/Jdbc.md
@@ -533,6 +533,70 @@ sink {
}
```
+## FAQ
+
+### Does JDBC Sink support automatic table creation?
+
+Yes. Use `schema_save_mode` to control table creation behavior:
+
+- `CREATE_SCHEMA_WHEN_NOT_EXIST`: Creates the table only if it does not exist.
+- `RECREATE_SCHEMA`: Drops and recreates the table on every job start.
+- `ERROR_WHEN_SCHEMA_NOT_EXIST`: Throws an error if the table is missing.
+- `IGNORE`: Skips all table creation logic.
+
+Use `generate_sink_sql = true` together with `database` and `table` for
automatic INSERT/UPSERT SQL generation.
+
+### How do I enable exactly-once semantics with JDBC Sink?
+
+JDBC Sink supports exactly-once via XA transactions. Enable it with:
+
+```hocon
+sink {
+ jdbc {
+ url = "jdbc:mysql://localhost:3306/mydb"
+ driver = "com.mysql.cj.jdbc.Driver"
+ user = "root"
+ password = "password"
+ is_exactly_once = true
+ xa_data_source_class_name = "com.mysql.cj.jdbc.MysqlXADataSource"
+ table = "target_table"
+ primary_keys = ["id"]
+ }
+}
+```
+
+Not all databases support XA transactions. Verify that your database and JDBC
driver both support XA before enabling this option.
+
+### How do I configure upsert (INSERT or UPDATE) behavior?
+
+Specify `primary_keys` to enable upsert behavior. SeaTunnel generates an
INSERT ... ON DUPLICATE KEY UPDATE (or equivalent) statement based on the
target database dialect:
+
+```hocon
+sink {
+ jdbc {
+ url = "jdbc:mysql://localhost:3306/mydb"
+ driver = "com.mysql.cj.jdbc.Driver"
+ ...
+ primary_keys = ["id"]
+ }
+}
+```
+
+Without `primary_keys`, JDBC Sink performs plain INSERTs and does not handle
duplicate key conflicts.
+
+### How do I write to multiple tables in a single job?
+
+Use `table = "${table_name}"` and `database = "${schema_name}"` as
placeholders. SeaTunnel resolves these from the upstream record's metadata when
used with CDC sources or multi-table configurations. Pair with
`generate_sink_sql = true` for fully automatic SQL generation.
+
+### Why is my JDBC driver not found?
+
+SeaTunnel does not bundle all JDBC drivers due to licensing restrictions.
Place the JDBC driver JAR in `$SEATUNNEL_HOME/lib/` manually before starting
the job. Common drivers:
+
+- MySQL: `mysql-connector-j-8.x.x.jar`
+- PostgreSQL: `postgresql-42.x.x.jar`
+- Oracle: `ojdbc8.jar`
+- SQL Server: `mssql-jdbc-12.x.x.jre11.jar`
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/sink/Kafka.md b/docs/en/connectors/sink/Kafka.md
index 42e5cda945..77eeae3997 100644
--- a/docs/en/connectors/sink/Kafka.md
+++ b/docs/en/connectors/sink/Kafka.md
@@ -363,6 +363,64 @@ The input parameter requirements are as follows:
```
Note：key/value is of type byte[].
+## FAQ
+
+### Does Kafka Sink automatically create topics?
+
+SeaTunnel Kafka Sink writes records to the configured `topic` but does not
explicitly create Kafka topics itself. Whether a missing topic is created
automatically depends on the Kafka broker's `auto.create.topics.enable` setting.
+
+In production, we recommend creating topics explicitly in advance to control
partition count, replication factor, retention policy, and ACLs. Do not rely on
automatic topic creation for production workloads, as brokers may have
`auto.create.topics.enable = false`.
+
+### What happens if `partition_key_fields` is not configured?
+
+If `partition_key_fields` is not set, SeaTunnel sends records with a **null**
Kafka message key. Kafka then distributes records across partitions using its
default round-robin strategy.
+
+This is suitable for load distribution but does **not** preserve ordering for
records with the same business key. If you need records with the same business
key to land in the same partition, configure `partition_key_fields` with the
relevant field names.
+
+### How do I achieve exactly-once delivery to Kafka?
+
+Set `semantics = EXACTLY_ONCE` to enable exactly-once delivery, and configure
`transaction_prefix`
+so each job uses a distinct Kafka transactional ID prefix. SeaTunnel
coordinates Kafka transactions
+with checkpoints to provide exactly-once semantics:
+
+```hocon
+sink {
+ kafka {
+ topic = "output-topic"
+ bootstrap.servers = "localhost:9092"
+ semantics = EXACTLY_ONCE
+ transaction_prefix = "SeaTunnelJob"
+ kafka.transaction.timeout.ms = "900000"
+ }
+}
+```
+
+Ensure the Kafka broker has transactions enabled and that
`transaction.timeout.ms` is aligned with your checkpoint interval.
+
+### How do I configure SASL/Kerberos authentication?
+
+Pass broker authentication settings via `kafka.*` properties:
+
+```hocon
+sink {
+ kafka {
+ topic = "secure-topic"
+ bootstrap.servers = "broker:9092"
+ kafka.security.protocol = "SASL_PLAINTEXT"
+ kafka.sasl.mechanism = "GSSAPI"
+ kafka.sasl.kerberos.service.name = "kafka"
+ kafka.sasl.jaas.config = """com.sun.security.auth.module.Krb5LoginModule
required
+ useKeyTab=true
+ keyTab="/etc/kafka/kafka.keytab"
+ principal="[email protected]";"""
+ }
+}
+```
+
+### What message formats does Kafka Sink support?
+
+Kafka Sink supports: `json`, `text`, `canal_json`, `debezium_json`,
`ogg_json`, `avro`, `protobuf`, and `NATIVE`. Use `NATIVE` when the upstream
data is already in Kafka-native format (with headers, key, and value as byte
fields).
+
## Changelog
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
diff --git a/docs/en/connectors/sink/StarRocks.md
b/docs/en/connectors/sink/StarRocks.md
index 8e4a06ea0b..3c7584c4e8 100644
--- a/docs/en/connectors/sink/StarRocks.md
+++ b/docs/en/connectors/sink/StarRocks.md
@@ -389,7 +389,57 @@ sink {
}
```
+## FAQ
+
+### Does StarRocks Sink support automatic table creation?
+
+Yes. Use `schema_save_mode` to control table creation behavior:
+
+- `CREATE_SCHEMA_WHEN_NOT_EXIST`: Creates the table only if it does not exist.
+- `RECREATE_SCHEMA`: Drops and recreates the table on every job start.
+- `ERROR_WHEN_SCHEMA_NOT_EXIST`: Throws an error if the table is missing.
+- `IGNORE`: Skips all table creation logic.
+
+SeaTunnel infers StarRocks column types from the upstream schema automatically.
+
+### Does StarRocks Sink support upsert and DELETE operations?
+
+Yes. Enable upsert and DELETE propagation by setting `enable_upsert_delete =
true`. This requires the target StarRocks table to use the **Primary Key**
model. DELETE events from CDC sources are propagated correctly when this option
is enabled.
+
+### What is `labelPrefix` used for in StarRocks Sink?
+
+The current StarRocks Sink page does not list exactly-once as a supported
connector capability.
+Use `labelPrefix` to control the prefix of the Stream Load labels generated by
the sink.
+Keeping this prefix stable and unique helps reduce label collisions across
retries or job restarts:
+
+```hocon
+sink {
+ StarRocks {
+ nodeUrls = ["starrocks-fe:8030"]
+ base-url = "jdbc:mysql://starrocks-fe:9030/"
+ username = root
+ password = ""
+ database = "mydb"
+ table = "mytable"
+ labelPrefix = "unique-job-label"
+ }
+}
+```
+
+For the published connector contract, follow the **Key Features** matrix and
the `labelPrefix`
+option entry on this page.
+
+### Are StarRocks column names case-sensitive?
+
+StarRocks column names are case-insensitive by default. Verify that upstream
field names align with the target StarRocks column names to avoid unintended
mapping issues.
+
+### What is the difference between `nodeUrls` and `base-url`?
+
+- `nodeUrls`: HTTP addresses of the StarRocks FE nodes, used for Stream Load
data ingestion.
+- `base-url`: JDBC URL pointing to a StarRocks FE node, used for DDL
operations such as table creation and schema inspection.
+
+Both parameters are required when automatic table creation is enabled.
+
## Changelog
<ChangeLog />
-
diff --git a/docs/en/connectors/source/Kafka.md
b/docs/en/connectors/source/Kafka.md
index 35ec94cbec..be6cac4df7 100644
--- a/docs/en/connectors/source/Kafka.md
+++ b/docs/en/connectors/source/Kafka.md
@@ -533,6 +533,73 @@ The returned data is as follows:
```
Note：key/value is of type byte[].
+## FAQ
+
+### What `start_mode` values are available and how do they differ?
+
+| `start_mode` | Behavior |
+|---|---|
+| `earliest` | Consume from the earliest available offset in each partition |
+| `latest` | Consume only new messages produced after the job starts |
+| `group_offsets` | Resume from the committed offsets for the consumer group |
+| `specific_offsets` | Start from explicitly specified offsets per partition |
+| `timestamp` | Start from the first message at or after a given timestamp |
+
+Use `group_offsets` to resume an interrupted job. Use `earliest` for a full
replay from the beginning of the topic.
+
+### How can I filter messages from the same topic by Kafka message key?
+
+Use `format = "NATIVE"` to expose the raw Kafka metadata — including the `key`
field — as part of each record. Then apply a SQL Transform to keep only
messages matching the desired key value:
+
+```hocon
+source {
+ Kafka {
+ topic = "events"
+ bootstrap.servers = "localhost:9092"
+ format = "NATIVE"
+ consumer.group = "my-group"
+ }
+}
+transform {
+ Sql {
+ plugin_input = "kafka_source"
+ plugin_output = "filtered"
+ query = "SELECT * FROM kafka_source WHERE key = 'expected_key_base64'"
+ }
+}
+```
+
+Note: the `key` field in NATIVE format is base64-encoded bytes.
+
+### What message formats does Kafka Source support?
+
+Kafka Source supports: `json`, `text`, `canal_json`, `debezium_json`,
`ogg_json`, `avro`, `protobuf`, and `NATIVE`. Use `NATIVE` when you need access
to Kafka-level metadata (headers, key, partition, timestamp) as part of the
record.
+
+### How do I configure SASL/Kerberos authentication?
+
+Pass authentication settings via `kafka.*` properties in the connector
configuration:
+
+```hocon
+source {
+ Kafka {
+ bootstrap.servers = "broker:9092"
+ topic = "secure-topic"
+ consumer.group = "my-group"
+ kafka.security.protocol = "SASL_PLAINTEXT"
+ kafka.sasl.mechanism = "GSSAPI"
+ kafka.sasl.kerberos.service.name = "kafka"
+ kafka.sasl.jaas.config = """com.sun.security.auth.module.Krb5LoginModule
required
+ useKeyTab=true
+ keyTab="/etc/kafka/kafka.keytab"
+ principal="[email protected]";"""
+ }
+}
+```
+
+### How are consumer group offsets committed?
+
+Offsets are committed to Kafka when a SeaTunnel checkpoint completes. Ensure
checkpointing is enabled via `checkpoint.interval` in the `env` block. If the
job restarts with `start_mode = "group_offsets"`, it resumes from the last
committed checkpoint offset.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/source/MySQL-CDC.md
b/docs/en/connectors/source/MySQL-CDC.md
index 3e5dabddce..2210231123 100644
--- a/docs/en/connectors/source/MySQL-CDC.md
+++ b/docs/en/connectors/source/MySQL-CDC.md
@@ -372,6 +372,62 @@ sink {
}
```
+## FAQ
+
+### What MySQL permissions are required for CDC?
+
+The MySQL user must have the following privileges:
+
+```sql
+GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON
*.* TO 'user'@'%';
+```
+
+Also enable binary logging in `my.cnf` / `my.ini`:
+
+```ini
+[mysqld]
+log_bin = mysql-bin
+binlog_format = ROW
+binlog_row_image = FULL
+```
+
+### Can SeaTunnel read CDC from a MySQL replica?
+
+Yes. SeaTunnel subscribes to MySQL binary logs, which are also streamed to
replicas. You can point SeaTunnel at a replica to offload the primary. Ensure
the replica has binary logging enabled and `log_slave_updates = ON` set in its
configuration.
+
+### Does MySQL CDC support tables without primary keys?
+
+By default, MySQL CDC expects primary keys. If the source table does not
declare a primary key but
+does have another unique column that can identify rows, you can override it
with
+`table-names-config.primaryKeys` as shown in the existing source options
example. Without a stable
+unique key, UPDATE and DELETE events cannot be applied safely downstream.
+
+### How does the full snapshot phase work, and when does it switch to
incremental reading?
+
+On first startup, SeaTunnel takes a consistent full snapshot of the configured
tables. After the snapshot completes, it automatically switches to reading
binlog from the position recorded at the beginning of the snapshot, ensuring no
events are lost during the transition.
+
+### Does MySQL CDC support DDL propagation?
+
+Yes, but only in a limited form. Enable `schema-changes.enabled = true`, then
follow the current
+schema evolution contract already documented on this page and in the
+[Schema Evolution
guide](../../introduction/configuration/schema-evolution.md). The current
+documented support covers `add column`, `drop column`, `rename column`, and
`modify column`.
+
+### How do I avoid `server-id` conflicts when running multiple CDC jobs?
+
+Each CDC job must use a unique `server-id` or a non-overlapping range.
Duplicate `server-id` values cause the MySQL server to disconnect one of the
clients. Assign distinct ranges, for example `5400-5600` for one job and
`5601-5800` for another.
+
+### Why is the initial snapshot very slow?
+
+Snapshot speed depends on table size, JDBC fetch size, and network bandwidth.
You can tune
+`snapshot.split.size` and `snapshot.fetch.size` to control chunking and fetch
behavior. For very
+large tables where historical data is not needed, set `startup.mode =
"latest"` to start from the
+latest offset and skip the initial snapshot.
+
+### How do I handle timezone and character set issues?
+
+Set `server-time-zone` to match the MySQL server's timezone, for example
`"Asia/Shanghai"`. For character set issues, append
`characterEncoding=UTF-8&useUnicode=true` to the JDBC connection URL.
+
## See Also
For a production-grade end-to-end guide covering full + incremental
synchronization lifecycle,
@@ -381,4 +437,3 @@ For a production-grade end-to-end guide covering full +
incremental synchronizat
## Changelog
<ChangeLog />
-
diff --git a/docs/en/connectors/source/Oracle-CDC.md
b/docs/en/connectors/source/Oracle-CDC.md
index cbb42db485..c67fec3a1a 100644
--- a/docs/en/connectors/source/Oracle-CDC.md
+++ b/docs/en/connectors/source/Oracle-CDC.md
@@ -367,6 +367,64 @@ source {
> Must be used with kafka connector sink, see [compatible debezium
> format](../formats/cdc-compatible-debezium-json.md) for details
+## FAQ
+
+### What Oracle permissions are required for CDC?
+
+The LogMiner user needs the following privileges:
+
+```sql
+GRANT CREATE SESSION TO logminer_user;
+GRANT SET CONTAINER TO logminer_user;
+GRANT SELECT ON V_$DATABASE TO logminer_user;
+GRANT FLASHBACK ANY TABLE TO logminer_user;
+GRANT SELECT ANY TABLE TO logminer_user;
+GRANT SELECT_CATALOG_ROLE TO logminer_user;
+GRANT EXECUTE_CATALOG_ROLE TO logminer_user;
+GRANT SELECT ANY TRANSACTION TO logminer_user;
+GRANT LOGMINING TO logminer_user;
+GRANT CREATE TABLE TO logminer_user;
+GRANT LOCK ANY TABLE TO logminer_user;
+GRANT CREATE SEQUENCE TO logminer_user;
+GRANT EXECUTE ON DBMS_LOGMNR TO logminer_user;
+GRANT EXECUTE ON DBMS_LOGMNR_D TO logminer_user;
+GRANT SELECT ON V_$LOG TO logminer_user;
+GRANT SELECT ON V_$LOG_HISTORY TO logminer_user;
+GRANT SELECT ON V_$LOGMNR_LOGS TO logminer_user;
+GRANT SELECT ON V_$LOGMNR_CONTENTS TO logminer_user;
+GRANT SELECT ON V_$LOGMNR_PARAMETERS TO logminer_user;
+GRANT SELECT ON V_$LOGFILE TO logminer_user;
+GRANT SELECT ON V_$ARCHIVED_LOG TO logminer_user;
+GRANT SELECT ON V_$ARCHIVE_DEST_STATUS TO logminer_user;
+GRANT SELECT ON V_$TRANSACTION TO logminer_user;
+```
+
+Also enable supplemental logging at the database and table level:
+
+```sql
+ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
+ALTER TABLE schema_name.table_name ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;
+```
+
+### Does Oracle CDC support multi-tenant (CDB/PDB) databases?
+
+Yes. Set `database-names` to the CDB name and configure the JDBC URL to point
to the CDB root. The user must be a common user (prefixed with `C##`) with the
above privileges granted in all containers (`CONTAINER = ALL`).
+
+### Does Oracle CDC support tables without primary keys?
+
+By default, Oracle CDC requires primary keys. You can specify a custom primary
key column via `table-names-config` with the `primaryKeys` field if the table
has a suitable unique column.
+
+### How do I improve LogMiner performance?
+
+Treat this primarily as a database and redo-log tuning topic. Reuse the
LogMiner setup and
+supplemental logging sections above first, enable logging only for the
required tables, and add
+Debezium passthrough tuning only after validating that those properties are
supported in the exact
+Oracle CDC runtime you are deploying.
+
+### Which Oracle versions are supported?
+
+Oracle CDC is supported on Oracle Database 11g, 12c, 19c, and 21c. For 12c and
later multi-tenant configurations, use the CDB root connection with a common
user.
+
## See Also
For a production-grade end-to-end guide covering full + incremental
synchronization lifecycle,
diff --git a/docs/en/connectors/source/PostgreSQL-CDC.md
b/docs/en/connectors/source/PostgreSQL-CDC.md
index 3e47f403f7..3a79cf32c8 100644
--- a/docs/en/connectors/source/PostgreSQL-CDC.md
+++ b/docs/en/connectors/source/PostgreSQL-CDC.md
@@ -192,6 +192,41 @@ source {
}
```
+## FAQ
+
+### What PostgreSQL permissions are required for CDC?
+
+The CDC user must have the `REPLICATION` role and `SELECT` access to the
monitored tables:
+
+```sql
+CREATE USER replication_user REPLICATION LOGIN PASSWORD 'password';
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
+```
+
+Also set `wal_level = logical` in `postgresql.conf` and add an entry in
`pg_hba.conf` to allow the replication connection.
+
+### Which logical decoding plugins are supported?
+
+SeaTunnel PostgreSQL CDC supports `pgoutput` (built-in since PostgreSQL 10),
`wal2json`, and `decoderbufs`. The default is `pgoutput`. Use the
`decoding.plugin.name` parameter to select the plugin.
+
+### Can SeaTunnel read CDC from a PostgreSQL standby?
+
+PostgreSQL logical replication slots must be created and consumed on the
primary server. SeaTunnel cannot read a logical replication slot directly from
a standby. Point the CDC connector at the primary instance.
+
+### Does PostgreSQL CDC support tables without primary keys?
+
+By default, PostgreSQL CDC requires primary keys. You can specify a custom
primary key via `table-names-config` with the `primaryKeys` field if the table
has a unique column that can serve as an identifier.
+
+### How are replication slots managed?
+
+SeaTunnel creates or reuses the replication slot identified by `slot.name`
when the job starts.
+Unused replication slots hold WAL segments on disk, which can cause unbounded
WAL growth. When a
+CDC job is permanently decommissioned, drop the unused replication slot
manually on PostgreSQL.
+
+### Why does PostgreSQL CDC fall behind?
+
+Replication lag can occur when the logical decoding plugin is slow or when the
WAL sender is under load. Monitor `pg_replication_slots` for
`confirmed_flush_lsn` drift. Ensure the CDC job consumes events continuously
and that network latency between SeaTunnel and PostgreSQL is low.
+
## See Also
For a production-grade end-to-end guide covering full + incremental
synchronization lifecycle,
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 7da70c1e79..4a1884b9ab 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -139,7 +139,9 @@ const sidebars = {
"label": "Connectors",
"items": [
"connectors/connector-isolated-dependency",
+ "connectors/connector-faq",
"connectors/cdc-production-cookbook",
+ "connectors/connector-faq",
{
"type": "category",
"label": "Source",
diff --git a/docs/zh/connectors/connector-faq.md
b/docs/zh/connectors/connector-faq.md
new file mode 100644
index 0000000000..53f90bf07c
--- /dev/null
+++ b/docs/zh/connectors/connector-faq.md
@@ -0,0 +1,65 @@
+---
+sidebar_position: 10
+---
+
+# Connector 常见问题
+
+本页面是按 Connector 类别组织的常见问题索引，每个条目均链接到对应 Connector 文档页面的 FAQ 小节。
+
+这些 FAQ 的定位是“快速导航”，不是另一套独立事实源。涉及精确配置项名称、默认值和完整示例时，应以
+各 Connector 页面中的 option 表和对应详细章节为准。
+
+关于 SeaTunnel 通用问题（引擎部署、变量替换、调度等），请查阅[通用 FAQ](../faq.md)。
+
+---
+
+## CDC 类 Connector
+
+CDC（变更数据捕获）Connector 从数据库事务日志中实时读取 INSERT / UPDATE / DELETE 变更事件。
+
+| Connector | 常见问题主题 |
+|---|---|
+| [MySQL CDC](./source/MySQL-CDC.md#常见问题) | 所需权限、binlog 配置、从库支持、无主键表、快照阶段、DDL
传播、server-id 冲突、快照性能、时区/字符集 |
+| [PostgreSQL CDC](./source/PostgreSQL-CDC.md#常见问题) |
所需权限、逻辑解码插件、备库限制、无主键表、复制槽管理、复制滞后 |
+| [Oracle CDC](./source/Oracle-CDC.md#常见问题) | LogMiner 权限、附加日志、CDB/PDB
多租户、无主键表、LogMiner 性能、支持的 Oracle 版本 |
+
+---
+
+## 消息队列类 Connector
+
+| Connector | 常见问题主题 |
+|---|---|
+| [Kafka Source](./source/Kafka.md#常见问题) | `start_mode` 各取值对比、按消息 key
过滤、支持的格式、SASL/Kerberos 认证、消费组 offset 提交 |
+| [Kafka Sink](./sink/Kafka.md#常见问题) | 自动创建 topic（Broker
端行为说明）、`partition_key_fields` 为空时的行为、精确一次、SASL/Kerberos 认证、支持的格式 |
+
+---
+
+## Sink 类 Connector
+
+### OLAP / 分析型存储
+
+| Connector | 常见问题主题 |
+|---|---|
+| [Doris Sink](./sink/Doris.md#常见问题) | 自动建表、2PC 精确一次、"Label already exists"
报错、DELETE 传播、列名大小写、Stream Load 格式 |
+| [StarRocks Sink](./sink/StarRocks.md#常见问题) | 自动建表、Upsert/DELETE
支持、`labelPrefix` 用法、列名大小写、`nodeUrls` 与 `base-url` 的区别 |
+| [ClickHouse Sink](./sink/Clickhouse.md#常见问题) | 自动建表、批量写入调优、支持的数据类型、"Table
doesn't exist" 报错 |
+
+### 关系型数据库
+
+| Connector | 常见问题主题 |
+|---|---|
+| [JDBC Sink](./sink/Jdbc.md#常见问题) | 自动建表、XA 精确一次、Upsert/主键配置、多表写入、JDBC 驱动未找到 |
+
+### 数据湖 / 文件系统
+
+| Connector | 常见问题主题 |
+|---|---|
+| [Hive Sink](./sink/Hive.md#常见问题) | 支持的文件格式、分区表、Kerberos 认证、小文件问题、Schema 演变 |
+
+---
+
+## 找答案的建议
+
+1. **Connector 特定问题** → 直接进入对应 Connector 页面，滚动到 **FAQ** 小节。
+2. **跨 Connector 通用问题**（如"SeaTunnel 是否支持 CDC？""什么是 `schema_save_mode`？"）→
查阅[通用 FAQ](../faq.md)。
+3. **仍未解决？** → 搜索 [GitHub Issues](https://github.com/apache/seatunnel/issues)
或通过[邮件列表](https://lists.apache.org/[email protected])联系社区。
diff --git a/docs/zh/connectors/sink/Clickhouse.md
b/docs/zh/connectors/sink/Clickhouse.md
index 2c49e2a2c3..827721724f 100644
--- a/docs/zh/connectors/sink/Clickhouse.md
+++ b/docs/zh/connectors/sink/Clickhouse.md
@@ -348,6 +348,27 @@ sink {
提交作业并执行成功后，我们可以看到 ClickHouse 数据表 `multi_sink_table1` 和 `multi_sink_table2`
的数据量都为100.
+## 常见问题
+
+### ClickHouse Sink 支持自动建表吗？
+
+支持。精确的模式和当前默认行为请以上面的 `schema_save_mode` 小节为准。如果需要自定义自动建表
+DDL，请使用 `save_mode_create_template`，不要在 FAQ 中再引入一套独立的 DDL 参数说法。
+
+### 如何调优批量写入性能？
+
+优先围绕 `bulk_size` 调优。精确的参数名和当前默认值已在上方 option 表中定义，因此吞吐调优时应以
+该表为准，而不是让 FAQ 再复制一份参数说明。
+
+### 支持哪些 ClickHouse 数据类型？
+
+SeaTunnel 可映射到 ClickHouse 的类型包括
`Int8/16/32/64`、`UInt8/16/32/64`、`Float32/64`、`Decimal`、`String`、`FixedString`、`Date`、`DateTime`、`Array`、`Map`
及其 `Nullable` 变体。复杂嵌套类型写入前可能需要通过 Transform 做转换。
+
+### 为什么提示"Table doesn't exist"错误？
+
+先看上面的 `schema_save_mode` 小节。如果你的环境允许缺表时自动创建，就沿用文档中定义好的
+自动建表流程；如果你的环境要求目标表必须预先存在，则显式切到更严格的模式，并在任务启动前先建表。
+
## 变更日志
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
diff --git a/docs/zh/connectors/sink/Doris.md b/docs/zh/connectors/sink/Doris.md
index dee3815346..319bcbe613 100644
--- a/docs/zh/connectors/sink/Doris.md
+++ b/docs/zh/connectors/sink/Doris.md
@@ -436,6 +436,62 @@ sink {
}
```
+## 常见问题
+
+### Doris Sink 支持自动建表吗？
+
+支持。精确行为、默认值以及 DDL 自定义入口，请以上面的 `schema_save_mode` 和
+`save_mode_create_template` 小节为准。
+
+### Doris Sink 如何实现精确一次（exactly-once）？
+
+Doris Sink 通过 Stream Load 两阶段提交（2PC）实现 exactly-once：
+
+```hocon
+sink {
+ Doris {
+ fenodes = "doris-fe:8030"
+ username = root
+ password = ""
+ database = "mydb"
+ table = "mytable"
+ sink.enable-2pc = "true"
+ sink.label-prefix = "unique-job-label"
+ }
+}
+```
+
+`sink.label-prefix` 必须全局唯一，以避免重试或重启时出现 label 冲突。
+
+### 为什么出现"Label already exists"错误？
+
+Doris 通过 Stream Load label 去重，防止重复提交。开启 2PC 后重启任务，可能复用相同的 label 前缀导致冲突。解决方法：
+
+- 在 `sink.label-prefix` 中加入时间戳或唯一标识，确保每次重启后 label 唯一。
+- 重启前在 Doris 中中止未提交的事务：`CANCEL LOAD WHERE LABEL LIKE 'your-prefix%'`。
+
+### Doris Sink 是否支持 CDC 的 DELETE 传播？
+
+支持。设置 `sink.enable-delete = "true"` 即可将 CDC 数据源（如 MySQL CDC）的 DELETE 事件传播到
Doris。目标表必须使用 Doris 的 **Unique Key** 模型。
+
+### Doris 列名是否区分大小写？
+
+请以上面的大小写敏感示例为准。如果上游字段名与 Doris 目标 schema 仍然对不上，应该在 sink 之前先
+做字段规范化，或直接调整目标 schema，而不是依赖并不存在的 `column_mapping` 选项。
+
+### Doris Stream Load 使用什么数据格式？
+
+默认使用 JSON 格式，可按需显式配置：
+
+```hocon
+doris.config {
+ format = "json"
+ read_json_by_line = "true"
+}
+```
+
+也支持 CSV 格式，但需要仔细配置分隔符。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/sink/Hive.md b/docs/zh/connectors/sink/Hive.md
index 4e2943750f..5869d55647 100644
--- a/docs/zh/connectors/sink/Hive.md
+++ b/docs/zh/connectors/sink/Hive.md
@@ -576,6 +576,54 @@ sink {
}
}
```
+## 常见问题
+
+### Hive Sink 支持哪些文件格式？
+
+Hive Sink 支持 `ORC`、`PARQUET`、`TEXT`、`JSON` 和 `SEQUENCE` 格式。通过
`file_format_type` 参数指定，需确保 Hive 表的 `STORED AS` 子句与配置的格式一致。
+
+### Hive Sink 是否支持分区表？
+
+支持。对于分区表，通过 `partition_by` 指定分区字段，SeaTunnel 会自动将数据写入正确的分区目录：
+
+```hocon
+sink {
+ Hive {
+ table_name = "mydb.sales"
+ metastore_uri = "thrift://hive-metastore:9083"
+ partition_by = ["dt", "region"]
+ }
+}
+```
+
+### 如何连接已启用 Kerberos 的 Hadoop 集群？
+
+在连接器配置中提供 Kerberos keytab 和 principal：
+
+```hocon
+sink {
+ Hive {
+ table_name = "mydb.events"
+ metastore_uri = "thrift://hive-metastore:9083"
+ kerberos_principal = "hive/[email protected]"
+ kerberos_keytab_path = "/etc/security/keytabs/hive.keytab"
+ krb5_path = "/etc/krb5.conf"
+ }
+}
+```
+
+### 为什么 Hive 表中产生了大量小文件？
+
+当任务并行度较高或批次较小时会产生大量小文件。减少小文件的方法：
+
+- 降低 `env` 块中的 `parallelism`。
+- 增大 `batch_size`，使每个 task 写入更大的文件。
+- 定期运行 `ALTER TABLE ... CONCATENATE` 或使用 Spark merge 任务合并小文件。
+
+### Hive Sink 是否支持 Schema 演变？
+
+Hive Sink 从 Hive Metastore 读取当前表 schema。若上游新增了列，需先手动执行 `ALTER TABLE` 更新 Hive
表结构，SeaTunnel 不会自动修改 Hive schema。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/sink/Jdbc.md b/docs/zh/connectors/sink/Jdbc.md
index 43d3d3240c..fb6f7075df 100644
--- a/docs/zh/connectors/sink/Jdbc.md
+++ b/docs/zh/connectors/sink/Jdbc.md
@@ -438,6 +438,70 @@ sink {
}
```
+## 常见问题
+
+### JDBC Sink 支持自动建表吗？
+
+支持。通过 `schema_save_mode` 参数控制建表行为：
+
+- `CREATE_SCHEMA_WHEN_NOT_EXIST`：表不存在时创建，已存在则跳过。
+- `RECREATE_SCHEMA`：每次任务启动时删除并重建表。
+- `ERROR_WHEN_SCHEMA_NOT_EXIST`：表不存在时抛出异常。
+- `IGNORE`：跳过所有建表逻辑。
+
+配合 `generate_sink_sql = true` 以及 `database`、`table` 参数可自动生成 INSERT/UPSERT SQL。
+
+### 如何用 JDBC Sink 实现精确一次（exactly-once）？
+
+JDBC Sink 通过 XA 事务支持 exactly-once：
+
+```hocon
+sink {
+ jdbc {
+ url = "jdbc:mysql://localhost:3306/mydb"
+ driver = "com.mysql.cj.jdbc.Driver"
+ user = "root"
+ password = "password"
+ is_exactly_once = true
+ xa_data_source_class_name = "com.mysql.cj.jdbc.MysqlXADataSource"
+ table = "target_table"
+ primary_keys = ["id"]
+ }
+}
+```
+
+不是所有数据库都支持 XA 事务，启用前请确认数据库和 JDBC 驱动均支持。
+
+### 如何配置 Upsert（INSERT OR UPDATE）行为？
+
+指定 `primary_keys` 即可启用 upsert。SeaTunnel 会根据目标数据库方言自动生成 `INSERT ... ON
DUPLICATE KEY UPDATE`（或等效）语句：
+
+```hocon
+sink {
+ jdbc {
+ url = "jdbc:mysql://localhost:3306/mydb"
+ driver = "com.mysql.cj.jdbc.Driver"
+ ...
+ primary_keys = ["id"]
+ }
+}
+```
+
+不设置 `primary_keys` 时，JDBC Sink 执行普通 INSERT，不处理主键冲突。
+
+### 如何在一个任务中写入多张表？
+
+使用 `table = "${table_name}"`、`database = "${schema_name}"` 占位符，SeaTunnel
会从上游记录的元数据中解析实际值（与 CDC 数据源或多表配置配合使用）。搭配 `generate_sink_sql = true` 可实现全自动 SQL
生成。
+
+### 为什么提示 JDBC 驱动未找到？
+
+SeaTunnel 出于许可证原因不内置所有 JDBC 驱动，需手动将驱动 JAR 放入 `$SEATUNNEL_HOME/lib/`。常用驱动：
+
+- MySQL：`mysql-connector-j-8.x.x.jar`
+- PostgreSQL：`postgresql-42.x.x.jar`
+- Oracle：`ojdbc8.jar`
+- SQL Server：`mssql-jdbc-12.x.x.jre11.jar`
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/sink/Kafka.md b/docs/zh/connectors/sink/Kafka.md
index 57bba9420c..ddad0db060 100644
--- a/docs/zh/connectors/sink/Kafka.md
+++ b/docs/zh/connectors/sink/Kafka.md
@@ -321,6 +321,61 @@ sink {
```
Note：key/value 需要 byte[]类型.
+## 常见问题
+
+### Kafka Sink 会自动创建 topic 吗？
+
+SeaTunnel Kafka Sink 本身不会主动创建 Kafka topic，只是向配置的 `topic` 写入数据。topic 是否自动创建取决于
Kafka Broker 的 `auto.create.topics.enable` 配置。
+
+生产环境中建议提前手动创建 topic，以便自行控制分区数、副本数、保留策略和 ACL。不要依赖自动创建，因为 Broker 可能已将
`auto.create.topics.enable` 设为 `false`。
+
+### 不配置 `partition_key_fields` 会怎样？
+
+若未设置 `partition_key_fields`，SeaTunnel 将以 **null** 作为 Kafka 消息 key 发送记录，Kafka
会使用默认的轮询策略将记录分散到各分区。
+
+这适合做负载均衡，但**不适合**需要相同业务 key 的记录落入同一分区以保证顺序的场景。如有顺序要求，请配置
`partition_key_fields`。
+
+### 如何实现精确一次（exactly-once）写入？
+
+将 `semantics` 设为 `EXACTLY_ONCE` 以启用精确一次语义，并配置 `transaction_prefix`
+为每个任务提供唯一的 Kafka 事务 ID 前缀。SeaTunnel 会将 Kafka 事务与 checkpoint 协调来实现 exactly-once：
+
+```hocon
+sink {
+ kafka {
+ topic = "output-topic"
+ bootstrap.servers = "localhost:9092"
+ semantics = EXACTLY_ONCE
+ transaction_prefix = "SeaTunnelJob"
+ kafka.transaction.timeout.ms = "900000"
+ }
+}
+```
+
+确保 Kafka Broker 开启了事务支持，且 `transaction.timeout.ms` 与 checkpoint 间隔相匹配。
+
+### 如何配置 SASL/Kerberos 认证？
+
+```hocon
+sink {
+ kafka {
+ topic = "secure-topic"
+ bootstrap.servers = "broker:9092"
+ kafka.security.protocol = "SASL_PLAINTEXT"
+ kafka.sasl.mechanism = "GSSAPI"
+ kafka.sasl.kerberos.service.name = "kafka"
+ kafka.sasl.jaas.config = """com.sun.security.auth.module.Krb5LoginModule
required
+ useKeyTab=true
+ keyTab="/etc/kafka/kafka.keytab"
+ principal="[email protected]";"""
+ }
+}
+```
+
+### Kafka Sink 支持哪些消息格式？
+
+支持：`json`、`text`、`canal_json`、`debezium_json`、`ogg_json`、`avro`、`protobuf` 和
`NATIVE`。当上游数据已经是带 headers、key 和 value 字节字段的 Kafka 原生格式时，使用 `NATIVE` 格式。
+
## 变更日志
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
diff --git a/docs/zh/connectors/sink/StarRocks.md
b/docs/zh/connectors/sink/StarRocks.md
index cf9722f832..575ed4b846 100644
--- a/docs/zh/connectors/sink/StarRocks.md
+++ b/docs/zh/connectors/sink/StarRocks.md
@@ -300,6 +300,56 @@ sink {
}
```
+## 常见问题
+
+### StarRocks Sink 支持自动建表吗？
+
+支持。通过 `schema_save_mode` 参数控制建表行为：
+
+- `CREATE_SCHEMA_WHEN_NOT_EXIST`：表不存在时创建，已存在则跳过。
+- `RECREATE_SCHEMA`：每次任务启动时删除并重建表。
+- `ERROR_WHEN_SCHEMA_NOT_EXIST`：表不存在时抛出异常。
+- `IGNORE`：跳过所有建表逻辑。
+
+SeaTunnel 会根据上游 schema 自动推断 StarRocks 列类型。
+
+### StarRocks Sink 是否支持 Upsert 和 DELETE 操作？
+
+支持。设置 `enable_upsert_delete = true` 可以传播 Upsert 和 DELETE 事件，目标 StarRocks
表必须使用**主键模型（Primary Key）**。来自 CDC 数据源的 DELETE 事件在开启此选项后可正确传播。
+
+### StarRocks Sink 中的 `labelPrefix` 是做什么的？
+
+当前 StarRocks Sink 页面并未将精确一次列为已支持的 Connector 能力。
+`labelPrefix` 用于控制 Sink 生成的 Stream Load label 前缀，保持此前缀稳定且全局唯一，
+可以减少重试或任务重启时的 label 冲突：
+
+```hocon
+sink {
+ StarRocks {
+ nodeUrls = ["starrocks-fe:8030"]
+ base-url = "jdbc:mysql://starrocks-fe:9030/"
+ username = root
+ password = ""
+ database = "mydb"
+ table = "mytable"
+ labelPrefix = "unique-job-label"
+ }
+}
+```
+
+正式契约请以本页的**主要特性**矩阵和 `labelPrefix` option 说明为准。
+
+### StarRocks 列名是否区分大小写？
+
+StarRocks 列名默认不区分大小写。请确认上游字段名与目标 StarRocks 列名的映射关系，避免意外的字段不匹配。
+
+### `nodeUrls` 和 `base-url` 有什么区别？
+
+- `nodeUrls`：StarRocks FE 节点的 HTTP 地址，用于 Stream Load 数据写入。
+- `base-url`：指向 StarRocks FE 节点的 JDBC URL，用于建表、查询 schema 等 DDL 操作。
+
+开启自动建表时两者均需配置。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/source/Kafka.md
b/docs/zh/connectors/source/Kafka.md
index 6e592c51f8..023f4087b3 100644
--- a/docs/zh/connectors/source/Kafka.md
+++ b/docs/zh/connectors/source/Kafka.md
@@ -525,6 +525,73 @@ source {
```
注意：key/value是byte[]类型。
+## 常见问题
+
+### `start_mode` 各取值有什么区别？
+
+| `start_mode` | 行为 |
+|---|---|
+| `earliest` | 从每个分区最早可用的 offset 开始消费 |
+| `latest` | 只消费任务启动后新产生的消息 |
+| `group_offsets` | 从消费组已提交的 offset 恢复消费 |
+| `specific_offsets` | 从每个分区指定的 offset 开始消费 |
+| `timestamp` | 从指定时间戳处或其后的第一条消息开始消费 |
+
+任务中断后重启时使用 `group_offsets` 恢复；需要从头重放全量数据时使用 `earliest`。
+
+### 如何按 Kafka 消息 key 过滤同一 topic 中的消息？
+
+将 `format` 设为 `"NATIVE"` 可以把 Kafka 原始元数据（包括 `key` 字段）作为记录的一部分暴露出来。再用 SQL
Transform 保留所需 key 值的消息：
+
+```hocon
+source {
+ Kafka {
+ topic = "events"
+ bootstrap.servers = "localhost:9092"
+ format = "NATIVE"
+ consumer.group = "my-group"
+ }
+}
+transform {
+ Sql {
+ plugin_input = "kafka_source"
+ plugin_output = "filtered"
+ query = "SELECT * FROM kafka_source WHERE key = 'expected_key_base64'"
+ }
+}
+```
+
+注意：NATIVE 格式中 `key` 字段为 base64 编码的字节数组。
+
+### Kafka Source 支持哪些消息格式？
+
+支持：`json`、`text`、`canal_json`、`debezium_json`、`ogg_json`、`avro`、`protobuf` 和
`NATIVE`。当需要将 Kafka 元数据（headers、key、partition、timestamp）作为记录字段使用时，选择 `NATIVE`
格式。
+
+### 如何配置 SASL/Kerberos 认证？
+
+通过 `kafka.*` 属性传入认证参数：
+
+```hocon
+source {
+ Kafka {
+ bootstrap.servers = "broker:9092"
+ topic = "secure-topic"
+ consumer.group = "my-group"
+ kafka.security.protocol = "SASL_PLAINTEXT"
+ kafka.sasl.mechanism = "GSSAPI"
+ kafka.sasl.kerberos.service.name = "kafka"
+ kafka.sasl.jaas.config = """com.sun.security.auth.module.Krb5LoginModule
required
+ useKeyTab=true
+ keyTab="/etc/kafka/kafka.keytab"
+ principal="[email protected]";"""
+ }
+}
+```
+
+### 消费组 offset 是如何提交的？
+
+SeaTunnel 在 checkpoint 完成时向 Kafka 提交 offset。需在 `env` 块中通过
`checkpoint.interval` 开启 checkpoint。使用 `start_mode = "group_offsets"`
重启任务时，将从上次 checkpoint 提交的 offset 恢复消费。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/source/MySQL-CDC.md
b/docs/zh/connectors/source/MySQL-CDC.md
index 78e8ac60f7..c08e6596ce 100644
--- a/docs/zh/connectors/source/MySQL-CDC.md
+++ b/docs/zh/connectors/source/MySQL-CDC.md
@@ -370,6 +370,59 @@ sink {
}
```
+## 常见问题
+
+### MySQL CDC 需要哪些权限？
+
+MySQL 用户需要以下权限：
+
+```sql
+GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON
*.* TO 'user'@'%';
+```
+
+同时需要在 `my.cnf` / `my.ini` 中开启 binlog：
+
+```ini
+[mysqld]
+log_bin = mysql-bin
+binlog_format = ROW
+binlog_row_image = FULL
+```
+
+### SeaTunnel 能从 MySQL 从库读取 CDC 数据吗？
+
+可以。SeaTunnel 通过订阅 binlog 工作，从库也有 binlog 流。将 SeaTunnel 指向从库可以减轻主库压力。需确保从库开启了
binlog，并在配置中设置 `log_slave_updates = ON`。
+
+### MySQL CDC 是否支持无主键表？
+
+默认要求主键。如果源表没有声明主键，但存在其他可唯一标识记录的列，可以像当前文档中的
+source options 示例那样，通过 `table-names-config.primaryKeys` 指定自定义主键。若没有稳定的
+唯一键，下游就无法安全处理 UPDATE / DELETE 事件。
+
+### 全量快照阶段如何工作？何时切换为增量读取？
+
+首次启动时，SeaTunnel 对已配置的表做一次一致性全量快照。快照完成后，自动从快照开始时记录的 binlog
位置切换为增量读取，确保切换过程中不丢失任何变更事件。
+
+### MySQL CDC 是否支持 DDL 传播？
+
+支持，但能力有限。需要启用 `schema-changes.enabled = true`，并遵循当前页面以及
+[Schema Evolution
文档](../../introduction/configuration/schema-evolution.md)中已经定义好的契约。
+目前文档中明确支持 `add column`、`drop column`、`rename column` 和 `modify column`。
+
+### 运行多个 CDC 任务时如何避免 `server-id` 冲突？
+
+每个 CDC 任务必须使用唯一的 `server-id` 或不重叠的范围。重复的 `server-id` 会导致 MySQL
服务器断开其中一个客户端连接。建议为每个任务分配独立的范围，例如一个任务用 `5400-5600`，另一个用 `5601-5800`。
+
+### 初始快照为什么很慢？
+
+快照速度取决于表大小、JDBC fetch size 和网络带宽。可以通过调整 `snapshot.split.size`
+和 `snapshot.fetch.size` 来控制快照切分与抓取行为。对于不需要历史数据的大表，可将
+`startup.mode` 设为 `"latest"`，从最新 offset 启动并跳过初始快照。
+
+### 如何处理时区和字符集问题？
+
+将 `server-time-zone` 设置为与 MySQL 服务器一致的时区，例如 `"Asia/Shanghai"`。字符集问题可通过在 JDBC
连接 URL 中追加 `characterEncoding=UTF-8&useUnicode=true` 来解决。
+
## 另请参阅
若需要一份面向生产的端到端实践指南，涵盖全量 + 增量同步生命周期、2PC sink 配置、Schema 演进与常见故障排查，请参阅 [CDC
生产实战手册](../cdc-production-cookbook.md)。
diff --git a/docs/zh/connectors/source/Oracle-CDC.md
b/docs/zh/connectors/source/Oracle-CDC.md
index 6bcaf201c1..d542a5057f 100644
--- a/docs/zh/connectors/source/Oracle-CDC.md
+++ b/docs/zh/connectors/source/Oracle-CDC.md
@@ -366,6 +366,63 @@ source {
> 必须与 kafka 连接器 sink 配合使用，详情请参阅 [兼容 debezium
> 格式](../formats/cdc-compatible-debezium-json.md)
+## 常见问题
+
+### Oracle CDC 需要哪些数据库权限？
+
+LogMiner 用户需要以下权限：
+
+```sql
+GRANT CREATE SESSION TO logminer_user;
+GRANT SET CONTAINER TO logminer_user;
+GRANT SELECT ON V_$DATABASE TO logminer_user;
+GRANT FLASHBACK ANY TABLE TO logminer_user;
+GRANT SELECT ANY TABLE TO logminer_user;
+GRANT SELECT_CATALOG_ROLE TO logminer_user;
+GRANT EXECUTE_CATALOG_ROLE TO logminer_user;
+GRANT SELECT ANY TRANSACTION TO logminer_user;
+GRANT LOGMINING TO logminer_user;
+GRANT CREATE TABLE TO logminer_user;
+GRANT LOCK ANY TABLE TO logminer_user;
+GRANT CREATE SEQUENCE TO logminer_user;
+GRANT EXECUTE ON DBMS_LOGMNR TO logminer_user;
+GRANT EXECUTE ON DBMS_LOGMNR_D TO logminer_user;
+GRANT SELECT ON V_$LOG TO logminer_user;
+GRANT SELECT ON V_$LOG_HISTORY TO logminer_user;
+GRANT SELECT ON V_$LOGMNR_LOGS TO logminer_user;
+GRANT SELECT ON V_$LOGMNR_CONTENTS TO logminer_user;
+GRANT SELECT ON V_$LOGMNR_PARAMETERS TO logminer_user;
+GRANT SELECT ON V_$LOGFILE TO logminer_user;
+GRANT SELECT ON V_$ARCHIVED_LOG TO logminer_user;
+GRANT SELECT ON V_$ARCHIVE_DEST_STATUS TO logminer_user;
+GRANT SELECT ON V_$TRANSACTION TO logminer_user;
+```
+
+同时，需要在数据库和表级别开启附加日志：
+
+```sql
+ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
+ALTER TABLE schema_name.table_name ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;
+```
+
+### Oracle CDC 是否支持多租户（CDB/PDB）数据库？
+
+支持。将 `database-names` 设置为 CDB 名称，并将 JDBC URL 指向 CDB 根容器。用户必须是公共用户（以 `C##`
为前缀），且需在所有容器中以 `CONTAINER = ALL` 方式授予上述权限。
+
+### Oracle CDC 是否支持无主键表？
+
+默认情况下，Oracle CDC 需要主键。如果表中存在合适的唯一列，可通过 `table-names-config` 中的 `primaryKeys`
字段指定自定义主键列。
+
+### 如何提升 LogMiner 性能？
+
+首先把它当作数据库和 redo log 调优问题处理。优先复用上面的 LogMiner 配置和 supplemental
+logging 章节，只为需要采集的表开启日志；只有在确认目标 Oracle CDC 运行时确实支持相应
+Debezium 透传属性后，再引入额外调优参数。
+
+### 支持哪些 Oracle 版本？
+
+Oracle CDC 支持 Oracle Database 11g、12c、19c 和 21c。对于 12c 及更高版本的多租户配置，需使用 CDB
根连接和公共用户。
+
## 另请参阅
若需要一份面向生产的端到端实践指南，涵盖全量 + 增量同步生命周期、2PC sink 配置、Schema 演进与常见故障排查，请参阅 [CDC
生产实战手册](../cdc-production-cookbook.md)。
diff --git a/docs/zh/connectors/source/PostgreSQL-CDC.md
b/docs/zh/connectors/source/PostgreSQL-CDC.md
index 4e6cc5559c..134afd2959 100644
--- a/docs/zh/connectors/source/PostgreSQL-CDC.md
+++ b/docs/zh/connectors/source/PostgreSQL-CDC.md
@@ -190,6 +190,41 @@ source {
}
```
+## 常见问题
+
+### PostgreSQL CDC 需要哪些权限？
+
+CDC 用户需要具备 `REPLICATION` 角色以及对监控表的 `SELECT` 权限：
+
+```sql
+CREATE USER replication_user REPLICATION LOGIN PASSWORD 'password';
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
+```
+
+同时需要在 `postgresql.conf` 中设置 `wal_level = logical`，并在 `pg_hba.conf`
中添加允许该用户复制连接的条目。
+
+### 支持哪些逻辑解码插件？
+
+SeaTunnel PostgreSQL CDC 支持 `pgoutput`（PostgreSQL 10 起内置）、`wal2json` 和
`decoderbufs`，默认使用 `pgoutput`。通过 `decoding.plugin.name` 参数指定插件。
+
+### SeaTunnel 能从 PostgreSQL 备库读取 CDC 数据吗？
+
+不能。PostgreSQL 逻辑复制槽必须在主库上创建和消费，SeaTunnel 无法直接从备库读取逻辑复制槽，需将 CDC 连接器指向主库实例。
+
+### PostgreSQL CDC 是否支持无主键表？
+
+默认需要主键。如果表有可作为唯一标识的列，可以通过 `table-names-config` 中的 `primaryKeys` 字段自定义主键。
+
+### 复制槽如何管理？
+
+SeaTunnel 在任务启动时会创建或复用 `slot.name` 指定的复制槽。未使用的复制槽会持续占用
+磁盘上的 WAL 段，导致 WAL 持续增长。当 CDC 任务永久下线时，应在 PostgreSQL 侧手动删除
+不再使用的复制槽。
+
+### PostgreSQL CDC 为什么会滞后？
+
+滞后可能由逻辑解码插件处理慢或 WAL sender 负载过高引起。可通过监控 `pg_replication_slots` 中的
`confirmed_flush_lsn` 漂移情况来排查。确保 CDC 任务持续消费事件，并保持 SeaTunnel 与 PostgreSQL
之间的网络低延迟。
+
## 另请参阅
若需要一份面向生产的端到端实践指南，涵盖全量 + 增量同步生命周期、2PC sink 配置、Schema 演进与常见故障排查，请参阅 [CDC
生产实战手册](../cdc-production-cookbook.md)。
