ocdp v1
This commit is contained in:
mangomqy
452
backend/BOOTSTRAP-DATA.md
Normal file
452
backend/BOOTSTRAP-DATA.md
Normal file
@ -0,0 +1,452 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user