453 lines
8.8 KiB
Markdown
453 lines
8.8 KiB
Markdown
# 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`)
|
||
|
||
```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: 修改配置文件
|
||
|
||
```bash
|
||
# 编辑配置
|
||
vim config/bootstrap.json
|
||
|
||
# 重启应用
|
||
make run-1
|
||
```
|
||
|
||
### 方式 2: 通过环境变量
|
||
|
||
```bash
|
||
export BOOTSTRAP_CONFIG_JSON='{
|
||
"enabled": true,
|
||
"users": [
|
||
{"username": "myuser", "password": "mypass", "email": "user@example.com"}
|
||
],
|
||
"registries": [],
|
||
"clusters": []
|
||
}'
|
||
|
||
make run-1
|
||
```
|
||
|
||
### 方式 3: 指定配置文件路径
|
||
|
||
```bash
|
||
export BOOTSTRAP_CONFIG_FILE=/path/to/custom-bootstrap.json
|
||
make run-1
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 安全建议
|
||
|
||
### ⚠️ 生产环境注意事项
|
||
|
||
1. **修改默认密码**
|
||
```json
|
||
{
|
||
"users": [
|
||
{
|
||
"username": "admin",
|
||
"password": "YourStrongPasswordHere" // ⚠️ 修改
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
2. **设置强加密密钥**
|
||
```bash
|
||
# 生成 32 字节随机密钥
|
||
export ENCRYPTION_KEY=$(openssl rand -base64 32)
|
||
```
|
||
|
||
3. **使用真实证书**
|
||
- 替换 `caData`, `certData`, `keyData` 为真实集群证书
|
||
- 确保证书有效期和权限正确
|
||
|
||
4. **禁用 Bootstrap（可选）**
|
||
```json
|
||
{
|
||
"enabled": false
|
||
}
|
||
```
|
||
|
||
5. **删除配置文件**
|
||
```bash
|
||
# 首次启动后删除（数据已导入）
|
||
rm config/bootstrap.json
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试验证
|
||
|
||
### 验证用户
|
||
|
||
```bash
|
||
# 登录测试
|
||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "admin",
|
||
"password": "admin123"
|
||
}'
|
||
|
||
# 预期返回: {"token": "eyJhbGc..."}
|
||
```
|
||
|
||
### 验证 Registry
|
||
|
||
```bash
|
||
# 查看 Registry 列表
|
||
curl http://localhost:8080/api/v1/registries
|
||
|
||
# 预期返回:
|
||
# [
|
||
# {
|
||
# "id": "...",
|
||
# "name": "Harbor Production",
|
||
# "url": "https://harbor.example.com"
|
||
# }
|
||
# ]
|
||
```
|
||
|
||
### 验证 Cluster
|
||
|
||
```bash
|
||
# 查看集群列表
|
||
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 模式数据
|
||
|
||
```bash
|
||
# Mock 数据存储在内存，重启即重置
|
||
make run-0
|
||
# Ctrl+C
|
||
make run-0
|
||
```
|
||
|
||
### 重置真实数据库数据
|
||
|
||
```bash
|
||
# 清理并重新创建
|
||
make clean-1
|
||
make run-1
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 更多示例
|
||
|
||
### 添加多个用户
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 添加多个集群
|
||
|
||
```json
|
||
{
|
||
"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 不生效
|
||
|
||
**症状**: 启动后没有预注入数据
|
||
|
||
**检查**:
|
||
```bash
|
||
# 1. 检查配置文件是否存在
|
||
ls -la config/bootstrap.json
|
||
|
||
# 2. 检查 enabled 是否为 true
|
||
cat config/bootstrap.json | jq .enabled
|
||
|
||
# 3. 查看启动日志
|
||
# 应该看到 "Starting bootstrap seeding..."
|
||
```
|
||
|
||
### 问题 2: 密码不正确
|
||
|
||
**症状**: 无法使用预注入的用户登录
|
||
|
||
**原因**: 密码在配置文件中可能已修改
|
||
|
||
**解决**:
|
||
```bash
|
||
# 查看配置文件中的密码
|
||
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
|
||
|