README
¶
core · 业务核心库
PigeonBox 业务核心库:18 个域服务(含 config 系统配置中心) + 数据访问 + 存储抽象 + HTTP 装配(bootstrap)。不含 main、不含静态资源、不含配置文件——本模块定位是被复用的库,消费方:
pigeonbox/server—— 标准独立部署(自托管)pigeonbox/fnos—— 飞牛 fnOS 应用(单容器库式调用)pigeonbox/openwrt—— OpenWrt/iStoreOS 原生包(库式调用)pigeonbox/qnap—— 威联通 QTS 原生 QPKG(库式调用)
🗂️ 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/*由 contractsAdminP2PService(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 设计)
app/—— 业务逻辑层,不依赖具体传输协议,不直接操作数据库(经 repo 层)transport/+gen/—— 传输层,协议适配,调用 app 层服务repo/—— 数据访问层,封装 DB/Redis/外部服务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
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）。 |
|
chunk
storage.go — 分片物理操作的存储接缝（chunk 域）。
|
storage.go — 分片物理操作的存储接缝（chunk 域）。 |
|
config
config.go 站点配置模型与校验:SystemConfig/UserSettings 类型、默认值、 写库前校验(纯函数簇,自 admin 域原样迁入)。
|
config.go 站点配置模型与校验:SystemConfig/UserSettings 类型、默认值、 写库前校验(纯函数簇,自 admin 域原样迁入)。 |
|
federation
directory.go — 联邦节点名录透传（2026-10-14 邀请信箱配套；2026-10-22 由 直传包搬入）。
|
directory.go — 联邦节点名录透传（2026-10-14 邀请信箱配套；2026-10-22 由 直传包搬入）。 |
|
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 预览域服务：取件校验与预览生成/持久化的业务编排。 |
|
request
Package request 寄件码/反向收件（P2）：用户创建投递链接，访客凭链接上传， 文件以链接主人名义成为普通分享（复用分享过期/清理/通知机制）。
|
Package request 寄件码/反向收件（P2）：用户创建投递链接，访客凭链接上传， 文件以链接主人名义成为普通分享（复用分享过期/清理/通知机制）。 |
|
share
秒传/去重的物理对象保护（2026-10-12，D1=A 同用户内去重）。
|
秒传/去重的物理对象保护（2026-10-12，D1=A 同用户内去重）。 |
|
API Key 临期站内通知（波次3）：定期扫描 7 天内到期的有效 Key， 给属主发站内信（带 Webhook 外推），并打去重标记。
|
API Key 临期站内通知（波次3）：定期扫描 7 天内到期的有效 Key， 给属主发站内信（带 Webhook 外推），并打去重标记。 |
|
signingkey.go 直传/分片会话签名密钥的单源取用。
|
signingkey.go 直传/分片会话签名密钥的单源取用。 |
|
gen
|
|
|
handler/admin
admin_manage.go 管理端增强：用户 CRUD / 文件管理 / 富统计 Dashboard。
|
admin_manage.go 管理端增强：用户 CRUD / 文件管理 / 富统计 Dashboard。 |
|
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/share
download_range.go — 远端后端的 Range 下载（断点续传/P3 下载续传）。
|
download_range.go — 远端后端的 Range 下载（断点续传/P3 下载续传）。 |
|
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
|
|
|
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/concurrency/async，后者为纯标准库实现的外部模块）：单机内存模式的共享存储原语。
|
Package memkv 进程内字符串 TTL KV（主包仅依赖标准库与 oekit/concurrency/async，后者为纯标准库实现的外部模块）：单机内存模式的共享存储原语。 |
|
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）基址归一——联邦域的单源。 |
|
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/model
suffix.go — 扩展名推导（仪表盘「文件类型分布」用）。
|
suffix.go — 扩展名推导（仪表盘「文件类型分布」用）。 |
|
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 生成）。 |
Click to show internal directories.
Click to hide internal directories.