Documentation
¶
Overview ¶
signingkey.go 直传/分片会话签名密钥的单源取用。
此前 bootstrap wiring 与 chunk/token 各自 os.Getenv("PB_PRESIGN_SIGNING_KEY") + 回退 jwt_secret 现读现拼(两处逐字重复,配置来源漂移风险);2026-10-10 收口于此。env 现读语义保留(与既有两处行为一致)。
Index ¶
- Constants
- func CodeFoldEnabledOrDefault() bool
- func FederationAllowedInMode(mode string) bool
- func PresignSigningKey() string
- func SetGlobalConfig(cfg *AppConfiguration)
- type APITokenConfig
- type AdminConfig
- type AppConfig
- type AppConfiguration
- func (c *AppConfiguration) IsAdminReplica() bool
- func (c *AppConfiguration) IsProduction() bool
- func (c *AppConfiguration) IsPublicReplica() bool
- func (c *AppConfiguration) IsStandalone() bool
- func (c *AppConfiguration) NormalizedDeploymentMode() string
- func (c *AppConfiguration) ServesAdminPlane() bool
- func (c *AppConfiguration) ServesPublicPlane() bool
- type AzureBlobConfig
- type CORSConfig
- type ClamAVConfig
- type CloudStorageConfig
- type DatabaseConfig
- type DeploymentConfig
- type DownloadConfig
- type DownloadTokenConfig
- type FTPConfig
- type FederationConfig
- type HDFSConfig
- type LocalImportConfig
- type LockoutConfig
- type LogConfig
- type MCPConfig
- type MetricsConfig
- type ModerationConfig
- type NotifyConfig
- type OIDCConfig
- type ObservabilityConfig
- type OneDriveConfig
- type RateLimitSettings
- type RedisConfig
- type S3Config
- type SFTPConfig
- type SMTPConfig
- type SSRFConfig
- type SecurityConfig
- type ServerConfig
- type StorageConfig
- type UIConfig
- type UploadConfig
- type UserConfig
- type WebDAVConfig
Constants ¶
const ( // DeployModeStandalone 单进程全功能(默认,即历史形态:全部路由 + 后台任务 + 迁移)。 DeployModeStandalone = "standalone" // DeployModePublic 公开面副本(可多副本横向扩容):只注册公开路由, // 不跑后台任务/迁移,只读 system_configs 并订阅管理端变更广播。 DeployModePublic = "public" // DeployModeAdmin 管理面单实例:admin/mcp/setup 等管理路由 + 后台任务 + // DB 迁移 + system_configs 唯一写者(变更后 Redis 广播)。 DeployModeAdmin = "admin" )
部署模式取值(deployment.mode / env PB_DEPLOY_MODE)。 详见 docs/specs/2026-10-06-multi-replica-deployment-modes.md。
const ( PresignPolicyEveryone = "everyone" // 所有人可直传 PresignPolicyAuthenticated = "authenticated" // 仅登录用户可直传 PresignPolicyDisabled = "disabled" // 完全关闭直传 )
直传策略取值(download.presign_policy)
Variables ¶
This section is empty.
Functions ¶
func CodeFoldEnabledOrDefault ¶ added in v0.14.7
func CodeFoldEnabledOrDefault() bool
CodeFoldEnabledOrDefault 全局配置未初始化(单测/极早期启动)时按默认开。
func FederationAllowedInMode ¶ added in v0.32.37
FederationAllowedInMode 部署模式是否允许联邦。
多副本拓扑(public / admin)下联邦**架构上不可用**:联邦节点身份是**进程级** Ed25519 密钥(PB_FEDERATION_NODE_KEY_PATH),多副本各持各的身份 ⇒ 注册/解析语义未定义(2026-10-30 拍板:暂不支持)⇒ 一律关闭。
⚠️ 这是**部署模式派生的硬约束**,不是配置项:管理台保存的联邦开关 (DB 里 system_configs 的 p2p.federation)是**提交意图**,不是生效值—— 它**不得**把多副本下的联邦打开。
为什么放在 conf(单一真相源) ¶
同一约束有两个触发点,口径必须一致,否则会漂:
- bootstrap 的 applyDeploymentConstraints(**启动时**降级);
- app/config 的 applySystemConfigOverlayLocked(**运行期**热应用; 管理台保存 / 多副本配置广播都会走到)。
第 2 点曾经漏了这条约束 ⇒ overlay 的整段赋值(next.Federation = *sc.P2P.Federation) 把启动时的降级**复活** ⇒ 多副本下 /api/config 报 federationEnabled=true ⇒ 前端承诺了架构上不可用的跨站取件。两处都必须走本函数。
func PresignSigningKey ¶ added in v0.15.1
func PresignSigningKey() string
PresignSigningKey 签名密钥:优先专用 env PB_PRESIGN_SIGNING_KEY,缺省回退 全局配置 jwt_secret;均无返回空串(消费方按"令牌通道关闭"降级—— presign 直传令牌与 chunk 会话令牌共用本密钥)。
Types ¶
type APITokenConfig ¶
type APITokenConfig struct {
Enabled bool `mapstructure:"enabled" json:"enabled"` // 默认 true
PerKeyQPS int `mapstructure:"per_key_qps" json:"per_key_qps"` // 默认 20;显式 0 = 不限
PerKeyBurst int `mapstructure:"per_key_burst" json:"per_key_burst"` // 默认 0 = 2×QPS
}
APITokenConfig 用户级 API Key(个人访问令牌,pb_sk_)。 Enabled 为认证总开关(env PB_API_TOKEN_ENABLED):false 时携带 Key 的请求一律 401。 PerKeyQPS 为单 Key 独立限流(令牌桶,进程内):0 = 不限(默认 20,burst 默认 2×QPS)。
type AdminConfig ¶
type AdminConfig struct {
// LogRetentionDays 审计/传输日志保留天数(0 = 永久)。env: PB_ADMIN_LOG_RETENTION_DAYS
LogRetentionDays int `mapstructure:"log_retention_days"`
// PickupDetailRetentionDays **取件明细**保留天数(0 = 永久)。
// env: PB_ADMIN_PICKUP_DETAIL_RETENTION_DAYS
//
// 为什么与 LogRetentionDays 分开(2026-10-24):取件计次记录表同时承担两个角色
// ——①「同一令牌不重复计次」的去重键(令牌过期后即可丢);② owner 侧「取件历史」
// 的逐条明细(IP / 时间 / 交付面)⇒ ②的留存需求**远长于**①。
// 此前两者共用一个「令牌 TTL + 1h」的清理窗口 ⇒ **owner 看到的明细最多只存在
// 1 小时**(第二天打开取件历史,明细全空)⇒ 「逐条取件历史」形同虚设。
PickupDetailRetentionDays int `mapstructure:"pickup_detail_retention_days"`
}
AdminConfig 管理端运维配置(治理 2026-10-03)
type AppConfig ¶
type AppConfig struct {
Name string `mapstructure:"name"`
Version string `mapstructure:"version"`
Description string `mapstructure:"description"`
DataPath string `mapstructure:"datapath"`
Production bool `mapstructure:"production"`
}
AppConfig 应用配置
type AppConfiguration ¶
type AppConfiguration struct {
Server ServerConfig `mapstructure:"server"`
Database DatabaseConfig `mapstructure:"database"`
Redis RedisConfig `mapstructure:"redis"`
Log LogConfig `mapstructure:"log"`
App AppConfig `mapstructure:"app"`
User UserConfig `mapstructure:"user"`
Upload UploadConfig `mapstructure:"upload"`
Download DownloadConfig `mapstructure:"download"`
Storage StorageConfig `mapstructure:"storage"`
UI UIConfig `mapstructure:"ui"`
Observability ObservabilityConfig `mapstructure:"observability"`
Security SecurityConfig `mapstructure:"security"`
RateLimit RateLimitSettings `mapstructure:"rate_limit"`
Notify NotifyConfig `mapstructure:"notify"`
MCP MCPConfig `mapstructure:"mcp"`
Moderation ModerationConfig `mapstructure:"moderation"`
Admin AdminConfig `mapstructure:"admin"`
Federation FederationConfig `mapstructure:"federation"`
Deployment DeploymentConfig `mapstructure:"deployment"`
}
AppConfiguration 完整应用配置
func GetGlobalConfig ¶
func GetGlobalConfig() *AppConfiguration
GetGlobalConfig 获取全局配置
返回的是**当前快照**(不可变):调用方拿到的指针在一次读取里是自洽的, 但**不要直接改它的字段**——要用 UpdateGlobalConfig 走 copy-on-write (否则会绕过原子换指针,重新引入撕裂读)。
func Snapshot ¶ added in v0.32.36
func Snapshot() *AppConfiguration
Snapshot 取当前全局配置快照(**推荐入口**)。
与 GetGlobalConfig() 等价,但语义更明确:返回值是**不可变快照**, 调用方要么用它读、要么整段替换后再走 UpdateGlobalConfig, **不要直接改它的字段**(那会绕过原子换指针,重新引入撕裂读)。
⚠️ 取到快照后**不要长期持有**:热更新会换指针 ⇒ 长期持有的快照会过期。 需要长期持有就复制一份需要的内容。
func UpdateGlobalConfig ¶ added in v0.32.36
func UpdateGlobalConfig(mutator func(cfg *AppConfiguration)) *AppConfiguration
UpdateGlobalConfig 以 copy-on-write 方式更新全局配置。
mutator 在**当前快照的副本**上修改;返回后原子换指针。 ⇒ 并发读者要么看到完整旧快照、要么看到完整新快照,**永不看到撕裂的中间态**。
之所以必须这样:热应用(管理台保存配置)会整段改写 Upload / Download / Notify / Security 等大段字段,而 45 处读取点在请求路径上无锁读它们 ⇒ 原地改写即数据竞争。
mutator 收到的副本是浅拷贝:段内若有引用类型字段(map/slice/指针), mutator 若要改它们的**内容**(而非整体替换),需自行深拷贝—— 整体替换某个段(cfg.Upload = *newUpload)是安全的。
返回值是**换指针之后**的新快照:调用方若要读生效值,用它而不要再直读 (避免多一个直读点,也避免读到换指针前的旧值)。
func (*AppConfiguration) IsAdminReplica ¶
func (c *AppConfiguration) IsAdminReplica() bool
IsAdminReplica 是否管理面单实例(admin 模式)。
func (*AppConfiguration) IsProduction ¶
func (c *AppConfiguration) IsProduction() bool
IsProduction 是否生产模式(综合 server.mode 与 app.production 判断)
func (*AppConfiguration) IsPublicReplica ¶
func (c *AppConfiguration) IsPublicReplica() bool
IsPublicReplica 是否公开面副本(public 模式)。
func (*AppConfiguration) IsStandalone ¶
func (c *AppConfiguration) IsStandalone() bool
IsStandalone 是否单机全功能模式(默认)。
func (*AppConfiguration) NormalizedDeploymentMode ¶
func (c *AppConfiguration) NormalizedDeploymentMode() string
NormalizedDeploymentMode 归一化部署模式(空值回退 standalone; 非法值由 bootstrap 的 applyDeploymentConstraints fail-fast 拒绝,此处不做校验)。
func (*AppConfiguration) ServesAdminPlane ¶
func (c *AppConfiguration) ServesAdminPlane() bool
ServesAdminPlane 是否注册管理面 + 后台任务 + 迁移(standalone 与 admin)。
func (*AppConfiguration) ServesPublicPlane ¶
func (c *AppConfiguration) ServesPublicPlane() bool
ServesPublicPlane 是否注册公开面(standalone 与 public)。
type AzureBlobConfig ¶
type AzureBlobConfig struct {
Account string `mapstructure:"account" json:"account"`
Container string `mapstructure:"container" json:"container"`
// Key 共享密钥(account key);SAS 非空时忽略
Key string `mapstructure:"key" json:"key"`
// SAS 容器级或账户级 SAS token(以 ? 开头的查询串)
SAS string `mapstructure:"sas" json:"sas"`
Endpoint string `mapstructure:"endpoint" json:"endpoint"` // 可选;Azurite/主权云(缺省 https://<account>.blob.core.windows.net)
Root string `mapstructure:"root" json:"root"`
}
AzureBlobConfig Azure Blob 存储配置(共享密钥或 SAS 二选一)
type CORSConfig ¶
type CORSConfig struct {
AllowOrigins []string `mapstructure:"allow_origins"` // 可信来源列表,env: PB_CORS_ALLOW_ORIGINS(逗号分隔)
AllowCredentials bool `mapstructure:"allow_credentials"` // 是否允许携带凭证
// EnableHSTS 三态(2026-10-08 加固):nil(未配置)= 生产模式默认开/开发默认关;
// 显式 true/false 恒以配置为准(自签证书等特殊拓扑的逃生开关)。
// env: PB_ENABLE_HSTS
EnableHSTS *bool `mapstructure:"enable_hsts"`
}
CORSConfig 跨域配置。
安全说明:当 AllowCredentials=true 时,AllowOrigins 不可为 "*"(浏览器规范), 必须显式列出可信来源。若 AllowOrigins 为空且 AllowCredentials=true, 中间件会退化为反射 Origin(仅适合开发环境)。
type ClamAVConfig ¶
type ClamAVConfig struct {
Enabled bool `mapstructure:"enabled"` // env: PB_MODERATION_CLAMAV_ENABLED
Addr string `mapstructure:"addr"` // 默认 localhost:3310;env: PB_MODERATION_CLAMAV_ADDR
TimeoutSeconds int `mapstructure:"timeout_seconds"` // 单文件扫描超时,默认 60
MaxScanBytes int64 `mapstructure:"max_scan_bytes"` // 超过跳过扫描,默认 512MB
}
ClamAVConfig clamd 病毒扫描配置(默认关闭;详见 app/moderation/clamav.go)
type CloudStorageConfig ¶
type CloudStorageConfig struct {
Region string `mapstructure:"region" json:"region"` // 厂商地域,如 ap-guangzhou / cn-hangzhou
Bucket string `mapstructure:"bucket" json:"bucket"`
AccessKey string `mapstructure:"access_key" json:"access_key"`
SecretKey string `mapstructure:"secret_key" json:"secret_key"`
Endpoint string `mapstructure:"endpoint" json:"endpoint"` // 空 = 按厂商+Region 推导
UseSSL *bool `mapstructure:"use_ssl" json:"use_ssl"` // 缺省 true
PathStyle *bool `mapstructure:"path_style" json:"path_style"` // 缺省 false(各厂商均为 virtual-host 风格)
}
CloudStorageConfig 云厂商对象存储通用配置(S3 兼容协议)。 Endpoint 留空时按厂商 + Region 自动推导。
type DatabaseConfig ¶
type DatabaseConfig struct {
Driver string `mapstructure:"driver"` // sqlite, mysql, postgres
DBName string `mapstructure:"db_name"`
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
User string `mapstructure:"user"`
Password string `mapstructure:"password"`
AutoMigrate bool `mapstructure:"auto_migrate"` // true=GORM AutoMigrate(开发友好,默认); false=版本化迁移(migrations/)
Migrate bool `mapstructure:"migrate"` // 启动时执行版本化迁移(企业级)。与 AutoMigrate 可共存:先 migrate 后 AutoMigrate 兜底
}
DatabaseConfig 数据库配置
type DeploymentConfig ¶
type DeploymentConfig struct {
// Mode standalone(默认) | public | admin。env: PB_DEPLOY_MODE
Mode string `mapstructure:"mode"`
}
DeploymentConfig 部署形态(多副本拆分,2026-10-06)。 同一镜像三种运行模式:public×N + admin×1 组成多副本拓扑; 单机部署保持默认 standalone,行为与历史版本完全一致。
type DownloadConfig ¶
type DownloadConfig struct {
DownloadTimeout int `mapstructure:"download_timeout" json:"download_timeout"`
RequireLogin bool `mapstructure:"require_login" json:"require_login"`
// S3DirectDownload s3 直下:存储后端为 s3 且开启时,文件下载 302 到短时效
// 预签名 GET URL(下载流量不经过服务器)。env: PB_DOWNLOAD_S3_DIRECT
S3DirectDownload bool `mapstructure:"s3_direct_download" json:"s3_direct_download"`
// PresignPolicy 直传策略:everyone=所有人可直传 / authenticated=仅登录用户 /
// disabled=完全关闭直传(全部走服务器中转)。空串=未设置,按 everyone 处理。
// 旧开关 presign_anonymous_enabled 已退役(2026-10-26):存量库该键的语义
// (false⇒仅登录用户)已并入本字段,迁移由启动期数据迁移完成。
PresignPolicy string `mapstructure:"presign_policy" json:"presign_policy"`
// PresignExpireSeconds 直传签名时效(秒)。0=默认 600;钳位 60..3600。
PresignExpireSeconds int `mapstructure:"presign_expire_seconds" json:"presign_expire_seconds"`
// PresignThresholdMB 前端直传阈值(MB)。0=默认 100;经 /api/config 下发。
PresignThresholdMB int `mapstructure:"presign_threshold_mb" json:"presign_threshold_mb"`
// CodeCaseInsensitive 分享码/自定义口令查询是否不区分大小写(6 位取件码字符表
// 全大写、天然不敏感,不受此开关影响)。指针三态:nil=未设置(默认不区分,
// 口播/手抄场景更友好)。开启时自定义口令创建同步按折叠查重,失败锁定键同步
// 归一。经 /api/config 以下发 codeCaseInsensitive 供前端提示联动。
CodeCaseInsensitive *bool `mapstructure:"code_case_insensitive" json:"code_case_insensitive"`
}
DownloadConfig 下载配置
func (DownloadConfig) CodeFoldEnabled ¶ added in v0.14.7
func (c DownloadConfig) CodeFoldEnabled() bool
CodeFoldEnabled 分享码查询是否折叠大小写(nil 视为开启,兼容存量配置)。
func (DownloadConfig) PresignPolicyOrDefault ¶
func (c DownloadConfig) PresignPolicyOrDefault() string
PresignPolicyOrDefault 解析生效的直传策略: 显式 presign_policy 优先;空串=未设置 ⇒ everyone。 旧开关 presign_anonymous_enabled 已退役(2026-10-26)——存量库该键的语义 (false⇒authenticated)由启动期数据迁移写入 presign_policy,本处不再回退读取。
func (DownloadConfig) PresignTTLOrDefault ¶
func (c DownloadConfig) PresignTTLOrDefault() time.Duration
PresignTTLOrDefault 直传签名时效(钳位 60..3600,0=默认 600)。
func (DownloadConfig) PresignThresholdMBOrDefault ¶
func (c DownloadConfig) PresignThresholdMBOrDefault() int
PresignThresholdMBOrDefault 前端直传阈值(0=默认 100MB)。
type DownloadTokenConfig ¶
type DownloadTokenConfig struct {
Enabled bool `mapstructure:"enabled"` // 默认 true
ValiditySeconds int `mapstructure:"validity_seconds"` // 令牌有效期,默认 1000s(对齐上游)
}
DownloadTokenConfig 取件下载令牌(时间窗 HMAC)。 启用后 /share/download 必须携带取件查询接口下发的 token(防取件码扫描直下)。
type FTPConfig ¶
type FTPConfig struct {
Host string `mapstructure:"host" json:"host"` // host[:port](port 缺省 21)
Username string `mapstructure:"username" json:"username"`
Password string `mapstructure:"password" json:"password"`
// TLS "true" = 显式 FTPS(AUTH TLS)
TLS string `mapstructure:"tls" json:"tls"`
// Root 远端子目录(所有对象挂其下;目录需已存在或可创建)
Root string `mapstructure:"root" json:"root"`
}
FTPConfig FTP/FTPS 存储配置
type FederationConfig ¶
type FederationConfig struct {
// Enabled 总开关(默认 false)。env: PB_FEDERATION_ENABLED
Enabled bool `mapstructure:"enabled" json:"enabled"`
// RegistryURL 联邦注册中心基址,如 http://p2p:12346;支持逗号分隔多主备
// (写路径全推、读路径依次 failover)。env: PB_FEDERATION_REGISTRY_URL
RegistryURL string `mapstructure:"registry_url" json:"registry_url"`
// PublicURL 本站对外可达基址(公告给取件方直连下载用;必须公网/局域网可达,
// 一般与 server.base_url 一致)。env: PB_FEDERATION_PUBLIC_URL
PublicURL string `mapstructure:"public_url" json:"public_url"`
// NodeKeyPath 节点身份密钥(Ed25519 seed hex, 0600),首次启动自动生成。
// 缺失/损坏会重新生成=联邦身份更换。env: PB_FEDERATION_NODE_KEY_PATH
NodeKeyPath string `mapstructure:"node_key_path" json:"node_key_path"`
// AnnounceMinEntropyBits 口令公告熵门槛(位),低于此熵的口令不出站
// (6 位数字取件码默认只在本站有效,防 registry 侧枚举)。0=默认 40。
// json 标签随 SystemConfig.p2p 段在线读写(2026-10-14 对称节点 P1)。
AnnounceMinEntropyBits int `mapstructure:"announce_min_entropy_bits" json:"announce_min_entropy_bits"`
}
FederationConfig P2P 联邦接入(M2;默认关闭。对端服务:github.com/pigeonbox/p2p)。 启用后本站注册进联邦注册中心,口令分享跨站可达(文件仍从本站直出, 注册中心不落盘不见明文)。详见 docs/specs/2026-10-04-p2p-registry-service-design.md。
type HDFSConfig ¶
type HDFSConfig struct {
// Endpoint WebHDFS 根地址,如 http://namenode:9870
Endpoint string `mapstructure:"endpoint" json:"endpoint"`
// User HDFS 代理用户(doAs)
User string `mapstructure:"user" json:"user"`
// Kerberos/Token 认证为扩展点(当前支持无认证/简单代理用户)
Root string `mapstructure:"root" json:"root"`
}
HDFSConfig HDFS 存储配置(WebHDFS REST,NameNode http(s) 端口)
type LocalImportConfig ¶
type LocalImportConfig struct {
Enabled bool `mapstructure:"enabled" json:"enabled"` // env: PB_LOCAL_IMPORT_ENABLED
Roots []string `mapstructure:"roots" json:"roots"` // 允许导入的绝对目录白名单;env: PB_LOCAL_IMPORT_ROOTS(逗号分隔)
}
LocalImportConfig 本地文件导入配置
type LockoutConfig ¶
type LockoutConfig struct {
Enabled bool `mapstructure:"enabled"` // 默认 true
MaxAttempts int `mapstructure:"max_attempts"` // 窗口内最大失败次数,默认 10
WindowSeconds int `mapstructure:"window_seconds"` // 计数窗口,默认 300s
LockSeconds int `mapstructure:"lock_seconds"` // 触发后锁定时长,默认 600s
}
LockoutConfig 登录/取件失败计数锁定(防爆破,非 QPS 语义)。
type LogConfig ¶
type LogConfig struct {
Level string `mapstructure:"level"`
Filename string `mapstructure:"filename"`
MaxSize int `mapstructure:"max_size"`
MaxBackups int `mapstructure:"max_backups"`
MaxAge int `mapstructure:"max_age"`
Compress bool `mapstructure:"compress"`
}
LogConfig 日志配置
type MCPConfig ¶
type MCPConfig struct {
// Enabled 默认 true(认证已强制,无暴露风险)。env: PB_MCP_ENABLED
Enabled bool `mapstructure:"enabled"`
// AllowGuest 访客快速分享(2026-10-12,对标上游 v2.8 MCP quick share 并超出):
// true 时 /api/v1/mcp 不再强制管理员 JWT——游客仅 share_text/share_file
// (与网页匿名寄件同链路、同限流、同审核/白名单),登录用户 += create_request_code/
// preview_share,管理员 = 全量工具。默认 false(维持管理员专属)。
// env: PB_MCP_ALLOW_GUEST
AllowGuest bool `mapstructure:"allow_guest"`
// MaxFileSize MCP 单文件上传/下载上限(字节)。默认 6MB——base64 膨胀 4/3 后
// 约 8MB,低于默认请求体上限(max(10MB, upload.max_file_size));
// 调大超过请求体上限时须同步调大 upload.max_file_size。env: PB_MCP_MAX_FILE_SIZE
MaxFileSize int64 `mapstructure:"max_file_size"`
}
MCPConfig Model Context Protocol server(AI 客户端集成;上游没有的差异化能力)。 端点 POST /api/v1/mcp(Streamable HTTP / JSON-RPC 2.0),默认挂管理员 JWT 认证。
type MetricsConfig ¶
type MetricsConfig struct {
Enabled bool `mapstructure:"enabled"`
Path string `mapstructure:"path"` // 指标暴露路径,默认 /metrics
}
MetricsConfig Prometheus 指标配置
type ModerationConfig ¶
type ModerationConfig struct {
// Enabled 审核钩子总开关(默认 false;env: PB_MODERATION_ENABLED)
Enabled bool `mapstructure:"enabled"`
// BlockedWords 敏感词表(子串匹配、大小写不敏感;env: PB_MODERATION_BLOCKED_WORDS,逗号分隔)
BlockedWords []string `mapstructure:"blocked_words"`
// BlockAction 命中处置策略:reject(默认,直接拒绝)| pending(建分享后置待审,进管理端队列)
BlockAction string `mapstructure:"block_action"`
// ClamAV 文件病毒扫描(clamd INSTREAM;启用后文件侧审核由扫描器接管)
ClamAV ClamAVConfig `mapstructure:"clamav"`
}
ModerationConfig 内容审核配置(治理 2026-10-03;默认关闭,词表为空恒放行)
type NotifyConfig ¶
type NotifyConfig struct {
// WebhookURL 外部推送地址:notify.created 事件以 JSON POST 推送(空 = 禁用)。
// env: PB_WEBHOOK_URL
WebhookURL string `mapstructure:"webhook_url" json:"webhook_url"`
// SMTP 邮件通知(站内信创建后对登记邮箱异步补发;空 host = 禁用)
SMTP SMTPConfig `mapstructure:"smtp" json:"smtp"`
}
NotifyConfig 通知配置(站内信 + 外部 Webhook + SMTP 邮件渠道)
type OIDCConfig ¶
type OIDCConfig struct {
Enabled bool `mapstructure:"enabled" json:"enabled"` // env: PB_OIDC_ENABLED
Issuer string `mapstructure:"issuer" json:"issuer"` // env: PB_OIDC_ISSUER
ClientID string `mapstructure:"client_id" json:"client_id"` // env: PB_OIDC_CLIENT_ID
ClientSecret string `mapstructure:"client_secret" json:"client_secret"` // env: PB_OIDC_CLIENT_SECRET
Scopes string `mapstructure:"scopes" json:"scopes"` // 默认 "openid profile email";env: PB_OIDC_SCOPES
FrontendCallback string `mapstructure:"frontend_callback" json:"frontend_callback"` // 默认 /#/oidc/callback
}
OIDCConfig OIDC 单点登录配置(P2;默认关闭。启用需 issuer/client_id/client_secret, 回调地址 <base_url>/api/v1/user/oidc/callback)
type ObservabilityConfig ¶
type ObservabilityConfig struct {
Metrics MetricsConfig `mapstructure:"metrics"`
}
ObservabilityConfig 可观测性配置(metrics;分布式追踪见路线图,未实现前不暴露配置)
type OneDriveConfig ¶
type OneDriveConfig struct {
ClientID string `mapstructure:"client_id" json:"client_id"`
ClientSecret string `mapstructure:"client_secret" json:"client_secret"`
// RefreshToken 一次性授权获得,长期有效(轮换由服务端自动处理)
RefreshToken string `mapstructure:"refresh_token" json:"refresh_token"`
// Tenant common(个人+组织)或具体租户/消费者域
Tenant string `mapstructure:"tenant" json:"tenant"` // 缺省 common
// DriveID 缺省 me/drive;站点/共享库填对应 drive id
DriveID string `mapstructure:"drive_id" json:"drive_id"`
Root string `mapstructure:"root" json:"root"`
}
OneDriveConfig OneDrive(Microsoft Graph)存储配置。 授权:在 Azure AD 注册应用(Files.ReadWrite.All + offline_access), 走一次授权码流程拿 refresh_token 后配置至此,运行时自动刷新 access token。
type RateLimitSettings ¶
type RateLimitSettings struct {
Enabled *bool `mapstructure:"enabled"`
GlobalQPS int `mapstructure:"global_qps"`
UploadQPS int `mapstructure:"upload_qps"`
DownloadQPS int `mapstructure:"download_qps"`
LoginQPS int `mapstructure:"login_qps"`
Burst int `mapstructure:"burst"`
BlockSeconds int `mapstructure:"block_seconds"`
UseRedis bool `mapstructure:"use_redis"` // true=Redis 分布式计数(多实例共享),Redis 不可用自动回退内存
}
RateLimitSettings 限流配置(代码内默认值见 middleware.DefaultRateLimitConfig)。 Enabled 用指针区分"未配置"(默认开)与"显式 false"。
type RedisConfig ¶
type RedisConfig struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
Password string `mapstructure:"password"`
DB int `mapstructure:"db"`
}
RedisConfig Redis配置
type S3Config ¶
type S3Config struct {
Endpoint string `mapstructure:"endpoint" json:"endpoint"`
Region string `mapstructure:"region" json:"region"`
Bucket string `mapstructure:"bucket" json:"bucket"`
AccessKey string `mapstructure:"access_key" json:"access_key"`
SecretKey string `mapstructure:"secret_key" json:"secret_key"`
UseSSL bool `mapstructure:"use_ssl" json:"use_ssl"`
PathStyle bool `mapstructure:"path_style" json:"path_style"`
}
S3Config S3 兼容对象存储配置(AWS S3 / 阿里云 OSS / 腾讯云 COS 等)
type SFTPConfig ¶
type SFTPConfig struct {
Host string `mapstructure:"host" json:"host"` // host[:port](port 缺省 22)
Username string `mapstructure:"username" json:"username"`
Password string `mapstructure:"password" json:"password"`
// PrivateKey PEM 私钥内容(多行,env 注入友好)
PrivateKey string `mapstructure:"private_key" json:"private_key"`
// HostKey 可选;known_hosts 行或 base64 主机公钥(配置后严格校验,缺省宽松)
HostKey string `mapstructure:"host_key" json:"host_key"`
Root string `mapstructure:"root" json:"root"`
}
SFTPConfig SFTP 存储配置(password 与 private_key 二选一,前者优先)
type SMTPConfig ¶
type SMTPConfig struct {
Host string `mapstructure:"host" json:"host"` // env: PB_SMTP_HOST
Port int `mapstructure:"port" json:"port"` // 465=隐式 TLS;25/587=STARTTLS;env: PB_SMTP_PORT
Username string `mapstructure:"username" json:"username"` // env: PB_SMTP_USERNAME
Password string `mapstructure:"password" json:"password"` // env: PB_SMTP_PASSWORD
From string `mapstructure:"from" json:"from"` // 发件地址,空 = 取 Username;env: PB_SMTP_FROM
}
SMTPConfig SMTP 邮件配置(P2;默认禁用)
type SSRFConfig ¶
type SSRFConfig struct {
// AllowPrivateNetworks 是否允许 s3/webdav 端点指向私网地址。
// 默认 false(阻止内网探测);局域网 MinIO/WebDAV(飞牛 NAS)部署需显式开启。
AllowPrivateNetworks bool `mapstructure:"allow_private_networks"`
}
SSRFConfig 存储端点 SSRF 防护。
type SecurityConfig ¶
type SecurityConfig struct {
CORS CORSConfig `mapstructure:"cors"`
TrustedProxies []string `mapstructure:"trusted_proxies"` // 可信代理 CIDR 列表,如 ["10.0.0.0/8","173.245.48.0/20"]
DownloadToken DownloadTokenConfig `mapstructure:"download_token"`
Lockout LockoutConfig `mapstructure:"lockout"`
SSRF SSRFConfig `mapstructure:"ssrf"`
APIToken APITokenConfig `mapstructure:"api_token"`
OIDC OIDCConfig `mapstructure:"oidc"`
}
SecurityConfig 安全相关配置(CORS / 可信代理 / 下载令牌 / 防爆破锁定 / SSRF / API Key / OIDC)
type ServerConfig ¶
type ServerConfig struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
Mode string `mapstructure:"mode"` // debug, release, test
BaseURL string `mapstructure:"base_url"` // 对外可访问的基础 URL(用于生成分享链接等)
ReadTimeout int `mapstructure:"read_timeout"`
WriteTimeout int `mapstructure:"write_timeout"`
}
ServerConfig 服务器配置
func (*ServerConfig) PublicBaseURL ¶
func (c *ServerConfig) PublicBaseURL(fallback string) string
PublicBaseURL 对外基础地址:base_url 优先,否则 host:port。 fallback 供配置未加载(测试)兜底。修复:直传/分片通道此前在 base_url 未配置时回落到写死的 localhost:12345 常量,反代/容器部署 下 API 返回的分享链接不可用。
type StorageConfig ¶
type StorageConfig struct {
Type string `mapstructure:"type" json:"type"` // local, s3, oss, cos, bos, ks3, obs, webdav
StoragePath string `mapstructure:"storage_path" json:"storage_path"`
// Quota 站点级全局存储配额(字节,0=不限)。统计口径=存活 file_codes 尺寸合计;
// 全通道统一闸口(直传/分片完成/预签名完成/本地导入/多文件)。env: PB_STORAGE_QUOTA
Quota int64 `mapstructure:"quota" json:"quota"`
S3 *S3Config `mapstructure:"s3" json:"s3"`
WebDAV *WebDAVConfig `mapstructure:"webdav" json:"webdav"`
FTP *FTPConfig `mapstructure:"ftp" json:"ftp"`
SFTP *SFTPConfig `mapstructure:"sftp" json:"sftp"`
AzureBlob *AzureBlobConfig `mapstructure:"azureblob" json:"azureblob"`
HDFS *HDFSConfig `mapstructure:"hdfs" json:"hdfs"`
OneDrive *OneDriveConfig `mapstructure:"onedrive" json:"onedrive"`
OSS *CloudStorageConfig `mapstructure:"oss" json:"oss"`
COS *CloudStorageConfig `mapstructure:"cos" json:"cos"`
BOS *CloudStorageConfig `mapstructure:"bos" json:"bos"`
KS3 *CloudStorageConfig `mapstructure:"ks3" json:"ks3"`
OBS *CloudStorageConfig `mapstructure:"obs" json:"obs"`
}
StorageConfig 存储配置 StorageConfig 存储配置。 Type 支持:local / s3(含 MinIO) / oss(阿里云) / cos(腾讯云) / bos(百度云) / ks3(金山云) / obs(华为云) / webdav。云厂商均走 S3 兼容协议(endpoint 可由 region 自动推导),各自配置段字段同 CloudStorageConfig。
type UIConfig ¶
type UIConfig struct {
RobotsText string `mapstructure:"robots_text" json:"robots_text"`
// ShowAdminAddr 缺省(nil/未配置)= 展示页脚管理入口;显式 false 才隐藏。
ShowAdminAddr *bool `mapstructure:"show_admin_addr" json:"show_admin_addr"`
Background string `mapstructure:"background" json:"background"`
AccentColor string `mapstructure:"accent_color" json:"accent_color"`
// ExposeOpenAPI 是否公开 /openapi.json(默认 true,前端 /api-docs 页依赖);
// 生产部署可置 false 收缩端点清单侦察面(env: PB_UI_EXPOSE_OPENAPI)。
ExposeOpenAPI bool `mapstructure:"expose_openapi" json:"expose_openapi"`
// AdminPath 自定义管理后台入口路径段(hash 路由,缺省 admin;env: PB_UI_ADMIN_PATH)。
// 仅入口混淆(SPA 须知路径才能路由,会随公开配置下发)——防误触与批量扫描,
// 不构成安全边界,安全靠登录鉴权。非法字符/超长自动回退 admin。
AdminPath string `mapstructure:"admin_path" json:"admin_path"`
}
UIConfig 前端 UI 相关配置。 Background/AccentColor 构成安全版主题:仅接受 http(s) 图片 URL 与 #RGB/#RRGGBB 颜色值(serve 时校验,非白名单内容整体忽略)——不接受自由 CSS,杜绝旧单体 background 配置的 CSS 注入面(上游 2.6.0 同类修复)。showAdminAddr:公开页脚 是否展示管理后台入口(缺省展示,用 ShowAdminAddrEnabled 取值;/admin 始终可 直达,此键仅控制入口可见性)。
func (*UIConfig) AdminPathOrDefault ¶ added in v0.18.0
AdminPathOrDefault 管理后台入口路径段(缺省 "admin")。 白名单消毒:仅字母/数字/-/_,长度 2~32;其余形态一律回退默认值。
func (*UIConfig) ShowAdminAddrEnabled ¶ added in v0.15.0
ShowAdminAddrEnabled 页脚管理入口是否展示(nil 视为展示)。
type UploadConfig ¶
type UploadConfig struct {
OpenUpload bool `mapstructure:"open_upload" json:"open_upload"`
UploadSize int64 `mapstructure:"upload_size" json:"upload_size"`
EnableChunk bool `mapstructure:"enable_chunk" json:"enable_chunk"`
ChunkSize int64 `mapstructure:"chunk_size" json:"chunk_size"`
RequireLogin bool `mapstructure:"require_login" json:"require_login"`
// TextMaxBytes 文本分享大小上限(字节)。<=0 时用默认 222KB(对齐上游)。
TextMaxBytes int64 `mapstructure:"text_max_bytes" json:"text_max_bytes"`
// AllowedExtensions 扩展名白名单(如 [".jpg",".png",".pdf"])。
// 非空时白名单优先:未命中的扩展名直接拒绝;空 = 黑名单模式。
AllowedExtensions []string `mapstructure:"allowed_extensions" json:"allowed_extensions"`
// BlockedExtensions 扩展名黑名单(如 [".exe",".bat"])。
// 非空时覆盖内置默认黑名单;空 = 使用内置默认(可执行文件类)。
BlockedExtensions []string `mapstructure:"blocked_extensions" json:"blocked_extensions"`
// EnableMagicCheck 是否启用魔数校验(默认 true)。
EnableMagicCheck bool `mapstructure:"enable_magic_check" json:"enable_magic_check"`
// AllowedExpireStyles 允许用户选择的过期样式
// (minute/hour/day/week/month/year/forever/count —— count =「按取件次数」,
// 2026-10-22 补入:此前注释漏了它,合法集合以 pkg/utils.AllExpireStyles 为准)。
// 空 = 全部允许;管理员可裁剪(对标上游白名单裁剪能力)。
AllowedExpireStyles []string `mapstructure:"allowed_expire_styles" json:"allowed_expire_styles"`
// MaxSaveSecondsCap 全局过期时间上限(秒),0 = 不限(对标上游 max_save_seconds)。
MaxSaveSecondsCap int64 `mapstructure:"max_save_seconds_cap" json:"max_save_seconds_cap"`
// MaxFileSize 单个文件大小上限(字节),适用于分片/预签名/匿名登记等
// "整文件"语义的通道;0 = 不限。upload_size 是"单请求体"上限,两者语义不同
// (回归:分片 init 曾误用 upload_size,48MB 文件被 10MB 单请求限制拦截)。
MaxFileSize int64 `mapstructure:"max_file_size" json:"max_file_size"`
// AnonymousDailyCount 匿名上传 per-IP 日配额(次数),0 = 不限。
// 仅约束匿名请求(登录用户走存储配额);Redis 可用时多实例共享计数。
AnonymousDailyCount int64 `mapstructure:"anonymous_daily_count" json:"anonymous_daily_count"`
// AnonymousDailyBytes 匿名上传 per-IP 日配额(字节),0 = 不限。
AnonymousDailyBytes int64 `mapstructure:"anonymous_daily_bytes" json:"anonymous_daily_bytes"`
// LocalImport NAS 本地文件免上传导入(P3:服务器本地白名单目录内的文件
// 直接登记为分享,服务端拷贝入存储;默认关闭)
LocalImport LocalImportConfig `mapstructure:"local_import" json:"local_import"`
}
UploadConfig 上传配置
type UserConfig ¶
type UserConfig struct {
AllowUserRegistration bool `mapstructure:"allow_user_registration"`
UserUploadSize int64 `mapstructure:"user_upload_size"`
UserStorageQuota int64 `mapstructure:"user_storage_quota"`
SessionExpiryHours int `mapstructure:"session_expiry_hours"`
MaxSessionsPerUser int `mapstructure:"max_sessions_per_user"`
JWTSecret string `mapstructure:"jwt_secret"`
}
UserConfig 用户配置
type WebDAVConfig ¶
type WebDAVConfig struct {
Endpoint string `mapstructure:"endpoint" json:"endpoint"`
Username string `mapstructure:"username" json:"username"`
Password string `mapstructure:"password" json:"password"`
}
WebDAVConfig WebDAV 存储配置