ben/mgmt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

添加Consul变量和存储配置功能

Browse Source 
- 添加Consul变量和存储配置指南文档
- 创建Consul变量配置示例脚本
- 创建Consul备份脚本
- 添加Consul完整配置文件
- 完善Vault集群初始化和开发环境配置脚本
- 添加Vault安全策略文档

这些配置将增强Consul集群的功能性，提供灵活的配置管理和数据持久化能力。
This commit is contained in:
Houzhong Xu
2025-09-30 04:57:44 +00:00
parent e8bfc76038
commit 7ea230b072
12 changed files with 1699 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

420
docs/setup/consul_variables_and_storage_guide.md Normal file
View File

@@ -0,0 +1,420 @@
# Consul 变量和存储配置指南
本文档介绍如何配置Consul的变量(Variables)和存储(Storage)功能，以增强集群的功能性和可靠性。
## 概述
Consul提供了两种关键功能来增强集群能力：
1. **变量(Variables)**: 用于存储配置信息、特性开关、应用参数等
2. **存储(Storage)**: 用于持久化数据、快照和备份
## 变量(Variables)配置
### 变量命名规范
我们遵循统一的命名规范来管理Consul KV存储中的配置：
```
config/{environment}/{provider}/{region_or_service}/{key}
```
各部分说明：
- **config**: 固定前缀，表示这是一个配置项
- **environment**: 环境名称，如 `dev`、`staging`、`prod` 等
- **provider**: 云服务提供商，如 `oracle`、`digitalocean`、`aws`、`gcp` 等
- **region_or_service**: 区域或服务名称，如 `kr`、`us`、`sgp` 等
- **key**: 具体的配置键名，如 `token`、`tenancy_ocid`、`user_ocid` 等
### 示例配置
#### 应用配置
```
config/dev/app/name
config/dev/app/version
config/dev/app/environment
```
#### 数据库配置
```
config/dev/database/host
config/dev/database/port
config/dev/database/name
```
#### 缓存配置
```
config/dev/cache/host
config/dev/cache/port
```
#### 特性开关
```
config/dev/features/new_ui
config/dev/features/advanced_analytics
```
### 如何添加变量
#### 使用curl命令
```bash
# 添加单个变量
curl -X PUT http://localhost:8500/v1/kv/config/dev/app/name -d "my-application"
# 添加多个变量
curl -X PUT http://localhost:8500/v1/kv/config/dev/database/host -d "db.example.com"
curl -X PUT http://localhost:8500/v1/kv/config/dev/database/port -d "5432"
```
#### 使用consul CLI
```bash
# 添加单个变量
consul kv put config/dev/app/name my-application
# 添加多个变量
consul kv put config/dev/database/host db.example.com
consul kv put config/dev/database/port 5432
```
#### 使用自动化脚本
我们提供了自动化脚本来配置Consul变量：
```bash
# 运行配置脚本
./deployment/scripts/setup_consul_variables_and_storage.sh
```
### 如何使用变量
#### 在Terraform中使用
```hcl
data "consul_keys" "app_config" {
key {
name = "app_name"
path = "config/dev/app/name"
}
key {
name = "db_host"
path = "config/dev/database/host"
}
}
resource "some_resource" "example" {
name = data.consul_keys.app_config.var.app_name
host = data.consul_keys.app_config.var.db_host
}
```
#### 在应用程序中使用
大多数Consul客户端库都提供了读取KV存储的方法。例如，在Go中：
```go
import "github.com/hashicorp/consul/api"
// 创建Consul客户端
client, _ := api.NewClient(api.DefaultConfig())
// 读取KV
kv := client.KV()
pair, _, _ := kv.Get("config/dev/app/name", nil)
appName := string(pair.Value)
```
## 存储(Storage)配置
### 持久化存储
Consul需要持久化存储来保存Raft日志和快照数据。在Nomad作业配置中，我们已经指定了数据目录：
```hcl
config {
command = "consul"
args = [
"agent",
"-server",
"-bootstrap-expect=3",
"-data-dir=/opt/nomad/data/consul", # 数据目录
# 其他参数...
]
}
```
### 快照配置
快照是Consul集群状态的时间点备份，用于灾难恢复。
#### 启用快照
在Consul配置文件中添加以下配置：
```hcl
snapshot {
enabled = true
interval = "24h" # 每24小时创建一次快照
retain = 30 # 保留30个快照
name = "consul-snapshot-{{.Timestamp}}"
}
```
#### 手动创建快照
```bash
# 创建快照
consul snapshot save backup-$(date +%Y%m%d).snap
# 恢复快照
consul snapshot restore backup-20231201.snap
```
### 备份配置
定期备份Consul数据是确保数据安全的重要措施。
#### 配置自动备份
```hcl
backup {
enabled = true
interval = "6h" # 每6小时备份一次
retain = 7 # 保留7个备份
name = "consul-backup-{{.Timestamp}}"
}
```
#### 备份脚本
```bash
#!/bin/bash
# backup_consul.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/consul"
CONSUL_ADDR="http://localhost:8500"
# 创建备份目录
mkdir -p $BACKUP_DIR
# 创建快照
curl -s "${CONSUL_ADDR}/v1/snapshot" > "${BACKUP_DIR}/consul-snapshot-${DATE}.snap"
# 保留最近7天的备份
find $BACKUP_DIR -name "consul-snapshot-*.snap" -mtime +7 -delete
echo "备份完成: ${BACKUP_DIR}/consul-snapshot-${DATE}.snap"
```
### Autopilot配置
Autopilot是Consul的自动管理功能，用于处理服务器故障和自动恢复。
```hcl
autopilot {
cleanup_dead_servers = true # 自动清理死服务器
last_contact_threshold = "200ms" # 最后联系阈值
max_trailing_logs = 250 # 最大 trailing 日志数
server_stabilization_time = "10s" # 服务器稳定时间
redundancy_zone_tag = "" # 冗余区域标签
disable_upgrade_migration = false # 禁用升级迁移
upgrade_version_tag = "" # 升级版本标签
}
```
## 完整配置示例
### Consul配置文件 (consul.hcl)
```hcl
# 基础配置
data_dir = "/opt/consul/data"
raft_dir = "/opt/consul/raft"
# 启用UI
ui_config {
enabled = true
}
# 数据中心配置
datacenter = "dc1"
# 服务器配置
server = true
bootstrap_expect = 3
# 网络配置
client_addr = "0.0.0.0"
bind_addr = "{{ GetInterfaceIP `eth0` }}"
advertise_addr = "{{ GetInterfaceIP `eth0` }}"
# 端口配置
ports {
dns = 8600
http = 8500
https = -1
grpc = 8502
grpc_tls = 8503
serf_lan = 8301
serf_wan = 8302
server = 8300
}
# 集群连接
retry_join = ["100.117.106.136", "100.116.80.94", "100.122.197.112"]
# 服务发现
enable_service_script = true
enable_script_checks = true
enable_local_script_checks = true
# 性能调优
performance {
raft_multiplier = 1
}
# 日志配置
log_level = "INFO"
enable_syslog = false
log_file = "/var/log/consul/consul.log"
# 安全配置
encrypt = "YourEncryptionKeyHere"
# 连接配置
reconnect_timeout = "30s"
reconnect_timeout_wan = "30s"
session_ttl_min = "10s"
# Autopilot配置
autopilot {
cleanup_dead_servers = true
last_contact_threshold = "200ms"
max_trailing_logs = 250
server_stabilization_time = "10s"
redundancy_zone_tag = ""
disable_upgrade_migration = false
upgrade_version_tag = ""
}
# 快照配置
snapshot {
enabled = true
interval = "24h"
retain = 30
name = "consul-snapshot-{{.Timestamp}}"
}
# 备份配置
backup {
enabled = true
interval = "6h"
retain = 7
name = "consul-backup-{{.Timestamp}}"
}
```
## 部署步骤
### 1. 准备配置文件
```bash
# 创建配置目录
mkdir -p /root/mgmt/components/consul/configs
# 创建配置文件
cat > /root/mgmt/components/consul/configs/consul.hcl << EOF
# 粘贴上面的完整配置示例
EOF
```
### 2. 运行配置脚本
```bash
# 运行自动化脚本
./deployment/scripts/setup_consul_variables_and_storage.sh
```
### 3. 重启Consul服务
```bash
# 停止Consul服务
nomad job stop consul-cluster-simple
# 重新启动Consul服务
nomad job run /root/mgmt/components/consul/jobs/consul-cluster-simple.nomad
```
### 4. 验证配置
```bash
# 检查Consul状态
curl http://localhost:8500/v1/status/leader
# 检查变量配置
curl -s http://localhost:8500/v1/kv/config/dev/?recurse | jq
# 检查存储配置
curl -s http://localhost:8500/v1/kv/storage/?recurse | jq
```
## 最佳实践
1. **定期备份**: 设置定期备份Consul数据，并测试恢复过程
2. **监控存储空间**: 监控Consul数据目录的使用情况，避免磁盘空间不足
3. **安全配置**: 使用ACL和TLS保护Consul集群
4. **版本控制**: 将Consul配置文件纳入版本控制系统
5. **环境隔离**: 为不同环境(dev/staging/prod)使用不同的配置路径
6. **文档记录**: 记录所有配置项的用途和取值范围
## 故障排除
### 常见问题
#### 1. 变量无法读取
- 检查Consul服务是否正常运行
- 验证变量路径是否正确
- 确认ACL权限是否足够
#### 2. 存储空间不足
- 检查数据目录大小
- 调整快照和备份保留策略
- 清理旧快照和备份
#### 3. 快照失败
- 检查磁盘空间
- 验证文件权限
- 查看Consul日志获取详细错误信息
### 调试命令
```bash
# 查看Consul成员
consul members
# 查看Raft状态
consul operator raft list-peers
# 查看键值存储
consul kv get --recurse config/dev/
# 查看快照信息
consul snapshot inspect backup.snap
```
## 扩展功能
### 与Vault集成
Consul可以与Vault集成，提供更强大的密钥管理功能：
```bash
# 配置Vault作为Consul的加密后端
vault secrets enable consul
# 配置Consul使用Vault进行加密
consul encrypt -vault-token="$VAULT_TOKEN" -vault-addr="$VAULT_ADDR"
```
### 与Nomad集成
Consul可以与Nomad集成，提供服务发现和配置管理：
```hcl
# Nomad配置中的Consul集成
consul {
address = "localhost:8500"
token = "your-consul-token"
ssl = false
}
```
## 总结
通过配置Consul的变量和存储功能，可以显著增强集群的功能性和可靠性。变量功能提供了灵活的配置管理，而存储功能确保了数据的安全性和持久性。结合自动化脚本和最佳实践，可以构建一个强大且易于维护的Consul集群。

112
docs/vault-dev-environment.md Normal file
View File

@@ -0,0 +1,112 @@
# Vault开发环境指南
## 1. 概述
本文档介绍了如何在开发环境中使用Vault，包括初始化、密钥管理和基本操作。
## 2. 开发环境特点
- 使用1个解封密钥（简化操作）
- 所有密钥存储在本地开发目录
- 适用于快速测试和开发
**注意**：此配置仅用于开发环境，生产环境请遵循安全策略文档。
## 3. 初始化Vault
### 3.1 运行初始化脚本
```bash
/root/mgmt/deployment/scripts/init_vault_dev.sh
```
脚本将：
1. 初始化Vault集群
2. 生成1个解封密钥和根令牌
3. 自动解封所有节点
4. 保存环境变量配置
### 3.2 查看密钥信息
```bash
/root/mgmt/deployment/scripts/show_vault_dev_keys.sh
```
## 4. 使用Vault
### 4.1 设置环境变量
```bash
source /root/mgmt/security/secrets/vault/dev/vault_env.sh
```
### 4.2 基本操作示例
```bash
# 检查状态
vault status
# 写入密钥值
vault kv put secret/myapp/config username="devuser" password="devpassword"
# 读取密钥值
vault kv get secret/myapp/config
```
### 4.3 运行完整示例
```bash
/root/mgmt/deployment/scripts/vault_dev_example.sh
```
## 5. 目录结构
```
/root/mgmt/security/secrets/vault/dev/
├── init_keys.json # 初始化密钥（解封密钥和根令牌）
├── vault_env.sh # 环境变量配置
```
## 6. 重要提醒
### 6.1 开发环境限制
- 仅使用1个解封密钥（生产环境应使用5个密钥中的3个阈值）
- 密钥存储在本地文件系统（生产环境应分散存储）
- 适用于单人开发测试
### 6.2 生产环境迁移
当从开发环境迁移到生产环境时：
1. 重新初始化Vault集群
2. 使用5个解封密钥中的3个阈值
3. 将密钥分发给不同管理员
4. 遵循安全策略文档
## 7. 故障排除
### 7.1 Vault未初始化
运行初始化脚本：
```bash
/root/mgmt/deployment/scripts/init_vault_dev.sh
```
### 7.2 Vault已初始化但被密封
使用解封密钥解封：
```bash
export VAULT_ADDR='http://<节点IP>:8200'
vault operator unseal <解封密钥>
```
### 7.3 无法连接到Vault
检查Vault服务状态：
```bash
curl -v http://<节点IP>:8200/v1/sys/health
```
## 8. 清理环境
如需重新开始，可以删除密钥文件并重新初始化：
```bash
rm -f /root/mgmt/security/secrets/vault/dev/init_keys.json
/root/mgmt/deployment/scripts/init_vault_dev.sh
```
## 9. 相关文档
- [Vault安全策略](vault-security-policy.md) - 生产环境安全指南
- [Vault官方文档](https://www.vaultproject.io/docs)
- [Vault API文档](https://www.vaultproject.io/api)

139
docs/vault-security-policy.md Normal file
View File

@@ -0,0 +1,139 @@
# Vault安全策略和密钥管理指南
## 1. 概述
本文档定义了Vault密钥的安全管理策略，确保基础设施的安全性和可靠性。
## 2. 密钥类型
### 2.1 初始化密钥
- **解封密钥**：用于解封Vault实例
- **根令牌**：具有Vault中所有权限的初始令牌
### 2.2 操作密钥
- **用户令牌**：分配给用户和服务的访问令牌
- **策略令牌**：基于特定策略的受限令牌
## 3. 安全存储策略
### 3.1 解封密钥存储
**禁止**：
- 将所有密钥存储在同一位置
- 在代码或配置文件中明文存储密钥
- 通过不安全的通信渠道传输密钥
**推荐**：
1. **物理分发**：
- 将5个解封密钥分别交给5个不同的可信管理员
- 每个管理员仅知道自己的密钥
- 需要3个密钥即可解封Vault（Shamir's Secret Sharing）
2. **加密存储**：
- 使用GPG或其他加密工具加密密钥文件
- 将加密后的文件存储在安全位置
- 加密密钥由不同管理员保管
3. **硬件安全模块**：
- 企业环境推荐使用HSM存储密钥
- 提供硬件级别的安全保护
### 3.2 根令牌存储
- 根令牌应立即用于创建具有最小权限的管理令牌
- 创建后应立即撤销根令牌
- 新的管理令牌应根据职责分离原则分发
## 4. 密钥生命周期管理
### 4.1 创建
- 初始化时生成密钥
- 立即按照安全策略分发和存储
- 记录密钥创建时间和负责人
### 4.2 使用
- 仅在必要时使用解封密钥
- 定期轮换用户和服务令牌
- 监控密钥使用情况
### 4.3 更新
- 定期重新初始化Vault以生成新密钥（谨慎操作）
- 当管理员变更时更新密钥分发
- 发生安全事件时立即重新生成密钥
### 4.4 销毁
- 安全删除不再需要的密钥副本
- 使用安全删除工具确保数据不可恢复
- 记录密钥销毁时间和负责人
## 5. 应急响应
### 5.1 密钥泄露
1. 立即生成新的解封密钥
2. 重新初始化Vault集群
3. 更新所有依赖Vault的服务配置
4. 调查泄露原因并修复安全漏洞
### 5.2 管理员不可用
1. 确保有足够的密钥持有者可用（至少3人）
2. 建立备用密钥持有者列表
3. 定期验证密钥持有者的可用性
## 6. 审计和合规
### 6.1 审计要求
- 记录所有密钥相关操作
- 定期审查密钥管理策略执行情况
- 生成密钥使用报告
### 6.2 合规性
- 遵循组织安全政策
- 满足行业标准要求（如SOC 2, ISO 27001等）
- 定期进行安全评估
## 7. 实施步骤
### 7.1 初始化Vault
```bash
# 使用提供的脚本初始化Vault
/root/mgmt/deployment/scripts/init_vault_cluster.sh
```
### 7.2 安全分发密钥
1. 将生成的密钥文件复制到安全位置
2. 将密钥文件加密并分发给不同管理员
3. 验证每个管理员都能正确解封Vault
### 7.3 创建管理令牌
```bash
# 使用根令牌创建管理令牌
export VAULT_ADDR='http://<节点IP>:8200'
export VAULT_TOKEN=<root_token>
vault token create -policy=admin -period=24h
```
### 7.4 撤销根令牌
```bash
# 撤销根令牌以提高安全性
vault token revoke <root_token>
```
## 8. 最佳实践
### 8.1 访问控制
- 实施最小权限原则
- 使用策略限制令牌权限
- 定期审查和更新策略
### 8.2 监控和告警
- 监控Vault解封和密封事件
- 设置密钥使用异常告警
- 定期生成安全报告
### 8.3 备份和恢复
- 定期备份Vault数据
- 测试恢复流程
- 确保备份数据的安全性
## 9. 相关文档
- [Vault官方安全指南](https://www.vaultproject.io/docs/internals/security)
- [HashiCorp安全模型](https://www.hashicorp.com/security)
- 组织内部安全政策