core

module
v0.33.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 3, 2026 License: Apache-2.0

README

core · 业务核心库

CI Tag Go License

PigeonBox 业务核心库:18 个域服务(含 config 系统配置中心) + 数据访问 + 存储抽象 + HTTP 装配(bootstrap)。不含 main、不含静态资源、不含配置文件——本模块定位是被复用的库,消费方:

🗂️ PigeonBox 生态成员仓 · 总览见 装配仓 pigeonbox · 架构图集

结构

目录 说明
bootstrap/ 库入口:Bootstrap(configPath) 拉起全部业务,返回 *server.Hertz
app/ 17 个域服务:share / chunk / anonymous / presign / admin / config / user / notify / qrcode / setup / storage / federation / mcp / moderation / oidc / preview / request(模块间近零耦合;跨域引用仅 admin→config 与 share→moderation 钩子窄接口,原 presign→share 已消解;2026-10-22 Wave B' 删 p2px 设备直传编排域)
repo/ 数据访问:db(gorm dao/model)、redis、external;dao 构造必填 *gorm.DB 依赖注入,全局回退已退役
storage/ 存储抽象(OpenDAL 多后端)
pkg/ 12 包横切设施:auth / baseurl / errors / gate / logger / memkv / metrics / middleware / resp / security / transfer / utils
transport/ 手写 http handler 与中间件(admin 面增强端点已 IDL 化收编 gen 链,手写区收窄为存储注入/多文件/OIDC 等桥接)
preview/ 文件预览服务
conf/ 配置结构定义
gen/ thrift 生成的 handler / router(模型类型在 pigeonbox/contracts)

p2p 联邦面:2026-10-22 两应用分拆(Wave B')后,Box 侧只保留联邦面 —— 设备直传(p2pc/p2pcweb)已拆为独立应用 PigeonBeam(信鸽直传),Box 不再编排 直传(直传九端点与 p2px 域整体退役)。/admin/p2p/* 由 contracts AdminP2PService(idl/p2p.thrift)定义,经 IDL gen 链接入,现存四端点 (invites 待收列表 / invites/accept 认领 / invite-push 推送 / directory 在线名录); 另有公开收件 POST /api/v1/p2p/invite(P2PPublicService,限流归桶; 口令=bearer,信任级同手工交接)。accept 为纯信封动作(出箱 + 留痕 + 返回 信封),文件接收由 PigeonBeam 客户端完成。

mcp:单端点 18 个工具;P2P 工具为联邦三件套(p2p_peers / p2p_invites / p2p_accept,admin 级);直传四工具(p2p_status / p2p_tasks / p2p_send / p2p_recv) 随直传编排层一并退役。

分层职责(继承自原仓库 internal 设计)

  1. app/ —— 业务逻辑层,不依赖具体传输协议,不直接操作数据库(经 repo 层)
  2. transport/ + gen/ —— 传输层,协议适配,调用 app 层服务
  3. repo/ —— 数据访问层,封装 DB/Redis/外部服务
  4. pkg/ —— 项目内横切工具(不含对外通用库)

库用法

import "github.com/pigeonbox/core/bootstrap"

h, err := bootstrap.Bootstrap("/path/to/config.yaml")
if err != nil { log.Fatal(err) }
defer bootstrap.Cleanup()
go h.Spin()

依赖规则(强制)

core ──► contracts ──► (thrift runtime)
  └─ 不允许 import server / frontend;不引入任何 UI 与部署物
  • thrift 版本约束由 contracts 以 require 传递,下游无需任何 replace(这是从原仓库拆出的重要修复:原仓库靠 replace thrift => v0.13.0 钉版本,库使用者被迫复述该约束)。
  • 显式钉 bytedance/sonic v1.15.0:hertz 声明的 v1.12.7 在 go1.27/arm64 有 linkname 链接错误。

来源

拆分自 zy84338719/fileCodeBox 的 backend/api、backend/gen/http/{handler,router}、backend/cmd/server/bootstrap,import 路径机械替换,业务逻辑零变更。

License

Apache-2.0

Directories

Path Synopsis
app
admin
auth.go 认证职责簇：管理员登录凭据校验与 JWT 签发（GenerateTokenForAdmin 属认证职责，单独成文件）。
 auth.go 认证职责簇：管理员登录凭据校验与 JWT 签发（GenerateTokenForAdmin 属认证职责，单独成文件）。
anonymous
Package anonymous 实现匿名取件 service（仿 vastsa/PigeonBox UX）。
 Package anonymous 实现匿名取件 service（仿 vastsa/PigeonBox UX）。
backup
Package backup 统一备份包（2026-10-31 起）：换机器 / 换后端 / 灾备三件事一个工具。
 Package backup 统一备份包（2026-10-31 起）：换机器 / 换后端 / 灾备三件事一个工具。
chunk
storage.go — 分片物理操作的存储接缝（chunk 域）。
 storage.go — 分片物理操作的存储接缝（chunk 域）。
config
config.go 站点配置模型与校验:SystemConfig/UserSettings 类型、默认值、 写库前校验(纯函数簇,自 admin 域原样迁入)。
 config.go 站点配置模型与校验:SystemConfig/UserSettings 类型、默认值、 写库前校验(纯函数簇,自 admin 域原样迁入)。
dbmigrate
Package dbmigrate 换库（SQLite → Postgres/MySQL）：把一个实例的数据**逻辑**搬到另一个库。
 Package dbmigrate 换库（SQLite → Postgres/MySQL）：把一个实例的数据**逻辑**搬到另一个库。
federation
delivery.go — 跨站投递（联邦前台化，2026-11-01）。
 delivery.go — 跨站投递（联邦前台化，2026-11-01）。
mcp
Package mcp 实现 PigeonBox 的 Model Context Protocol (MCP) server。
 Package mcp 实现 PigeonBox 的 Model Context Protocol (MCP) server。
moderation
Package moderation 内容审核钩子（治理 2026-10-03，方案 A：管控优先、审核留钩子）。
 Package moderation 内容审核钩子（治理 2026-10-03，方案 A：管控优先、审核留钩子）。
notify
Package notify 实现系统通知（管理员公告 + per-user 取件通知）service。
 Package notify 实现系统通知（管理员公告 + per-user 取件通知）service。
oidc
Package oidc 实现 OIDC 单点登录（P2，stdlib-only，无第三方依赖）。
 Package oidc 实现 OIDC 单点登录（P2，stdlib-only，无第三方依赖）。
presign
Package presign 实现预签名上传 service。
 Package presign 实现预签名上传 service。
preview
Package preview 预览域服务：取件校验与预览生成/持久化的业务编排。
 Package preview 预览域服务：取件校验与预览生成/持久化的业务编排。
qrcode
request
Package request 寄件码/反向收件（P2）：用户创建投递链接，访客凭链接上传， 文件以链接主人名义成为普通分享（复用分享过期/清理/通知机制）。
 Package request 寄件码/反向收件（P2）：用户创建投递链接，访客凭链接上传， 文件以链接主人名义成为普通分享（复用分享过期/清理/通知机制）。
setup
share
秒传/去重的物理对象保护（2026-10-12，D1=A 同用户内去重）。
 秒传/去重的物理对象保护（2026-10-12，D1=A 同用户内去重）。
storage
user
API Key 临期站内通知（波次3）：定期扫描 7 天内到期的有效 Key， 给属主发站内信（带 Webhook 外推），并打去重标记。
 API Key 临期站内通知（波次3）：定期扫描 7 天内到期的有效 Key， 给属主发站内信（带 Webhook 外推），并打去重标记。
signingkey.go 直传/分片会话签名密钥的单源取用。
 signingkey.go 直传/分片会话签名密钥的单源取用。
gen
handler
handler/admin
admin_manage.go 管理端增强：用户 CRUD / 文件管理 / 富统计 Dashboard。
 admin_manage.go 管理端增强：用户 CRUD / 文件管理 / 富统计 Dashboard。
handler/chunk
handler/common
handler/health
handler/maintenance
handler/notify
handler/p2p
gen/handler/p2p/admin_p2_pservice.go — P2P 联邦管理面（2026-10-22 Wave B'： 设备直传面整体拆除后，本文件只剩联邦四端点）。
 gen/handler/p2p/admin_p2_pservice.go — P2P 联邦管理面（2026-10-22 Wave B'： 设备直传面整体拆除后，本文件只剩联邦四端点）。
handler/presign
handler/preview
handler/publicapi
handler/qrcode
handler/ratelimit
handler/request
handler/setup
handler/share
download_range.go — 远端后端的 Range 下载（断点续传/P3 下载续传）。
 download_range.go — 远端后端的 Range 下载（断点续传/P3 下载续传）。
handler/share_anonymous
handler/storage
handler/user
router
router/admin
router/chunk
router/common
router/health
router/maintenance
router/notify
router/p2p
router/presign
router/preview
router/publicapi
router/qrcode
router/ratelimit
router/request
router/setup
router/share
router/share_anonymous
router/storage
router/user
internal
convention
Package convention 固化 core 的**代码约定**守卫（与 internal/arch 的依赖边界守卫互补： arch 管"谁能 import 谁"，convention 管"代码怎么写"）。
 Package convention 固化 core 的**代码约定**守卫（与 internal/arch 的依赖边界守卫互补： arch 管"谁能 import 谁"，convention 管"代码怎么写"）。
paging
Package paging 集中 core 全仓的**分页口径**（默认页长 / 上限 / 超限语义）。
 Package paging 集中 core 全仓的**分页口径**（默认页长 / 上限 / 超限语义）。
pkg
auth
baseurl
Package baseurl 公开链接 base 解析（请求级公开地址推断的单源）。
 Package baseurl 公开链接 base 解析（请求级公开地址推断的单源）。
errors
shareblocked.go 分享管控拒绝态错误（治理状态机的 typed error 词汇表）。
 shareblocked.go 分享管控拒绝态错误（治理状态机的 typed error 词汇表）。
gate
Package gate 上传/下载准入闸门。
 Package gate 上传/下载准入闸门。
logger
ctx.go — Ctx 系日志门面：业务排障日志带 trace_id 的一等入口。
 ctx.go — Ctx 系日志门面：业务排障日志带 trace_id 的一等入口。
memkv
Package memkv 进程内字符串 TTL KV（主包仅依赖标准库与 oekit/pkg/cache）：单机内存模式的共享存储原语。
 Package memkv 进程内字符串 TTL KV（主包仅依赖标准库与 oekit/pkg/cache）：单机内存模式的共享存储原语。
memkv/redisshim
Package redisshim 单机内存模式下 go-redis 命令面的等价实现（memkv.Store 的 redis 兼容垫片）：redis.host 为空时 anonymous/presign 等域的 NewService 以此 兜底，取件码映射/直传会话等短 TTL 数据存进程内——不跨进程共享、重启即失， DB 仍是唯一真相源。
 Package redisshim 单机内存模式下 go-redis 命令面的等价实现（memkv.Store 的 redis 兼容垫片）：redis.host 为空时 anonymous/presign 等域的 NewService 以此 兜底，取件码映射/直传会话等短 TTL 数据存进程内——不跨进程共享、重启即失， DB 仍是唯一真相源。
metrics
Package metrics 业务指标（治理 2026-10-03）。
 Package metrics 业务指标（治理 2026-10-03）。
middleware
auditactor.go 审计操作者提取：从请求上下文取 (用户ID, 用户名, IP)。
 auditactor.go 审计操作者提取：从请求上下文取 (用户ID, 用户名, IP)。
paircode
Package paircode 配对口令（p2pc 口令）归一——联邦域口令处理的单源。
 Package paircode 配对口令（p2pc 口令）归一——联邦域口令处理的单源。
registry
Package registry 联邦注册中心（p2pd）基址归一——联邦域的单源。
 Package registry 联邦注册中心（p2pd）基址归一——联邦域的单源。
resp
security
Package security 提供独立的安全原语：
 Package security 提供独立的安全原语：
transfer
Package transfer 提供传输日志（上传/下载）的异步记录。
 Package transfer 提供传输日志（上传/下载）的异步记录。
utils
uploadpath.go 上传相对路径的统一生成收口。
 uploadpath.go 上传相对路径的统一生成收口。
repo
db
Package db 提供数据库连接与迁移。
 Package db 提供数据库连接与迁移。
db/dao
Package dao 数据访问对象层：各域模型的 GORM 持久化实现。
 Package dao 数据访问对象层：各域模型的 GORM 持久化实现。
db/dao_preview
db/model
suffix.go — 扩展名推导（仪表盘「文件类型分布」用）。
 suffix.go — 扩展名推导（仪表盘「文件类型分布」用）。
redis
backends.go 存储后端注册表：类型 → Operator 构建器。
 backends.go 存储后端注册表：类型 → Operator 构建器。
opendal
Package opendal 提供 OpenDAL 风格的存储抽象。
 Package opendal 提供 OpenDAL 风格的存储抽象。
transport
http/handler
Package handler 提供定制 HTTP handlers（不走 thrift IDL 生成）。
 Package handler 提供定制 HTTP handlers（不走 thrift IDL 生成）。
http/middleware

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.