OpenFlare/docs/plan/of-options-migration.md

of_options 迁移到 w_system_configs 方案

背景

当前 OpenFlare 使用 of_options 表存储系统配置，维护了独立的 OptionMap 内存缓存和热重载机制。为了统一配置管理框架，需要将所有配置迁移到标准的 w_system_configs 表，复用现有的 SystemConfig 读取 API 和 Redis 缓存机制。

配置项分类

已存在于 w_system_configs，无需迁移

以下配置在新系统中已存在，不从 of_options 迁移：

• PasswordLoginEnabled → password_login_enabled (已存在)
• CapLoginEnabled → cap_login_enabled (已存在)
• PasswordRegisterEnabled → password_register_enabled (已存在)
• EmailVerificationEnabled → 映射到 email_login_verification_enabled (已存在)
• ServerAddress → server_address (已存在)
• SMTPServer → smtp_host (已存在，字段名不同)
• SMTPPort → smtp_port (已存在)
• SMTPAccount → smtp_username (已存在，字段名不同)
• SMTPToken → smtp_password (已存在，字段名不同)

旧系统冗余配置，直接删除

以下配置是旧系统遗留，当前系统不使用，不迁移：

• SystemName - 前端不再使用系统名称配置
• Footer - 前端不再使用页脚 HTML
• HomePageLink - 前端不再使用首页链接
• About - 前端不再使用关于信息

需要迁移的配置（全部 type=business）

所有迁移的配置都设为 business 类型。system 类型仅用于框架级配置（如 upload_allowed_extensions、disk_cache_max_size_mb 等）。

Agent 相关配置 (business, visibility=0)

原 Key (PascalCase)	新 Key (snake_case)	默认值	说明
AgentDiscoveryToken	agent_discovery_token	""	Agent 发现令牌（敏感）
AgentHeartbeatInterval	agent_heartbeat_interval	10000	Agent 心跳间隔（毫秒）
AgentWebsocketUpgradeEnabled	agent_websocket_upgrade_enabled	true	Agent WebSocket 升级开关
NodeOfflineThreshold	node_offline_threshold	120000	节点离线阈值（毫秒）
AgentUpdateRepo	agent_update_repo	Rain-kl/OpenFlare	Agent 更新仓库

系统功能配置 (business, visibility=0)

原 Key (PascalCase)	新 Key (snake_case)	默认值	说明
GeoIPProvider	geoip_provider	ipinfo	GeoIP 服务商
DatabaseAutoCleanupEnabled	database_auto_cleanup_enabled	false	数据库自动清理开关
DatabaseAutoCleanupRetentionDays	database_auto_cleanup_retention_days	30	数据库保留天数

UptimeKuma 集成配置 (business, visibility=0)

原 Key (PascalCase)	新 Key (snake_case)	默认值	说明
UptimeKumaEnabled	uptime_kuma_enabled	false	UptimeKuma 集成开关
UptimeKumaUrl	uptime_kuma_url	""	UptimeKuma URL
UptimeKumaUsername	uptime_kuma_username	""	UptimeKuma 用户名
UptimeKumaPassword	uptime_kuma_password	""	UptimeKuma 密码（敏感）
UptimeKumaMonitorScope	uptime_kuma_monitor_scope	all	UptimeKuma 监控范围
UptimeKumaSelectedSites	uptime_kuma_selected_sites	""	UptimeKuma 选定站点
UptimeKumaSyncInterval	uptime_kuma_sync_interval	5	UptimeKuma 同步间隔（分钟）
UptimeKumaInterval	uptime_kuma_interval	60	UptimeKuma 监控间隔（秒）
UptimeKumaRetry	uptime_kuma_retry	0	UptimeKuma 重试次数
UptimeKumaRetryInterval	uptime_kuma_retry_interval	60	UptimeKuma 重试间隔（秒）
UptimeKumaTimeout	uptime_kuma_timeout	48	UptimeKuma 超时（秒）

OpenResty 配置 (type=business)

OpenResty 反向代理和缓存配置，全部为 business 类型，visibility=0：

原 Key (PascalCase)	新 Key (snake_case)	默认值
OpenRestyDefaultServerReturnStatus	openresty_default_server_return_status	421
OpenRestyWorkerProcesses	openresty_worker_processes	auto
OpenRestyWorkerConnections	openresty_worker_connections	4096
OpenRestyWorkerRlimitNofile	openresty_worker_rlimit_nofile	65535
OpenRestyEventsUse	openresty_events_use	epoll
OpenRestyEventsMultiAcceptEnabled	openresty_events_multi_accept_enabled	true
OpenRestyKeepaliveTimeout	openresty_keepalive_timeout	20
OpenRestyKeepaliveRequests	openresty_keepalive_requests	1000
OpenRestyClientHeaderTimeout	openresty_client_header_timeout	15
OpenRestyClientBodyTimeout	openresty_client_body_timeout	15
OpenRestyClientMaxBodySize	openresty_client_max_body_size	64m
OpenRestyLargeClientHeaderBuffers	openresty_large_client_header_buffers	4 16k
OpenRestySendTimeout	openresty_send_timeout	30
OpenRestyResolvers	openresty_resolvers	""
OpenRestyProxyConnectTimeout	openresty_proxy_connect_timeout	3
OpenRestyProxySendTimeout	openresty_proxy_send_timeout	60
OpenRestyProxyReadTimeout	openresty_proxy_read_timeout	60
OpenRestyWebsocketEnabled	openresty_websocket_enabled	true
OpenRestyHTTP3Enabled	openresty_http3_enabled	true
OpenRestyProxyRequestBufferingEnabled	openresty_proxy_request_buffering_enabled	false
OpenRestyProxyBufferingEnabled	openresty_proxy_buffering_enabled	true
OpenRestyProxyBuffers	openresty_proxy_buffers	16 16k
OpenRestyProxyBufferSize	openresty_proxy_buffer_size	8k
OpenRestyProxyBusyBuffersSize	openresty_proxy_busy_buffers_size	64k
OpenRestyGzipEnabled	openresty_gzip_enabled	true
OpenRestyGzipMinLength	openresty_gzip_min_length	1024
OpenRestyGzipCompLevel	openresty_gzip_comp_level	5
OpenRestyCacheEnabled	openresty_cache_enabled	false
OpenRestyCachePath	openresty_cache_path	""
OpenRestyCacheLevels	openresty_cache_levels	1:2
OpenRestyCacheInactive	openresty_cache_inactive	30m
OpenRestyCacheMaxSize	openresty_cache_max_size	1g
OpenRestyCacheKeyTemplate	openresty_cache_key_template	$scheme$host$request_uri
OpenRestyCacheLockEnabled	openresty_cache_lock_enabled	true
OpenRestyCacheLockTimeout	openresty_cache_lock_timeout	5s
OpenRestyCacheUseStale	openresty_cache_use_stale	error timeout updating http_500...
OpenRestyMainConfigTemplate	openresty_main_config_template	(长模板)

总计：约 58 个配置需要迁移，全部为 business 类型。

迁移策略

1. 保持向后兼容

• 在迁移期间同时支持旧 API (/api/v1/openflare/options) 和新 API (/api/v1/admin/system-configs)
• 旧 API 内部委派到 SystemConfig 读写，不再直接操作 of_options 表
• 保留 /api/v1/openflare/status 接口，但从 SystemConfig 读取数据

2. 数据迁移顺序

1. 创建新的 ConfigKey 常量（已完成）
2. 创建 goose 迁移脚本，将 of_options 真正需要的配置复制到 w_system_configs（已完成）
3. 重构代码使用 repository.GetSystemConfigByKey / GetBoolByKey / GetIntByKey
4. 标记 of_options 表为 deprecated（保留一段时间用于回滚）
5. 后续版本完全删除 of_options 相关代码

3. 配置类型说明

所有从 of_options 迁移的配置都设为 business 类型：

• type='business'：业务配置，影响业务规则和功能行为
• type='system'：框架配置，仅用于框架级设置（如 upload_allowed_extensions、disk_cache_max_size_mb）

不迁移的配置：

• 已存在于 w_system_configs 的配置（如 password_login_enabled、smtp_host）
• 旧系统冗余配置（SystemName、Footer、HomePageLink、About）

4. 包级变量处理

原 openflare_option.go 中的包级变量（如 SystemName、PasswordLoginEnabled）将被移除。所有读取改为：

// 旧方式（包级变量）
systemName := model.SystemName
enabled := model.PasswordLoginEnabled

// 新方式（repository 读取）
systemName, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySystemName)
enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyPasswordLoginEnabled)

注意：对于已存在的配置，使用对应的新 key：

// 已存在的配置使用现有 key
enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyPasswordLoginEnabled)  // 不是 ConfigKeySystemName

5. 热重载机制

• 移除 InitOptionMap 和 OptionMapRWMutex
• SystemConfig 已通过 Redis 缓存实现热重载，更新后自动失效

实现步骤

1. ✅ 分析配置项并设计迁移方案（本文档）
2. 在 system_configs.go 添加所有 ConfigKey 常量
3. 创建 goose 迁移脚本（PostgreSQL + SQLite）
4. 重构所有业务代码使用 SystemConfig API
5. 更新 option 模块 API 和测试
6. 清理 of_options 遗留代码并验证

风险与注意事项

1. 敏感配置处理：包含 Token/Password/Secret 的配置不应暴露给前端（visibility=0）
2. 类型转换：of_options 将数值存为字符串，需要在读取时正确转换
3. 默认值一致性：确保 SQL 迁移中的默认值与代码中的默认值一致
4. 模板配置：OpenRestyMainConfigTemplate 是长文本，需要正确处理
5. 测试覆盖：所有使用 OptionMap 的测试需要更新为使用 SystemConfig

后续清理计划

迁移完成后，在下一个主版本（如 v2.0）中完全移除：

• internal/model/openflare_option.go
• internal/model/openflare_option_apply.go
• of_options 表及相关迁移文件
• internal/apps/openflare/option 模块（或重构为 SystemConfig 的代理）