This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 5571e39f Add etcd usage guide (#356)
5571e39f is described below
commit 5571e39f41a47da872b0f1eb3cff04223b24ec9c
Author: SweetWuXiaoMei <[email protected]>
AuthorDate: Sat Nov 16 22:44:45 2024 +0800
Add etcd usage guide (#356)
---
java-chassis-reference/zh_CN/docs/config/etcd.md | 85 +++++++++++++
java-chassis-reference/zh_CN/docs/registry/etcd.md | 134 +++++++++++++++++++++
java-chassis-reference/zh_CN/mkdocs.yml | 2 +
3 files changed, 221 insertions(+)
diff --git a/java-chassis-reference/zh_CN/docs/config/etcd.md
b/java-chassis-reference/zh_CN/docs/config/etcd.md
new file mode 100644
index 0000000..0637540
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/config/etcd.md
@@ -0,0 +1,85 @@
+# 使用 etcd
+
+## 下载安装
+
+可以通过 [Etcd官网](https://etcd.io/docs/v3.5/install/) 下载和安装 Etcd。
+
+## 开发使用
+
+使用etcd，需要在项目中引入如下依赖：
+
+```xml
+<dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>config-etcd</artifactId>
+ <version>x.x.x</version>
+</dependency>
+```
+
+然后在配置文件 microservice.yaml 中增加如下配置项：
+
+```yaml
+servicecomb:
+ config:
+ etcd:
+ connectString: http://127.0.0.1:2379
+```
+
+* 配置中心增加配置
+
+etcd 使用下面的配置结构和环境（Environment）、应用（Application）、服务（Service）、版本（Version）、Tag对应，
配置级别优先级从低到高。
+
+```yaml
+servicecomb:
+ config:
+ environment:
+ ${environment}:
+ exampleText: exampleTextValue
+ exampleYaml.yaml: exampleYamlValue
+ exampleYaml.yml: exampleYamlValue
+ exampleProperties.properties: examplePropertiesValue
+ application:
+ ${environment}:
+ ${application}:
+ exampleText: exampleTextValue
+ exampleYaml.yaml: exampleYamlValue
+ exampleYaml.yml: exampleYamlValue
+ exampleProperties.properties: examplePropertiesValue
+ service:
+ ${environment}:
+ ${application}:
+ ${service}:
+ exampleText: exampleTextValue
+ exampleYaml.yaml: exampleYamlValue
+ exampleYaml.yml: exampleYamlValue
+ exampleProperties.properties: examplePropertiesValue
+ version:
+ ${environment}:
+ ${application}:
+ ${service}:
+ ${version}:
+ exampleText: exampleTextValue
+ exampleYaml.yaml: exampleYamlValue
+ exampleYaml.yml: exampleYamlValue
+ exampleProperties.properties: examplePropertiesValue
+ tag:
+ ${environment}:
+ ${application}:
+ ${service}:
+ ${version}:
+ ${tag}:
+ exampleText: exampleTextValue
+ exampleYaml.yaml: exampleYamlValue
+ exampleYaml.yml: exampleYamlValue
+ exampleProperties.properties: examplePropertiesValue
+```
+
+配置文件的类型根据KEY的后缀确定。目前会解析 `.yaml`、`.yml`、`.properties`后缀，其他情况钧视为普通的key-value对。
+
+* 配置项参考
+
+| 配置项名 | 默认值 | 是否必须 | 含义
|
+|-----------------------------------------------|----------------|------|-----------------------------------------------|
+| servicecomb.config.etcd.connect-string | http://127.0.0.1:2379 | 是
| etcd的地址信息，可以配置多个，用逗号分隔。 |
+| servicecomb.config.etcd.authenticationInfo | 空 | 否 |
当认证方式为 digest 的时候，配置用户名密码信息，比如: user:password |
+| servicecomb.config.etcd.instance-tag | 空 | 否 |
实例的TAG信息，用于TAG级别的配置查询 |
diff --git a/java-chassis-reference/zh_CN/docs/registry/etcd.md
b/java-chassis-reference/zh_CN/docs/registry/etcd.md
new file mode 100644
index 0000000..8e3e137
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/registry/etcd.md
@@ -0,0 +1,134 @@
+# 使用 etcd
+
+可以通过 [Etcd官网](https://etcd.io/docs/v3.5/install/) 下载和安装 Etcd。
+
+使用Etcd需要确保下面的软件包引入：
+
+```
+<dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>registry-etcd</artifactId>
+ <version>x.x.x</version>
+</dependency>
+```
+
+* 表1-1 访问Etcd常用的配置项
+
+| 配置项 | 默认值 | 是否必选 |
含义 |
+|:--------------------------------------------------|:---------------|:-----|:-----------------------------------|
+| servicecomb.registry.etcd.enabled | true | 是
| 是否启用。 |
+| servicecomb.registry.etcd.connectString | http://127.0.0.1:2379
| 是 | etcd的地址信息，可以配置多个，用逗号分隔。 |
+| servicecomb.registry.etcd.authenticationInfo | 空 | 否
| etcd认证，配置用户名密码信息，比如: user:password |
+| servicecomb.registry.etcd.enableSwaggerRegistration | false | 否
| 是否注册契约 |
+
+## etcd使用认证
+
+在 etcd 中启用和配置认证需要进行以下步骤：
+
+#### 1. 启用 etcd 认证
+
+首先需要确保 etcd 已经正常运行，然后按以下步骤启用认证功能：
+
+##### 1.1 启动 etcd 服务
+
+确保 etcd 服务已启动，监听所需的端口（如 2379 和 2380）。可以使用 etcdctl 进行操作。
+
+---
+
+#### 2. 添加用户
+
+使用 etcdctl 添加一个用户并设置密码。例如，添加一个用户 root：
+
+etcdctl user add root
+
+执行上述命令后，会提示输入并确认密码。
+
+---
+
+#### 3. 为用户分配角色
+
+为用户分配一个角色，可以是已有角色，也可以新建一个。以下是新建角色并分配权限的示例：
+
+##### 3.1 创建角色
+
+etcdctl role add rootrole
+
+##### 3.2 分配权限
+
+为 rootrole 分配对所有键的读写权限：
+
+etcdctl role grant-permission rootrole readwrite /
+
+##### 3.3 关联用户和角色
+
+将用户 root 与角色 rootrole 关联：
+
+etcdctl user grant-role root rootrole
+
+---
+
+#### 4. 启用认证
+
+完成用户和角色的配置后，启用 etcd 认证：
+
+etcdctl auth enable
+
+注意：启用认证后，所有的 etcd 操作都需要进行认证，包括通过 API 或客户端命令。
+
+---
+
+#### 5. 使用认证进行操作
+
+认证启用后，所有 etcdctl 命令都需要指定用户名和密码。例如：
+
+etcdctl --user=root:yourpassword put foo bar
+etcdctl --user=root:yourpassword get foo
+
+---
+
+#### 6. 其他用户与角色管理
+
+添加新用户
+
+etcdctl user add newuser
+
+创建新角色
+
+etcdctl role add newrole
+
+分配权限给新角色
+
+etcdctl role grant-permission newrole readwrite /example-prefix
+
+将用户与角色关联
+
+etcdctl user grant-role newuser newrole
+
+7. 注意事项
+
+ 1. 安全性：为保证安全，避免在生产中使用默认用户 root，可以创建其他用户并分配特定权限。
+ 2. TLS 加密：推荐在启用认证的同时启用 TLS，以加密数据传输。
+ 3. 高可用场景：如果使用 etcd 集群，确保所有节点的认证配置保持一致。
+
+示例配置 (全流程)
+
+以下是完整操作流程的一个示例：
+
+###### 添加用户 root
+etcdctl user add root
+
+###### 创建角色 rootrole
+etcdctl role add rootrole
+
+###### 分配读写权限给 rootrole
+etcdctl role grant-permission rootrole readwrite /
+
+###### 将 root 用户关联到 rootrole
+etcdctl user grant-role root rootrole
+
+###### 启用认证
+etcdctl auth enable
+
+###### 使用认证操作
+etcdctl --user=root:yourpassword put foo bar
+etcdctl --user=root:yourpassword get foo
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml
b/java-chassis-reference/zh_CN/mkdocs.yml
index 2f9bd58..d39f9e3 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -69,6 +69,7 @@ nav:
- 使用Service Center: registry/service-center.md
- 使用Nacos: registry/nacos.md
- 使用ZooKeeper: registry/zookeeper.md
+ - 使用Etcd: registry/etcd.md
- 本地注册发现: registry/local-registry.md
- 去中心化注册发现: registry/distributed.md
- 多样化的配置管理功能:
@@ -77,6 +78,7 @@ nav:
- 使用Kie: config/kie.md
- 使用Nacos: config/nacos.md
- 使用Zookeeper: config/zookeeper.md
+ - 使用Etcd: config/etcd.md
- 使用Apollo: config/apollo.md
- 使用CSE1.0配置中心: config/cse1.md
- 服务治理功能参考:
