# 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

