# 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