Docs Hub

主题

架构设计 ​

三层分离 ​

API 层 (Gin)          → HTTP 路由、参数校验、中间件（鉴权/限流/审计）
Chain 层              → 业务编排（ChainBase + RunModule 调度原语）
Adapter/Service 层    → 站点适配、下载器控制、媒体匹配、通知、调度

核心模式（借鉴 MoviePilot） ​

Chain / Module / Event ​

  • core/module.Run[T]：按优先级遍历已注册 Module，返回值按 Skip/Continue/Stop 三种语义聚合。这是整个架构的调度原语。
  • chain.ChainBase：内嵌 ModuleManager + EventBus，各业务 Chain（SiteChain/DownloadChain/...）继承它。
  • core/event：广播事件（并发扇出 + panic 隔离）+ 链式事件（优先级串行中间件）。

Oper 模式（数据访问） ​

每张表一个 Oper 类（SiteOper/DownloaderOper/...），封装 GORM 事务 + 敏感字段加解密。

配置即代码（站点定义） ​

站点定义（YAML）驱动抓取——选择器集中在 site/defaults.go 一处维护，站点 YAML 仅需 5 行（id/name/urls）。新增站点零代码。

后端包组织（47 包，~12.6 万行非测试代码） ​

数字口径：ls internal | wc -l / find internal -name '*.go' ! -name '*_test.go' | xargs wc -l。 本节为导读地图而非逐包清单——新增包不再逐行登记，以目录实况为准。

internal/
├── api/              HTTP 边界层
│   ├── middleware/   auth(jwt+apikey) / cors / ratelimit / requestid / accesslog
│   │                  / body_limit / security_headers / prommetrics / metricsauth
│   ├── errcode/      统一错误码注册表（85+ 码，CI 唯一性测试）
│   └── v1/           handlers: auth, site, downloader, dashboard, media, backup,
│                      entertainment, filemanager, notification, ops 中心
│                      (docker/ssh/磁盘/终端/数据库), agent, llm_gateway, mcp, servarr...
├── chain/            业务编排: site, download, media, keepseed, notification,
│                      entertainment, dashboard, brushflow, contract, rss,
│                      subscribe, transfer, cloud, savept, cookiecloud, mediaproxy,
│                      recommend + ChainBase/RunModule
│                      (SiteChain.credential 按 schema 分发：mteam→apiKey / 其余→cookie)
├── core/             config, log, security(jwt/aes/bcrypt/hkdf), event, module, safego
├── site/             站点适配框架: types, selector(goquery), nologin, registry,
│   └── schemas/      defaults + nexusphp 系 + mteam/tnode 等特化（304 个 YAML 定义驱动）
├── downloader/       统一接口 + qb(client/methods/rid-sync) + tr(RPC) + transmission 等
│   └── manager/      多实例管理（缓存 + Invalidate）
├── workflow/         可视化工作流引擎（nodes 编排 + 运行记录）
├── monitor/          主机监控: agent 长连接(文件传输/终端) + SSH + 指标快照/告警
├── media/            TMDB + Douban + Bangumi + MusicBrainz + NFO
├── mediaserver/      Emby/Jellyfin/Plex 播放回调与直链
├── cloud/            网盘客户端（115/夸克/阿里/天翼/百度）+ STRM
├── aiagent/          ReAct 智能体（46 工具 + 危险操作确认流 + 会话持久化）
├── llm/ llmgateway/  OpenAI/Anthropic 兼容 provider + 对外暴露网关（Cursor 直连）
├── mcp/ ocr/         MCP Server / PaddleOCR 验证码识别
├── httpclient/       统一抓取: cookie/retry/UA/Cloudflare/SSRF(拨号时校验)
├── filemanager/      WebDAV + Alist + 本机
├── cookiecloud/      AES 解密 + host 匹配 + 内置服务端
├── keepseed/ iyuu/   辅种评分 + IYUU 协同
├── entertainment/    游戏框架 + 好学(jgg/magic_scratch/medal) + 各站特化
├── notification/     bark/telegram/webhook/ntfy/... 24 渠道 + Manager
├── scheduler/        robfig/cron + Recover
├── automation/       7×24: stats-sync + checkin + cookie-keepalive + hr-check + registration + freeleech
├── backup/           导出/导入(自身格式 + MoviePilot) + 口令加密信封
├── auth/             好学 VIP 准入 + 激活码(HMAC) + guard + 一次性 ticket
├── plugins/          插件系统（市场/调度/KV/日志）
├── transfer/ dirwatch/ subtitle/ torznab/ trakt/ savept/ doctor/ tgbot/
├── ws/               前端实时推送（增量 diff 协议 + 周期 full 重同步）
├── web/              go:embed 内嵌前端 + SPA Handler
├── db/               GORM + SQLite/PG + AutoMigrate + 版本化迁移(schema_migrations)
│   ├── models/       50+ 模型
│   └── oper/         30+ Oper
└── app/              依赖装配 + HTTP 生命周期 + cron 注册

文件组织原则（可维护性） ​

  • 每个文件单一职责（如 qb/ 拆为 client.go + methods.go + convert.go）
  • 超过 ~400 行主动拆分
  • 通用工具集中（helpers.go / defaults.go / convert.go）
  • 站点 YAML 极简（5 行），选择器自动填充

数据流 ​

移动端 WebView 登录 → 取 cookie → POST /sites/:id/cookie → 后端 AES 加密存储
                                                                      ↓
automation cron ───────────────────────────────────────────────────→ 站点抓取
  ├── stats-sync: FetchUserInfo → 写 SiteStat → /dashboard 聚合显示
  ├── checkin: POST attendance.php → 日志 + 通知
  ├── cookie-keepalive: 认证 GET 刷新 session + Set-Cookie 轮换回写 + 失效告警
  ├── hr-check: 抓 getusertorrentlist.php?type=hr → 未达标/临期告警
  └── registration: 探测 signup.php → 关闭→开放转换通知
                                                                      ↓
Web UI / Flutter ← GET /dashboard (真实聚合) / GET /downloaders/:id/torrents