README
¶
数据库迁移系统
概述
本项目的数据库迁移系统完全基于Ent ORM实现，提供了完整的数据库结构迁移和默认数据初始化功能。
特性
1. 基于Ent ORM
- 使用Ent的类型安全查询构建器
- 支持事务操作
- 避免SQL注入风险
- 跨数据库兼容
3. 智能初始化
- 自动检测已存在数据
- 避免重复初始化
- 支持增量数据更新
4. 完整的数据初始化
- 认证方法配置
- 支付方式设置
- 系统配置
- 默认管理员账户
- 默认公告和文档
迁移组件
1. Migrator (migrate.go)
核心迁移器，包含以下功能：
AutoMigrate(): 仅数据库结构迁移AutoMigrateWithData(): 完整迁移（结构+数据）InitBasicData(): 初始化基础数据（legacy SQL + 邮件模板回填）ensureEmailAuthMethodTemplates(): 邮件认证空模板幂等回填CreateDefaultAdminUser(): 创建默认管理员
2. 修复工具 (repair.go)
数据修复工具，用于数据迁移后的修复和清理。
使用方法
1. 自动迁移（服务启动时）
服务启动时在 internal/data/data.go 中调用 migrator：
migrator := migrate.NewMigrator(client, logger, appConf, c.Database.Driver, c.Database.Source)
// 新库: AutoMigrateWithData；已有 legacy 库: InitBasicData + CreateDefaultAdminUser
2. 手动迁移
基础数据同步
# 启动服务即会执行 InitBasicData（含邮件模板回填）
make dev
# 或
go run ./cmd/npanel -conf ./configs
完整迁移
make migrate # 提示：新库首次启动时自动完成结构+数据迁移
迁移验证
当前仓库未提供独立迁移测试命令。请启动服务并检查日志，或查询 auth_method.config 等表确认数据已写入。
默认数据详情
1. 认证方法
- 邮件认证: SMTP 配置框架；默认 HTML 模板来自
pkg/email/template.go，启动时由ensureEmailAuthMethodTemplates回填；运行时EmailAuthConfig.Unmarshal亦会兜底空模板 - 手机认证: abosend短信平台（包含测试密钥）
- OAuth认证: Apple、Google、GitHub配置
- 设备认证: 设备管理配置
- Telegram认证: 机器人集成配置
2. 支付方式
- 余额支付: 默认启用
- 支付宝: 配置框架
- 微信支付: 配置框架
3. 系统配置
- 站点基本信息（名称、Logo、关键词等）
- 货币配置（默认货币和符号）
- 注册限制和试用设置
- 邀请推荐系统配置
- 验证服务配置
- 订阅模式配置
4. 默认管理员
管理员信息从配置文件读取，如果没有配置则使用默认值：
- 邮箱: 从config.yaml读取，默认admin@example.com
- 密码: 从config.yaml读取，默认admin123456
- 算法: 从config.yaml读取，默认default
- 权限: 超级管理员
配置示例：
app:
admin:
email: "your-admin@example.com"
password: "your-secure-password"
algo: "default"
配置文件要求
确保 configs/config.yaml 包含正确的数据库配置：
data:
database:
driver: mysql
source: root:password@tcp(127.0.0.1:3306)/npanel_pro?parseTime=True&loc=Local
redis:
addr: 127.0.0.1:6379
password:
read_timeout: 0.2s
write_timeout: 0.2s
db: 0
pool_size: 10
min_idle_conns: 5
生产环境注意事项
1. 安全配置
- 更改默认管理员密码
- 更新短信平台API密钥
- 配置真实的支付商户信息
2. 数据备份
- 迁移前备份现有数据
- 请使用数据库原生备份工具（如
mysqldump）备份重要配置
3. 性能考虑
- 大量数据迁移时建议分批执行
- 监控迁移过程中的内存使用
故障排除
1. 连接失败
Error: failed to create data client
解决: 检查数据库服务状态和连接配置
2. 权限问题
Error: failed to create schema
解决: 确保数据库用户有CREATE TABLE权限
3. 数据重复
Warning: Auth methods already exist
解决: 这是正常提示，系统会跳过已存在数据
4. 事务失败
Error: failed to commit transaction
解决: 检查数据库磁盘空间和锁定状态
开发和扩展
1. 添加新的初始化数据
在 migrate.go 中的 InitBasicData 方法中添加新的初始化函数：
// 初始化自定义数据
func (m *Migrator) initCustomData(ctx context.Context, tenantID int64) error {
// 检查是否已存在
count, err := m.client.ProxyCustomTable.Query().
Where(proxycustomtable.TenantID(tenantID)).
Count(ctx)
if err != nil {
return err
}
if count > 0 {
return nil
}
// 创建数据
_, err = m.client.ProxyCustomTable.Create().
SetTenantID(tenantID).
SetName("Custom Data").
Save(ctx)
return err
}
2. 自定义迁移逻辑
可以通过实现自定义的Migrator接口来扩展迁移功能：
type CustomMigrator interface {
Migrate(ctx context.Context) error
Rollback(ctx context.Context) error
}
3. 数据验证
迁移完成后，请启动服务并检查日志，或查询数据库确认初始化数据完整性。
这个迁移系统确保了数据库结构的一致性和初始数据的完整性，为项目的部署和维护提供了可靠的解决方案。
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator 数据迁移器
func NewMigrator ¶
func NewMigrator(client *ent.Client, logger log.Logger, appConf *conf.Application, dbDriver, dbSource string) *Migrator
NewMigrator 创建新的迁移器
func (*Migrator) AutoMigrate ¶
AutoMigrate 自动迁移数据库结构
func (*Migrator) AutoMigrateWithData ¶
AutoMigrateWithData 自动迁移数据库结构并初始化数据
func (*Migrator) CreateDefaultAdminUser ¶
CreateDefaultAdminUser 创建默认管理员用户
type Repairer ¶
type Repairer struct {
// contains filtered or unexported fields
}
Repairer 数据修复器
func NewRepairer ¶
NewRepairer 创建新的修复器
func (*Repairer) RepairReferCodes ¶
RepairReferCodes 修复推荐码重复问题
func (*Repairer) RepairSubscriptionTraffic ¶
RepairSubscriptionTraffic 修复订阅流量数据
func (*Repairer) RepairSystemConfig ¶
RepairSystemConfig 修复系统配置
Source Files
Click to show internal directories.
Click to hide internal directories.