OCDP/ocdp-go

Fork 0

Files

mangomqy c5e51ed069 ocdp v1

2025-11-13 02:54:06 +00:00

8.8 KiB

Raw Permalink Blame History

Bootstrap 预注入数据说明

📋 概述

Bootstrap 功能在应用启动时自动预注入初始数据，帮助快速搭建开发/测试环境。

配置文件: config/bootstrap.json

🔧 预注入数据内容

1️⃣ 用户 (Users)

预注入 1 个管理员账户：

字段	值	说明
username	`admin`	管理员用户名
password	`admin123`	初始密码（⚠️ 生产环境请修改）
email	`admin@example.com`	邮箱地址

用途:

登录后台管理系统
测试用户认证功能
管理集群和 Registry

密码加密: 使用 bcrypt 加密存储

2️⃣ Registry (OCI 镜像仓库)

预注入 1 个 Harbor Registry：

字段	值	说明
name	`Harbor Production`	Registry 名称
url	`https://harbor.example.com`	Registry 地址
description	`Production Harbor Registry`	描述
username	`admin`	Registry 用户名
password	`Harbor12345`	Registry 密码（加密存储）
insecure	`false`	是否跳过 SSL 验证

用途:

浏览 Helm Chart 制品
拉取 OCI Artifacts
测试 Registry 连接

密码加密: 使用 AES 加密存储（基于 ENCRYPTION_KEY 环境变量）

3️⃣ Kubernetes 集群 (Clusters)

预注入 1 个测试集群：

字段	值	说明
name	`Test Cluster`	集群名称
host	`https://kubernetes.example.com:6443`	Kubernetes API Server 地址
description	`Test Kubernetes Cluster`	描述
caData	`LS0tLS1CRUdJTi1D...`	CA 证书（Base64 编码）
certData	`LS0tLS1CRUdJTi1D...`	客户端证书（Base64 编码）
keyData	`LS0tLS1CRUdJTi1S...`	客户端密钥（Base64 编码）

用途:

部署 Helm Chart 应用
查看集群状态和资源
测试 Kubernetes 集成

证书加密: CA/Cert/Key 使用 AES 加密存储

🎯 Bootstrap 模式

Mock 模式 (run-0)

✅ Bootstrap 启用
✅ 数据存储在内存中
✅ 重启后数据重置

真实模式 (run-1, run-2)

✅ Bootstrap 启用
✅ 数据存储在 PostgreSQL
✅ 重启后数据持久化
⚠️ 避免重复: 如果数据已存在会跳过创建

📝 配置文件

完整配置示例 (`config/bootstrap.json`)

{
  "enabled": true,
  "users": [
    {
      "username": "admin",
      "password": "admin123",
      "email": "admin@example.com"
    }
  ],
  "registries": [
    {
      "name": "Harbor Production",
      "url": "https://harbor.example.com",
      "description": "Production Harbor Registry",
      "username": "admin",
      "password": "Harbor12345",
      "insecure": false
    }
  ],
  "clusters": [
    {
      "name": "Test Cluster",
      "host": "https://kubernetes.example.com:6443",
      "description": "Test Kubernetes Cluster",
      "caData": "LS0tLS1CRUdJTi1DRVJUSUZJQ0FURS0tLS0t...",
      "certData": "LS0tLS1CRUdJTi1DRVJUSUZJQ0FURS0tLS0t...",
      "keyData": "LS0tLS1CRUdJTi1SU0EgUFJJVkFURSBLRVktLS0tLQ=="
    }
  ]
}

⚙️ 自定义配置

方式 1: 修改配置文件

# 编辑配置
vim config/bootstrap.json

# 重启应用
make run-1

方式 2: 通过环境变量

export BOOTSTRAP_CONFIG_JSON='{
  "enabled": true,
  "users": [
    {"username": "myuser", "password": "mypass", "email": "user@example.com"}
  ],
  "registries": [],
  "clusters": []
}'

make run-1

方式 3: 指定配置文件路径

export BOOTSTRAP_CONFIG_FILE=/path/to/custom-bootstrap.json
make run-1

🔒 安全建议

⚠️ 生产环境注意事项

修改默认密码

{
  "users": [
    {
      "username": "admin",
      "password": "YourStrongPasswordHere"  // ⚠️ 修改
    }
  ]
}

设置强加密密钥

# 生成 32 字节随机密钥
export ENCRYPTION_KEY=$(openssl rand -base64 32)

使用真实证书
- 替换 caData, certData, keyData 为真实集群证书
- 确保证书有效期和权限正确
禁用 Bootstrap（可选）
```
{
  "enabled": false
}
```

删除配置文件

# 首次启动后删除（数据已导入）
rm config/bootstrap.json

🧪 测试验证

验证用户

# 登录测试
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

# 预期返回: {"token": "eyJhbGc..."}

验证 Registry

# 查看 Registry 列表
curl http://localhost:8080/api/v1/registries

# 预期返回: 
# [
#   {
#     "id": "...",
#     "name": "Harbor Production",
#     "url": "https://harbor.example.com"
#   }
# ]

验证 Cluster

# 查看集群列表
curl http://localhost:8080/api/v1/clusters

# 预期返回:
# [
#   {
#     "id": "...",
#     "name": "Test Cluster",
#     "host": "https://kubernetes.example.com:6443"
#   }
# ]

📊 启动日志示例

成功的 Bootstrap 日志

🌱 Starting bootstrap seeding...
   ↳ Seeding 1 user(s)...
     ✓ User 'admin' created
   ↳ Seeding 1 registry(ies)...
     ✓ Registry 'Harbor Production' created (credentials encrypted)
   ↳ Seeding 1 cluster(s)...
     ✓ Cluster 'Test Cluster' created (credentials encrypted)
✅ Bootstrap seeding completed

数据已存在的日志

🌱 Starting bootstrap seeding...
   ↳ Seeding 1 user(s)...
     ⊙ User 'admin' already exists, skipping
   ↳ Seeding 1 registry(ies)...
     ⊙ Registry 'Harbor Production' already exists, skipping
   ↳ Seeding 1 cluster(s)...
     ⊙ Cluster 'Test Cluster' already exists, skipping
✅ Bootstrap seeding completed

🔄 重置数据

重置 Mock 模式数据

# Mock 数据存储在内存，重启即重置
make run-0
# Ctrl+C
make run-0

重置真实数据库数据

# 清理并重新创建
make clean-1
make run-1

📖 更多示例

添加多个用户

{
  "enabled": true,
  "users": [
    {
      "username": "admin",
      "password": "admin123",
      "email": "admin@example.com"
    },
    {
      "username": "developer",
      "password": "dev123",
      "email": "dev@example.com"
    },
    {
      "username": "operator",
      "password": "ops123",
      "email": "ops@example.com"
    }
  ]
}

添加多个 Registry

{
  "registries": [
    {
      "name": "Harbor Production",
      "url": "https://harbor.example.com",
      "username": "admin",
      "password": "password1"
    },
    {
      "name": "Docker Hub",
      "url": "https://registry-1.docker.io",
      "username": "myuser",
      "password": "password2"
    },
    {
      "name": "GitHub Container Registry",
      "url": "https://ghcr.io",
      "username": "github-user",
      "password": "ghp_token"
    }
  ]
}

添加多个集群

{
  "clusters": [
    {
      "name": "Dev Cluster",
      "host": "https://dev-k8s.example.com:6443",
      "description": "Development Environment",
      "caData": "...",
      "certData": "...",
      "keyData": "..."
    },
    {
      "name": "Staging Cluster",
      "host": "https://staging-k8s.example.com:6443",
      "description": "Staging Environment",
      "caData": "...",
      "certData": "...",
      "keyData": "..."
    },
    {
      "name": "Production Cluster",
      "host": "https://prod-k8s.example.com:6443",
      "description": "Production Environment",
      "caData": "...",
      "certData": "...",
      "keyData": "..."
    }
  ]
}

🛠️ 故障排查

问题 1: Bootstrap 不生效

症状: 启动后没有预注入数据

检查:

# 1. 检查配置文件是否存在
ls -la config/bootstrap.json

# 2. 检查 enabled 是否为 true
cat config/bootstrap.json | jq .enabled

# 3. 查看启动日志
# 应该看到 "Starting bootstrap seeding..."

问题 2: 密码不正确

症状: 无法使用预注入的用户登录

原因: 密码在配置文件中可能已修改

解决:

# 查看配置文件中的密码
cat config/bootstrap.json | jq '.users[0].password'

# 使用正确的密码测试
curl -X POST http://localhost:8080/api/v1/auth/login \
  -d '{"username":"admin","password":"配置文件中的密码"}'

问题 3: 重复创建报错

症状: 日志显示 "duplicate key" 错误

原因: 数据库中已存在同名记录

解决:

正常现象，Bootstrap 会自动跳过
如需重新创建，使用 make clean-1 清理数据库

📚 相关文档

配置示例: config/bootstrap.example.json
代码实现: internal/bootstrap/seeder.go
架构文档: docs/architecture.md - Bootstrap 预注入章节

最后更新: 2025-11-10

8.8 KiB Raw Permalink Blame History Unescape Escape