【免费下载链接】safebucketOn-prem file sharing made simple, fast and safe.项目地址https://gitcode.com/gh_mirrors/sa/safebucket点击查看免费下载SafeBucket 是一款开源的自托管文件共享平台On-prem file sharing其文件上传/下载通过预签名 URL 直连对象存储天然绕过服务器。但要支撑生产环境的高并发与后台任务单进程部署远远不够——本文完整讲解 SafeBucket 水平扩展的核心Profile 机制让你用一行配置把 API 进程与 Worker 进程分离轻松实现多实例水平扩容。为什么 SafeBucket 需要水平扩展SafeBucket 采用可插拔基础设施架构所有组件存储、数据库、事件、缓存、通知均可替换在默认部署下一个进程同时承担两类职责API 层处理用户登录、文件管理、共享链接等 HTTP 请求Worker 层处理object_deletion对象删除、bucket_events桶事件、trash_cleanup回收站清理、garbage_collector垃圾回收等后台任务流量增大时这两类负载会互相争抢 CPU 与连接池。水平扩展的正确姿势是API 实例无状态、可随意横向扩容Worker 实例独立部署靠分布式锁保证同一时刻只有一个实例执行。这正是 Profile 机制要解决的问题。3种Profile模式速查表三种 Profile 定义在 internal/configuration/profiles.go启动时通过GetProfile()加载ProfileHTTP 服务object_deletionbucket_eventstrash_cleanupgarbage_collectordefault✅ 开启all全实例执行all全实例执行singleton单例锁singleton单例锁api✅ 开启disableddisableddisableddisabledworker❌ 关闭singletonsingletonsingletonsingleton三种 Worker 执行模式定义在 internal/models/profile.godisabled该实例不运行此 Workerall所有实例同时运行此 Worker消费型任务如队列消息消费多实例并行处理更快singleton通过缓存中的分布式锁互斥集群内只有一台实例执行实例宕机后其他实例自动接管 这就是 SafeBucket 水平扩展的关键设计api实例专注扛请求worker实例专注跑后台任务而 singleton 锁保证了扩容 Worker 数量也不会导致任务重复执行。配置一个profile字段即可启用Profile 由配置项profile控制见 templates/config.yaml支持配置文件或环境变量两种方式# templates/config.yaml # Profile determines which components run # Options: default, api, worker profile: api或使用环境变量APP__PROFILEworker官方 deployments/local/full/docker-compose.yml 即采用APP__PROFILE注入。启动入口 main.go 会根据 Profile 决定行为if app.Profile.HTTPServer { httpShutdown core.StartHTTPServer(config, app.Router, webDistFS) } else if app.Profile.Workers.AnyEnabled() { zap.L().Info(Running in worker-only mode) }✅验证方式查看启动日志——Loaded profile api/Loaded profile workerworker 实例会额外输出Running in worker-only mode配置了非法 Profile 值会直接 Fatal 退出并提示available_profiles: [default api worker]三步完成API与Worker分离部署第一步部署 N 个 API 实例。所有实例profile: api通过负载均衡器分发流量。API 实例之间完全对等加实例即扩容。第二步部署 1~2 个 Worker 实例。所有实例profile: worker。放心多起几台——singleton Worker 靠锁互斥多实例的价值在于故障自动接管。第三步在管理后台确认覆盖状态。Worker 启动时会向缓存写入心跳coverage heartbeat管理后台的设置页会实时显示每个组件的覆盖状态covered/not_covered前端展示组件见 web/src/components/admin-settings/components/CoverageValue.tsx三种实例共享同一份配置数据库、缓存、事件总线、token_secret等仅profile字段不同# API 实例 APP__PROFILEapi docker run ghcr.io/safebucket/safebucket:latest # Worker 实例 APP__PROFILEworker docker run ghcr.io/safebucket/safebucket:latest注意水平扩展依赖两个共享组件缓存必须是共享型Redis/Valkey分布式锁与心跳都写在缓存里键前缀app:worker:lock:、app:worker:active:事件总线必须是共享型NATS JetStream、AWS SQS、Azure、GCP 等memory类型仅限本地开发无法跨实例传递消息配置模板 templates/config.yaml 中有注释说明容错自愈分布式锁与心跳机制SafeBucket 的 Worker 容错逻辑实现在 internal/core/bootstrap.go单例锁startSingletonWorker实例通过SetNX抢占app:worker:lock:name锁 TTL 为60 秒每55 秒刷新一次持锁实例崩溃后锁自然过期其他 worker 实例在下一次抢锁时自动接管任务若持锁实例发现刷新失败锁被抢走会主动停止本地 Worker避免双跑覆盖心跳startCoverageHeartbeat每台 API 实例每分钟在缓存的app:identity中注册唯一 UUID见 internal/core/app.go用于统计在线平台/实例数运行中的 Worker 每20 秒上报活跃心跳管理后台据此判断组件是否有人干活也就是说加 Worker 实例 加冗余不会加重复执行减实例 自动漂移无需人工干预。推荐生产拓扑场景API 实例Worker 实例说明小型部署11default单进程亦可默认 Profile 单进程即可中型部署22api ×2 扛请求worker ×2 互为热备大型部署N按 QPS 扩容2~3Worker 数量无需随流量增长任务由消息队列解耦水平扩展常见坑所有实例都用worker没有任何实例提供 HTTP 服务用户无法访问缓存用了本地/内存实现锁和心跳无法跨实例可见singleton 互斥失效事件类型用了memory消息只在单实例内存中流转API 发出的删除/通知事件 Worker 收不到各实例配置不一致token_secret、mfa_encryption_key、数据库连接等必须完全相同否则会话互相失效trash_cleanup只在需要上传确认的存储/事件组合下启动见 internal/core/bootstrap.go 中RequiresUploadConfirmation判断未启用时后台显示not_applicable属正常现象总结关键词说明参考文件Profile 机制default/api/worker三种运行模式internal/configuration/profiles.goWorkerModedisabled/singleton/allinternal/models/profile.go分布式单例锁TTL 60s、55s 刷新的缓存锁internal/core/bootstrap.go覆盖心跳管理后台 Worker 覆盖状态internal/services/admin.go部署参考Docker Compose 全组件编排deployments/local/full/docker-compose.yml只需记住核心公式API 用profile: api随便扩Worker 用profile: worker做冗余共享 Redis 消息队列SafeBucket 即可平滑水平扩展。赞分享【免费下载链接】safebucketOn-prem file sharing made simple, fast and safe.项目地址https://gitcode.com/gh_mirrors/sa/safebucket点击查看免费下载相关推荐BullMQ Elixir Worker 伸缩指南从单机多进程到 Kubernetes 的水平扩展BullMQ Elixir Worker 伸缩指南从单机多进程到 Kubernetes 的水平扩展 这篇指南面向使用 BullMQ Elixir 版本构建后台后端任务调度消息队列Robyn多进程与多工作者配置如何实现水平扩展终极指南Robyn是一个高性能、社区驱动且创新友好的Web框架具有Rust运行时。作为现代Web开发的首选Robyn的多进程与多工作者配置功能让您的应用能够轻松实现后端Web框架Apache CouchDB数据分片机制实现水平扩展的终极指南Apache CouchDB数据分片机制实现水平扩展的终极指南 Apache CouchDB数据分片机制是构建大规模分布式数据库系统的核心技术通过智能的数据数据库文档数据库分布式数据库后端数据同步创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/23 9:30:19 · 阅读 1.2k 如何水平扩展SafeBucket：Profile机制实现API与Worker进程分离完全指南
【免费下载链接】safebucketOn-prem file sharing made simple, fast and safe.项目地址https://gitcode.com/gh_mirrors/sa/safebucket点击查看免费下载SafeBucket 是一款开源的自托管文件共享平台On-prem file sharing其文件上传/下载通过预签名 URL 直连对象存储天然绕过服务器。但要支撑生产环境的高并发与后台任务单进程部署远远不够——本文完整讲解 SafeBucket 水平扩展的核心Profile 机制让你用一行配置把 API 进程与 Worker 进程分离轻松实现多实例水平扩容。为什么 SafeBucket 需要水平扩展SafeBucket 采用可插拔基础设施架构所有组件存储、数据库、事件、缓存、通知均可替换在默认部署下一个进程同时承担两类职责API 层处理用户登录、文件管理、共享链接等 HTTP 请求Worker 层处理object_deletion对象删除、bucket_events桶事件、trash_cleanup回收站清理、garbage_collector垃圾回收等后台任务流量增大时这两类负载会互相争抢 CPU 与连接池。水平扩展的正确姿势是API 实例无状态、可随意横向扩容Worker 实例独立部署靠分布式锁保证同一时刻只有一个实例执行。这正是 Profile 机制要解决的问题。3种Profile模式速查表三种 Profile 定义在 internal/configuration/profiles.go启动时通过GetProfile()加载ProfileHTTP 服务object_deletionbucket_eventstrash_cleanupgarbage_collectordefault✅ 开启all全实例执行all全实例执行singleton单例锁singleton单例锁api✅ 开启disableddisableddisableddisabledworker❌ 关闭singletonsingletonsingletonsingleton三种 Worker 执行模式定义在 internal/models/profile.godisabled该实例不运行此 Workerall所有实例同时运行此 Worker消费型任务如队列消息消费多实例并行处理更快singleton通过缓存中的分布式锁互斥集群内只有一台实例执行实例宕机后其他实例自动接管 这就是 SafeBucket 水平扩展的关键设计api实例专注扛请求worker实例专注跑后台任务而 singleton 锁保证了扩容 Worker 数量也不会导致任务重复执行。配置一个profile字段即可启用Profile 由配置项profile控制见 templates/config.yaml支持配置文件或环境变量两种方式# templates/config.yaml # Profile determines which components run # Options: default, api, worker profile: api或使用环境变量APP__PROFILEworker官方 deployments/local/full/docker-compose.yml 即采用APP__PROFILE注入。启动入口 main.go 会根据 Profile 决定行为if app.Profile.HTTPServer { httpShutdown core.StartHTTPServer(config, app.Router, webDistFS) } else if app.Profile.Workers.AnyEnabled() { zap.L().Info(Running in worker-only mode) }✅验证方式查看启动日志——Loaded profile api/Loaded profile workerworker 实例会额外输出Running in worker-only mode配置了非法 Profile 值会直接 Fatal 退出并提示available_profiles: [default api worker]三步完成API与Worker分离部署第一步部署 N 个 API 实例。所有实例profile: api通过负载均衡器分发流量。API 实例之间完全对等加实例即扩容。第二步部署 1~2 个 Worker 实例。所有实例profile: worker。放心多起几台——singleton Worker 靠锁互斥多实例的价值在于故障自动接管。第三步在管理后台确认覆盖状态。Worker 启动时会向缓存写入心跳coverage heartbeat管理后台的设置页会实时显示每个组件的覆盖状态covered/not_covered前端展示组件见 web/src/components/admin-settings/components/CoverageValue.tsx三种实例共享同一份配置数据库、缓存、事件总线、token_secret等仅profile字段不同# API 实例 APP__PROFILEapi docker run ghcr.io/safebucket/safebucket:latest # Worker 实例 APP__PROFILEworker docker run ghcr.io/safebucket/safebucket:latest注意水平扩展依赖两个共享组件缓存必须是共享型Redis/Valkey分布式锁与心跳都写在缓存里键前缀app:worker:lock:、app:worker:active:事件总线必须是共享型NATS JetStream、AWS SQS、Azure、GCP 等memory类型仅限本地开发无法跨实例传递消息配置模板 templates/config.yaml 中有注释说明容错自愈分布式锁与心跳机制SafeBucket 的 Worker 容错逻辑实现在 internal/core/bootstrap.go单例锁startSingletonWorker实例通过SetNX抢占app:worker:lock:name锁 TTL 为60 秒每55 秒刷新一次持锁实例崩溃后锁自然过期其他 worker 实例在下一次抢锁时自动接管任务若持锁实例发现刷新失败锁被抢走会主动停止本地 Worker避免双跑覆盖心跳startCoverageHeartbeat每台 API 实例每分钟在缓存的app:identity中注册唯一 UUID见 internal/core/app.go用于统计在线平台/实例数运行中的 Worker 每20 秒上报活跃心跳管理后台据此判断组件是否有人干活也就是说加 Worker 实例 加冗余不会加重复执行减实例 自动漂移无需人工干预。推荐生产拓扑场景API 实例Worker 实例说明小型部署11default单进程亦可默认 Profile 单进程即可中型部署22api ×2 扛请求worker ×2 互为热备大型部署N按 QPS 扩容2~3Worker 数量无需随流量增长任务由消息队列解耦水平扩展常见坑所有实例都用worker没有任何实例提供 HTTP 服务用户无法访问缓存用了本地/内存实现锁和心跳无法跨实例可见singleton 互斥失效事件类型用了memory消息只在单实例内存中流转API 发出的删除/通知事件 Worker 收不到各实例配置不一致token_secret、mfa_encryption_key、数据库连接等必须完全相同否则会话互相失效trash_cleanup只在需要上传确认的存储/事件组合下启动见 internal/core/bootstrap.go 中RequiresUploadConfirmation判断未启用时后台显示not_applicable属正常现象总结关键词说明参考文件Profile 机制default/api/worker三种运行模式internal/configuration/profiles.goWorkerModedisabled/singleton/allinternal/models/profile.go分布式单例锁TTL 60s、55s 刷新的缓存锁internal/core/bootstrap.go覆盖心跳管理后台 Worker 覆盖状态internal/services/admin.go部署参考Docker Compose 全组件编排deployments/local/full/docker-compose.yml只需记住核心公式API 用profile: api随便扩Worker 用profile: worker做冗余共享 Redis 消息队列SafeBucket 即可平滑水平扩展。赞分享【免费下载链接】safebucketOn-prem file sharing made simple, fast and safe.项目地址https://gitcode.com/gh_mirrors/sa/safebucket点击查看免费下载相关推荐BullMQ Elixir Worker 伸缩指南从单机多进程到 Kubernetes 的水平扩展BullMQ Elixir Worker 伸缩指南从单机多进程到 Kubernetes 的水平扩展 这篇指南面向使用 BullMQ Elixir 版本构建后台后端任务调度消息队列Robyn多进程与多工作者配置如何实现水平扩展终极指南Robyn是一个高性能、社区驱动且创新友好的Web框架具有Rust运行时。作为现代Web开发的首选Robyn的多进程与多工作者配置功能让您的应用能够轻松实现后端Web框架Apache CouchDB数据分片机制实现水平扩展的终极指南Apache CouchDB数据分片机制实现水平扩展的终极指南 Apache CouchDB数据分片机制是构建大规模分布式数据库系统的核心技术通过智能的数据数据库文档数据库分布式数据库后端数据同步创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考