SyncTV 项目架构与实践指南

项目架构解析

架构概览

SyncTV采用模块化设计，基于Go语言构建，通过分层架构实现功能解耦，支持同步观看、直播及视频管理等核心能力。

核心模块功能拆解

目录路径	核心功能	开发者注意事项
cmd/	命令行接口实现，包含服务器启动与管理命令	新增命令需注册至root.go的Command树
internal/	核心业务逻辑，含配置、数据库、认证等模块	内部包禁止跨模块循环依赖
server/	HTTP服务实现，包含路由、中间件与处理器	处理器需遵循RESTful设计规范
utils/	通用工具函数，如加密、M3U8解析等	工具函数需通过单元测试验证

代码组织逻辑

项目采用DDD架构思想，通过领域模型划分模块边界：

• 基础设施层：internal/bootstrap/负责应用初始化
• 领域层：internal/model/定义核心数据结构
• 应用层：internal/op/实现业务流程编排
• 接口层：server/handlers/处理HTTP请求

核心模块实践

启动流程解析

应用入口位于main.go，通过cmd.Execute()触发命令解析：

package main
import "github.com/synctv-org/synctv/cmd"
func main() {
    cmd.Execute() // 启动命令解析器
}

初始化流程通过Bootstrap结构体实现任务编排，支持按序执行初始化步骤：

b := bootstrap.New(bootstrap.WithTask(
    config.Init,
    db.Init,
    server.Init,
))
b.Run(ctx) // 依次执行配置、数据库、服务器初始化

数据模型设计

核心数据模型位于internal/model/，包含用户、房间、媒体资源等实体：

• User：用户基本信息与认证状态
• Room：同步观看房间元数据
• Movie：媒体资源索引与播放状态

模型间关系遵循领域规则，如一个房间包含多个成员，一个用户可加入多个房间。

认证授权实现

系统采用JWT认证机制，配置定义于internal/conf/jwt.go：

type JwtConfig struct {
    SecretKey     string `yaml:"secret_key"`
    ExpiresHours  int    `yaml:"expires_hours"`
    RefreshEnable bool   `yaml:"refresh_enable"`
}

认证中间件通过server/middlewares/auth.go实现请求鉴权，支持基于角色的访问控制。

个性化配置指南

配置体系解析

主配置结构体Config定义于internal/conf/config.go，包含五大配置域：

• 日志配置：控制日志级别、输出格式与轮转策略
• 服务器配置：HTTP/RTMP监听参数与缓存设置
• 数据库配置：多类型数据库连接参数
• 认证配置：JWT密钥与过期策略
• 限流配置：API请求频率控制

常见配置错误排查

错误现象	可能原因	解决方案
数据库连接失败	连接字符串格式错误	检查database.custom_dsn或各字段组合
端口占用	端口已被其他服务占用	修改server.http.port或终止占用进程
认证失败	JWT密钥不匹配	确保jwt.secret_key与生成环境一致
缓存溢出	缓存路径无写入权限	检查server.proxy_cache_path权限设置

性能优化参数推荐

针对高并发场景，建议调整以下参数：

• 数据库连接池：database.max_open_conns设为CPU核心数*2
• 缓存配置：server.proxy_cache_size建议设为可用内存的30%
• 限流设置：rate_limit.global建议设为500 QPS/IP
• 日志级别：生产环境设为INFO，避免DEBUG级日志影响性能

配置修改后需重启服务生效，建议通过setting命令行工具进行参数调整：

./synctv setting set server.http.port 8081

高级配置技巧

1. 自定义数据库连接：通过database.custom_dsn配置复杂连接参数
2. HTTPS部署：设置server.http.cert_path与key_path启用TLS
3. RTMP服务：通过server.rtmp.enable开启直播功能
4. OAuth2集成：在oauth2_plugins配置第三方登录提供商